How-to: Add nanopayments to an x402 seller

Add gas-free nanopayments to an existing x402ResourceServer so it accepts them alongside your current onchain payment methods. Your existing payment setup continues to work unchanged: the server includes nanopayment options in its 402 responses in addition to what your facilitator already supports, and buyers choose whichever method they have funded. For the client-side counterpart, see the x402 buyer integration.

Prerequisites

Before you begin, ensure that you’ve:

Set up an x402 seller with @x402/express or @x402/core using x402ResourceServer.
Installed Node.js v18+.

Steps

Install the SDK

npm install @circle-fin/x402-batching @x402/evm

Wire in Gateway settlement alongside your existing facilitator

Add BatchFacilitatorClient alongside your existing HTTPFacilitatorClient. Each facilitator handles a different payment type. Your existing facilitator continues to handle standard onchain payments, and BatchFacilitatorClient handles Gateway payments:

import { x402ResourceServer } from "@x402/express";
import { HTTPFacilitatorClient } from "@x402/core/server";
import { BatchFacilitatorClient } from "@circle-fin/x402-batching/server";

const server = new x402ResourceServer([
  new HTTPFacilitatorClient({ url: "https://facilitator.example.com" }),
  new BatchFacilitatorClient(),
]);

Advertise Gateway options in your 402 responses

Replace ExactEvmScheme with GatewayEvmScheme. GatewayEvmScheme extends ExactEvmScheme, so standard onchain payments continue to work. It also preserves the extra metadata (such as verifyingContract) that Gateway clients need for EIP-712 signing:

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

server.register("eip155:*", new GatewayEvmScheme());
await server.initialize();

After initialization, the server’s 402 responses include Gateway nanopayment options in the accepts array alongside any options your existing facilitator supports.

If you don’t have an existing onchain payment setup or are a new seller, you can add onchain payment support by connecting to an existing x402 facilitator using HTTPFacilitatorClient. See the x402 documentation for a list of available facilitators.

Route through a custom facilitator (optional)

If you run your own x402 facilitator that supports Gateway (see facilitator integration), you can route payments through it instead of connecting to Circle Gateway directly. Use facilitatorUrl with createGatewayMiddleware:

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

const gateway = createGatewayMiddleware({
  sellerAddress: "0xSELLER_ADDRESS",
  facilitatorUrl: "https://your-facilitator.com",
});

Check your balance and withdraw

After buyers pay for your resources, funds accumulate in your Gateway balance. Use GatewayClient to check your earnings using the Get Token Balances API endpoint and withdraw using the Create Transfer Attestation API endpoint:

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

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

const balances = await client.getBalances();
console.log(`Available: ${balances.gateway.formattedAvailable} USDC`);
console.log(`Total: ${balances.gateway.formattedTotal} USDC`);

This example uses one or more private keys for local testing. In production, use a secure key management solution and never expose or share private keys.

Withdraw to your wallet on the same blockchain or to a different one:

await client.withdraw("50");

await client.withdraw("50", { chain: "baseSepolia" });

To trace individual payments back to the requests that triggered them, see Reconcile nanopayments.

Gateway handles settlement automatically. When you call settle() in the middleware, the payment is submitted for batched processing. Your Gateway available balance increases after the batch settles onchain.

Verify the integration

Send an unauthenticated request to a protected route to trigger a 402 response, then inspect the PAYMENT-REQUIRED header:

curl -si http://localhost:3000/protected-resource | grep -i "^payment-required:"

The header value is a base64-encoded JSON payload. After decoding, the accepts array should include an entry where extra.name is "GatewayWalletBatched":

{ "extra": { "name": "GatewayWalletBatched" }, ... }

If both standard and Gateway entries appear in accepts, the server is correctly offering both payment methods.

Circle CLI

Agent marketplace

x402 facilitators

How-to: Add nanopayments to an x402 seller

Prerequisites

Steps

​Prerequisites

​Steps

Prerequisites

Steps