​
x402-express

Express middleware integration for the x402 Payment Protocol. This package allows you to easily add paywall functionality to your Express.js applications using the x402 protocol.

​
Installation

npm install x402-express @coinbase/x402

​
Quick Start

import express from "express";
import { paymentMiddleware, Network } from "x402-express";

const app = express();

// Configure the payment middleware
app.use(paymentMiddleware(
  "0xYourAddress",
  {
    "/protected-route": {
      price: "$0.10",
      network: "sei-testnet",
      config: {
        description: "Access to premium content",
      }
    }
  }
));

// Implement your route
app.get("/protected-route", 
  (req, res) => {
    res.json({ message: "This content is behind a paywall" });
  }
);

app.listen(3000);

​
Configuration

The paymentMiddleware function accepts three parameters:
  1. payTo: Your receiving address (0x${string})
  2. routes: Route configurations for protected endpoints
  3. facilitator: (Optional) Configuration for the x402 facilitator service
  4. paywall: (Optional) Configuration for the built-in paywall
See the Middleware Options section below for detailed configuration options.

​
Middleware Options

The middleware supports various configuration options:

​
Route Configuration

type RoutesConfig = Record<string, Price | RouteConfig>;

interface RouteConfig {
  price: Price;           // Price in USD or token amount
  network: Network;       // "sei" or "seiTestnet"
  config?: PaymentMiddlewareConfig;
}

​
Payment Configuration

interface PaymentMiddlewareConfig {
  description?: string;               // Description of the payment
  mimeType?: string;                  // MIME type of the resource
  maxTimeoutSeconds?: number;         // Maximum time for payment (default: 60)
  outputSchema?: Record<string, any>; // JSON schema for the response
  customPaywallHtml?: string;         // Custom HTML for the paywall
  resource?: string;                  // Resource URL (defaults to request URL)
}

​
Facilitator Configuration

type FacilitatorConfig = {
  url: string;                        // URL of the x402 facilitator service
  createAuthHeaders?: CreateHeaders;  // Optional function to create authentication headers
};

​
Paywall Configuration

For more on paywall configuration options, refer to the paywall README. 
type PaywallConfig = {
  cdpClientKey?: string;              // Your CDP Client API Key
  appName?: string;                   // Name displayed in the paywall wallet selection modal
  appLogo?: string;                   // Logo for the paywall wallet selection modal
};

​
Example with Full Configuration

import express from "express";
import { paymentMiddleware } from "x402-express";

const app = express();

app.use(paymentMiddleware(
  "0xYourAddress",
  {
    "/premium-api": {
      price: "$0.05",
      network: "sei-testnet",
      config: {
        description: "Premium API access",
        maxTimeoutSeconds: 120,
      }
    },
    "/data-feed": {
      price: "$0.01",
      network: "sei-testnet",
      config: {
        description: "Real-time data feed",
        mimeType: "application/json",
      }
    }
  },
  {
    url: "https://x402.org/facilitator" // Use test facilitator
  },
  {
    appName: "My Premium API",
    appLogo: "https://example.com/logo.png"
  }
));

app.get("/premium-api", (req, res) => {
  res.json({ 
    data: "This is premium content",
    timestamp: new Date().toISOString()
  });
});

app.get("/data-feed", (req, res) => {
  res.json({ 
    price: Math.random() * 100,
    symbol: "BTC/USD",
    timestamp: Date.now()
  });
});

app.listen(3000, () => {
  console.log("Server running on port 3000");
});