x402 Payments

How x402 Works on the Wire

An x402 exchange uses two requests. The first request arrives without payment; the server responds 402 Payment Required with a structured body that names the price, the accepted settlement rail, and the recipient. The client forms a payment, signs it, and retries with an X-PAYMENT header. The server validates the payment proof, completes the request, and returns the response plus a settlement identifier.

# First request, no payment
GET /expensive-resource HTTP/1.1
Host: api.example.com

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "x402": "0.5",
  "price": { "amount": "0.01", "asset": "USDC" },
  "pay_to": "0xA11CE...",
  "networks": ["base-mainnet"],
  "nonce": "b41f-...-c8a9"
}

# Second request, with payment proof
GET /expensive-resource HTTP/1.1
Host: api.example.com
X-PAYMENT: base64url(<signed payment envelope>)

HTTP/1.1 200 OK
Content-Type: application/json
X-PAYMENT-RESPONSE: base64url(<settlement receipt>)

{ "data": "..." }

Chio's validation code currently supports x402 spec version 0.5. A bound x402 claim whose source_protocol_version is anything other than 0.5 is rejected as an unsupported source version, and a claim carrying a refunded status is a hard claim failure.

What Chio Adds

x402 is a payment protocol. It does not define which agent is allowed to pay, how much in aggregate, against what policy, or what receipt should be kept. Chio sits on both sides of the exchange and adds the following controls:

• Capability scoping. An agent must hold a capability that explicitly grants payments.x402.invoke at the relevant scope. Without it, the kernel denies before the payment is ever constructed, so no paid request leaves the box without authority.
• Pre-authorization and budgets. Chio evaluates the upcoming payment against per-call and cumulative budgets from the Budgets & Metering controls. A call that exceeds a limit is denied before payment is sent.
• Receipts on both ends. The paying side signs a pre-payment receipt; the receiving side emits a settlement receipt. Both are chained to the capability id. Receipt logs can therefore associate a payment with its capability.
• Revocation. A capability can be revoked mid-flight. Once revoked, the kernel refuses any further x402 payment even if the agent process still holds the token.
• Oracle-aware pricing. When the settlement currency differs from the budget currency, Chio consults Chainlink or Pyth to price the call, applies the configured FX margin, and attaches the evidence to the receipt.

Governed Flow

Integration Shape

Outbound (agent pays an x402 endpoint)

A Chio-fronted agent asks the kernel for authorization and a payment envelope before sending the second request. The kernel evaluates the capability, reserves against the budget, and returns a signed envelope the agent can place in the X-PAYMENT header.

import { chio } from "@chio-protocol/sdk";

const resp = await fetch("https://api.example.com/expensive-resource");
if (resp.status !== 402) return resp;

const quote = await resp.json();  // { price, pay_to, networks, nonce, ... }

// Ask chio to authorise and sign the payment under our capability.
const authorised = await chio.x402.authorise({
  capability_id: "cap-expense-line-item-019",
  quote,
});

if (authorised.decision !== "allow") {
  throw new Error("chio denied: " + authorised.reason);
}

return fetch("https://api.example.com/expensive-resource", {
  headers: { "X-PAYMENT": authorised.payment_header },
});

Inbound (service charges via x402)

On the receiving side, Chio validates the incoming payment envelope, confirms the signature matches the advertised price and recipient, watches settlement to the configured finality, and emits a signed settlement receipt. The application code sees only allow or deny verdicts. The application does not manage settlement directly.

import { chio } from "@chio-protocol/sdk";

export async function handler(req: Request): Promise<Response> {
  const paymentHeader = req.headers.get("X-PAYMENT");
  if (!paymentHeader) {
    return Response.json(quoteForThisRoute(), { status: 402 });
  }

  const verdict = await chio.x402.verify({
    payment_header: paymentHeader,
    expected_price: quoteForThisRoute().price,
    pay_to: serverConfig.payToAddress,
  });

  if (verdict.decision !== "allow") {
    return Response.json({ error: verdict.reason }, { status: 402 });
  }

  const data = await runTheExpensiveThing(req);
  return new Response(JSON.stringify(data), {
    status: 200,
    headers: { "X-PAYMENT-RESPONSE": verdict.receipt_header },
  });
}

Governed Interoperability API

x402 is not its own crate. It is one of four bounded payment-interop capabilities that ship inside chio-settle, all of which sit on top of governed dispatch and settlement truth and none of which replace signed receipts. The x402 projection is the one this page covers; the other three round out the machine-payment and gas-abstraction compatibility surface:

• x402 payment-requirement projection · build_x402_payment_requirements turns one governed settlement dispatch into an x402 payment-requirement object, bound to a facilitator URL, resource identifier, and an explicit accepted-token list.
• EIP-3009 gasless transfer · prepare_transfer_with_authorization prepares one transferWithAuthorization digest for review, with nonce dedup enforced through an Eip3009NonceStore so a nonce cannot be replayed.
• Circle nanopayment evaluation · evaluate_circle_nanopayment evaluates one nanopayment candidate, and only when operator-managed custody is declared explicitly.
• ERC-4337 paymaster compatibility · prepare_paymaster_compatibility evaluates one paymaster compatibility record, bounded by explicit reimbursement ceilings.

The boundary is deliberately narrow. The interop layer is not a generic payment-facilitator marketplace, does not perform implicit custody handoff, and does not offer universal gas sponsorship. It never mutates signed Chio receipts to reflect off-protocol facilitator state: the shipped code supports interoperability only.

Status and Roadmap

• Today (alpha). Outbound authorization, inbound verification, settlement on Base + USDC. Receipts tie x402 payments to their authorising capability.
• Near-term. Expanded settlement rails (Solana USDC, additional stablecoins), Stripe Shared Payment Token bridge, and a Coinbase-hosted facilitator adapter for operators who do not want to run their own settlement runtime.
• Later. Batched settlement (one on-chain tx amortised across many x402 calls) reconciled via merkle-proof release, aligning x402's per-call flow with Chio's existing batch anchoring path.

Next Steps

• Settlement · the on-chain layer where x402 payments actually land
• Chainlink Oracles · cross-currency pricing for x402 quotes outside the budget currency
• Budgets & Metering · per-agent spend envelopes that gate x402 calls
• Capabilities · the token format that authorises each payment