clanker-wallet 0.4.2 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # clanker-wallet
 
-Human-approved blockchain transactions for AI agents. Agent proposes a tx, human reviews and signs it from the [web app](https://clanker-wallet.xyz). All communication is end-to-end encrypted.
+Human-approved blockchain transactions for AI agents. Agent proposes a tx, human reviews and signs it from the [web app](https://clanker-wallet.xyz). All communication is end-to-end encrypted. EVM chains take raw transactions; bitcoin and chia take transfers (network, recipient, amount) that the human's wallet builds.
 
 ## Install
 
@@ -36,7 +36,7 @@ clanker-wallet status
 
 ### `pair`
 
-Pair with a human's web app. Run once — `pair` writes identity and pairing to `~/.clanker-wallet/`.
+Pair with a human's web app. Run once per chain family — `pair` writes identity and pairing to `~/.clanker-wallet/`. The web app's bitcoin and chia tabs give pairing JSON with `"chain_family":"bitcoin"` / `"chain_family":"chia"`; each family is kept in its own file, so pairing one never replaces another.
 
 If the pairing JSON contains `"mode":"managed"`, the relay simulates each transaction for the human's review screen, so `tx` also sends the plain transaction fields to it. Otherwise the relay only sees ciphertext. Pair with the JSON as given.
 
@@ -78,13 +78,33 @@ clanker-wallet tx \
 | `--expected-outcome <text>` | no | — | What will happen |
 | `--timeout <ms>` | no | `3600000` (1 h) | How long `tx` blocks waiting for the human |
 
+### `send`
+
+Send bitcoin or chia. The human's wallet builds, signs and broadcasts the transaction; you give the network, recipient and amount. Needs a pairing from the web app's bitcoin or chia tab. Same blocking, `--reason`/`--urgency`/`--expected-outcome`/`--timeout`, output and exit codes as `tx`; exit code 4 means that chain family isn't paired.
+
+```bash
+clanker-wallet send --btc testnet --to tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx --sats 1000 --reason "send 1000 sats on bitcoin testnet"
+clanker-wallet send --xch testnet11 --to txch1qqqsyqcyq5rqwzqfpg9scrgwpugpzysnzs23v9ccrydpk8qarc0sw0amhg --mojos 1000 --fee-mojos 0 --reason "send 1000 mojos on chia testnet11"
+# approved → {"tx_hash":"<bitcoin txid or chia transaction id>","status":"approved"}
+```
+
+| Flag | Required | Default | Description |
+|------|----------|---------|-------------|
+| `--btc <network>` | one of `--btc`/`--xch` | — | `mainnet`, `testnet` or `signet` |
+| `--xch <network>` | one of `--btc`/`--xch` | — | `mainnet` or `testnet11` |
+| `--to <address>` | yes | — | On that network: segwit `bc1...`/`tb1...` (no legacy `1...`/`3...`), or `xch1...`/`txch1...` |
+| `--sats <n>` | with `--btc` | — | Whole sats (1 BTC = `100000000`); the wallet sets the fee |
+| `--mojos <n>` | with `--xch` | — | Whole mojos (1 XCH = `1000000000000`) |
+| `--fee-mojos <n>` | no (chia only) | `0` | Chia fee, shown to the human |
+
 ### `status`
 
-Check current pairing status.
+Check current pairing status. `wallet` and `relay` are the evm pairing's; `pairings` lists every paired chain family.
 
 ```bash
 clanker-wallet status
-# → {"agent_id":"agent_abc123","paired":true,"wallet":"0x...","relay":"wss://..."}
+# → {"agent_id":"agent_abc123","paired":true,"wallet":"0x...","relay":"wss://...",
+#    "pairings":{"evm":{"wallet":"0x...","relay":"wss://...","mode":null,"chain_network":null}}}
 ```
 
 ### `whoami`
@@ -104,7 +124,7 @@ clanker-wallet whoami
 | 1 | Rejected by human |
 | 2 | Timeout |
 | 3 | Connection/relay error |
-| 4 | Not paired |
+| 4 | Not paired (`send`: not paired for that chain family) |
 | 5 | Invalid arguments (bad or missing flag; nothing sent) |
 
 ## State
@@ -113,10 +133,15 @@ Identity and pairing are persisted in `~/.clanker-wallet/`:
 
 ```
 ~/.clanker-wallet/
-  identity.json    # agent keypair (auto-generated on first use)
-  pairing.json     # human's public key + relay URL
+  identity.json        # agent keypair (auto-generated on first use)
+  pairings/evm.json    # per chain family: human's public key + relay URL
+  pairings/bitcoin.json
+  pairings/chia.json
+  pairing.json         # written by 0.4.x; still read as the evm pairing, never changed
 ```
 
+`~/.clanker-wallet/pairings/<family>.json` takes precedence over a 0.4.x `pairing.json`, which is never moved, rewritten or deleted.
+
 ## Common Chain IDs
 
 | Chain | ID |
@@ -129,6 +154,35 @@ Identity and pairing are persisted in `~/.clanker-wallet/`:
 | Sepolia (testnet) | 11155111 |
 | Base Sepolia (testnet) | 84532 |
 
+## MCP (assistants)
+
+`clanker-wallet mcp` runs an MCP server over stdio, so an assistant (Claude Desktop, Claude Code, Cursor, or another MCP host that runs local commands) can ask for transactions as tool calls. The human approves every request on their own device; the server holds no wallet keys. It uses the CLI's identity and pairings in `~/.clanker-wallet/`, so pair first (`clanker-wallet pair '<JSON>'`, once per chain family). In a sandbox the server needs the same relay access and `~/.clanker-wallet/` writes as the CLI.
+
+Claude Code:
+
+```bash
+claude mcp add clanker-wallet -- npx -y clanker-wallet mcp
+```
+
+Claude Desktop (`claude_desktop_config.json`), Cursor (`~/.cursor/mcp.json`), and any other MCP host that runs local stdio servers (command `npx`, args `-y clanker-wallet mcp`):
+
+```json
+{
+  "mcpServers": {
+    "clanker-wallet": { "command": "npx", "args": ["-y", "clanker-wallet", "mcp"] }
+  }
+}
+```
+
+| Tool | Arguments | Returns |
+|------|-----------|---------|
+| `request_evm_tx` | `chain_id`, `to`, `value` (wei, integer string), `data` (default `0x`), `reason`, optional `urgency` / `expected_outcome` | `{"request_id":"req_...","status":"pending","expires_at":"..."}` |
+| `request_transfer` | `family` (`bitcoin`), `network` (`mainnet`, `testnet`, `signet`), `to`, `amount` (sats, integer string), `reason`, optional `urgency` / `expected_outcome` | as above |
+| `get_request` | `request_id`, optional `wait_seconds` (at most 50) | `status`: `pending`, `approved` (with `tx_hash`), `rejected`, `failed` (with `error`), `unknown` (with `error`) or `expired` |
+| `list_pairings` | none | `agent_id`, `fingerprint`, and the paired families (`evm`, `bitcoin`) with network, wallet and mode |
+
+Requests are asynchronous: a request tool returns once the relay has the request, then the assistant calls `get_request` (with `wait_seconds` to wait for an answer) until the status is no longer `pending`. Invalid input or a missing pairing is a tool error, and nothing is sent. Pending requests live in the server process: after 1 h the server stops waiting and reports `expired`, and a restarted server no longer knows them (`get_request` then reports an unknown `request_id`). In both cases the human may still approve the request in their wallet, so ask them before sending it again. `unknown` means the request was delivered but the server lost its relay connection: the human may still approve it, so ask them before sending it again. Chia is not offered over MCP yet.
+
 ---
 
 ## Library Usage (Advanced)
@@ -155,6 +209,19 @@ const txHash = await wallet.requestTx({
 
 `requestTx` throws `InvalidTxError` (with `field` and `reason`) before anything is sent if `chain_id`, `to`, `value` or `data` is malformed.
 
+With a bitcoin or chia pairing, use `requestTransfer`; the family comes from the pairing:
+
+```typescript
+// 1000 mojos on chia testnet11; amount and fee are integer strings or bigints
+const txId = await wallet.requestTransfer({
+  chain_network: 'testnet11',
+  transfer: { asset: 'xch', to: 'txch1qqqsyqcyq5rqwzqfpg9scrgwpugpzysnzs23v9ccrydpk8qarc0sw0amhg', amount: '1000', fee: '0' },
+  context: { reason: 'send 1000 mojos on chia testnet11' },
+})
+```
+
+It throws `InvalidTxError` before sending for an evm pairing, an unknown network, a recipient from another network, a non-integer amount, or a bitcoin `fee` (the wallet sets bitcoin fees). Chia `fee` defaults to `"0"`.
+
 See full API: [`src/`](./src/)
 
 ## Python SDK
@@ -176,14 +243,22 @@ tx_hash = await agent.request_tx(RequestTxOptions(
     transaction=Transaction(to="0x000000000000000000000000000000000000dEaD", value="1000000000000000", data="0x"),
     context=TxContext(reason="send 0.001 ETH on base sepolia"),
 ))
+
+# with a bitcoin pairing: 1000 sats on bitcoin testnet
+from clanker_wallet import RequestTransferOptions, Transfer
+
+txid = await agent.request_transfer(RequestTransferOptions(
+    chain_network="testnet",
+    transfer=Transfer(asset="btc", to="tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx", amount=1000),
+))
 ```
 
 ## How It Works
 
 1. Human opens [clanker-wallet.xyz](https://clanker-wallet.xyz), connects wallet, clicks "copy prompt for agent" — gets a paste-ready prompt that bundles intent, the setup guide URL, and the pairing JSON
 2. Human pastes the prompt to their AI agent. Agent extracts the JSON and runs `clanker-wallet pair` — establishes E2E encrypted channel
-3. Agent runs `clanker-wallet tx` — encrypts tx with nacl.box, sends via WebSocket relay
-4. Human reviews tx details, simulation, risk flags in the web app. A new agent shows up as unverified with its fingerprint; auto-approve rules only apply after the human trusts it. Contract rules (address + methods) don't limit token amounts or recipients
+3. Agent runs `clanker-wallet tx` (or `send` for bitcoin/chia) — encrypts the request with nacl.box, sends via WebSocket relay
+4. Human reviews tx details, simulation, risk flags in the web app. A new agent shows up as unverified with its fingerprint; auto-approve rules only apply after the human trusts it. Trust applies on every chain family; each chain family has its own policy (rules and remote URL), edited while that chain is selected. Value and daily limits are wei for evm and sats for bitcoin (the sent amount; the wallet's fee isn't counted); a send on another family never matches a rule that sets one, and chia has none. On bitcoin the wallet still confirms each auto-approved send. Contract rules (address + methods) don't limit token amounts or recipients
 5. Human approves → wallet signs + broadcasts → agent gets the tx hash
 
 Request and response payloads are encrypted end-to-end; the relay only forwards them. Exception: when paired in managed mode, the agent also sends the transaction fields (from, to, value, data, chainId) to the relay for simulation.

package/SKILL.md

@@ -51,13 +51,15 @@ clanker-wallet pair '{"version":1,"pubkey":"ab12...","relay":"wss://...","wallet
 
 If the human only pastes raw JSON (no prompt prose), pair with it directly. If they only paste the URL, ask them to click "copy prompt for agent" on the pairing screen.
 
-`pair` writes your identity and the pairing to `~/.clanker-wallet/`. You only need to do this once.
+`pair` writes your identity and the pairing to `~/.clanker-wallet/`. You only need to do this once per chain family.
+
+The web app has an evm, a bitcoin and a chia tab, and each tab gives its own pairing JSON (bitcoin and chia add `"chain_family":"bitcoin"` / `"chain_family":"chia"`). Pair each one you need: every family is kept in its own file, `~/.clanker-wallet/pairings/<family>.json` (`evm`, `bitcoin`, `chia`), so pairing one never replaces another. A `~/.clanker-wallet/pairing.json` written by clanker-wallet 0.4.x is still read as the evm pairing and is left untouched.
 
 If the JSON contains `"mode":"managed"`, the human chose managed mode: the relay simulates each transaction for the review screen, so `tx` also sends the plain transaction fields (from, to, value, data, chainId) to the relay, which shares them with its simulation provider. Without it (or with `"mode":"encrypted"`) the relay only sees ciphertext. Pair with the JSON exactly as given either way.
 
 ### Trust (first request)
 
-The web app lists a new agent as unverified and shows its fingerprint (e.g. `ab12 cd34 ef56 7890`). Until the human compares it with the `fingerprint` from `clanker-wallet whoami` and clicks "trust this agent", none of their auto-approve rules apply: every tx waits for manual approval. Contract rules (contract address + allowed methods) do not limit token amounts or recipients: a rule allowing `transfer` on a token auto-approves any amount to any recipient. If asked, run `clanker-wallet whoami` and share the fingerprint.
+The web app lists a new agent as unverified and shows its fingerprint (e.g. `ab12 cd34 ef56 7890`). Until the human compares it with the `fingerprint` from `clanker-wallet whoami` and clicks "trust this agent", none of their auto-approve rules apply: every tx waits for manual approval. Trust applies on every chain family; each chain family has its own policy (rules and remote URL), edited while that chain is selected. Value and daily limits come in two units: wei limits apply to evm only, sats limits to bitcoin only (they count the sent amount, not the fee the wallet adds); a `send` on any other family never matches a rule that sets one and waits for the human. Chia has no value limits. On bitcoin the wallet still asks the human to confirm each auto-approved `send`. Contract rules (contract address + allowed methods) do not limit token amounts or recipients: a rule allowing `transfer` on a token auto-approves any amount to any recipient. If asked, run `clanker-wallet whoami` and share the fingerprint.
 
 ### Transaction notifications
 
@@ -117,6 +119,21 @@ The command **blocks until the human approves or rejects**, for up to 1 hour by
 | `--expected-outcome <text>` | no | — | What will happen |
 | `--timeout <ms>` | no | `3600000` (1 h) | How long `tx` blocks waiting for the human |
 
+## Sending Bitcoin or Chia
+
+Bitcoin and chia sends are transfers: you name the network, recipient and amount, and the human's wallet builds, signs and broadcasts the transaction. Pair the web app's bitcoin or chia tab first.
+
+```bash
+clanker-wallet send --btc testnet --to tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx --sats 1000 --reason "Send 1000 sats on bitcoin testnet"
+clanker-wallet send --xch testnet11 --to txch1qqqsyqcyq5rqwzqfpg9scrgwpugpzysnzs23v9ccrydpk8qarc0sw0amhg --mojos 1000 --fee-mojos 0 --reason "Send 1000 mojos on chia testnet11"
+```
+
+- **network:** `--btc mainnet|testnet|signet` or `--xch mainnet|testnet11`. There is no default network; the recipient must belong to it (`bc1...` on bitcoin mainnet, `tb1...` on testnet/signet, `xch1...` / `txch1...` on chia).
+- **bitcoin recipients are segwit addresses only** (`bc1q...`, `bc1p...`, `tb1...`); legacy `1...`/`3...` addresses are refused.
+- **amounts are whole base units**: `--sats` (1 BTC = `100000000`), `--mojos` (1 XCH = `1000000000000`). No decimals.
+- **fees:** bitcoin fees are set in the human's wallet. Chia takes `--fee-mojos` (default `0`), which the human sees before approving.
+- `--reason`, `--urgency`, `--expected-outcome` and `--timeout` work as for `tx`, and so do the output and exit codes. On approval `tx_hash` is the bitcoin txid or the chia transaction id. Exit code 4 means that chain family isn't paired.
+
 ## Common Chain IDs
 
 | Chain | ID |
@@ -165,17 +182,50 @@ clanker-wallet tx \
 ```bash
 # Check pairing status
 clanker-wallet status
-# → {"agent_id":"agent_abc123","paired":true,"wallet":"0x...","relay":"wss://..."}
+# → {"agent_id":"agent_abc123","paired":true,"wallet":"0x...","relay":"wss://...",
+#    "pairings":{"evm":{"wallet":"0x...","relay":"wss://...","mode":null,"chain_network":null},"chia":{"wallet":"xch1...",...}}}
+# wallet and relay are the evm pairing's; pairings lists every paired chain family
 
 # Show agent identity
 clanker-wallet whoami
 # → {"agent_id":"agent_abc123","public_key":"ab12cd34ef567890...","fingerprint":"ab12 cd34 ef56 7890"}
 ```
 
+## MCP (assistants)
+
+`clanker-wallet mcp` runs an MCP server over stdio, so an assistant (Claude Desktop, Claude Code, Cursor, or another MCP host that runs local commands) can ask for transactions as tool calls. The human approves every request on their own device; the server holds no wallet keys. It uses the CLI's identity and pairings in `~/.clanker-wallet/`, so pair first (`clanker-wallet pair '<JSON>'`, once per chain family). In a sandbox the server needs the same relay access and `~/.clanker-wallet/` writes as the CLI.
+
+If your host supports MCP, the human can add the server instead of you running `tx` / `send`:
+
+Claude Code:
+
+```bash
+claude mcp add clanker-wallet -- npx -y clanker-wallet mcp
+```
+
+Claude Desktop (`claude_desktop_config.json`), Cursor (`~/.cursor/mcp.json`), and any other MCP host that runs local stdio servers (command `npx`, args `-y clanker-wallet mcp`):
+
+```json
+{
+  "mcpServers": {
+    "clanker-wallet": { "command": "npx", "args": ["-y", "clanker-wallet", "mcp"] }
+  }
+}
+```
+
+| Tool | Arguments | Returns |
+|------|-----------|---------|
+| `request_evm_tx` | `chain_id`, `to`, `value` (wei, integer string), `data` (default `0x`), `reason`, optional `urgency` / `expected_outcome` | `{"request_id":"req_...","status":"pending","expires_at":"..."}` |
+| `request_transfer` | `family` (`bitcoin`), `network` (`mainnet`, `testnet`, `signet`), `to`, `amount` (sats, integer string), `reason`, optional `urgency` / `expected_outcome` | as above |
+| `get_request` | `request_id`, optional `wait_seconds` (at most 50) | `status`: `pending`, `approved` (with `tx_hash`), `rejected`, `failed` (with `error`), `unknown` (with `error`) or `expired` |
+| `list_pairings` | none | `agent_id`, `fingerprint`, and the paired families (`evm`, `bitcoin`) with network, wallet and mode |
+
+Flow: call `list_pairings` to see which chains you can use, call `request_evm_tx` or `request_transfer` (same rules as `tx` / `send`: wei and sats as integer strings, real addresses), tell the human a request is waiting (see "Transaction notifications"), then call `get_request` with `wait_seconds` until the status is no longer `pending`. Invalid input or a missing pairing comes back as a tool error and nothing is sent. After 1 h the server stops waiting and reports `expired`, and a restarted server no longer knows its earlier requests (`get_request` then reports an unknown `request_id`). In both cases the human may still approve the request in their wallet, so ask them before sending it again. `unknown` means the request was delivered but the server lost its relay connection: the human may still approve it, so ask them before sending it again. Chia is not offered over MCP yet.
+
 ## Troubleshooting
 
 - **exit code 5 / "invalid --flag: ..."** — fix the named flag; nothing was sent. Usually a placeholder `--to`, a `--value` in ETH instead of wei, or `--data` that isn't even-length hex
-- **exit code 4 / "not paired"** — run `clanker-wallet pair '<JSON>'` first
+- **exit code 4 / "not paired"** — run `clanker-wallet pair '<JSON>'` first (for `send`, with the JSON from the web app's bitcoin or chia tab)
 - **exit code 2 / timeout** — human didn't respond in time, increase `--timeout` or ask them to check the web app
 - **exit code 1 / "rejected"** — human clicked reject. Explain why the tx is needed and try again if appropriate.
 - **exit code 3 / "relay connection error: could not reach wss://..."** — if you run in a sandbox or behind a firewall, allow that host (`relay.clanker-wallet.xyz` by default) and, if the error mentions it, rerun with `NODE_USE_ENV_PROXY=1` (see "Running in a sandbox"); otherwise the relay may be down or rate limiting, try again in a few seconds

package/bin/cli.js

@@ -1,18 +1,29 @@
 #!/usr/bin/env node
-import { ClankerWallet, InvalidTxError, validateTx } from '../dist/index.js'
+import { ClankerWallet, InvalidTxError, validateTransfer, validateTx } from '../dist/index.js'
+import { createMcpServer, MAX_WAIT_SECONDS, REQUEST_STATUSES } from '../dist/mcp.js'
 import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from 'fs'
 import { join } from 'path'
 import { homedir } from 'os'
+import { createInterface } from 'readline'
 
 // ── constants ────────────────────────────────────────────────────────
 const STATE_DIR = join(homedir(), '.clanker-wallet')
 const IDENTITY_FILE = join(STATE_DIR, 'identity.json')
-const PAIRING_FILE = join(STATE_DIR, 'pairing.json')
+// one pairing per chain family: pairings/<family>.json. 0.4.x wrote pairing.json (evm only); it is still read as the
+// evm pairing and never moved, rewritten or deleted
+const PAIRINGS_DIR = join(STATE_DIR, 'pairings')
+const LEGACY_PAIRING_FILE = join(STATE_DIR, 'pairing.json')
+const FAMILIES = ['evm', 'bitcoin', 'chia']
 
 const EXIT = { OK: 0, REJECTED: 1, TIMEOUT: 2, CONNECTION: 3, NOT_PAIRED: 4, BAD_ARGS: 5 }
 const DEFAULT_TIMEOUT_MS = 3_600_000
 /** validateTx field -> the tx flag that sets it */
 const FIELD_FLAGS = { chain_id: '--chain', to: '--to', value: '--value', data: '--data' }
+/** per send network flag (named after the asset it sends): the pairing family it uses and its amount/fee flags */
+const SEND_FAMILIES = {
+  btc: { family: 'bitcoin', amountFlag: 'sats', networks: 'mainnet, testnet or signet' },
+  xch: { family: 'chia', amountFlag: 'mojos', feeFlag: 'fee-mojos', networks: 'mainnet or testnet11' },
+}
 
 // ── helpers ──────────────────────────────────────────────────────────
 const hex = (bytes) => Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('')
@@ -50,15 +61,20 @@ function saveIdentity(data) {
   chmodSync(IDENTITY_FILE, 0o600)
 }
 
-function loadPairing() {
-  if (!existsSync(PAIRING_FILE)) return null
-  try { return JSON.parse(readFileSync(PAIRING_FILE, 'utf8')) }
+function readJson(path) {
+  if (!existsSync(path)) return null
+  try { return JSON.parse(readFileSync(path, 'utf8')) }
   catch { return null }
 }
 
-function savePairing(data) {
+function loadPairing(family) {
+  return readJson(join(PAIRINGS_DIR, `${family}.json`)) ?? (family === 'evm' ? readJson(LEGACY_PAIRING_FILE) : null)
+}
+
+function savePairing(family, data) {
   ensureDir()
-  writeFileSync(PAIRING_FILE, JSON.stringify(data, null, 2) + '\n')
+  if (!existsSync(PAIRINGS_DIR)) mkdirSync(PAIRINGS_DIR, { mode: 0o700 })
+  writeFileSync(join(PAIRINGS_DIR, `${family}.json`), JSON.stringify(data, null, 2) + '\n')
 }
 
 /** restore or create a ClankerWallet with persisted identity */
@@ -114,11 +130,19 @@ function cmdPair(positional) {
     die(`pair failed: ${err.message}`, EXIT.BAD_ARGS)
   }
 
-  savePairing({
+  // the family names the pairing file, so only the known ones are accepted
+  const family = pairingData.chain_family || 'evm'
+  if (!FAMILIES.includes(family)) {
+    die(`pair failed: unsupported chain_family ${JSON.stringify(family)} (expected ${FAMILIES.join(', ')})`, EXIT.BAD_ARGS)
+  }
+
+  savePairing(family, {
     pubkey: pairingData.pubkey,
     relay: pairingData.relay,
     wallet: pairingData.wallet || null,
     mode: pairingData.mode || null,
+    chain_family: pairingData.chain_family,
+    chain_network: pairingData.chain_network,
   })
 
   out({
@@ -126,55 +150,43 @@ function cmdPair(positional) {
     status: 'paired',
     wallet: pairingData.wallet || null,
     relay: pairingData.relay,
+    ...(family !== 'evm' && { chain_family: family }),
   })
 }
 
-async function cmdTx(flags) {
-  const pairing = loadPairing()
-  if (!pairing) die('not paired — run: clanker-wallet pair \'<JSON>\'', EXIT.NOT_PAIRED)
-
-  const chain = flags.chain
-  const to = flags.to
-  if (!chain) die('missing --chain', EXIT.BAD_ARGS)
-  if (!to) die('missing --to', EXIT.BAD_ARGS)
-
-  if (!/^[0-9]+$/.test(chain)) die(`invalid --chain: must be a positive integer chain id, got ${JSON.stringify(chain)}`, EXIT.BAD_ARGS)
+function parseTimeout(flags) {
   if (flags.timeout !== undefined && !/^[1-9][0-9]*$/.test(flags.timeout)) {
     die(`invalid --timeout: must be a positive number of milliseconds, got ${JSON.stringify(flags.timeout)}`, EXIT.BAD_ARGS)
   }
-  const timeout = flags.timeout ? Number(flags.timeout) : DEFAULT_TIMEOUT_MS
-
-  // same checks requestTx runs, done here so a bad flag exits 5 instead of surfacing as a connection error
-  let request
-  try {
-    request = validateTx(Number(chain), { to, value: flags.value ?? '0', data: flags.data ?? '0x' })
-  } catch (err) {
-    if (!(err instanceof InvalidTxError)) throw err
-    die(`invalid ${FIELD_FLAGS[err.field]}: ${err.reason}`, EXIT.BAD_ARGS)
-  }
+  return flags.timeout ? Number(flags.timeout) : DEFAULT_TIMEOUT_MS
+}
 
+function contextFrom(flags) {
   const context = {}
   if (flags.reason) context.reason = flags.reason
   if (flags.urgency) context.urgency = flags.urgency
   if (flags['expected-outcome']) context.expected_outcome = flags['expected-outcome']
+  return Object.keys(context).length > 0 ? context : undefined
+}
 
-  const wallet = getWallet()
-  const pairingJson = JSON.stringify({
+/** a ClankerWallet (the saved identity by default) paired from a saved pairing */
+function pairedWallet(pairing, wallet = getWallet()) {
+  wallet.pair(JSON.stringify({
     version: 1,
     pubkey: pairing.pubkey,
     relay: pairing.relay,
     wallet: pairing.wallet,
     mode: pairing.mode || undefined,
-  })
-  wallet.pair(pairingJson)
+    chain_family: pairing.chain_family,
+    chain_network: pairing.chain_network,
+  }))
+  return wallet
+}
 
+/** wait for the human's answer and exit with its code */
+async function exitWithResult(request) {
   try {
-    const txHash = await wallet.requestTx({
-      chain_id: request.chain_id,
-      transaction: request.transaction,
-      context: Object.keys(context).length > 0 ? context : undefined,
-      timeout_ms: timeout,
-    })
+    const txHash = await request
     out({ tx_hash: txHash, status: 'approved' })
     process.exit(EXIT.OK)
   } catch (err) {
@@ -192,15 +204,99 @@ async function cmdTx(flags) {
   }
 }
 
+async function cmdTx(flags) {
+  const pairing = loadPairing('evm')
+  if (!pairing) die('not paired — run: clanker-wallet pair \'<JSON>\'', EXIT.NOT_PAIRED)
+
+  const chain = flags.chain
+  const to = flags.to
+  if (!chain) die('missing --chain', EXIT.BAD_ARGS)
+  if (!to) die('missing --to', EXIT.BAD_ARGS)
+
+  if (!/^[0-9]+$/.test(chain)) die(`invalid --chain: must be a positive integer chain id, got ${JSON.stringify(chain)}`, EXIT.BAD_ARGS)
+  const timeout = parseTimeout(flags)
+
+  // same checks requestTx runs, done here so a bad flag exits 5 instead of surfacing as a connection error
+  let request
+  try {
+    request = validateTx(Number(chain), { to, value: flags.value ?? '0', data: flags.data ?? '0x' })
+  } catch (err) {
+    if (!(err instanceof InvalidTxError)) throw err
+    die(`invalid ${FIELD_FLAGS[err.field]}: ${err.reason}`, EXIT.BAD_ARGS)
+  }
+
+  const wallet = pairedWallet(pairing)
+  await exitWithResult(wallet.requestTx({
+    chain_id: request.chain_id,
+    transaction: request.transaction,
+    context: contextFrom(flags),
+    timeout_ms: timeout,
+  }))
+}
+
+async function cmdSend(flags) {
+  const picked = Object.keys(SEND_FAMILIES).filter((flag) => flags[flag] !== undefined)
+  if (picked.length !== 1) die('invalid --btc/--xch: give exactly one of --btc <network> or --xch <network>', EXIT.BAD_ARGS)
+  const networkFlag = picked[0]
+  const { family, amountFlag, feeFlag, networks } = SEND_FAMILIES[networkFlag]
+  const network = flags[networkFlag]
+  if (network === true) die(`invalid --${networkFlag}: give the network, ${networks}`, EXIT.BAD_ARGS)
+
+  // another family's amount/fee flag is a mistake, not something to ignore
+  for (const flag of ['sats', 'mojos', 'fee-mojos']) {
+    if (flag !== amountFlag && flag !== feeFlag && flags[flag] !== undefined) {
+      die(`invalid --${flag}: not a --${networkFlag} flag (${family} amounts are --${amountFlag}${feeFlag ? `, fee --${feeFlag}` : ', and the wallet sets the fee'})`, EXIT.BAD_ARGS)
+    }
+  }
+  for (const flag of ['to', amountFlag, feeFlag]) {
+    if (flag && flags[flag] === true) die(`invalid --${flag}: missing value`, EXIT.BAD_ARGS)
+  }
+
+  const pairing = loadPairing(family)
+  if (!pairing) die(`not paired with a ${family} wallet — open the web app's ${family} tab and run: clanker-wallet pair '<JSON>'`, EXIT.NOT_PAIRED)
+
+  if (!flags.to) die('missing --to', EXIT.BAD_ARGS)
+  if (flags[amountFlag] === undefined) die(`missing --${amountFlag}`, EXIT.BAD_ARGS)
+  const timeout = parseTimeout(flags)
+
+  const transfer = { asset: networkFlag, to: flags.to, amount: flags[amountFlag] }
+  if (feeFlag && flags[feeFlag] !== undefined) transfer.fee = flags[feeFlag]
+  const flagFor = { chain_family: networkFlag, chain_network: networkFlag, asset: networkFlag, to: 'to', amount: amountFlag, fee: feeFlag }
+  const badArg = (err) => die(`invalid --${flagFor[err.field]}: ${err.reason}`, EXIT.BAD_ARGS)
+
+  // same checks requestTransfer runs, done here so a bad flag exits 5 instead of surfacing as a connection error
+  try {
+    validateTransfer(family, network, transfer)
+  } catch (err) {
+    if (!(err instanceof InvalidTxError)) throw err
+    badArg(err)
+  }
+
+  const wallet = pairedWallet(pairing)
+  // requestTransfer also refuses a network the pairing isn't for; that is a bad flag too
+  const request = wallet.requestTransfer({ chain_network: network, transfer, context: contextFrom(flags), timeout_ms: timeout })
+  await request.catch((err) => { if (err instanceof InvalidTxError) badArg(err) })
+  await exitWithResult(request)
+}
+
 function cmdStatus() {
   const identity = loadIdentity()
-  const pairing = loadPairing()
+  const pairings = {}
+  for (const family of FAMILIES) {
+    const pairing = loadPairing(family)
+    if (pairing) {
+      pairings[family] = { wallet: pairing.wallet || null, relay: pairing.relay || null, mode: pairing.mode || null, chain_network: pairing.chain_network || null }
+    }
+  }
+  const evm = pairings.evm
 
+  // wallet/relay stay the evm pairing's, as in 0.4.x
   out({
     agent_id: identity?.agent_id || null,
-    paired: !!pairing,
-    wallet: pairing?.wallet || null,
-    relay: pairing?.relay || null,
+    paired: Object.keys(pairings).length > 0,
+    wallet: evm?.wallet || null,
+    relay: evm?.relay || null,
+    pairings,
   })
 }
 
@@ -213,9 +309,55 @@ function cmdWhoami() {
   })
 }
 
+function packageVersion() {
+  return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
+}
+
 function cmdVersion() {
-  const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
-  process.stdout.write(version + '\n')
+  process.stdout.write(packageVersion() + '\n')
+}
+
+function showMcpHelp() {
+  process.stderr.write(`clanker-wallet mcp — MCP server over stdio for assistants (Claude Desktop, Claude Code, Cursor, ...)
+
+uses this agent's identity and pairings (~/.clanker-wallet/); pair first with: clanker-wallet pair '<JSON>'
+every request waits for the human to approve it on their own device.
+
+tools:
+  request_evm_tx    ask for an evm transaction (value in wei, integer string) -> { request_id }
+  request_transfer  ask for a bitcoin send (amount in sats, integer string) -> { request_id }
+  get_request       ${REQUEST_STATUSES.join(' | ')}; wait_seconds up to ${MAX_WAIT_SECONDS}
+  list_pairings     paired chain families, networks, wallets, and the agent fingerprint
+
+claude code:     claude mcp add clanker-wallet -- npx -y clanker-wallet mcp
+other hosts:     {"mcpServers":{"clanker-wallet":{"command":"npx","args":["-y","clanker-wallet","mcp"]}}}
+
+requests are kept in memory: after 1 h the server stops waiting (expired), and a restart forgets pending ones.
+expired, unknown (relay lost after delivery) or forgotten: the human may still approve it, so ask before sending it again.
+docs: https://clanker-wallet.xyz/SKILL.md
+`)
+}
+
+/** serve MCP on stdin/stdout until stdin ends; stdout carries only protocol messages */
+async function cmdMcp(flags) {
+  if (flags.help) return showMcpHelp()
+
+  const identity = getWallet()
+  const server = createMcpServer({
+    version: packageVersion(),
+    identity: { agent_id: identity.agentId, fingerprint: fingerprint(hex(identity.publicKey)) },
+    loadPairing,
+    // the identity loaded at startup, which list_pairings shows: re-reading identity.json per request could switch agents mid-run
+    wallet: (pairing) => pairedWallet(pairing, new ClankerWallet({ secretKey: identity.secretKey })),
+  })
+  const lines = createInterface({ input: process.stdin, crlfDelay: Infinity })
+  // each line is answered when it settles, so a get_request that waits never holds up the others
+  lines.on('line', (line) => {
+    server.handleLine(line).then((reply) => { if (reply) process.stdout.write(reply + '\n') })
+  })
+  await new Promise((resolve) => lines.on('close', resolve))
+  // the host is gone: drop pending requests (their relay sockets would keep the process alive)
+  process.exit(EXIT.OK)
 }
 
 function showHelp() {
@@ -223,9 +365,11 @@ function showHelp() {
 
 commands:
   pair '<JSON>'   pair with human's web app (one-time setup)
-  tx              send a transaction (blocks until approved/rejected)
-  status          check pairing status
+  tx              send an evm transaction (blocks until approved/rejected)
+  send            send btc or xch; the human's wallet builds it (blocks until approved/rejected)
+  status          check pairing status (one pairing per chain family: evm, bitcoin, chia)
   whoami          show agent identity
+  mcp             run an MCP server over stdio for assistants (Claude Desktop/Code, Cursor, ...); mcp --help
 
 tx flags:
   --chain <id>                 chain ID (required) — 1, 8453, 84532 (base sepolia), etc.
@@ -237,18 +381,29 @@ tx flags:
   --expected-outcome <text>    what will happen
   --timeout <ms>               how long tx blocks waiting for the human (default: 3600000 = 1 h)
 
+send flags (pair the web app's bitcoin or chia tab first):
+  send --btc <mainnet|testnet|signet> --to <address> --sats <n>
+  send --xch <mainnet|testnet11> --to <address> --mojos <n> [--fee-mojos <n>]
+  --to <address>               recipient: segwit bc1/tb1 for bitcoin, xch1/txch1 for chia (required)
+  --sats <n>                   bitcoin amount in sats (1 BTC = 100000000); the wallet sets the fee
+  --mojos <n>                  chia amount in mojos (1 XCH = 1000000000000)
+  --fee-mojos <n>              chia fee in mojos (default: 0), shown to the human
+  --reason, --urgency, --expected-outcome, --timeout   as for tx
+
 exit codes:
   0  success
   1  rejected by human
   2  timeout
   3  connection error (in a sandbox or behind a firewall, allow the relay host, wss://relay.clanker-wallet.xyz/ws by default;
      behind HTTPS_PROXY run with NODE_USE_ENV_PROXY=1)
-  4  not paired
+  4  not paired (send: not paired for that chain family)
   5  invalid arguments
 
 examples:
   clanker-wallet pair '{"version":1,"pubkey":"ab12...","relay":"wss://...","wallet":"0x..."}'
   clanker-wallet tx --chain 84532 --to 0x000000000000000000000000000000000000dEaD --value 1000000000000000 --reason "send 0.001 ETH on base sepolia"
+  clanker-wallet send --btc testnet --to tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx --sats 1000 --reason "test payment"
+  clanker-wallet send --xch testnet11 --to txch1qqqsyqcyq5rqwzqfpg9scrgwpugpzysnzs23v9ccrydpk8qarc0sw0amhg --mojos 1000 --fee-mojos 0
   clanker-wallet status
   clanker-wallet whoami
 
@@ -267,12 +422,18 @@ switch (cmd) {
   case 'tx':
     await cmdTx(flags)
     break
+  case 'send':
+    await cmdSend(flags)
+    break
   case 'status':
     cmdStatus()
     break
   case 'whoami':
     cmdWhoami()
     break
+  case 'mcp':
+    await cmdMcp(flags)
+    break
   case '--version':
   case '-v':
     cmdVersion()