Agent Setup

Botwallet has two agent-facing integrations that share the same wallet files. Use the CLI when your agent has shell access (scripts, CI, OpenClaw, terminal agents) and the MCP server when it runs inside an MCP client such as Claude Desktop, Cursor, Windsurf or Cline.

CLI

Install

Method	Command
npm	npm install -g @botwallet/agent-cli
Homebrew	brew install botwallet-co/tap/botwallet
Shell script (Linux/macOS)	curl -fsSL https://botwallet.co/install.sh | sh
PowerShell (Windows)	iwr https://botwallet.co/install.ps1 | iex
Scoop (Windows)	scoop bucket add botwallet https://github.com/botwallet-co/scoop-bucket then scoop install botwallet
Go	go install github.com/botwallet-co/agent-cli@latest

Binaries for every platform are also on GitHub Releases.

Local files

botwallet register writes everything the CLI needs:

Path	Contents
~/.botwallet/config.json	API key, username and public key per wallet, plus the default wallet
~/.botwallet/seeds/<wallet>.seed	The agent’s FROST key share (S1). Never leaves the machine

Both are shared with the MCP server. Treat the seed file like a private key: back it up, never commit it, never send it anywhere.

Authentication

The CLI resolves credentials in this order:

1. --api-key flag
2. BOTWALLET_API_KEY (or BW_API_KEY) environment variable
3. --wallet <name> flag, selecting a wallet from the config file
4. The default wallet in ~/.botwallet/config.json

An API key alone is enough for read-only calls, but signing (pay confirm, withdraw confirm, x402 fetch confirm) also needs the matching seed file on the machine.

Global flags

Flag	Description
--human	Formatted, colored output instead of JSON
--wallet <name>	Use a specific local wallet
--api-key <key>	Override the API key
--api-url <url>	Custom API base URL (development)

Multiple wallets

botwallet register --name "Research bot" --owner you@email.com
botwallet register --name "Ops bot" --owner you@email.com
botwallet wallet list                          # local wallets and the default
botwallet wallet use ops-bot                   # switch the default
botwallet wallet balance --wallet research-bot # one-off override

Moving a wallet to another machine

botwallet wallet export -o my-wallet.bwlt      # on the old machine
botwallet wallet import my-wallet.bwlt         # on the new machine

The .bwlt file is encrypted with AES-256-GCM. The decryption key is held by the server and retrieved during import, so the file alone cannot unlock the wallet. The format is shared with the MCP server.

Backing up the key share

botwallet wallet backup

This starts a two-step confirmation and then reveals the 12-word backup phrase for the agent’s share. The owner needs this phrase, together with the server share from the dashboard, to recover funds without the agent, and to authorize dashboard withdrawals through the signing portal.

MCP server

Configure your client

Add one block to your MCP client configuration. No API key is needed up front: the agent calls botwallet_register on first use.

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

Client	Where
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
Cursor	Settings → MCP → Add new MCP server
Windsurf	~/.codeium/windsurf/mcp_config.json
Cline	MCP Servers → Configure in the Cline sidebar
Other clients	The same command everywhere: npx -y @botwallet/mcp

Installed globally (npm install -g @botwallet/mcp), the command is botwallet-mcp.

Environment variables

All optional. The server reads ~/.botwallet/config.json and works out the rest.

Variable	Default	Purpose
BOTWALLET_API_KEY	—	API key (alternative to the config file)
BOTWALLET_WALLET	—	Which local wallet to use when there are several
BOTWALLET_BASE_URL	https://api.botwallet.co/v1	Custom API endpoint

Set them in the env block of the server entry in your client config.

First run

Tell the agent: “Create a Botwallet for yourself.” It runs botwallet_register, saves the key share locally and returns the claim link. Claim the wallet in the dashboard, then the agent can pay, invoice and buy API access. The full tool list is in the MCP reference.

Cursor plugin and OpenClaw skill

• The Botwallet plugin on the Cursor Marketplace bundles the MCP server with skills for wallet operations and x402, plus rules for transaction safety, checking pending events and key backups.
• The OpenClaw skill teaches shell-based agents the CLI workflow.

Recommended agent workflow

These habits come from the CLI’s built-in guidance (botwallet docs) and the MCP tool descriptions.

1. Check for news at the start of a session. botwallet events (or botwallet_events) lists unread notifications: resolved approvals, deposits, funded requests, guard-rail changes. Act on them, then botwallet events --mark-read.
2. Preview before paying. botwallet pay preview @to <amount> (or botwallet_can_i_afford) tells you whether the payment will pass balance and guard-rail checks.
3. Handle approvals asynchronously. When a payment, withdrawal or x402 purchase returns awaiting_approval, store the approval_id in persistent memory, poll botwallet approval status <id>, and run the matching confirm command once it is approved.
4. Use idempotency keys on retries. --idempotency-key on pay and withdraw (or idempotency_key in MCP) prevents duplicate transactions when a call times out.
5. Track your invoices. Give paylinks a --reference and look them up with paylink get --reference <ref>. Paylinks expire (--expires 1h|24h|7d, default 24h).
6. Ask for funds instead of failing. botwallet fund <amount> --reason "..." notifies the owner and creates a funding link.
7. Never hardcode addresses or amounts in source code, and never print or commit the seed file.