Scheme: batch-settlement on EVM
Summary
The batch-settlement scheme on EVM is a capital-backed network binding using stateless unidirectional payment channels for high-throughput, low-cost payments. Clients deposit funds into onchain channels once and sign off-chain cumulative vouchers per request. Servers verify vouchers with fast signature checks and claim them onchain periodically in batches, reducing both latency and gas costs drastically. A single claim transaction can cover many channels at once and only updates onchain accounting; claimed funds are later transferred to the receiver via a separate settle operation that sweeps many claims into one token transfer.
The scheme supports dynamic pricing: the client authorizes a maximum per-request, and the server charges the actual cost within that ceiling.
The scheme also supports two voucher-management modes, which differ in whether the resource server (self-managed, the default) or the facilitator (facilitator-managed) keeps the latest voucher and runs the claim/settle schedule. See Voucher Management.
Channel Lifecycle
Channel creation and deposits
A channel is created implicitly on the first deposit. The client deposits funds from the payer address into an onchain escrow via one of two asset transfer methods: eip3009 for tokens that support receiveWithAuthorization (e.g. USDC) or permit2 as a universal fallback for any ERC-20. Deposits are sponsored by the facilitator (gasless for the client).
Channel identity is derived from an immutable config struct:
struct ChannelConfig {
address payer; // Client wallet (EOA or smart wallet)
address payerAuthorizer; // EOA for voucher signing, or address(0) for EIP-1271 via payer
address receiver; // Server's payment destination (EOA or routing contract)
address receiverAuthorizer; // Authorizes claims and refunds via EIP-712 signatures
address token; // ERC-20 payment token
uint40 withdrawDelay; // Seconds before timed withdrawal completes (15 min – 30 days)
bytes32 salt; // Differentiates channels with identical parameters
}
with channelId = EIP712Hash(ChannelConfig) under the x402 Batch Settlement domain. The hash binds the immutable config to the EVM chainId and deployed x402BatchSettlement address, so the same config produces different IDs across chains or deployments.
Requests and vouchers
The channel tracks two values: balance (total deposited minus withdrawals and refunds) and totalClaimed (cumulative amount claimed by the server). Each voucher the client signs carries a cumulative ceiling (maxClaimableAmount). The server can claim up to that ceiling. Because vouchers are monotonically increasing, old vouchers with lower ceilings are naturally superseded.
The server tracks a running total of actual charges per channel (chargedCumulativeAmount). For each subsequent request, the client sets the voucher’s maxClaimableAmount to chargedCumulativeAmount + amount, where amount is the per-request maximum.
Claim and settle
The server claims the latest voucher per channel onchain at its discretion. claimWithSignature(claims, signature) allows aggregating claims from multiple channels in one call. Claiming updates totalClaimed per channel; no token transfer occurs.
settle sweeps all claimed-but-unsettled funds to the receiver in one transfer.
Refund and withdrawal
Cooperative refund: the receiver side can return up to balance - totalClaimed to the payer via two paths:
refund(config, amount): direct call byreceiverorreceiverAuthorizer, no signature required.refundWithSignature(config, amount, nonce, sig): relay-friendly; anyone submits an EIP-712Refundsignature fromreceiverAuthorizer.
Both paths share the same internal execution: refundNonce is incremented first (before the amount cap is applied and before any token transfer), so a no-op refund (amount > 0 but no unclaimed escrow available) still advances the nonce without emitting Refunded or moving tokens. A direct refund call therefore invalidates any pre-signed refundWithSignature digest for the previous nonce. If a timed withdrawal is pending, a cooperative refund reduces its recorded amount proportionally; it is only cancelled entirely when the refund amount meets or exceeds the pending withdrawal amount.
Timed withdrawal (escape hatch): the payer or payerAuthorizer calls initiateWithdraw(config, amount) to start a grace period. The requested amount must not exceed balance - totalClaimed at initiation time; the call reverts otherwise. During the grace period the server can claim outstanding vouchers. After the withdrawal delay elapses, finalizeWithdraw (also callable by payerAuthorizer) completes the withdrawal, capping the transferred amount to whatever unclaimed escrow remains at that point.
Authorizer roles
Payer authorizer (payerAuthorizer): if set to a non-zero address (an EOA), vouchers are verified via ECDSA recovery against that committed key ( fast, no RPC required). If set to zero, vouchers are verified against the payer address, supporting EIP-1271 smart wallets at the cost of an RPC call.
Receiver authorizer (receiverAuthorizer): authorizes claim and refund operations via EIP-712 signatures. The server chooses this address: a server-owned EOA or smart contract (eg for key rotation), or a facilitator-provided address when the server delegates authorization. Must not be zero. Anyone can relay a claimWithSignature or refundWithSignature transaction with a valid authorization signature from the receiverAuthorizer.
Channel lifecycle events
The contract emits ChannelCreated(channelId, config) on the first deposit into a channel (when balance transitions from zero with totalClaimed == 0). It emits ChannelClosed(channelId, config) when unclaimed escrow returns to zero with totalClaimed == 0 - triggered by either a full cooperative refund or a timed withdrawal that drains all escrow. Indexers must handle ChannelCreated firing more than once on the same channelId if the channel is re-funded after being fully drained.
Channel reuse and parameter changes
Channels are long-lived. After a refund, the client can top up and reuse the same channel. However, the channel config is immutable. If any parameter needs to change, a new channel is required. If delegating receiverAuthorizer to a facilitator, the server should claim all outstanding vouchers and refund remaining balances on old channels before switching to another facilitator. In facilitator-managed mode with a server-owned refund key, the refundAuthorizer is part of salt, so rotating it also requires a new channel.
Voucher Management
The scheme has two voucher-management modes. They differ in who stores the latest client-signed voucher and the per-channel charge total (chargedCumulativeAmount, the “watermark”), and in who decides when to claim and settle onchain.
| Mode | extra.voucherManager |
Voucher /settle |
Watermark and claim/settle schedule | Authoritative store |
|---|---|---|---|---|
| Self-managed | omitted or "server" |
No | Resource server | Server channel store |
| Facilitator-managed | "facilitator" |
Yes - durable offchain write | Facilitator | Facilitator |
In self-managed mode the resource server owns the per-channel state and the facilitator only verifies payloads and submits onchain transactions. In facilitator-managed mode the resource server is a pass-through: it calls /verify then /settle for every payload (including voucher) and uses the settle result as the payment response. The facilitator verifies every payload, persists vouchers, chargedCumulativeAmount, and a chargeCount (see Payment Response Contract) on /settle, and claims and settles on a schedule (see Claim & Settlement Strategy). Per-channel serialization is described under POST /verify.
Selecting the mode. A facilitator advertises the voucher-management modes it supports as voucherManager: ["server", "facilitator"] on /supported; omitting the field means ["server"]. A facilitator offering "facilitator" also advertises receiverAuthorizer and withdrawDelay, and MAY advertise delegatedRefund: true (see GET /supported). The server picks one mode and sets the single value voucherManager on the 402, copying receiverAuthorizer and withdrawDelay as well; it MUST NOT override withdrawDelay, and MUST NOT choose a mode the facilitator did not advertise. The client echoes the value and reads it only to decide whether to pack the refund authorizer into salt (see 402 Response).
402 Response (PaymentRequirements)
The 402 response contains pricing terms and the server’s channel parameters. The client maps payTo → ChannelConfig.receiver, extra.receiverAuthorizer → ChannelConfig.receiverAuthorizer, asset → ChannelConfig.token, and extra.withdrawDelay → ChannelConfig.withdrawDelay, then fills in its own payer, payerAuthorizer, and salt to construct the full config.
In facilitator-managed mode the server copies receiverAuthorizer and withdrawDelay from /supported, sets voucherManager: "facilitator", and sets refundAuthorizer only when it signs refunds with its own key (see below).
{
"scheme": "batch-settlement",
"network": "eip155:8453",
"amount": "100000",
"asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"payTo": "0xServerReceiverAddress",
"maxTimeoutSeconds": 3600,
"extra": {
"receiverAuthorizer": "0xReceiverAuthorizerAddress",
"withdrawDelay": 900,
"name": "USDC",
"version": "2",
"minDeposit": "1000000",
// Facilitator-managed only:
// "voucherManager": "facilitator",
// Only when the server signs refunds with its own EOA:
// "refundAuthorizer": "0xRefundAuthorizerAddress"
},
}
| Field | Type | Required | Description |
|---|---|---|---|
extra.receiverAuthorizer |
string |
yes | Address that will authorize claims/refunds |
extra.withdrawDelay |
number |
yes | Withdrawal delay in seconds (15 min – 30 days) |
extra.assetTransferMethod |
string |
optional | "eip3009" (default) or "permit2" |
extra.name |
string |
yes | EIP-712 domain name of the token contract |
extra.version |
string |
yes | EIP-712 domain version of the token contract |
extra.minDeposit |
string |
optional | Atomic deposit target. When present, MUST be a positive integer >= amount. |
extra.voucherManager |
string |
optional | "server" (default) or "facilitator" manages vouchers (see Voucher Management) |
extra.refundAuthorizer |
string |
conditional | Server-owned EOA that consents to cooperative refunds. Facilitator-managed mode only, and only when the server signs refunds with its own key; omitted otherwise (see below) |
extra.channelState |
object |
optional | Corrective-only server channel snapshot for cumulative amount resynchronization |
extra.voucherState |
object |
optional | Corrective-only signed voucher proof for cumulative amount resynchronization |
Clients SHOULD use a conforming extra.minDeposit as the deposit target, and SHOULD enforce a local maximum deposit so a 402 cannot lock unbounded escrow. Servers SHOULD NOT reject a deposit solely because deposit.amount is below this field. A server that applies a local minimum-deposit policy MAY reject and MUST return invalid_batch_settlement_evm_deposit_below_min_deposit. The facilitator MUST NOT enforce minDeposit.
extra.channelState and extra.voucherState appear only on a corrective 402, which the voucher manager returns when the client’s cumulative amount is out of sync (see Recovery After State Loss).
Refund authorizer (facilitator-managed mode only). A cooperative refund bypasses the withdrawal delay, and /settle is otherwise unauthenticated. In self-managed mode the refund consent is the server’s own refundAuthorizerSignature, or, when the server delegates receiverAuthorizer, the facilitator’s authentication of the /settle caller (see Security and Trust); no extra.refundAuthorizer is used and the salt is never packed. In facilitator-managed mode the facilitator is always the receiverAuthorizer and signs the onchain refund itself, so it needs separate proof that the server consents to each refund. The 402 selects how that proof is given:
- A server-owned EOA (stable per receiver until rotated). The server sets
extra.refundAuthorizerto that address and signs each refund with that key (see Cooperative refund flow). - The facilitator’s
/settlecaller authentication. The server omitsextra.refundAuthorizer. This requires the facilitator to advertisedelegatedRefund: trueon/supported. No signature is needed; the facilitator authenticates the caller as the service that created the channel.
When voucherManager is "facilitator" and extra.refundAuthorizer is present, the client MUST set ChannelConfig.salt = bytes12(entropy) || bytes20(refundAuthorizer), which binds the address into channelId so a /settle caller cannot substitute a different refund authorizer. When extra.refundAuthorizer is omitted, the salt is the raw client salt. Self-managed channels never pack, so their channelId does not depend on extra.refundAuthorizer. entropy is a 12-byte channel index: if the caller’s salt has zero high 12 bytes (left-padded 0, 1, 2, …), use the low 96 bits; otherwise keep the first 12 bytes of a 32-byte salt. Changing this address, like any other config parameter, requires a new channel.
Client: Payment Construction
The client constructs a payment payload whose type depends on channel state:
deposit: No channel exists or balance is exhausted - client signs a token authorization and vouchervoucher: Channel has sufficient balance - client signs a new cumulative voucherrefund: Client requests a cooperative refund - client signs a zero-charge voucher and optionally includes a refund amount
In facilitator-managed mode the payloads are identical, except that accepted echoes the managed 402 (including voucherManager and, when present, refundAuthorizer) and channelConfig.salt uses the packed layout when refundAuthorizer is present.
Deposit Payload
The deposit.authorization field contains the token transfer authorization - exactly one of erc3009Authorization or permit2Authorization must be present.
{
"x402Version": 2,
"accepted": {
"scheme": "batch-settlement",
"network": "eip155:8453",
"amount": "1000",
"asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"payTo": "0xServerReceiverAddress",
"maxTimeoutSeconds": 3600,
"extra": {
"receiverAuthorizer": "0xReceiverAuthorizerAddress",
"withdrawDelay": 900,
"name": "USDC",
"version": "2",
// Facilitator-managed only:
// "voucherManager": "facilitator",
// Only when the server signs refunds with its own EOA:
// "refundAuthorizer": "0xRefundAuthorizerAddress"
},
},
"payload": {
"type": "deposit",
"channelConfig": {
"payer": "0xClientAddress",
"payerAuthorizer": "0xClientPayerAuthorizerEOA",
"receiver": "0xServerReceiverAddress",
"receiverAuthorizer": "0xReceiverAuthorizerAddress",
"token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"withdrawDelay": 900,
"salt": "0x0000000000000000000000000000000000000000000000000000000000000000",
// With voucherManager "facilitator" and extra.refundAuthorizer (packed layout): bytes12(entropy) || bytes20(refundAuthorizer)
// "salt": "0x000000000000000000000000aaaabbbbccccddddeeeeffffaaaabbbbccccdddd"
},
"voucher": {
"channelId": "0xabc123...channelId",
"maxClaimableAmount": "1000",
"signature": "0x...EIP-712 voucher signature",
},
"deposit": {
"amount": "100000",
"authorization": {
"erc3009Authorization": {
"validAfter": "0",
"validBefore": "1770000000",
"salt": "0x...authorization salt",
"signature": "0x...ERC-3009 signature",
},
},
},
},
}
Voucher Payload
{
"x402Version": 2,
"accepted": { "...": "..." },
"payload": {
"type": "voucher",
"channelConfig": {
"payer": "0xClientAddress",
"payerAuthorizer": "0xClientPayerAuthorizerEOA",
"receiver": "0xServerReceiverAddress",
"receiverAuthorizer": "0xReceiverAuthorizerAddress",
"token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"withdrawDelay": 900,
"salt": "0x0000000000000000000000000000000000000000000000000000000000000000"
},
"voucher": {
"channelId": "0xabc123...channelId",
"maxClaimableAmount": "5000",
"signature": "0x...EIP-712 voucher signature"
}
}
}
Refund Payload
The optional amount requests a partial refund; omit it for a full refund. The voucher is zero-charge: voucher.maxClaimableAmount MUST equal the channel’s current chargedCumulativeAmount. Before settlement, the server completes the payload with the refund nonce, claim data, and any receiver-authorizer signatures it is responsible for.
{
"x402Version": 2,
"accepted": { "...": "..." },
"payload": {
"type": "refund",
"channelConfig": {
"payer": "0xClientAddress",
"payerAuthorizer": "0xClientPayerAuthorizerEOA",
"receiver": "0xServerReceiverAddress",
"receiverAuthorizer": "0xReceiverAuthorizerAddress",
"token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
"withdrawDelay": 900,
"salt": "0x0000000000000000000000000000000000000000000000000000000000000000"
},
"voucher": {
"channelId": "0xabc123...channelId",
"maxClaimableAmount": "3200",
"signature": "0x...EIP-712 zero-charge voucher signature"
},
"amount": "1500"
}
}
Server: State & Forwarding
This section describes self-managed mode, where the server is the sole owner of per-channel state. In facilitator-managed mode the server is a pass-through (see Voucher Management); only the Payment Response Contract and Cooperative refund flow below apply to it.
A facilitator-managed server MAY persist a copy of the latest voucher after a successful /settle, solely to enable out-of-band claim() / refund(). The replica MUST NOT drive cumulative checks, per-channel locks, or corrective 402s.
Per-Channel State
The server must maintain per-channel state, keyed by channel ID:
| State Field | Type | Description |
|---|---|---|
channelConfig |
ChannelConfig |
Full channel configuration object |
chargedCumulativeAmount |
uint128 |
Actual accumulated cost for this channel |
signedMaxClaimable |
uint128 |
maxClaimableAmount from the latest client-signed voucher |
signature |
bytes |
Client’s voucher signature for the latest signedMaxClaimable |
balance |
uint128 |
Current channel balance (mirrored from onchain) |
totalClaimed |
uint128 |
Total claimed onchain (mirrored from onchain) |
withdrawRequestedAt |
uint64 |
Unix timestamp when timed withdrawal was initiated, or 0 if none (mirrored from onchain) |
refundNonce |
uint256 |
Next nonce required for refundWithSignature (mirrored from onchain) |
onchainSyncedAt |
uint64 |
Local timestamp when mirrored onchain fields were refreshed |
lastRequestTimestamp |
uint64 |
Timestamp of the last paid request |
Request Processing
The server must serialize request processing per channel and must not update voucher state until the resource handler has succeeded.
- Verify:
- For
voucheranddepositpayloads, check thatpayload.voucher.maxClaimableAmount == chargedCumulativeAmount + paymentRequirements.amount. If this fails, reject withinvalid_batch_settlement_evm_cumulative_amount_mismatchand return a corrective 402. - For refund payloads, check that
payload.voucher.maxClaimableAmount == chargedCumulativeAmountand skip the resource handler after facilitator verification. - Always call facilitator
/verifyfordepositandrefundpayloads, as well asvoucherpayloads with EIP-1271 vouchers. - A plain EOA-authorized
vouchermay be verified locally when the server’s mirrored onchain state is fresh.
- For
- Execute: Run the resource handler
- On success - commit state:
chargedCumulativeAmount += actualPrice(whereactualPrice <= PaymentRequirements.amount)- Mirror
balance,totalClaimed,withdrawRequestedAt, andrefundNoncefrom the facilitator response
- On failure: State unchanged, client can retry the same voucher.
Payment Response Contract
Both modes produce this shape. In facilitator-managed mode the facilitator /settle response is the payment response.
Successful paid responses distinguish onchain transfers from offchain charges:
- Voucher-only response:
transactionis"", top-levelamountis"",extra.chargedAmountis the request charge, andextra.channelStatecarries the channel snapshot. - Deposit response:
transactionis the deposit transaction hash, top-levelamountis the deposited amount,extra.chargedAmountis the request charge, andextra.channelStatecarries the channel snapshot. - Refund response:
transactionis the refund transaction hash, top-levelamountis the refunded amount,extra.channelStatecarries the post-refund channel snapshot andextra.chargedAmountis omitted.
{
"success": true,
"transaction": "",
"network": "eip155:8453",
"payer": "0xClientAddress",
"amount": "",
"extra": {
"chargedAmount": "700",
// Facilitator-managed only:
// "chargeCount": 4,
"channelState": {
"channelId": "0xabc123...channelId",
"balance": "100000",
"totalClaimed": "3200",
"withdrawRequestedAt": 0,
"refundNonce": "1",
"chargedCumulativeAmount": "3900",
},
},
}
Charge count. Facilitator-managed responses (all three types) also include extra.chargeCount. It is the number of paid offchain commits since the last confirmed onchain claim - an unattested delta, not a lifetime total. The facilitator increments it on each type: "voucher" commit and on the voucher persisted with a type: "deposit"; zero-charge refunds and cancel settles do not increment it. Each claim attests the delta onchain (see Claim & Settlement Strategy).
Cooperative refund flow
When the server receives a type: "refund" payload:
- Verify (zero-charge): enforce
payload.voucher.maxClaimableAmount == chargedCumulativeAmount(no increment frompaymentRequirements.amount). If local state is stale, emit a corrective 402 so the client can recover and retry. - Bypass the protected resource. Refund payloads are payment operations, not paid requests; the application route is not invoked.
- Complete the settlement payload: resolve omitted
amountto a full refund, validate any partialamount, addrefundNonce, buildclaims, and add receiver-authorizer signatures when the server owns that key. - Submit onchain:
claimWithSignature(claims, claimSig)(no-op whenmaxClaimableAmount == totalClaimed) followed byrefundWithSignature(config, amount, nonce, refundSig). The contract incrementsrefundNoncebefore applying the amount cap; even if no tokens move (zero available escrow), the nonce advances. - Update channel state:
- Full refund (refunded amount equals the remainder): delete the channel record.
- Partial refund: keep the channel record, mirror the returned
balance,totalClaimed,withdrawRequestedAt, andrefundNonce. If a timed withdrawal was pending, its recorded amount is reduced proportionally (or cancelled if the refund covers it entirely).
- Return the settle response in the standard
PAYMENT-RESPONSEheader.
After the server completes the refund payload, the facilitator receives:
{
"type": "refund",
"channelConfig": { "...": "..." },
"voucher": {
"channelId": "0xabc123...channelId",
"maxClaimableAmount": "3200",
"signature": "0x...EIP-712 zero-charge voucher signature"
},
"amount": "1500",
"refundNonce": "1",
"claims": [
{
"voucher": {
"channel": { "...": "..." },
"maxClaimableAmount": "3200"
},
"signature": "0x...EIP-712 zero-charge voucher signature",
"totalClaimed": "3200"
}
],
"refundAuthorizerSignature": "0x...refund authorization",
"claimAuthorizerSignature": "0x...claim authorization"
}
refundAuthorizerSignature and claimAuthorizerSignature are included when the server owns the receiver-authorizer key. If the channel delegates receiver authorization to the facilitator, the server omits both and the facilitator signs the onchain Refund and ClaimBatch digests itself, after authenticating the /settle caller as the service that created the channel.
In facilitator-managed mode the facilitator always signs, so it needs proof that the server consents to the refund. That proof depends on whether the 402 carries extra.refundAuthorizer:
extra.refundAuthorizerpresent (server-owned EOA): the address unpacked fromchannelConfig.saltMUST equalextra.refundAuthorizer. The server attachesrefundAuthorizerSignature, signed by that address over the EIP-712Refunddigest (Refund(bytes32 channelId,uint256 nonce,uint128 amount)). The facilitator recovers the signer and only then submitsrefundWithSignature.extra.refundAuthorizeromitted: no signature is attached. The facilitator authenticates the/settlecaller as the service that created the channel and rejects all others. This is available only when the facilitator advertisesdelegatedRefund: true.
Facilitator Interface
Uses the standard x402 facilitator interface (/verify, /settle, /supported).
POST /verify
Verifies a deposit, voucher, or refund payment payload. Returns the onchain channel snapshot:
{
"isValid": true,
"payer": "0xPayerAddress",
"extra": {
"channelId": "0xabc123...",
"balance": "1000000",
"totalClaimed": "500000",
"withdrawRequestedAt": 0,
"refundNonce": "0",
// Facilitator-managed only:
// "chargedCumulativeAmount": "3900",
// "pendingId": "0x...server-authored reservation"
},
}
Facilitator-managed /verify also returns the offchain watermark (chargedCumulativeAmount) and extra.pendingId, a server-authored reservation (not a PAYMENT-RESPONSE field):
- The facilitator MUST take a short-lived exclusive lock per
channelId, bound to the verified voucher so a replayed or guessedpendingIdcannot admit a different voucher. A second in-flight request returnsinvalid_batch_settlement_evm_channel_busy(retryable). The facilitator SHOULD run stateless checks (channelConfigagainst thechannelIdand requirements, EOA voucher signatures) before acquiring the lock. - The lock is not a payment commit: the watermark does not advance until
/settle. - A client-supplied
pendingIdorcancelMUST be rejected. - Managed
depositandrefund/settleMUST hold the channel lock from before the onchain submission until the result is persisted, so a voucher cannot commit against escrow the transaction is about to move. A reservation that lapsed before/settleis re-acquired; another live holder fails the settle withinvalid_batch_settlement_evm_pending_id_mismatch.
On invalid_batch_settlement_evm_cumulative_amount_mismatch, managed /verify returns extra.channelState and extra.voucherState (same objects as the corrective 402). The resource server copies those onto accepts[].extra.
POST /settle
payload.type |
When Used | Onchain Effect |
|---|---|---|
"deposit" |
First request or top-up | Deposit via the canonical ERC-3009 or Permit2 collector |
"voucher" |
Facilitator-managed paid request | None - persist voucher; chargedCumulativeAmount += actual; increment chargeCount |
"claim" |
Server batches voucher claims | Validate vouchers, update accounting (no transfer) |
"settle" |
Server transfers earned funds | Transfer unsettled amount to receiver |
"refund" |
Cooperative refund | Return specified amount to payer, increment refund nonce |
type: "voucher" is valid only in facilitator-managed mode (extra.voucherManager === "facilitator"); self-managed /settle rejects it with invalid_batch_settlement_evm_payload_type. Its response is the voucher-only payment response (see Payment Response Contract).
In facilitator-managed mode, deposit and voucher settles commit a charge as follows:
/verifysees the per-request maximum,payload.accepted.amount. The settle-time chargeactualispaymentRequirements.amounton the settle call and MAY be lower. Managed/verifyMUST reject the payload whenpayload.accepted.amountdiffers frompaymentRequirements.amount./settleMUST rejectactualabovepayload.accepted.amount, and MUST commit only whenchargedCumulativeAmountequalsvoucher.maxClaimableAmount - payload.accepted.amount(sochargedCumulativeAmount + actual <= voucher.maxClaimableAmount).- A repeated settle after that commit is not idempotent: it MUST leave
chargedCumulativeAmountunchanged and returninvalid_batch_settlement_evm_cumulative_amount_mismatch. Callers MUST NOT auto-retryPOST /settle. - Deposit
/settlealso persists the deposit’s voucher, initializes the watermark, and incrementschargeCount.
Facilitator-managed /settle MAY add two server-authored fields on the existing deposit / voucher / refund payload:
| Field | Type | When |
|---|---|---|
pendingId |
string |
Echo of extra.pendingId from /verify. A live reservation with a different voucher fails the settle; an omitted pendingId fully re-verifies. |
cancel |
boolean |
true on handler cancel (paymentRequirements.amount is "0"). Facilitator releases the reservation and MUST NOT charge, deposit, or refund. |
{
"payload": {
"type": "voucher",
"channelConfig": { "...": "..." },
"voucher": { "...": "..." },
"pendingId": "0x...server-authored reservation",
"cancel": true
}
}
Server-authored claim and settle payloads use the same type discriminator:
{
"type": "claim",
"claims": [
{
"voucher": {
"channel": { "...": "..." },
"maxClaimableAmount": "5000"
},
"signature": "0x...voucher signature",
"totalClaimed": "5000"
}
],
"claimAuthorizerSignature": "0x...claim authorization"
}
claimAuthorizerSignature is included when the server owns the receiver-authorizer key. If receiver authorization is delegated to the facilitator, the server omits it and the facilitator signs before submitting the transaction.
{
"type": "settle",
"receiver": "0xServerReceiverAddress",
"token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
}
Example facilitator response for a claim:
{
"success": true,
"transaction": "0x...transactionHash",
"network": "eip155:8453",
"amount": ""
}
amount is empty because claim only updates accounting; no funds move.
Example facilitator response for a settle:
{
"success": true,
"transaction": "0x...transactionHash",
"network": "eip155:8453",
"amount": "5000"
}
amount is the amount transferred to the receiver; if settlement is a no-op, it is "0".
Example facilitator response for a deposit (see Payment Response Contract for the managed extras):
{
"success": true,
"transaction": "0x...transactionHash",
"network": "eip155:8453",
"payer": "0xPayerAddress",
"amount": "100000",
"asset": "0xAssetAddress",
"extra": {
// Facilitator-managed only:
// "chargedAmount": "700",
// "chargeCount": 4,
"channelState": {
"channelId": "0xabc123...",
"balance": "100000",
"totalClaimed": "3200",
"withdrawRequestedAt": 0,
"refundNonce": "1",
// Facilitator-managed only:
// "chargedCumulativeAmount": "3900"
},
},
}
Example facilitator response for a refund:
{
"success": true,
"transaction": "0x...transactionHash",
"network": "eip155:8453",
"payer": "0xPayerAddress",
"amount": "1500",
"extra": {
// Facilitator-managed only:
// "chargeCount": 4,
"channelState": {
"channelId": "0xabc123...",
"balance": "98500",
"totalClaimed": "3200",
"withdrawRequestedAt": 0,
"refundNonce": "2",
// Facilitator-managed only:
// "chargedCumulativeAmount": "3200"
},
},
}
amount is the amount returned to the payer.
If a deposit, claim, settle, or refund transaction broadcasts successfully but its confirmation cannot be established (e.g. a node/RPC error or timeout while waiting for the receipt), the facilitator MAY return settlement_pending (see §9 Error Handling) with the broadcast transaction hash in transaction, so the caller can reconcile on chain before retrying.
GET /supported
The facilitator MAY declare a receiver authorizer whose role is to produce EIP-712 signatures for claims and refunds. The server may delegate to this address as its channel’s receiverAuthorizer, or supply its own. Any address in signers may relay the resulting transactions. extra.delegatedRefund: true signals that the facilitator authenticates /settle callers and honors unsigned refunds from the service that created the channel. It replaces any address-valued refund-authorizer advertisement. A facilitator that supports it advertises delegatedRefund: true next to receiverAuthorizer. Its meaning depends on the mode:
- Self-managed delegation: a server that delegates
receiverAuthorizerand sends no signatures relies on the facilitator’s caller authentication, so the facilitator advertisesdelegatedRefund: true. A facilitator that advertisesdelegatedRefund: falsewill not honor unsigned refunds, and a server delegating to it cannot refund. - Facilitator-managed:
receiverAuthorizeralone is enough when the server brings its own refund key (extra.refundAuthorizeron the 402).delegatedRefund: trueis needed only when the server omitsextra.refundAuthorizerand relies on the facilitator’s caller authentication.
A facilitator with no /settle caller authentication MAY advertise a receiverAuthorizer for facilitator-managed mode only, where servers bring their own refund key; it MUST NOT expect servers to delegate refund consent to it in self-managed mode (see Security and Trust). An absent delegatedRefund field denotes a legacy facilitator whose support is unknown; servers MUST treat it as “no information”, not as false.
A facilitator lists the voucher-management modes it supports in voucherManager. Offering "facilitator" also requires withdrawDelay:
{
"kinds": [
{
"x402Version": 2,
"scheme": "batch-settlement",
"network": "eip155:8453",
"extra": {
"receiverAuthorizer": "0xReceiverAuthorizerAddress",
"delegatedRefund": true,
// Facilitator-managed only:
// "withdrawDelay": 604800,
// "voucherManager": ["server", "facilitator"]
},
},
],
"extensions": [],
"signers": {
"eip155:*": ["0xSignerAddress1", "0xSignerAddress2"],
},
}
Verification Rules
A facilitator must enforce:
- Channel config consistency (deposit, voucher, and refund): the config’s chain-bound EIP-712 hash must equal the claimed channel ID.
- Token match: the channel token must match the payment requirements asset.
- Receiver match: the channel receiver must equal the payment requirements
payTo. - Receiver authorizer match: the channel receiver authorizer must equal
extra.receiverAuthorizer. - Withdraw delay match: the channel withdraw delay must equal
extra.withdrawDelay. - Signature validity: recover the signer from the EIP-712 voucher digest. If the payer authorizer is set, the signer must match it (ECDSA only). If the payer authorizer is zero, validate via
SignatureCheckeragainst the payer. - Channel existence: the channel must have a positive balance.
- Balance check (deposit only): the client must have sufficient token balance.
- Deposit sufficiency:
maxClaimableAmountmust be at mostbalance(orbalance + depositAmountfor deposit payloads). - Not below claimed: for voucher and deposit payloads,
maxClaimableAmountmust be at least onchaintotalClaimed + requirements.amount, so every paid request advances the cumulative ceiling by at least the price. This floor is strict:maxClaimableAmountmust also be strictly greater thantotalClaimed, so a zero-price route cannot be satisfied by a voucher equal tototalClaimed.requirements.amountis supplied by the resource server and MUST NOT be trusted: the facilitator MUST validate it as a non-negative base-10 integer string before use and, if it is malformed or negative, MUST return an invalid response (invalid_batch_settlement_evm_voucher_payloadfor vouchers,invalid_batch_settlement_evm_deposit_payloadfor deposits) rather than throwing or lowering the floor. For refund payloads (payload.type == "refund"), this rule is relaxed tomaxClaimableAmount >= totalClaimed, since refund vouchers are zero-charge and may match the already-claimed total exactly. - Signed refunds: the refund nonce must equal the onchain
refundNonceat the time of submission; the EIP-712Refunddigest (Refund(bytes32 channelId,uint256 nonce,uint128 amount)) must bind the sameamountsubmitted in the transaction. The contract increments the nonce before computing the capped transfer amount, so the nonce advances even when no tokens move. - Managed watermark (
extra.voucherManager === "facilitator"):maxClaimableAmountmust equalchargedCumulativeAmount + paymentRequirements.amount. For refund payloads,maxClaimableAmountmust equalchargedCumulativeAmount. On mismatch, returninvalid_batch_settlement_evm_cumulative_amount_mismatchwithextra.channelStateandextra.voucherState. - Refund authorizer bind (facilitator-managed mode): whenever
extra.refundAuthorizeris present, the address unpacked fromchannelConfig.saltmust equal it. Managed/verify(including deposit) MUST reject a 402 that omitsextra.refundAuthorizerwhen the facilitator does not honor caller-identity refunds (delegatedRefundis nottrue), because neither consent path would be available.
The facilitator must return the channel snapshot (balance, totalClaimed, withdrawRequestedAt, refundNonce) in every /verify response extra field and in every /settle response under extra.channelState. In facilitator-managed mode those objects MUST also include chargedCumulativeAmount. If withdrawRequestedAt is non-zero, outstanding vouchers should be claimed promptly before the withdraw delay elapses.
Claim & Settlement Strategy
In self-managed mode the server runs this strategy. In facilitator-managed mode the facilitator does - including claiming before a timed withdrawal finalizes and refunding idle channels.
claim(voucherClaims) validates payer voucher signatures and updates accounting for multiple channels; msg.sender must be receiver or receiverAuthorizer for every row. claimWithSignature(claims, signature) is the relay-friendly variant: anyone can submit it with a valid EIP-712 ClaimBatch signature from receiverAuthorizer covering all rows (all rows must share the same receiverAuthorizer). No token transfer occurs in either path.
Claim attestation. In facilitator-managed mode, the facilitator SHOULD attest the chargeCount deltas of a claim onchain by carrying them in the settlement metadata field m of the transaction’s ERC-8021 Schema 2 calldata suffix. The contract is unchanged: it ignores trailing calldata and does not validate the suffix.
This only reuses the ERC-8021 / x402 builder-code suffix format (CBOR map with an m entry, followed by the ERC-8021 marker) as a carrier for facilitator-authored metadata:
- No builder code is required. The facilitator does not need a
wcode, and noaorscodes are involved. A suffix that carries onlymis valid. - It composes with builder codes. When the facilitator also configures a builder code, or the payment carries client/server attribution,
mrides in the same single suffix next tow/a/s. The two are independent; neither changes the meaning of the other. - Single suffix, at the end of the top-level calldata. ERC-8021 parsers only read the end of the transaction input, so the suffix is appended once to the outer call. Inner
multicalllegs carry no suffix.
Encoding. m has one key:
m = { "x402ChargeCounts": [c0, c1, ..., c(n-1)] }
- The array has one entry per claim row, across all
claim/claimWithSignaturelegs of the transaction, in call order (leg order, then row order within a leg). Entryciis thechargeCountdelta of rowi. - Entries are unsigned integers in shortest-form CBOR: 1 byte up to 23, 2 bytes up to 255, 3 bytes up to 65,535. Zero counts stay in the array so positions remain aligned with rows.
- The key MUST be omitted when the transaction has no claim leg (refund-only,
settle,deposit). - Overhead is about 22 bytes plus 1–3 bytes per row; 100 rows fit in roughly 120–320 bytes.
Example: for rows with counts 3, 0, 41, the m entry of the CBOR suffix map is 616d a1 70<"x402ChargeCounts"> 83 03 00 1829 (25 bytes). Together with a facilitator code the full map is {"w":"bc_myfacilitator","m":{"x402ChargeCounts":[3,0,41]}}.
Row selection. The facilitator MUST only include rows that advance totalClaimed (chargedCumulativeAmount > totalClaimed) and SHOULD NOT include the same channelId twice in one transaction. The contract does not reject duplicates: a row whose totalClaimed is not above the channel’s current total is a silent no-op, so a repeated channel can leave a later row without a Claimed event. Every other row emits exactly one Claimed event, in row order, except when execution races with an out-of-band claim or the batch was already applied (a no-op row emits no Claimed).
Indexer decoding (row join). Indexers MUST join counts to rows by (channelId, newTotalClaimed), never by event position, because a single no-op row would shift every later pairing and attribute counts to the wrong channels:
- Parse the ERC-8021 suffix from the top-level transaction input and read
m.x402ChargeCounts. If it is absent, there is no attestation. - ABI-decode the top-level call. Unwrap
multicall(bytes[])and collect the rows of everyclaim/claimWithSignatureleg in call order. If the array length does not equal the total row count, ignore the attestation. - Compute each row’s
channelIdfrom its channel config (EIP-712 hash, chain-bound). - Match each row against the
Claimed(channelId, ...)events emitted byx402BatchSettlementin the same receipt: the event whosechannelIdequals the row’s and whosenewTotalClaimedequals the row’stotalClaimed. Each event matches at most one row. A matched row attestschargeCounts[i]to that channel. A row without a match was a no-op and attests nothing. For example, rows[A, totalClaimed=8], [A, totalClaimed=5]emit a singleClaimed(A, newTotalClaimed=8): only row 0 attests. If several matched rows share achannelId, their counts are snapshots of the same per-channel counter (which only drops after the claim confirms), so indexers MUST credit the channel with the largest of them, not their sum. - Authenticate the submitter. The suffix is not signed, and
claimWithSignaturecan be submitted by anyone, so any account can attach counts to a valid claim. Indexers MUST honor counts only from transactions sent tox402BatchSettlementby a sender they trust, for example the facilitator’s submitting addresses (a directclaimis already restricted by the contract toreceiver/receiverAuthorizer; the relay path is sent by the facilitator’s own signer, not thereceiverAuthorizer).Claimed.senderis that sender.
Indexers that cannot ABI-decode calldata (for example SQL over events) MAY use a shortcut: if the number of Claimed events in the transaction equals the length of x402ChargeCounts, every row applied and the n-th Claimed event by log index takes chargeCounts[n]. Otherwise the pairing is ambiguous and the attestation MUST be ignored.
After confirmation. The facilitator subtracts the attested snapshot from the stored chargeCount only for rows that emitted Claimed (matched as above; the largest snapshot once per channel if a channel repeats); do not zero the field, or in-flight commits are lost. Counts of rows that emitted no Claimed (including every row of an already-applied batch) stay pending and are attested by that channel’s next claim, as are charges of zero amount, which increment chargeCount without creating a claim row.
Facilitators claim and refund in one transaction via multicall(bytes[]) of [claim, refund]; the layout above applies unchanged, with m on the outer suffix and a bare inner claim. Indexers MUST support a direct claim / claimWithSignature call and multicall(bytes[]). Other wrappers (for example Multicall3 or smart-account execute) can only be attested by indexers that know how to unwrap them.
settle(receiver, token) transfers all claimed-but-unsettled funds for a receiver+token pair to the receiver in one transfer. Permissionless.
| Strategy | Description | Trade-off |
|---|---|---|
| Periodic | Claim + settle every N minutes | Predictable gas costs |
| Threshold | Claim + settle when unclaimed amount exceeds T | Bounds server’s risk exposure |
| On withdrawal | Claim + settle when withdrawal is initiated | Minimum gas, maximum risk window |
Outstanding vouchers must be claimed before the withdraw delay elapses. Unclaimed vouchers become unclaimable after finalizeWithdraw() reduces the channel balance.
Client Verification Rules
Steady State
PAYMENT-RESPONSE extra is untrusted. The client updates local state
from its own previous state plus extra.chargedAmount (missing is 0).
It MUST NOT copy extra.channelState into that local state.
The client applies that update only when chargedAmount <= PaymentRequirements.amount and, if present,
channelState.chargedCumulativeAmount equals previous + chargedAmount.
Otherwise it MUST leave local state unchanged.
The next voucher is signed from that local state. A skipped apply is not a new charge; desync is recovered via Corrective 402.
Recovery After State Loss
Channel identity is deterministic. The client can recompute channelId from the 402 response plus its own channel parameters (payer, payerAuthorizer, salt), then read channels(channelId) to recover the onchain balance and totalClaimed. In facilitator-managed mode with a server-owned refund key, salt carries extra.refundAuthorizer, so recovery must use the same address that opened the channel. Without extra.refundAuthorizer (the server relies on delegatedRefund), and in self-managed mode, salt is the raw client salt.
The recovery baseline is:
- Use onchain
totalClaimedwhen no trusted offchain state is available. - Use server-provided
chargedCumulativeAmountonly when the server also returns the last signed voucher (signedMaxClaimableandsignature) and the client verifies that signature against its own voucher signer.
Client cold start. When the client has no local channel record, it reads onchain state and sets chargedCumulativeAmount = totalClaimed. If the next request would exceed the recovered balance, the client sends a deposit/top-up payload. Otherwise it signs a voucher for totalClaimed + amount.
Server state loss. If the voucher manager (server or facilitator) has no channel record, it sets chargedCumulativeAmount = totalClaimed as the baseline, using the totalClaimed returned by the facilitator’s onchain read for this request. The voucher manager MUST NOT derive the baseline from the client-signed voucher. A resource server acting as voucher manager MUST reject the request if the facilitator response does not include totalClaimed, and MUST parse totalClaimed canonically: either a plain decimal string with no leading zeros ("0" is the only string that starts with 0), or a JSON number that is a non-negative integer no greater than 2^53 − 1. Anything else (leading zeros, signs, whitespace, non-integers, out-of-range numbers) is treated as missing. If the voucher manager lost unclaimed vouchers, those unclaimed charges are forfeited.
Corrective 402. If a paid payload (deposit or voucher) is rejected because the client’s cumulative amount does not match the voucher manager’s chargedCumulativeAmount, the 402 is invalid_batch_settlement_evm_cumulative_amount_mismatch with accepts[].extra.channelState containing the channel snapshot and accepts[].extra.voucherState containing signedMaxClaimable and signature. The client verifies the voucher signature before adopting chargedCumulativeAmount and retrying. In facilitator-managed mode the 402 also carries the managed extra fields (voucherManager, and refundAuthorizer when the server owns the refund key).
{
"x402Version": 2,
"error": "invalid_batch_settlement_evm_cumulative_amount_mismatch",
"accepts": [
{
"scheme": "batch-settlement",
"extra": {
"receiverAuthorizer": "0xReceiverAuthorizerAddress",
"withdrawDelay": 900,
"name": "USDC",
"version": "2",
// Facilitator-managed only:
// "voucherManager": "facilitator",
// Only when the server owns the refund key:
// "refundAuthorizer": "0xRefundAuthorizerAddress",
"channelState": {
"channelId": "0xabc123...channelId",
"balance": "100000",
"totalClaimed": "500",
"withdrawRequestedAt": 0,
"refundNonce": "1",
"chargedCumulativeAmount": "3200",
},
"voucherState": {
"signedMaxClaimable": "3200",
"signature": "0x...last voucher signature",
},
},
},
],
}
Error Codes
| Error Code | Description |
|---|---|
invalid_batch_settlement_evm_authorizer_address_mismatch |
Authorizer address does not match the expected receiver authorizer |
invalid_batch_settlement_evm_channel_busy |
Another request holds the per-channel lock; client should retry shortly |
invalid_batch_settlement_evm_channel_id_mismatch |
Channel config does not hash to the claimed channel ID |
invalid_batch_settlement_evm_channel_not_found |
No channel with positive balance for the given channel ID |
invalid_batch_settlement_evm_channel_state_read_failed |
Facilitator failed to read onchain channel state |
invalid_batch_settlement_evm_charge_exceeds_signed_cumulative |
Committing the charge would exceed the voucher’s signed maxClaimableAmount |
invalid_batch_settlement_evm_claim_payload |
Claim payload is malformed |
invalid_batch_settlement_evm_claim_simulation_failed |
Claim simulation failed |
invalid_batch_settlement_evm_claim_transaction_failed |
Onchain claim transaction failed |
invalid_batch_settlement_evm_cumulative_amount_mismatch |
Corrective 402: client’s cumulative voucher ceiling does not match the server’s tracked chargedCumulativeAmount |
invalid_batch_settlement_evm_cumulative_below_claimed |
Voucher maxClaimableAmount violates monotonicity vs onchain totalClaimed (voucher and deposit verify: must be at least totalClaimed + requirements.amount and strictly greater than totalClaimed; refund: must not be strictly below totalClaimed) |
invalid_batch_settlement_evm_cumulative_exceeds_balance |
Voucher maxClaimableAmount exceeds effective onchain balance |
invalid_batch_settlement_evm_deposit_below_min_deposit |
Server rejected a deposit below its local extra.minDeposit policy |
invalid_batch_settlement_evm_deposit_payload |
Deposit payload is malformed |
invalid_batch_settlement_evm_deposit_simulation_failed |
Deposit simulation failed |
invalid_batch_settlement_evm_deposit_transaction_failed |
Onchain deposit transaction failed |
invalid_batch_settlement_evm_eip2612_amount_mismatch |
EIP-2612 permit amount does not match the requested authorization |
invalid_batch_settlement_evm_eip2612_asset_mismatch |
EIP-2612 permit asset does not match the payment asset |
invalid_batch_settlement_evm_eip2612_deadline_expired |
EIP-2612 permit deadline has expired |
invalid_batch_settlement_evm_eip2612_invalid_format |
EIP-2612 permit segment is malformed |
invalid_batch_settlement_evm_eip2612_invalid_signature |
EIP-2612 permit signature is invalid |
invalid_batch_settlement_evm_eip2612_owner_mismatch |
EIP-2612 permit owner does not match the payer |
invalid_batch_settlement_evm_eip2612_spender_mismatch |
EIP-2612 permit spender does not match the expected spender |
invalid_batch_settlement_evm_erc20_approval_asset_mismatch |
ERC-20 approval asset does not match the payment asset |
invalid_batch_settlement_evm_erc20_approval_broadcast_failed |
Facilitator failed to broadcast the pre-signed ERC-20 approval transaction |
invalid_batch_settlement_evm_erc20_approval_from_mismatch |
ERC-20 approval signer does not match the payer |
invalid_batch_settlement_evm_erc20_approval_invalid_format |
ERC-20 approval segment is malformed |
invalid_batch_settlement_evm_erc20_approval_unavailable |
ERC-20 approval gas sponsorship is unavailable |
invalid_batch_settlement_evm_erc20_approval_wrong_spender |
ERC-20 approval spender is not Permit2 |
invalid_batch_settlement_evm_erc3009_authorization_required |
Deposit payload is missing the required erc3009Authorization |
invalid_batch_settlement_evm_insufficient_balance |
Client token balance is insufficient for the deposit |
invalid_batch_settlement_evm_missing_channel |
Resource server has no channel session for the payload’s channel ID |
invalid_batch_settlement_evm_missing_eip712_domain |
Token EIP-712 domain (name, version) is missing from payment requirements |
invalid_batch_settlement_evm_network_mismatch |
Payment payload accepted.network does not match paymentRequirements.network on the verify request |
invalid_batch_settlement_evm_payload_authorization_valid_after |
ERC-3009 authorization validAfter is still in the future |
invalid_batch_settlement_evm_payload_authorization_valid_before |
ERC-3009 authorization validBefore has already passed |
invalid_batch_settlement_evm_payload_type |
Payload type is not valid for the current verify/settle operation |
invalid_batch_settlement_evm_pending_id_mismatch |
/settle echoed a pendingId whose voucher does not match the live reservation |
invalid_batch_settlement_evm_permit2_allowance_required |
Permit2 allowance is required before deposit |
invalid_batch_settlement_evm_permit2_amount_mismatch |
Permit2 authorization amount does not match the requested deposit amount |
invalid_batch_settlement_evm_permit2_authorization_required |
Deposit payload is missing the required Permit2 authorization |
invalid_batch_settlement_evm_permit2_deadline_expired |
Permit2 authorization deadline has expired |
invalid_batch_settlement_evm_permit2_invalid_signature |
Permit2 authorization signature is invalid |
invalid_batch_settlement_evm_permit2_invalid_spender |
Permit2 authorization spender is not the expected spender |
invalid_batch_settlement_evm_receive_authorization_signature |
ERC-3009 receiveWithAuthorization signature is invalid |
invalid_batch_settlement_evm_receiver_authorizer_mismatch |
Channel receiver authorizer does not match extra.receiverAuthorizer |
invalid_batch_settlement_evm_receiver_mismatch |
Channel receiver does not match payTo |
invalid_batch_settlement_evm_refund_amount_invalid |
Refund amount is non-numeric or non-positive |
invalid_batch_settlement_evm_refund_authorizer_mismatch |
Address unpacked from channelConfig.salt does not match extra.refundAuthorizer |
invalid_batch_settlement_evm_refund_authorizer_signature |
refundAuthorizerSignature is missing or does not recover to extra.refundAuthorizer |
invalid_batch_settlement_evm_refund_no_balance |
Cooperative refund requested but no refundable balance remains |
invalid_batch_settlement_evm_refund_payload |
Refund payload is malformed |
invalid_batch_settlement_evm_refund_simulation_failed |
Refund simulation failed |
invalid_batch_settlement_evm_refund_transaction_failed |
Onchain refund transaction failed |
invalid_batch_settlement_evm_rpc_read_failed |
Facilitator failed to read required onchain data |
invalid_batch_settlement_evm_scheme |
scheme is not batch-settlement |
invalid_batch_settlement_evm_settle_payload |
Settle payload is malformed |
invalid_batch_settlement_evm_nothing_to_settle |
Receiver/token pair has no claimed-but-unsettled funds |
invalid_batch_settlement_evm_settle_simulation_failed |
Settle simulation failed |
invalid_batch_settlement_evm_settle_transaction_failed |
Onchain settle transaction failed |
invalid_batch_settlement_evm_token_mismatch |
Channel token does not match the payment requirements asset |
invalid_batch_settlement_evm_transaction_reverted |
Submitted transaction reverted |
invalid_batch_settlement_evm_unexpected_cancel |
Client supplied server-authored cancel |
invalid_batch_settlement_evm_unexpected_pending_id |
Client supplied server-authored pendingId |
invalid_batch_settlement_evm_unknown_settle_action |
Settle payload requested an unknown action |
invalid_batch_settlement_evm_voucher_payload |
Voucher payload is malformed |
invalid_batch_settlement_evm_voucher_signature |
EIP-712 voucher signature does not recover to the expected signer |
invalid_batch_settlement_evm_wait_for_receipt_failed |
Facilitator failed while waiting for the transaction receipt |
invalid_batch_settlement_evm_withdraw_delay_mismatch |
Channel withdraw delay does not match extra.withdrawDelay |
invalid_batch_settlement_evm_withdraw_delay_out_of_range |
Withdraw delay is outside the 15 min - 30 day bounds |
settlement_pending |
Broadcast succeeded but confirmation could not be established - non-terminal; carries the broadcast transaction hash so the caller can reconcile on chain before retrying |
Security and Trust
-
Capital risk and cumulative replay protection: Clients bear risk up to the signed
maxClaimableAmount; the receiver authorizer determines actualtotalClaimedonchain within that bound. Over-claiming is a trust violation, not a protocol violation. The cumulative model makes nonces unnecessary. AstotalClaimedonly increases, and old vouchers are naturally superseded. -
Withdrawal delay as escape hatch: The 15 min – 30 day bounds prevent a server from indefinitely trapping client funds while giving the server a fair window to claim outstanding vouchers. Cooperative refund returns unclaimed balance immediately when the server cooperates; timed withdrawal is the unilateral fallback. Servers bear the risk of vouchers left unclaimed when
finalizeWithdrawcompletes. -
Cross-function replay prevention:
Voucher,Refund, andClaimBatchuse distinct EIP-712 type hashes so a signature for one cannot be replayed as another. Refunds additionally carry a per-channel nonce. -
Voucher expiry via escrow depletion: Vouchers carry no expiry field. A voucher remains claimable as long as
balance - totalClaimed > 0;finalizeWithdrawandrefundWithSignatureclose the claim window by draining available escrow. The ERC-3009validBefore/validAfterfields bound only the deposit authorization, not the voucher. -
Refund authorization: A cooperative refund bypasses the timed-withdrawal delay, so it must carry receiver-side consent. In self-managed mode, when the server supplies its own
refundAuthorizerSignaturethat signature is the consent; when the server delegatesreceiverAuthorizerto the facilitator, the facilitator MUST authenticate that eachrefundrequest originates from the service that created the channel (e.g. SIWX, JWT, or API credential bound at channel-creation time) and reject all others. In facilitator-managed mode the consent is therefundAuthorizerSignaturefromextra.refundAuthorizer, or out-of-band/settlecaller authentication when the 402 omitsextra.refundAuthorizerand the facilitator advertisesdelegatedRefund: true(see Cooperative refund flow). -
Admission reservation:
/verifyand/settlethat carry apendingIdSHOULD run over an authenticated facilitator channel. A facilitator that exposes/settleto untrusted callers MUST NOT treatpendingIdas authorization.
Reference Implementation: x402BatchSettlement
The batch-settlement scheme is implemented by the x402BatchSettlement contract alongside the ERC3009DepositCollector and Permit2DepositCollector deposit collector contracts. Each contract is deployed to a deterministic address across all supported EVM chains via CREATE2.
| Contract | Canonical Address |
|---|---|
x402BatchSettlement |
0x4020074e9dF2ce1deE5A9C1b5c3f541D02a10003 |
ERC3009DepositCollector |
0x4020806089470a89826cB9fB1f4059150b550004 |
Permit2DepositCollector |
0x4020425FAf3B746C082C2f942b4E5159887B0005 |
The x402BatchSettlement contract uses ReentrancyGuardTransient (EIP-1153 transient storage) and must only be deployed on chains where that opcode is supported.
Version History
| Version | Date | Changes | Authors |
|---|---|---|---|
| v1.1 | 2026-10-06 | Facilitator-managed vouchers mode | @phdargen @CarsonRoscoe |
| v1.0 | 2025-04-28 | Initial draft | @phdargen @CarsonRoscoe @ilikesymmetry |