SpendPreflight

Preflight a payment (allow / hold / block)

preflight_payment

Read-only

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.

Input Schema

Name	Required	Description
`cart`	No	Use instead of challenge for agent checkout / card payments
`rules`	No	Spending rules; all optional. See get_service_info for defaults.
`challenge`	No	The x402 PaymentRequired body (v1 or v2) your agent received with HTTP 402
`resource_url`	No	URL that returned the 402, if not inside the challenge
`resource_method`	No	Advertised method for an indexed URL with multiple methods
`spent_today_usd`	No	What this agent already spent today, for the daily cap

Output Schema

Name	Required	Description
`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	Pay on allow, ask a human on hold, never pay on block
`chosen_option`	No	The cheapest acceptable payment option
`index_evidence`	Yes
`options_evaluated`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 14, 2026

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}"

Changed26 schema fields changedOct 10, 2026
- 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
```
- removedInput schema / properties / rules / properties / hold_on_payto_change / description
```
Removed value: -"Hold on a payTo change observed within seven days (default true)"
```
- addedInput schema / properties / rules / properties / max_per_payment_usd / exclusiveMinimum
```
Added value: +0
```
- removedInput schema / properties / rules / properties / max_price_multiple / description
```
Removed value: -"Hold above this category median multiple (default 5); null disables"
```
- 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
```
- removedInput schema / properties / rules / properties / require_live / description
```
Removed value: -"Hold after three usable failed unpaid probes; unavailable index evidence stays unknown"
```
- addedInput schema / properties / rules / properties / screen_sanctions
```
Added value: +{
+  "type": "boolean"
+}
```
- 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"
+]
```

Changed6 schema fields changedOct 9, 2026

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 / hold_on_payto_change

Added value: +{
+  "description": "Hold on a payTo change observed within seven days (default true)",
+  "type": "boolean"
+}

addedInput schema / properties / rules / properties / max_price_multiple

Added value: +{
+  "anyOf": [
+    {
+      "exclusiveMinimum": 0,
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Hold above this category median multiple (default 5); null disables"
+}

addedInput schema / properties / rules / properties / require_live

Added value: +{
+  "description": "Hold after three usable failed unpaid probes; unavailable index evidence stays unknown",
+  "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 / required

Previous value: -[
-  "decision",
-  "reasons",
-  "options_evaluated",
-  "receipt"
-]New value: +[
+  "decision",
+  "reasons",
+  "options_evaluated",
+  "index_evidence",
+  "receipt"
+]

First observedOct 6, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=false; the description adds substantial context beyond that. It explains the allow|hold|block decision, receipt creation on repeat calls, the no-sign/no-settle/no-hold guarantee, pricing, trial allowance, and the requirement to stop and inspect payment terms before continuing.

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 opening sentence is well front-loaded, but the description is long and contains redundancy, such as the price appearing twice and repeated 'illustrative' caveats around the output excerpt. The payment how-to is useful but could be tightened for an agent that mainly needs selection and invocation guidance.

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 x402 payment flows, nested inputs, annotations, and an output schema, the description covers what the tool returns and how to invoke it safely. Nothing critical is missing for an agent to decide whether to call it and how to proceed after a payment-required response.

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 description coverage is 100%, so the baseline is 3, but the description adds practical meaning: it says to send the x402 PaymentRequired body (v1 or v2) or a cart, enumerates the optional rules categories, and notes spent_today_usd's role in the daily cap. The minimal input example further clarifies intended argument shape.

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 first sentence states a specific verb and resource: call before any x402/USDC payment to evaluate a challenge or cart before signing. It clearly distinguishes itself from check_payee by scope (payment preflight vs. standalone screening), so an agent can choose without opening either schema.

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?

Explicitly says when to use it ('before any x402/USDC payment', 'before every payment') and names the alternative for a different need: check_payee for standalone wallet/name/domain screening without a payment. It also covers the retry path after payment approval, which is unusual and valuable guidance.

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

All SpendPreflight tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?