Skip to main content
PAYMENTS INTEGRATION

x402 (HTTP 402)

HTTP 402 commerce and x402 payments for machine-payable APIs

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 HTTP 402 challenge-and-proof flow so automated clients, including AI agents, can pay and access resources without out-of-band flows. Think of it as a programmable way to meter access fairly.

Getting Started with x402

Protect an API endpoint with a 402 challenge: return status 402 with amount, currency, and a reference ID. Clients pay, then retry with a verifiable receipt. Works with any payment rail and supports fully automated agent-to-agent payment flows.

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.
💡 Design tip

Keep the 402 payload small and explicit. Include a stable reference the server can match later.

Try it now:

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:

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.

Postman + OpenAPI

Frequently Asked Questions

What does HTTP 402 do here?

It signals that payment is required and supplies just enough machine-readable detail for a client to pay and retry.

Can I keep my existing auth?

Yes. 402 sits alongside your auth. You can charge only for specific routes or tiers.

Do I need stablecoins?

No. x402 is rail-agnostic. Stablecoins are common, but you can integrate any payment rail that issues a verifiable receipt.

Ready to implement x402?

Start with one of our stack guides above, or explore developer tools for x402 receipts and verification.

Start here