x402 (HTTP 402)

Overview

x402 brings payments back into the web’s native path: the request/response loop. Your API returns 402 Payment Required with a machine-readable hint. The client pays, presents a receipt, and retries.

A simple pattern: servers challenge with HTTP 402, clients pay and come back with a verifiable receipt. No accounts, no dashboards - just HTTP.

What is x402?

x402 standardizes the challenge and the proof so automated clients (including AI agents) can transact without out-of-band flows. HTTP 402 sat unused for decades. Today it’s being put to work for APIs and content: a first-class signal that payment is needed before the resource is returned.

Treat it like a capability, not a paywall - a programmable way to meter access fairly.

The Flow: Client → 402 → Pay → Receipt → Access

1. Client requests a priced resource.
2. Server responds 402 with a payment hint (amount, currency, reference).
3. Client pays using the hinted rail, obtains a receipt/proof.
4. Client retries with the receipt in headers or body.
5. Server verifies the receipt and returns the resource with standard 2xx.

curl -i https://www.originary.xyz/api/x402-demo

Minimal 402 Response

A compliant 402 response with a JSON payment hint:

HTTP/1.1 402 Payment Required
Content-Type: application/json; charset=utf-8
Cache-Control: no-store

{
  "detail": "Payment required to access this resource.",
  "payment": {
    "protocol": "x402",
    "amount": "0.10",
    "currency": "USDC",
    "reference": "demo-402-abc123",
    "instructions": "Pay using your client wallet and present a receipt in the follow-up request."
  }
}

Server Examples

Choose your stack and implement x402 in under 15 minutes:

• → Express (Node)

  Add 402 to your Express API

• → Next.js / Edge Runtime

  Route handlers with 402 challenges

• → Cloudflare Workers

  Tiny Worker returning HTTP 402

• → FastAPI (Python)(coming soon)

Receipts: Structure & Verification

A receipt ties the payment to your resource request. Keep two checks:

1. The cryptographic or gateway proof
2. Your own ledger mapping reference → entitlement

Return explicit errors for expired/insufficient proofs.

See Model Context Protocol (MCP), Agentic Commerce Protocol (ACP), and Agent-to-Agent (A2A) for receipt integration patterns.

x402 vs L402

L402 couples Lightning and macaroons for auth and payment in one flow. x402 is HTTP-native and rail-agnostic.

Choose L402 for Lightning-first ecosystems; choose x402 when you want chain/gateway flexibility and simple HTTP semantics.

Choosing Rails: x402 vs Arc vs Tempo

The right rail depends on your currency, fee model, and developer footprint. Start with what your customers already hold (e.g., stablecoins), then optimize for verification latency and dispute handling. We will maintain a running comparison as the space evolves.

Postman + OpenAPI

• Download OpenAPI: x402 demo
• Download Postman collection

Frequently Asked Questions