Learn / Spec

The x402 402 response, field by field

The 402 response is the price tag. Everything a client needs to pay is in it, and anything missing is a reason a client will give up.

The payment requirements

Where to name the facilitator

Use the root facilitator field and accepts[].extra.facilitator. Leave it out of accepts[].facilitator: that is not a v2 PaymentRequirements field, and because clients echo the accepted requirements back with the payment, a strict client can fail to match it.

A short example

{
  "x402Version": 2,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "10000",
    "payTo": "0x...",
    "maxTimeoutSeconds": 60,
    "extra": {"name": "USD Coin", "version": "2",
              "facilitator": "https://x402-agent-pay.com/facilitator"}
  }],
  "facilitator": "https://x402-agent-pay.com/facilitator"
}

Check any endpoint's 402 with our free endpoint report.

Common questions

What does amount 10000 mean in x402?

USDC uses 6 decimals, so 10000 base units is 0.01 USDC.

Should the payment terms be in the header or the body?

In x402 v2 the PAYMENT-REQUIRED header is the authoritative copy. A body is optional and should carry the same terms.

Why would a client refuse to pay a 402?

Common reasons are a v1-only response, an unsupported network or asset, a missing payTo, or a facilitator named in a field the client does not expect.

Keep reading

x402 v1 vs v2: what changedHow to accept x402 payments on your APIx402 payment refusal codes and fixesAll x402 guides
See what our facilitator supports
LearnDocsSettlement policyEndpoint report