preflight402

preflight402

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

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](docs/findings-x402-catalog.md) — 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 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

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 . 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:// :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 8402

curl 'http://localhost:8402/preflight?url=https://api.example.com/paid'

Development

Requires 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

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