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: 'arcTestnet', privateKey });
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: 'arcTestnet',
  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);

Need Testnet USDC? Get some from the Circle Faucet (select "Arc Testnet").

Supported Networks

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

• Gas-free Payments: Currently supported on Arc Testnet.
• Deposits & Withdrawals: Supported on many EVM chains.

Learn More

• x402 Protocol
• Circle Gateway Documentation
• Circle Faucet