preflight402

preflight402

在 Agent 付款前，提供一次免费调用。健康状况、真实性和经过 Sybil 过滤的声誉——一个判定。

面向 Agent 支付经济（x402）的免费信任／健康预检。在 Agent 付款前探测端点，并返回一个 trust-preview.v1 判定：存活状态、TLS、402 握手（x402 v1/v2 + MPP 检测）、价格合理性、持续在线历史、ERC-8004 身份绑定，以及经过 Sybil 过滤的链上声誉——汇总为继续／谨慎／避免的建议，并附上通俗易懂的理由。无需钱包、密钥，也不收费。

**为什么过滤后的声誉很重要：**某个在线 Agent 显示 996 位评价者的平均分为 99.8/100——但经过 Sybil 过滤后，这些评价者会被归并为 12 个独立资金集群，评分降至 89.7。 原始声誉极易刷高；判定实际评分时依据的就是过滤结果。（此外，只有约 4% 的 x402 收款方绑定了任何 ERC-8004 身份——因此，大多数判定只依据健康状况、价格和握手情况，并会如实说明。）

为什么“已列出”意义不大：在一个包含 51,331 个端点的目录中，15 天内共进行了 776 万次探测，结果显示，两个蹲占域名的主机占所有已列出的 x402 端点的 58%——其中一个在 “此应用尚未上线” 占位页后统一返回 404，另一个则统一出现 Cloudflare TLS 故障。排除它们后，87% 的真实端点都能正常工作；按提供方统计，约每七台主机中有一台（13.9%）无法提供有效的 402 响应。查看调查结果： 780 万次探测揭示的 x402 经济现状 ——其中也解释了为什么仅使用 GET 的爬取（包括我们修复问题前的爬取）会将 x402 无效率夸大约 2 倍。完整方法和注意事项：docs/checkpoint-m3.md。

30 秒快速开始

将任意 Agent 指向托管 MCP 端点——无需钱包、密钥或安装：

https://preflight402.ironshell.io/mcp

也可以通过普通 HTTP 检查端点：

curl 'https://preflight402.ironshell.io/preflight?url=https://api.example.com/paid'

自动守护每笔付款

preflight402-guard 可将此服务变为 x402 Python SDK 的付款关卡——安全默认启用，无需 Agent 记得手动调用：

pip install "preflight402-guard[x402]"   # PyPI publish pending; for now: pip install "git+https://github.com/duskwire/preflight402.git#subdirectory=guard"

from preflight402_guard import Guard
from x402 import x402Client

guard = Guard()          # block "avoid", warn on "caution"
client = x402Client()
guard.install(client)    # every payment is preflighted before signing;
                         # a bad verdict raises PaymentAbortedError

它还会交叉核对客户端选定的收款方是否与预检端点匹配（402 的资源 URL 由攻击者控制），根据实际选定的条款执行可选的 max_price_usd 上限，并默认采用失败开放策略，确保你的交易服务不会依赖我们的在线状态。它也提供命令行工具：preflight402-guard check <url>。请参阅 guard/README.md。

状态

服务已在 preflight402.ironshell.io 上线，并收录于官方 MCP 注册表，名称为 io.ironshell/preflight402。免费的预检引擎（健康状况 + 402 解析 + 判定）、持续探测与在线历史、ERC-8004 绑定以及 Sybil 过滤器均已发布并投入实际服务。整个服务免费——没有付费墙。

使用方法

作为 MCP 工具（无需钱包或密钥）

preflight 工具接收一个 url，并返回 trust-preview.v1 判定。

最简单的方法——将任意 MCP 客户端指向托管实例，无需安装：

https://preflight402.ironshell.io/mcp   (streamable-http)

也可以通过 stdio 自行运行。Claude Code——只需一行（PyPI 发布尚未完成；在此之前，请将 --directory 指向克隆目录）：

claude mcp add preflight402 -- uvx --from preflight402 preflight402-mcp
# pre-PyPI: claude mcp add preflight402 -- uv run --directory /path/to/preflight402 preflight402-mcp

Claude Desktop——将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "preflight402": {
      "command": "uvx",
      "args": ["--from", "preflight402", "preflight402-mcp"]
    }
  }
}

无论采用哪种方式，都可以将其作为托管 HTTP 服务运行：preflight402-mcp --transport streamable-http（在 http://<host>:8000/mcp 提供相同的工具）。

作为 REST 调用

托管实例也提供 REST 服务：

curl 'https://preflight402.ironshell.io/preflight?url=https://api.example.com/paid'

也可以自行运行（在同一个端口上提供 REST + MCP）：

uv run uvicorn preflight402.api.app:app --port 8402
curl 'http://localhost:8402/preflight?url=https://api.example.com/paid'

开发

需要安装 uv。

uv sync                                        # create venv + install deps
uv run uvicorn preflight402.api.rest:app       # serve on :8000
curl http://localhost:8000/healthz             # {"status":"ok","version":"0.1.0"}

uv run pytest                                  # tests
uv run ruff check .                            # lint
uv run ruff format --check .                   # formatting

目录结构

src/preflight402/
├── api/          # REST + MCP server
├── probe/        # async prober, TLS inspection, 402 parsers (x402 v1/v2, MPP)
├── verdict/      # rules -> trust-preview.v1 JSON
├── chains/       # ChainVerifier interface: EVM (Base), SVM (Solana)
├── reputation/   # ERC-8004 subgraph client, endpoint binding, Sybil filter
├── ingest/       # endpoint seed ingesters (Bazaar, x402scan, ...)
├── scheduler/    # probe loop with per-host politeness
└── db/           # SQLite (WAL) schema + queries
guard/            # preflight402-guard: client-side auto-preflight for the x402 SDK
tests/            # unit/ + golden/ (captured 402 responses) + integration/ (marked slow)
deploy/           # Dockerfile + deploy notes
docs/             # trust-preview.v1 schema + API docs (M8)