Skip to main content

​
Overview

  • Add nanopayments to an existing x402 client so it can pay gas-free when a server supports it, while still falling back to standard onchain payments when it does not.
  • Gas-free payments require a one-time USDC deposit into a Gateway Wallet contract. After depositing, all subsequent payments are offchain signatures with zero gas cost.
  • Your existing onchain payment flows continue to work unchanged. The client automatically selects the right payment method based on what the server offers.

​
Prerequisites

Before you begin, ensure you have:
  • An existing x402 client using @x402/core.
  • Node.js v18+ installed.
  • An EVM wallet private key for signing.
  • Testnet USDC from the Circle Faucet (for Gateway deposits).

​
Steps

​
Step 1. 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

​
Step 2. Choose your integration approach

Pick the option that best fits your setup. 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.

​
Option B: Add Gateway support to an existing client

If you already have scheme registrations and want to add Gateway support with minimal changes: 
import { registerBatchScheme } from "@circle-fin/x402-batching/client";

registerBatchScheme(client, { signer: account });

​
Option C: Gateway only

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.

​
Step 3. Deposit USDC into Gateway

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 to any server that supports nanopayments. See the discussion at Fast deposits about increasing deposit speeds.

​
Step 4. Check support before paying

Before attempting a gas-free payment, check whether the target server supports Gateway. The supports() method queries the Get Supported x402 Payment Kinds API endpoint: 
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.

​
Step 5. Understand deposit finality

When you deposit USDC into Gateway, the API waits for block confirmations before your balance becomes available. Wait times vary by blockchain:
BlockchainDeposit time
Arc Testnet~0.5 sec
Avalanche Fuji~8 sec
HyperEVM Testnet, Sei Atlantic~5 sec
Polygon PoS Amoy, Sonic Testnet~8 sec
Arbitrum Sepolia, Base Sepolia, Ethereum Sepolia, Optimism Sepolia, Unichain Sepolia, World Chain Sepolia~13-19 min
To avoid long deposit wait times, see the discussion at Fast deposits about third party services that offer fast deposits. Alternatively, use Bridge Kit to bridge your USDC to a fast-finality blockchain before depositing into Gateway. Your Gateway balance works across all supported blockchains regardless of where you deposited.
import { BridgeKit } from "@circle-fin/bridge-kit";

const bridge = new BridgeKit();

const transfer = await bridge.transfer({
  sourceChain: "base-sepolia",
  destinationChain: "arc-testnet",
  amount: "10",
  token: "USDC",
});
await bridge.waitForCompletion(transfer.id);

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

​
Step 6. Withdraw funds (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" });

​
Step 7. Monitor 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({
  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({
    status: "received",
    pageSize: 20,
    pageAfter: pagination.pageAfter,
  });
}
searchTransfers supports filtering by sender, recipient, network, status, token, and date range. When network is omitted, the client defaults to the client’s configured blockchain. See the SDK reference for the full list of parameters.

​
See also