How-to: Add nanopayments to an x402 buyer

Add gas-free nanopayments to an existing x402 client so it can pay without gas when a server supports it, and fall back to standard onchain payments when it does not. Gas-free payments require a one-time USDC deposit into a Gateway Wallet contract. After that, every subsequent payment is an offchain signature with zero gas cost. For the server-side counterpart, see the x402 seller integration.

Prerequisites

Before you begin, ensure that you’ve:

Set up an x402 client using @x402/core.
Installed Node.js v18+.
Generated an EVM wallet private key for signing.
Funded the wallet with testnet USDC from the Circle Faucet so you can deposit into Gateway.

Steps

Install the SDK

npm install @circle-fin/x402-batching

If you plan to use CompositeEvmScheme (recommended for supporting both payment methods), also install:

npm install @x402/evm

Enable Gateway payments in your client

Pick the approach that matches your setup:

Composite (recommended): support both Gateway and onchain payments in one client, with automatic routing based on what each server offers.
Existing client: add Gateway to a client you’ve already configured, with minimal changes and standard onchain payments preserved.

If you only need gas-free payments and don’t need standard onchain support, use GatewayClient directly. See the buyer quickstart for a full walkthrough.

Composite
Existing client

Use CompositeEvmScheme to route automatically based on the server’s payment requirements. When the server offers a Gateway option, the client uses BatchEvmScheme for a gas-free payment. When only standard onchain options are available, it falls back to ExactEvmScheme:

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);

No per-request routing code is needed. CompositeEvmScheme checks each payment option’s extra.name field and delegates to the correct scheme automatically.

If you already have scheme registrations and want to add Gateway support with minimal changes while keeping standard onchain payments available:

import { ExactEvmScheme } from "@x402/evm/exact/client";
import { registerBatchScheme } from "@circle-fin/x402-batching/client";

registerBatchScheme(client, {
  signer: account,
  fallbackScheme: new ExactEvmScheme(account),
});

Fund your Gateway balance

Before making gas-free payments, deposit USDC from your wallet into the Gateway Wallet contract. This is a one-time onchain transaction:

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

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

const balances = await gatewayClient.getBalances();
if (balances.gateway.available < 1_000_000n) {
  await gatewayClient.deposit("1");
}

getBalances() calls the Get Token Balances API endpoint. After the deposit confirms, your Gateway balance is available for gas-free payments.Deposit time depends on the blockchain. See required block confirmations for exact times per blockchain.

Unified Balance in Arc App Kits offers fast deposits, which credit your Gateway balance in seconds.

Verify the target server supports Gateway

Before attempting a gas-free payment, check whether the target server supports Gateway. The supports() method requests the target URL, checks for a 402 response, and inspects the PAYMENT-REQUIRED header for a compatible Gateway batching option:

const support = await gatewayClient.supports(
  "https://api.example.com/resource",
);

if (!support.supported) {
  console.log("Server does not support Gateway -- falling back to onchain");
}

If you are using CompositeEvmScheme, this check is optional since the scheme handles fallback automatically.

Withdraw funds back to your wallet (optional)

Withdraw USDC from Gateway back to your wallet at any time. Withdrawals are instant for both same-blockchain and crosschain destinations. The withdraw() method calls the Create Transfer Attestation API endpoint:

await gatewayClient.withdraw("5");

await gatewayClient.withdraw("5", { chain: "baseSepolia" });

Look up individual transfers (optional)

After paying for resources, you can look up individual transfers using the Get x402 Transfer by ID API endpoint, or search across transfer history using the Search x402 Transfers API endpoint:

const { transfers, pagination } = await gatewayClient.searchTransfers({
  from: gatewayClient.address,
  status: "received",
  pageSize: 20,
});

const transferUUID = transfers[0]?.id;

if (transferUUID) {
  try {
    const transfer = await gatewayClient.getTransferById(transferUUID);

    console.log({
      id: transfer.id,
      status: transfer.status,
      amount: transfer.amount,
    });
  } catch (error) {
    console.error("Could not load transfer", error);
  }
}

if (pagination?.pageAfter) {
  const nextPage = await gatewayClient.searchTransfers({
    from: gatewayClient.address,
    status: "received",
    pageSize: 20,
    pageAfter: pagination.pageAfter,
  });
}

searchTransfers supports filtering by sender, recipient, nonce, network, status, token, and date range. When you filter by status, also provide from, to, or nonce to narrow the search. This example uses the buyer’s address as from. When network is omitted, the client defaults to the client’s configured blockchain. See the SDK reference for the full list of parameters.

Circle CLI

Agent marketplace

x402 facilitators

How-to: Add nanopayments to an x402 buyer

Prerequisites

Steps

​Prerequisites

​Steps

Prerequisites

Steps