preflight402

preflight402

One free call before your agent pays. Health, authenticity, and Sybil-filtered reputation — one verdict.

[License: MIT] [Python 3.10+] [MCP]

A free trust/health preflight for the agent payment economy (x402). It probes an endpoint before your agent pays and returns one trust-preview.v1 verdict: liveness, TLS, the 402 handshake (x402 v1/v2 + MPP detection), price sanity, continuous uptime history, ERC-8004 identity binding, and Sybil-filtered on-chain reputation — rolled into a proceed / caution / avoid recommendation with plain-language reasons. No wallet, no key, no charge.

Why filtered reputation matters: one live agent shows a 99.8/100 average from 996 reviewers — until Sybil filtering collapses those reviewers into 12 independent funding clusters at 89.7. Raw reputation is trivially farmed; this is what the verdict actually scores. (Separately, only ~4% of x402 payees bind to any ERC-8004 identity at all — so most verdicts run on health, price, and handshake, and say so honestly.)

Why "listed" means little: across 7.76M probes over 15 days of a 51,331-endpoint catalog, two squatting hosts account for 58% of every listed x402 endpoint — one serving a uniform 404 behind a "This app isn't live yet" placeholder, the other a uniform Cloudflare TLS failure. Strip them out and 87% of real endpoints work; measured per provider, about one host in seven (13.9%) serves no valid 402. Read the findings: What 7.8M probes say about the x402 economy — including why a GET-only crawl (ours included, before we fixed it) overstates x402 invalidity ~2×. Full method and caveats: docs/checkpoint-m3.md.

30-second quickstart

Point any agent at the hosted MCP endpoint — no wallet, no key, no install:

https://preflight402.ironshell.io/mcp

Or check an endpoint over plain HTTP:

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

Guard every payment automatically

preflight402-guard turns the service into a payment gate for the x402 Python SDK — safety becomes default-on instead of something an agent has to remember to call:

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 Guardfrom 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

It also cross-checks that the payee your client selected matches the endpoint that was preflighted (the 402's resource URL is attacker-controlled), enforces an optional max_price_usd ceiling against the actual selected terms, and fails open by default so your commerce never depends on our uptime. There's a CLI too: preflight402-guard check <url>. See guard/README.md.

Status

Live at preflight402.ironshell.io and in the official MCP registry as io.ironshell/preflight402. The free preflight engine (health + 402 parse + verdict), continuous probing with uptime history, ERC-8004 binding, and the Sybil filter are all shipped and serving live. The whole service is free — there is no paywall.

Use it

As an MCP tool (no wallet, no key)

The preflight tool takes a url and returns a trust-preview.v1 verdict.

Easiest — point any MCP client at the hosted instance, no install:

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

Or run it yourself over stdio. Claude Code — one line (PyPI publish pending; until then point --directory at a clone):

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 — add to claude_desktop_config.json:

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

Either way, run it as a hosted HTTP server with preflight402-mcp --transport streamable-http (serves the same tool at http://<host>:8000/mcp).

As a REST call

The hosted instance also serves REST:

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

Or run it yourself (serves REST + MCP on one port):

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

Development

Requires uv.

uv sync                                        # create venv + install depsuv run uvicorn preflight402.api.rest:app       # serve on :8000curl http://localhost:8000/healthz             # {"status":"ok","version":"0.1.0"}
uv run pytest                                  # testsuv run ruff check .                            # lintuv run ruff format --check .                   # formatting

Layout

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 + queriesguard/            # preflight402-guard: client-side auto-preflight for the x402 SDKtests/            # unit/ + golden/ (captured 402 responses) + integration/ (marked slow)deploy/           # Dockerfile + deploy notesdocs/             # trust-preview.v1 schema + API docs (M8)