{
  "markdown": "# preflight402\n\n*One free call before your agent pays. Health, authenticity, and Sybil-filtered\nreputation — one verdict.*\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)\n![MCP](https://img.shields.io/badge/MCP-io.ironshell%2Fpreflight402-8A2BE2.svg)\n\nA free trust/health preflight for the agent payment economy (x402). It probes\nan endpoint before your agent pays and returns one `trust-preview.v1` verdict:\nliveness, TLS, the 402 handshake (x402 v1/v2 + MPP detection), price sanity,\ncontinuous uptime history, ERC-8004 identity binding, and **Sybil-filtered**\non-chain reputation — rolled into a **proceed / caution / avoid** recommendation\nwith plain-language reasons. No wallet, no key, no charge.\n\n**Why filtered reputation matters:** one live agent shows a **99.8/100 average\nfrom 996 reviewers — until Sybil filtering collapses those reviewers into 12\nindependent funding clusters at 89.7.** Raw reputation is trivially farmed;\nthis is what the verdict actually scores. (Separately, only ~4% of x402 payees\nbind to any ERC-8004 identity at all — so most verdicts run on health, price,\nand handshake, and say so honestly.)\n\n**Why \"listed\" means little:** across **7.76M probes over 15 days** of a\n51,331-endpoint catalog, **two squatting hosts account for 58% of every listed\nx402 endpoint** — one serving a uniform 404 behind a *\"This app isn't live\nyet\"* placeholder, the other a uniform Cloudflare TLS failure. Strip them out\nand **87% of real endpoints work**; measured per provider, about **one host in\nseven** (13.9%) serves no valid 402. Read the findings:\n**[What 7.8M probes say about the x402 economy](docs/findings-x402-catalog.md)**\n— including why a GET-only crawl (ours included, before we fixed it) overstates\nx402 invalidity ~2×. Full method and caveats: [docs/checkpoint-m3.md](docs/checkpoint-m3.md).\n\n## 30-second quickstart\n\nPoint any agent at the hosted MCP endpoint — no wallet, no key, no install:\n\n```\nhttps://preflight402.ironshell.io/mcp\n```\n\nOr check an endpoint over plain HTTP:\n\n```sh\ncurl 'https://preflight402.ironshell.io/preflight?url=https://api.example.com/paid'\n```\n\n## Guard every payment automatically\n\n[`preflight402-guard`](guard/) turns the service into a payment gate for the\n[x402 Python SDK](https://github.com/x402-foundation/x402) — safety becomes\ndefault-on instead of something an agent has to remember to call:\n\n```sh\npip install \"preflight402-guard[x402]\"   # PyPI publish pending; for now: pip install \"git+https://github.com/duskwire/preflight402.git#subdirectory=guard\"\n```\n\n```python\nfrom preflight402_guard import Guard\nfrom x402 import x402Client\n\nguard = Guard()          # block \"avoid\", warn on \"caution\"\nclient = x402Client()\nguard.install(client)    # every payment is preflighted before signing;\n                         # a bad verdict raises PaymentAbortedError\n```\n\nIt also cross-checks that the payee your client selected matches the endpoint\nthat was preflighted (the 402's resource URL is attacker-controlled), enforces\nan optional `max_price_usd` ceiling against the *actual* selected terms, and\nfails **open** by default so your commerce never depends on our uptime. There's\na CLI too: `preflight402-guard check <url>`. See [guard/README.md](guard/README.md).\n\n## Status\n\nLive at [preflight402.ironshell.io](https://preflight402.ironshell.io) and in\nthe [official MCP registry](https://registry.modelcontextprotocol.io) as\n`io.ironshell/preflight402`. The free preflight engine (health + 402 parse +\nverdict), continuous probing with uptime history, ERC-8004 binding, and the\nSybil filter are all shipped and serving live. The whole service is **free** —\nthere is no paywall.\n\n## Use it\n\n### As an MCP tool (no wallet, no key)\n\nThe `preflight` tool takes a `url` and returns a `trust-preview.v1` verdict.\n\nEasiest — point any MCP client at the hosted instance, no install:\n\n```\nhttps://preflight402.ironshell.io/mcp   (streamable-http)\n```\n\nOr run it yourself over stdio. Claude Code — one line (PyPI publish pending;\nuntil then point `--directory` at a clone):\n\n```sh\nclaude mcp add preflight402 -- uvx --from preflight402 preflight402-mcp\n# pre-PyPI: claude mcp add preflight402 -- uv run --directory /path/to/preflight402 preflight402-mcp\n```\n\nClaude Desktop — add to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"preflight402\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"preflight402\", \"preflight402-mcp\"]\n    }\n  }\n}\n```\n\nEither way, run it as a hosted HTTP server with\n`preflight402-mcp --transport streamable-http` (serves the same tool at\n`http://<host>:8000/mcp`).\n\n### As a REST call\n\nThe hosted instance also serves REST:\n\n```sh\ncurl 'https://preflight402.ironshell.io/preflight?url=https://api.example.com/paid'\n```\n\nOr run it yourself (serves REST + MCP on one port):\n\n```sh\nuv run uvicorn preflight402.api.app:app --port 8402\ncurl 'http://localhost:8402/preflight?url=https://api.example.com/paid'\n```\n\n## Development\n\nRequires [uv](https://docs.astral.sh/uv/).\n\n```sh\nuv sync                                        # create venv + install deps\nuv run uvicorn preflight402.api.rest:app       # serve on :8000\ncurl http://localhost:8000/healthz             # {\"status\":\"ok\",\"version\":\"0.1.0\"}\n\nuv run pytest                                  # tests\nuv run ruff check .                            # lint\nuv run ruff format --check .                   # formatting\n```\n\n## Layout\n\n```\nsrc/preflight402/\n├── api/          # REST + MCP server\n├── probe/        # async prober, TLS inspection, 402 parsers (x402 v1/v2, MPP)\n├── verdict/      # rules -> trust-preview.v1 JSON\n├── chains/       # ChainVerifier interface: EVM (Base), SVM (Solana)\n├── reputation/   # ERC-8004 subgraph client, endpoint binding, Sybil filter\n├── ingest/       # endpoint seed ingesters (Bazaar, x402scan, ...)\n├── scheduler/    # probe loop with per-host politeness\n└── db/           # SQLite (WAL) schema + queries\nguard/            # preflight402-guard: client-side auto-preflight for the x402 SDK\ntests/            # unit/ + golden/ (captured 402 responses) + integration/ (marked slow)\ndeploy/           # Dockerfile + deploy notes\ndocs/             # trust-preview.v1 schema + API docs (M8)\n```\n",
  "bytes": 6293,
  "sha": "efe0fd41daebd4e1cffb061fb767effd4ff036318f0d46c6dfa013c52608aec8",
  "repo_slug": "duskwire/preflight402",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_ironshell_preflight402_07330709/readme"
}