X402 Doctor MCP Server

x402 Doctor

· Live status ·

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.

What it checks

Statuses: pass, warn (works, but something is off), fail (payments fail or it is not valid x402), info.

Web app

npm install
npm start          # http://localhost:3001

Reports are shareable: https://<host>/?url=<endpoint>&method=GET runs the diagnosis on load (&method=POST&body=<json> for a POST with an example body).

API: POST /api/diagnose with { "url": "...", "method": "GET" | "POST", "body": { ... } } (method and body optional) returns { url, method, overall, checks[], challenge, share_url }. body is an example request body (JSON, up to 16 KB) for a POST that checks its input before the 402; it implies POST, and the report says which body reached the 402 (body, and body_source when it came from the seller's /openapi.json). share_url is the page link above, to paste into an issue or a chat. Rate-limited to 10 diagnoses per minute per IP.

Paid API for agents (x402)

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.

• Unpaid requests get the x402 challenge (PAYMENT-REQUIRED header, mirrored in the body) with a Bazaar input and output schema.
• body=<URL-encoded JSON> (optional, also on preflight, deep and fix, and as body in the MCP tools): an example request body for a POST route that checks its input before the 402. It implies POST; with method=GET, or when it is not JSON, the answer is a 400 before payment. The batch takes no body.
• Invalid input (bad URL, non-http(s), unknown method) gets a 400 before payment. The bare route without url answers 402, so indexers such as x402scan can register it. Paying without a url returns a 400.
• The x402 middleware settles only after a 2xx response, so a diagnosis that errors out is never charged.
• Discovery: /openapi.json (with x-payment-info) and /.well-known/x402.
• Browsers opening the route get a wallet paywall (Base first: MetaMask, Coinbase Wallet) instead of the bare 402.
• Bazaar: a facilitator lists a route after the first payment it settles for it. With the CDP keys set, one paid call (e.g. from the browser paywall) puts the route in the CDP Bazaar that agents search.

# pay-per-call from Node with @x402/fetch
const paidFetch = wrapFetchWithPayment(fetch, client);   // client with an EVM or SVM signer
const report = await (await paidFetch("https://<host>/api/v1/diagnose?url=https://api.example.com/paid")).json();

Pre-payment check for buyers: GET /api/v1/preflight

GET /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. Add client=gateway when your agent pays with Circle's Gateway client from a Gateway balance: Circle Gateway-only endpoints (gateway_only, otherwise a caution) are then a go, and a Gateway option is recommended first.

{
  "verdict": "go",                     // go | caution | no_go
  "safe_to_pay": true,
  "summary": "OK to pay: $0.02 on Solana.",
  "recommended_option": 1,             // index into the endpoint's accepts[]
  "options": [{ "network": "eip155:8453", "asset_symbol": "USDC", "usd": 0.02, "payable": true, "problems": [] }, …],
  "signals": { "https": true, "advertised_price_usd": 0.02, "listed_in_cdp_bazaar": true },
  "reasons": [],                       // [{ level: no_go | caution | info, code, message }]
  "cached": false
}

BNB Chain (eip155:56) has no Circle USDC. Sellers price in 18-decimal dollar tokens: Binance-Peg USDC, USDT, USD1 and United Stables (U), so $0.01 is "10000000000000000". Doctor prices those options like USDC. USDC and USDT there have no EIP-3009, so an option without assetTransferMethod: "permit2" fails; a value standard x402 clients don't know is a warning, because @x402/evm then signs EIP-3009 instead. "permit2-exact" and "permit2-upto" are the methods of Binance's B402 facilitator, so only its own clients pay those options.

Bait check (TypeSafe's Jev, when TYPESAFE_API_KEY is set): for an endpoint that could be paid, Jev judges what the protocol checks can't. Does it claim to be, or to be official from or endorsed by, a brand that doesn't own its domain (brand_impersonation; reselling or proxying a brand's product under the seller's own name, such as an LLM gateway naming the models it serves, is not), lure with free tokens, airdrops or guaranteed returns (lure_description), or promise something its declared output doesn't deliver (output_mismatch)? A clear yes is a caution, an in-between answer info; it never makes a verdict no_go and never turns one into go. The probabilities are in signals.jev_lure. On 300 real CDP Bazaar listings it raised no caution for brand or lure wording. When a bait question changes (BAIT_VERSION in lib/jev-lure.js), the Trust Index's next run asks again, first, every service the old wording flagged or was unsure about; clear answers carry over.

Namesakes (same key, from the daily Trust Index scan, lib/namesakes.js): the x402 Bazaar indexes each listing's service name, so an agent that searches for a known service finds every listing with that name. When another seller, with its own payout address and fewer payers, lists under the brand name of an established service, the preflight adds namesake (info: the name, the original's site and both payer counts). Sites that share a payout address, a distinctive host-name word or three or more names count as one owner, and TypeSafe's Jev must be sure (0.85) that the name is a brand rather than a description such as "web search". On 23 Oct 2026, 83 names were listed by more than one owner and one was a brand with a better-known original. It never changes the verdict: a namesake can be a fair reseller or an unrelated service.

Price check (same key): is the price far above what comparable services ask? Doctor takes up to 24 paid APIs of other sellers from the x402 Trust Index whose descriptions share rare words with this one (at most two per seller), and Jev judges per candidate whether a buyer would be served just as well by it. With at least 5 such services, their median price is the comparison: 5x or more (and at least $0.05 more) is info, 20x or more (and at least $0.25 more) a caution, both price_high and naming up to three cheaper alternatives. The comparison is in signals.price_check (comparable_median_usd, comparables, ratio, cheaper[]). It never makes a verdict no_go: the price is the seller's choice, the agent decides whether it is worth it.

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.

Several endpoints at once: GET /api/v1/preflight/batch

GET /api/v1/preflight/batch?url=<a>&url=<b>&max_usd=0.05, $0.005 USDC per call for up to 10 endpoints (one url parameter each; duplicates count once). For marketplaces, directories and agents that weigh several services. Each endpoint gets the same verdict as a single preflight; one that errors or does not answer within 20 seconds is unknown and does not hold up the rest.

{
  "count": 2,
  "counts": { "go": 1, "caution": 0, "no_go": 1, "unknown": 0 },
  "results": [
    { "url": "https://a.example/paid", "verdict": "go", "safe_to_pay": true, "summary": "OK to pay: $0.02 on Base.", "recommended_option": 0, "options": […], "reasons": [] },
    { "url": "https://b.example/paid", "verdict": "no_go", "safe_to_pay": false, "summary": "Do not pay: …", … }
  ]
}

Before an expensive call: GET /api/v1/preflight/deep

GET /api/v1/preflight/deep?url=<endpoint>&max_usd=0.5, $0.01 USDC per call: everything the preflight answers, plus

• diagnosis: the full diagnosis (overall, every check, and the failing or warning ones as problems);
• history: the daily scans of the last 30 days, one { date, status } per day;
• seller: the seller's other scanned endpoints on the same origin (how many, payable today, average payable ratio, how many were unreliable). A seller whose endpoints were payable on less than half of the scans turns go into caution (unreliable_seller);
• domain: the domain-move checks (well-known, bazaar-listing), e.g. a Bazaar listing only under an old domain.

Paid and delivered? GET /api/v1/delivery-check

GET /api/v1/delivery-check?url=<endpoint>&method=GET|POST, $0.25 USDC per check: x402 Doctor buys the endpoint once, with the example input its own listing declares, and publishes what came back. For sellers who want proof that their endpoint delivers, and for buyers before a large order.

• Checked before you pay: the endpoint must be https, not a fizzl.eu route, get a go from the pre-payment check, be payable in USDC on Base and cost at most $0.10. Anything else answers 400 (or 503 when the day's 20 checks are taken), and nothing is charged. A request with a payment always waits for the whole check before anything settles. A probe without a payment wants the 402: it gets one unless the request itself is malformed (not one https URL, a fizzl.eu route, a bad method), also for an endpoint that can't be bought now, since uptime monitors fill url with a placeholder such as https://example.com, and within 5 seconds (the CDP Bazaar's validator and health probe give up after 10). To get the answer before paying, send X-Delivery-Precheck: 1; the homepage does.
• The answer comes at once, the purchase shortly after: the paid call answers with a job id and a status_url. delivery-check.yml takes the queue (GET /api/v1/delivery-check/queue, free) and buys with the dedicated spot-buy wallet (SPOT_BUY_KEY; no wallet key on the server). Only a job whose payment settled is released to the queue. The server starts the workflow as soon as a payment settles (DELIVERY_DISPATCH_TOKEN: a fine-grained GitHub token for this repository with only Actions read and write; lib/delivery-dispatch.js); its schedule, every 10 minutes, is the fallback, since GitHub runs scheduled workflows late or not at all.
• The same steps as the spot-buy (lib/spot-buy.js): a fresh preflight with the OFAC payout screen right before paying, the seller's declared example input, the answer checked against the declared output schema and judged by TypeSafe's Jev (is it what was paid for, does it carry instructions for the agent: lib/jev-answer.js), and the charge measured on chain.
• Public result: GET /api/v1/delivery-check/<id> (free) shows queued, then done with the result (delivered, off_schema, empty, charged_not_delivered, payment_rejected, error_not_charged, or the step that stopped it before paying) and the transaction. Every result is on the delivery-data branch.
• Caching: for a delivered GET answer, cache says whether a shared cache (a CDN) may store the paid answer and serve it to callers who did not pay (shared_cache: yes, no or unspecified, with the Cache-Control it sent). The x402 payment travels in its own header, not in Authorization, so only Cache-Control: private or no-store keeps it out (Five Attacks on x402, attack III).

Jobs are kept in the credits Redis (CREDITS_REDIS_URL); without it the route answers 503 before payment.

Prepaid credits: GET /api/v1/credits/1000

Agents that check often can prepay: one x402 payment of $0.80 for 1000 credits or $7.00 for 10,000 (20% and 30% off), valid for a year. A credit is $0.001: a preflight costs 1, a batch 5, a deep preflight or a diagnosis 10, the fix 50. The pack answers with a credit_key; send it as the x-credit-key header with any paid call instead of paying. GET /api/v1/credits (free) shows the prices and, with the header, your balance. A call that fails gives its credits back; with no key or too few credits the normal 402 applies. Needs CREDITS_REDIS_URL (a persistent Redis such as Upstash; the presign-guard instance is fine, the keys are apart); without it, no packs are sold.

The fix, as code: GET /api/v1/fix

GET /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).

{
  "stack": { "id": "express", "name": "Express (@x402/express)", "detected_from": "x-powered-by: Express" },
  "summary": "3 fixes (1 blocking), for Express (@x402/express).",
  "fixes": [
    {
      "recipe": "amount",
      "severity": "warn",
      "checks": ["accepts[0]-amount"],
      "title": "Amount \"0.01\" → \"10000\" ($0.01)",
      "why": "x402 amounts are integer strings in the token's smallest unit; USDC has 6 decimals.",
      "steps": ["Easiest: let the SDK convert it by using price: \"$0.01\" instead of an amount."],
      "code": [{ "language": "javascript", "stack": "node", "label": "Route config", "snippet": "accepts: [{ scheme: \"exact\", price: \"$0.01\", ... }]" }],
      "verify": "Run x402 Doctor again on https://…; accepts[0]-amount should pass."
    }
  ],
  "unfixed": []
}

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.

Learning from outcomes: POST /api/v1/outcome

After a paid preflight, a buyer can report (free) what happened when it then paid the endpoint: paid_ok, paid_failed (402 again) or paid_error. x402-safe-fetch does it with shareOutcomes: true.

{ "outcome": "paid_failed", "status": 402, "preflight": { …the signed preflight answer… }, "query": { "url": "…", "method": "GET", "max_usd": "0.05", "network": "eip155:8453" } }

• A report counts only with a real preflight that Doctor signed for exactly that query, once per preflight (receipt.request_id), so a false report costs a paid preflight.
• Doctor counts reports per endpoint over 30 days. When most reported payments failed, from at least three different paying wallets, later preflights add payments_fail_after_preflight (caution); signals.agent_outcomes shows the counts.
• Reports land in the usage log (endpoint, outcome, status, verdict, payer from the receipt); nothing else about the buyer.

Signed verdicts

Every paid answer (diagnose, preflight, batch, deep 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": {
  "request_id": "…", "route": "GET /api/v1/preflight", "input_sha256": "…",
  "payment": { "network": "eip155:8453", "amount": "1000", "payer": "0x…", "nonce": "0x…", "proof": "eip3009" },
  "signed_at": "2026-09-27T08:00:00.000Z", "signer": "0x…",
  "algorithm": "eip191-canonical-json-v1", "signature": "0x…"
}

• Signed: the whole answer without 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>).
• Signer: /.well-known/x402-doctor-signer.json, with retired signers listed so old receipts keep verifying.
• Free check: POST /api/v1/verify with {"response": …, "route": …, "input": …} returns valid, signer, known_signer and input_matches. Over MCP: the free tool verify_receipt with the same arguments (route like mcp x402_preflight, input the tool arguments).

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.

x402 Trust Index

Documentation truncated — see the full README on GitHub.