tp tate@programs batch review
tate@programs ~/notes/x402-batch-settlement escrow / vouchers / claims

x402 batch settlement / may 2026

When x402 moves to vouchers, launch risk moves to session state.

Batch settlement lets agents authorize many small paid interactions with signed vouchers and redeem them later in bulk. That makes high-frequency agent commerce cheaper, but it also adds new proof requirements: escrow funding, channel storage, voucher monotonicity, claim timing, refund windows, and reconciliation after partial failure.

read checklist x402 announcement official docs policy builder surface check
scheme
batch-settlement
hot path
signed voucher
risk
state drift

why now

The public x402 surface is no longer only one request, one settlement.

The official x402 team announced batch settlement on May 11, 2026. The model separates request-time authorization from later onchain redemption: the buyer commits funds, signs cumulative vouchers per request, the seller verifies those vouchers cheaply, and settlement happens later in bulk. That is a strong fit for agent loops, inference, data, and compute, but it shifts review from a single 402 response to the lifecycle around channels.

readiness checklist

Use this before putting batch-settled routes in front of agents.

1. Make the scheme explicit in discovery

The paid route should say when it uses batch-settlement instead of immediate exact settlement. Agents need to know whether they are authorizing a one-off transfer, opening a channel, topping up escrow, or signing a voucher against an existing channel.

2. Publish the per-request ceiling

Batch settlement can support dynamic usage, but each route still needs a maximum charge per interaction. Put the ceiling in the challenge and docs, then explain when the server may settle for less than that ceiling.

3. Cap deposits separately from route price

A per-call max does not bound the session if the client auto-deposits too much. Show the deposit multiplier, maximum deposit, top-up trigger, and what happens when the cap is reached.

4. Treat voucher signing as a hot credential

If voucher signing is delegated to a separate key, document the delegation boundary. The buyer should be able to rotate it, revoke it, and prove which signer authorized each cumulative amount.

5. Prove vouchers are monotonic

Every voucher should advance the cumulative amount for a channel. Reject stale vouchers, duplicate vouchers, lower cumulative amounts, route mismatches, expired sessions, and vouchers for the wrong receiver.

6. Use durable, shared channel storage

In-memory channel state is fine for a toy demo. Production needs storage that survives restarts. Serverless or multi-instance deployments need shared storage so two workers cannot accept conflicting channel state.

7. Schedule claims before withdrawal risk

The claim interval, settle interval, refund interval, and withdrawal delay should be visible. Operators need enough margin to claim outstanding vouchers before a payer can exit a channel.

8. Separate claim, settle, and refund evidence

A launch report should show which vouchers were accepted, when they were claimed, when claimed funds were swept to the receiver, and how idle balances are refunded.

9. Reconcile paid-but-not-served and served-but-not-claimed states

Batch settlement changes failure handling. Track whether the server served the resource after voucher verification, whether the voucher was later claimed, and whether the user can recover from a channel resync.

10. Keep browser CORS and resource binding intact

Batch-settled routes still need readable 402 responses, exposed payment headers, canonical resource.url, and accept-level resource echo. The settlement scheme changes, but the launch surface still has to be inspectable.

proof fields

What a batch-settlement review should capture.

channel

Escrow map

Network, token, receiver, channel id, deposit policy, maximum deposit, top-up policy, and withdrawal delay.

voucher

Signed state

Signer, cumulative amount, route binding, expiry, nonce or sequence, replay handling, and stale-voucher rejection.

storage

Persistence

Where the latest voucher and channel session state live, whether storage is shared, and how recovery works after restart.

claim

Operator cadence

Claim interval, settle interval, refund interval, max claims per batch, and alerting when claim lag grows.

refund

Exit path

Idle-channel refund rules, cooperative close behavior, outstanding-voucher handling, and user-facing recovery copy.

ledger

Reconciliation

Per-request served state, voucher accepted state, claim state, onchain sweep state, and unresolved discrepancy queue.

commands

Start with normal surface checks, then inspect batch state.

A public no-payment check still verifies whether the route advertises the scheme, price ceiling, network, payee, resource URL, and browser readability. Batch-specific evidence then comes from docs, code, logs, or operator screenshots rather than paid calls. 

npx --yes x402-surface-check@latest \
  --endpoint --method GET https://api.example.com/metered \
  --origin https://app.example.com

curl -si https://api.example.com/metered \
  -H 'Origin: https://app.example.com'

# Then review evidence for:
# - deposit policy and maximum deposit
# - voucher signer delegation
# - durable channel storage
# - claim/settle/refund intervals
# - reconciliation states

paid review angle

The offer is a lifecycle review, not a payment attempt.

Send the public route, docs, and non-secret evidence for channel storage, voucher signing, and claim jobs. The review returns a spend map, state-machine gaps, and a patch order without sending payment headers or touching private keys.

scope a review