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.

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