Skip to main content
Glama
dinggi5

Kura

by dinggi5
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Rust
Local

Fetch a paid URL (x402)

x402_fetch
Destructive

Fetch paid x402 APIs or URLs using USDC on Base: sends the request, and if a 402 Payment Required is returned, asks for wallet approval and retries with payment.

Instructions

Calls an x402 paid API or URL. It sends the request first — GET by default, or the given method (POST, PUT, PATCH, DELETE) with optional headers and a JSON object body; if the server answers 402 Payment Required, it asks the user to approve the required payment (exact scheme, the active network, that chain's USDC) in the wallet app, then sends the SAME request (same method, headers and body) again with the payment header and returns the content. If no payment is required (no 402), it just returns the response. Redirects are not followed once a payment header is attached (nor at all when method, headers or body are given) — a redirect comes back as an error with the new address. Text and JSON come back in body. Binary responses (images, PDF, audio) are saved to a file whose path is in saved_file (with content_type); a PNG/JPEG/GIF/WebP image up to 3 MB is also attached as an image. Text longer than 100,000 characters is cut in body and kept whole in saved_file. If saving takes too long (macOS asking for Downloads access), the result comes back first and saving_file names where the file will appear. Settlement takes one of two shapes, chosen by the server's requirement: a facilitator settles the signed EIP-3009 authorization (no gas from this wallet), or — where gas is paid in USDC itself and the server asks for eip3009-client-broadcast — the wallet broadcasts the transfer itself, so the price AND its gas leave this balance. Approval works exactly as in request_payment (password by default; automatic only when the user has turned autopay on), and the app enforces per-payment and daily limits and the emergency lock. Never send a password as an argument. Arguments: url (required), method, headers, body (JSON object), memo (what the payment is for — the user reads it to decide), agent_id. Returns: payment, paid, status, http_status, body, and amount/pay_to/settlement when paid; on a chain where the wallet broadcasts the payment itself, tx and explorer point at that transaction (both are empty on the facilitator-settled path, where settlement_tx/settlement_explorer carry the transaction the seller reports in its receipt — the seller's word, not checked on-chain by the wallet). IMPORTANT — decide on payment, which says where the money is: "none" = nothing was paid, trying again is safe (declined, no 402, or "reverted": the chain rejected the transfer and only gas was spent); "confirmed" = the money left the wallet; "unknown" = it MAY have left (status pending/unknown, or settlement_failed on the facilitator path, where the server's refusal doesn't prove the facilitator didn't settle). For confirmed and unknown without content, asking again can pay a second time — stop and tell the user, showing the tx (when a tx came back without content, x402_resubmit re-sends its proof without paying again). paid is kept for older callers and is simply payment != "none". Read notice when present, and never retry on an HTTP status alone: after the money moved the server may answer with a fresh 402 challenge that reads as if the payment never happened.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
urlYesURL of the paid resource to fetch (http/https).
bodyNoJSON object sent as the request body (not allowed with GET). Content-Type defaults to application/json. The paid retry sends exactly the same body.
memoNoWhat the payment is for — the user reads this in the approval window, so fill it in.
methodNoHTTP method: GET (default), POST, PUT, PATCH or DELETE. Many paid APIs (search, image generation) take POST with a JSON body. The paid retry uses the same method.
headersNoExtra request headers as a JSON object of name → value. Payment headers, Host, Content-Length and connection headers are set by the wallet and are refused here. The paid retry sends the same headers.
agent_idNoOptional: the seller's ERC-8004 agent number, if you know it from the service's own documentation or agent card. The wallet then reads that agent's on-chain record and shows the user whether the payment address and the resource domain match what is registered. Leave it out if you don't know it — a wrong number just produces a "no such agent" note.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.5.0
    • addedInput schema / properties / body
      Added value: +{
+  "additionalProperties": true,
+  "description": "JSON object sent as the request body (not allowed with GET). Content-Type defaults to\napplication/json. The paid retry sends exactly the same body.",
+  "type": "object"
+}
    • addedInput schema / properties / headers
      Added value: +{
+  "additionalProperties": {
+    "type": "string"
+  },
+  "description": "Extra request headers as a JSON object of name → value. Payment headers, Host,\nContent-Length and connection headers are set by the wallet and are refused here.\nThe paid retry sends the same headers.",
+  "type": "object"
+}
    • addedInput schema / properties / method
      Added value: +{
+  "description": "HTTP method: GET (default), POST, PUT, PATCH or DELETE. Many paid APIs (search, image\ngeneration) take POST with a JSON body. The paid retry uses the same method.",
+  "type": "string"
+}
  2. Changed4 schema fields changedv0.4.1
    • removedInput schema / properties / agent_id / default
      Removed value: -null
    • removedInput schema / properties / agent_id / nullable
      Removed value: -true
    • removedInput schema / properties / memo / default
      Removed value: -null
    • removedInput schema / properties / memo / nullable
      Removed value: -true
  3. Changed1 schema field changedv0.3.0
    • addedInput schema / properties / agent_id
      Added value: +{
+  "default": null,
+  "description": "Optional: the seller's ERC-8004 agent number, if you know it from the service's own\ndocumentation or agent card. The wallet then reads that agent's on-chain record and shows\nthe user whether the payment address and the resource domain match what is registered.\nLeave it out if you don't know it — a wrong number just produces a \"no such agent\" note.",
+  "format": "uint64",
+  "minimum": 0,
+  "nullable": true,
+  "type": "integer"
+}
  4. First observedv0.2.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only say destructive/openWorld/non-idempotent, while the description discloses far more: the retry-safety semantics of the `payment` field ('none'/'confirmed'/'unknown'), the double-payment hazard, facilitator vs eip3009-client-broadcast gas behavior, redirect handling under a payment header, the 100k truncation and saved_file behavior, and the warning never to retry on HTTP status alone. This is exactly the value-beyond-annotations the dimension rewards, and the destructiveHint is consistent with money leaving the wallet.

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?

The basic request flow is front-loaded before the settlement and retry-safety detail, and nearly every sentence carries operational or safety weight. It is nevertheless very long for a single tool, with some density that could be tightened, so it stops short of a 5.

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?

There is no output schema, so the description carries the full burden of explaining returns — and it does: payment/paid/status/http_status/body/amount/pay_to/settlement, tx/explorer vs settlement_tx, and notice. For a 6-param destructive payment tool, an agent has everything needed to call it and interpret the result safely.

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 real meaning: it explains memo is what the user reads to decide, agent_id drives an on-chain ERC-8004 verification note, and it warns never to pass a password as an argument. These are semantic additions beyond the schema text.

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 opening sentence gives a specific verb and resource ('Calls an x402 paid API or URL') and the whole description keeps the scope tight around paid HTTP fetching. It distinguishes itself from request_payment by reference ('Approval works exactly as in request_payment') and from x402_resubmit by naming it as the no-pay-again path. An agent can separate it from every sibling without opening a schema.

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

Usage Guidelines4/5

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

It clearly states the triggering condition (server answers 402 → user approval → same request resent), when the tool is a plain fetch (no 402), and routes to x402_resubmit when a tx came back without content. It does not give an explicit 'prefer X over request_payment when...' decision rule, but the surrounding context is strong enough to infer usage.

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

Deploy Server

Other Tools