Skip to main content
Nanopayments integrates with existing x402 setups at every layer of the stack. It is additive: it introduces gas-free payments as a new option alongside standard onchain x402 payments, without replacing them. Sellers automatically accept both methods, and buyers choose whichever they have funded.

​
Install the SDK

npm install @circle-fin/x402-batching

​
Integration paths

Choose the guides that match your role in the x402 ecosystem.

Buyer (client-side)

Add nanopayments to your x402 client so it can pay gas-free when servers support it

Seller (server-side)

Add gas-free nanopayments to your existing x402 server alongside your current payment flows

Facilitator

Route Gateway payments alongside onchain payments in your facilitator service

​
Seller (server-side)

Add BatchFacilitatorClient and GatewayEvmScheme to your existing server. Your 402 responses then include both standard and Gateway payment options: 
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(),
]);
server.register("eip155:*", new GatewayEvmScheme());
await server.initialize();
See Full seller integration guide.

​
Buyer (client-side)

Use CompositeEvmScheme to handle both Gateway and standard payments automatically. The client picks the right scheme based on what the server offers: 
import { ExactEvmScheme } from "@x402/evm/exact/client";
import {
  CompositeEvmScheme,
  BatchEvmScheme,
} from "@circle-fin/x402-batching/client";

const composite = new CompositeEvmScheme(
  new BatchEvmScheme(signer),
  new ExactEvmScheme(signer),
);

client.register("eip155:*", composite);
See Full buyer integration guide.

​
Facilitator

Use isBatchPayment() to route Gateway payments to BatchFacilitatorClient while your existing handler covers standard payments: 
import {
  BatchFacilitatorClient,
  isBatchPayment,
} from "@circle-fin/x402-batching/server";

const gatewayClient = new BatchFacilitatorClient();

async function handleSettle(payload, requirements) {
  if (isBatchPayment(requirements)) {
    return gatewayClient.settle(payload, requirements);
  }
  return existingOnChainHandler.settle(payload, requirements);
}
See Full facilitator integration guide.

​
How routing works

When both payment methods are available, routing is automatic at every layer:
LayerWhat happens
ServerThe 402 response lists both standard and Gateway options in the accepts array.
ClientCompositeEvmScheme checks each option’s extra.name. If "GatewayWalletBatched" is present, it uses BatchEvmScheme. Otherwise it uses ExactEvmScheme.
FacilitatorisBatchPayment() checks the same extra.name field and routes verify/settle calls to either Gateway or the existing onchain handler.
No manual routing code is needed in sellers or buyers. The SDK handles it based on the payment requirements.