MCP Server Reference

@botwallet/mcp exposes Botwallet as Model Context Protocol tools over stdio. It works with Claude Desktop, Cursor, Windsurf, Cline and any MCP-compatible client. Source: botwallet-co/mcp.

Configuration

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

With a global install (npm install -g @botwallet/mcp) use "command": "botwallet-mcp" and no args. Client-specific file locations are in Agent setup.

Environment variables

Variable	Default	Purpose
`BOTWALLET_API_KEY`	—	API key (alternative to the 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 in 8 groups. Amounts are USD (USDC); usernames are passed without the @.

Wallet management

Tool	Parameters	What it does
`botwallet_ping`	—	Check API connectivity (no auth)
`botwallet_register`	`name`, `owner_email?`, `agent_model?`, `description?`, `metadata?`	Create a wallet with FROST key generation; saves the key share to `~/.botwallet/seeds/` and returns the claim link
`botwallet_info`	—	Wallet metadata, status, owner and claim info
`botwallet_balance`	—	On-chain balance, budget, amount spent and remaining allowance
`botwallet_update_owner`	`owner_email`	Set the owner email of an unclaimed wallet
`botwallet_rename`	`name`	Change the display name
`botwallet_wallet_list`	—	List local wallets
`botwallet_wallet_use`	`name`	Switch the active wallet

Payments

Tool	Parameters	What it does
`botwallet_lookup`	`username`	Check that a recipient exists
`botwallet_can_i_afford`	`to`, `amount`	Pre-flight balance and guard-rail check
`botwallet_pay`	`to` + `amount` or `payment_request_id`, `note?`, `reference?`, `idempotency_key?`	Pay a bot, merchant or paylink. Within guard rails it signs and completes immediately (`paid: true`); otherwise it returns `needs_approval: true` with a `transaction_id` and `approval_url`
`botwallet_confirm_payment`	`transaction_id`	Complete a payment after the owner approved it (FROST signing)
`botwallet_list_payments`	—	List outgoing payments
`botwallet_cancel_payment`	`transaction_id`	Cancel a pending or pre-approved payment

Earning

Tool	Parameters	What it does
`botwallet_create_paylink`	`description`, `amount?`, `items?`, `reference?`, `expires_in?`, `reveal_owner?`	Create a payment request or itemized invoice
`botwallet_send_paylink`	`request_id`, `to_email?` or `to_wallet?`, `message?`	Send it by email or to a bot’s inbox
`botwallet_get_paylink`	`request_id?` or `reference?`	Check whether it has been paid
`botwallet_list_paylinks`	—	List your paylinks
`botwallet_cancel_paylink`	`request_id`	Cancel a pending paylink

Funding

Tool	Parameters	What it does
`botwallet_get_deposit_address`	—	USDC deposit address on Solana
`botwallet_request_funds`	`amount`, `reason`	Ask the owner for funds
`botwallet_list_fund_requests`	—	Past fund requests and their status

Withdrawals

Tool	Parameters	What it does
`botwallet_withdraw`	`amount`, `to_address`, `reason`, `idempotency_key?`	Request a withdrawal to an external Solana address
`botwallet_confirm_withdrawal`	`transaction_id`	Complete it after approval
`botwallet_get_withdrawal`	`withdrawal_id`	Status, fees and, when complete, the Solana signature

x402 paid APIs

Tool	Parameters	What it does
`botwallet_x402_discover`	`query?`	Search the curated catalog of paid APIs
`botwallet_x402_fetch`	`url`, `method?`, `headers?`, `body?`	Probe a URL. Free content is returned directly; a 402 response yields the price and a `fetch_id`. Nothing is spent
`botwallet_x402_pay_and_fetch`	`fetch_id`, `headers?`, `body?`	Pay, fetch the content and settle

History and guard rails

Tool	Parameters	What it does
`botwallet_transactions`	—	Full transaction ledger
`botwallet_my_limits`	—	Spending limits set by the owner
`botwallet_pending_approvals`	—	Actions waiting for approval, with approval URLs
`botwallet_approval_status`	`approval_id`	`pending`, `approved`, `rejected` or `expired`; when approved, includes the tool and arguments to confirm
`botwallet_events`	`types?`, `limit?`, `unread_only?`, `since?`, `mark_read?`	Wallet notifications

Wallet transfer

Tool	Parameters	What it does
`botwallet_wallet_export`	`output_path`	Export the wallet to an encrypted `.bwlt` file
`botwallet_wallet_import`	`file_path`	Import a `.bwlt` file
`botwallet_wallet_backup`	—	Reveal the 12-word backup phrase of the local key share. Sensitive: only on explicit user request

Resources

URI	What it returns
`botwallet://status`	Wallet summary: balance, limits, deposit address and local key-share status

Approval flow

botwallet_pay (or a withdrawal or x402 purchase) returns needs_approval: true with a transaction_id, approval_id and approval_url.
The agent stores the transaction_id and polls botwallet_approval_status, or watches botwallet_events for approval_resolved.
Once approved, the agent calls botwallet_confirm_payment (or botwallet_confirm_withdrawal) with the transaction_id.

How it works

The server runs locally on the agent’s machine and talks to api.botwallet.co over HTTPS. Key shares stay in ~/.botwallet/seeds/ and are never sent over the network; the server co-signs with Botwallet and submits the combined signature to Solana. Spending limits are enforced server-side, so the agent cannot bypass them.

CLI interop

The MCP server and the CLI share ~/.botwallet/config.json, ~/.botwallet/seeds/*.seed and the .bwlt export format. A wallet created with one works with the other.