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

  1. 1Requests the URL.
  2. 3Checks the price against its budget, builds the payment and signs it with the agent key.
  3. 4Requests again, with the payment attached.

The service

  1. 2Answers 402 with its price, the mint and where to pay.
  2. 5Hands the payment to its facilitator.
  3. 7Answers 200 with the result and a receipt.

The facilitator

  1. 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>" }
  }]
}
FieldHow the SDK uses it
schemeMust be exact: the price is paid in full, in one transfer.
networkSolana mainnet, devnet or testnet, by name or by its chain id. It picks the RPC the budget is read from.
assetMust be the budget’s mint. Offers in other mints are passed over.
amountThe price in base units (maxAmountRequired on the first version). 5000 is 0.005 USDC.
payToThe service’s wallet. The payment goes to that wallet’s token account for the mint.
extra.feePayerThe facilitator’s key, which pays the network fee. The agent key is never the fee payer.
extra.recentBlockhashOptional. Without it the SDK takes a recent blockhash from the RPC.
extra.memoOptional, 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.

#InstructionValue
1Compute unit limit20,000 units
2Compute unit price1 micro-lamport per unit
3TransferCheckedThe price, out of the budget account
4MemoThe 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 versionRequest headerReceipt header
2PAYMENT-SIGNATUREPAYMENT-RESPONSE
1X-PAYMENTX-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.

SchemeSold asThe channelWho signs the vouchers
uptoA 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-settlementA 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:

FieldHow the SDK uses it
amountFor upto, the ceiling of one call; for batch-settlement, the price of one call.
extra.feePayerThe facilitator’s key. It pays the network fee and the rent of the channel, and it is the channel’s payee on chain.
extra.receiverAuthorizerThe service’s key for the channel. On upto it signs the voucher for what the call used.
extra.withdrawDelaySeconds of grace between a request to close the channel and the moment it can be sealed.
extra.minDepositOptional, batch-settlement: the least deposit the service takes for a session.
extra.recentSlotOptional. The slot the channel opens at; without it the SDK reads the finalized slot.
extra.recentBlockhash, extra.memoAs 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.

#InstructionValue
1Compute unit limit200,000 units
2Compute unit price1 micro-lamport per unit
3open_channelThe deposit, out of the budget account into the channel’s token account
4MemoThe service’s reference, or a random one
5MemoOn 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

  1. 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.
  2. The service settles what it is owed, up to the deposit, and the channel pays it to payTo.
  3. When the channel is sealed, Breaker’s distribute_channel pays 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 byIt needs
exactNothing. Any facilitator settles a budget payment.
uptoTo name Breaker’s facilitator, https://facilitator.breaker.to. The stock upto seller scheme stays as it is.
batch-settlementTo 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.