Skip to main content
Time: under 5 minutes. By the end of this guide, your AI agent will be able to check balances, look up prices, estimate fees, and prepare transactions - all through natural language.
This page walks the self-hosted OWS path that ships today. A hosted TEE-backed deployment for consumer-scale and platform operators is planned for Q2–Q3 2026 — see Self-Hosting Over HTTP → Roadmap or contact us.

​
What Your Agent Will Be Able to Do

  • What's Vitalik's ETH balance? — queries the blockchain in real-time
  • How much is 1 ETH in USD? — gets the current market price
  • What would the gas fee be for sending 0.1 ETH? — estimates the network fee
  • Prepare a transfer of 0.1 ETH to 0x... — builds an unsigned transaction payload

​
Prerequisites

  • WalletSuite API key — see Credentials & Authentication
  • An MCP-compatible host or framework - Claude Desktop, Claude Code, LangChain, CrewAI, LlamaIndex or any MCP client
  • Node.js 22+

​
Step 1 — Install (30 seconds)

Add WalletSuite MCP to your client’s MCP config: 
{
  "mcpServers": {
    "walletsuite": {
      "command": "npx",
      "args": ["-y", "@walletsuite/mcp-server"],
      "env": { "WALLETSUITE_API_KEY": "your-key" }
    }
  }
}
The server starts in read mode by default — seven tools for balances, prices, fees, and transaction history. No passphrase, no vault, no signing. Where to put this config depends on your host:
HostConfig Location
Claude Code.mcp.json in your project root
For full framework-specific instructions, see Install Guides.

​
Step 2 — Restart Your Host

After saving the config, restart the application or reload MCP servers from the host settings.

​
Step 3 — Try It

Ask your agent any of these: 
What is the ETH balance of 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?
You should see a structured response with the balance in ETH and its USD value. Try a few more:
  • What's the price of ETH right now?
  • Show me recent transactions for 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 on ethereum
  • Resolve USDC on ethereum — finds the token contract address
  • What would the gas fee be for sending 1 ETH from 0xabc to 0xdef?

​
Step 4 — Expand Access (Optional)

By default, your agent can only read data (MCP_BANDS=read, 7 tools). To allow more: Add transaction preparation when you want the agent to construct payloads: 
"MCP_BANDS": "read,prepare"
This adds 3 tools — prepare_transfer, prepare_serialized_unsigned_tx, prepare_onramp. The agent can now construct unsigned transaction payloads but cannot sign or broadcast them.

​
What Happens Under the Hood

Your agent asks a question
  → MCP host sends a tool call to WalletSuite MCP (running locally)
    → WalletSuite MCP calls the WalletSuite REST API
      → API queries the blockchain
    → WalletSuite MCP returns a structured response
  → Your agent reads the response and answers naturally
No keys are involved for read operations. The MCP server is an orchestration layer that translates natural language into blockchain queries.

​
Production signing

When you’re ready to sign and broadcast, enable OWS with the full band set: 
"MCP_BANDS": "full",
"OWS_ENABLED": "true",
"OWS_AUTH_MODE": "owner",
"OWS_PASSPHRASE": "your-passphrase"
Keys are generated and stored locally on the host that runs OWS — WalletSuite never sees them. The example above uses owner mode — an interactive setup where the vault passphrase unlocks the vault for bootstrap and admin operations. For headless or multi-agent deployments, switch the same MCP server to agent mode with a scoped token bound to a policy (chain allowlists, spend limits, expiry). The vault passphrase is not required at runtime in agent mode. See OWS Local Signing for the full token-issuance and policy-binding flow, and Policy Gates for the policy primitives themselves. Before enabling signing, read:

​
Next Steps