The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the X402 Doctor listing page.
Diagnoses why an x402-payable endpoint's payment flow is broken, without needing a funded wallet.
Paste a URL (web app) or run x402-doctor <url> (CLI, CI) and get back exactly which check failed, why, and how
to fix it. Every check traces back to a real bug hit while shipping
PlainText and
Ichimoku Signal.
▶ Watch the 70-second explainer (with voice and captions): diagnosing a broken endpoint, the pre-payment check for agents, and the daily Trust Index.
▶ New: the paid fix in 70 seconds: for $0.05 the Doctor hands you the medicine, the exact code that fixes each problem for your stack, in the browser or as JSON for agents.
| Group | Check | Catches |
|---|---|---|
| 402 challenge | returns-402 | No 402 for GET or POST (tries both, or --method) |
protocol-version, challenge-header | v1 vs v2, missing x402Version, challenge in the wrong header, undecodable header | |
envelope-body-mirror | Header-only challenge (@x402/express sends {}), header and body disagreeing | |
| MCP (payment per tool call) | mcp-server | When the URL answers no 402 but speaks MCP (Streamable HTTP, JSON or SSE, with or without a session): initialize and tools/list without payment |
mcp-paid-tools | No tool description says it is paid (x402, USDC, a price), so agents can't tell | |
mcp-payment-required | One unpaid tools/call per paid-looking tool (at most 2; explicitly paid tools first — "Paid …" or a price / "via x402" in the title; never tools that call themselves free, destructive tools, or write tools unless explicitly paid). A free answer warns only for an explicitly paid tool, otherwise it is info: the x402 payment requirement in the tool result with isError: true (as @x402/mcp), or an HTTP 402 with PAYMENT-REQUIRED instead (payable over HTTP, not by @x402/mcp clients), a JSON-RPC error, a tool that answers for free, or example arguments refused before the payment step (publish one valid call as _meta.examples to avoid that). The requirement then gets the payment-option, settlement and wallet checks below | |
mcp-payment-text, mcp-payment-structured | The requirement only in structuredContent (the x402 MCP transport requires JSON text in content[0]), or only as text (structuredContent preferred) | |
| Payment options | accepts[i]-scheme, -network | Missing scheme; legacy names like base / solana:mainnet instead of CAIP-2 |
accepts[i]-payto, -asset | Invalid EVM/Solana addresses; asset that is not USDC, or USDC of another network (e.g. Base Sepolia USDC on Base) | |
accepts[i]-amount | Decimal dollar amounts ("0.02") instead of atomic units, zero or non-integer amounts | |
accepts[i]-extra | Solana without extra.feePayer (clients throw "feePayer is required"), EVM without the EIP-712 name/version | |
| Resource | resource-url | http:// resource URL on an https:// endpoint (Express behind a TLS proxy without trust proxy) |
resource-metadata | Missing description / mimeType | |
| Settlement | solana-payout-account | Solana payout wallet without a token account for the asset: every settlement fails on-chain |
solana-wallets | Solana settled by PayAI, which rejects Phantom (Lighthouse instructions before the transfer) | |
| Who can pay | wallets | Per wallet (MetaMask, Coinbase Wallet, Rabby, Phantom, Solflare, Backpack, x402 agents): the networks where payment works and where it fails, and why. Also in the JSON report as wallets |
metamask-site-scan | Only with METAMASK_SCAN=on (off by default: the endpoint has no published API or licence). MetaMask's site scanner (Blockaid) blocks the domain (e.g. "wallet drainer"): MetaMask users can't open the site or pay in the browser. With how to report a false positive. Agents are not affected | |
evm-payto-eoa | EVM payout wallet is a regular wallet (EOA): MetaMask's Blockaid check may flag the payment signature as "a deceptive request". Info, with how to get it cleared | |
| Discovery | bazaar, bazaar-output | Missing or invalid Bazaar declaration, output example not matching its schema |
bazaar-replay | The declared example request not answering 402, so the Bazaar cannot index it | |
openapi-present, openapi-title, openapi-guidance | Missing /openapi.json, info.title, info.x-guidance | |
well-known | /.well-known/x402 missing (info), unreadable (resources as URLs or objects with a url are both read), or listing resources on another host than the one checked (built from the request Host header, it keeps pointing crawlers at an old domain). A platform address such as *.onrender.com pointing at its own domain is fine | |
bazaar-listing | Where the CDP Bazaar lists this route (same path, same payTo): under this origin, not yet, or only under another host. The Bazaar keeps the URL the payer used, so after a domain move a route stays listed under the old host until someone pays through the new one. On the web check and the paid API (not the CLI) | |
| Browser | paywall | Browser paywall in testnet mode on a mainnet endpoint (@x402/paywall defaults to testnet; the flag is read from JS or JSON config) |
Statuses: pass, warn (works, but something is off), fail (payments fail or it is not valid x402), info.
Reports are shareable: https://<host>/?url=<endpoint>&method=GET runs the diagnosis on load.
API: POST /api/diagnose with { "url": "...", "method": "GET" | "POST" } (method optional) returns
{ url, method, overall, checks[], challenge, share_url }: share_url is the page link above, to paste into an issue or a chat. Rate-limited to 10 diagnoses per minute per IP.
GET /api/v1/diagnose?url=<endpoint>&method=GET|POST returns the same report, $0.01 USDC per call on Base or
Solana via x402, with no rate limit. It is meant for agents and CI pipelines; the web page stays free.
PAYMENT-REQUIRED header, mirrored in the body) with a Bazaar input and
output schema.url
answers 402, so indexers such as x402scan can register it. Paying without a url returns a 400./openapi.json (with x-payment-info) and /.well-known/x402.GET /api/v1/preflightGET /api/v1/preflight?url=<endpoint>&max_usd=0.05&network=<caip2>&method=GET|POST, $0.001 USDC per call:
call it before your agent pays an x402 endpoint it has not used before. It never pays the endpoint.
| Verdict | When |
|---|---|
no_go | No 402 or no valid challenge; every option would fail to settle (bad payTo/amount, missing fee payer or EIP-712 domain, Solana payout wallet without a token account); cheapest option above max_usd; no payable option on the requested network |
caution | Charges more than its OpenAPI advertises; not HTTPS; not a known USDC contract; decimal amount; resource URL differs from the requested URL; testnet only |
go | None of the above. recommended_option is the cheapest payable USDC option (on network if given) |
Not being listed in the CDP Bazaar is reported as info only. Results are cached for 10 minutes per URL, budget
and network (cached: true), so checking before every payment stays fast.
GET /api/v1/fixGET /api/v1/fix?url=<endpoint>&method=GET|POST&stack=<optional>, $0.05 USDC per call: diagnoses the endpoint,
then returns, per failed or warning check, the concrete change that fixes it, as code for your stack and filled in
with your own values (payTo, amount, network, route).
The stack is read from the response headers (x-powered-by, server, Vercel/Render/Cloudflare headers) and the
challenge: express, next, hono, node (an @x402 SDK behind another framework), python or generic (raw
HTTP, for any language). Pass stack= when the guess is wrong. Node snippets use the @x402 v2 route config, which is
the same for @x402/express, /next and /hono; lines that only apply to Express say so.
Recipes (lib/recipes.js, one test each in test/recipes.test.js): no 402 at all (200 before the paywall, auth or
validation first, 404/405, unreachable), v1 or invalid challenge, wrong header name, no body mirror, no accepts,
scheme, legacy network names, invalid payTo (spots quotes, spaces, the wrong chain), USDC asset, decimal amounts,
Solana fee payer, EIP-712 domain, http resource URL behind a proxy, resource URL and metadata, Bazaar declaration and
example, Solana payout token account, Phantom on PayAI, testnet paywall on mainnet, and openapi.json. Anything
without a recipe is returned under unfixed with the diagnosis hint.
Every paid answer (diagnose, preflight and fix; HTTP and MCP) carries a receipt signed by Doctor, so an agent can later prove which verdict it got for which endpoint, for example why it did or didn't pay:
receipt.signature, as canonical JSON (profile js-json-stringify-sorted-utf16-ascii-v1: keys sorted by UTF-16 code units, compact, every code unit from U+007F up as lowercase \uXXXX, numbers as JavaScript's JSON.stringify writes them — 1.0 → 1, 0.000001 → 0.000001 — then UTF-8 bytes; Python's json.dumps matches only for ASCII keys and integers, so use examples/canonical.py, which also has verify_receipt(answer)), with EIP-191 personal_sign. Flipping the verdict or moving it to another request breaks it.payment: the payment that bought this answer, from your x402 payment payload. On Base the payer and the EIP-3009 nonce, so anyone can find the settlement on-chain as the USDC contract's AuthorizationUsed(payer, nonce) event; on Solana the payer and a SHA-256 of the signed transaction you sent.input_sha256: SHA-256 of the canonical JSON of {"route", "input"}, where input is your query parameters as strings (HTTP) or the tool arguments (MCP, route mcp <tool>)./.well-known/x402-doctor-signer.json, with retired signers listed so old receipts keep verifying.POST /api/v1/verify with {"response": …, "route": …, "input": …} returns valid, signer, known_signer and input_matches.Key rotation without client updates: the payout wallet (0x6B0F4651eD42893ab58139938175E4a69f175F25) authorises each signing key with a personal_sign over fizzl receipt signer / service: x402-doctor / signer: <address> / valid_from: <YYYY-MM-DD>. Set it as RECEIPT_SIGNER_CERT (YYYY-MM-DD:0x<signature>, produced by /sign-receipt-key in the wallet's browser). It is checked at startup and carried in every receipt as receipt.cert, so a client that pins only the payout wallet verifies a new key offline.
Same format as presign-guard, so one verifier works for both. The key comes from RECEIPT_SIGNER_SECRET (holds no funds); without it answers are unsigned.
Once a day, trust-scan.yml runs the pre-payment check against every resource in
the CDP Bazaar (read-only: it stops at the 402 challenge, at most two requests per host at a time, one
/openapi.json per origin, a User-Agent that links to /trust). The results roll into a 30-day history per resource,
one letter per day (g go, c caution, n no-go, x unreachable, - not scanned), published as
index.json + summary.json on the trust-data branch.
signals.track_record and a caution (unreliable_history) when a seller was
payable on fewer than half of at least 3 scanned days.GET /api/trust?url=<resource> (free, 30/min per IP): the track record of one resource.
GET /api/trust/summary: totals of the latest scan. /trust: the public page, with lookup and the scan's rules.node scripts/trust-scan.js --out trust-data --limit 200.https://x402-doctor.fizzl.eu/mcp is an MCP server (Streamable HTTP, stateless) for Claude, Cursor and agent frameworks, listed in the official MCP registry as io.github.Fizzl13/x402-doctor.
| Tool | Price | Returns |
|---|---|---|
x402_quick_check | free, 10 calls/hour | pass/warn/fail, the number of problems and the top three |
x402_diagnose | $0.01 USDC via x402 | Every check with a fix hint, as GET /api/v1/diagnose |
x402_preflight | $0.001 USDC via x402 | go/caution/no_go before paying an endpoint, as GET /api/v1/preflight |
x402_fix | $0.05 USDC via x402 | The code changes for your stack, as GET /api/v1/fix |
feedback | free | Report a bug or a missing feature, as POST /feedback (below) |
The paid tools are paid inside the MCP call with the x402 MCP transport (_meta["x402/payment"]), on Base or Solana, at the same prices and to the same payout wallets as the HTTP routes. Invalid input is refused before payment, and a failed call is not charged.
Found a bug, or missing something? Send it with POST /feedback (free, no payment) or the MCP tool feedback:
type is bug, feature or other; message is required (up to 2000 characters); endpoint and contact are optional. The answer is 202 with an id. At most 10 reports per hour per caller. Reports go to the usage log (shown on /admin/usage), and a person reads every one; nothing in a report is run or changed automatically. GET /feedback shows the schema. A diagnosis never calls another server's feedback tool: tools that call themselves free are skipped.
Exit code 0 on pass/warn, 1 when a check fails (or on warnings with --strict), 2 on usage errors.
The CLI can diagnose localhost, so you can run it against a dev server.
Check your x402 endpoints on every push. The step fails on a broken 402, each problem shows up as an annotation on the run and the PR, and the job summary lists what is wrong with the fix next to it.
| Input | Default | |
|---|---|---|
urls | (required) | One per line or comma separated. localhost works for a dev server started earlier in the job. |
method | tries GET, then POST | GET or POST |
fail-on | fail | fail: a failed check fails the step. warn: warnings too. never: report only. |
Outputs: overall (pass, warn or fail, the worst across the URLs) and
report (the full reports as JSON). The Action uses the runner's own Node
(20.18 or newer, as on GitHub-hosted runners) and does not change the job's
Node version. Read-only: no wallet, no payment.
Or the CLI in a plain run: step:
| Variable | Purpose |
|---|---|
PORT | Web server port (default 3001) |
SOLANA_RPC_URL | RPC for the Solana payout-account check (default: public mainnet RPC, which rate-limits) |
AGENT_PAYOUT_WALLET | Base address that receives paid-API payments (or DOCTOR_PAYOUT_WALLET) |
AGENT_PAYOUT_WALLET_SOLANA | Solana address that receives paid-API payments (or DOCTOR_PAYOUT_WALLET_SOLANA); needs a USDC token account |
DOCTOR_PRICE | Price per paid diagnosis (default $0.01) |
DOCTOR_PREFLIGHT_PRICE | Price per pre-payment check (default $0.001) |
DOCTOR_FIX_PRICE | Price per fix (default $0.05) |
FACILITATOR_URL | x402 facilitator (default PayAI, https://facilitator.payai.network) |
CDP_API_KEY_ID, CDP_API_KEY_SECRET | Use Coinbase's CDP facilitator for Base (PayAI stays the fallback). Payments settled through CDP get the route listed in the CDP Bazaar |
DOCTOR_SOLANA_FACILITATOR | With CDP keys set, Solana is settled by PayAI (CDP takes over if PayAI is down). Set to cdp to settle Solana through CDP too |
| USAGE_LOG_TOKEN | Fine-grained GitHub token with Contents read/write on the usage-log repo only. Every call is logged there (see below) |
| USAGE_LOG_REPO | The private usage-log repo (default Fizzl13/usage-log) |
| ADMIN_PASSWORD | Password for /admin/usage (any user name). Without it the admin pages do not exist |
Without either payout wallet the paid route answers 503 and the rest of the app works as before.
/admin/usage shows every call to the Fizzl services (x402 Doctor, PlainText, Ichimoku Signal, presign-guard):
totals, revenue, paying wallets, calls per day per service, the most asked inputs and the latest calls with what
was filled in, the result and the payment (with a Basescan/Solscan link). Each service appends one JSON line per
call to events/<service>/<YYYY-MM-DD>.jsonl in the private usage-log repo (lib/usage-log.js, copied into
each service); the dashboard reads it back (lib/usage-reader.js). 402 challenges, health checks and static
files are not counted, and inputs are cut to 300 characters. Logging never delays or fails a request.
The web app fetches user-submitted URLs server-side:
/api/diagnose (free) is rate-limited per IP; /api/v1/diagnose is paid per call and uses the same guards.It never pays the endpoint it diagnoses: no wallet, no signatures, zero financial risk. A paid probe (sign and settle one minimal payment to trace verify/settle failures) is deliberately out of scope here.
The suites run the doctor against local fixture servers: a healthy v2 service (Base + Solana, Bazaar, OpenAPI, mainnet paywall) and a broken one that reproduces the real bugs above, plus SSRF, size-cap, API and CLI tests.