How-to: Integrate nanopayments into your existing facilitator

Route Gateway payments through your existing x402 facilitator alongside standard onchain payments. Connected sellers gain gas-free batched settlement without changing seller-side code.

This guide is for infrastructure providers and payment processors running x402 facilitators.

Prerequisites

Before you begin, ensure that you’ve:

Built an x402 facilitator service using @x402/core.
Installed Node.js v18+.
Familiarized yourself with the x402 protocol and how facilitators verify and settle payments.

Steps

Install the SDK

Install @circle-fin/x402-batching alongside its required peer dependencies:

npm install @circle-fin/x402-batching @x402/core viem

Add a Gateway client for verification, settlement, and discovery

The BatchFacilitatorClient handles all communication with Circle Gateway, including verification using the Verify x402 Payment API endpoint, settlement using the Settle x402 Payment API endpoint, and supported-network discovery using the Get Supported x402 Payment Kinds API endpoint. See the SDK reference for the full BatchFacilitatorClient API.

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

const gatewayClient = new BatchFacilitatorClient();

Route payments by type

Your facilitator acts as a router. Use isBatchPayment() to detect Gateway payments and delegate them to the BatchFacilitatorClient. Route all other payments to your existing onchain logic.Gateway payments are identified by the extra metadata field: extra.name === "GatewayWalletBatched".

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

async function handleVerify(
  payload: PaymentPayload,
  requirements: PaymentRequirements,
) {
  if (isBatchPayment(requirements)) {
    return gatewayClient.verify(payload, requirements);
  }
  return existingOnChainHandler.verify(payload, requirements);
}

async function handleSettle(
  payload: PaymentPayload,
  requirements: PaymentRequirements,
) {
  if (isBatchPayment(requirements)) {
    return gatewayClient.settle(payload, requirements);
  }
  return existingOnChainHandler.settle(payload, requirements);
}

async function handleSupported() {
  const gateway = await gatewayClient.getSupported();
  const existing = await existingOnChainHandler.getSupported();

  return {
    kinds: [...existing.kinds, ...gateway.kinds],
    extensions: [...existing.extensions, ...gateway.extensions],
    signers: { ...existing.signers, ...gateway.signers },
  };
}

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.

For background on how Gateway batches payments, see How batched settlement works.

Wire up HTTP endpoints

Expose your routing logic through standard x402 facilitator endpoints:

app.post("/v1/x402/verify", async (req, res) => {
  const { paymentPayload, paymentRequirements } = req.body;
  const response = await handleVerify(paymentPayload, paymentRequirements);
  res.json(response);
});

app.post("/v1/x402/settle", async (req, res) => {
  const { paymentPayload, paymentRequirements } = req.body;
  const response = await handleSettle(paymentPayload, paymentRequirements);
  res.json(response);
});

app.get("/v1/x402/supported", async (_req, res) => {
  const response = await handleSupported();
  res.json(response);
});

Connect sellers to your facilitator

Once your facilitator supports Gateway, sellers connect to it and automatically gain access to both standard and gas-free payment options. Sellers new to the Gateway middleware can start from the seller quickstart.Sellers connect using one of two setups.

x402ResourceServer
Gateway middleware

Sellers using x402ResourceServer connect to your facilitator with HTTPFacilitatorClient:

import { x402ResourceServer } from "@x402/core/server";
import { HTTPFacilitatorClient } from "@x402/core/server";

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

await server.initialize();

Sellers using the Gateway middleware can route verification and settlement through your facilitator by setting facilitatorUrl:

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

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

Alternative: gas-free-only facilitator

If you are building a new facilitator that only needs to support gas-free payments (without standard onchain settlement), use BatchFacilitatorClient directly with x402ResourceServer:

npm install @x402/core @x402/express @x402/evm

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

const server = new x402ResourceServer([new BatchFacilitatorClient()]);

await server.initialize();

Preserve Gateway signing metadata

When using x402ResourceServer with BatchFacilitatorClient, register GatewayEvmScheme to ensure payment requirements include the metadata that Gateway clients need for EIP-712 signing. GatewayEvmScheme extends the standard ExactEvmScheme to:

Preserve extra metadata (verifyingContract, name, version) in payment requirements
Set maxTimeoutSeconds to 604900 (7 days plus a small buffer) for batched settlement
Register USDC money parsers for all Gateway-supported networks

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

const circleClient = new BatchFacilitatorClient();
const server = new x402ResourceServer([circleClient]);
server.register("eip155:*", new GatewayEvmScheme());
await server.initialize();

The base ExactEvmScheme discards the extra field from supported kinds when building payment requirements. Gateway clients require extra.verifyingContract to construct valid EIP-712 signatures. GatewayEvmScheme preserves this data.

Circle CLI

Agent marketplace

x402 facilitators

How-to: Integrate nanopayments into your existing facilitator

Prerequisites

Steps

Alternative: gas-free-only facilitator

Preserve Gateway signing metadata

​Prerequisites

​Steps

​Alternative: gas-free-only facilitator

​Preserve Gateway signing metadata

Prerequisites

Steps

Alternative: gas-free-only facilitator

Preserve Gateway signing metadata