Documentation · How-to

How do I check that an x402 endpoint actually works?

Call the endpoint with no payment header and read what comes back. A working x402 endpoint returns 402 Payment Required with a parseable accepts array naming a scheme, network, asset, payTo address and amount. That check is free and proves the endpoint can describe a price; only a small payment that settles and returns the paid content proves it works. For how often endpoints fail these checks, see the two datasets linked below.

The checklist

  1. Right request. Use the documented method, path and body. A GET to a POST-only route returns 405, not a challenge.
  2. Status is 402. 200 means the content is free or unprotected; 401/403 means an auth wall rather than x402; 404/405/5xx mean you are not testing payment yet.
  3. Body is JSON with an accepts array (some v2 servers also send the challenge in a header). Empty or non-JSON bodies cannot be parsed by any client.
  4. Each entry is complete: scheme, network, asset, payTo, and an amount (maxAmountRequired in v1, amount in v2).
  5. Values are sane: payTo is a well-formed address you expect, the asset is a real token on that network, and the amount is a plausible per-call price in the token’s smallest unit.
  6. Parses with a stock client. Feed the body to the client library you intend to use (see below).
  7. Settled test payment. With a dedicated wallet and a small balance, sign one offer, retry, confirm on-chain settlement to the advertised payTo, and confirm a substantive response follows.

Probe without paying

Steps 1–6 need no wallet and no funds. A plain request is enough:

curl -i -X GET https://example.com/paid/endpoint

Inspect the status line and the body (and response headers, for v2 servers that carry the challenge there). Do not attach a payment header. The request-and-retry cycle is described in x402 explained, and the x402 quickstart shows a full paid call.

Common malformed-402 failure modes

  • Wrong status. The paid route returns 200, 401, 403, 404 or 405 instead of 402.
  • No usable body. Empty, HTML, or non-JSON content on a 402.
  • Empty or missing accepts. The challenge exists but offers nothing to sign.
  • Empty-string fields. For example an empty asset, which strict parsers reject.
  • Missing v1-required fields such as description, mimeType or resource.
  • Network naming the client does not know, including CAIP-2 ids sent to a v1-only client.
  • Non-x402 responder. A 402 status with a body in some other payment format.
  • Unreachable host. DNS, connect or TLS failure before any status.

We recorded how these classes occur across advertised endpoints in the x402 payable endpoints dataset and the x402 client-compatibility census. Both are point-in-time probes (October 2026) of ERC-8004-registered endpoints; read their method notes for populations and caveats before quoting any figure.

How clients differ

x402 has two body shapes in the wild. v1 bodies use short network slugs (base), a maxAmountRequired string and several required descriptive fields. v2 bodies use CAIP-2 network ids (a standard chain-ID format; eip155:8453), an amount field, and a top-level resource object. A client built for one shape may reject the other, and parsers differ in strictness (per-entry versus whole-body validation). The same endpoint can therefore be payable for one library and unusable for another. Our census write-up compares legacy v1, v2 and Python parsers on the same bodies.

What this doesn’t prove

A valid challenge is a claim about price, not a guarantee of delivery. It does not show that verification and settlement will succeed, that the response will be correct, or that the seller will behave the same tomorrow. For agent-level checks (registration, reachability, ownership) see how to check if an ERC-8004 agent is reachable and payable. Keep first payments small.

FAQ

How do I check an x402 endpoint without paying?

Send the request the endpoint documents (correct method, path and body) with no payment header. A working x402 endpoint answers HTTP 402 and a machine-readable body listing what it accepts. Read the body, do not sign anything, and you have tested the discovery half of the protocol for free.

What should a well-formed x402 402 response contain?

An accepts array with at least one entry. Each entry names a payment scheme, a network, an asset (token), a payTo address, and an amount, plus a protocol version. v1 bodies use maxAmountRequired and short network names such as base; v2 bodies use amount and CAIP-2 network ids such as eip155:8453. The payTo should be a well-formed address and the amount a plausible per-call price.

Why does my x402 client reject a 402 response that looks valid?

Usually a version or schema mismatch: a v1-only client rejects v2 bodies (CAIP-2 network strings, renamed or missing fields), and strict parsers reject empty-string fields or non-JSON bodies. Our published client-compatibility census records which parser accepted each observed body, so you can see the failure classes.

Does a 402 response prove an endpoint works?

No. A 402 shows the endpoint can describe a price. It does not show that a signed payment will verify, that settlement will succeed, or that a useful response follows. Only a small payment that settles on-chain and returns the paid content proves the full path.

Is it safe to send a test payment?

Treat it as spending real money: use a dedicated wallet holding a small balance, check the payTo and amount against what you expect, and start with the cheapest endpoint. Never sign an offer you have not read.