Preflight a payment (allow / hold / block)
preflight_paymentUse when you are about to sign an x402 payment for allow, hold or block, reasons and a signed decision receipt. Covers payee sanctions screening, spending rules and cached price/recipient evidence where available. For separate evidence, use lint_endpoint/listing_guard for technical seller-metadata checks, verify_payee_binding for ERC-8478 registry-to-wallet binding, and payment_receipt for a native Base USDC transfer observation after payment. These tools have separate scopes and may have separate charges; Preflight does not execute them automatically or verify delivered API content. A transfer receipt is not delivery proof, wallet binding is not seller-safety proof, and an allow decision does not grant payment authority. Call this before any x402/USDC payment to evaluate the actual challenge or cart before signing. Spend preflight for AI agents. Send the x402 PaymentRequired body (v1 or v2) you received, or a cart, plus optional rules (per-payment max, hold threshold, daily cap, allowlists, new-domain days, endpoint category price multiple, liveness and payTo changes). Returns allow|hold|block with reasons, the cheapest acceptable payment option, and a receipt id. Read-only: never signs, settles, or holds funds. Use before every payment. It includes payee screening in its spending-rule decision. For standalone wallet, name, or domain screening without a payment, use check_payee instead. Each repeat call creates a new receipt and may consume another trial or paid call. Price $0.02 per call (free trial first). Price: 0.02 USDC. Minimal input example: {"cart":{"merchant_name":"Example Shop LLC","total_usd":0.01},"rules":{"max_per_payment_usd":1},"spent_today_usd":0}. Illustrative output excerpt: {"decision":"hold","reasons":["hold: missing fresh index evidence"],"chosen_option":null,"options_evaluated":0,"payee":null,"index_evidence":{"status":"unknown","observed_at":null,"note":"Missing evidence remains unknown."},"receipt":{"id":"illustration","ts":"2026-10-30T00:00:00Z","input_sha256":"0000000000000000000000000000000000000000000000000000000000000000","decision":"hold","jws":"illustrative-not-a-live-signature"}}. Illustrative output excerpt, not a live result, signature, approval or guarantee. Freshness/data/availability checks still apply. How to pay (MCP): First use the existing shared allowance of 3 eligible calls per IP per UTC day, without payment metadata. This is shared with eligible HTTP trials, not a new allowance. Use an x402-capable MCP client. A generic MCP connector without payment support cannot complete a paid continuation. On payment required, STOP. Inspect the exact accepts amount, asset, network and payTo; obtain explicit wallet/budget approval before continuing. Only after approval, let the configured x402 MCP client attach its signed payload in _meta["x402/payment"] and retry the same tools/call arguments. Never send a separate USDC transfer or paste keys into tool arguments. Never silently fall back from free access to payment. If a signed attempt has an unknown outcome, inspect that authorization/transaction; do not create another automatically.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "preflight_payment"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cart | No | Optional. Checkout JSON object used instead of challenge; provide exactly one. Example: {"merchant_domain":"example.com","total_usd":1.25,"pay_to":"0xBf4164e07552e4c1b1B1597E72C7acAA3F0a1c58"}. total_usd is a USD number. | |
| rules | No | Optional. Spending-rule JSON object; omitted fields use service defaults available from get_service_info. Example: {"max_per_payment_usd":5,"usdc_only":true}. USD amounts are numbers, not atomic strings. | |
| challenge | No | Optional. Actual x402 HTTP 402 PaymentRequired JSON object, version 1 or 2. Required unless cart is supplied; provide exactly one. Example structure: {"x402Version":2,"resource":{"url":"https://api.example.com/data"},"accepts":[{"scheme":"exact","network":"eip155:8453","asset":"0x833589fcd6edb6e08f4c7c32d4f71b54bda02913","payTo":"0xBf4164e07552e4c1b1B1597E72C7acAA3F0a1c58","amount":"10000","maxTimeoutSeconds":60}]}. Amounts inside challenges are atomic integer strings (10000 = 0.01 USDC at 6 decimals), not decimal USDC. | |
| resource_url | No | Optional. Absolute HTTP(S) resource URL string. Example: https://api.example.com/data. Supply if the resource URL is absent from the challenge or requirement. | |
| resource_method | No | Optional. Advertised HTTP method string, 3–16 letters. Example: POST. Supply when an indexed URL has multiple methods. | |
| spent_today_usd | No | Optional. Already-spent daily total as a nonnegative USD number. Example: 2.5. Caller-supplied context for the daily cap. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| payee | No | Payee screening details | |
| reasons | Yes | Every rule that fired, prefixed with its decision | |
| receipt | Yes | Signed decision; keep privately for audit | |
| decision | Yes | Allow only within your approved budget, ask a human on hold, never pay on block | |
| chosen_option | No | The cheapest acceptable payment option | |
| index_evidence | Yes | ||
| options_evaluated | Yes |