x402 Payment Required — how to make your site agent-ready

What it is

x402 revives HTTP 402 Payment Required (in the spec since 1997, never used) as the canonical agent payment handshake. An agent requests a resource, the server responds with a 402 whose body describes the accepted payment methods and amounts. The agent pays (often via USDC on L2 rails) and retries.

Backed by the x402 Foundation (Cloudflare + Coinbase, 2026).

Remediation Prompt

I want to improve my site's agent readiness. Please implement the following fix for x402 Payment Required across our codebase.

Instructions:
Please fix the x402 Payment Required issue on my site so it is agent-ready.

How we test it

We can't drive payments in a scan. We look for signals of support:

GET / with X-402-Capable: 1 header → watch for X-402-Supported in response.
Look for a /.well-known/x402.json descriptor (community convention).
Probe a representative paid-resource URL if one is listed in /.well-known/x402.json.

Pass Warn Fail Matrix

Condition	Status	Score
`/.well-known/x402.json` exists + valid schema + references an endpoint that returns 402 on probe	pass	1.0
`/.well-known/x402.json` exists but the probe endpoint returns non-402 (500, 404)	warn	0.4
Only a response header hint, no descriptor	warn	0.3
Nothing detected	fail	0.0

Sub Tests

id	Weight	Pass when
`descriptor-present`	0.5	`/.well-known/x402.json` parseable JSON
`endpoint-402`	0.5	One of the listed endpoints returns 402 with a valid body

Remediation Prompt

If you sell something an agent should buy (API credits, articles, data), add x402 support.

1. Publish /.well-known/x402.json listing paid resources and accepted assets:
    {
      "version": "1.0",
      "resources": [
        {
          "url": "https://example.com/premium/report.pdf",
          "price": { "asset": "USDC", "chain": "base", "amount": "0.50" },
          "description": "Premium quarterly report."
        }
      ],
      "receiver": "0x…"  // your receiving address
    }

2. On requests to a paid resource without proof of payment, respond:
    HTTP/1.1 402 Payment Required
    Content-Type: application/x402+json
    X-402-Version: 1.0
    Body:
    { "price": { "asset":"USDC","chain":"base","amount":"0.50" }, "payTo":"0x…", "nonce":"…", "expiresAt":"…" }

3. Verify inbound payments (on-chain settlement) before serving the resource on retry.

Use a library like @x402/server for Node if available.

References

Test Fixtures

pass-descriptor-and-402.json
warn-descriptor-but-no-402.json
fail-404.json

← Previous Check

WebMCP