{"openapi":"3.1.0","info":{"title":"WalletConnect MCP HTTP API","version":"0.6.0","description":"Act on a user's own wallet through WalletConnect. Every write prepares an action and sends nothing; the caller restates it in a confirm call, then polls until the wallet answers. Tokens come from the OAuth authorization server on this origin, bound to the resource https://mcp.walletconnect.com/api.\n\nAgent instructions: This server lets you act on the user's own wallet through WalletConnect. You never hold keys: the user approves every request in their wallet app. Start with wallet_status or wallet_connect. Write tools (send_transfer, swap_execute) send nothing: they return a prepared action with every step decoded, the raw transaction bytes and plan.hash. Compare the plan with what the user asked (asset, amount, recipient, chain, and for a swap the minimum out), tell the user in one line what will happen, then call confirm_action(action_id, plan_hash, expect) with expect filled from the user's request, not copied from the plan; the server sends the first step to the wallet only if the hash and every expect field match. If anything differs, call cancel_action with the reason and tell the user. After confirming, tell the user to approve in their wallet, then call get_action_status(action_id) right away and keep calling it until the status is confirmed, rejected, expired, failed or cancelled. Never wait for the user to say they approved. Amounts are decimal strings in whole units. Transactions move real funds; state amount, recipient and chain before calling a write tool. Wallet links: each connected session carries walletLinks, the wallet app's own native (custom scheme, e.g. trust://) and universal (https) links from its session metadata. While an action is awaiting_wallet it also carries approveLinks: the same links with the request id appended, which open the wallet on that exact request. If the user is on their phone, show the universal approve link as a tappable link. If your client can open URLs on the user's device, open the native link first and fall back to the universal one, because a universal link can land in a browser instead of the app. These links hold no secrets and stop working when the request expires; the pairing URI from wallet_connect is different and must be shown only to the user. When the wallet is on a different device from the agent, the links do not help there: tell the user to open their wallet app, which may also notify them."},"servers":[{"url":"https://mcp.walletconnect.com/api/v1"}],"security":[{"oauth2":[]}],"tags":[{"name":"meta","description":"Server info, the tool list and the generic call"},{"name":"wallet","description":"Pairing and session"},{"name":"portfolio","description":"Balances"},{"name":"actions","description":"Prepare, confirm, poll and cancel"},{"name":"swaps","description":"Quotes"}],"paths":{"/":{"get":{"operationId":"info","summary":"Server info","description":"Version, the instructions an agent should follow, enabled chains, policy caps, tool names and where the OAuth resource metadata is.","tags":["meta"],"responses":{"200":{"description":"Server info.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerInfo"}}}},"401":{"description":"Missing, expired or wrongly scoped token. The WWW-Authenticate header names the resource metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools":{"get":{"operationId":"listTools","summary":"List tools","description":"Every tool with its JSON Schema, in the shape an agent framework needs to register them as functions.","tags":["meta"],"responses":{"200":{"description":"The tools.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolList"}}}},"401":{"description":"Missing, expired or wrongly scoped token. The WWW-Authenticate header names the resource metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tools/{name}":{"post":{"operationId":"callTool","summary":"Call a tool by name","description":"The same call as MCP tools/call: the body is the tool's arguments, the result is its text and data. Works for every tool, including ones without a route of their own. The data has the shape the tool's own route documents.","tags":["meta"],"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"The tool's text and data.","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"One line for a human or an agent: what happened and what to do next"},"data":{"type":"object","additionalProperties":true},"images":{"$ref":"#/components/schemas/Images"}},"required":["text","data"]}}}},"400":{"description":"The arguments do not match the schema; `issues` names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired or wrongly scoped token. The WWW-Authenticate header names the resource metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, action or pairing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The wallet or action is in the wrong state: no wallet connected, an open action in the way, or a plan that expired or does not match the restatement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A policy guardrail refused the request: a cap, an unlisted token or chain, a bad amount or address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/wallet/pairings/{id}":{"get":{"operationId":"pairingStatus","summary":"Pairing status","description":"Whether the wallet approved the pairing from POST /wallet/pairings. Poll it, or call GET /wallet, which waits for the approval.","tags":["wallet"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The pairing: awaiting_approval, approved (with the session), rejected, expired or failed.","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"One line for a human or an agent: what happened and what to do next"},"data":{"$ref":"#/components/schemas/PairingStatus"},"images":{"$ref":"#/components/schemas/Images"}},"required":["text","data"]}}}},"401":{"description":"Missing, expired or wrongly scoped token. The WWW-Authenticate header names the resource metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, action or pairing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/actions":{"get":{"operationId":"listActions","summary":"Open actions","description":"Actions that are prepared, awaiting the wallet or submitted. Terminal actions are not listed; fetch them by id.","tags":["actions"],"responses":{"200":{"description":"The open actions.","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"One line for a human or an agent: what happened and what to do next"},"data":{"$ref":"#/components/schemas/ActionList"},"images":{"$ref":"#/components/schemas/Images"}},"required":["text","data"]}}}},"401":{"description":"Missing, expired or wrongly scoped token. The WWW-Authenticate header names the resource metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/wallet/pairings":{"post":{"operationId":"wallet_connect","summary":"Connect wallet","description":"Returns the connected wallet accounts, or starts a WalletConnect pairing and returns everything needed to complete it in chat: a QR code image, the raw wc: URI (the user can paste it into their wallet's WalletConnect screen), deep links for common mobile wallets, and a hosted page with a wallet picker. Show the QR or the link to the user and tell them to approve in their wallet, then call wallet_status, which waits for the approval. The pairing expires in 5 minutes and is a bearer secret: anyone who scans it pairs their wallet to this user, so show it only to the user. Pass new_session: true to connect a different wallet while one is already connected.","tags":["wallet"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"new_session":{"type":"boolean","description":"Start a new pairing even if a wallet is already connected, to switch wallets."},"qr":{"type":"boolean","description":"Include the QR code as an image (default true). Set false for clients that cannot show images."}}}}}},"responses":{"200":{"description":"The tool's one-line text and its data, what the MCP tool wallet_connect returns as structuredContent.","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"One line for a human or an agent: what happened and what to do next"},"data":{"$ref":"#/components/schemas/PairingStart"},"images":{"$ref":"#/components/schemas/Images"}},"required":["text","data"]}}}},"400":{"description":"The arguments do not match the schema; `issues` names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired or wrongly scoped token. The WWW-Authenticate header names the resource metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, action or pairing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The wallet or action is in the wrong state: no wallet connected, an open action in the way, or a plan that expired or does not match the restatement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A policy guardrail refused the request: a cap, an unlisted token or chain, a bad amount or address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/wallet":{"get":{"operationId":"wallet_status","summary":"Wallet status","description":"Wallet connection status: accounts per chain, wallet name, walletLinks (the wallet app's native custom-scheme and universal https links), session expiry and any open actions. If a connect link is awaiting approval it waits for the wallet (up to 55 s) and returns as soon as it connects; call it again while still awaiting.","tags":["wallet"],"parameters":[{"name":"wait_seconds","in":"query","required":false,"description":"How long to wait for a pending connection, in seconds (default 55).","schema":{"type":"integer","minimum":0,"maximum":55}}],"responses":{"200":{"description":"The tool's one-line text and its data, what the MCP tool wallet_status returns as structuredContent.","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"One line for a human or an agent: what happened and what to do next"},"data":{"$ref":"#/components/schemas/WalletStatus"},"images":{"$ref":"#/components/schemas/Images"}},"required":["text","data"]}}}},"400":{"description":"The arguments do not match the schema; `issues` names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired or wrongly scoped token. The WWW-Authenticate header names the resource metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, action or pairing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The wallet or action is in the wrong state: no wallet connected, an open action in the way, or a plan that expired or does not match the restatement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A policy guardrail refused the request: a cap, an unlisted token or chain, a bad amount or address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/wallet/session":{"delete":{"operationId":"wallet_disconnect","summary":"Disconnect wallet","description":"End the WalletConnect session with the user's wallet. Steps not yet sent to the wallet are cancelled.","tags":["wallet"],"responses":{"200":{"description":"The tool's one-line text and its data, what the MCP tool wallet_disconnect returns as structuredContent.","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"One line for a human or an agent: what happened and what to do next"},"data":{"$ref":"#/components/schemas/Disconnect"},"images":{"$ref":"#/components/schemas/Images"}},"required":["text","data"]}}}},"400":{"description":"The arguments do not match the schema; `issues` names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired or wrongly scoped token. The WWW-Authenticate header names the resource metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, action or pairing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The wallet or action is in the wrong state: no wallet connected, an open action in the way, or a plan that expired or does not match the restatement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A policy guardrail refused the request: a cap, an unlisted token or chain, a bad amount or address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/portfolio":{"get":{"operationId":"get_portfolio","summary":"Portfolio","description":"All token balances of the connected wallet on a chain with USD prices and values, from the Blockchain API. Read-only, no wallet approval needed.","tags":["portfolio"],"parameters":[{"name":"chain","in":"query","required":false,"description":"Chain name or CAIP-2 id, e.g. \"base\". Defaults to the first enabled chain.","schema":{"type":"string"}}],"responses":{"200":{"description":"The tool's one-line text and its data, what the MCP tool get_portfolio returns as structuredContent.","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"One line for a human or an agent: what happened and what to do next"},"data":{"$ref":"#/components/schemas/Portfolio"},"images":{"$ref":"#/components/schemas/Images"}},"required":["text","data"]}}}},"400":{"description":"The arguments do not match the schema; `issues` names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired or wrongly scoped token. The WWW-Authenticate header names the resource metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, action or pairing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The wallet or action is in the wrong state: no wallet connected, an open action in the way, or a plan that expired or does not match the restatement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A policy guardrail refused the request: a cap, an unlisted token or chain, a bad amount or address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/actions/transfers":{"post":{"operationId":"send_transfer","summary":"Send transfer","description":"Send native ETH or an ERC-20 token (USDC) from the connected wallet to an address (real funds). amount is a decimal string in whole units (e.g. \"0.001\" ETH or \"5\" USDC), never wei. The server builds the calldata. Before calling, state the amount, recipient and chain to the user. Returns a prepared action. Nothing is sent to the wallet yet: the result is a prepared action with each step decoded (asset, amount, recipient, chain, contract, and for a swap the quote and minimum out), the raw transaction bytes, and plan.hash. Compare it with what the user asked, tell the user in one line what will happen, then call confirm_action(action_id, plan_hash, expect) with expect filled from the user's request rather than copied from the plan. If anything differs, call cancel_action with the reason. Once confirmed, the wallet request expires in 5 minutes: tell the user to approve in their wallet, then call get_action_status(action_id) right away and keep calling it until the status is confirmed, rejected, expired, failed or cancelled. Do not wait for the user to say they approved. While a step is awaiting_wallet the action carries approveLinks (universal: https, native: custom scheme) that open the wallet app on that request: show the universal one to a user on their phone, or open the native one first if you can open URLs on their device.","tags":["actions"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","description":"Recipient 0x address"},"amount":{"type":"string","description":"Amount as a decimal string in whole units"},"token":{"type":"string","description":"\"ETH\" (default, native) or a listed token symbol such as \"USDC\""},"chain":{"type":"string","description":"Chain name or CAIP-2 id, e.g. \"base\". Defaults to the first enabled chain."}},"required":["to","amount"]}}}},"responses":{"201":{"description":"The tool's one-line text and its data, what the MCP tool send_transfer returns as structuredContent.","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"One line for a human or an agent: what happened and what to do next"},"data":{"$ref":"#/components/schemas/Action"},"images":{"$ref":"#/components/schemas/Images"}},"required":["text","data"]}}}},"400":{"description":"The arguments do not match the schema; `issues` names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired or wrongly scoped token. The WWW-Authenticate header names the resource metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, action or pairing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The wallet or action is in the wrong state: no wallet connected, an open action in the way, or a plan that expired or does not match the restatement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A policy guardrail refused the request: a cap, an unlisted token or chain, a bad amount or address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/actions/{action_id}/confirm":{"post":{"operationId":"confirm_action","summary":"Confirm action","description":"Send a prepared action to the wallet. Pass plan.hash from the action you reviewed and expect: your own restatement of what the user asked, as strings, with the keys in plan.expectKeys. For kind transfer: kind, chain, asset, amount, to. For kind swap: kind, chain, from_asset, to_asset, amount_in, min_out, recipient (min_out from the plan, everything else from the user's request). The server refuses, and sends nothing, if the hash differs from the prepared plan, if any expect field disagrees with the plan, or if the plan expired. On success the first step is in the wallet: tell the user to approve, then call get_action_status right away and keep calling it until the status is terminal.","tags":["actions"],"parameters":[{"name":"action_id","in":"path","required":true,"description":"The action_id of a prepared action","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plan_hash":{"type":"string","description":"plan.hash from the prepared action"},"expect":{"type":"object","additionalProperties":{"type":"string"},"description":"Your restatement of the user's request; the keys are listed in plan.expectKeys"}},"required":["plan_hash","expect"]}}}},"responses":{"200":{"description":"The tool's one-line text and its data, what the MCP tool confirm_action returns as structuredContent.","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"One line for a human or an agent: what happened and what to do next"},"data":{"$ref":"#/components/schemas/Action"},"images":{"$ref":"#/components/schemas/Images"}},"required":["text","data"]}}}},"400":{"description":"The arguments do not match the schema; `issues` names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired or wrongly scoped token. The WWW-Authenticate header names the resource metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, action or pairing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The wallet or action is in the wrong state: no wallet connected, an open action in the way, or a plan that expired or does not match the restatement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A policy guardrail refused the request: a cap, an unlisted token or chain, a bad amount or address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/actions/{action_id}":{"get":{"operationId":"get_action_status","summary":"Action status","description":"Wait for and return the state of an action and each of its steps: prepared (nothing sent; confirm_action or cancel_action it), awaiting_wallet, submitted (tx hash known), confirmed, rejected, expired, failed or cancelled. Call it right after confirm_action, without asking the user. It waits server-side (up to 55 s) and returns as soon as something changes; a prepared action returns at once. If the action is not terminal yet, call it again immediately. Multi-step actions advance on their own: the next step is sent to the wallet when the previous one confirms. While a step is awaiting_wallet the result carries approveLinks that open the wallet app on that request; show the universal one to a user on their phone.","tags":["actions"],"parameters":[{"name":"action_id","in":"path","required":true,"description":"The action_id returned by a write tool","schema":{"type":"string"}},{"name":"wait_seconds","in":"query","required":false,"description":"How long to wait for a change, in seconds (default 55).","schema":{"type":"integer","minimum":0,"maximum":55}}],"responses":{"200":{"description":"The tool's one-line text and its data, what the MCP tool get_action_status returns as structuredContent.","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"One line for a human or an agent: what happened and what to do next"},"data":{"$ref":"#/components/schemas/Action"},"images":{"$ref":"#/components/schemas/Images"}},"required":["text","data"]}}}},"400":{"description":"The arguments do not match the schema; `issues` names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired or wrongly scoped token. The WWW-Authenticate header names the resource metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, action or pairing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The wallet or action is in the wrong state: no wallet connected, an open action in the way, or a plan that expired or does not match the restatement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A policy guardrail refused the request: a cap, an unlisted token or chain, a bad amount or address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/actions/{action_id}/cancel":{"post":{"operationId":"cancel_action","summary":"Cancel action","description":"Cancel a prepared action, or the steps of a running action that have not been sent to the wallet yet. A request already showing in the wallet cannot be recalled; the user rejects it there. Give the reason, for example what in the plan differed from the user's request; it is written to the audit log.","tags":["actions"],"parameters":[{"name":"action_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Why the action is cancelled, e.g. what differed from the user's request"}}}}}},"responses":{"200":{"description":"The tool's one-line text and its data, what the MCP tool cancel_action returns as structuredContent.","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"One line for a human or an agent: what happened and what to do next"},"data":{"$ref":"#/components/schemas/Action"},"images":{"$ref":"#/components/schemas/Images"}},"required":["text","data"]}}}},"400":{"description":"The arguments do not match the schema; `issues` names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired or wrongly scoped token. The WWW-Authenticate header names the resource metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, action or pairing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The wallet or action is in the wrong state: no wallet connected, an open action in the way, or a plan that expired or does not match the restatement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A policy guardrail refused the request: a cap, an unlisted token or chain, a bad amount or address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/swaps/assets":{"get":{"operationId":"swap_assets","summary":"Swappable assets","description":"Read-only: which assets can be swapped on which chains, with their decimals and token addresses. Availability differs by chain, so check here before quoting an asset the user named. No wallet approval needed.","tags":["swaps"],"parameters":[{"name":"chain","in":"query","required":false,"description":"Limit to one chain. Omit for every enabled chain.","schema":{"type":"string"}}],"responses":{"200":{"description":"The tool's one-line text and its data, what the MCP tool swap_assets returns as structuredContent.","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"One line for a human or an agent: what happened and what to do next"},"data":{"$ref":"#/components/schemas/SwapAssets"},"images":{"$ref":"#/components/schemas/Images"}},"required":["text","data"]}}}},"400":{"description":"The arguments do not match the schema; `issues` names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired or wrongly scoped token. The WWW-Authenticate header names the resource metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, action or pairing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The wallet or action is in the wrong state: no wallet connected, an open action in the way, or a plan that expired or does not match the restatement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A policy guardrail refused the request: a cap, an unlisted token or chain, a bad amount or address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/swaps/quote":{"get":{"operationId":"swap_quote","summary":"Swap quote","description":"Read-only: what a swap would return right now on Uniswap V3. from and to are asset symbols (call swap_assets for what a chain offers); amount is a decimal string in the from asset. The server tries every fee tier and quotes the best pool. No wallet approval needed.","tags":["swaps"],"parameters":[{"name":"from","in":"query","required":true,"description":"Asset to sell, e.g. \"USDC\"","schema":{"type":"string"}},{"name":"to","in":"query","required":true,"description":"Asset to buy, e.g. \"ETH\"","schema":{"type":"string"}},{"name":"amount","in":"query","required":true,"description":"Amount of the from asset, e.g. \"10\" or \"0.005\"","schema":{"type":"string"}},{"name":"chain","in":"query","required":false,"description":"Chain name or CAIP-2 id, e.g. \"base\", \"ethereum\", \"optimism\" or \"arbitrum\". Defaults to the first enabled chain.","schema":{"type":"string"}}],"responses":{"200":{"description":"The tool's one-line text and its data, what the MCP tool swap_quote returns as structuredContent.","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"One line for a human or an agent: what happened and what to do next"},"data":{"$ref":"#/components/schemas/Quote"},"images":{"$ref":"#/components/schemas/Images"}},"required":["text","data"]}}}},"400":{"description":"The arguments do not match the schema; `issues` names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired or wrongly scoped token. The WWW-Authenticate header names the resource metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, action or pairing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The wallet or action is in the wrong state: no wallet connected, an open action in the way, or a plan that expired or does not match the restatement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A policy guardrail refused the request: a cap, an unlisted token or chain, a bad amount or address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/actions/swaps":{"post":{"operationId":"swap_execute","summary":"Swap on Uniswap","description":"Swap one asset for another on Uniswap V3 (real funds), from and to the connected wallet. from and to are asset symbols (call swap_assets for what a chain offers); amount is a decimal string in the from asset. The server picks the best fee tier, sets a minimum output (quote minus max slippage, default 0.5%) and a 10-minute deadline, and runs the swap against the chain before preparing it. Selling an ERC-20 is a two-step action: an exact-amount approval, then the swap, which the server sends once the approval confirms. Selling the chain's native asset is one step. Before calling, state the amount and both assets to the user. Returns a prepared action. Nothing is sent to the wallet yet: the result is a prepared action with each step decoded (asset, amount, recipient, chain, contract, and for a swap the quote and minimum out), the raw transaction bytes, and plan.hash. Compare it with what the user asked, tell the user in one line what will happen, then call confirm_action(action_id, plan_hash, expect) with expect filled from the user's request rather than copied from the plan. If anything differs, call cancel_action with the reason. Once confirmed, the wallet request expires in 5 minutes: tell the user to approve in their wallet, then call get_action_status(action_id) right away and keep calling it until the status is confirmed, rejected, expired, failed or cancelled. Do not wait for the user to say they approved. While a step is awaiting_wallet the action carries approveLinks (universal: https, native: custom scheme) that open the wallet app on that request: show the universal one to a user on their phone, or open the native one first if you can open URLs on their device.","tags":["actions"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","description":"Asset to sell, e.g. \"USDC\""},"to":{"type":"string","description":"Asset to buy, e.g. \"ETH\""},"amount":{"type":"string","description":"Amount of the from asset, e.g. \"10\" or \"0.005\""},"max_slippage_pct":{"type":"number","exclusiveMinimum":true,"minimum":0,"maximum":1,"description":"Max slippage in percent (default 0.5, max 1). Leave unset unless the user asks."},"chain":{"type":"string","description":"Chain name or CAIP-2 id, e.g. \"base\", \"ethereum\", \"optimism\" or \"arbitrum\". Defaults to the first enabled chain."}},"required":["from","to","amount"]}}}},"responses":{"201":{"description":"The tool's one-line text and its data, what the MCP tool swap_execute returns as structuredContent.","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"One line for a human or an agent: what happened and what to do next"},"data":{"$ref":"#/components/schemas/Action"},"images":{"$ref":"#/components/schemas/Images"}},"required":["text","data"]}}}},"400":{"description":"The arguments do not match the schema; `issues` names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, expired or wrongly scoped token. The WWW-Authenticate header names the resource metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such tool, action or pairing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The wallet or action is in the wrong state: no wallet connected, an open action in the way, or a plan that expired or does not match the restatement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A policy guardrail refused the request: a cap, an unlisted token or chain, a bad amount or address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"oauth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE. Request the resource https://mcp.walletconnect.com/api; register a client at https://mcp.walletconnect.com/register or use a client ID metadata document. The consent page pairs the user's wallet. A client that pairs itself through POST /wallet/pairings (a wallet, say) adds connect=skip to the authorization request and gets the decision alone.","flows":{"authorizationCode":{"authorizationUrl":"https://mcp.walletconnect.com/authorize","tokenUrl":"https://mcp.walletconnect.com/token","refreshUrl":"https://mcp.walletconnect.com/token","scopes":{"wallet:read":"Read balances, status and actions","wallet:write":"Prepare, confirm and cancel actions"}}}}},"schemas":{"WalletLinks":{"type":"object","properties":{"native":{"type":"string","description":"Custom-scheme deep link into the wallet app, e.g. trust://"},"universal":{"type":"string","description":"https universal link into the wallet app"}},"description":"Links into the wallet app from its session metadata. Either may be absent."},"Session":{"type":"object","properties":{"topic":{"type":"string","description":"WalletConnect session topic"},"accounts":{"type":"array","items":{"type":"string","description":"CAIP-10 account, e.g. eip155:8453:0x…"}},"chains":{"type":"array","items":{"type":"string","description":"CAIP-2 chain, e.g. eip155:8453"}},"expiry":{"type":"integer","description":"Session expiry, seconds since the epoch"},"walletName":{"type":"string"},"walletIcon":{"type":"string"},"walletLinks":{"$ref":"#/components/schemas/WalletLinks"},"walletLink":{"type":"string","description":"The single best link into the wallet: universal, else native"}},"required":["topic","accounts","chains","expiry","walletLinks"],"example":{"topic":"9f2c…","accounts":["eip155:8453:0x13A2Ff792037AA2cd77fE1f4B522921ac59a9C52"],"chains":["eip155:8453"],"expiry":1762780800,"walletName":"Trust Wallet","walletIcon":"https://…/icon.png","walletLinks":{"native":"trust://","universal":"https://link.trustwallet.com"},"walletLink":"https://link.trustwallet.com"}},"ConnectedWallet":{"type":"object","properties":{"walletName":{"type":"string"},"walletIcon":{"type":"string"},"accounts":{"type":"array","items":{"type":"string","description":"CAIP-10 account"}},"chains":{"type":"array","items":{"type":"string","description":"CAIP-2 chain"}},"expiry":{"type":"integer","description":"Seconds since the epoch"}},"required":["accounts","chains","expiry"]},"Pairing":{"type":"object","properties":{"id":{"type":"string"},"uri":{"type":"string","description":"The wc: pairing URI. A bearer secret: whoever scans it pairs their wallet to this user, so show it only to the user."},"status":{"type":"string","enum":["awaiting_approval","approved","rejected","expired","failed"]},"created_at":{"type":"integer","description":"Milliseconds since the epoch"},"expires_at":{"type":"integer","description":"Milliseconds since the epoch"},"topic":{"type":["string","null"],"description":"The session topic once approved"},"error":{"type":["string","null"]}},"required":["id","uri","status","created_at","expires_at"]},"WalletStatus":{"type":"object","properties":{"connected":{"type":"boolean"},"sessions":{"type":"array","items":{"$ref":"#/components/schemas/Session"},"description":"Live sessions, newest first"},"latestPairing":{"$ref":"#/components/schemas/Pairing"},"relayConnected":{"type":"boolean","description":"Whether the server's WalletConnect relay socket is up"},"openActions":{"type":"array","items":{"$ref":"#/components/schemas/Action"},"description":"Actions that are prepared, awaiting the wallet or submitted"}},"required":["connected","sessions","relayConnected","openActions"],"example":{"connected":true,"sessions":[{"topic":"9f2c…","accounts":["eip155:8453:0x13A2Ff792037AA2cd77fE1f4B522921ac59a9C52"],"chains":["eip155:8453"],"expiry":1762780800,"walletName":"Trust Wallet","walletIcon":"https://…/icon.png","walletLinks":{"native":"trust://","universal":"https://link.trustwallet.com"},"walletLink":"https://link.trustwallet.com"}],"relayConnected":true,"openActions":[]}},"PairingStart":{"description":"The connected session when a wallet is already connected (and new_session was not set), else everything needed to complete a new pairing.","oneOf":[{"allOf":[{"type":"object","properties":{"connected":{"const":true}},"required":["connected"]},{"$ref":"#/components/schemas/Session"}]},{"type":"object","properties":{"connected":{"const":false},"pairingId":{"type":"string","description":"Poll GET /wallet/pairings/{pairingId}, or GET /wallet, which waits"},"uri":{"type":"string","description":"The wc: URI to show as a QR or paste into the wallet. A bearer secret; show it only to the user."},"connectUrl":{"type":"string","description":"Hosted page with a wallet picker and the QR, bound to this user, valid for 10 minutes"},"deepLinks":{"type":"object","properties":{"trust":{"type":"string"},"metamask":{"type":"string"},"rainbow":{"type":"string"}},"required":["trust","metamask","rainbow"],"description":"The URI wrapped in common wallets' universal links"},"expiresInSeconds":{"type":"integer"},"next":{"type":"string"}},"required":["connected","pairingId","uri","connectUrl","deepLinks","expiresInSeconds","next"],"example":{"connected":false,"pairingId":"7c1e5d6a-…","uri":"wc:7c1e…@2?relay-protocol=irn&symKey=…","connectUrl":"https://mcp.walletconnect.com/connect?t=…","deepLinks":{"trust":"https://link.trustwallet.com/wc?uri=wc%3A…","metamask":"https://metamask.app.link/wc?uri=wc%3A…","rainbow":"https://rnbwapp.com/wc?uri=wc%3A…"},"expiresInSeconds":300,"next":"Show the QR or link to the user, then call wallet_status."}}]},"PairingStatus":{"type":"object","properties":{"pairingId":{"type":"string"},"status":{"type":"string","enum":["awaiting_approval","approved","rejected","expired","failed"]},"expiresAt":{"type":"string","description":"ISO 8601"},"accounts":{"type":"array","items":{"type":"string","description":"CAIP-10 account"},"description":"Once approved"},"session":{"$ref":"#/components/schemas/ConnectedWallet"},"error":{"type":"string","description":"Why the pairing was rejected or failed"}},"required":["pairingId","status","expiresAt"],"example":{"pairingId":"7c1e5d6a-…","status":"approved","expiresAt":"2026-11-03T13:05:00.000Z","accounts":["eip155:8453:0x13A2Ff792037AA2cd77fE1f4B522921ac59a9C52"],"session":{"walletName":"Trust Wallet","accounts":["eip155:8453:0x13A2Ff792037AA2cd77fE1f4B522921ac59a9C52"],"chains":["eip155:8453"],"expiry":1762780800}}},"Disconnect":{"type":"object","properties":{"disconnected":{"type":"integer","description":"Sessions ended"}},"required":["disconnected"],"example":{"disconnected":1}},"Asset":{"type":"object","properties":{"symbol":{"type":"string"},"name":{"type":"string"},"amount":{"type":"string","description":"Decimal string in whole units"},"decimals":{"type":"integer"},"priceUsd":{"type":"number","description":"Absent when the price is unknown"},"valueUsd":{"type":"number","description":"Absent when the price is unknown; such assets are left out of totalUsd"},"address":{"type":"string","description":"Token contract; absent for the native asset"}},"required":["symbol","name","amount","decimals"]},"Portfolio":{"type":"object","properties":{"chain":{"type":"string","description":"Chain name"},"address":{"type":"string","description":"The connected account"},"totalUsd":{"type":"number","description":"Sum of the priced assets; absent when prices were unavailable"},"assets":{"type":"array","items":{"$ref":"#/components/schemas/Asset"}},"source":{"type":"string","enum":["blockchain-api","rpc"]}},"required":["chain","address","assets","source"],"example":{"chain":"Base","address":"0x13A2Ff792037AA2cd77fE1f4B522921ac59a9C52","totalUsd":8.26,"assets":[{"symbol":"USDC","name":"USD Coin","amount":"7.12484","decimals":6,"priceUsd":1,"valueUsd":7.12,"address":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"},{"symbol":"ETH","name":"Ethereum","amount":"0.000474129","decimals":18,"priceUsd":2413,"valueUsd":1.14}],"source":"blockchain-api"}},"SwapAssets":{"type":"object","properties":{"provider":{"type":"string","enum":["uniswap-v3"]},"chains":{"type":"array","items":{"type":"object","properties":{"chain":{"type":"string","description":"Chain name"},"caip2":{"type":"string","description":"CAIP-2 id"},"assets":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"decimals":{"type":"integer"},"address":{"type":"string","description":"Token contract; absent for the native asset"},"native":{"type":"boolean"}},"required":["symbol","decimals","native"]}}},"required":["chain","caip2","assets"]},"description":"Every enabled chain with swaps, and what can be swapped there. Availability differs by chain."}},"required":["provider","chains"],"example":{"provider":"uniswap-v3","chains":[{"chain":"Base","caip2":"eip155:8453","assets":[{"symbol":"ETH","decimals":18,"native":true},{"symbol":"USDC","decimals":6,"address":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","native":false}]}]}},"Quote":{"type":"object","properties":{"chain":{"type":"string","description":"Chain name"},"provider":{"type":"string","enum":["uniswap-v3"]},"from":{"type":"string","description":"Asset symbol being sold"},"to":{"type":"string","description":"Asset symbol being bought"},"amountIn":{"type":"string","description":"Whole units"},"amountOut":{"type":"string","description":"Whole units, what the pool quotes right now"},"feeTierPct":{"type":"number","description":"The fee tier of the pool the quote came from. Chosen per trade: the deepest tier differs by chain, by pair and by direction"},"pool":{"type":"string"}},"required":["chain","provider","from","to","amountIn","amountOut","feeTierPct","pool"],"example":{"chain":"Base","provider":"uniswap-v3","from":"USDC","to":"ETH","amountIn":"10","amountOut":"0.004381099","feeTierPct":0.05,"pool":"Uniswap V3 USDC/ETH 0.05%"}},"Step":{"type":"object","properties":{"n":{"type":"integer","description":"1-based position in the action"},"summary":{"type":"string"},"chain":{"type":"string","description":"Chain name"},"status":{"type":"string","enum":["queued","skipped","awaiting_wallet","submitted","confirmed","rejected","expired","failed","cancelled"]},"txHash":{"type":"string","description":"Once the wallet has broadcast it"},"explorerUrl":{"type":"string"},"error":{"type":"string","description":"Why the step was rejected, failed, expired or cancelled"},"expiresInSeconds":{"type":"integer","description":"While awaiting the wallet"},"decoded":{"type":"object","description":"The step in words and whole units: action, chain, asset, amount, to, and for a swap the quote, minimum out and recipient. Check these against what the user asked.","additionalProperties":{"type":["string","number","boolean"]}},"tx":{"type":"object","properties":{"to":{"type":"string"},"data":{"type":"string","description":"Hex calldata"},"value":{"type":"string","description":"Wei, decimal string"}},"required":["to","data","value"],"description":"The exact transaction this step sends, present while the action is prepared"},"approveLinks":{"$ref":"#/components/schemas/WalletLinks"}},"required":["n","summary","chain","status"],"example":{"n":1,"summary":"Send 0.001 ETH to 0x000000000000000000000000000000000000dEaD","chain":"Base","status":"queued","decoded":{"action":"transfer","chain":"Base","asset":"ETH","amount":"0.001","amountBaseUnits":"1000000000000000","to":"0x000000000000000000000000000000000000dEaD"},"tx":{"to":"0x000000000000000000000000000000000000dEaD","data":"0x","value":"1000000000000000"}}},"Action":{"type":"object","properties":{"actionId":{"type":"string"},"status":{"type":"string","enum":["prepared","awaiting_wallet","submitted","confirmed","rejected","expired","failed","cancelled"]},"summary":{"type":"string"},"steps":{"type":"array","items":{"$ref":"#/components/schemas/Step"}},"plan":{"type":"object","properties":{"hash":{"type":"string","description":"SHA-256 over the exact bytes of every step; pass it to confirm"},"expiresAt":{"type":"string","description":"ISO 8601"},"expiresInSeconds":{"type":"integer"},"expectKeys":{"type":"array","items":{"type":"string"},"description":"The facts to restate in confirm's expect"}},"required":["hash","expiresAt","expiresInSeconds","expectKeys"],"description":"Present while the action is prepared: what confirm needs"},"expiresAt":{"type":"string","description":"While a step is awaiting the wallet: when that request expires, ISO 8601"},"expiresInSeconds":{"type":"integer"},"walletLinks":{"$ref":"#/components/schemas/WalletLinks"},"walletLink":{"type":"string","description":"The single best link into the wallet app"},"approveLinks":{"$ref":"#/components/schemas/WalletLinks"},"next":{"type":"string","description":"What to do next, in words"}},"required":["actionId","status","summary","steps","next"],"description":"Terminal statuses: confirmed, rejected, expired, failed, cancelled. Poll GET /actions/{id} until one of them.","example":{"actionId":"act_1f3c9a2b7d4e5f60","status":"prepared","summary":"Send 0.001 ETH to 0x0000…dEaD on Base","steps":[{"n":1,"summary":"Send 0.001 ETH to 0x000000000000000000000000000000000000dEaD","chain":"Base","status":"queued","decoded":{"action":"transfer","chain":"Base","asset":"ETH","amount":"0.001","amountBaseUnits":"1000000000000000","to":"0x000000000000000000000000000000000000dEaD"},"tx":{"to":"0x000000000000000000000000000000000000dEaD","data":"0x","value":"1000000000000000"}}],"plan":{"hash":"0x5c0a…(64 hex chars)","expiresAt":"2026-11-03T13:05:00.000Z","expiresInSeconds":299,"expectKeys":["kind","chain","asset","amount","to"]},"next":"Nothing has been sent to the wallet. Check each step's decoded fields against what the user asked, then call confirm with plan.hash and expect {kind, chain, asset, amount, to}. The plan expires in 299 s."}},"ActionList":{"type":"object","properties":{"actions":{"type":"array","items":{"$ref":"#/components/schemas/Action"}}},"required":["actions"]},"ServerInfo":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string","description":"Bumped whenever the tool surface changes"},"instructions":{"type":"string","description":"The protocol an agent must follow; put it in the system prompt"},"chains":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"CAIP-2"},"name":{"type":"string"}},"required":["id","name"]}},"caps":{"type":"object","properties":{"eth":{"type":"string","description":"Per-transaction cap in ETH"},"usdc":{"type":"string","description":"Per-transaction cap in USDC"}},"required":["eth","usdc"]},"tools":{"type":"array","items":{"type":"string"}},"openapi":{"type":"string"},"docs":{"type":"string"},"oauth":{"type":"object","properties":{"resource":{"type":"string","description":"Ask for this resource when authorizing"},"metadata":{"type":"string","description":"RFC 9728 resource metadata"}},"required":["resource","metadata"]}},"required":["name","version","instructions","chains","caps","tools","openapi","docs","oauth"]},"Tool":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"inputSchema":{"type":"object","description":"JSON Schema of the arguments"},"annotations":{"type":"object","additionalProperties":true},"rest":{"type":"object","properties":{"method":{"type":"string"},"path":{"type":"string"}},"required":["method","path"],"description":"The resource route, when the tool has one"}},"required":["name","description","inputSchema"]},"ToolList":{"type":"object","properties":{"tools":{"type":"array","items":{"$ref":"#/components/schemas/Tool"}}},"required":["tools"]},"ToolResult":{"type":"object","properties":{"text":{"type":"string","description":"One line for a human or an agent: what happened and what to do next"},"data":{"type":"object","description":"The tool's structured result; see the tool description for its fields","additionalProperties":true},"images":{"$ref":"#/components/schemas/Images"}},"required":["text","data"]},"Images":{"type":"array","items":{"type":"object","properties":{"mimeType":{"type":"string","enum":["image/png"]},"data":{"type":"string","description":"Base64"}},"required":["mimeType","data"]},"description":"Present when the tool produced an image, e.g. the pairing QR code"},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_request","unauthorized","not_found","conflict","blocked","internal"]},"message":{"type":"string"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}}},"description":"For invalid_request: each field that failed validation"}},"required":["code","message"]}},"required":["error"]}}}}