EVM Batch Settlement on Base

​

How it works

1. Deposit. The customer signs a USDC authorization (EIP-3009, or Permit2 for other ERC-20s) that funds a channel identified by its immutable config: payer, receiver, receiver authorizer, token, withdraw delay and a salt. PayAI submits the deposit; the customer pays no gas.
2. Vouchers. Each request carries a voucher with a cumulative ceiling: everything charged so far plus this request’s maximum. Your server verifies the signature locally in a few milliseconds and charges the actual amount, from zero up to the ceiling. Nothing touches the chain.
3. Claim. On your schedule, your server sends the latest voucher per channel to PayAI, which submits one claimWithSignature transaction covering up to 25 channels.
4. Sweep. A settle transaction transfers everything claimed for your receiver and token to your wallet in one transfer.
5. Refund or withdraw. Your server can cooperatively refund a customer’s unused balance at any time; the customer can always start a timed withdrawal (one to 24 hours under PayAI’s policy) as a unilateral fallback.

import { setSettlementOverrides } from "@x402/express";

app.get("/api/generate", (req, res) => {
  const actualUsage = computeCost(); // atomic units, "50%", or "$0.001"
  setSettlementOverrides(res, { amount: String(actualUsage) });
  res.json({ result: "..." });
});

​

1. Install the upstream SDK

npm install @x402/core@^2.27.0 @x402/evm@^2.27.0 @x402/express@^2.27.0 viem

​

2. Choose a receiver authorizer

​

Option A: your own key (default, no account needed)

import { x402ResourceServer, HTTPFacilitatorClient } from "@x402/core/server";
import { BatchSettlementEvmScheme } from "@x402/evm/batch-settlement/server";
import { RedisChannelStorage } from "@x402/evm/batch-settlement/server/redis-storage";

const facilitator = new HTTPFacilitatorClient({
  url: "https://facilitator.payai.network",
  timeoutMs: 110_000, // PayAI answers within its 100 s budget; keep the client above it
});

const scheme = new BatchSettlementEvmScheme(receiverAddress, {
  receiverAuthorizerSigner, // an EOA you control; no ETH or tokens needed
  withdrawDelay: 3600,      // seconds; PayAI accepts 3600–86400
  storage: new RedisChannelStorage({ client: redisClient }),
});

const server = new x402ResourceServer(facilitator).register("eip155:8453", scheme);

​

Option B: PayAI holds the authorizer (API key required)

const facilitator = new HTTPFacilitatorClient({
  url: "https://facilitator.payai.network",
  timeoutMs: 110_000,
  createAuthHeaders: async () => {
    const headers = { Authorization: `Bearer ${await generatePayAIJwt(apiKeyId, apiKeySecret)}` };
    return { verify: headers, settle: headers, supported: headers };
  },
});

const scheme = new BatchSettlementEvmScheme(receiverAddress, {
  // no receiverAuthorizerSigner: the SDK takes extra.receiverAuthorizer from /supported
  withdrawDelay: 3600,
  storage: new RedisChannelStorage({ client: redisClient }),
});

• The first authenticated deposit /verify for a channel reserves it for your account; the deposit /settle from the same account binds it. First writer wins.
• Claims, refunds and voucher or refund verifies on that channel must come from your account. Requests from any other account, or without a JWT, are refused. Sweeps stay public because they only pay the channel’s receiver.
• Delegated legs bill like any authenticated leg: the free allowance first, then credits, at the same per-leg prices.

• Lock-in. PayAI’s authorizer address is hashed into every channel id. To move those channels to another facilitator, claim outstanding vouchers and refund the remaining balances first.
• Fallback. If PayAI is unavailable, the channel’s receiver can still call claim and refund on the contract directly, but only if the receiver is an EOA or a contract able to make those calls. Use Option A if your payTo is a routing contract.
• Rotation. If PayAI rotates its advertised address, channels on the old address keep working, but one claim batch cannot mix channels from two authorizers; drain old channels before your channel manager mixes them. Restart your server after a rotation so it reads the new address.

​

3. Run the channel manager

const manager = scheme.createChannelManager(facilitator, "eip155:8453");
manager.start({
  claimIntervalSecs: 60,
  settleIntervalSecs: 300,
  refundIntervalSecs: 3600,
  selectRefundChannels: channels =>
    channels.filter(c => Date.now() - c.lastRequestTimestamp >= 3_600_000),
});

​

4. Policy and limits

​

5. What PayAI bills

​

Recovery

​

Test before taking customer traffic