Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.circle.com/llms.txt

Use this file to discover all available pages before exploring further.

In this quickstart, you will add Circle Gateway payment middleware to an Express API so that it accepts gasless USDC payments via the x402 protocol. By the end, your API will return 402 Payment Required for unpaid requests and serve resources when a valid payment signature is provided.

​
Prerequisites

Before you begin, ensure you have:
  • Installed Node.js v22+
  • An EVM wallet address where you want 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="tsx server.ts"

# Install runtime dependencies
npm install @circle-fin/x402-batching @x402/core @x402/evm viem express tsx 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.

​
Advanced: Use BatchFacilitatorClient directly

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.