BotWallet Server

---

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