AgentWallet MCP Server

pay_x402

Instructions

Handle an x402 payment flow. Fetches a URL, and if the server returns HTTP 402 Payment Required, parses the payment requirements (v1 body or v2 PAYMENT-REQUIRED header), signs an EIP-3009 TransferWithAuthorization for the "exact" scheme (no gas, nothing broadcast by the payer), and retries the request with the payment header. AgentWallet paywalls are paid by on-chain transfer instead. The "upto" scheme is settled with a Permit2 authorization bounded by the cap. Returns the final response and the settlement receipt. Supports the x402 open payment standard (https://x402.org). max_payment can only lower the operator's cap for one call.

Input Schema

Name	Required	Description	Default
`url`	Yes	The URL to access (will handle 402 payment if required)
`body`	No	Optional request body for POST/PUT requests
`method`	No	HTTP method (GET, POST, PUT, DELETE)	GET
`headers`	No	Optional JSON string of additional request headers. Credentials placed here (Authorization, Cookie, API keys) are sent only to the origin in `url`; if the endpoint redirects to a different origin they are dropped, not forwarded.
`wallet_id`	Yes	Wallet ID to pay from
`approval_id`	No	An approval id from an earlier over-cap attempt. Once the owner has approved it, pass it here to make that one payment.
`max_payment`	No	Maximum payment in human-readable format (e.g. "1.00" for 1 USDC). Lowers the operator's AGENTWALLET_MAX_AUTOPAY ceiling (default "1") for this one call; it can never raise it, and a value above the ceiling is ignored and reported as max_payment_ignored.
`prefer_chain`	No	Preferred chain ID if the server accepts payment on multiple chains (e.g. 8453 for Base, 1 for Ethereum)
`request_approval`	No	Hosted wallets only. When the payment exceeds the cap, email the wallet owner an approve/deny link instead of refusing, and return an approval_id to retry with. Default true unless AGENTWALLET_APPROVALS=0.
`fresh_authorization`	No	Sign a new authorization even if one for the same endpoint, amount and recipient is still valid. By default a repeat call within the validity window re-sends the earlier signature (same nonce, so it cannot settle twice) instead of paying again.

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv1.14.2Oct 14, 2026

addedInput schema / properties / approval_id

Added value: +{
+  "description": "An approval id from an earlier over-cap attempt. Once the owner has approved it, pass it here to make that one payment.",
+  "type": "string"
+}

addedInput schema / properties / fresh_authorization

Added value: +{
+  "description": "Sign a new authorization even if one for the same endpoint, amount and recipient is still valid. By default a repeat call within the validity window re-sends the earlier signature (same nonce, so it cannot settle twice) instead of paying again.",
+  "type": "boolean"
+}

changedInput schema / properties / headers / description

Previous value: -"Optional JSON string of additional request headers"New value: +"Optional JSON string of additional request headers. Credentials placed here (Authorization, Cookie, API keys) are sent only to the origin in `url`; if the endpoint redirects to a different origin they are dropped, not forwarded."

changedInput schema / properties / max_payment / description

Previous value: -"Maximum payment in human-readable format (e.g. \"1.00\" for 1 USDC). Rejects payments above this amount. Strongly recommended to prevent overspending."New value: +"Maximum payment in human-readable format (e.g. \"1.00\" for 1 USDC). Lowers the operator's AGENTWALLET_MAX_AUTOPAY ceiling (default \"1\") for this one call; it can never raise it, and a value above the ceiling is ignored and reported as max_payment_ignored."

addedInput schema / properties / request_approval

Added value: +{
+  "description": "Hosted wallets only. When the payment exceeds the cap, email the wallet owner an approve/deny link instead of refusing, and return an approval_id to retry with. Default true unless AGENTWALLET_APPROVALS=0.",
+  "type": "boolean"
+}

First observedv1.7.3Mar 11, 2026

TDQS

A4.3/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does so well: it discloses that the 'exact' scheme requires no gas and nothing is broadcast by the payer, that 'upto' settles via a cap-bounded Permit2 authorization, that the call retries with a payment header, and that it returns both the final response and a settlement receipt. It also flags the approval flow and the one-way cap semantics of max_payment.

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 core purpose is front-loaded in the first sentence and the dense technical detail that follows is mostly justified for a complex payment tool. It is somewhat run-on and mixes scheme semantics with cap semantics, but every clause contributes information rather than filler.

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

Completeness4/5

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

For a 10-parameter mutation tool with no output schema, the description explains the return value (final response plus settlement receipt) and the safety-relevant flow. Combined with fully documented parameters, it is nearly complete, though it could say more about failure modes and the approval round-trip.

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

Parameters3/5

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

Schema description coverage is 100%, so all ten parameters (including max_payment, approval_id, request_approval, fresh_authorization) are already documented in the schema, making 3 the baseline. The description adds some connective context about how the payment schemes relate to these fields, but does not introduce meaning the schema lacks.

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 names a specific verb and resource: it fetches a URL and, on HTTP 402, completes an x402 payment then retries. It distinguishes itself from siblings like quote_x402 and discover_x402 by describing the actual pay-and-retry flow, and it reconciles the two settlement paths (EIP-3009 'exact' vs Permit2 'upto').

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 trigger condition (server returns 402) and notes that AgentWallet paywalls are instead paid by on-chain transfer, and that the 'upto' scheme uses Permit2. It doesn't explicitly route the agent to sibling alternatives (e.g. quote_x402 to preview, discover_x402 to find endpoints) or state when not to use it, so it stops short of full when/when-not guidance.

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

pay_x402

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools