x402 Integration¶

LedgerFlow is designed as a pure extension to the x402 payment protocol. It adds authorization without changing any x402 semantics.

The Golden Rule¶

Merchant servers speak x402 only. LedgerFlow data travels strictly as x402 extensions. Settlement rail details remain inside the Facilitator.

x402 Responsibility Boundaries¶

What x402 Handles¶

• Payment challenge and response flow
• Transport headers and payload structure
• Payment verification and settlement contracts
• Merchant-agent interoperability surface

What LedgerFlow Handles¶

• Warrant format definition
• Proof-of-authorization format
• Signer identity and warrant signature verification
• Authorization constraints against x402 quote and request context
• Cacheable warrant digests and local replay protection
• Normalized authorization decision for x402 middleware

What the Facilitator Handles¶

• Map x402 payment requirements to actual settlement rails
• Talk to blockchains, exchanges, custodians, or traditional gateways
• Payment verification and settlement execution
• Return normalized x402 settlement results

Extension Key¶

LedgerFlow data lives under the x402 extension namespace:

extensions["ledgerflow"]

This is the only surface area where LedgerFlow touches x402. The core PaymentRequired, PaymentPayload, and HTTP headers remain standard x402.

Challenge Extension¶

When the merchant returns 402 Payment Required, it includes a LedgerFlow challenge extension inside the x402 response body.

{
  "extensions": {
    "ledgerflow": {
      "version": "lfx402/v1",
      "challenge_id": "01HV7W8M7BX3Q6P0WJ7T5QK1V2",
      "proof_binding": "accepted+request",
      "warrant_transport": "inline_or_digest_ref",
      "required_subject_kinds": ["signer", "payment_subject"],
      "nonce_bytes": 16
    }
  }
}

This does not change x402 semantics. It tells the client how to satisfy the extra authorization requirement.

Response Extension¶

When the agent sends the payment response, it keeps the standard x402 payload and adds LedgerFlow data under the same extension key.

{
  "accepted": { "...": "standard x402 accepted payment requirement" },
  "payload": { "...": "standard x402 payment payload" },
  "extensions": {
    "ledgerflow": {
      "version": "lfx402/v1",
      "challenge_id": "01HV7W8M7BX3Q6P0WJ7T5QK1V2",
      "warrant": {
        "encoding": "lfw1+cbor",
        "digest": "sha256:8a5a...",
        "inline_b64": "base64url..."
      },
      "proof": {
        "encoding": "lfpop1",
        "created_at_ms": 1774502400123,
        "nonce_b64": "tR4Q7Y3qZ9GxwY6l9cYkQQ==",
        "request_hash": "sha256:5d2d...",
        "accepted_hash": "sha256:f321...",
        "signature": {
          "alg": "ed25519",
          "value_b64": "..."
        }
      },
      "subject": {
        "signer": {
          "alg": "ed25519",
          "key_b64": "..."
        },
        "payment_subject": {
          "kind": "facilitator_account",
          "value": "binance:uid:12345678"
        }
      }
    }
  }
}

Verification Flow¶

1. Merchant receives request with x402 PaymentRequired response
2. Merchant x402 middleware extracts extensions["ledgerflow"]
3. LedgerFlow verifier:
   a. Verifies warrant signature
   b. Verifies proof signature
   c. Checks warrant validity window
   d. Checks audience scope
   e. Checks all constraints against request context
   f. Verifies proof binds to exact selected accepted object
   g. Verifies proof binds to current HTTP request
   h. Checks replay protection
4. Returns normalized authorization decision
5. x402 middleware proceeds with settlement if authorized

What the Merchant Never Needs to Know¶

The merchant never needs to know:

• Whether settlement happens on Ethereum, Solana, or via Binance
• What the payment subject identifier means
• What chain the agent's wallet is on
• How the Facilitator routes payments
• Any details about the underlying rail

The merchant sees x402. The merchant verifies x402 + LedgerFlow authorization. The Facilitator does the rest.

Multi-Rail Settlement¶

The same merchant API, the same x402 flow, different settlement rails:

The merchant never changes its code. The Facilitator abstracts all rail complexity.

See Also¶

• Protocol — Wire format details
• Facilitator — Settlement routing architecture
• Quick Start — End-to-end integration example