x402-batching

Gas-free micropayments via Circle Gateway.

This SDK allows you to add gas-free payments to your application using the open x402 protocol. Payments are signed off-chain and settled in batches by Circle Gateway.

Integration at a Glance

1. Simple Integration (Express)

Monetize any API route with 2 lines of code:

// Seller
const gateway = createGatewayMiddleware({ sellerAddress: '0x...' });
app.get('/premium', gateway.require('$0.01'), (req, res) => res.json({ ... }));

Pay for it without gas:

// Buyer
const client = new GatewayClient({ chain: 'polygon', privateKey }); // or any supported chain
await client.pay('https://api.example.com/premium');

2. Using standard @x402/core?

If you already use the standard x402 library, just add Gateway support:

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

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

await server.initialize();

Installation

npm install @circle-fin/x402-batching

This will also install the required peer dependencies (@x402/core, viem). The optional peer dependency @x402/evm is only needed if using CompositeEvmScheme or GatewayEvmScheme.

Quick Start

Seller Setup

Create an Express server that charges for a route:

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

const app = express();
const gateway = createGatewayMiddleware({ sellerAddress: '0xYOUR_ADDRESS' });

app.get('/premium', gateway.require('$0.01'), (req, res) => {
  res.json({ content: 'Premium content' });
});

app.listen(3000);

Buyer Setup

Pay for a protected resource gas-freely:

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

const client = new GatewayClient({
  chain: 'polygon', // or 'arcTestnet' for testing
  privateKey: '0xYOUR_PRIVATE_KEY',
});

// One-time deposit (funds your Gateway balance)
await client.deposit('1.00');

// Pay for the resource — no gas needed
const response = await client.pay('http://localhost:3000/premium');
console.log(response.data);

Testing? Get testnet USDC from the Circle Faucet and use a testnet chain like 'arcTestnet'.

Supported Networks

Circle Gateway connects multiple blockchains for instant cross-chain liquidity.

• Mainnet: Arbitrum, Avalanche, Base, Ethereum, HyperEVM, Optimism, Polygon, Sei, Sonic, Unichain, World Chain
• Testnet: Arbitrum Sepolia, Arc Testnet, Avalanche Fuji, Base Sepolia, Ethereum Sepolia, HyperEVM Testnet, Optimism Sepolia, Polygon Amoy, Sei Atlantic, Sonic Testnet, Unichain Sepolia, World Chain Sepolia

See Supported Networks for full details including chain IDs, USDC addresses, and deposit times.

Learn More

• x402 Protocol
• Circle Gateway Documentation
• Circle Faucet (testnet USDC)