x402 Payments

HTTP 402 exchange

The server uses HTTP 402 to request payment. In x402 V2, PAYMENT-REQUIRED carries the requirements, PAYMENT-SIGNATURE carries the retry's payment payload, and PAYMENT-RESPONSE carries the settlement response. The values are Base64-encoded JSON. The exchange below is illustrative, with symbolic payloads; the x402 HTTP documentation defines their schemas.

GET /v1/quote?sku=sku-301 HTTP/1.1
Host: pricing.larkfield.example

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: <Base64 PaymentRequired JSON>

GET /v1/quote?sku=sku-301 HTTP/1.1
Host: pricing.larkfield.example
PAYMENT-SIGNATURE: <Base64 PaymentPayload JSON>

HTTP/1.1 200 OK
PAYMENT-RESPONSE: <Base64 SettlementResponse JSON>
Content-Type: application/json

{ "sku": "sku-301", "price": "140.00", "currency": "USD" }

V1 used X-PAYMENT and X-PAYMENT-RESPONSE, with x402Version: 1; V2 uses x402Version: 2. The protocol migration guide covers the change. These public wire versions are distinct from the source-version literal that Chio's offline claim validator accepts.

Inbound payment claims

For the receiving direction, Chio ships an offline claim validator; it parses no payment headers and builds no 402 Payment Required response. It checks an external.x402.payment.v1 subject inside a proof envelope for a matching source version, four SHA-256 digests, a transaction passport reference that matches the envelope, an order id, network, asset, a non-zero amount, a status of authorized or settled, and a payment receipt reference bound into the envelope.

The validator accepts the source-version literal 0.5. A bound x402 claim whose source_protocol_version is any other value is rejected as an unsupported source version, and a claim carrying a refunded status is a hard claim failure.

Governed interoperability API

x402 has no crate of its own. It is one of four bounded payment-interop capabilities in chio-settle, each built on governed dispatch and settlement truth, with signed receipts staying the record:

• x402 payment-requirement projection. build_x402_payment_requirements turns one governed settlement dispatch into an x402 payment-requirement object, bound to a facilitator URL, a resource identifier, and an explicit accepted-token list.
• EIP-3009 gasless transfer. prepare_transfer_with_authorization prepares one transferWithAuthorization digest for review, and an Eip3009NonceStore keeps each nonce single-use.
• Circle nanopayment evaluation. evaluate_circle_nanopayment evaluates one nanopayment candidate, 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.

Each function projects, prepares, or evaluates one record for an external system. The layer runs no payment-facilitator marketplace, takes no implicit custody handoff, and offers no universal gas sponsorship. Off-protocol facilitator state never changes a signed Chio receipt.

Where the payment code lives

The caller never assembles a payment envelope. Authorization, budget reservation, adapter dispatch, and receipt signing happen inside the kernel, so the caller uses the same capability, intent, and verdict as any other tool call. The payment-specific parts live in the four chio-settle::payments functions above and in chio-kernel::payment::X402PaymentAdapter. The ACP adapter carries one path per operation:

pub struct AcpPaymentAdapter {
    base_url: String,
    authorize_path: String,
    capture_path: String,
    release_path: String,
    refund_path: String,
    settlement_state_path: String,
    bearer_token: Option<String>,
    http: ureq::Agent,
}