WalletConnect MCP

The WalletConnect MCP is a hosted Model Context Protocol server. It lets any MCP client, such as Claude, Claude Code, Cursor or ChatGPT, read your balances and prepare transfers and swaps on your own wallet over WalletConnect. The same tools are served as an HTTP API for agents and backends that don't speak MCP.

The server is the app side of a WalletConnect session. It never holds signing keys: it can only ask your wallet to sign, and you approve every transaction in your wallet app.

What you can doCopy Anchor Link

• Check your portfolio. "What's in my wallet on Base? Give me the USD total." Every token the wallet holds, with USD prices and values. Reads never reach your wallet, so there is nothing to approve.
• Send money. "Send 10 USDC to 0x… on Arbitrum." The server builds the transfer, the agent restates it, and you approve it in your wallet.
• Swap tokens. "How much ETH would I get for 25 USDC?" then "Do it." A live Uniswap V3 quote, then an exact-amount approval and the swap, prepared as one action.
• Build agents that pay. Backends and agent frameworks call the HTTP API with the same tools, so an agent can propose a payment and the user signs it on their phone.

Connect a clientCopy Anchor Link

The MCP endpoint is:

https://mcp.walletconnect.com/mcp

claude mcp add --transport http walletconnect https://mcp.walletconnect.com/mcp

The first time you connect, a consent page opens in your browser:

You can also connect from the chat: ask "Connect my wallet" and the agent calls wallet_connect, which returns a connect link and a QR code.

How a transaction worksCopy Anchor Link

Every write tool prepares an action and sends nothing. The agent has to show you the plan and confirm it before your wallet sees anything.

1. Prepare. A write tool returns an action_id, status: "prepared", every step decoded into whole units (asset, amount, recipient, chain, contract and, for a swap, the quote and minimum out), the raw to, data and value each step will send, and plan.hash, a SHA-256 over those bytes.
2. Confirm. The agent compares the plan with your request, tells you what will happen, and calls confirm_action with the hash and expect, its own restatement of your request (plan.expectKeys lists the fields). The server sends the first step only if the hash matches the stored plan, every expect field matches the plan, and the plan is less than 5 minutes old. It sends the exact bytes it hashed.
3. Approve. You approve the request in your wallet. Each wallet request expires 5 minutes after it is sent.
4. Track. The agent polls get_action_status until the action reaches a final status: confirmed, rejected, expired, failed or cancelled. Multi-step actions, such as approve then swap, advance on their own as each step confirms.

A plan that doesn't match is refused and written to the audit log, and the agent cancels it with a reason.

While a step waits for your signature, the action carries approveLinks: links that open your wallet app on that exact request. On a phone, the agent shows you the link; on a desktop client, it can open your wallet directly.

SecurityCopy Anchor Link

Two layers protect you. The server's policy blocks anything outside its limits before it reaches your wallet, and anything that passes still needs your signature.

LimitsCopy Anchor Link

Transaction checksCopy Anchor Link

The server runs these checks in code on every transaction. Each one refuses the action before it reaches your wallet, except the receipt check, which runs after the wallet answers.

When an action is prepared

When an action is confirmed

While an action runs

Each user has an audit log on the server. It records every action prepared, confirmed, refused for a mismatch, cancelled, replaced or expired, and every step sent, submitted, confirmed, reverted or retried.

Supported chains and assetsCopy Anchor Link

Tools called without a chain use Base. SPCXON is Ondo's tokenized SpaceX, available on Ethereum only. Swaps quote all four Uniswap fee tiers and use the best one for each trade.

Any WalletConnect-compatible wallet works. Balances, prices and quotes come from the WalletConnect Blockchain API; your wallet is only ever asked to sign.

ToolsCopy Anchor Link

HTTP APICopy Anchor Link

The same tools are available as JSON routes under https://mcp.walletconnect.com/api/v1, with the same prepare, confirm and track flow.

• The OpenAPI 3.1 document is at /api/v1/openapi.json and needs no token. A readable reference is at /api/docs.
• GET /api/v1 returns the version, the agent instructions, the enabled chains and caps.
• GET /api/v1/tools lists every tool with its JSON Schema, ready to register as functions in any agent framework.

AuthorizeCopy Anchor Link

Tokens come from the same OAuth 2.1 server, with PKCE. Name the API as the resource when you authorize: resource=https://mcp.walletconnect.com/api. A user has to open the consent page and approve in their wallet; there are no API keys.

1. A call without a token returns 401 and points to the resource metadata, which names the authorization server.
2. Register your client (see below), send the user to /authorize with a code challenge and the resource, and exchange the code at /token.
3. Access tokens last one hour and refresh tokens rotate. A grant that keeps refreshing never expires; one left idle for 30 days does.

How your client registers depends on what it is:

• A local agent or CLI registers itself at /register with a loopback redirect (http://localhost:<port>/…). Nothing to set up.
• A hosted app uses a client ID metadata document: its client_id is an HTTPS URL on its own domain serving client_name, redirect_uris and token_endpoint_auth_method. The consent page shows that domain next to the app's name.
• A platform that can do neither, such as ChatGPT Actions, needs a pre-registered client. Contact us to get one.

A client that creates the WalletConnect pairing itself adds connect=skip to the authorization request. The consent page then shows only Allow and Deny, and the client pairs through POST /api/v1/wallet/pairings.

Send a transferCopy Anchor Link

# 1. Prepare
curl -X POST https://mcp.walletconnect.com/api/v1/actions/transfers \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to": "0xRECIPIENT_ADDRESS", "amount": "1", "token": "USDC", "chain": "base"}'

# 2. Confirm with plan.hash and your restatement of the request (keys from plan.expectKeys)
curl -X POST https://mcp.walletconnect.com/api/v1/actions/ACTION_ID/confirm \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"plan_hash": "PLAN_HASH", "expect": {"kind": "transfer", "chain": "Base", "asset": "USDC", "amount": "1", "to": "0xRECIPIENT_ADDRESS"}}'

# 3. Wait for the wallet's answer
curl "https://mcp.walletconnect.com/api/v1/actions/ACTION_ID?wait_seconds=55" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

RoutesCopy Anchor Link

Prepare routes answer 201 with the prepared action. Every success is { text, data, images? }: the one-line text an MCP client would see, the tool's typed data, and images such as the pairing QR code.

ErrorsCopy Anchor Link

Errors are { error: { code, message, issues? } }.

Not supported yetCopy Anchor Link

Lending, sign-in with Ethereum (SIWE), per-user enablement of protocols, limits in USD, bridging, a local stdio server, and Solana.

FAQCopy Anchor Link