x402 Integration

This section is advisory and non-prescriptive. It describes what the host protocol permits, read from its own primary artifact. Where this page and the host protocol disagree, the host is correct — build from its schema, not from an example here.

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). Servers advertise extensions in PaymentRequired and clients echo them in PaymentPayload; the host states the preservation rule in lower case and about the info payload rather than the map — the client must include at least the info received, and may append but cannot delete or overwrite existing info.

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/terms/v3.md"
    }
  }],
  "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 Offer and Receipt Extension defines server-signed artifacts (EIP-712 or JWS), which would be the natural home for a legal-context reference — and that path is not available today. Its EIP-712 Offer and Receipt types are closed structures with no free-form member, and the extension states that any change to its canonical types is a breaking change requiring explicit versioning; a reference added to an EIP-712 payload changes the type hash and fails verification against stock implementations. Carrying LCP inside a signed x402 artifact is Tier B.

extra is no longer wholly scheme-private. x402 reserves two key names inside PaymentRequirements.extra: assetTransferMethod and paymentFlow. "Clients and servers MUST interpret them as defined here rather than as opaque scheme-private fields." Other keys remain scheme-specific, so an LCP field in extra is still available — but a deployment writing there MUST NOT use a reserved name, and should expect the reserved set to grow. The top-level extensions map is the more durable carrier for exactly this reason: it is namespaced by extension identifier.

Settlement may precede resource delivery. paymentFlow takes three values: authorization (verify → resource → settle), upfront (settle → resource) and escrow (settle → resource → settle). A deployment that assumes settlement follows delivery — and therefore that a receipt-time reference is always available before the resource is served — is assuming authorization. Where the resolved flow is not authorization, accepts[].extra.paymentFlow MUST be present, so the flow is discoverable from the challenge; clients MUST NOT construct a payment for a flow they do not recognize.

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 §8.3 pattern selected for that primitive (see Appendix B).

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.