01 · The handshake
Ask, get 402, pay, retry once.
First call without payment. The service answers 402 Payment Required with everything your agent needs: scheme, network, asset, amount, recipient, and the per-call cap.
1 · Ask without paying
curl -X POST https://vex402.online/verify \
-H "Content-Type: application/json" \
-H "x-idempotency-key: 3f2c7a1e-5b8d-4c6f-9a4e-7b2d9c1f6a3e" \
-d '{"pair":"USDC/WETH","dex":"uniswap-v3","sizeUsd":100000}'
# → HTTP 402 Payment Required
# accepts: eip155:84532 (Base Sepolia testnet USDC) or solana:EtWTR… (devnet USDC)
# payTo, amount, maxTimeoutSeconds; the 402 challenge is authoritative
2 · Pay and retry with proof
# x402 clients (e.g. @x402/fetch) do this automatically:
# read the 402 → sign the exact payment → retry with PAYMENT-SIGNATURE
# (x402 v2; the legacy X-PAYMENT header is also accepted)
# The retry returns the verdict with an evidence_bundle.
Send x-idempotency-key on the first call
If the connection dies after settlement, the retry with the same key replays the same bytes for free — within ten minutes, three replays max. Use crypto.randomUUID() or at least 32 URL-safe random characters with at least 16 distinct characters; weak keys are rejected with 400 weak_idempotency_key. The key is a secret: anyone who has it can replay the settled verdict until the window or cap closes. It does not prove payment or survive a process restart.
02 · Receipts
Every paid response can be rechecked.
The response carries an evidence bundle so a third party can recompute the measurement without trusting the service: the hash of the canonical request, the hash of the actual response body, and the pinned block.
| Field | What it proves |
| requestHash | This exact request was the one answered — canonical bytes, not a paraphrase |
| responseHash | The exact bytes returned; a replay that doesn't match isn't free |
| pinnedBlock | The chain state the answer describes. Everything is a quote about one block. |
| verdict | edge, no_edge, or no_edge_costs_ate_it |
The recovery contract, in one paragraph
A settlement is staged, not recorded, when payment succeeds. It is promoted only by the official onAfterSettle hook, keyed on a server-generated operationId carried in the response and requiring a confirmed settle with a transaction reference — with the hash of the actual response bytes as an additional check. Equal output does not identify an operation: two requests that both return no_match are still distinct, and settling one never promotes the other. A failed or pending settlement promotes nothing; staged-unpromoted records age out silently after five minutes; the replay cap is per operation, bound to the caller's key. Reusing a key with changed request content is a 409 conflict resolved before the paywall — never the other operation's answer, never a charge. A concurrent same-key request is also a 409 (operation_in_flight, or settlement_pending while a staged settlement is unresolved), issued before the paywall. The reservation is in-process and lost on restart unless the operator runs a durable store (RECOVERY_DB_PATH), in which case the staged record survives the restart and stays unreplayable until reconciliation resolves it. The original idempotency key is the only replay credential; no payer identity is read from x-payment or authorization.from, and the old content-hash companion alias has been removed. The key is a bearer secret: a leaked key allows replay until the TTL/replay cap, and recovery does not prove payment; durability covers the verdict record and its replay budget only, and only when the operator configures a durable store. Two parts of this were broken in public by an independent auditor and fixed the same day: commit 4bf3c9c, then hardened after the x402 spec review (#3848).
03 · Before you sign
One free gate, one short-lived receipt.
POST /preflight is free. Give it an x402 payment request or a chain transaction; it returns PASS / CAUTION / BLOCK, typed reasons, the checks that actually ran, and the checks that did not. Every response carries an HMAC-signed receipt bound to the exact normalized intent, the exact request body, and, where the chain is readable, a fresh pinned block. On EVM, a block older than 30s is CAUTION; older than 120s is BLOCK; a block with no timestamp is a 503. requestHash is additive within @1: receipts issued before it existed stay signature-valid but are not caller-bound, and a supplied request verifies with missing_request_hash. A missing intentHash returns missing_intent_hash. The reference executor requires both intentBound and requestBound; receipt-only verification remains compatible but reports both as false.
Use it from an agent: verify402-mcp exposes the gate (no wallet) and the five paid checks (hot wallet, per-call x402) over MCP.
| Intent | What it needs | What it checks |
| payment | network, asset, amount, payTo, resource | scheme, CAIP-2 network, payment asset (canonical USDC, or another recognized dollar stable named in the token registry), amount/policy cap, payee allowlist, resource URL, resource host/exact match when policy binds it, timeout, authorization window, payer balance on EVM, EVM block freshness; seller payout binding and caller-supplied obligation state when provided |
| transaction | chainId (EVM 1/42161/8453), to, data, value, from | recipient, calldata decode, contract bytecode, approval/spender policy, swap deadline/minOut/recipient, eth_call simulation, EVM block freshness |
Optional caller-supplied checks: payment.idempotencyKey + policy.obligation.settledKeys rejects an already-settled key; policy.obligation.spentUsd + grantUsd rejects cumulative spend over the grant. policy.sellerPayoutWallets is only a payout allowlist; policy.sellerPayoutManifest fetches a seller-signed manifest from a caller-pinned HTTPS origin and is the only source of payee_payout_binding. The gate does not persist this state, and neither form independently proves the seller controls the wallet.
Payment request · abbreviated
curl -X POST https://vex402.online/preflight \
-H "Content-Type: application/json" \
-d '{
"kind": "payment",
"from": "0xYourWallet",
"payment": {
"scheme": "exact",
"network": "eip155:84532",
"asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
"amount": "10000",
"payTo": "0xAeEF086DD4e436c69d6d0F684b4c9F43392df9cb",
"resource": "https://vex402.online/verify"
},
"policy": { "maxAmountUsd": 0.25, "allowedResourceHosts": ["vex402.online"] }
}'
Response
{ "verdict": "PASS", "sign_allowed": true, "requires_ack": false,
"checked": ["scheme", "network", "asset", "amount", "payee", "payer_balance"],
"notChecked": ["recipient reputation", "sanctions screening", "counterparty identity / tool metadata", "prompt injection / hidden Unicode in tool output"],
"receipt": { "spec": "verify402/preflight-receipt@1", "intentHash": "…", "requestHash": "…",
"blockNumber": 48277717, "signature": "…" } }
Verify before you trust the receipt
POST /preflight/verify with {"receipt":{…},"request":{…}} recomputes the HMAC, checks the expiry, and re-hashes the caller's original request (and optional normalized intent). No chain call. A CAUTION is an explicit decision, not a pass; a BLOCK is a refusal. If the chain cannot be read, /preflight returns 503 and issues no receipt, so the executor must fail closed. Reference executor: examples/preflight-guard.mjs — it refuses to call your signer without a verified receipt.