Preflight is a single, open, pre-payment verdict for one x402 seller, the check an agent runs before it hits the 402. This page defines the contract: what the verdict means, what goes into it, and how to act on it. It is free to adopt, attribution appreciated.
The verdict
One light, with a human label and a rule for what an agent should do:
- CLEAR
green: nothing alarming found. Safe to pay on payment-safety grounds. Not a promise the goods are worth buying. - HOLD
yellow: payable, but resolve the reasons first (a live quote that disagrees with the listing, or a paid call that came up short). - ABORT
red: do not pay without checking the live 402. The address or the goods have failed before. - UNRATED
gray: no data yet. Absence is not a bad sign, but nothing has been verified.
The machine value is light (green / yellow / red / gray); CLEAR / HOLD / ABORT is only its label. A score from 0 to 100 accompanies it for a numeric gate.
What goes into it
The verdict folds four independent signals, each measured, none sponsored:
- Payment safety: does the live 402 price match the listing, does the live payTo match the listing, is the paywall real. From probing the whole directory, free.
- Delivery: has a paid call to this host come up short of its promised fields, confirmed on two calls. From the receipts.
- Demand realness: does its on-chain revenue come from many wallets or one, and does most of it leave again. Context, does not move the light.
- Free upstream: is this a category an agent can get for nothing (an exchange price, weather, a chain read, a web search). Informational, does not move the light.
The one rule for a red light
ABORT is a strong claim, so it fires only from evidence that money or goods have actually gone wrong, never a soft signal: a payTo that disagrees with the listing, a phantom paywall (a price quoted for a route that cannot exist), or a reverified severe underdeliver (paid in full and returned none of two or more promised fields, confirmed on two calls). Demand and free-upstream flags are context and never turn a light red.
How an agent uses it
Call preflight(url) on the MCP server, or GET the host out of /api/preflight.json. Gate the payment on the light: pay on CLEAR, resolve the reasons on HOLD, refuse on ABORT. Then, whatever the verdict, read the payTo and the amount out of the live 402 on every call and sign against those, never a listing. A verdict is a prior, not a substitute for reading the challenge you are about to pay.
The shape of a verdict
A real ABORT verdict, in full:
{
"host": "api.k8s-dev.blockscout.com",
"light": "red",
"score": 10,
"confidence": "checked",
"confidence_basis": "free live checks only (live price and payTo vs the listing); not yet paid",
"reasons": [
{
"level": "red",
"text": "Its live payment address does not match its listing. Money would go to an address the directory does not name."
},
{
"level": "red",
"text": "Phantom paywall: it returns a priced 402 for routes that cannot exist, which means its payment middleware runs before route validation. A quote is not evidence of a real endpoint, and a paid call to a wrong route may settle and return nothing."
},
{
"level": "info",
"text": "Not yet bought from, so delivery is unverified. Absence of a grade is not a bad grade."
}
],
"checked_live": true,
"receipts": 0,
"settled_payments": 0,
"disputes": 0,
"delivered": 0,
"accurate": 0,
"history": null,
"free_alternative": null,
"page": false
}