explainer

What is HTTP 402? Payment Required for agents and APIs

HTTP 402 Payment Required was reserved in 1997 for digital payments. It sat unused for decades. Agents calling paid APIs need a machine-readable way to learn that payment is required, and specifications such as x402 now use 402 for that.
Originary2 min read

An agent calling a paid API cannot fill in a checkout form. It needs the server to say, in a form software can read, that payment is required and how to make it. HTTP has had a status code reserved for that since 1997.

The history of HTTP 402

  • 1997. HTTP 402 defined in RFC 2068, marked as "reserved for future use" for digital payments.
  • 1997 to 2023. Status code sits unused while web payments evolve through separate channels.
  • 2024 and beyond. AI agents need machine-readable payment signals. HTTP 402 finally sees production use through layered specifications such as x402.

HTTP 402 is currently documented by MDN as nonstandard: reserved for future use with no agreed convention for how clients and servers exchange payment data. Specifications layered on top of 402 (such as x402) define their own headers and bodies above the bare status code.

Why HTTP 402 matters now

A person can read a pricing page and fill in a payment form. An agent needs the same information as structured data:

  • Clear signal. HTTP 402 unambiguously signals "payment required".
  • Payment instructions. Structured data: what to pay, how much, where.
  • Proof of payment. Receipt proving payment occurred.

How PEAC uses HTTP 402

PEAC Protocol builds on HTTP 402 with additional structure for AI access control, payments, and receipts. When a PEAC-enabled endpoint receives a request without valid payment:

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "type": "payment_required",
  "message": "Access requires payment",
  "payment": {
    "amount": "0.01",
    "currency": "USD",
    "methods": ["x402", "stripe"]
  },
  "policy_url": "https://example.com/.well-known/peac.txt"
}

Response fields explained:

  • Payment methods. x402 for crypto, Stripe for fiat.
  • Amount and currency. Clear pricing in machine-readable format.
  • AI policy URL. Link to crawling policy and usage terms.

x402: the payment extension

x402 is a specification layered on HTTP 402 that adds structured payment descriptions to 402 responses. Used with PEAC, the flow provides:

  • Payment negotiation. Agents can query acceptable payment methods.
  • Receipts. x402 carries its own payment artifacts; a PEAC record can reference them alongside the access decision.
  • Verification. Receipts can be verified at the domain's verify endpoint.

See the PEAC Protocol overview for the verifiable interaction-record format.

Testing HTTP 402

You can test a PEAC-enabled 402 endpoint with curl:

curl -i https://example.com/api/gated

# Response:
# HTTP/2 402
# content-type: application/json

Beyond payments: access control

In PEAC, a 402 response can also gate access on conditions other than payment:

  • AI bot policy. Require agents to comply with crawling policy.
  • Attribution. Require agreement to attribution terms.
  • Consent. Proof of user consent for training use.
  • Rate limiting. Premium access for paying agents.

Getting started

  1. Define your AI access policy with Originary Downloads.
  2. Add 402 responses to your API endpoints.
  3. Integrate x402 or Stripe for payment processing.
  4. Return signed receipts on successful payment.

See Add HTTP 402 to your API in 15 minutes for a step-by-step guide.

related