Function

1) Actors and Roles

  • Client/Buyer (app, script, or agent): Calls your paid endpoint. On 402 Payment Required, it constructs a payment and retries the same request with verifiable proof. In x402, payment is encoded directly in the HTTP loop. Coinbase Developer Docs+1

  • Your Service (x402 Seller): Exposes a normal HTTP route but returns 402 with machine-readable payment requirements (amount, currency, recipient, expiry). After verification, it returns 200 OK with the resource. Coinbase Developer Docs

  • x402 Facilitator: A verification/settlement service you call to verify that the client’s onchain payment satisfies the requirements, and (optionally) to settle onchain without running your own node. Coinbase Developer Docs+1

  • Solana blockchain: Final settlement layer for USDC-SPL transfers used to satisfy the 402 challenge. Coinbase Developer Docs

2) The HTTP 402 Request Lifecycle (Step-by-Step)

  1. Initial request: The client calls your protected route, e.g., GET /v1/summarize?chars=2000.

  2. Payment challenge: Your service responds with HTTP 402 Payment Required, including structured payment requirements: price, SPL mint (USDC), destination address, expiry/nonce, and any facilitator hints. The 402 code is a long-standing, rarely used status explicitly intended for payment gating, which x402 standardizes for web use. MDN Web Docs+1

  3. Client payment (Solana): The client prepares and signs a USDC-SPL transfer that matches the requirements and broadcasts it to Solana (or passes the transaction data to the facilitator depending on integration). Coinbase Developer Docs

  4. Verify: Your service calls the facilitator’s /verify endpoint with the client’s payment header and your requirements. The facilitator checks chain state and confirms whether the transfer meets the contract (amount, recipient, token, freshness). GitHub

  5. Settle (optional): If you want the facilitator to handle submission/settlement flows, call its /settle API; otherwise, you can treat the onchain transfer as final once confirmed. Coinbase Developer Docs

  6. Serve content: If verified, you return 200 OK with the response payload and include a payment receipt (e.g., an X-Payment-Response header) for auditability and refunds if you support them. If verification fails, return another 402 describing what’s missing. Coinbase Developer Docs

3) Payment Requirements & Headers

x402 formalizes how sellers declare payments and how buyers prove them via headers. In practice, your 402 response embeds a compact, signed structure that includes amount, currency/mint (USDC-SPL), destination, valid-until, and any facilitator or nonce fields needed for replay protection. The client’s retry includes a payment header referencing the transaction and a proof the facilitator can validate deterministically. This makes paying “stateless” at the HTTP layer and avoids local sessions or bespoke checkout flows. Coinbase Developer Docs+1

4) Why Solana USDC-SPL for Settlement

Solana offers high throughput, low fees, and rapid finality, which are critical for pay-per-call economics and agent-driven use cases. USDC on Solana (SPL) is supported in the x402 Network & Token Support matrix, making it a first-class fit for the protocol without custom shims. For teams, this keeps the round-trip fast enough that “pay-then-retry” feels instantaneous. Coinbase Developer Docs

5) Operationalization with Layer2 Financial

After the facilitator verifies payment on Solana, Layer2 Financial handles the operational side:

  • Treasury & custody: USDC-SPL program wallets, multi-custody routing (e.g., segregated accounts), and reconciliation/monitoring so finance teams can audit flows.

  • Bank connectivity: ACH and Fedwire for inbound/outbound fiat, plus program settlement accounts when you want to sweep or fund card rails.

  • Card authorizations (optional): If you issue cards, JIT funding can top up authorizations from treasury in real time. These building blocks are covered in company materials (ACH Pull/Push, custody partners, and payout infra) and map cleanly to x402 receipts. Rail

6) Error Handling, Idempotency, and Retries

  • Idempotency: Treat verify/settle as idempotent via request IDs so your service is safe to retry on network hiccups. The facilitator and your server should accept duplicate notifications without double-serving content. Coinbase Developer Docs

  • Expired or underpaid: If the transfer is late or short, the facilitator returns failure; you respond with a fresh 402 detailing updated requirements. Coinbase Developer Docs

  • Observability: Correlate request IDs from client → facilitator → Solana transaction hash → response receipt for audit and refunds.

7) Security & Compliance Touchpoints

  • Header integrity: Sign the payment requirements you place inside 402 to prevent tampering.

  • Replay protection: Include nonces and expirations; facilitators validate freshness. Coinbase Developer Docs

  • KYT/monitoring: Run KYT on inbound Solana transfers if your risk policy requires it; reconcile receipts to treasury ledgers.

  • No-session design: Because x402 is HTTP-native, you avoid long-lived sessions or embedded keys in client apps.

8) Developer Workflow (Putting It Together)

  • Server: Add a middleware that, on access checks failing for “not yet paid,” emits a standards-conforming 402 with requirements. On success from verify, proceed to the handler and return 200 OK. Coinbase Developer Docs

  • Client: Use an x402-compatible library or a thin wrapper that can parse the 402, create a USDC-SPL transfer on Solana, and retry with a payment header. Coinbase Developer Docs

  • Facilitator: Integrate /verify (and /settle if desired) from the facilitator API. Third-party facilitators exist; Coinbase’s reference implementation is open source. GitHub+1

PreviousWhy x402?NextReferences

Last updated