x402 Doctor

x402 Doctor

A free diagnostic for x402 seller endpoints. Point it at your paid endpoint and it performs the handshake a paying client would — a GET with no X-PAYMENT header — then reports what is wrong with the 402 challenge you answered with, and what to change.

Live: https://x402-doctor.tsharpe.workers.dev

curl -s -X POST https://x402-doctor.tsharpe.workers.dev/probe \  -H 'Content-Type: application/json' \  -d '{"url":"https://your-service.example/paid-endpoint"}'

Why seller-side

Buyer-side x402 is well served by the official SDKs. Seller-side is where people get stuck, because the failure happens inside a facilitator you cannot see into: your endpoint looks fine, the payment does not settle, and the error surfaces somewhere you do not control.

Every check carries a provenance field, so no finding has to be taken on trust:

• spec — the x402 specification requires it.
• observed (source) — we watched a real facilitator reject it, and the source is named.

What you get back

{  "target": "https://your-service.example/paid-endpoint",  "finalUrl": "https://your-service.example/paid-endpoint",  "status": "advisories",  "http": { "status": 402, "contentType": "application/json" },  "findings": [    {      "id": "challenge-cacheable",      "severity": "warn",      "title": "402 challenge is cacheable",      "why": "…",      "fix": "…",      "provenance": "observed (ours, 2026-08-15)",      "evidence": "cache-control: public, max-age=300"    }  ],  "checksRun": 16,  "bodyTruncated": false,  "bodyChecksSkipped": 0,  "bodySkipReason": null}

status is one of:

If the body was truncated or unparseable, body checks are skipped and the report says so (bodyChecksSkipped, bodySkipReason). A check that did not run is never reported as a check that passed.

The 16 checks

Also an MCP server

POST /mcp, stateless Streamable HTTP. Three tools:

What it deliberately does not do

• It never validates through a facilitator. Doing so would route your traffic through someone else's facilitator credentials. Every check here is derived from the challenge you actually returned.
• It never sends a payment, and never asks for a key, a seed, or a wallet.
• It does not judge networks it does not know. An unrecognised network name is an info note about the limits of this probe's list — not a claim that your network is wrong. Address-format rules apply only where the address format is known.

Limits worth knowing

• The body is read to a cap; past that, body checks are skipped and the report says so rather than guessing.
• Redirects are followed to a depth of 3, with the SSRF guard re-run on every hop.
• Rate limited to 20 requests/hour per IP and 300/hour overall, because the service fetches whatever URL it is given.
• The only thing stored is a per-IP request counter for that rate limit, which expires within two hours. No analytics, and probe targets are never logged.

Security posture, and the residual risks that were accepted rather than fixed, are documented in SECURITY.md.

Reading and running the source

cd doctornpm test          # 163 tests, no dependencies of any kind

Zero dependencies, runtime or dev — the suite is node --test. The rules are pure functions with no I/O; all network access lives in src/probe.js, which is also where the SSRF guard lives.

The hosted service above is free to use and needs no licence. The source is published for inspection and verification under the same terms as the rest of this repository: no licence granted at this time, all rights reserved. If you want to reuse or self-host it, ask.

Built by Twelve Permissions. Free, and unrelated to anything sold there.