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 Ichimoku Signal and presign-guard.

▶ 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

Group	Check	Catches
402 challenge	returns-402	No 402 for GET or POST (tries both, or --method). Behind Cloudflare or Amazon CloudFront the hint names the usual Monetization Gateway or AWS WAF Monetize rule misses. An endpoint that asks for x401 proof first is info, not a failure. A POST that answers 400 or 422 to an empty body checks its input before payment: Doctor sends the requestBody example from the seller's /openapi.json (or one built from its schema), or your own example body, and without one the check is a warning (needs input), not a failure
	x401	An x401 proof request (PROOF-REQUEST, x401.id) instead of a 402: the endpoint asks who is behind the agent before it asks for payment. Pass when the base64url payload names scheme x401, a version and credential requests (with their protocols, the token endpoint and the payment hint); a warning when agents can't read it; info for the older header name PROOF-REQUIRED
	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 to avoid that). The requirement then gets the payment-option, settlement and wallet checks below

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
}

Verdict	When
no_go	No 402 or no valid challenge; every option would fail to settle (bad payTo/amount, a payTo that is the zero or another burn address (payto_burn, caution when another option is payable), 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 (or BNB Chain dollar token) contract; decimal amount, or a 6-decimal amount on an 18-decimal token; resource URL differs from the requested URL; testnet only; bait (below); 20x or more above comparable services (below)
go	None of the above. recommended_option is the cheapest payable USDC option (on network if given); at the same price, one every x402 client can pay (EIP-3009, not Permit2) and USDC before other dollar tokens

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 (: , or , with the it sent). The x402 payment travels in its own header, not in , so only or keeps it out (, 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

Once a day, trust-scan.yml runs the pre-payment check against every resource in the CDP Bazaar, the MPP directory, the GoPlausible facilitator's discovery list (x402 on Algorand, about 2,500 endpoints the Bazaar doesn't list) Circle's Agent Marketplace catalog (about 2,800 endpoints, many paid through Circle Gateway) and the XRPL AI Hub (the merchants paid through t54's XRPL facilitator; it has no listing API, so its merchant pages are read, about 190 pages a day) and nohumans.directory's catalogue (CC BY 4.0, mirroring it is a supported use; about 9,600 active listings, some 1,550 of them in no other registry on 25 Oct 2026) and PayAPI Market's catalogue (its open /agent/list; about 940 listings and 1,000 routes, some 300 of them in no other registry on 25 Oct 2026) (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/ + summary.json on the trust-data branch. The index is written in parts of at most 24 MB (index/meta.json, then index/<nn>.ndjson with one [key, resource] per line; lib/index-files.js), so no file nears GitHub's 100 MB limit as the index grows; index.json and index.ndjson, the whole index as one file, are published as well while they stay under 90 MB. The scan runs in parallel jobs, each with whole sellers (a plan job reads the catalogs, four scan jobs, a publish job merges them): a share that fails leaves its endpoints not checked that day, never marked down. A seller with more than 5,000 endpoints gets a share of them checked each day, so that each one has its turn within a week (the rest are - that day and keep their last verdict; one seller listed 62,924 on 27 Oct 2026). The server doesn't load that index (42 MB, ~88,000 resources on 25 Oct 2026): after the scan, () writes it as small precomputed files on the same branch, from the same code ( with the summary, , , , the price check's word index under , one per network (one over 16 MB as a head and parts, listed in ), and the resources in 256 buckets by key under ). reads only what a request needs (one ~130 kB bucket per lookup, at most 32 kept) with the same answers as the full index, and falls back to the full index while the views aren't published. Measured on the 20 Oct index: 116 MB peak instead of 285 MB, 37 MB of heap instead of ~100 MB. After each scan, publishes it as an open dataset on Hugging Face, (CC BY 4.0): (every endpoint in the latest scan with its verdict, reasons, price, networks, category and history), (go / caution / no_go per day), (every purchase of the weekly spot-buy, from the branch), (signed USDC payments on Base per payout address and day, from the branch) and the dataset card (). It also keeps the dataset in the Hugging Face collection "x402 agent payments" when the token may write collections. It needs the repository secret (a Hugging Face write token); the variable overrides the dataset name. publishes the the same way (): a dataset with every run and its transcript (from x402-examples' branch), the published tables as , and a static leaderboard Space of the same name. It runs when the script changes, every Monday and by hand; the variable overrides the name. publishes as the Space : a Gradio app that is also an MCP server (, or added under Hugging Face's MCP settings), with four free tools over the public API: (), (), () and (). It never pays or holds a key; the variable overrides the name. Hugging Face hosts Gradio Spaces only for PRO accounts: without PRO the workflow warns and publishes nothing, and the Space waits in . Doctor's own MCP server is .

• 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.
• Spot-buy sample: does "go" mean paid and delivered? The scan only reads the 402 challenge. Once a week spot-buy.yml buys a small random sample of "go" endpoints (lib/spot-buy.js): x402 exact in USDC on Base only, one endpoint per host, never a fizzl.eu or test host, the seller's own declared example as the request (when it reaches the paywall), a fresh preflight with the OFAC payout screen right before paying, and hard caps (default 30 endpoints, $0.05 per call, $2 per run; at most 50, $0.10 and $5). Whether money left the wallet is measured on chain (its USDC balance before and after), and the seller's PAYMENT-RESPONSE is checked against the chain. Each result is delivered, off_schema (an answer that doesn't match the declared output schema), empty, charged_not_delivered, payment_rejected, error_not_charged or payment_failed; the run is appended to the spot-data branch (latest.json, results/<date>.json, a second run that day as results/<date>-2.json). It pays only with the secret SPOT_BUY_KEY, a dedicated wallet holding a few USDC; without it every run is a dry run that pays nothing. The latest run is on /trust ("Paid and delivered?") and at GET /api/trust/spot (summary and every purchase, no wallet details); GET /api/trust?url=… adds spot_buy when that endpoint was bought in it (lib/spot-results.js). The paid pre-payment check adds the same as signals.spot_buy, and a caution (charged_without_answer) when the endpoint took the payment for the example request its own listing declares and answered with an error or not within 90 seconds. Each purchase also records its answer time (answer_s, from the first request to the paid answer): the summary counts answers slower than 30 seconds (slow_answers, and delivered_within_30s_pct, what an agent that waits 30 seconds gets), and a slow one adds slow_after_payment (info) to the pre-payment check.
• Delivery evidence from others who buy endpoints with real USDC: nohumans.directory (its catalogue is CC BY 4.0) and , which pays one route of each listing once. The scan's plan job writes the endpoints they bought and got an answer from to and on (by key: the day of that purchase, the listing's status, a link to the listing; about 3,650 and 970 on 25 Oct 2026, 600 of PayAPI's not in nohumans', against the 26 a week the spot-buy can afford). The paid pre-payment check adds (the latest purchase, every source's in ) and an line () for such an endpoint, adds , and the web check and show it (). It is information next to the read-only check, never the verdict. The same wallet makes one other kind of payment, started by hand: pays our own fizzl.eu routes (), because the CDP Bazaar lists a route only after a payment for it settles and drops it after 30 days without one. (the default) pays each of our 16 routes whose last settled payment in the Bazaar is 21 days old or more (read from its public search), each at most its own price (); pays one route once. The money goes to our own payout wallets. It publishes nothing, so the sample stays one of other sellers. Each run is also a self-audit of those routes: the same payment header is sent once more and must get a 402 ("Five Attacks on x402", attack II; a route that serves it again fails the run), and the settlement transaction's ERC-8021 suffix shows whether our Base Builder Code was written into it. Other sellers' endpoints are never replayed.

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

The same run writes a digest per network, Algorand and the XRP Ledger (network-digest.js): how many endpoints could be paid there, from how many sellers, what changed since last week (new endpoints, ones that stopped being payable, new sellers), how many accept only that network, the median price and the biggest sellers. It names payable sellers only; problems are counted. Files: reports/<date>-<network>.md and -posts.md (X and community drafts), plus reports/networks/<network>-latest.json, the snapshot next week compares with. Locally: node scripts/network-digest.js --out reports [--index trust-data/index.json] [--previous reports/networks].

Fizzl Buy (buy.fizzl.eu)

Fizzl's fourth agent, from this repository (buy-server.js, lib/buy/), runs as its own Render service. An agent says what it needs and the inkoper buys the right paid API for it: POST /v1/buy {"need": "weather forecast for Amsterdam tomorrow"}, $0.02 over x402 (USDC on Base or Solana), for services up to $0.01.

1. Pick (lib/buy/search.js): the wallet server's ranked search of the whole Bazaar, kept to sellers payable in USDC on Base within the cap and payable on at least 80% of 3 or more days x402 Doctor checked.
2. Fill in (lib/buy/fill.js): Claude answers the seller's input from the need (the keys of its Bazaar example, path parameters into the path).
3. Check and buy (lib/buy/purchase.js): a fresh preflight must say go (OFAC payout screen, track record, namesake, bait); then the inkoper's own wallet (BUY_WALLET_KEY, kept small) pays, within BUY_DAILY_USD a day (default 5) and its balance.
4. Check the answer: TypeSafe Jev's answer check (lib/jev-answer.js). Not what was paid for, an error or an empty answer moves on to the next candidate, at most three. When none delivers the answer is an error and the agent's own payment is not settled.

GET /v1/pick?need=… and the MCP tool x402_pick (free, 10 an hour) say what would be bought and why; the MCP tool x402_buy buys, paid inside the call ($0.02 over x402, _meta["x402/payment"], the same networks as the HTTP route, and the same lock against one payment used twice). The MCP server (https://buy.fizzl.eu/mcp) is in the official MCP registry as io.github.Fizzl13/fizzl-buy (server.buy.json, published with the Publish to MCP registry workflow, server fizzl-buy). In the ERC-8004 Identity Registry on Base it is agent #988891. node scripts/buy-dry-run.js "<need>" … shows the picks, the filled-in requests and the preflights without paying (needs ANTHROPIC_API_KEY). On 23 Oct 2026 it found a seller with a preflight go for all seven test needs (weather, BTC price, web search, crypto news, EUR to USD, a token check, a translation), passing over a caution and a seller that didn't answer 402.

One payment buys one answer: x402 verifies a payment before the purchase and settles it after, so the same payment sent several times at once would otherwise run several purchases with the inkoper's money; a payment already in use is refused with a 409 (lib/buy/once.js). The day budget (BUY_DAILY_USD) survives a deploy: each purchase writes what it paid sellers into the usage log, and a new instance counts what the others spent today (lib/buy/spent-log.js).

Live at https://buy.fizzl.eu since 23 Oct 2026 (the first indexing payment was delivered in 15 seconds). Like the other fizzl.eu services, its 402 names the seller (x402-merchant) and, with BUILDER_CODE set on the Render service, carries the Base Builder Code.

Agent skills

Two Agent Skills in skills/ teach a coding agent (Claude Code, Codex, Cursor and others that read SKILL.md) when and how to use Doctor:

• x402-preflight: before the agent pays any x402 or MPP endpoint (awal x402 pay, x402-fetch, Privy's x402 client, mppx…), it looks up the free track record, then buys the $0.001 preflight and follows go / caution / no_go, and reports the outcome afterwards.
• x402-seller-check: after building or changing a paid endpoint, it runs the free check until it passes, and buys the $0.05 fix when a problem isn't obvious.

npx skills add Fizzl13/x402-doctor

Claude Code plugin

In Claude Code, the same skills come as a plugin together with the MCP server below, and presign-guard's skill and MCP server as a second plugin. Fizzl Buy, the Fizzl Agent Wallet and Ichimoku Signal have a plugin each, from Fizzl13/fizzl-skills, the overview of every Fizzl skill:

/plugin marketplace add Fizzl13/x402-doctor
/plugin install x402-doctor@fizzl
/plugin install presign-guard@fizzl
/plugin install fizzl-agent-wallet@fizzl
/plugin install ichimoku-signal@fizzl
/plugin install fizzl-buy@fizzl

The marketplace is .claude-plugin/marketplace.json. The paid tools of both MCP servers need an MCP client that pays x402; without one, the skills pay over HTTP with your own x402 client, as they describe.

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. Directories can read its tools without connecting from the server card at /.well-known/mcp/server-card.json (the same list as tools/list).

https://x402-doctor.fizzl.eu/mcp/free is the same server with only the free tools (x402_quick_check, check_payment_proof, x402_trust_record, x402_trust_add), for directories whose clients don't pay, such as Claude's connectors directory. Claude calls connectors from Anthropic's outbound range (160.79.104.0/21), so calls from there share one pool of 300 free calls an hour instead of 10 per address, on both endpoints.

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_preflight_batch	$0.005 USDC via x402	The preflight for up to 10 endpoints (urls), as GET /api/v1/preflight/batch
x402_preflight_deep	$0.01 USDC via x402	The preflight plus diagnosis, history, seller and domain checks, as GET /api/v1/preflight/deep
x402_fix	$0.05 USDC via x402	The code changes for your stack, as GET /api/v1/fix
x402_delivery_check	$0.25 USDC via x402	One real purchase of the endpoint: a job id now, the result shortly after, as GET /api/v1/delivery-check
x402_delivery_status	free	The status and, once done, the result of a delivery check, as GET /api/v1/delivery-check/{id}
verify_receipt	free	Whether a paid answer's signed receipt is valid and for which request, as POST /api/v1/verify (see Signed verdicts)
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. A delivery check ordered over MCP is queued only once its payment settled, like the HTTP route.

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
npx github:Fizzl13/x402-doctor https://api.example.com/v1/score --body '{"text":"hello"}'

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. On the GitHub Marketplace as x402 Doctor check; a public endpoint that passes also gets a badge snippet.

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

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:

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

Configuration

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
ALGORAND_PAY_TO	Algorand address that receives paid-API payments in USDC (ASA 31566704), settled by GoPlausible's facilitator (ALGORAND_FACILITATOR_URL overrides). The account must have opted in to USDC. Unset or off: no Algorand option
STELLAR_FACILITATOR_KEY	API key for OpenZeppelin's "Built on Stellar" facilitator (generate one at channels.openzeppelin.com/gen); turns on the Stellar option: paid-API payments in USDC on Stellar mainnet, fees paid by the facilitator. STELLAR_FACILITATOR_URL points at another facilitator (with or without the key)
STELLAR_PAY_TO	Stellar account that receives those payments; default Frits's account (it trusts USDC). The account must have a USDC trustline. off: no Stellar option
BUILDER_CODE	Base Builder Code (ERC-8021, minted at base.dev) declared in every paid route's 402 as the builder-code extension: the buyer's x402 client echoes it and the facilitator writes it into the settlement, so Base attributes the payment. Unset or not a valid code: none
DOCTOR_PRICE	Price per paid diagnosis (default $0.01)
DOCTOR_PREFLIGHT_PRICE	Price per pre-payment check (default $0.001)
DOCTOR_BATCH_PRICE	Price per batch pre-payment check, up to 10 endpoints (default $0.005)
DOCTOR_DEEP_PRICE	Price per deep pre-payment check (default $0.01)
DOCTOR_FIX_PRICE	Price per fix (default $0.05)

| 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, Ichimoku Signal, presign-guard, Fizzl Buy): 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>/<HH>.jsonl (one file per UTC hour since 25 Oct 2026; one per day, events/<service>/<YYYY-MM-DD>.jsonl, before) in the private usage-log repo (lib/usage-log.js, copied into each service); the dashboard reads both back (lib/usage-reader.js). A bot's unpaid 402s are one line per hour, route and agent, with count and visitors (how many different callers). 402 challenges, health checks and static files are not counted as calls, and inputs are cut to 300 characters. Logging never delays or fails a request.

Payment security (Five Attacks on x402)

Five Attacks on x402 (Li, Wang and Wang, 2026) describes five ways an x402 payment can go wrong between the HTTP request and the chain, and maps each to a mitigation. How this service handles them:

Attack	What goes wrong	Here
I-A Revert-grant	The answer is released before the payment is final, and the payment then fails	The answer is held until the settlement is confirmed: @x402/express buffers it, and the XRPL and Solana paths wait for a validated, successful transaction. A failed settlement answers 402, never the content.
I-B Settlement preemption	Someone who sees the payment header submits the authorization first, so the server's own settlement fails	A protocol-level issue; the paper's fix is settlement bound to the facilitator. Here the payment header only travels over HTTPS and is never logged.
II Replay	One payment buys several answers	Each payment is claimed once: EIP-3009 nonces on Base, a settlement cache keyed by the transaction on XRPL and Solana (an XRPL payment through t54 is also refused once its transaction is on the ledger, so a restart does not reopen it), and an MPP Tempo transfer must carry the memo of one challenge (valid for minutes) and is claimed by its hash. An XRPL payment's InvoiceID names this service, and credits are taken atomically.
III Cache and header confusion	A shared cache (CDN, proxy) stores a paid answer and serves it to someone who did not pay	402 challenges are Cache-Control: no-store; paid answers carry private (added by @x402/express) or no-store.
IV Server selection	Fake or manipulated listings steer agents to the wrong seller	openapi.json carries an ownership proof signed by the payout wallet (x402scan), and the pre-payment check flags impersonation, bait, template farms and payout addresses on the OFAC list.

Doctor checks other sellers for two of them as well: the paid delivery check records whether a CDN may serve the paid answer for free (III), and the pre-payment check covers IV for every endpoint a buyer is about to pay.

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
lib/index-files.js     The index in parts (index/meta.json, index/<nn>.ndjson): written, read, loaded over HTTP
scripts/trust-scan.js  Daily scan entry point (trust-scan.yml): plan, one share of the sellers, merge
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/request-body.js    Example POST body: the caller's, or the requestBody example from the seller's /openapi.json
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 (or BNB Chain's dollar tokens) 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
skills/                Agent Skills: x402-preflight (buyers) and x402-seller-check (sellers)
.claude-plugin/        Claude Code plugin marketplace: the skills plus the MCP servers of Doctor and presign-guard
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.

License

Copyright (C) 2026 Frits Zwager. Licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only); see LICENSE. If you run a modified version as a network service, you must offer its source code to the users of that service.