SVM batch-settlement Scheme: High-Throughput Channel Payments on Solana
Companion to the network-agnostic
scheme_batch_settlement.md. This document specifies how thebatch-settlementscheme is realized on Solana Virtual Machine (SVM) networks.
1. Purpose
batch-settlement is the high-throughput x402 scheme: a client deposits once
into an escrow channel, then authorizes cumulative Ed25519 vouchers for
individual requests. By default the client signs each voucher. An optional
server-signer mode lets the client sign an expiring channel-bound bearer proof and
the resource operator sign cumulative vouchers for the actual metered amount
after successful requests. The server verifies each authorization offchain, stores the latest
commitment, serves immediately, and later redeems the latest voucher onchain.
This removes onchain settlement from the request path.
On SVM this scheme is backed by the
payment-channels program,
the same program used by SVM upto. upto is a one-request channel that closes
after one metered charge; batch-settlement keeps the channel open across many
requests and advances a cumulative watermark.
The x402 roles map to the payment-channel program as follows:
- Client: channel
payer; funds deposits and either signs per-request vouchers or signs expiring operator authorizations. - Voucher signer: Ed25519 key recorded as channel
authorized_signer. In client mode it is client-controlled and MAY equalpayer; in server mode it is theextra.operatorkey controlled by the resource operator. - Server: resource provider; receives funds at
payTo; owns per-channel offchain state, including the accepted cumulative watermark and latest voucher. - Receiver authorizer: required server-controlled Ed25519 key advertised as
extra.receiverAuthorizer(section 3). It is an offchain x402 role and is not recorded in the payment-channel account. - Facilitator / sponsor: account advertised as
extra.feePayer; sponsors transaction fees and channel rent. It is the transaction fee payer and channelrent_payer, and occupies the channelpayeelifecycle-authority seat with a zero share of settled funds. The server MAY self-facilitate.
payTo is the server’s payment receiver, typically a cold wallet. The channel
distribution always sends 100% of settled funds to payTo through one explicit
recipient and leaves the channel payee with a zero implicit remainder, even
when both roles use the same address.
This authority split prevents rent lock without granting payment authority to the facilitator:
- The facilitator, as
payee, can runsettle_and_sealwithhas_voucher = 0, thendistributeandreclaim, even if the client and server disappear. A client/server pair cannot strand the rent it sponsored. - Only the channel’s
payerAuthorizercan sign a voucher that advances the settled watermark. In client mode this is client-controlled. In server mode the client explicitly delegates that authority toextra.operator, which can sign up to the full channel deposit. The facilitator can close at the current onchain watermark but cannot redirect funds.
A facilitator that closes before the latest client voucher is claimed freezes the watermark and causes the unclaimed remainder to be returned to the client. The server MUST treat unclaimed voucher value as facilitator credit risk and claim promptly.
2. Mapping the Core Requirements to SVM
| Requirement (generic spec) | SVM mechanism |
|---|---|
| One-time escrow deposit | Payment-channels open deposits escrow, records withdrawDelay, fixes payee, authorized_signer, rent_payer, and commits distribution_hash. |
| Per-request authorization | Client mode: an Ed25519 voucher signed by payerAuthorizer. Server mode: an expiring payer proof plus a single-use request identifier; the advertised amount is a ceiling and the operator signs the actual cumulative charge after serving. |
| Monotonic amount | Server-owned offchain watermark plus onchain settled < maxClaimableAmount <= deposit at redemption. For client-signed voucher verify and for the client-signed voucher on a top-up deposit, the facilitator MUST require maxClaimableAmount >= Channel.settled + PaymentRequirements.amount and maxClaimableAmount > Channel.settled, so a zero-price route cannot be satisfied by a voucher equal to Channel.settled. |
| Batched redemption | One settle per channel, packed transaction-size permitting; distribute pays settled deltas. |
| Recipient binding | distribution_hash fixed at open sends funds to payTo; program re-checks it at distribute. |
| Recovery of unused deposit | Section 3. |
3. Payment-Channel Method
SVM batch-settlement defines a single payment method backed by the
payment-channels program, so the wire format does not include
extra.assetTransferMethod.
The canonical program id is a network/SDK constant, not a server-provided wire field. For the current mainnet deployment:
CHNLxYvVA28MJP9PrFuDXccuoGXAx7jBacfLEkahyGsX
Implementations MUST target the canonical payment-channels program id for the
selected network and MUST NOT trust or negotiate a channelProgram value from
extra. Program documentation and instruction references live in the
payment-channels repository.
The current program lifecycle is:
open: creates the channel PDA, escrows the deposit, storesgrace_period == extra.withdrawDelay, storesopen_slot, and commits the payout distribution.settle: permissionlessly advances the onchainsettledwatermark from a valid voucher.distribute: permissionlessly pays the newly settled delta topayToand advancespayout_watermark. While the channel is still open, it does not return unused escrow to the payer or close the escrow.settle_and_seal:payee-signed cooperative close. It may apply a final voucher, locks the watermark, and moves the channel toSealed.- Sealed
distribute: pays any final settled delta, returnsdeposit - settledto the payer, closes the escrow token account, and either deallocates the channel PDA immediately or marks itDistributed. reclaim: permissionless cleanup forDistributedchannels afterclock.slot > open_slot + OPEN_SLOT_WINDOW; it returns remaining PDA rent to the recordedrent_payer.
The address carried on the x402 wire as extra.feePayer is recorded by the
program as both Channel.rent_payer and zero-share Channel.payee. Rent returns
to that address during the final distribute fast path or a later reclaim.
Because the sponsor holds the payee lifecycle authority, it can seal and clean
up an abandoned channel without a client or server signature. It MUST be able
to rediscover the channels it sponsored as specified in section 6. Token
payouts and the return of unused escrow are completed by distribute and are
not delayed by the later reclaim of PDA rent.
Every channel is bound to one receiver authorizer at open. The client’s open transaction carries, in addition to the seller/nonce Memo, a binding Memo whose UTF-8 data is exactly:
x402:batch-settlement:svm:rcvauth:v1:<base58 receiverAuthorizer>
The key MUST equal extra.receiverAuthorizer. Because the payer signs the open
transaction, the binding is fixed for the channel lifetime; changing it
requires closing the channel and opening a new one. The facilitator MUST NOT
trust a receiver-authorizer key merely because it appears in
PaymentRequirements or a settlement request.
The bound key is either the server’s own signer (self-managed) or a key the
facilitator advertises and holds (delegated). A server with no local signer
MUST copy extra.receiverAuthorizer from the facilitator’s /supported
advertisement and MUST refuse to start when that advertisement is missing or
not a Solana address. A server with a local signer MUST reject a challenge
whose extra.receiverAuthorizer is a different key.
In delegated mode the facilitator authenticates the caller. On the open it
resolves a caller identity and records it, keyed by (network, channelId),
before broadcast. A missing identity MUST be rejected with
invalid_batch_settlement_svm_delegated_unauthenticated. The first writer
wins. On seal and cooperative refund the same identity MUST be presented
again; closeAuthorization is then omitted. The identity is not onchain. If
the facilitator loses it, those closes fail closed and the client falls back
to request_close. A facilitator that did not opt into delegated
authorization MUST reject a close that omits closeAuthorization.
The facilitator MUST be able to read the binding from at least one of:
- a store, or
- an explicitly configured history reader that pages the channel account’s
signatures to the oldest successful transaction and reads the binding memo
from the base64
getTransactionresult.
The history reader is used only when facilitator config sets it. The facilitator MUST NOT adopt one from the signer or from a public RPC. Startup MUST fail when both sources are absent.
Configuring both is allowed. The store is primary; a history read is written back into the store. Deposit broadcast depends on which sources are configured:
- Store only: the facilitator MUST bind the open’s key and read that row back
before broadcasting. A failed write, or a read-back that is missing or a
different key, MUST NOT send the open. The first writer wins; a different
key MUST be rejected with
invalid_batch_settlement_svm_receiver_authorizer_mismatch. - Store and history: the facilitator MUST bind the open’s key and read that row
back before broadcasting. A failed write, or a read-back that is missing or a
different key, MUST NOT send the open. The first writer wins; a different
key MUST be rejected with
invalid_batch_settlement_svm_receiver_authorizer_mismatch. History remains the fallback at close. - History only: the facilitator does not write a store row, because the transaction is the record, and the open proceeds.
History depth cannot be checked at startup: the history reader’s RPC MUST retain the open for the life of the channel, and a pruned history is an unavailable binding. The binding is read only when closing:
deposit,voucher, andauthorization: no receiver-authorizer check. A top-up does not re-bind.sealand cooperativerefund: the bound key MUST equalextra.receiverAuthorizer. Self-managed closes MUST carry a validCloseAuthorizationfrom that key. Delegated closes MUST match the caller identity bound at open and MUST NOT requirecloseAuthorization. Asealwithout an available binding MUST be rejected.claimandsettle: no receiver-authorizer check.
Neither the binding nor a CloseAuthorization replaces the facilitator’s
onchain payee signature or the close voucher the server supplies at settle
(client-signed in client mode, operator-signed after server enrichment in
server mode). The server MUST
reject an open whose binding Memo is not its own key before forwarding the
deposit. A refund for a channel that is already Closing reports that close.
A refund is a cooperative close by default: the facilitator applies the
server’s accepted voucher with settle_and_seal and a sealed distribute on
the Open channel, returning deposit - settled to the payer at once. When
the binding is unavailable, the client MAY retry once with a payer-signed
request_close transaction. The facilitator adds its fee-payer signature and
broadcasts it, and the facilitator or another permissionless crank finalizes
the channel after the grace period. The idle abandon-close (extra.maxIdleSecs,
Phase 4) and the payer’s own onchain request_close remain the client’s
liveness escape when neither the server nor the facilitator cooperates.
If the client invokes request_close, the channel enters Closing and regular
settle is no longer available. Only the payee can apply a final voucher with
settle_and_seal during the grace period; the server supplies that voucher
through the seal settlement payload of section 4.5, authenticated by its
receiver authorizer. After the grace period, anyone can call seal; the payer
can recover unspent escrow through withdraw_payer or sealed distribute.
4. Wire Format
batch-settlement reuses the x402 v2 transport: a 402 response carries
PAYMENT-REQUIRED; each paid request carries PAYMENT-SIGNATURE; the response
carries PAYMENT-RESPONSE. The core PaymentRequirements, PaymentPayload,
and SettlementResponse types are defined in
x402-specification-v2.md.
4.1 PaymentRequirements (in PAYMENT-REQUIRED.accepts[])
| Field | Type | Required | Notes |
|---|---|---|---|
scheme |
string | yes | "batch-settlement" |
network |
string | yes | CAIP-2, e.g. solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp |
amount |
string | yes | Per-request amount in atomic units. In server mode this is the maximum charge; the actual charge is selected after handling and MUST NOT exceed it. |
asset |
string | yes | Concrete SPL / Token-2022 mint pubkey, not a symbol. |
payTo |
string | yes | Base58 final payment receiver. Normally a server cold wallet. |
maxTimeoutSeconds |
number | yes | HTTP completion window. |
extra |
object | yes | See below. |
extra:
| Field | Type | Required | Notes |
|---|---|---|---|
paymentFlow |
string | no | When present, MUST be "authorization". The scheme resolves to the protocol-default authorization flow: read-only verification runs before the resource handler, and /settle commits the voucher - and broadcasts any deposit transaction - after it. |
feePayer |
string | yes | Base58 sponsor key set as channel rent_payer and zero-share payee. Co-signs setup/top-up transactions as transaction fee payer and signs channel lifecycle transactions. |
receiverAuthorizer |
string | yes | Base58 server-controlled Ed25519 key (section 3). Not a payment-channel account field. |
voucherSigner |
string | no | Voucher-signing mode: "client" (default) or "server". A client MUST NOT act on a "server" accept unless it has trusted that operator out of band (section 8); a server advertising "server" SHOULD list a "client" accept for the same resource alongside it so clients that do not extend that trust can still pay. |
operator |
string | conditional | Base58 resource-operator Ed25519 key. REQUIRED when voucherSigner == "server"; MUST be absent in client mode. |
withdrawDelay |
number | yes | Forced-close grace period in seconds. MUST be an integer from 900 through 2592000 (15 minutes through 30 days), MUST be >= maxTimeoutSeconds, and MUST be encoded exactly as the program grace_period. The payment-channels program accepts any positive grace_period; this range is an x402 conformance bound, so verifying facilitators MUST enforce it and reject out-of-range requirements. |
tokenProgram |
string | yes | SPL Token (Tokenkeg...) or Token-2022 (TokenzQ...) program that owns asset. The client and facilitator MUST verify it against the onchain mint owner. |
memo |
string | no | Seller-defined UTF-8 payment reference for the setup transaction’s Memo instruction. Maximum 256 bytes. |
recentBlockhash |
string | no | Pre-fetched blockhash the client MAY use to build an open or top_up transaction without an RPC round trip. The client MUST refresh it if it is no longer valid. |
recentSlot |
number | no | Recent slot the client MAY use as channelConfig.openSlot when it does not fetch its own slot. The program still enforces the open-slot window. |
minDeposit |
string | no | Atomic deposit target. When present, MUST be a positive integer greater than or equal to amount. |
maxIdleSecs |
number | no | Facilitator idle window in seconds, copied from the facilitator’s /supported extra. After this long with no facilitator-visible lifecycle activity on an Open channel, the facilitator MAY abandon-close it at the onchain settled watermark (see Phase 4). Absent means the facilitator does not idle-close. |
transactionVersions |
array | no | Transaction message versions the facilitator accepts, as an array of 0 and/or 1, copied from the facilitator’s /supported extra. Absent means [0]. See Transaction versions. |
maxClaimChannels |
number | no | Most claims[] entries the facilitator redeems in one claim transaction, copied from the facilitator’s /supported extra. Absent means 4. See Facilitator-built transactions. |
maxSettleChannels |
number | no | Most channels[] entries the facilitator distributes in one settle transaction, copied from the facilitator’s /supported extra. Absent means 4. |
channelState |
object | no | Corrective-only server channel snapshot for cumulative amount resynchronization. |
voucherState |
object | no | Corrective-only signed voucher proof for cumulative amount resynchronization. |
recentBlockhash and recentSlot are
transaction-construction hints only. They are not persistent channel
configuration and are not included in the voucher message. A client MAY ignore
the hints and obtain fresher values from an RPC.
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 it
and MUST return
invalid_batch_settlement_svm_deposit_below_min_deposit. The facilitator MUST
NOT enforce minDeposit.
The x402 wire format does not expose program-specific split arrays. The client derives the payment-channel accounts and distribution from the x402 fields:
rent_payer = extra.feePayer
payee = extra.feePayer
authorized_signer = channelConfig.payerAuthorizer
grace_period = extra.withdrawDelay
recipients = [{ recipient: payTo, bps: 10000 }]
payee_implicit_remainder_bps = 0
Any facilitator commercial fee is outside this wire contract or included in the
server’s pricing. The channel distribution for this scheme MUST NOT assign any
portion of settled funds away from payTo. The explicit single-entry
distribution is REQUIRED even when payTo == extra.feePayer.
Example:
{
"scheme": "batch-settlement",
"network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
"amount": "1000",
"asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"payTo": "<server-receiver>",
"maxTimeoutSeconds": 300,
"extra": {
"feePayer": "<facilitator-fee-payer>",
"receiverAuthorizer": "<server-close-authorizer>",
"withdrawDelay": 3600,
"tokenProgram": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
"minDeposit": "10000",
"memo": "invoice-123",
"recentBlockhash": "<recent-blockhash>",
"recentSlot": 341000000
}
}
4.2 Shared Wire Objects and Program Mapping
The wire format uses network-neutral x402 names even when the SVM program uses different instruction or account notation:
In this section, camelCase names identify x402 wire fields. Snake_case names identify the payment-channels program’s Rust account fields; generated clients may expose those program fields with language-specific casing.
| x402 wire field | Payment-channels program notation |
|---|---|
PaymentRequirements.extra.feePayer |
Channel.rent_payer and zero-share Channel.payee |
PaymentRequirements.extra.receiverAuthorizer |
No program field. Section 3. |
PaymentRequirements.extra.tokenProgram |
open.token_program / top_up.token_program; MUST equal the onchain owner of Channel.mint |
channelConfig.payer |
Channel.payer |
channelConfig.payerAuthorizer |
Channel.authorized_signer |
channelConfig.voucherSigner |
No program field; omitted or "client" means client mode, while "server" binds payerAuthorizer to PaymentRequirements.extra.operator |
channelConfig.receiver |
Sole DistributionEntry.recipient with bps = 10000; the Channel.payee implicit remainder is always zero |
channelConfig.receiverAuthorizer |
No program field; MUST equal PaymentRequirements.extra.receiverAuthorizer |
channelConfig.token |
Channel.mint |
channelConfig.withdrawDelay |
Channel.grace_period |
channelConfig.salt |
Channel.salt |
channelConfig.openSlot |
Channel.open_slot |
voucher.channelId |
VoucherArgs.channel_id |
voucher.maxClaimableAmount |
VoucherArgs.cumulative_amount |
voucher.expiresAt |
VoucherArgs.expires_at; MUST be 0 in this scheme |
channelState.balance |
Channel.deposit |
channelState.totalClaimed |
Channel.settled |
channelState.withdrawRequestedAt |
Channel.closure_started_at |
channelState.chargedCumulativeAmount |
Server-owned offchain cumulative charge |
ChannelConfig:
| Field | Type | Notes |
|---|---|---|
payer |
string | Client wallet and channel payer. MUST NOT equal feePayer, because the program requires distinct payer and payee accounts. |
payerAuthorizer |
string | Ed25519 voucher signer; maps to channel authorized_signer. In client mode it is client-controlled and MAY equal payer. In server mode it MUST equal extra.operator. It MUST NOT equal feePayer. |
receiver |
string | MUST equal payTo. |
receiverAuthorizer |
string | Required. MUST equal extra.receiverAuthorizer (section 3). Not a channel PDA seed or program account field. |
token |
string | MUST equal asset; maps to channel mint. |
withdrawDelay |
number | MUST equal extra.withdrawDelay; maps to channel grace_period. |
salt |
string | Decimal u64 channel salt. |
openSlot |
number | u64 slot encoded in open and used as a channel PDA seed. |
voucherSigner |
string | Optional. Omitted or "client" selects client mode; "server" selects server mode and MUST equal extra.voucherSigner. |
The client and facilitator MUST confirm extra.tokenProgram equals the onchain
owner of channelConfig.token; neither role may trust the server-provided value
without that check.
channelId is the program-derived address:
find_program_address(
[
"channel",
channelConfig.payer,
PaymentRequirements.extra.feePayer,
channelConfig.token,
channelConfig.payerAuthorizer,
u64(channelConfig.salt).to_le_bytes(),
u64(channelConfig.openSlot).to_le_bytes()
],
CANONICAL_PAYMENT_CHANNELS_PROGRAM_ID
)
For a new channel, the open instruction MUST encode:
salt == channelConfig.saltdeposit == deposit.amountgrace_period == channelConfig.withdrawDelayopen_slot == channelConfig.openSlotrent_payer == PaymentRequirements.extra.feePayerpayee == PaymentRequirements.extra.feePayerauthorized_signer == channelConfig.payerAuthorizermint == channelConfig.token- the distribution derived from
channelConfig.receiveras specified in section 4.1
BatchVoucher:
| Field | Type | Notes |
|---|---|---|
channelId |
string | Channel PDA (base58). |
maxClaimableAmount |
string | Cumulative authorized total in atomic units; maps to program cumulative_amount. |
expiresAt |
number | MUST be 0 (no voucher expiry). The field stays in the signed message for program compatibility; the forced-close grace period alone bounds the redemption window. |
signature |
string | Base58 Ed25519 signature by channelConfig.payerAuthorizer. |
The signed message is exactly:
0x56 0x01 || channelId || u64(maxClaimableAmount).le || i64(expiresAt).le
This is the payment-channels program voucher layout (VOUCHER_MAGIC,
channel_id, cumulative_amount, expires_at), 50 bytes total.
BatchAuthorization is the expiring bearer proof for server mode:
| Field | Type | Notes |
|---|---|---|
type |
string | MUST be "proof". |
channelId |
string | Channel PDA (base58). |
payer |
string | MUST equal channelConfig.payer. |
requestId |
string | Fresh opaque single-use request identifier. |
authorizedAmount |
string | Maximum charge in atomic units; MUST equal PaymentRequirements.amount. |
expiresAt |
number | Integer Unix seconds. The server MUST require now < expiresAt. |
signature |
string | Base58 payer signature over the authorization message below. |
The client signs exactly the concatenation of these bytes:
utf8("x402-batch-authorization-v2") ||
base58_decode(channelId) ||
base58_decode(payer) ||
base58_decode(extra.operator) ||
u16(len(utf8(requestId))).le || utf8(requestId) ||
u64(authorizedAmount).le ||
i64(expiresAt).le
Each decoded address MUST be exactly 32 bytes, and requestId MUST encode to 1
through 256 UTF-8 bytes. The proof authorizes one request up to
authorizedAmount for that channel, payer, and operator until expiresAt. It
MUST be handled as a bearer credential. Clients SHOULD set expiresAt no later
than their current time plus maxTimeoutSeconds and MUST issue a fresh proof
for each HTTP request. The request and amount bindings limit a leaked proof to
one bounded request; expiry limits how long it can be presented. None of these
fields revoke the operator’s onchain authority to sign vouchers for the channel.
CloseAuthorization:
| Field | Type | Notes |
|---|---|---|
validBefore |
number | Integer Unix seconds. The server MUST set it no later than its current time plus maxTimeoutSeconds; the facilitator MUST require now < validBefore <= now + maxTimeoutSeconds. |
signature |
string | Base58 Ed25519 signature by the channel’s bound receiver authorizer (section 3). Omitted on a delegated close; the facilitator authenticates the caller instead. |
The receiver authorizer signs the SHA-256 digest of this exact byte sequence:
UTF8("x402:batch-settlement:svm:close:v1") || 0x00 ||
u16(len(network)).le || UTF8(network) ||
programId[32] ||
feePayer[32] ||
channelId[32] ||
u64(maxClaimableAmount).le ||
i64(voucherExpiresAt).le ||
i64(validBefore).le
network is the canonical CAIP-2 identifier from PaymentRequirements;
programId is the canonical payment-channels program id for that network; and
feePayer, channelId, and the voucher fields are decoded to their canonical
binary forms. The length is the number of UTF-8 bytes in network. This domain
separation prevents the signature from authorizing another operation, network,
program deployment, facilitator, channel, voucher watermark, or expiry.
ChannelState:
| Field | Type | Notes |
|---|---|---|
channelId |
string | Channel PDA (base58). |
balance |
string | Current Channel.deposit ceiling in atomic units. |
totalClaimed |
string | Current onchain Channel.settled watermark. |
withdrawRequestedAt |
number | Channel.closure_started_at, or 0 when no forced close is pending. |
chargedCumulativeAmount |
string | Server-owned offchain cumulative actual charge. Present only when the response is authored by the server. |
4.3 Client PaymentPayload Variants
The client payload is a tagged union on payload.type. /verify accepts all
four variants. /settle accepts deposit and refund directly. The server
enriches refund with a CloseAuthorization before forwarding it as
specified in section 4.5. A voucher is accepted offchain by the server.
deposit opens a channel or tops up an existing channel and authorizes the
current request:
| Field | Type | Notes |
|---|---|---|
type |
string | "deposit" |
channelConfig |
ChannelConfig |
Full channel configuration. |
voucher |
BatchVoucher |
REQUIRED in client mode and absent in server mode. Cumulative authorization for the current request. |
authorization |
BatchAuthorization |
REQUIRED in server mode and absent in client mode. Expiring payer proof. |
deposit.amount |
string | Amount to deposit or top up in atomic units. |
deposit.transaction |
string | Base64 client-signed open or top_up transaction for the facilitator to validate, co-sign, and broadcast. Its message version MUST be one advertised in extra.transactionVersions (see Transaction versions). |
{
"x402Version": 2,
"accepted": {
"scheme": "batch-settlement",
"network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
"amount": "1000",
"asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"payTo": "<server-receiver>",
"maxTimeoutSeconds": 300,
"extra": {
"feePayer": "<facilitator-fee-payer>",
"receiverAuthorizer": "<server-close-authorizer>",
"withdrawDelay": 3600,
"tokenProgram": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
"recentBlockhash": "<recent-blockhash>",
"recentSlot": 341000000
}
},
"payload": {
"type": "deposit",
"channelConfig": {
"payer": "<client-wallet>",
"payerAuthorizer": "<client-voucher-signer>",
"receiver": "<server-receiver>",
"receiverAuthorizer": "<server-close-authorizer>",
"token": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"withdrawDelay": 3600,
"salt": "42",
"openSlot": 341000000
},
"voucher": {
"channelId": "<channel-pda>",
"maxClaimableAmount": "1000",
"expiresAt": 0,
"signature": "<base58-ed25519-signature>"
},
"deposit": {
"amount": "100000",
"transaction": "<base64-client-signed-open-or-top-up-transaction>"
}
}
}
voucher authorizes a steady-state paid request without an onchain
transaction:
| Field | Type | Notes |
|---|---|---|
type |
string | "voucher" |
channelConfig |
ChannelConfig |
Full channel configuration. |
voucher |
BatchVoucher |
New cumulative voucher. |
{
"x402Version": 2,
"accepted": {
"scheme": "batch-settlement",
"network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
"amount": "1000",
"asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"payTo": "<server-receiver>",
"maxTimeoutSeconds": 300,
"extra": {
"feePayer": "<facilitator-fee-payer>",
"receiverAuthorizer": "<server-close-authorizer>",
"withdrawDelay": 3600,
"tokenProgram": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
"recentBlockhash": "<recent-blockhash>",
"recentSlot": 341000000
}
},
"payload": {
"type": "voucher",
"channelConfig": {
"payer": "<client-wallet>",
"payerAuthorizer": "<client-voucher-signer>",
"receiver": "<server-receiver>",
"receiverAuthorizer": "<server-close-authorizer>",
"token": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"withdrawDelay": 3600,
"salt": "42",
"openSlot": 341000000
},
"voucher": {
"channelId": "<channel-pda>",
"maxClaimableAmount": "5000",
"expiresAt": 0,
"signature": "<base58-ed25519-signature>"
}
}
}
authorization is the server-mode steady-state request. It carries no
client-signed voucher and no transaction:
| Field | Type | Notes |
|---|---|---|
type |
string | "authorization" |
channelConfig |
ChannelConfig |
MUST select server mode. |
authorization |
BatchAuthorization |
Expiring, single-request, amount-bounded payer proof. |
{
"type": "authorization",
"channelConfig": {
"payer": "<client-wallet>",
"payerAuthorizer": "<resource-operator>",
"receiver": "<server-receiver>",
"token": "<mint>",
"withdrawDelay": 3600,
"salt": "42",
"openSlot": 341000000,
"voucherSigner": "server"
},
"authorization": {
"type": "proof",
"channelId": "<channel-pda>",
"payer": "<client-wallet>",
"requestId": "<opaque-request-id>",
"authorizedAmount": "1000",
"expiresAt": 1758215100,
"signature": "<base58-payer-signature>"
}
}
refund closes the channel (section 3). It is not a paid resource request,
so the resource handler MUST be bypassed, and the payload MUST NOT contain an
amount.
| Field | Type | Notes |
|---|---|---|
type |
string | "refund" |
channelConfig |
ChannelConfig |
Full channel configuration. |
voucher |
BatchVoucher |
REQUIRED in client mode. The server’s accepted cumulative amount (expiresAt MUST be 0). MUST be absent in server mode on the client-authored payload. |
authorization |
BatchAuthorization |
REQUIRED in server mode. authorizedAmount MUST be "0" (close intent). MUST be absent in client mode. |
transaction |
string | Omitted unless retrying after invalid_batch_settlement_svm_receiver_binding_unavailable (section 3). Base64 payer-signed request_close with extra.feePayer as the Solana fee payer. Its message version MUST be one advertised in extra.transactionVersions. |
{
"x402Version": 2,
"accepted": {
"scheme": "batch-settlement",
"network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
"amount": "1000",
"asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"payTo": "<server-receiver>",
"maxTimeoutSeconds": 300,
"extra": {
"feePayer": "<facilitator-fee-payer>",
"receiverAuthorizer": "<server-close-authorizer>",
"withdrawDelay": 3600,
"tokenProgram": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
"recentBlockhash": "<recent-blockhash>",
"recentSlot": 341000000
}
},
"payload": {
"type": "refund",
"channelConfig": {
"payer": "<client-wallet>",
"payerAuthorizer": "<client-voucher-signer>",
"receiver": "<server-receiver>",
"receiverAuthorizer": "<server-close-authorizer>",
"token": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"withdrawDelay": 3600,
"salt": "42",
"openSlot": 341000000
},
"voucher": {
"channelId": "<channel-pda>",
"maxClaimableAmount": "5000",
"expiresAt": 0,
"signature": "<base58-voucher-signature>"
}
}
}
4.4 SettlementResponse (in PAYMENT-RESPONSE)
| Field | Type | Required | Notes |
|---|---|---|---|
success |
boolean | yes | Whether acceptance or settlement succeeded. |
errorReason |
string | no | Omitted on success. |
payer |
string | no | Channel payer. |
transaction |
string | yes | Onchain signature for deposit/top-up/refund-initiation/cooperative-close/claim/settle operations; empty string for offchain voucher acceptance. |
network |
string | yes | CAIP-2 network identifier. |
amount |
string | no | Amount moved onchain; empty for voucher acceptance and claim. |
extra.commitmentId |
string | no | MUST be non-empty for voucher acceptance, e.g. channelId:maxClaimableAmount. |
extra.chargedAmount |
string | yes | Actual charge for this request. |
extra.channelState |
ChannelState |
no | Current channel snapshot. |
extra.voucher |
BatchVoucher |
conditional | REQUIRED in server mode. This operator-signed cumulative voucher is the receipt. |
Scheme-specific response fields are nested under extra.
A successful voucher-only response is:
{
"success": true,
"transaction": "",
"network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
"payer": "<client-wallet>",
"amount": "",
"extra": {
"commitmentId": "<channel-pda>:5000",
"chargedAmount": "2000",
"channelState": {
"channelId": "<channel-pda>",
"balance": "100000",
"totalClaimed": "3000",
"withdrawRequestedAt": 0,
"chargedCumulativeAmount": "5000"
},
"voucher": {
"channelId": "<channel-pda>",
"maxClaimableAmount": "5000",
"expiresAt": 0,
"signature": "<base58-operator-voucher-signature>"
}
}
}
4.5 Facilitator Interface
The standard x402 POST /verify and POST /settle request envelope contains
x402Version, paymentPayload, and paymentRequirements. For every request,
paymentPayload.accepted MUST equal paymentRequirements.
| Request field | Type | Required | Notes |
|---|---|---|---|
x402Version |
number | yes | MUST be 2. |
paymentPayload |
PaymentPayload |
yes | Its inner payload is one of the variants defined below. |
paymentRequirements |
PaymentRequirements |
yes | The selected requirements from the server’s PaymentRequired. |
POST /verify
paymentPayload.payload MUST be one of the client-authored deposit, voucher,
authorization, or refund variants in section 4.3. The facilitator validates the wire fields,
voucher signature, derived channel PDA, and onchain channel state and, for
deposit and refund, the client-signed transaction. For authorization, and
for a deposit whose channelConfig selects server mode, it MUST also verify
the BatchAuthorization itself: the payer signature over the section 4.2
message, channelId equal to the derived PDA, payer equal to
channelConfig.payer, authorizedAmount equal to PaymentRequirements.amount,
a non-empty requestId, and now < expiresAt. A facilitator used as a
standalone verifier therefore never accepts a server-mode request on the
resource server’s word alone. For refund, follow section 3. The channel
MUST be Open or still within its Closing grace period, and the payer’s
canonical return ATA MUST be healthy.
| Response field | Type | Required | Notes |
|---|---|---|---|
isValid |
boolean | yes | Whether the payload is valid. |
invalidReason |
string | no | Machine-readable reason when invalid. |
payer |
string | no | Channel payer when recoverable from the payload. |
extra.channelId |
string | no | Derived channel PDA. |
extra.balance |
string | no | Onchain Channel.deposit. |
extra.totalClaimed |
string | no | Onchain Channel.settled. |
extra.withdrawRequestedAt |
number | no | Onchain Channel.closure_started_at. |
A successful response is:
{
"isValid": true,
"payer": "<client-wallet>",
"extra": {
"channelId": "<channel-pda>",
"balance": "1000000",
"totalClaimed": "500000",
"withdrawRequestedAt": 0
}
}
The facilitator MUST return isValid: false with invalidReason when
verification fails. The server MAY verify ordinary voucher payloads locally
when its onchain snapshot is fresh; deposit and refund MUST be sent to the
facilitator.
POST /settle
Each wire type names the effect of the payload, not the payment-channels
instruction it invokes:
Wire payload.type |
Author | Effect | SVM program instruction |
|---|---|---|---|
deposit |
Client | Open a channel or add escrow. | open / top_up |
voucher |
Client | Accept an offchain authorization; no funds move. | None |
authorization |
Client | Ask the operator to accept and sign the next cumulative voucher; no funds move. | None |
claim |
Server | Advance accounting; no funds move to the receiver. | settle |
settle |
Server | Move earned funds to the receiver. | distribute |
seal |
Server | Finalize a Closing channel with the server’s latest voucher during the grace period; pays the receiver and returns unused escrow to the payer. |
settle_and_seal + sealed distribute |
refund |
Client, server-enriched | Section 3. | settle_and_seal + sealed distribute, or request_close |
The examples in this subsection show the inner paymentPayload.payload; the
caller MUST wrap each one in the standard request envelope defined above.
The deposit settle payload is the client variant from section 4.3. A voucher
is stored and answered by the server without a facilitator settlement. Every
server-authored payload identifies a channel by the same entry shape,
channelId plus channelConfig, and carries vouchers as BatchVoucher
objects; claim and settle wrap one or more such entries in an array (up to the
facilitator’s advertised capacity, four when it advertises none), while
seal acts on one channel. The server-authored or server-enriched variants
are:
| Payload | Field | Type | Notes |
|---|---|---|---|
| Claim | type |
string | "claim" |
| Claim | claims |
array | One to extra.maxClaimChannels (four when absent) channels to claim in one transaction. |
| Claim | claims[].channelId |
string | Channel PDA. |
| Claim | claims[].channelConfig |
ChannelConfig |
Full channel configuration. |
| Claim | claims[].voucher |
BatchVoucher |
Latest accepted voucher; its maxClaimableAmount becomes the new onchain settled watermark. expiresAt MUST be 0. |
| Settle | type |
string | "settle" |
| Settle | channels |
array | One to extra.maxSettleChannels (four when absent) channels to distribute in one transaction. |
| Settle | channels[].channelId |
string | Channel PDA. |
| Settle | channels[].channelConfig |
ChannelConfig |
Full configuration used to derive accounts, validate the channel, and reconstruct the distribution. |
| Seal | type |
string | "seal" |
| Seal | channelId |
string | Channel PDA. |
| Seal | channelConfig |
ChannelConfig |
Full channel configuration. |
| Seal | voucher |
BatchVoucher |
Latest accepted voucher; its maxClaimableAmount becomes the final settled watermark. expiresAt MUST be 0. |
| Seal | closeAuthorization |
CloseAuthorization |
REQUIRED (section 3). Binds this exact close. |
| Refund | type |
string | "refund" |
| Refund | channelConfig |
ChannelConfig |
Client-provided channel configuration. |
| Refund | voucher |
BatchVoucher |
Client mode: section 4.3. Server mode: injected by the server from stored operator state before settle. |
| Refund | authorization |
BatchAuthorization |
Server mode only on the client payload (section 4.3). |
| Refund | transaction |
string | Section 4.3. |
| Refund | closeAuthorization |
CloseAuthorization |
Added by the server (section 3). |
The server forwards a client-authored deposit unchanged. It MAY settle
voucher or authorization locally by storing the commitment and producing
the response in section 4.4. The facilitator validates channel and deposit
bindings for server-mode payloads, but the expiring payer proof is verified
by the authenticated resource server because it is a bearer credential for
that server; it is not a facilitator payment authorization.
For refund, the server MUST serialize processing with every paid request and
other close for the channel, and bypass the resource handler. In client mode it
MUST reject a voucher whose maxClaimableAmount differs from its accepted
cumulative amount. In server mode it MUST verify the payer authorization
(authorizedAmount "0"), MUST reject a client-supplied voucher, MUST inject
the stored operator voucher at the accepted cumulative, and MUST add a
CloseAuthorization over that amount before forwarding (section 3). Once a
sponsored request_close confirms, the server MUST reject new paid requests for
the channel:
{
"type": "refund",
"channelConfig": {
"payer": "<client-wallet>",
"payerAuthorizer": "<client-voucher-signer>",
"receiver": "<server-receiver>",
"receiverAuthorizer": "<server-close-authorizer>",
"token": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"withdrawDelay": 3600,
"salt": "42",
"openSlot": 341000000
},
"voucher": {
"channelId": "<channel-pda>",
"maxClaimableAmount": "5000",
"expiresAt": 0,
"signature": "<base58-ed25519-latest-voucher-signature>"
},
"closeAuthorization": {
"validBefore": 1785341100,
"signature": "<base58-server-close-authorization-signature>"
}
}
When the binding in section 3 is available, the facilitator MUST validate
closeAuthorization and the voucher against the channel. It MUST reject a
CloseAuthorization at or after validBefore. When
Channel.settled < voucher.maxClaimableAmount, it emits the
voucher’s Ed25519 precompile instruction immediately followed by
settle_and_seal with has_voucher = 1. When the values are equal, it invokes
settle_and_seal with has_voucher = 0; submitting an equal voucher onchain
would fail the program’s strict monotonicity check. Any other relationship
MUST be rejected. It then invokes sealed distribute in the same transaction,
verifies the confirmed onchain result, and returns the full amount
deposit - settled transferred to the payer.
When the binding is unavailable, the facilitator MUST validate and co-sign the
client’s request_close transaction with extra.feePayer,
broadcast it, and confirm that the channel entered Closing. It MUST NOT
fabricate or apply a final voucher. After Channel.closure_started_at + Channel.grace_period, the facilitator MUST schedule and attempt seal followed
by sealed distribute, returning deposit - settled to the payer. If another
permissionless crank completes either transition first, the facilitator MUST
treat the observed terminal state as success. Eligible PDA rent is recovered
by the same worker through reclaim; none of these asynchronous transactions
is part of the initial HTTP refund response.
The server initiates asynchronous accounting with a claim payload. Each
entry carries the full channel configuration needed to derive and validate the
channel plus the latest accepted voucher, whose signature builds the Ed25519
precompile instruction:
{
"type": "claim",
"claims": [
{
"channelId": "<channel-pda-1>",
"channelConfig": {
"payer": "<client-wallet-1>",
"payerAuthorizer": "<client-voucher-signer-1>",
"receiver": "<server-receiver>",
"receiverAuthorizer": "<server-close-authorizer>",
"token": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"withdrawDelay": 3600,
"salt": "42",
"openSlot": 341000000
},
"voucher": {
"channelId": "<channel-pda-1>",
"maxClaimableAmount": "5000",
"expiresAt": 0,
"signature": "<base58-ed25519-voucher-signature-1>"
}
},
{
"channelId": "<channel-pda-2>",
"channelConfig": {
"payer": "<client-wallet-2>",
"payerAuthorizer": "<client-voucher-signer-2>",
"receiver": "<server-receiver>",
"receiverAuthorizer": "<server-close-authorizer>",
"token": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"withdrawDelay": 3600,
"salt": "43",
"openSlot": 341000050
},
"voucher": {
"channelId": "<channel-pda-2>",
"maxClaimableAmount": "7000",
"expiresAt": 0,
"signature": "<base58-ed25519-voucher-signature-2>"
}
}
]
}
claims[] MUST contain at least one entry and at most extra.maxClaimChannels
entries, or four when the facilitator advertises no maxClaimChannels, so the
instruction pairs fit in one transaction without address lookup tables. A
facilitator MUST reject a claims[] longer than the capacity it advertises
with invalid_batch_settlement_svm_payload_type. The facilitator MUST process
every entry or fail the request; it MUST NOT silently truncate a batch. For each claim it emits an Ed25519
precompile instruction immediately followed by the program settle
instruction.
After claims advance onchain accounting, the server initiates distribution with
a settle payload:
{
"type": "settle",
"channels": [
{
"channelId": "<channel-pda-1>",
"channelConfig": {
"payer": "<client-wallet-1>",
"payerAuthorizer": "<client-voucher-signer-1>",
"receiver": "<server-receiver>",
"receiverAuthorizer": "<server-close-authorizer>",
"token": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"withdrawDelay": 3600,
"salt": "42",
"openSlot": 341000000
}
},
{
"channelId": "<channel-pda-2>",
"channelConfig": {
"payer": "<client-wallet-2>",
"payerAuthorizer": "<client-voucher-signer-2>",
"receiver": "<server-receiver>",
"receiverAuthorizer": "<server-close-authorizer>",
"token": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"withdrawDelay": 3600,
"salt": "43",
"openSlot": 341000050
}
}
]
}
channels[] MUST contain at least one entry and at most extra.maxSettleChannels
entries, or four when the facilitator advertises no maxSettleChannels. A
facilitator MUST reject a longer channels[] with
invalid_batch_settlement_svm_payload_type. The facilitator invokes distribute for
every channels[] entry in one transaction and MUST process every entry or
fail the request; it MUST NOT silently truncate a batch. It MUST confirm the
transaction onchain before returning success.
Once the payer has broadcast request_close, the channel is Closing and
program settle is unavailable: a claim for that channel, and a voucher or
authorization verification against it, MUST fail with
invalid_batch_settlement_svm_channel_closing. The server’s only way to
collect voucher value above the onchain settled watermark is a seal
payload, which the facilitator executes as payee before the grace period
ends. A server that sees that code SHOULD mark the channel closing and seal it
on its next redemption pass, and SHOULD stop once the grace period has passed.
It SHOULD set withdrawDelay comfortably above its claim cadence so the grace
period always covers a scheduled redemption:
{
"type": "seal",
"channelId": "<channel-pda>",
"channelConfig": {
"payer": "<client-wallet>",
"payerAuthorizer": "<client-voucher-signer>",
"receiver": "<server-receiver>",
"receiverAuthorizer": "<server-close-authorizer>",
"token": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"withdrawDelay": 3600,
"salt": "42",
"openSlot": 341000000
},
"voucher": {
"channelId": "<channel-pda>",
"maxClaimableAmount": "5000",
"expiresAt": 0,
"signature": "<base58-ed25519-latest-voucher-signature>"
},
"closeAuthorization": {
"validBefore": 1785341100,
"signature": "<base58-server-close-authorization-signature>"
}
}
The facilitator MUST authenticate a seal as specified in section 3, requiring
now < validBefore <= now + maxTimeoutSeconds. A key that merely appears in
the request MUST NOT be trusted, because a payer holding an older voucher could
otherwise freeze the watermark below the server’s latest. It MUST verify the voucher signature
against channelConfig.payerAuthorizer, confirm the channel is Closing with
now < closure_started_at + grace_period, and require Channel.settled <= voucher.maxClaimableAmount <= Channel.deposit. When settled < maxClaimableAmount it emits the voucher’s Ed25519 precompile instruction
immediately followed by settle_and_seal with has_voucher = 1; when equal it
invokes settle_and_seal with has_voucher = 0. It then invokes sealed
distribute in the same transaction, confirms it onchain, and reports
amount as the funds moved to payTo; the payer receives deposit - maxClaimableAmount in the same transaction. Any other state MUST be rejected
with invalid_batch_settlement_svm_close_state. A seal occupies the
("close", channelId, maxClaimableAmount) namespace of Phase 5.
Successful responses have operation-specific amount semantics:
Claim (amount is empty because no funds move):
{
"success": true,
"transaction": "<base58-transaction-signature>",
"network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
"amount": ""
}
Settle (amount is the total transferred to the receiver across the batch):
{
"success": true,
"transaction": "<base58-transaction-signature>",
"network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
"amount": "5000"
}
A facilitator MAY add per-channel confirmation under extra: for a claim,
extra.accepts[] entries of { "channelId", "totalClaimed" } giving the
confirmed onchain settled value the claim advanced each channel to; for a
settle, extra.channels[] listing the channel PDAs the transaction paid. A
server MUST NOT require either field. When they are absent, it reconciles the
settled and payout_watermark values by reading the channel account after
the transaction confirms; when they are present, it MAY use them only if they
name exactly the channels it submitted.
Seal (amount is the delta paid to the receiver; extra.channelState
carries the final watermark, and balance - totalClaimed went back to the
payer):
{
"success": true,
"transaction": "<base58-transaction-signature>",
"network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
"payer": "<client-wallet>",
"amount": "2000",
"extra": {
"channelState": {
"channelId": "<channel-pda>",
"balance": "100000",
"totalClaimed": "5000",
"withdrawRequestedAt": 0
}
}
}
Deposit (amount is the amount deposited or topped up):
{
"success": true,
"transaction": "<base58-transaction-signature>",
"network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
"payer": "<client-wallet>",
"amount": "100000",
"extra": {
"commitmentId": "<channel-pda>:1000",
"chargedAmount": "1000",
"channelState": {
"channelId": "<channel-pda>",
"balance": "100000",
"totalClaimed": "0",
"withdrawRequestedAt": 0,
"chargedCumulativeAmount": "1000"
}
}
}
Sponsored refund initiation (section 3; amount is empty because the grace
period may still be running):
{
"success": true,
"transaction": "<base58-request-close-transaction-signature>",
"network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
"payer": "<client-wallet>",
"amount": "",
"extra": {
"channelState": {
"channelId": "<channel-pda>",
"balance": "100000",
"totalClaimed": "5000",
"withdrawRequestedAt": 1785341100,
"chargedCumulativeAmount": "5000"
}
}
}
The facilitator MUST return the request-close signature after it confirms the
channel entered Closing; it MUST NOT claim that the refund amount has moved
until a later seal/distribute cleanup confirms it. For this unilateral path,
the server MUST mark the channel close-pending and reject further paid
requests. A later session MUST open a new channel with a new openSlot.
A cooperative refund (section 3) instead returns the close signature and
amount = deposit - settled.
GET /supported
The facilitator advertises its SVM transaction fee payer, the transaction
message versions it accepts, the most channels it redeems in one claim and
one settle transaction (maxClaimChannels, maxSettleChannels; see
Facilitator-built transactions),
and, when it runs
idle rent cleanup, the idle window maxIdleSecs (a positive integer number of
seconds; the reference implementation defaults to 604800, seven days). A
facilitator that accepts delegated closes also advertises
extra.receiverAuthorizer, the key it binds into those channels. The server
MUST copy feePayer, transactionVersions, maxClaimChannels,
maxSettleChannels, and maxIdleSecs into PaymentRequirements.extra, MUST
NOT author a claim or settle request with more entries than the copied
capacity (four when absent), then
set extra.tokenProgram from the selected asset’s verified mint owner. A
server SHOULD claim every channel well inside maxIdleSecs, because the
facilitator may close an idle channel at its onchain settled watermark and
any voucher value above it is then forfeited. The scheme resolves to the
protocol-default authorization payment flow, so extra.paymentFlow is
normally omitted; when either party emits it, the value MUST be
"authorization". The server MUST set extra.receiverAuthorizer (section 3):
its own signer when it self-manages closes, otherwise the facilitator’s
advertised key:
{
"kinds": [
{
"x402Version": 2,
"scheme": "batch-settlement",
"network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
"extra": {
"feePayer": "<facilitator-fee-payer>",
"transactionVersions": [0, 1],
"maxClaimChannels": 18,
"maxSettleChannels": 13,
"maxIdleSecs": 604800
}
}
],
"extensions": [],
"signers": {
"solana:*": ["<facilitator-fee-payer>"]
}
}
4.6 Corrective PaymentRequired
When the client’s cumulative amount does not match server state, the server
SHOULD return invalid_batch_settlement_svm_cumulative_amount_mismatch with a
signed recovery proof:
{
"x402Version": 2,
"error": "invalid_batch_settlement_svm_cumulative_amount_mismatch",
"accepts": [
{
"scheme": "batch-settlement",
"network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
"amount": "1000",
"asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"payTo": "<server-receiver>",
"maxTimeoutSeconds": 300,
"extra": {
"feePayer": "<facilitator-fee-payer>",
"receiverAuthorizer": "<server-close-authorizer>",
"withdrawDelay": 3600,
"tokenProgram": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
"recentBlockhash": "<recent-blockhash>",
"recentSlot": 341000000,
"channelState": {
"channelId": "<channel-pda>",
"balance": "100000",
"totalClaimed": "2000",
"withdrawRequestedAt": 0,
"chargedCumulativeAmount": "3000"
},
"voucherState": {
"signedMaxClaimable": "3000",
"expiresAt": 0,
"signature": "<base58-ed25519-voucher-signature>"
}
}
}
]
}
Before adopting the corrective state, the client MUST verify
voucherState.signature against its own payerAuthorizer key as an Ed25519
signature over the 50-byte voucher message of section 4.2, reconstructed from
the derived channelId, maxClaimableAmount = voucherState.signedMaxClaimable,
and expiresAt = voucherState.expiresAt. The client MUST reject the snapshot
when the signature does not verify or when
channelState.chargedCumulativeAmount exceeds voucherState.signedMaxClaimable.
Only after these checks does the client adopt chargedCumulativeAmount as its
new cumulative base and retry. When the server has no accepted voucher for the
channel, it omits voucherState and the client resynchronizes from onchain
state instead.
In server mode voucherState.signature is the operator’s, so it proves only
that the operator produced the snapshot, not that the client authorized it. A
server-mode client MUST additionally reject a corrective snapshot whose
chargedCumulativeAmount exceeds its own confirmed watermark plus the sum of
PaymentRequirements.amount for its requests on that channel whose outcome it
never observed. That sum is the most the client has agreed the operator may
have charged.
5. Phases
Phase 1 - Open or Top Up
The client builds an open transaction for a new channel or a top_up
transaction for an existing channel. The client signs as channel payer; the
sponsor later signs as transaction fee payer. For open, the sponsor also signs
as program rent_payer, because the payment-channels program debits SOL from
that account to fund the channel PDA and escrow ATA rent.
The client MAY use extra.recentBlockhash and extra.recentSlot to avoid an
RPC round trip while constructing the transaction. If either hint is stale, the
client MUST fetch a fresh value and rebuild the transaction. The facilitator
MUST reject an expired transaction blockhash and an openSlot outside the
program’s accepted window.
For open, the client MUST set payee = extra.feePayer, authorized_signer = channelConfig.payerAuthorizer, rent_payer = extra.feePayer,
mint = channelConfig.token, grace_period = channelConfig.withdrawDelay,
open_slot = channelConfig.openSlot, and deposit = payload.deposit.amount.
The sponsor adds its signature to transaction bytes constructed by the client.
Before signing, it MUST statically validate the complete compiled message under
the acceptance policy below. Simulation or eventual onchain failure MUST NOT
replace these checks because either occurs only after the sponsor’s signature
has authorized fee and, for open, rent expenditure. Smart-wallet wrappers are
not supported by this version of the scheme.
Client-supplied transaction acceptance policy
Transaction versions
Solana defines three transaction message formats: legacy, version 0 (adds
Address Lookup Tables), and version 1 (SIMD-0385: 4096-byte transactions that
carry the compute budget in the message header). The facilitator advertises
the versions it accepts as extra.transactionVersions in /supported, and the
server MUST copy that value into PaymentRequirements.extra.transactionVersions.
Entries MUST be the JSON integers 0 and 1 only. Unlike Wallet Standard
supportedTransactionVersions, the field never contains legacy, and a
string such as "1" is not a valid entry. A client or server MUST treat a field
containing any non-integer entry (a string, null, or "legacy") or any
integer other than 0 or 1 as invalid and fail closed with
unsupported_transaction_version. When the field is absent, the accepted set
is [0].
Legacy (unversioned) messages are deprecated. They are never advertised in
extra.transactionVersions and clients MUST NOT build them. A facilitator MAY
keep accepting legacy messages from existing clients for backward
compatibility; that tolerance will be removed in a future revision of this
scheme.
-
The client MUST intersect the advertised versions (
[0]when the field is absent) with the versions it and its signer support, then build the highest version in that intersection. It MUST fail withunsupported_transaction_versionwhen the intersection is empty. The client MUST NOT use Address Lookup Tables. -
The facilitator MUST reject a message whose version is outside the set it accepts, before inspecting any instruction, with
unsupported_transaction_version. The facilitator enforces its own accepted set; it does not readPaymentRequirements.extra.transactionVersions. -
A legacy or version-0 transaction MUST NOT exceed 1232 serialized bytes; a version-1 transaction MUST NOT exceed 4096 serialized bytes.
-
A version-1 transaction carries its compute budget in the message’s
TransactionConfigMaskand the config values that follow it (SIMD-0385). This spec names the values by the bits that carry them:- bits 0 and 1:
priorityFee, the total priority fee in lamports (u64). The two bits are set together; a transaction with only one set is invalid. - bit 2:
computeUnitLimit(u32). - bit 3:
loadedAccountsDataSizeLimit(u32). - bit 4: the requested heap size (u32).
SDKs expose these as a config object (for example
configon a@solana/kitmessage orTransactionConfigin solana-go). An unset value takes its minimum: an unsetpriorityFeeis 0, an unsetcomputeUnitLimitrequests 0 compute units, and an unsetloadedAccountsDataSizeLimitrequests 0 bytes of loaded account data. (The cost model still reserves 32 KiB of loaded account data for scheduling, but the transaction’s own budget is 0.) A transaction that leaves bit 2 or bit 3 unset therefore cannot execute its instructions, so a client-built version-1 transaction MUST set both. - bits 0 and 1:
-
The runtime ignores Compute Budget program instructions in a version-1 transaction: they configure nothing and execute as no-ops that still consume compute units. As an x402 sponsor rule, a client-built version-1 transaction MUST NOT contain them, and the sponsor MUST reject one that does.
-
A version-1
priorityFeeis evaluated against a per-compute-unit cap aspriorityFee * 1000000 <= maxPriorityFeeMicroLamports * computeUnitLimit. HeremaxPriorityFeeMicroLamportsis the maximum compute-unit price that applies toSetComputeUnitPricein a legacy or version-0 transaction:5000000microlamports per compute unit, or a stricter local sponsor policy. Both sides of the inequality MUST be evaluated with arbitrary-precision integers (or at least 128-bit unsigned integers), so that an oversizedpriorityFeecannot wrap and pass the check.
Message and signer rules
- The message version MUST be one advertised in
extra.transactionVersions(0when the field is absent; see Transaction versions), and the message MUST NOT contain Address Lookup Table lookups. The canonicalopenandtop_upforms fit in static account keys. - The transaction fee payer MUST equal
extra.feePayer. - The complete required-signer set MUST equal the distinct addresses in
{ channelConfig.payer, extra.feePayer }. No other signature may be required. - The payer signature MUST be present and valid before the sponsor signs. The
sponsor MUST add or replace only its own
extra.feePayersignature slot. channelConfig.payerandchannelConfig.payerAuthorizerMUST NOT equalextra.feePayer.- For
open,extra.feePayerMAY appear only in its canonicalrent_payerand zero-sharepayeeaccount positions. Fortop_up, it MUST NOT appear in the payment-channel instruction’s account list. In either form it MUST NOT be invoked as a program or used by any other instruction. channelConfig.receiverAuthorizerandextra.receiverAuthorizerMUST both be present and equal (section 3). The receiver authorizer is not a transaction signer or a payment-channel instruction account.
Top-level instruction layout
The top-level instructions MUST consist only of the following ordered regions:
- In a legacy or version-0 transaction, an optional Compute Budget prefix
containing at most one
SetComputeUnitLimitinstruction and at most oneSetComputeUnitPriceinstruction. If both are present, the limit MUST precede the price. A version-1 transaction carries its compute budget in the message config and MUST NOT contain this prefix. - Exactly one canonical payment-channels
openortop_upinstruction, matching the payload form selected by the decoded channel state. - A suffix containing exactly one SPL Memo instruction
(
MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr) and at most three Lighthouse instructions (L2TExMFKdjpN9kozasaurPirfHy9P8sbXoAN1qA3S95). The Memo data MUST beextra.memoas UTF-8 when supplied, or otherwise a random nonce of at least 16 bytes encoded as hexadecimal text. Anopensuffix also carries exactly one binding Memo from section 3. The signed transaction is subject to the version-specific size limit above.
No other top-level instruction or program is allowed. In particular, a
top-level associated-token-account instruction, arbitrary wallet program,
second payment-channel instruction, or duplicate setup instruction MUST cause
rejection. The payment-channels open instruction creates the escrow ATA
internally.
When present, Compute Budget instructions:
- MUST invoke
ComputeBudget111111111111111111111111111111; - MUST use only discriminator
2(SetComputeUnitLimit, exactly 5 data bytes) or discriminator3(SetComputeUnitPrice, exactly 9 data bytes); - MUST set a compute-unit limit no greater than
400000; and - MUST set a compute-unit price no greater than
5000000microlamports per compute unit.
A sponsor MAY apply stricter local compute-unit, priority-fee, or required-signature caps, but MUST NOT relax the absolute maxima above.
In a version-1 transaction the same caps apply to the message config values
instead (see Transaction versions): computeUnitLimit
(bit 2) MUST be set and MUST NOT exceed 400000, loadedAccountsDataSizeLimit
(bit 3) MUST be set, and priorityFee (bits 0 and 1, total lamports) MUST
satisfy priorityFee * 1000000 <= 5000000 * computeUnitLimit, evaluated without
overflow. A version-1 transaction that contains a Compute Budget instruction
MUST be rejected (an x402 sponsor rule; the runtime treats such instructions as
no-ops).
Lighthouse and Memo instructions are allowed only in the final suffix and
MUST NOT reference extra.feePayer as an account or as the invoked program. If
extra.memo is present, the facilitator MUST require exactly one Memo besides
the binding Memo and an exact UTF-8 data match. A sponsor MAY reject all optional Lighthouse
instructions, but MUST NOT reject the required Memo or admit instructions
outside this allowlist.
Canonical open
The open instruction MUST invoke the canonical payment-channels program, use
discriminator 1, contain exactly these 14 accounts in order, and contain no
remaining accounts:
| Position | Account role | Required binding | Required privileges |
|---|---|---|---|
| 0 | payer |
channelConfig.payer |
writable, signer |
| 1 | rent_payer |
extra.feePayer |
writable, signer |
| 2 | payee |
extra.feePayer |
read-only role |
| 3 | mint |
asset == channelConfig.token |
read-only |
| 4 | authorized_signer |
channelConfig.payerAuthorizer |
read-only role |
| 5 | channel |
voucher.channelId |
writable |
| 6 | payer_token_account |
Canonical ATA for payer, mint, and the mint’s token program |
writable |
| 7 | channel_token_account |
Canonical ATA for channel, mint, and the mint’s token program |
writable |
| 8 | token_program |
Onchain owner of mint; supported SPL Token or Token-2022 program |
read-only |
| 9 | system_program |
11111111111111111111111111111111 |
read-only |
| 10 | rent |
SysvarRent111111111111111111111111111111111 |
read-only |
| 11 | associated_token_program |
ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL |
read-only |
| 12 | event_authority |
Canonical event-authority PDA for the payment-channels program | read-only |
| 13 | self_program |
Canonical payment-channels program id | read-only |
The facilitator MUST fully decode the instruction data, reject truncated data or trailing bytes, and enforce the exact salt, deposit, grace period, open slot, single-recipient distribution, and PDA derivation specified in sections 4.1 and 4.2. It MUST confirm the payer has sufficient tokens for the deposit and the sponsor has sufficient SOL for the transaction fee plus the channel PDA and escrow ATA rent. The sponsor’s signature authorizes no other SOL or token debit.
Canonical top_up
The top_up instruction MUST invoke the canonical payment-channels program, use
discriminator 3, contain exactly these six accounts in order, and contain no
remaining accounts:
| Position | Account role | Required binding | Required privileges |
|---|---|---|---|
| 0 | payer |
channelConfig.payer |
writable, signer |
| 1 | channel |
voucher.channelId |
writable |
| 2 | payer_token_account |
Canonical ATA for payer, mint, and the mint’s token program |
writable |
| 3 | channel_token_account |
Canonical escrow ATA for channel, mint, and the mint’s token program |
writable |
| 4 | mint |
asset == channelConfig.token |
read-only |
| 5 | token_program |
Onchain owner of mint; supported SPL Token or Token-2022 program |
read-only |
The facilitator MUST confirm the decoded amount equals
payload.deposit.amount; the channel is Open; and every immutable channel
field and the committed distribution match the payload and requirements. It
MUST confirm the payer has sufficient tokens. In this form extra.feePayer
authorizes only the bounded transaction fee and MUST NOT be an instruction
account, authority, source, or delegate.
Solana message compilation deduplicates equal keys and unions privileges.
Therefore authorized_signer MAY be effectively writable and a signer when
payerAuthorizer == payer, and payee is effectively writable and a signer
because payee == rent_payer. Those prescribed unions MUST NOT cause rejection;
no other privilege escalation is permitted.
Before co-signing an open or top_up, the facilitator MUST simulate the exact
client-supplied transaction and confirm the eventual settlement path is usable
for the bound mint, token program, payer return ATA, treasury, and payTo
recipient ATA. It MAY use a facilitator-built composite simulation or targeted
account checks in addition to the setup simulation, but it MUST reject before
escrowing when a settlement account is missing, frozen, has the wrong owner or
mint, or is otherwise unusable under the program rules. After confirmation it
MUST re-read the channel and verify its status, deposit, mint, payer, payee,
authorized signer, rent payer, grace period, open slot, and distribution against
the payload and requirements before reporting settlement success.
The payer MUST provision its canonical return ATA. The resource server MUST
provision the canonical payTo recipient ATA before advertising these
requirements, and the payment-channel deployment operator MUST provision the
canonical treasury ATA for each supported mint and token program. A client MUST
NOT be required to create or fund an ATA owned by the resource server or
payment-channel treasury. When a required ATA is absent, a facilitator SHOULD
identify whether the payer, recipient, or treasury ATA is missing in its
settlement-simulation error.
Under the authorization flow, the open or top_up transaction is broadcast
by the post-handler /settle, after the statically validated deposit request
passes Phase 3 and the resource handler succeeds. After the transaction
confirms, the server records the channel in its ChannelStore.
Canonical refund request_close
The refund transaction MUST contain exactly one canonical payment-channels
request_close instruction for the PDA derived from channelConfig. It MAY
also contain the bounded Compute Budget prefix allowed above and a suffix with
at most three Lighthouse instructions and at most one Memo. The suffix uses the
same program and fee-payer-isolation rules as setup transactions; when
extra.memo is present, a supplied Memo MUST match it. The instruction MUST
use discriminator 5, contain exactly these two accounts in order, and contain
no remaining accounts:
| Position | Account role | Required binding | Required privileges |
|---|---|---|---|
| 0 | payer |
channelConfig.payer == Channel.payer |
read-only, signer |
| 1 | channel |
PDA derived from channelConfig |
writable |
The transaction MUST contain the payer signature and extra.feePayer as fee
payer; no other signer or address lookup table is permitted. No instruction or
program outside the prefix/suffix allowlist is permitted. The facilitator MUST
verify that the channel is Open or Closing, that the payer and fee-payer
bindings match the decoded channel, and that the transaction does not include
seal, settle_and_seal, distribute, or any token transfer. The sponsor
signature authorizes only the bounded network fee.
If the channel is Open, the facilitator MUST simulate the exact transaction,
reject a failed simulation, sign and broadcast it, and confirm that the channel
entered Closing before returning success. An expired blockhash or
out-of-window openSlot MUST be rejected; the client must rebuild and re-sign
with fresh values. If the channel is already Closing, the facilitator MUST
NOT rebroadcast; after revalidating the channel bindings, it returns the
observed initiation state as the idempotent result.
Phase 2 - Steady-State Request
In client mode, using the last authenticated PAYMENT-RESPONSE, the client sets
maxClaimableAmount = channelState.chargedCumulativeAmount + PaymentRequirements.amount, signs a new BatchVoucher, and sends a voucher
payload. In server mode it sends an authorization payload with an unexpired
payer proof binding a fresh requestId and PaymentRequirements.amount; it
does not propose a cumulative amount. A client enters server mode only for an
operator it has trusted out of band; when a 402 offers both modes for the same
resource, a client that holds such trust SHOULD prefer the server-mode accept
and every other client MUST fall back to the client-mode accept.
The client MUST keep at most one server-mode request in flight per channel so
the returned cumulative voucher can be evaluated against one exact local
watermark. A transport retry is a new x402 request and MUST use a new
requestId; applications requiring response recovery SHOULD use the payment
identifier extension. No onchain transaction is required in the request path.
The server verifies the authorization under Phase 3, reserves up to
PaymentRequirements.amount, then after the handler measures the actual charge
and stores an operator-signed voucher for that amount.
For a new channel, chargedCumulativeAmount starts at zero.
Phase 3 - Voucher Acceptance (before serving)
The server is the sole owner of per-channel offchain state. A separate facilitator, if used, remains stateless for ordinary voucher acceptance; it only needs onchain state plus a voucher when it later settles.
The server MUST serialize only reservation, final accounting, and close
transitions per channel. Server-mode resource handlers MAY execute concurrently
outside that short critical section. The server stores
chargedCumulativeAmount, signedMaxClaimable, the latest voucher signature,
the last time its mirrored onchain fields were refreshed, and server-mode
operations in a store keyed by (channelId, requestId). For every paid
request, the server MUST:
-
In client mode, verify the Ed25519 signature over the 50-byte voucher message using
channelConfig.payerAuthorizer. In server mode, verify the expiring payer proof usingchannelConfig.payer, requirenow < authorization.expiresAt, confirm its operator equalsextra.operator, and confirmchannelConfig.payerAuthorizer == extra.operator. In both modes the payer authorizer MUST equal the channelauthorized_signer. -
Confirm
channelIdmatches the PDA derived fromchannelConfigand the canonical payment-channels program id. -
Confirm the channel exists, is
Open, hasmint == channelConfig.token == asset,payee == extra.feePayer,authorized_signer == channelConfig.payerAuthorizer,rent_payer == extra.feePayer,grace_period == channelConfig.withdrawDelay == extra.withdrawDelay,open_slot == channelConfig.openSlot, and a distribution topayTomatching section 4.1.channelConfig.receiverAuthorizerMUST equalextra.receiverAuthorizer(section 3). Reject ifpayerorpayerAuthorizerequalsfeePayer. The server MUST obtain these fields from facilitator verification for everydepositandrefund. It MAY verify a steady-statevoucherorauthorizationlocally only while its mirrored onchain state is within a bounded freshness interval. A missing or stale snapshot MUST fall through to facilitator verification, and a successful verification MUST refresh the stored snapshot timestamp. For server-moderefund, verify the payer proof (authorizedAmount"0", freshrequestId, expiry) and reject any client-suppliedvoucherbefore reserving the close. -
No voucher expiry. The client MUST sign
expiresAt = 0, and the server and facilitator MUST reject any voucher with nonzeroexpiresAt. The forced-close grace period already bounds the redemption window after a payerrequest_close; a per-voucher expiry would add a second clock the server has to beat and could make an accepted voucher unredeemable while the channel is still open, after the resource has been served. -
Reserve capacity before running the handler. In client mode, require
maxClaimableAmount == chargedCumulativeAmount + PaymentRequirements.amountandmaxClaimableAmount <= channel.deposit. In server mode, reserve the advertised ceiling under the request’s single-use identifier and enforce:sum(activeReservation.ceiling) <= deposit - chargedCumulativeAmountA failed or canceled handler MUST release the reservation without charging. A close transition MUST NOT be accepted while any paid request remains reserved.
-
Enforce replay protection. Reject stale or already accepted client vouchers, and atomically create at most one server-mode operation for each
(channelId, requestId). Any duplicate operation, whether running or completed, MUST be rejected withduplicate_settlement(orinvalid_batch_settlement_svm_operation_ceiling_changedwhen its ceiling differs from the recorded one) and MUST NOT execute the handler. The scheme does not replay either the settlement response or the application resource body. -
Execute the resource handler. In client mode, the actual charge is the advertised amount. In server mode, after metering completes, choose an actual charge satisfying
0 <= chargedAmount <= PaymentRequirements.amountand setnewCumulative = chargedCumulativeAmount + chargedAmount. Only after handler success, atomically store the new cumulative amount and voucher, then returnPAYMENT-RESPONSEwithtransaction == "",extra.commitmentId,extra.chargedAmount,extra.channelState, and in server mode the operator-signedextra.voucher. The server-mode client MUST verify that voucher againstchannelConfig.payerAuthorizer, derivechargedAmount = voucher.maxClaimableAmount - localConfirmed, and require0 <= chargedAmount <= PaymentRequirements.amount. On any mismatch it MUST leave local state unchanged and resynchronize through a corrective 402. The server MUST durably bindrequestIdto the ceiling, actual charge, and resulting cumulative amount before acknowledging success.
Different operations MAY complete in any order. Each completion briefly locks the channel, adds its actual charge to the then-current watermark, signs that new cumulative value, commits the operation, and releases its reservation. Production implementations using separate channel and operation stores MUST make that transition atomic or provide equivalent recovery semantics.
For a deposit payload, the open or top_up transaction is broadcast by the
post-handler /settle, so the checks above run against the statically
validated transaction: for open, the step-3 bindings and the step-5 cap are
evaluated against the transaction’s instruction fields with
deposit = payload.deposit.amount; for top_up, against the existing onchain
channel with its deposit increased by payload.deposit.amount. The server
accepts the risk that a validated deposit transaction later fails to confirm;
because earlier vouchers were capped by the confirmed deposit, that exposure is
bounded by the single request’s advertised ceiling.
On any failure, the server returns 402 without serving the resource. If the
server has local channel state and a client-mode payload submits the wrong
cumulative amount, the server SHOULD return a corrective 402 with
accepts[].extra.channelState and accepts[].extra.voucherState, as shown in
section 4.6.
Phase 4 - Batched Redemption (out of band)
The server or facilitator redeems accumulated vouchers asynchronously, outside the request path:
- Claim (
type: "claim"). For each channel, build an Ed25519 precompile instruction for the latest stored voucher followed by programsettle. Pack as many channels as the facilitator’s advertisedmaxClaimChannelsallows (four in a legacy or version-0 transaction, eighteen in version 1, see Facilitator-built transactions) and do not silently drop channels from a full batch. Programsettleadvances onchainsettledto the voucher’s exactmaxClaimableAmount. - Settle (
type: "settle"). Call programdistributeto pay the newly claimed delta topayToand advancepayout_watermark. The channel remains open. - Seal (
type: "seal"). For a channel the payer has moved toClosing, the server submits its latest voucher with aCloseAuthorization; the facilitator, aspayee, applies it withsettle_and_sealand pays out with sealeddistributebefore the grace period ends. This is how a server collects voucher value above the onchain watermark once the payer walks. - Refund (
type: "refund"). Section 3.distributepays any remaining settled delta, returnsdeposit - settledto the payer, closes the escrow token account, and moves the channel to its cleanup state. - Rent cleanup. If final
distributeleaves the channel inDistributed, anyone can later callreclaimafter the open-slot window to return remaining PDA rent torent_payer.
Facilitator-built transactions and batching capacity
extra.transactionVersions governs only the client-supplied open, top_up
and request_close messages. The redemption transactions above are built and
signed by the facilitator alone, so their message version is the facilitator’s
choice:
- The facilitator MAY build any message version the network supports. A
version-1 transaction it builds MUST set both
computeUnitLimit(bit 2) andloadedAccountsDataSizeLimit(bit 3) of itsTransactionConfigMask(an unset value requests 0). It SHOULD set them to values sized for the batch rather than the runtime maxima. - Batch size MUST be derived from the serialized transaction (1232 bytes for legacy and version 0, 4096 bytes for version 1), the 64 static account keys a message may carry, and the 64 top-level instruction limit, never from a fixed count. A batch that does not fit is split, never truncated.
- The facilitator advertises the
claimandsettlecapacity of the message version it builds redemptions in asextra.maxClaimChannelsandextra.maxSettleChannels: positive integers no greater than what fits that version for every channel shape it accepts. A facilitator that builds redemptions as legacy or version 0 MUST NOT advertise more than4(it MAY omit the fields, which means4); one that builds them as version 1 MAY advertise up to the version-1 capacities in the table below. The facilitator checks a request’s length against the capacity it advertises, not againstPaymentRequirements.extra. If a request within that capacity still does not fit (an unusual channel shape), the facilitator MUST fail it rather than truncate it.
The table is informative. Per-channel costs are the bytes a further channel
adds to the message once the shared accounts (fee payer, programs, sysvars,
mint, payee and treasury token accounts) are already present; the shared
overhead is about 230 bytes for the claim shape and about 400 bytes for
distribute. Capacities are the binding limit of size, accounts and
instruction count. The distribute capacity assumes every channel in a
settle request pays the route’s payTo, as the facilitator requires: 14 fit
then, so 13 leaves a channel of margin. Were each channel to pay its own
recipient, only 11 would fit.
| Instruction | Per channel | Legacy / v0 (1232 B) | Version 1 (4096 B) | Binding limit for v1 |
|---|---|---|---|---|
settle claim: Ed25519 precompile + settle |
1 account, 2 instructions, ~205 B | 4 | 18 | size |
distribute (open or sealed) |
3 accounts with the shared payTo, 1 instruction, ~143 B |
5 | 13 | 64 account keys |
reclaim |
1 account, 1 instruction, ~38 B | ~26 | 62 | 64 account keys |
settle_and_seal + sealed distribute (refund) |
one channel per transaction | 1 | 1 | not batched |
open, top_up, request_close |
client-built, one channel per transaction | 1 | 1 | not batched |
In a devnet measurement, a four-channel claim serializes to 1,046 bytes as a legacy message and 1,070 bytes as version 1, executes in 1,696 compute units (Ed25519 verification is charged separately by the precompile), and costs 25,000 lamports. The base fee includes both transaction signatures and Ed25519 precompile signatures, so each additional channel adds a signature fee.
A read-only devnet getFeeForMessage check at slot 508336903 returned
25,000 lamports for four-channel v0 and v1 claims (one transaction signature
and four Ed25519 precompile signatures), and 95,000 lamports for an
18-channel v1 claim (one transaction signature and 18 precompile signatures).
These fee probes were not live settlement executions. At those full batch
sizes, packing 18 channels instead of 4 reduces transaction count by a factor
of 4.5, but reduces the base fee per channel from 6,250 to about 5,278
lamports, roughly 15.6%, excluding priority fees. Larger batches reduce
RPC/submission overhead and amortize the transaction-signature fee; the
per-channel precompile-signature fee remains. A version-1 batch packed at
4 channels has the same base fee as version 0.
The close authorization does not remove the facilitator’s independent permissionless lifecycle authority to finalize a forced close at the current onchain watermark under its published rent-recovery policy.
The payer exits through the payment-channel program’s forced-close path. The
server SHOULD claim with enough buffer before withdrawDelay can elapse after
the payer calls request_close. During the grace period, only the facilitator
as payee can apply a final voucher and seal cooperatively, and only when the
server has authenticated that close. After the grace period, anyone can call
seal; the payer can recover unspent deposit via withdraw_payer or sealed
distribute, and vouchers not yet claimed are forfeited by the server.
Idle abandon-close. Vouchers in this scheme never expire, so an Open
channel whose payer walks away would lock sponsored rent forever. A facilitator
that advertises extra.maxIdleSecs MAY, once an Open channel has seen no
facilitator-visible lifecycle activity for that many seconds, close it at the
current onchain settled watermark with settle_and_seal (has_voucher = 0), then distribute and reclaim. Facilitator-visible activity is any
deposit, claim or settle the facilitator processed for the channel;
offchain voucher acceptance on the server does not reset the clock. Closing at
the watermark forfeits every voucher the server has not claimed, so the server
MUST treat maxIdleSecs as a second clock it races against, and SHOULD claim
long before it elapses (the reference channel manager redeems on an interval
well inside the seven-day default). A facilitator MUST NOT idle-close earlier
than the window it advertised, and MUST NOT apply an idle policy it does not
advertise.
Phase 5 - Duplicate and Concurrent Operation Handling
The cumulative voucher and payment-channel state machine prevent duplicate token movement. Core x402 requests are single-shot; scheme state prevents a duplicate request from executing but is not an HTTP response-recovery protocol:
- Server-mode paid requests. The operation record is the authoritative
replay defense. Reuse of a running or completed
(channelId, requestId)MUST returnduplicate_settlement, orinvalid_batch_settlement_svm_operation_ceiling_changedwhen the reuse carries a different ceiling; it MUST NOT replay a settlement response or execute the handler. Applications that need to recover a resource body after a lost response SHOULD use the payment identifier extension. - Client-mode paid requests. The per-channel lock and charged watermark are the authoritative replay defense. The same authorization MUST NOT execute the resource handler more than once.
- Client-supplied transactions. For
depositandrefund, the facilitator SHOULD maintain a short-lived in-flight cache keyed by the exact serialized transaction or its first signature. Concurrent/settlecalls for the same transaction MUST be coalesced to one broadcast and one result or rejected withduplicate_settlement; they MUST NOT produce independent successful settlements. The entry MAY be evicted once the transaction’s blockhash is no longer valid. A refund retry afterrequest_closeconfirms MUST return the observedClosingstate rather than attempt a second transition. - Claims. Program
settlerequires a strictly increasing watermark, so the same claim cannot advance accounting twice. A facilitator MAY coalesce in-flight(channelId, maxClaimableAmount)claims to avoid a predictable second transaction failure; no durable duplicate cache is required. - Open-channel distributions.
distributeadvancespayout_watermarktosettled; a repeat cannot pay the same delta again. A facilitator MAY coalesce concurrent distributions for the same channel and observed watermark. - Refunds. The facilitator MUST coalesce retries of the same
request_closetransaction into one broadcast and one initiation result. OnceClosing, later retries return the observed channel state. Asealor server-enriched refund occupies the("close", channelId, maxClaimableAmount)namespace; the server and facilitator MUST cache that result throughcloseAuthorization.validBefore. - Reclaim. A channel can transition from
Distributedto deallocated only once. Concurrent reclaim attempts require no additional replay mitigation; later attempts observe an absent account or invalid status.
6. Asynchronous Recovery and Channel Discovery
Channel discovery is onchain for lifecycle and rent recovery. A client can
discover channels whose payer equals its wallet. A facilitator can discover
every channel for which it fronted rent by querying rent_payer or, equivalently
in this scheme, payee. The server still requires durable offchain storage for
the accepted charge watermark, unclaimed voucher, request correlation, and
replay state; those values cannot be reconstructed from channel accounts.
Implementations MAY retain a local lifecycle index, but a facilitator MUST be able to rebuild the onchain portion after local state loss, at startup, and periodically while it sponsors rent.
6.1 getProgramAccounts Discovery
Implementations MUST call getProgramAccounts against the canonical
payment-channels program for the selected network. This specification targets
the current 256-byte channel account layout, whose public-key offsets are:
| Channel field | Offset | Discovery use |
|---|---|---|
payer |
88 | Client deposit/channel recovery |
payee |
120 | Facilitator lifecycle recovery; equals feePayer in this scheme |
authorized_signer |
152 | Client voucher-authorizer recovery |
rent_payer |
216 | Facilitator rent recovery; equals feePayer in this scheme |
For example, a facilitator discovers channels for which it paid rent using a
base58-encoded key in a memcmp filter:
{
"encoding": "base64",
"commitment": "confirmed",
"filters": [
{ "dataSize": 256 },
{ "memcmp": { "offset": 216, "bytes": "<facilitator-fee-payer>" } }
]
}
The client uses the same filter with offset 88 and its payer key. A
facilitator MAY additionally filter payee at offset 120; because payee == rent_payer == feePayer, the two fields provide equivalent identities in valid
channels for this scheme.
Every returned account MUST be decoded with the supported payment-channels
codec. The implementation MUST reject an account whose owner, discriminator,
version, data length, or PDA does not match the selected program and decoded
channel fields. It MUST rederive the PDA from payer, payee, mint,
authorized_signer, salt, and open_slot before accepting the account.
Implementations MUST NOT reuse these byte offsets for an unsupported future
channel-account version.
6.2 Recovery Flow
Discovery and cleanup are asynchronous maintenance, not part of the paid HTTP request path. After startup or local state loss, a rent sponsor MUST:
- Query and decode matching channels, then upsert their addresses and statuses into a disposable local work queue.
- Refetch and revalidate a channel immediately before acting. If another worker or user changes its status, refetch and reclassify it instead of treating the stale transition failure as permanent.
- For an
Openchannel, wait until it has been idle for the advertisedextra.maxIdleSecs(Phase 4), giving the server that window to submit its latest voucher. The facilitator MAY then close at the current onchain watermark usingsettle_and_sealwithhas_voucher = 0, followed bydistributeand, when necessary,reclaim. A channel rediscovered after local state loss starts its idle clock at rediscovery. - For a
Closingchannel, schedule a recheck at the grace deadline. During the grace period, the facilitator MAY apply a final voucher supplied by the server when it has a valid cooperative authorization; afterward the normal permissionlesssealpath applies regardless of server availability. - For a
Sealedchannel, submit or relaydistribute. For aDistributedchannel, schedulereclaimafter the open-slot gate; recovered SOL always returns to the recordedrent_payer.
Onchain recovery does not recreate an unclaimed voucher or the server’s
chargedCumulativeAmount. If those records are lost, the server MUST NOT invent
a charge. The facilitator’s conservative recovery action is to close at the
current onchain settled watermark and return the remainder to the payer.
6.3 Reference Storage Boundaries
The reference implementation separates channel accounting from request operations. Its channel store owns the cumulative watermark and active reservations; its operation store provides the conceptual operations:
reserveOperation(channelId, requestId, ceiling)
completeOperation(channelId, requestId, actual, cumulative)
getOperation(channelId, requestId)
The included in-memory stores demonstrate the state machine and per-key locks. They are not production persistence. Implementers may replace them with a database, object store, distributed lock, HSM-backed signer, or another design, provided reservation and completion invariants survive process failure and concurrent workers. Retention, sharding, monitoring, and application-result storage are implementation concerns.
7. Error Codes
Standard x402 codes apply. The facilitator reports verification failures in
VerifyResponse.invalidReason and settlement failures in
SettlementResponse.errorReason; a resource server returning a corrective
PaymentRequired uses error. Scheme-specific codes are:
invalid_batch_settlement_svm_payload_type- payloadtypeis not valid for the current verify or settle operation.invalid_batch_settlement_svm_payment_flow-extra.paymentFlowis present and is not"authorization".invalid_batch_settlement_svm_token_program-extra.tokenProgramis not a supported SPL token program or does not own the selected mint.invalid_batch_settlement_svm_voucher_signature- signature invalid orchannelConfig.payerAuthorizerdoes not match channelauthorized_signer.invalid_batch_settlement_svm_channel_id_mismatch-channelIddoes not match the canonical PDA derivation.invalid_batch_settlement_svm_fee_payer_mismatch- channelpayeeorrent_payerdoes not matchextra.feePayer.invalid_batch_settlement_svm_receiver_authorizer_mismatch- the bound key in section 3 does not matchextra.receiverAuthorizer.invalid_batch_settlement_svm_receiver_binding_unavailable- the binding in section 3 is unavailable.invalid_batch_settlement_svm_delegated_unauthenticated- a delegated open, seal, or cooperative refund has no caller identity, or the identity does not match the one bound at open.invalid_batch_settlement_svm_close_authorization- close authorization is missing, malformed, expired, signed by a key other than the channel’s bound receiver authorizer, or does not bind the exact cooperative-close request.invalid_batch_settlement_svm_close_amount_unsupported- the"refund"wire payload contains anamount; this scheme supports only returning the full unused escrow.invalid_batch_settlement_svm_close_state- the channel cannot be closed, or a cooperative voucher does not equal server state or is behind the channel’s onchainsettledvalue.invalid_batch_settlement_svm_channel_closing- the payer has started a forced close, so programsettleis unavailable: aclaim,voucher, orauthorizationfor the channel is refused and the server retries with asealpayload inside the grace period.invalid_batch_settlement_svm_withdraw_delay_mismatch- channel grace period does not matchextra.withdrawDelay.invalid_batch_settlement_svm_withdraw_delay_out_of_range-withdrawDelayis outside900..=2592000seconds or is shorter thanmaxTimeoutSeconds.invalid_batch_settlement_svm_cumulative_amount_mismatch- corrective 402: client’s cumulative voucher does not match server state.invalid_batch_settlement_svm_cumulative_exceeds_deposit- voucher exceeds escrowed deposit.invalid_batch_settlement_svm_voucher_expiry- voucherexpiresAtis nonzero; this scheme requires non-expiring vouchers.invalid_batch_settlement_svm_setup_transaction- setup transaction fails the sponsor safety checks.invalid_batch_settlement_svm_settlement_simulation- setup or settlement-readiness simulation/checks failed before accepting the deposit.invalid_batch_settlement_svm_deposit_below_min_deposit- the server applies a local minimum-deposit policy and rejected a deposit below the advertisedextra.minDeposittarget.invalid_batch_settlement_svm_channel_state- confirmed channel state does not match the payload and challenge-bound requirements.invalid_batch_settlement_svm_refund_transaction- refund transaction is not a valid payer-signedrequest_closefor the derived channel or contains an unauthorized instruction.invalid_batch_settlement_svm_payout_attribution_ambiguous- asettletransaction confirmed, but the receiver’s token-balance delta cannot be attributed to the batch because a sealed payout in the same transaction returned escrow to a payer or treasury that aliasespayTo. The facilitator returns the confirmed signature with this reason instead of anamount; the server reconciles from onchain state.invalid_batch_settlement_svm_operation_ceiling_changed- a server-moderequestIdwas already reserved or completed with a different ceiling. The reuse is a duplicate operation: the handler did not run, and the earlier request’s outcome is not reported.duplicate_settlement- a server-moderequestIdwas already reserved or completed with the same ceiling, or the same client-supplied setup or refund transaction is already being settled.
8. Security Properties
- Bounded authorization. Onchain
settlerejects vouchers abovedepositand sets the exact cumulative maximum signed by the selected voucher signer. - Operator delegation is explicit and high trust. Selecting server mode
records
extra.operatoras the onchainauthorized_signer. The operator can therefore take up to the full deposit without another client signature or proof that it delivered service. The blast radius isdeposit, which may be much greater than onePaymentRequirements.amount; in client mode it is only the amount of the voucher the client chose to sign. Clients SHOULD prefer client mode. A client choosing server mode SHOULD use small, short-lived deposits and top up frequently. Over-provisioning is theft exposure in server mode, not merely temporarily locked client funds. - Server mode is opt-in per operator, never per 402. A client MUST NOT open
or pay into a server-mode channel because a
PaymentRequiredadvertisedvoucherSigner: "server". It MUST require an explicit, locally configured allowlist ofextra.operatorkeys. The grant is keyed by operator alone so it holds on every transport; nothing carried in the 402 body, and no transport-specific attribute such as a request origin, is a trust anchor. The grant SHOULD carry a maximum escrow the client will lock per channel under that operator, expressed per asset; the client MUST clamp every deposit hint, includingextra.minDeposit, to that cap, since the cap is exactly what a dishonest operator could take. Absent a grant the client MUST refuse the server-mode accept and SHOULD pay a client-mode accept for the same resource, network, and asset at no more than the refused amount when one is offered; servers advertising server mode SHOULD therefore also offer the same resource in client mode, typically at the request ceiling as a fixed price. Because the channel derivation bindsvoucherSignerandoperator, a server that later changes either cannot reuse a channel the client opened under the old terms; the new terms go through the same trust decision. - Bearer-proof confinement. The proof binds the channel, payer, operator,
single-use request identifier, amount ceiling, and expiry under a versioned
domain. It MUST NOT be logged or sent to any origin other than the authorized
resource server. The request binding limits a stolen proof to one bounded
request, while
expiresAtlimits how long it can be presented. Servers MAY additionally require an authenticated session, audience binding, or a per-request payer signature. Proof expiry does not remove the operator’s onchain signing authority; closing the channel is the only protocol-level revocation mechanism. - No redirection.
distribution_hashis fixed atopenand re-checked atdistribute; the derived distribution sends settled funds topayTo. - Authenticated vouchers. The wire
extra.feePayeraddress is recorded as programChannel.rent_payerand zero-shareChannel.payee. ProgramChannel.authorized_signerinstead comes from wirechannelConfig.payerAuthorizer, so the facilitator can close a channel but cannot advancesettledwithout a voucher from the selected signer. In server mode the payer’s channel-bound proof delegates that signing role. The committed distribution prevents payout redirection. - Authenticated cooperative closes. Section 3. The client voucher independently binds the final cumulative spend.
- Committed value is preserved at close. Both forced and cooperative close
paths pay any settled delta to
payTo, return exactlydeposit - settledto the payer, and close the escrow. Partial unused-escrow returns and channel reuse after close are not supported. - Facilitator rent recovery. Because the facilitator is channel
payee, it can runsettle_and_sealwithhas_voucher = 0, thendistributeandreclaim, without client or server cooperation. Abandoned channels cannot permanently lock sponsored rent. The idle window that triggers this is published asextra.maxIdleSecs, so the forfeiture it implies is a known, bounded term rather than an opaque facilitator policy. - Facilitator early-close exposure. Closing before the latest voucher is claimed freezes the onchain watermark and returns the remainder to the client. The server MUST bound its exposure by claiming promptly and SHOULD treat unclaimed voucher value as facilitator credit risk. During a client-initiated grace period, only the facilitator can apply the final voucher, and only after authenticating the server.
- No replay / no rollback. Server offchain watermark plus onchain
settledmonotonicity reject old vouchers. Server-mode request identifiers are single use; duplicates are rejected rather than replayed. Clients keep one request in flight per channel and only advance from their local confirmed watermark. A sponsoredrequest_closeis idempotent by that transaction. Cooperative closes use a separate operation namespace and a terminal onchain transition. - Bounded sponsor exposure. Client-supplied transactions have a static
instruction allowlist, exact signer and account layouts, no address lookup
tables, bounded compute-unit limit and price, and transaction simulation.
Outside the prescribed
openrent roles, the facilitator signature authorizes network fees only. - Client escape hatch.
withdrawDelayis fixed atopen; the payer can start forced close and recover whatever remains after the grace period. In server moderequest_closedoes not freeze the voucher watermark: during the grace period the operator can still submit a voucher up to the full deposit. Forced close therefore creates a race and is not protection against a malicious operator that already holds the onchain signing authority. The protocol bounds the delay to 15 minutes through 30 days and never shorter than the HTTP completion window. - Single settlement clock. Vouchers never expire (
expiresAtis fixed at0); the channel’s forced-close path alone bounds the commitment. The server beats one clock - the grace period after a payerrequest_close- and an accepted voucher can never become unredeemable while the channel is open. - Metered server pricing assumes an honest operator. In server mode the
server treats
PaymentRequirements.amountas a ceiling, reports an actual post-handler charge, and returns a cumulative voucher from which the client derives that charge. The ceiling, metering result, and voucher are all operator-controlled; the facilitator does not verify service delivery or pricing. Client verification is post-hoc detection and accounting, not prevention of overcharging. In client mode each fresh voucher increases the cumulative authorization by exactlyPaymentRequirements.amount.
9. Out of Scope
- A prescribed persistence backend, worker topology, or scheduling architecture for the required asynchronous maintenance.
- Smart-wallet-wrapped
openortop_uptransactions and simulation-based acceptance of arbitrary wallet programs. - Delegated passkey or secp256r1 voucher signers.