x402 Integration

HTTP-402 payment protocol — accepts[].extra and extensions blocks on the challenge, payload, and settlement receipt today; a registered legalContext extension identifier as forward work.

This section is advisory and non-prescriptive. The illustrations describe current possibilities and limitations rather than canonical shapes. The x402 Foundation is invited to publish authoritative LCP integration guidance for the protocol.

What it is

An HTTP-402-based payment protocol, originated by Coinbase and now stewarded by the x402 Foundation under the Linux Foundation (Technical Charter March 2026). Version 2 defines forward-compatible extension points: a per-requirement accepts[].extra object and a top-level extensions object, the latter carried on the PaymentRequired challenge, the PaymentPayload, and the SettlementResponse (the receipt). Each entry in the extensions map is keyed by an extension identifier and carries info (the extension's data) and schema (a JSON Schema for that data). Clients echo server-advertised extensions and MAY append to but MUST NOT delete or overwrite them.

Tier A — Available today

LCP fields ride inside accepts[].extra or the top-level extensions map:

{
  "x402Version": 2,
  "accepts": [{
    "scheme": "...",
    "network": "...",
    "extra": {
      "atrHash": "0x7f83b165...",
      "legalContextUrl": "https://example.com/.well-known/legal-context.json"
    }
  }],
  "extensions": {
    "legalContext": {
      "info": { "type": "sha256", "value": "0x7f83b165..." },
      "schema": { "$ref": "https://example.com/schemas/lcp-extension.json" }
    }
  }
}

A custom response header (e.g. X-LCP-Hash) is also viable on any HTTP-based rail, including v1 deployments that lack the extensions field.

Because the extensions object is also carried on the SettlementResponse, LCP can bind at receipt/execution time, not only at the proposal phase. The merged Offer-and-Receipt Extension defines a server-signed receipt (EIP-712 or JWS) returned in the settlement response, into which an atrHash or legalContext reference can be carried — giving the buyer a signed, integrity-bound artifact confirming the terms in force at settlement. This is Tier A today, with one caveat: the extension's forward-compatibility guidance treats unknown payload fields as unsupported rather than interpreted, so an in-payload reference rides verifier pass-through until a typed slot is standardized (Tier B below).

Tier B — Forward work

Registering a canonical legalContext extension identifier — with a published schema — once x402's canonical extension architecture is standardized, rather than relying on an ad-hoc key in the extensions map, would give parsers standardized handling across implementations. This is a standardization step, not a protocol change: the carrier already exists on both the proposal and the receipt.

Limitations

The extra and extensions blocks are HTTP-layer carriers — they do not, by themselves, commit the value to the settlement transaction. On-chain binding depends on the chosen settlement primitive and the binding pattern selected for that primitive.

Steward invitation

The x402 Foundation is invited to publish authoritative guidance on placement of atrHash inside extra, the extensions map, and the Offer-and-Receipt receipt, and on the relationship between HTTP-layer carriers and on-chain binding patterns.