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.

Getting Started with x402

Implementing x402 in your API takes three steps: return a 402 response with payment details, accept payment receipts, and verify those receipts before granting access. The protocol is designed to work with any payment rail - from traditional payment gateways to cryptocurrency wallets to stablecoins.

Start by protecting a single API endpoint with a 402 challenge. When clients request that endpoint without payment, return status code 402 with a JSON payload containing the amount, currency, and a unique reference ID. Clients use this information to complete payment off-band, then retry the request with a verifiable receipt.

For AI agents and autonomous systems, x402 enables fully automated payment flows. Agents can parse the 402 response, execute payment through their configured wallet or payment provider, and retry the request - all without human intervention. This makes x402 ideal for agent-to-agent commerce, API marketplaces, and usage-based pricing models in the agentic economy.

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.

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