X402 Doctor MCP Server

x402 Doctor

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.

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.

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.
• 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.

{
  "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
}

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.

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.

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

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.

• The pre-payment check adds 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.
• Run it yourself: node scripts/trust-scan.js --out trust-data --limit 200.

Weekly x402 health report

Every Monday, weekly-report.yml turns the last 7 days of the Trust Index into a report: how many Bazaar resources are clean, payable with a caution or not payable, the most common reasons with the fix for each, which networks payable resources accept, and what changed this week (broke, fixed, flaky, new). It names no seller or host. The report, its numbers and drafts for X, Discord and Reddit (for a person to review and post) go to reports/<date>.md, .json and -posts.md on the weekly-reports branch. Locally: node scripts/weekly-report.js --out reports [--index trust-data/index.json].

MCP server

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.

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.

Feedback

Found a bug, or missing something? Send it with POST /feedback (free, no payment) or the MCP tool feedback:

curl -X POST https://x402-doctor.fizzl.eu/feedback \
  -H 'content-type: application/json' \
  -d '{"type": "feature", "message": "Also check the facilitator /supported list", "endpoint": "/api/v1/diagnose"}'

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.

CLI

npx github:Fizzl13/x402-doctor https://api.example.com/paid
npx github:Fizzl13/x402-doctor https://api.example.com/paid --method POST --json

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.

GitHub Action

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.

- uses: Fizzl13/x402-doctor@master
  with:
    urls: |
      https://your-api.example.com/paid
      https://your-api.example.com/other

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:

- run: npx -y github:Fizzl13/x402-doctor https://your-api.example.com/paid

Configuration

| 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.

Usage dashboard

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

Safety

The web app fetches user-submitted URLs server-side:

• Every connection is checked against private and reserved ranges (RFC 1918, loopback, link-local and cloud metadata, CGNAT, IPv6 ULA/link-local, IPv4-mapped IPv6 in any notation) at connect time, so DNS rebinding cannot slip past a separate lookup. Redirects are followed manually and each hop is re-checked.
• Responses are capped at 2 MB and every request times out after 8 s.
• /api/diagnose (free) is rate-limited per IP; /api/v1/diagnose is paid per call and uses the same guards.
• Everything taken from the diagnosed endpoint is rendered as text, never as HTML.

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.

Project structure

server.js              Express app: /api/diagnose (free), paid API, /openapi.json, /.well-known/x402, static frontend
lib/paid-api.js        GET /api/v1/diagnose, /preflight (+ /batch, /deep) and /fix behind x402 (Base + Solana USDC)
lib/recipes.js         The fix per failed check, as code for the detected stack
lib/stack.js           Which stack runs an endpoint, from its response headers
lib/preflight.js       Pre-payment check: verdict, recommended option, reasons (cached)
lib/preflight-plus.js  Batch (up to 10 endpoints) and deep pre-payment checks
lib/bazaar-index.js    Cached CDP Bazaar index (listing signal for preflight)
lib/trust-scan.js      Trust Index scan: catalog, polite fetch, 30-day history
lib/trust-index.js     Reads the published index for preflight and /api/trust
scripts/trust-scan.js  Daily scan entry point (trust-scan.yml)
public/trust.html      /trust page
lib/media.js           Serves the explainer and paid-fix videos from their branches (/media/explainer.mp4, /media/fix.mp4)
media/explainer/       Explainer video pipeline (script, voice, recording, encoding)
lib/diagnose.js        The checks
lib/site-scan.js       MetaMask's site scanner verdict for the domain
lib/mcp-check.js       x402 over MCP: tools/list, unpaid tools/call, the payment requirement in the tool result
lib/networks.js        Known networks, USDC per network, address validation
lib/safe-fetch.js      SSRF-safe fetch (connect-time IP check, redirects, size cap, timeout)
bin/x402-doctor.js     CLI
public/index.html      Frontend
test/                  node:test suites (fixture x402 servers, SSRF, CLI, API)

Tests

npm test

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.