x402 Doctor

x402 Doctor

面向 x402 卖家端点的免费诊断工具。将其指向你的付费端点，它会执行付费客户端会进行的握手——发送不带 X-PAYMENT 标头的 GET 请求——然后报告你返回的 402 挑战中有哪些问题，以及需要做哪些更改。

在线使用：https://x402-doctor.tsharpe.workers.dev

curl -s -X POST https://x402-doctor.tsharpe.workers.dev/probe \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://your-service.example/paid-endpoint"}'

为什么关注卖家端

官方 SDK 已能很好地支持买家端 x402。卖家端则是人们容易卡住的地方，因为故障发生在你无法查看的 facilitator 内部：你的端点看起来正常，付款却无法结算，而错误会出现在你无法控制的地方。

每项检查都带有 provenance 字段，因此所有发现都有据可查：

• spec — x402 规范要求如此。
• observed (source) — 我们观察到实际的 facilitator 因此拒绝了请求，并注明了来源。

你会收到什么

{
  "target": "https://your-service.example/paid-endpoint",
  "finalUrl": "https://your-service.example/paid-endpoint",
  "status": "advisories",
  "http": { "status": 402, "contentType": "application/json" },
  "findings": [
    {
      "id": "challenge-cacheable",
      "severity": "warn",
      "title": "402 challenge is cacheable",
      "why": "…",
      "fix": "…",
      "provenance": "observed (ours, 2026-08-15)",
      "evidence": "cache-control: public, max-age=300"
    }
  ],
  "checksRun": 16,
  "bodyTruncated": false,
  "bodyChecksSkipped": 0,
  "bodySkipReason": null
}

status 的取值之一为：

status	含义
healthy	没有需要报告的问题
advisories	有值得查看的提示，但没有错误
defects_found	至少有一项 error
not_x402	端点没有返回 x402 挑战
unreachable	探测未能完成 — 请查看 reason

如果响应正文被截断或无法解析，则会跳过正文检查，报告也会明确说明（bodyChecksSkipped、bodySkipReason）。未运行的检查绝不会被报告为已通过。

16 项检查

id	严重程度	检查项	来源
no-402	error	端点未在无付款时返回 402	spec
body-not-json	error	402 正文不是可解析的 JSON	spec
oversized-body	warn	402 正文超出读取上限	observed (this probe)
missing-x402-version	error	缺少 x402Version，或其值不是 1	spec
accepts-empty	error	accepts 缺失、不是数组或为空	spec
output-schema-null	error	outputSchema 被明确设为 null	observed (Coinbase CDP facilitator, 2026-07-17)
amount-not-atomic-string	error	maxAmountRequired 不是原子单位字符串	spec
asset-network-mismatch	warn	asset 不是此网络上的 USDC 合约	spec
missing-eip712-extra	error	scheme 为 "exact"，但 extra 中缺少 EIP-712 域	spec
unknown-network-name	info	网络名称不在此探测工具识别的范围内	spec
payto-not-an-address	error	payTo 不是此网络上的有效地址	spec
payto-not-checksummed	info	payTo 不是校验和地址	spec
no-timeout-declared	info	未提供 maxTimeoutSeconds	spec
challenge-cacheable	warn	402 挑战可被缓存	observed (ours, 2026-08-15)
cors-headers-not-exposed	info	浏览器客户端需要在结算响应中公开付款标头	observed (x402-foundation/x402#2112)
bazaar-ext-inside-accepts	warn	Bazaar 扩展在 accepts 条目内声明	observed (ours, 2026-08-14)

同时也是 MCP 服务

无状态 Streamable HTTP，路径为 POST /mcp。提供三种工具：

工具	功能
probe_x402_endpoint	对某个 URL 运行诊断
explain_defect	按 id 查看某项检查的完整说明
list_checks	查看包含来源信息的完整规则表

刻意不做的事

• 它绝不会通过 facilitator 进行验证。 这样做会让你的流量经过他人的 facilitator 凭据。这里的每项检查都基于你实际返回的挑战。
• 它绝不会发送付款，也绝不会索要密钥、种子或钱包。
• 它不会评判自己不认识的网络。 无法识别的网络名称只会作为 info 提示，说明此探测工具的网络列表存在局限 — 并不代表你的网络有误。仅在已知地址格式的情况下才会应用地址格式规则。

值得了解的限制

• 正文读取到上限后，后续内容将跳过正文检查，报告会明确说明，而不会猜测结果。
• 最多跟随 3 层重定向，并在每一跳重新运行 SSRF 防护。
• 每个 IP 每小时最多 20 次请求，整体每小时最多 300 次，因为服务会获取收到的任意 URL。
• 唯一存储的数据是用于速率限制的每 IP 请求计数器，并会在两小时内过期。没有分析数据，也绝不会记录探测目标。

安全态势以及已接受而未修复的残余风险，记录在 SECURITY.md 中。

阅读和运行源代码

cd doctor
npm test          # 163 tests, no dependencies of any kind

没有运行时或开发依赖——测试套件使用 node --test。这些规则是没有 I/O 的纯函数；所有网络访问都位于 src/probe.js，SSRF 防护也在其中。

上面的托管服务可免费使用，无需许可证。源代码按与本仓库其余部分相同的条款发布，供查阅和验证：目前未授予任何许可证，保留所有权利。如果你想复用或自行托管，请联系询问。

---

由 Twelve Permissions 构建。免费，且与该网站销售的任何产品无关。