Skip to main content
Glama

Preflight a payment (allow / hold / block)

preflight_payment
Read-only

Use 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

NameRequiredDescriptionDefault
cartNoOptional. 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.
rulesNoOptional. 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.
challengeNoOptional. 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_urlNoOptional. 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_methodNoOptional. Advertised HTTP method string, 3–16 letters. Example: POST. Supply when an indexed URL has multiple methods.
spent_today_usdNoOptional. Already-spent daily total as a nonnegative USD number. Example: 2.5. Caller-supplied context for the daily cap.

Output Schema

NameRequiredDescriptionDefault
payeeNoPayee screening details
reasonsYesEvery rule that fired, prefixed with its decision
receiptYesSigned decision; keep privately for audit
decisionYesAllow only within your approved budget, ask a human on hold, never pay on block
chosen_optionNoThe cheapest acceptable payment option
index_evidenceYes
options_evaluatedYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed25 schema fields changed
    • changedInput schema / properties / cart / description
      Previous value: -"Use instead of challenge for agent checkout / card payments"New value: +"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."
    • addedInput schema / properties / cart / properties / merchant_domain / description
      Added value: +"Optional. Merchant hostname or URL string. Example: shop.example.com. Omit if unknown."
    • addedInput schema / properties / cart / properties / merchant_name / description
      Added value: +"Optional. Merchant legal-name string. Example: Example Trading Ltd. Omit if unknown."
    • addedInput schema / properties / cart / properties / pay_to / description
      Added value: +"Optional. Recipient address string. Example: 0xBf4164e07552e4c1b1B1597E72C7acAA3F0a1c58."
    • addedInput schema / properties / cart / properties / total_usd / description
      Added value: +"Optional. Cart total as a nonnegative USD number. Example: 1.25. Omit if unknown; do not supply atomic units."
    • changedInput schema / properties / challenge / description
      Previous value: -"The x402 PaymentRequired body (v1 or v2) your agent received with HTTP 402"New value: +"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."
    • changedInput schema / properties / resource_method / description
      Previous value: -"Advertised method for an indexed URL with multiple methods"New value: +"Optional. Advertised HTTP method string, 3–16 letters. Example: POST. Supply when an indexed URL has multiple methods."
    • changedInput schema / properties / resource_url / description
      Previous value: -"URL that returned the 402, if not inside the challenge"New value: +"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."
    • changedInput schema / properties / rules / description
      Previous value: -"Spending rules; all optional. See get_service_info for defaults."New value: +"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."
    • addedInput schema / properties / rules / properties / allowed_networks / description
      Added value: +"Optional. Array of allowed network identifier strings. Example: [\"eip155:8453\"]. Omit to use the service default."
    • addedInput schema / properties / rules / properties / daily_cap_usd / description
      Added value: +"Optional. Nonnegative daily spending cap number in USD. Example: 20. Omit to use the service default."
    • addedInput schema / properties / rules / properties / domain_allowlist / description
      Added value: +"Optional. Array of allowed merchant hostname strings. Example: [\"example.com\"]. Omit to use the service default."
    • addedInput schema / properties / rules / properties / domain_blocklist / description
      Added value: +"Optional. Array of blocked merchant hostname strings. Example: [\"blocked.example\"]. Omit to use the service default."
    • addedInput schema / properties / rules / properties / hold_above_usd / description
      Added value: +"Optional. Nonnegative hold threshold number in USD. Example: 1. Omit to use the service default."
    • addedInput schema / properties / rules / properties / hold_on_payto_change / description
      Added value: +"Optional. Boolean holding on an observed recipient change. Example: true. Defaults to true."
    • addedInput schema / properties / rules / properties / max_per_payment_usd / description
      Added value: +"Optional. Positive per-payment cap number in USD. Example: 5. Omit to use the service default."
    • addedInput schema / properties / rules / properties / max_price_multiple / description
      Added value: +"Optional. Positive price-to-observed-median ratio number, or null to disable. Example: 5 means five times the median. Defaults to 5."
    • addedInput schema / properties / rules / properties / new_domain_days / description
      Added value: +"Optional. New-domain age threshold as a nonnegative number of days. Example: 30. Omit to use the service default."
    • addedInput schema / properties / rules / properties / payto_allowlist / description
      Added value: +"Optional. Array of allowed recipient address strings. Example: [\"0xBf4164e07552e4c1b1B1597E72C7acAA3F0a1c58\"]. Omit to use the service default."
    • addedInput schema / properties / rules / properties / payto_blocklist / description
      Added value: +"Optional. Array of blocked recipient address strings. Example: [\"0xBf4164e07552e4c1b1B1597E72C7acAA3F0a1c58\"]. Omit to use the service default."
    • addedInput schema / properties / rules / properties / require_live / description
      Added value: +"Optional. Boolean holding after three usable failed unpaid probes. Example: true. Defaults to true; missing evidence is not a failed probe."
    • addedInput schema / properties / rules / properties / screen_sanctions / description
      Added value: +"Optional. Boolean enabling payee sanctions screening. Example: true. Omit to use the service default."
    • addedInput schema / properties / rules / properties / strict_allowlist / description
      Added value: +"Optional. Boolean requiring allowlist membership. Example: true. Omit to use the service default."
    • addedInput schema / properties / rules / properties / usdc_only / description
      Added value: +"Optional. Boolean restricting supported payment assets to USDC. Example: true. Omit to use the service default."
    • changedInput schema / properties / spent_today_usd / description
      Previous value: -"What this agent already spent today, for the daily cap"New value: +"Optional. Already-spent daily total as a nonnegative USD number. Example: 2.5. Caller-supplied context for the daily cap."
  2. Changed1 schema field changed
    • changedOutput schema / properties / decision / description
      Previous value: -"Pay on allow, ask a human on hold, never pay on block"New value: +"Allow only within your approved budget, ask a human on hold, never pay on block"
  3. Changed1 schema field changed
    • addedInput schema / description
      Added value: +"Example arguments: {\"cart\":{\"merchant_name\":\"Example Shop LLC\",\"total_usd\":0.01},\"rules\":{\"max_per_payment_usd\":1},\"spent_today_usd\":0}"
  4. Changed29 schema fields changed
    • addedInput schema / properties / resource_method
      Added value: +{
      +  "description": "Advertised method for an indexed URL with multiple methods",
      +  "maxLength": 16,
      +  "minLength": 3,
      +  "type": "string"
      +}
    • addedInput schema / properties / rules / properties / allowed_networks / items / maxLength
      Added value: +128
    • addedInput schema / properties / rules / properties / allowed_networks / items / minLength
      Added value: +1
    • addedInput schema / properties / rules / properties / allowed_networks / maxItems
      Added value: +100
    • addedInput schema / properties / rules / properties / daily_cap_usd / minimum
      Added value: +0
    • addedInput schema / properties / rules / properties / domain_allowlist / items / maxLength
      Added value: +253
    • addedInput schema / properties / rules / properties / domain_allowlist / items / minLength
      Added value: +1
    • addedInput schema / properties / rules / properties / domain_allowlist / maxItems
      Added value: +100
    • addedInput schema / properties / rules / properties / domain_blocklist / items / maxLength
      Added value: +253
    • addedInput schema / properties / rules / properties / domain_blocklist / items / minLength
      Added value: +1
    • addedInput schema / properties / rules / properties / domain_blocklist / maxItems
      Added value: +100
    • addedInput schema / properties / rules / properties / hold_above_usd / minimum
      Added value: +0
    • addedInput schema / properties / rules / properties / hold_on_payto_change
      Added value: +{
      +  "type": "boolean"
      +}
    • addedInput schema / properties / rules / properties / max_per_payment_usd / exclusiveMinimum
      Added value: +0
    • addedInput schema / properties / rules / properties / max_price_multiple
      Added value: +{
      +  "anyOf": [
      +    {
      +      "exclusiveMinimum": 0,
      +      "type": "number"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ]
      +}
    • addedInput schema / properties / rules / properties / new_domain_days / minimum
      Added value: +0
    • addedInput schema / properties / rules / properties / payto_allowlist / items / maxLength
      Added value: +128
    • addedInput schema / properties / rules / properties / payto_allowlist / items / minLength
      Added value: +1
    • addedInput schema / properties / rules / properties / payto_allowlist / maxItems
      Added value: +100
    • addedInput schema / properties / rules / properties / payto_blocklist / items / maxLength
      Added value: +128
    • addedInput schema / properties / rules / properties / payto_blocklist / items / minLength
      Added value: +1
    • addedInput schema / properties / rules / properties / payto_blocklist / maxItems
      Added value: +100
    • addedInput schema / properties / rules / properties / require_live
      Added value: +{
      +  "type": "boolean"
      +}
    • addedInput schema / properties / rules / properties / screen_sanctions
      Added value: +{
      +  "type": "boolean"
      +}
    • addedOutput schema / properties / index_evidence
      Added value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "data_as_of": {
      +      "type": "string"
      +    },
      +    "note": {
      +      "type": "string"
      +    },
      +    "observed_at": {
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "status": {
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "status",
      +    "note"
      +  ],
      +  "type": "object"
      +}
    • changedOutput schema / properties / receipt / description
      Previous value: -"Log this for audit"New value: +"Signed decision; keep privately for audit"
    • addedOutput schema / properties / receipt / properties / jws
      Added value: +{
      +  "description": "Offline-verifiable EdDSA decision attestation",
      +  "type": "string"
      +}
    • changedOutput schema / properties / receipt / required
      Previous value: -[
      -  "id",
      -  "ts",
      -  "input_sha256",
      -  "decision"
      -]New value: +[
      +  "id",
      +  "ts",
      +  "input_sha256",
      +  "decision",
      +  "jws"
      +]
    • changedOutput schema / required
      Previous value: -[
      -  "decision",
      -  "reasons",
      -  "options_evaluated",
      -  "receipt"
      -]New value: +[
      +  "decision",
      +  "reasons",
      +  "options_evaluated",
      +  "index_evidence",
      +  "receipt"
      +]
  5. First observed

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, open-world, and non-idempotent behavior, and the description reinforces them with 'Read-only: never signs, settles, or holds funds.' It adds substantial context beyond annotations: sanctions screening is included, repeat calls create new receipts and may consume paid calls, pricing is $0.02 per call with a free trial, and it clarifies that a transfer receipt is not delivery proof and an allow decision grants no payment authority.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded, but the description is very long and contains redundancy—'Call this before any x402/USDC payment' is restated as 'Use before every payment,' and pricing appears twice ('Price $0.02 per call' and 'Price: 0.02 USDC'). The detailed MCP payment-flow instructions, while useful, inflate the definition beyond what is needed for tool selection.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of a payment preflight tool with an output schema, the description covers purpose, routing, safety caveats, pricing, repeat-call behavior, and a minimal input/output example. Nothing an agent needs to call the tool correctly or interpret its role appears to be missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents every parameter thoroughly with examples. The description adds meaning by summarizing the optional rule fields (per-payment max, hold threshold, daily cap, allowlists, new-domain days, price multiple, liveness, payTo changes) and by clarifying that the challenge and cart are alternatives where exactly one must be supplied.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action—preflight an x402/USDC payment to get allow/hold/block with reasons and a signed receipt—and explicitly distinguishes itself from siblings like check_payee, lint_endpoint, listing_guard, verify_payee_binding, and payment_receipt. An agent can identify exactly what this tool does and what it does not do.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use ('Call this before any x402/USDC payment') and when-not-to-use guidance ('For standalone wallet, name, or domain screening without a payment, use check_payee instead'), plus names the alternative tools for separate evidence checks. The routing conditions are concrete and leave little to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.