Express.js Server

Start accepting x402 payments in your Express server in minutes. Build a monetized API with just a few lines of code.

Quick Start

Use the PayAI Express starter template to bootstrap a ready-to-run x402-enabled server. No payment infrastructure needed - just add your wallet address and start earning.

Step 1: Create Project

Use your favorite package manager to create a new server from the starter template:

npm (npx)

npx @payai/x402-express-starter my-first-server

pnpm

pnpm dlx @payai/x402-express-starter my-first-server

bun

bunx @payai/x402-express-starter my-first-server

Step 2: Configure Environment

Open your project's .env file and set:

FACILITATOR_URL - Facilitator base URL (defaults to: https://facilitator.payai.network)
NETWORK - Network to use (e.g., base-sepolia, base, solana)
ADDRESS - Your wallet public address to receive payments

FACILITATOR_URL=https://facilitator.payai.network
NETWORK=base-sepolia # or base, solana, polygon
ADDRESS=0x... # your wallet public address

# Required if using Base mainnet facilitator
CDP_API_KEY_ID="Coinbase Developer Platform Key"
CDP_API_KEY_SECRET="Coinbase Developer Platform Key Secret"

Step 3: Server Code

This is the generated index.ts. It loads your environment, applies the x402 payment middleware, and defines protected routes:

import { config } from "dotenv";
import express from "express";
import { paymentMiddleware, Resource } from "x402-express";
config();

const facilitatorUrl = process.env.FACILITATOR_URL as Resource;
const payTo = process.env.ADDRESS as `0x${string}`;

if (!facilitatorUrl || !payTo) {
  console.error("Missing required environment variables");
  process.exit(1);
}

const app = express();

app.use(
  paymentMiddleware(
    payTo,
    {
      "GET /weather": {
        // USDC amount in dollars
        price: "$0.001",
        network: "base-sepolia",
      },
      "/premium/*": {
        // Define atomic amounts in any EIP-3009 token
        price: {
          amount: "100000",
          asset: {
            address: "0xabc",
            decimals: 18,
            eip712: {
              name: "WETH",
              version: "1",
            },
          },
        },
        network: "base-sepolia",
      },
    },
    {
      url: facilitatorUrl,
    },
  ),
);

app.get("/weather", (req, res) => {
  res.send({
    report: {
      weather: "sunny",
      temperature: 70,
    },
  });
});

app.get("/premium/content", (req, res) => {
  res.send({
    content: "This is premium content",
  });
});

app.listen(4021, () => {
  console.log(`Server listening at http://localhost:${4021}`);
});

Step 4: Run Your Server

npm run dev

Your server is now accepting x402 payments! Test it by making a request to http://localhost:4021/weather

How It Works

1. Client Requests Resource

When a client calls a protected endpoint, the middleware intercepts the request.

2. Server Returns 402

The server responds with HTTP 402 and payment instructions in the headers.

3. Client Pays

The client creates and signs a blockchain transaction to your wallet address.

4. Payment Verified

The facilitator verifies the payment on-chain and the middleware allows the request through.

5. Resource Delivered

Your endpoint handler runs and returns the requested resource to the client.

Pricing Options

Dollar-Based Pricing

Simplest option - specify price in dollars and let the system handle conversion:

"GET /weather": {
  price: "$0.001",
  network: "base-sepolia"
}

Token-Based Pricing

Define atomic amounts in any EIP-3009 token for more control:

"/premium/*": {
  price: {
    amount: "100000",
    asset: {
      address: "0xabc...",
      decimals: 18,
      eip712: {
        name: "WETH",
        version: "1"
      }
    }
  },
  network: "base-sepolia"
}

Deploy to Production

To deploy your x402 server to production:

Change NETWORK from base-sepolia to base (or your chosen mainnet)
Add Coinbase Developer Platform API keys for Base mainnet
Deploy to your hosting provider (Vercel, Railway, AWS, etc.)
Register your service on Nova402 marketplace

Next Steps

Learn how to consume x402 services from your client applications.

Client Integration View on GitHub