Build an AI Wallet Agent in 15 Minutes with MCP

WalletSuite MCP is a Model Context Protocol (MCP) server that gives AI agents on-chain wallet access across 79 blockchains. Install via npx, configure one JSON block, and your agent can query balances, look up prices, and prepare transfers — no SDK, no RPC, no boilerplate.

Your AI agent needs to move money. The alternative is weeks of wallet plumbing — RPC providers, gas estimation, nonce management, key security — before it sends a single transaction. Then repeat for every chain. WalletSuite is wallet infrastructure for AI agents: one MCP server handles safety, spend governance, and key isolation so you don't have to.

What You'll Build

An AI agent (Claude) connected to WalletSuite MCP that can:

• Query wallet balances — native tokens and ERC-20s with fiat values
• Look up real-time token prices by symbol or contract address
• Resolve token contracts from names or symbols
• Check transaction status and history
• Prepare unsigned transfer payloads

All 16 tools across 4 bands, accessed through natural language — this tutorial covers the read and prepare tools. No blockchain libraries required.

Prerequisites

• Claude Desktop or Claude Code
• Node.js 22+ (for npx) or Docker
• A WalletSuite API key (request early access)

Step 1: Configure the MCP Server

Add WalletSuite to your Claude MCP config.

Claude Desktop — edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "walletsuite": {
      "command": "npx",
      "args": ["@walletsuite/mcp-server"],
      "env": {
        "WALLETSUITE_API_KEY": "sk_your_key_here",
        "MCP_BANDS": "read,prepare"
      }
    }
  }
}

Claude Code — add to .mcp.json in your project root:

{
  "mcpServers": {
    "walletsuite": {
      "command": "npx",
      "args": ["@walletsuite/mcp-server"],
      "env": {
        "WALLETSUITE_API_KEY": "sk_your_key_here",
        "MCP_BANDS": "read,prepare"
      }
    }
  }
}

Restart Claude. You should see "walletsuite" in the MCP tools list with 10 read and prepare tools (16 total with OWS enabled).

Configuration notes: MCP_BANDS controls which tools load. Use "read" for read-only agents, "read,prepare" to also build unsigned transfers. The default is read if omitted — safe by default. The server enforces HTTPS on the API URL (localhost is exempt for development).

Step 2: Query an AI Agent Wallet

Open Claude and type:

check balances for 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD1a

Claude calls get_all_balances behind the scenes and returns:

Balances for 0x742d...bD1a on Ethereum:

Asset     Amount        USD Value
ETH       4.2061        $8,358.13
USDC      1,250.00      $1,249.87
USDT      500.00        $499.95

Total portfolio: ~$10,107.95

No SDK import. No RPC URL. No ethers.js. The MCP server detected the Ethereum address format (0x prefix), queried native ETH and token balances, fetched USD prices, and returned structured results — all from one natural language prompt. Address formats are validated per chain: 0x-prefixed for Ethereum, T-prefixed for Tron.

Ready to try it? Get your API key, run npx @walletsuite/mcp-server, and query your first wallet in under 2 minutes. Early access is free.

Step 3: Look Up Prices

what's the current ETH price?

Claude calls get_price with the symbol "ETH" and returns the current price with the base currency (USD by default). You can also query by contract address for less common tokens:

price of token at contract 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48

The get_price tool accepts a symbol or contract address, with an optional chain parameter (defaults to Ethereum) and base currency.

Step 4: Resolve a Token

Before transferring a token, you need its contract address. The resolve_asset tool finds verified candidates:

find the USDC token contract on ethereum

Claude calls resolve_asset with the symbol "USDC" on Ethereum and returns candidates with their contract addresses. The resolution status is "unique" (one match), "ambiguous" (multiple matches — user must choose), or "not_found."

This two-step flow is intentional: prepare_transfer never guesses token contracts from symbols. You resolve first, then transfer with the verified contract address.

Step 5: Prepare a Transfer

When you're ready to move funds:

prepare a transfer of 0.5 ETH to 0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B

Claude calls prepare_transfer, which:

1. Validates the address format and chain parameter via Zod
2. Resolves the amount — accepts human-readable ("0.5") or exact wei values, but never both simultaneously
3. Builds the unsigned transaction payload via the WalletSuite API
4. Returns the transaction details for your review

Transfer prepared:

From:    0x742d...1a2B
To:      0xAb58...eC9B
Amount:  0.5 ETH

Ready to sign. Sign with your wallet to broadcast.

The agent never sees private keys. You sign the unsigned payload externally with your own wallet infrastructure.

For token transfers, include the contract address from the resolve_asset step:

prepare a transfer of 100 USDC (contract 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48) to 0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B

How the MCP Wallet Server Works

Band Filtering and Spend Governance

WalletSuite uses band filtering to control which tools enter the LLM's context window — the foundation of spend governance for AI agents:

Choose bands at connection time via environment variable:

"env": {
  "WALLETSUITE_API_KEY": "sk_...",
  "MCP_BANDS": "read,prepare"
}

The default band is read if MCP_BANDS is not set — safe by default. An agent on the read band can never see broadcast tools, let alone call them. Band caps are the first layer; policy-gated signing (chain allowlists, daily spend limits, scoped agent tokens) adds the second.

Structured Errors

When something goes wrong, the MCP server returns errors that guide the LLM's next action:

{
  "category": "validation",
  "code": "MISSING_TOKEN_CONTRACT",
  "message": "USDT is not the native token for ethereum. Provide tokenContract.",
  "requiredAction": "resolve_asset"
}

Six error categories: validation (fix input), upstream (retry with backoff — automatic 3 attempts), flow (execute requiredAction first), auth (configure API key), limit (back off), and not_available (feature-gated to a different plan). Each error includes a requiredAction field that tells the agent what to do next — no guessing, no hallucinating recovery steps.

Key Isolation and Audit Trail

Private keys never leave your machine. The MCP server never handles, stores, or transmits them — full key isolation by design. The prepare_transfer tool builds unsigned payloads. You sign with your own wallet infrastructure — MetaMask, Ledger, or any signing solution you control. Alternatively, enable OWS (Open Wallet Standard) for local signing — keys stay encrypted in a local vault, never transmitted to WalletSuite.

Every tool call is logged with structured metadata: operation, duration, and outcome. No raw addresses or transaction hashes in logs — just operation labels ([tool] get_balance OK (243ms)). All inputs validated via Zod schemas before API calls. HTTPS enforced on the API URL at startup (localhost exempt for development).

MCP Wallet Server: Capabilities and Roadmap

WalletSuite MCP provides 16 tools across 79 blockchains. Read and prepare tools cover all 79 chains. Local signing and broadcasting via OWS supports Ethereum and Tron, with policy-gated agent mode (90-day default expiry, chain restrictions, scoped tokens).

Coming next:

• Swap and approval tools
• Additional OWS signing chain coverage beyond Ethereum and Tron

If you're building AI agents that interact with blockchains, request early access and tell us what you're building. Early access is free — no credit card, no commitment.

More deep dives on AI agent wallet infrastructure on the WalletSuite blog.

Frequently Asked Questions