x402 Payments

x402 is a specification for per-request machine payments: an HTTP response body that returns 402 Payment Required, names a price and an accepted rail, and resumes the request once the caller attaches a signed payment proof. It is a rail, not a policy layer. Chio supplies the policy: which agents can pay, for what, up to what cumulative amount, against which capability, and with which evidence kept in the receipt log. Together they produce an HTTP endpoint that accepts payment from an agent without a human in the loop and leaves behind a signed record of every transaction.

How x402 Works on the Wire

An x402 exchange is a two-request dance. 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": "1.0",
  "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": "..." }

What Chio Adds

Vanilla x402 is a payment protocol. It says nothing about 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 fills in exactly those gaps:

• 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-authorisation and budgets. Chio evaluates the upcoming payment against per-call and cumulative budgets from the Budgets & Metering layer. Exceed the limit and the call is denied at the policy boundary, not after the money is spent.
• 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, so the full financial path of any request reconstructs from the receipt log.
• 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; revocation short-circuits the rail.
• 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 authorisation 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 rail is abstracted.

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 },
  });
}

Status and Roadmap

• Today (alpha). Outbound authorisation, 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