Quickstart: Accept payments with nanopayments

Add Circle Gateway payment middleware to an Express API so that it accepts gasless USDC payments through the x402 protocol. The API returns 402 Payment Required for unpaid requests and serves resources when a valid payment signature is provided.

Prerequisites

Before you begin, ensure that you’ve:

Installed Node.js v22.6+.
Chosen an EVM wallet address to receive USDC payments.

Step 1: Set up your project

1.1. Create the project and install dependencies

# Set up your directory and initialize a Node.js project
mkdir nanopayments-seller
cd nanopayments-seller

npm init -y

# Set up module type and start command
npm pkg set type=module
npm pkg set scripts.start="node server.ts"

# Install runtime dependencies
npm install @circle-fin/x402-batching @x402/core @x402/evm viem express typescript

# Install dev dependencies
npm install --save-dev @types/node @types/express

1.2. Configure TypeScript (optional)

This step is optional. It helps prevent missing types in your IDE or editor.

Create a tsconfig.json file:

npx tsc --init

Then, update the tsconfig.json file:

cat <<'EOF' > tsconfig.json
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "types": ["node"]
  }
}
EOF

Step 2: Create the server

Create a new file server.ts with an Express app and the Gateway middleware:

server.ts

import express from "express";
import { createGatewayMiddleware } from "@circle-fin/x402-batching/server";
import { formatUnits } from "viem";

// Extended Express Request type to include payment information
type PaidRequest = express.Request & {
  payment?: {
    verified: boolean;
    payer: string;
    amount: string;
    network: string;
    transaction?: string;
  };
};

const app = express();

const gateway = createGatewayMiddleware({
  sellerAddress: "0xYOUR_WALLET_ADDRESS",
  facilitatorUrl: "https://gateway-api-testnet.circle.com",
});

Replace 0xYOUR_WALLET_ADDRESS with a valid EVM address where you want to receive payments. This quickstart uses Arc Testnet, so it points to the testnet Gateway API. The middleware still accepts payments from all supported networks.

Step 3: Protect a route

Use gateway.require() to protect any route with a price. When a request arrives without a valid payment, the middleware returns 402 Payment Required with the payment details. When a valid payment signature is attached, the middleware settles it with Gateway using the Settle x402 Payment API endpoint and calls next():

server.ts

app.get("/premium-data", gateway.require("$0.01"), (req: PaidRequest, res) => {
  const { payer, amount, network } = req.payment!;
  const formattedAmount = formatUnits(BigInt(amount), 6);
  console.log(`Paid ${formattedAmount} USDC by ${payer} on ${network}`);

  res.json({
    secret: "The treasure is hidden under the doormat.",
    paid_by: payer,
  });
});

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

Step 4: Test the server

4.1. Start the server

npm start

4.2. Send an unpaid request

In a separate terminal, use curl to verify the server returns a 402 response:

curl -i http://localhost:3000/premium-data

You should see a 402 Payment Required response with a PAYMENT-REQUIRED header. The header contains the payment options.

4.3. Pay with a buyer client

Use the buyer quickstart client to make a gasless payment to your server:

import { GatewayClient } from "@circle-fin/x402-batching/client";

const client = new GatewayClient({
  chain: "arcTestnet",
  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
});

const { data, status } = await client.pay("http://localhost:3000/premium-data");
console.log(`Status: ${status}`);
console.log("Data:", data);

If the payment succeeds, you’ll see the JSON response from your protected endpoint. If it’s rejected, the error reference covers each error code, including insufficient_funds, expired_authorization, invalid_payload, and invalid_signature. Each entry explains the cause and how to recover. To attribute settled payments back to the requests that triggered them, see Reconcile nanopayments.

Handle payments without the middleware (advanced)

If you are not using Express, or need custom logic like dynamic pricing, use the BatchFacilitatorClient directly. The settle() method calls the Settle x402 Payment API endpoint:

server.ts

import { BatchFacilitatorClient } from "@circle-fin/x402-batching/server";

const facilitator = new BatchFacilitatorClient({
  url: "https://gateway-api-testnet.circle.com",
});

const requirements = {
  scheme: "exact",
  network: "eip155:5042002", // CAIP-2 identifier for Arc Testnet (chain ID 5042002)
  asset: "0x...", // USDC contract address on Arc Testnet — see supported chains reference
  amount: "10000", // 0.01 USDC
  maxTimeoutSeconds: 604900,
  payTo: "0xYOUR_ADDRESS", // seller address that receives the payment
  extra: {
    name: "GatewayWalletBatched",
    version: "1",
    verifyingContract: "0x...", // Gateway Wallet contract on Arc Testnet — see supported chains reference
  },
};

async function handleRequest(paymentSignature?: string) {
  if (!paymentSignature) {
    const paymentRequired = {
      x402Version: 2,
      resource: {
        url: "/premium-data",
        description: "Paid resource",
        mimeType: "application/json",
      },
      accepts: [requirements],
    };

    return {
      status: 402,
      headers: {
        "PAYMENT-REQUIRED": Buffer.from(
          JSON.stringify(paymentRequired),
        ).toString("base64"),
      },
      body: {},
    };
  }

  const payload = JSON.parse(
    Buffer.from(paymentSignature, "base64").toString("utf8"),
  );

  const settlement = await facilitator.settle(payload, requirements);

  if (!settlement.success) {
    return {
      status: 402,
      body: { error: "Settlement failed" },
    };
  }

  return {
    status: 200,
    body: { data: "Your paid content" },
  };
}

Gateway’s settle() endpoint is optimized for low latency and guarantees settlement. Use settle() directly rather than calling verify() followed by settle() in production flows.

Limit accepted networks (optional)

By default, the middleware accepts payments from any Gateway-supported blockchain, discovered through the Get Supported x402 Payment Kinds API endpoint. This maximizes your reach since any buyer with a Gateway balance on one of those accepted networks can pay you. If you need to restrict payments to specific networks:

const gateway = createGatewayMiddleware({
  sellerAddress: "0x...",
  networks: ["eip155:5042002"], // Only accept Arc Testnet
});

Payment signatures must have at least 7 days plus a small buffer of validity. The validBefore timestamp in the buyer’s EIP-3009 authorization must be at least 7 days in the future, or Gateway will reject it.

Circle CLI

Agent marketplace

x402 facilitators

Quickstart: Accept payments with nanopayments

Prerequisites

Step 1: Set up your project

1.1. Create the project and install dependencies

1.2. Configure TypeScript (optional)

Step 2: Create the server

Step 3: Protect a route

Step 4: Test the server

4.1. Start the server

4.2. Send an unpaid request

4.3. Pay with a buyer client

Handle payments without the middleware (advanced)

Limit accepted networks (optional)

​Prerequisites

​Step 1: Set up your project

​1.1. Create the project and install dependencies

​1.2. Configure TypeScript (optional)

​Step 2: Create the server

​Step 3: Protect a route

​Step 4: Test the server

​4.1. Start the server

​4.2. Send an unpaid request

​4.3. Pay with a buyer client

​Handle payments without the middleware (advanced)

​Limit accepted networks (optional)

Prerequisites

Step 1: Set up your project

1.1. Create the project and install dependencies

1.2. Configure TypeScript (optional)

Step 2: Create the server

Step 3: Protect a route

Step 4: Test the server

4.1. Start the server

4.2. Send an unpaid request

4.3. Pay with a buyer client

Handle payments without the middleware (advanced)

Limit accepted networks (optional)