Docs
x402
x402 is HTTP’s 402 Payment Required, put to work: a service names its price in the response, and the client pays and asks again. A budget payment is a standard x402 payment.
The 402 exchange
The agent
- 1Requests the URL.
- 3Checks the price against its budget, builds the payment and signs it with the agent key.
- 4Requests again, with the payment attached.
The service
- 2Answers 402 with its price, the mint and where to pay.
- 5Hands the payment to its facilitator.
- 7Answers 200 with the result and a receipt.
The facilitator
- 6Checks the payment, signs as fee payer, and settles it on Solana.
The SDK does steps 3 and 4 inside agent.fetch. Your code sees one call and one response.
What the service sends
The 402 carries one or more offers. The SDK reads them from the PAYMENT-REQUIRED header, or from the JSON body of a service on the first version of the protocol.
{
"x402Version": 2,
"resource": { "url": "https://api.example.com/search" },
"accepts": [{
"scheme": "exact",
"network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
"asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"amount": "5000",
"payTo": "<the service's wallet>",
"extra": { "feePayer": "<the facilitator's key>" }
}]
}
| Field | How the SDK uses it |
|---|---|
scheme | Must be exact: the price is paid in full, in one transfer. |
network | Solana mainnet, devnet or testnet, by name or by its chain id. It picks the RPC the budget is read from. |
asset | Must be the budget’s mint. Offers in other mints are passed over. |
amount | The price in base units (maxAmountRequired on the first version). 5000 is 0.005 USDC. |
payTo | The service’s wallet. The payment goes to that wallet’s token account for the mint. |
extra.feePayer | The facilitator’s key, which pays the network fee. The agent key is never the fee payer. |
extra.recentBlockhash | Optional. Without it the SDK takes a recent blockhash from the RPC. |
extra.memo | Optional, up to 256 bytes: the service’s own reference for the payment. Without it the SDK writes a random one, so two payments of the same price are never the same transaction. |
The payment’s shape
The payment is one version-0 Solana transaction with exactly four instructions, in the order the exact scheme asks for.
| # | Instruction | Value |
|---|---|---|
| 1 | Compute unit limit | 20,000 units |
| 2 | Compute unit price | 1 micro-lamport per unit |
| 3 | TransferChecked | The price, out of the budget account |
| 4 | Memo | The service’s reference, or a random one |
TransferChecked
source the budget account (owned by the budget, not the agent)
mint USDC
destination the service's account (payTo's token account for the mint)
authority the agent key (the account's delegate)
amount the price (from the 402)
decimals the mint's (checked by the token program)
The fee payer is the facilitator’s key, and the agent key signs as the transfer’s authority. The transaction leaves the agent with one signature on it and one missing: only the facilitator can complete and send it.
The token program lowers the key’s allowance by the amount, and refuses the transfer if the amount is above it. That refusal is the limit, enforced by the same program that holds every token balance on Solana.
How it travels
The signed transaction goes back to the service base64-encoded inside a small JSON envelope, in one request header.
| Protocol version | Request header | Receipt header |
|---|---|---|
| 2 | PAYMENT-SIGNATURE | PAYMENT-RESPONSE |
| 1 | X-PAYMENT | X-PAYMENT-RESPONSE |
The receipt on the service’s final response names the settled transaction’s signature. The SDK reads it to tell Breaker which origin the payment was for; your code can read it too, from res.headers.
What the facilitator checks
A facilitator verifies a payment by its outcome: the mint, the amount, the destination account. It leaves the source account free, so a transfer signed by a delegate, out of an account the agent does not own, settles on the facilitator’s default path. The facilitator pays the network fee, which is why an agent key needs no SOL.
The scheme is specified by the x402 Foundation: Exact Payment Scheme for SVM.
Streamed payments
A service that charges by use names one of x402’s two streamed schemes instead of exact. Both settle through the payment-channels program, CHNLxYvVA28MJP9PrFuDXccuoGXAx7jBacfLEkahyGsX: the payer locks a deposit in a channel, the service is paid out of it, and what it was not paid goes back to the payer. A budget is the payer. Its deposit counts against the period’s limit the moment the channel opens, so the limit holds for a stream exactly as it does for a call.
| Scheme | Sold as | The channel | Who signs the vouchers |
|---|---|---|---|
upto | A metered call: a ceiling per request, the amount used settled after. | One per call, opened for the ceiling. The service settles what the call used, and the rest comes back in the same claim. | The service. |
batch-settlement | A session: a price per call, many calls. | One per service, kept open. Each call adds a voucher for the new running total; the service claims them in batches. | The agent key. |
When a 402 holds no exact offer in the budget’s mint, the SDK takes a batch-settlement offer, then an upto one. Your code still makes one fetch; the SDK page has what it keeps between calls.
What the service sends
A streamed offer has the fields of an exact one, and these in extra:
| Field | How the SDK uses it |
|---|---|
amount | For upto, the ceiling of one call; for batch-settlement, the price of one call. |
extra.feePayer | The facilitator’s key. It pays the network fee and the rent of the channel, and it is the channel’s payee on chain. |
extra.receiverAuthorizer | The service’s key for the channel. On upto it signs the voucher for what the call used. |
extra.withdrawDelay | Seconds of grace between a request to close the channel and the moment it can be sealed. |
extra.minDeposit | Optional, batch-settlement: the least deposit the service takes for a session. |
extra.recentSlot | Optional. The slot the channel opens at; without it the SDK reads the finalized slot. |
extra.recentBlockhash, extra.memo | As for exact. |
The open
A budget cannot sign for itself, so its channel opens through Breaker: the agent key signs Breaker’s open_channel, and the program opens the channel by a cross-program call with the budget as payer and the budget account as the payer’s token account. A top-up is top_up_channel the same way.
| # | Instruction | Value |
|---|---|---|
| 1 | Compute unit limit | 200,000 units |
| 2 | Compute unit price | 1 micro-lamport per unit |
| 3 | open_channel | The deposit, out of the budget account into the channel’s token account |
| 4 | Memo | The service’s reference, or a random one |
| 5 | Memo | On a batch-settlement open only: the service’s receiverAuthorizer, bound to the channel |
The facilitator is the fee payer and the rent payer, and the agent key is the only other signer. Inside open_channel the program refuses a budget that is off or expired, and a deposit above what remains of the period’s limit or above the balance. The channel pays out to the offer’s payTo: the service’s wallet is the channel’s recipient, and its share is the whole of what is settled.
How it travels
In the same header as an exact payment. For upto, the payload is the channel and its open: channelId, deposit and maxAmount (both the ceiling), from (the budget), nonce, openSlot, authorizedSigner, openTransaction, expiresAt and validAfter. For batch-settlement, the first call carries type: "deposit" with the channel’s config, the deposit’s amount and signed transaction, and the first voucher; later calls carry type: "voucher" and a voucher alone.
voucher
channelId the channel
maxClaimableAmount the running total the service may claim, in base units
expiresAt 0: it never expires on its own
signature the agent key's ed25519 signature
Where the money goes
- The open moves the deposit from the budget account into the channel. The allowance falls by the deposit, and the period’s spend rises by it.
- The service settles what it is owed, up to the deposit, and the channel pays it to
payTo. - When the channel is sealed, Breaker’s
distribute_channelpays out what was settled and returns the rest to the budget account. If the deposit was counted in the current period, the unspent part goes back to the allowance in the same instruction; a deposit from an earlier period comes back as balance only, since the roll already began a fresh limit.
A metered call settles and closes at once: an upto call with a ceiling of 0.05 that used 0.012 pays 0.012 and returns 0.038. A session stays open while the agent uses it, and closes when the service seals it or after a request to close and its grace. The Budgets page has what each control does to an open channel.
The facilitator
A stock facilitator checks a channel open against one layout, a wallet signing the channel program’s open, and turns a budget’s away. Breaker’s facilitator is the reference x402 facilitator for Solana, serving exact, upto and batch-settlement, with one layout added: Breaker’s open_channel or top_up_channel in that place, every inner account pinned as the reference pins them, the payer the budget and its token account the budget account. A wallet’s open passes it unchanged.
https://facilitator.breaker.to
What services need
Nothing. A budget payment is a standard x402 payment. A service that takes USDC over x402 on Solana today takes a budget payment today, and the payment arrives whole. Solana carried 76% of x402 transactions in the four weeks to 2026-09-22 (Artemis, via Solana Compass, 2026-09-22).
| The service sells by | It needs |
|---|---|
exact | Nothing. Any facilitator settles a budget payment. |
upto | To name Breaker’s facilitator, https://facilitator.breaker.to. The stock upto seller scheme stays as it is. |
batch-settlement | To name Breaker’s facilitator, and to register @breaker/x402-seller’s scheme in place of the stock one, which checks the open itself before the facilitator sees it. |
A seller of sessions
npm i https://breaker.to/x402-seller/breaker-x402-seller-0.2.0.tgz
import { x402ResourceServer, HTTPFacilitatorClient } from '@x402/core/server'
import { BatchSvmScheme, MemoryChannelStore } from '@breaker/x402-seller'
const facilitator = new HTTPFacilitatorClient({ url: 'https://facilitator.breaker.to' })
const server = new x402ResourceServer(facilitator)
.register('solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp', new BatchSvmScheme({ receiverAuthorizer, store: new MemoryChannelStore() }))
It is the reference batch-settlement seller scheme of @x402/svm 2.31.0 with the budget’s open added to its checks. Its API, options, vouchers, claims and payouts are the reference’s own, and it takes a wallet’s session as before.
If you run a service
For services has what a budget payment looks like from your side, and how to read who paid.