Skip to main content
Glama

x402 Doctor

by io.github.Fizzl13
OverviewDiscussionsAdmin

Check an x402 endpoint before paying it ($0.001 via x402)

x402_preflight
Read-only

Paid ($0.001 USDC via x402 on Base or Solana): call this before your agent pays an x402 endpoint. Returns go, caution or no_go, the recommended payment option, and why: payment would fail, the seller's payout address is on the OFAC SDN sanctions list, over your budget (max_usd), price above what is advertised, not HTTPS, unknown token, its 30-day track record. Never pays the endpoint. The buyer's check for one call; for several endpoints at once use x402_preflight_batch, before a payment above about $1 x402_preflight_deep, and to debug your own endpoint x402_diagnose. Same as GET /api/v1/preflight. The answer carries a signed receipt (EIP-191, bound to your arguments) that proves later which verdict you got.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
urlYesThe x402 endpoint (public http(s) URL), e.g. https://api.example.com/paid
methodNoHTTP method of the paid route (default: GET, then POST)
max_usdNoYour budget per call in USD, e.g. 0.05
networkNoCAIP-2 network you want to pay on, e.g. eip155:8453

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
urlNo
acceptsNoOnly on an unpaid call: the x402 payment options
optionsNoEach payment option with its network, price and problems
reasonsNo
receiptNoSigned receipt (EIP-191) binding the answer to your arguments
summaryNoOne line, e.g. OK to pay: $0.02 on Base.
verdictNogo: pay; caution: ask first; no_go: do not pay
safe_to_payNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": true,
+  "properties": {
+    "accepts": {
+      "anyOf": [
+        {
+          "$ref": "#/properties/options/anyOf/0"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Only on an unpaid call: the x402 payment options"
+    },
+    "options": {
+      "anyOf": [
+        {
+          "items": {
+            "additionalProperties": {},
+            "type": "object"
+          },
+          "type": "array"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Each payment option with its network, price and problems"
+    },
+    "reasons": {
+      "anyOf": [
+        {
+          "$ref": "#/properties/options/anyOf/0"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "receipt": {
+      "anyOf": [
+        {
+          "additionalProperties": {},
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Signed receipt (EIP-191) binding the answer to your arguments"
+    },
+    "safe_to_pay": {
+      "type": [
+        "boolean",
+        "null"
+      ]
+    },
+    "summary": {
+      "description": "One line, e.g. OK to pay: $0.02 on Base.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "url": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "verdict": {
+      "description": "go: pay; caution: ask first; no_go: do not pay",
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "type": "object"
+}
  2. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnlyHint and openWorldHint, and the description reinforces without contradicting: 'Never pays the endpoint.' It adds material context beyond the annotations — the $0.001 USDC cost, the concrete no_go causes (OFAC SDN list, budget, advertised-price mismatch, non-HTTPS, unknown token, track record), and the EIP-191 signed receipt bound to the caller's arguments.

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

Conciseness4/5

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

Front-loaded with cost, trigger and return values, then routing, then receipt. Dense but nearly every clause carries distinct information; the verdict-cause list is long but each item is a useful failure mode rather than filler.

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?

An output schema exists, so return values need not be spelled out, yet the description still names the verdicts and receipt semantics. With annotations covering safety and a 100%-documented schema, nothing an agent needs to decide and invoke correctly is 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 baseline is 3, but the description adds meaning: it ties max_usd to the 'over your budget' verdict and implies network selects the chain to pay on. It does not explain method negotiation order beyond the schema default, so it stays just above baseline.

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?

States a specific verb and resource ('call this before your agent pays an x402 endpoint') plus the exact return shape (go/caution/no_go, recommended payment option, and reason). It also explicitly differentiates itself from siblings x402_preflight_batch, x402_preflight_deep, and x402_diagnose by use case.

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?

Gives explicit when-to-use routing: this tool for one call, x402_preflight_batch for several endpoints, x402_preflight_deep before payments above about $1, x402_diagnose to debug your own endpoint. The core trigger ('before your agent pays') is stated up front with no inference required.

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

All x402 Doctor toolsInspect
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