Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.x402.org/llms.txt

Use this file to discover all available pages before exploring further.

The batch-settlement scheme is for high-throughput payments where many requests are authorized individually and redeemed later in batches. The EVM implementation uses stateless unidirectional payment channels: a buyer deposits funds into onchain escrow once, then signs off-chain cumulative vouchers for each request. The seller verifies vouchers quickly and redeems them onchain later in batches. Use batch-settlement for repeated paid API calls, usage-metered endpoints, and other workloads where many small payments would be too expensive or slow to settle one-by-one.

​
How It Works

  1. Deposit: the client opens or tops up a channel by depositing ERC-20 funds into escrow. Deposits use EIP-3009 or Permit2 and are submitted by the facilitator.
  2. Voucher: each paid request includes a signed cumulative voucher for the channel’s total claimable amount.
  3. Verify: the server verifies the voucher and serves the response without waiting for an onchain transfer.
  4. Claim: the server’s channel manager periodically claims the latest vouchers from many channels in one transaction.
  5. Settle: claimed funds are swept to the receiver in a separate settle transaction.
  6. Refund: idle channels can be cooperatively refunded after outstanding vouchers are claimed.
The route price is still a per-request maximum. For dynamic pricing, the server can charge less than that maximum with settlement overrides.

​
Server Setup

Register the scheme with a resource server, protect routes with scheme: "batch-settlement", configure server-side channel storage, and run a channel manager to claim, settle, and refund channels. 
import { HTTPFacilitatorClient } from "@x402/core/server";
import { BatchSettlementEvmScheme, FileChannelStorage } from "@x402/evm/batch-settlement/server";
import { paymentMiddleware, setSettlementOverrides, x402ResourceServer } from "@x402/express";

const network = "eip155:84532" as const;
const facilitatorClient = new HTTPFacilitatorClient({ url: process.env.FACILITATOR_URL! });

const batchScheme = new BatchSettlementEvmScheme(receiverAddress, {
  receiverAuthorizerSigner,
  withdrawDelay: 86400,
  storage: new FileChannelStorage({ directory: "./channels" }),
});

const resourceServer = new x402ResourceServer(facilitatorClient)
  .register(network, batchScheme);

const channelManager = batchScheme.createChannelManager(facilitatorClient, network);
channelManager.start({
  claimIntervalSecs: 60,
  settleIntervalSecs: 300,
  refundIntervalSecs: 3600,
  maxClaimsPerBatch: 100,
});

app.use(paymentMiddleware({
  "GET /weather": {
    accepts: {
      scheme: "batch-settlement",
      price: "$0.01",
      network,
      payTo: receiverAddress,
    },
    description: "Weather data",
    mimeType: "application/json",
  },
}, resourceServer));

app.get("/weather", (req, res) => {
  setSettlementOverrides(res, { amount: "50%" });
  res.json({ report: { weather: "sunny", temperature: 70 } });
});

​
Server Storage

Server storage keeps the latest voucher and channel session state that the channel manager uses to claim, settle, and refund later. In-memory storage is useful for local demos, but production servers should configure durable storage so outstanding vouchers survive restarts. Use file storage for single-process deployments. For serverless or multi-instance deployments, use Redis/Valkey storage so channel updates are shared atomically across processes. See the Next.js batch-settlement Redis example for a full withX402 setup with RedisChannelStorage and cron-based claim/settle routes.

​
Client Setup

Register BatchSettlementEvmScheme for eip155:*. The client SDK handles deposits, voucher signing, channel recovery, and corrective 402 resync. 
import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
import { toClientEvmSigner } from "@x402/evm";
import { BatchSettlementEvmScheme } from "@x402/evm/batch-settlement/client";
import { createPublicClient, http } from "viem";
import { baseSepolia } from "viem/chains";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const publicClient = createPublicClient({ chain: baseSepolia, transport: http() });
const signer = toClientEvmSigner(account, publicClient);

const batchScheme = new BatchSettlementEvmScheme(signer, {
  depositPolicy: { depositMultiplier: 5 },
});

const client = new x402Client();
client.register("eip155:*", batchScheme);

const fetchWithPayment = wrapFetchWithPayment(fetch, client);
const response = await fetchWithPayment("https://api.example.com/weather");

​
Deposit Policy

The deposit policy controls how much the client deposits when a channel needs funding or top-up.
FieldDescription
depositMultiplier / DepositMultiplierDeposits amount x multiplier for the advertised per-request maximum. The default is 5; the minimum is 3.
depositStrategy / DepositStrategyOptional callback for caps, dynamic deposits, or opting out of automatic top-up.
const maxDeposit = 1_000_000n;

const batchScheme = new BatchSettlementEvmScheme(signer, {
  depositPolicy: { depositMultiplier: 5 },
  depositStrategy: ({ depositAmount }) => {
    const amount = BigInt(depositAmount);
    return amount > maxDeposit ? maxDeposit : undefined;
  },
});

​
Voucher Signer Delegation

By default, vouchers are signed by the payer key. For higher-throughput clients, especially smart wallets using EIP-1271, delegate voucher signing to a dedicated EOA. The delegated address is committed into the channel as payerAuthorizer, which lets the facilitator verify vouchers with ECDSA recovery instead of an onchain smart-wallet signature check. 
const voucherSigner = toClientEvmSigner(
  privateKeyToAccount(process.env.EVM_VOUCHER_SIGNER_PRIVATE_KEY as `0x${string}`),
);

const batchScheme = new BatchSettlementEvmScheme(signer, {
  voucherSigner,
});

​
Client Persistence and Refunds

Client channel state is stored in memory by default. Persistent client storage is optional because the SDK can recover channel state through corrective 402 responses and onchain state on the next paid request. Long-lived clients can still persist state to avoid that recovery round trip after restarts. 
import { FileClientChannelStorage } from "@x402/evm/batch-settlement/client";

const batchScheme = new BatchSettlementEvmScheme(signer, {
  storage: new FileClientChannelStorage({ directory: "./channels" }),
});

await batchScheme.refund("https://api.example.com/weather");
await batchScheme.refund("https://api.example.com/weather", { amount: "1000000" });

​
Receiver Authorizer

Every channel commits to a receiverAuthorizer, which signs claim and refund authorizations.
StrategyWhen to use it
Self-managed receiverAuthorizerSignerRecommended for production. Channels survive facilitator changes because any facilitator can relay your signed claims and refunds.
Facilitator-delegated authorizerSimpler to run. If you switch facilitators, claim and refund old channels before opening new ones.

​
Settlement Policy

Choose claim, settle, and refund intervals based on throughput and gas cost:
  • Claim often enough that outstanding vouchers are claimed before a payer’s timed withdrawal can finalize after withdrawDelay.
  • Settle less often when gas savings matter more than cash-flow latency.
  • Refund idle channels to return unclaimed balance to payers.
Set withdrawDelay greater than your claim cadence plus an operational safety margin.

​
Examples

​
Specs

​
See Also