bwalletx: the bWalletX CLI and MCP server

Run bWalletX agent accounts from the command line or from any MCP client (Claude Desktop, Claude Code, Cursor). v1 is standalone mode: the CLI holds one agent account's exported key file, encrypted with a passphrase. Paired mode (scoped tokens from the app) comes later; bwalletx login says so.

Only agent accounts can be exported, never the main wallet. The agent account's balance is the budget.

Install

npm i -g bwalletx      # Node 20+

Related MCP server: seashail

Pair with your phone (recommended)

Keys stay on your phone. In bWalletX (5.1.40+), open your agent account, then run:

bwalletx login --account phone

Scan the QR in the terminal from bWalletX (Settings › Paired websites › Scan to connect), check both screens show the same 4-digit code, choose what the CLI may do (see balances; buy and load strategies; send BSV) and for how long (1, 7 or 30 days), then tap Pair. Every command for that account becomes an end-to-end encrypted request: bWalletX checks it against the account's Stop switch, daily cap and loaded strategy, then signs it. Keep bWalletX open on that account while the CLI works. Disconnect any time in the app (Settings › Paired websites) or with bwalletx logout --account phone.

For unattended servers where no phone is around, import a key file instead (below).

Install (from source)

git clone <this repo> bwalletx-cli && cd bwalletx-cli
pnpm install
pnpm build
pnpm link --global      # puts `bwalletx` on your PATH (or run `node dist/cli.js`)

Node 20+ required.

Import an agent account

In bWalletX: Settings › Agents › account › Export key file. Then:

bwalletx key import ./trader.key.json     # asks for the passphrase (or set BWALLETX_PASSPHRASE)
bwalletx accounts

The file is checked by decrypting it once, then stored still encrypted at ~/.bwalletx/accounts/<name>.key.json (mode 600). Keys are only decrypted in memory, when a live transaction is signed. Set BWALLETX_HOME to keep state somewhere other than ~/.bwalletx.

Key file format (bwalletx.agentkey/1)

{"format":"bwalletx.agentkey/1","name":"trader","identityAddress":"1…",
 "enc":{"kdf":"pbkdf2-sha256","iter":310000,"salt":"<b64 16 bytes>","iv":"<b64 12 bytes>",
        "alg":"aes-256-gcm","data":"<b64 ciphertext || 16-byte GCM tag>"}}

data decrypts to {"payPk":WIF,"ordPk":WIF,"identityPk":WIF}. PBKDF2-SHA256 over the UTF-8 passphrase → AES-256-GCM, tag appended to the ciphertext exactly as WebCrypto returns it. src/keyfile.ts (encryptKeyFile / decryptKeyFile) uses only crypto.subtle, so the app can use the same code.

Commands

bwalletx balance --account trader                 # BSV + BSV-21 tokens, valued in USD
bwalletx price <tokenId>                          # floor price, USD per token
bwalletx send 5 richard@bwalletx.com --account trader   # $5 of BSV to a paymail or address
bwalletx buy <tokenId> --max-usd 2 --account trader
bwalletx strategy load ./accumulator.json --account trader          # paper ($100 pretend book)
bwalletx strategy load ./accumulator.json --account trader --live   # real money
bwalletx strategy show | unload
bwalletx agent run trader --interval 300          # rule-driven loop; Ctrl-C to stop
bwalletx log --account trader                     # ~/.bwalletx/log/trader.jsonl
bwalletx stop                                     # kill switch: refuse all spending
bwalletx resume
bwalletx cap trader 10                            # optional $10/day cap ("off" to clear)
bwalletx mcp                                      # stdio MCP server

Add --json for machine-readable output. send asks for confirmation on a terminal; -y skips it.

Token ids are BSV-21 ids (txid_vout). send moves BSV, so when a strategy is loaded its rules.tokens must include "BSV", actions must include "send", and the recipient must be in sendTo.

The gate

Every spending action, from the CLI, agent run or MCP, passes the same checks in this order:

1. Kill switch (bwalletx stop, file ~/.bwalletx/STOP) or the account is stopped

2. Daily cap for the account (if set)

3. Rate limit: at most 30 spending actions per hour per account (paper and failed attempts count)

4. Strategy rules (bwalletx.strategy/1; same parseStrategy / checkRules / paperFill as the app)

5. Paper mode fills on the paper book and never signs

Every refusal is logged with the rule that refused it.

Strategies

Same format as the app; see docs/STRATEGY-FORMAT.md in the bWalletX repo. Example:

{
  "format": "bwalletx.strategy/1",
  "name": "Slow accumulator",
  "version": "1.0",
  "goals": "Build a position slowly while the price is low.",
  "rules": {
    "tokens": ["<bsv21 id txid_vout>"],
    "actions": ["buy"],
    "buyBelowUsd": 0.001,
    "maxPerTradeUsd": 2,
    "maxPerDayUsd": 10,
    "maxTotalUsd": 200,
    "stop": { "holdTokens": 100000 }
  }
}

agent run needs no AI: each tick, for every BSV-21 id in rules.tokens, if buy is allowed and the floor price is at or below buyBelowUsd, it asks to buy maxPerTradeUsd worth. The gate decides.

Live vs paper

Live sends sign with the account's key file; set BWALLETX_PASSPHRASE for unattended use (MCP, servers). 1-sat outputs are never spent as fee money, so ordinals and tokens on the pay address are safe.

bwalletx buy <tokenId> --max-usd 5 shows the exact totals (seller, market fee, overlay fee, network fee) and asks before broadcasting; -y or BWALLETX_YES=1 skips the prompt. The gate sees the full dollar cost including fees. --dry-run builds and verifies the purchase against the real listing with throwaway keys and a synthetic funding coin, without touching your account or broadcasting.

MCP

Tools: accounts, balance, price, send, buy, strategy_show, strategy_load (always loads in paper mode; going live is a human step), log, stop_all. Spending tools use the gate above.

Claude Code

claude mcp add bwalletx -e BWALLETX_PASSPHRASE=your-passphrase-here -- bwalletx mcp

Claude Desktop (claude_desktop_config.json) and Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "bwalletx": {
      "command": "bwalletx",
      "args": ["mcp"],
      "env": { "BWALLETX_PASSPHRASE": "your-passphrase-here" }
    }
  }
}

Leave out BWALLETX_PASSPHRASE to keep MCP read-only and paper-only: live sends then fail with "No passphrase". If bwalletx isn't on the PATH, use "command": "node", "args": ["/path/to/bwalletx-cli/dist/cli.js", "mcp"].

Development

pnpm build
pnpm test      # keyfile round-trip, strategy rules, gate order, rate limit, paper book, offline send signing

Tests use freshly generated throwaway keys only.