Skip to main content

​
Overview

  • Add nanopayments to an existing x402ResourceServer so it offers gas-free payments alongside your current payment flows.
  • Your existing payment setup continues to work unchanged. The server includes nanopayment options in its 402 responses in addition to the options your facilitator already supports, and buyers choose whichever method they have funded.

​
Prerequisites

Before you begin, ensure you have:
  • An existing x402 seller using @x402/express or @x402/core with x402ResourceServer.
  • Node.js v18+ installed.

​
Steps

​
Step 1. Install the SDK

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

​
Step 2. Add BatchFacilitatorClient to your server

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,
  GatewayEvmScheme,
} from "@circle-fin/x402-batching/server";

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

​
Step 3. Register GatewayEvmScheme

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: 
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.

​
Step 4. 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",
});

​
Step 5. Check your balance and withdraw

After buyers pay for your resources, funds accumulate in your Gateway balance. Use GatewayClient to check your earnings and withdraw: 
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`);
Withdraw to your wallet on the same blockchain or to a different one: 
await client.withdraw("50");

await client.withdraw("50", { chain: "baseSepolia" });
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.

​
Step 6. Verify the integration

The server’s 402 responses should now include Gateway options alongside standard options. Check the accepts array for entries with: 
extra.name === "GatewayWalletBatched";
If both standard and Gateway entries are present, the server is correctly offering both payment methods.

​
See also