A check that runs after the signature is an audit. A check that runs before it is a gate. The difference is one line of control flow, and it is the only line that matters.
This is the shortest version that is still honest: install the server, call the gate on the intent, and wire the refusal so that a BLOCK cannot reach the signer. Everything below runs against the free tier.
Step 1 — run it
npx -y verify402-mcp
Without EVM_PRIVATE_KEY the bridge starts in free-only mode. It registers three tools and nothing else:
- preflight_gate — the gate itself, for a payment challenge or an EVM transaction.
- inspect_402 — read any public 402 before you pay it.
- directory_402 — the watched list of public x402 endpoints.
None of the three can spend. The five paid measurement tools only appear when a wallet is configured, which is a separate decision you do not need to make today.
Step 2 — add it to the client
Claude Desktop reads claude_desktop_config.json. Cursor reads .cursor/mcp.json. The block is the same:
{
"mcpServers": {
"verify402": {
"command": "npx",
"args": ["-y", "verify402-mcp"],
"env": {
"VERIFY402_URL": "https://vex402.online"
}
}
}
}
Restart the client. The three tools appear in the model's tool list. If you want to run your own instance instead of the public one, point VERIFY402_URL at it — the receipt is signed by whichever instance answered, so pinning the URL is pinning the trust boundary.
Step 3 — call the gate on the intent you are about to sign
The gate takes the decoded intent, not a summary of it. For an x402 payment, that means the fields out of the challenge itself:
preflight_gate({
kind: "payment",
chainId: 84532,
from: "0xYourAgentWallet",
payment: {
scheme: "exact",
network: "eip155:84532",
asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
amount: "50000",
payTo: "0xAeEF086DD4e436c69d6d0F684b4c9F4332df9cb",
resource: "https://vex402.online/verify",
maxTimeoutSeconds: 300
},
policy: {
maxAmountUsd: 0.10,
allowedNetworks: ["eip155:84532"],
expectedResource: "https://vex402.online/verify"
}
})
It returns a verdict, the reasons behind it, the list of checks that ran, the list that did not, and a receipt. For a transaction intent, send kind: "transaction" with to, data and an optional value instead of payment.
Pass policy or you get structural checks only. A structural PASS on an intent with no policy says the shape is coherent, not that it matches what you wanted.
Step 4 — make the signature depend on it
Calling the tool from a prompt is not enforcement. A model can skip a tool call; it cannot skip a function you removed from the path. Two ways to wire it, depending on whether you hold the signer directly.
If you call the signer yourself
The reference guard is examples/preflight-guard.mjs in the repository. It is not in the npm tarball — copy it into your project, or read it and write the twenty lines yourself. It runs the gate, verifies the receipt, and returns only after both bindings match. On BLOCK it throws PreflightBlockedError, so the line after it never runs.
// copied from examples/preflight-guard.mjs in the repository
import { guardX402Payment } from "./preflight-guard.mjs";
const { verdict, receipt } = await guardX402Payment({
paymentRequired: challenge,
policy: { maxAmountUsd: 0.10, allowedNetworks: ["eip155:84532"] },
from: wallet.address,
acknowledgeCaution: false
});
// unreachable on BLOCK, on an unverified receipt, or on an expired one
const signature = await wallet.signTypedData(receipt.intent, domain, types);
If you use the x402 client SDK
createX402PreflightHook() returns a hook for onBeforePaymentCreation. It blocks on BLOCK, refuses CAUTION unless you set acknowledgeCaution, verifies the receipt, and attaches it to context.verify402 before the SDK can sign.
// copied from examples/preflight-guard.mjs in the repository
import { createX402PreflightHook } from "./preflight-guard.mjs";
client.onBeforePaymentCreation(createX402PreflightHook({
policy: { maxAmountUsd: 0.10, allowedNetworks: ["eip155:84532"] },
from: account.address,
onBlocked: (e) => console.error("blocked:", e.message)
}));
What the guard actually enforces
- BLOCK — throws. The signer is not called.
- CAUTION — throws unless you passed
acknowledgeCaution: true. A warning that is silently ignored is not a warning. - No receipt, or an expired one — throws. The default lifetime is 90 seconds.
- Receipt bound to different bytes — throws. The request hash is recomputed locally, so a receipt that names another intent cannot be reused.
- Gate unreachable — throws. It fails closed, not open.
There is deliberately no verify: false switch. A caller-controlled option that can reach the signer without the checks would be the first thing an injected prompt turns off.
The mistakes that make it theatre
- Calling the gate after signing. That is a log line. Useful, not a gate.
- Treating a structural PASS as a policy PASS. No policy, no comparison — only coherence.
- Reusing a receipt across intents. It is bound to one request; a second intent needs a second call.
- Swallowing the error to "keep the agent running". Then the gate is decoration and the next failure is irreversible.
- Reading only the verdict.
notCheckedis the part that tells you what the PASS did not cover.
What it costs
The gate is free, and it has to be: a check that runs before every signature cannot have a per-call price. The receipt is short-lived by design. The five paid measurements — arbitrage, token safety, route, quote fairness, depth — are separate tools, off unless you configure a wallet, and priced per call in testnet USDC on the public demo.
Try to break it
Run a payment you expect to pass. Then change payTo, the asset, or the resource host and run it again. If a swapped version still passes, that is the finding worth reporting — and it is exactly the kind of thing the tester kit exists for.
The ask
Wire it, then send three intents.
One you expect to pass, one you are unsure about, one you think should be blocked. I will run all three and reply with the raw verdict and the reason codes.
Previous: Check an x402 endpoint before you pay it. · All notes