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.

Website · Dashboard · Docs · CLI · npm

Add one JSON block to your MCP client config. That's it.

{
  "mcpServers": {
    "botwallet": {
      "command": "npx",
      "args": ["-y", "@botwallet/mcp"]
    }
  }
}

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

{
  "mcpServers": {
    "botwallet": {
      "command": "npx",
      "args": ["-y", "@botwallet/mcp"]
    }
  }
}

Cursor

Go to Settings > MCP, click Add new MCP server, and add:

{
  "mcpServers": {
    "botwallet": {
      "command": "npx",
      "args": ["-y", "@botwallet/mcp"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "botwallet": {
      "command": "npx",
      "args": ["-y", "@botwallet/mcp"]
    }
  }
}

Cline

Open the Cline sidebar, click MCP Servers, then Configure, and add:

{
  "mcpServers": {
    "botwallet": {
      "command": "npx",
      "args": ["-y", "@botwallet/mcp"]
    }
  }
}

Other MCP clients

The config is the same everywhere — npx -y @botwallet/mcp as the command.

Global install (alternative)

npm install -g @botwallet/mcp

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

┌─────────────────┐     stdio (JSON-RPC)     ┌──────────────────┐
│   AI Client     │◄────────────────────────►│  Botwallet MCP   │
│ (Claude/Cursor) │                          │     Server       │
└─────────────────┘                          └────────┬─────────┘
                                                      │
                                              ┌───────┴───────┐
                                              │               │
                                     ~/.botwallet/     api.botwallet.co
                                     (seeds, config)        (API)
                                                              │
                                                        ┌─────┴─────┐
                                                        │  Solana   │
                                                        │ (mainnet) │
                                                        └───────────┘

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.

Development

git clone https://github.com/botwallet-co/mcp.git
cd mcp
npm install
npm run build
npm test                # 76 tests (unit + integration + E2E)
npm run inspect         # Open in MCP Inspector

License

Apache 2.0