Botwallet Co MCP README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Botwallet Co MCP listing page.
Botwallet MCP Server
Let your AI agent send invoices to earn, pay for APIs and manage money, while you stay in control.
Give your AI agent financial autonomy without giving up control. Your agent can create invoices to get paid, spend on other agents and paid APIs, and manage its own USDC wallet. You set the spending limits, approve large transactions, and see everything it does. Works with Claude Desktop, Cursor, Windsurf, Cline, and any MCP-compatible client.
Add one JSON block to your MCP client config. That's it.
Then tell your agent: "Create a Botwallet for yourself."
It runs botwallet_register, generates a cryptographic key share locally, and comes back with a deposit address. No setup, no API keys to configure beforehand.
From there:
"Send $5 to @acme-bot for the data report"
If the amount is within guard rails, the agent signs and submits. If not, it asks the human owner for approval.
"Create an invoice for $25 for the consulting session"
The agent creates a paylink. When someone pays it, the USDC goes straight to the wallet.
"Find a speech-to-text API and use it"
The agent searches the x402 catalog, finds a paid API, pays for access, and returns the result.
How signing works
Every wallet uses FROST 2-of-2 threshold signatures. During wallet creation, a key generation ceremony produces two shares:
- S1 — the agent's share, stored locally at
~/.botwallet/seeds/ - S2 — the server's share, held by Botwallet
The full private key never exists. Every transaction requires both parties to co-sign. Neither the agent nor Botwallet can move funds alone. Human owners set spending limits and approve anything outside the rules.
Installation
Claude Desktop
Add to your Claude Desktop config file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Cursor
Go to Settings > MCP, click Add new MCP server, and add:
Windsurf
Add to ~/.codeium/windsurf/mcp_config.json:
Cline
Open the Cline sidebar, click MCP Servers, then Configure, and add:
Other MCP clients
The config is the same everywhere — npx -y @botwallet/mcp as the command.
Global install (alternative)
If you install globally, use botwallet-mcp as the command instead of npx -y @botwallet/mcp.
Environment variables
| Variable | Default | Purpose |
|---|---|---|
BOTWALLET_API_KEY | — | API key (alternative to config file) |
BOTWALLET_WALLET | — | Which wallet to use (if you have several) |
BOTWALLET_BASE_URL | https://api.botwallet.co/v1 | Custom API endpoint |
All optional. The server reads ~/.botwallet/config.json (shared with the CLI) and figures out the rest.
Tools
36 tools across 8 groups.
Wallet management
| Tool | What it does |
|---|---|
botwallet_ping | Check API connectivity |
botwallet_register | Create a new wallet (FROST key generation) |
botwallet_info | Wallet metadata and status |
botwallet_balance | On-chain balance and remaining budget |
botwallet_update_owner | Set owner email |
botwallet_rename | Change display name |
botwallet_wallet_list | List local wallets |
botwallet_wallet_use | Switch active wallet |
Payments
| Tool | What it does |
|---|---|
botwallet_lookup | Check if a recipient exists |
botwallet_can_i_afford | Pre-flight check before paying |
botwallet_pay | Pay someone (auto-signs if within limits) |
botwallet_confirm_payment | Complete a payment after owner approval |
botwallet_list_payments | List outgoing payments |
botwallet_cancel_payment | Cancel a pending payment |
Earning
| Tool | What it does |
|---|---|
botwallet_create_paylink | Create a payment request or invoice |
botwallet_send_paylink | Send a paylink via email or bot inbox |
botwallet_get_paylink | Check paylink status |
botwallet_list_paylinks | List your paylinks |
botwallet_cancel_paylink | Cancel a pending paylink |
Funding
| Tool | What it does |
|---|---|
botwallet_get_deposit_address | Get the USDC deposit address |
botwallet_request_funds | Ask the human owner for funds |
botwallet_list_fund_requests | List past fund requests |
Withdrawals
| Tool | What it does |
|---|---|
botwallet_withdraw | Withdraw USDC to an external Solana address |
botwallet_confirm_withdrawal | Complete a withdrawal after approval |
botwallet_get_withdrawal | Check withdrawal status |
x402 paid APIs
| Tool | What it does |
|---|---|
botwallet_x402_discover | Search for paid APIs |
botwallet_x402_fetch | Probe a URL for payment requirements |
botwallet_x402_pay_and_fetch | Pay and retrieve content from an x402 API |
History and guard rails
| Tool | What it does |
|---|---|
botwallet_transactions | Full transaction ledger |
botwallet_my_limits | View spending limits set by the owner |
botwallet_pending_approvals | List actions waiting for approval |
botwallet_approval_status | Check a specific approval |
botwallet_events | Wallet notifications |
Wallet transfer
| Tool | What it does |
|---|---|
botwallet_wallet_export | Export wallet to an encrypted .bwlt file |
botwallet_wallet_import | Import wallet from a .bwlt file |
botwallet_wallet_backup | Reveal the mnemonic backup phrase |
Resources
| URI | What it returns |
|---|---|
botwallet://status | Wallet summary — balance, budget, seed file status |
Architecture
The server runs locally on the agent's machine. Key shares stay in ~/.botwallet/seeds/ and are never sent over the network. The server talks to the Botwallet API for co-signing and submits the combined signature to Solana.
Security
The agent can't bypass spending limits. Those are enforced server-side. Transactions above the auto-approve threshold go to the human owner for approval. Key shares are stored locally and never leave the machine. There is no full private key anywhere in the system.
See SECURITY.md for vulnerability reporting.
CLI interop
This MCP server and the Botwallet CLI share the same local files:
- Config:
~/.botwallet/config.json - Seeds:
~/.botwallet/seeds/*.seed - Export format:
.bwlt(encrypted, works both directions)
A wallet created with the CLI works in the MCP server, and vice versa.