SpendPreflight

SpendPreflight

Call preflight_payment before signing an x402 payment. Get allow, hold or block, reasons and a signed decision receipt; enforce the decision within your approved wallet and budget. Preflight combines payee screening, spending rules and cached price/recipient evidence where available. ERC-8478 wallet binding remains a separate verify_payee_binding call.

About to pay? Start with Preflight. Selling via x402? Start with free Lint and monitoring.

Three runnable examples: a guarded x402 client, Claude Code / Cursor MCP setup, and seller CI. The examples run offline by default; no payment or live probe is needed to try them.

MCP core tools appear first: preflight_payment, check_payee, lint_endpoint, check_token, payment_receipt. Free get_service_info groups the complete enabled catalog into Buyers, Sellers, Books and Data APIs. All products and prices remain available in the catalog; solar and FillPoint have their own Data APIs page.

Spend Policy (free)

SDK 0.4.0 includes a free JSON policy helper for daily and per-call caps, merchant allow/block lists, hold thresholds and exact network/asset pairs. Try the offline example; the existing remote preflight service fee is separate.

JSON configuration

createSpendPolicy(policy) adds an explicit JSON configuration to the existing local guard. It supports daily/per-call caps, a hold threshold, merchant payTo allow/block lists, and exact network/asset pairs. parseSpendPolicy(unknown) rejects extra or misspelled fields and unsupported valuations. Limits use USDC face value with at most six decimal places; this helper supports the SDK's known native-USDC deployments, not arbitrary-token USD prices. Merchant addresses are policy identifiers, not verified identities.

import { createSpendPolicy } from 'spendpreflight';

const policy = { version: 1, dailyCapUsd: 5, maxPerCallUsd: 0.25, holdAboveUsd: 0.10, merchantAllowlist: ['0x1111111111111111111111111111111111111111'], merchantBlocklist: [], networkAllowlist: ['eip155:8453'], assetAllowlist: [{ network: 'eip155:8453', asset: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913' }] }; const controller = createSpendPolicy(policy); // offline by default // controller.evaluate(challenge, selectedRequirement, spentTodayUsd): local preview // await controller.check(challenge, selectedRequirement): holds without remote preflight

Replace the illustrative recipient with an explicitly approved merchant. Empty allowlists deny all matching payments; blocklists win. Select an unmodified exact requirement from the x402 v2 challenge. evaluate is free and pure, and its caller-supplied spend value is only preview context. Its local allow is not payment authorization.

For the actual payment path, create one long-lived controller with explicit remote options, then call controller.attach(yourX402Client) before signing. For example, createSpendPolicy(policy, { remote: { fetch: separatelyGuardedScreeningFetch } }). The helper runs local gates first and calls the existing /v1/preflight equivalent of MCP preflight_payment only for locally allowed requests. Plain fetch does not pay; a 402, malformed result, timeout or failure holds. Holds and blocks abort, with no fail-open mode or automatic hold approval. A same-controller recursive screening payment is rejected. No account, new route, key or package fee is introduced; the existing remote preflight service fee is separate.

check returns the combined allow/hold/block decision and reasons, with the remote receipt ID when present. An allowed check reserves the selected amount before returning. Use either attach for the real client hook or a correctly integrated manual check; do not call both for the same attempt. The hook rejects requirements changed during preflight. This package never signs, settles, fetches the merchant target or moves funds.

Reservations are conservative and in-process per controller, per UTC day, not a settlement ledger or wallet-wide budget. Allowed but abandoned/failed attempts retain reservations. Concurrent checks share the same queue; backward clocks do not reset it. Restarting or creating another controller starts another budget, so use wallet-level or durable shared controls across restarts, processes and devices. Do not reuse a returned verdict for another attempt or mutate requirements after the gate. The separate screening client's fees need their own bounded policy/budget and are not included in the merchant controller's cap.

Run the offline example after npm run build: node examples/spend-policy.mjs. It prints a local preview, an offline hold, and mock-only reservation decisions. It performs no live API call, trial, target request or payment.

Remote tools

• Draft ERC-8478 Payee Verification: remote MCP verify_payee_binding or POST /v1/payee-binding, 0.01 USDC with the existing shared trial. Signed JSON reports exactly one of nine outcomes at a pinned registry block; not-read is uncharged. Checks direct agent-wallet equality or EIP-712 delegation, including ERC-1271, rotation and expiry. An observation is not payment approval. Base first, plus public Robinhood reads; the Draft may change.

• x402 Security Check: free passive coverage in Lint; an optional full report from a current complete saved Lint snapshot costs 0.10 USDC, with no new probe or shared trial. Replay protection, paid caching and settlement behavior remain unknown without controlled evidence.
• Quote Check: compare a supplied exact quote with cached public evidence; 0.001 USDC for a usable comparison, unknown without charge, no shared trial. No target request or automatic payment approval.
• Seller Index: top three cached public matches free; extended results up to 12 cost 0.01 USDC only if additional matches exist. Missing ranking evidence remains unknown; no crawl or safety certification.

Read the announcement and tool-selection guide. These are operated remote-service tools; this metadata update does not publish a new npm package or enable automatic payments.

Historical Quote Check before signing

createQuoteCheckHook attaches to onBeforePaymentCreation. It compares the selected exact-scheme quote with a dated cached public unpaid quote, never requests the merchant, and aborts on above_expected, payTo_changed, unknown or an error. ok only means the supplied amount is not above the last comparable observation with the same recipient; it is not payment approval or loss prevention. Keep the local guard for allowlists, per-payment limits and its in-process daily budget.

import { createQuoteCheckHook, guard } from 'spendpreflight';

// comparisonFetch is a SEPARATE locally guarded x402 fetch configured by you. // It can pay the comparison API's $0.001 fee; no shared trial or auto-renewal. client.onBeforePaymentCreation(createQuoteCheckHook({ fetch: comparisonFetch })); guard(client, { remote: false, rules: { maxPerPaymentUsd: 0.10, dailyCapUsd: 1 } });

Without an explicitly supplied paid fetch, plain fetch stops at the 402 offer. The same client cannot pay its own hook fee: recursion is rejected before signing. Missing/stale/ambiguous history returns unknown without a charge. No automatic retry, target refresh, signature replay or application of a suggested cap occurs. The informational suggested_max_amount_per_payment uses atomic units for the stated asset/network and expires with the cached observation; it is not a personal budget. Use quoteCheck(input, options) for a standalone comparison, or signed GET /quote-check / MCP quote_check. URL and quote fields are sent transiently to the comparison API; do not use private URLs or query secrets.

SpendPreflight — trust and verification tools for stablecoin payments, built for AI agents and the people who run them.

Product catalog · Trust and privacy

Allow, hold or block every x402 payment before your agent pays.

Maintained by the operator of SpendPreflight, the optional paid screening API linked below.

Drop-in spend guard for the official x402 client (@x402/core, @x402/fetch, @x402/axios). It checks each payment *before anything is signed*:

• Local rules (free): per-payment max, hold threshold, daily cap, network and asset checks (USDC only by default), and domain or payTo allow/blocklists.
• Remote screening (optional): an OFAC sanctions screen of the payee wallet and a new-domain check via the SpendPreflight API, at $0.02 per check over x402, or free on the trial.

A blocked payment is aborted before signing. A hold goes to your onHold callback, or is denied. Every decision is passed to onDecision so you can log it.

npm i spendpreflight @x402/fetch @x402/evm viem

import { x402Client, wrapFetchWithPayment } from "@x402/fetch";

import { ExactEvmScheme } from "@x402/evm/exact/client"; import { privateKeyToAccount } from "viem/accounts"; import { guard } from "spendpreflight";

const account = privateKeyToAccount(process.env.AGENT_KEY as 0x${string}); const client = new x402Client().register("eip155:8453", new ExactEvmScheme(account)); const pay = wrapFetchWithPayment(fetch, client);

guard(client, { rules: { maxPerPaymentUsd: 1, holdAboveUsd: 0.25, dailyCapUsd: 20 }, remote: false, // local rules; separate screening client shown below onHold: async v => askHuman(v), // return true to approve onDecision: v => console.log(v.decision, v.reasons, v.receiptId), });

const res = await pay("https://api.some-paid-service.com/data"); // guarded

Try it without paying

guard(client, { remote: { trial: true } }); // 3 free remote checks per day per IP

Or use local rules only, with no network call:

guard(client, { remote: false });

Framework examples

Copy-paste examples maintained by the operator of SpendPreflight:

• Vercel AI SDK tool: POST a merchant's 402 challenge and rules to /v1/preflight before paying ($0.02 screening fee).
• LangChain JS check_payee tool: screen a wallet/name/domain ($0.01 screening fee).
• OpenAI Agents SDK tool: a typed preflight tool with explicit error propagation ($0.02 screening fee).
• Plain x402 fetch + guard: enforce free local spending rules before signing, with no caller account or API key.

See setup and safety notes. The screening tools never pay the merchant under review. Enforce decisions in the actual payment client; a model selecting a tool alone is not a spending gate. Tests use local mocks and throwaway signers, with no paid calls.

Decisions

| hold | onHold(verdict) decides; denied if you don't provide one | Above hold threshold, domain not on allowlist, new domain