clanker-wallet 0.4.1 → 0.5.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
 
@@ -14,6 +14,8 @@ npx clanker-wallet
 bunx clanker-wallet
 ```
 
+Running in a sandbox (e.g. Claude Code)? Allow a WebSocket to the relay, `wss://relay.clanker-wallet.xyz/ws` (the `relay` URL in the pairing JSON), or `tx` fails with exit code 3. If the sandbox only lets traffic out through `HTTPS_PROXY`, run the CLI as `NODE_USE_ENV_PROXY=1 clanker-wallet ...` (Node 24+); Node ignores the proxy otherwise. `pair` writes `~/.clanker-wallet/` and the other commands write there too, so allow writes (see [State](#state)).
+
 ## Quick Start
 
 ```bash
@@ -34,7 +36,9 @@ clanker-wallet status
 
 ### `pair`
 
-Pair with a human's web app. Run once — identity and pairing are saved 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.
 
 ```bash
 clanker-wallet pair '<pairing JSON from web app>'
@@ -43,7 +47,7 @@ clanker-wallet pair '<pairing JSON from web app>'
 
 ### `tx`
 
-Send a transaction request. Blocks until the human approves or rejects, for up to 1 hour by default; `--timeout <ms>` changes that.
+Send a transaction request. Blocks until the human approves or rejects, for up to 1 hour by default; `--timeout <ms>` changes that. If your shell tool kills long commands, run `tx` in the background and read its output when it exits.
 
 ```bash
 clanker-wallet tx \
@@ -74,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`
@@ -100,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
@@ -109,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 |
@@ -151,6 +180,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
@@ -172,14 +214,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

@@ -16,6 +16,16 @@ npm install -g clanker-wallet
 
 Or use without installing: `npx clanker-wallet` / `bunx clanker-wallet`
 
+### Running in a sandbox
+
+If your commands run in a sandbox (e.g. Claude Code), the CLI needs:
+
+- **network:** a WebSocket to the relay, `wss://relay.clanker-wallet.xyz/ws` (the `relay` URL in the pairing JSON). Without it `tx` fails with exit code 3.
+- **the sandbox proxy:** if the sandbox only lets traffic out through `HTTPS_PROXY` (Claude Code does), Node ignores it unless you run the CLI as `NODE_USE_ENV_PROXY=1 clanker-wallet ...` (Node 24+). The exit-3 error says so when this applies.
+- **files:** `pair` writes your identity and the pairing to `~/.clanker-wallet/`, and the other commands write there too (they fix file permissions and create the identity if it is missing). Allow writes, not just reads.
+
+Ask the human to allow the host and the directory before you pair.
+
 ## Pairing (one-time)
 
 Before you can send transactions, check if you're already paired:
@@ -41,11 +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.
 
-This saves identity and 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
 
@@ -79,7 +93,7 @@ clanker-wallet tx \
 
 This sends 0.001 ETH (`1000000000000000` wei) on Base Sepolia (chain `84532`) to the burn address `0x000000000000000000000000000000000000dEaD`.
 
-The command **blocks until the human approves or rejects**, for up to 1 hour by default. Pass `--timeout <ms>` to wait a different time (`600000` = 10 minutes). Output is JSON:
+The command **blocks until the human approves or rejects**, for up to 1 hour by default. Pass `--timeout <ms>` to wait a different time (`600000` = 10 minutes). If your shell tool kills commands after a few minutes, run `tx` in the background and read its output when it exits. Output is JSON:
 - Approved: `{"tx_hash":"0x...","status":"approved"}` (exit code 0)
 - Rejected: `{"status":"rejected","error":"..."}` (exit code 1)
 - Timeout: `{"status":"timeout","error":"..."}` (exit code 2)
@@ -105,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 |
@@ -153,7 +182,9 @@ 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
@@ -163,7 +194,7 @@ clanker-wallet whoami
 ## 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 / connection error** — relay may be down, try again in a few seconds
+- **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,5 +1,5 @@
 #!/usr/bin/env node
-import { ClankerWallet, InvalidTxError, validateTx } from '../dist/index.js'
+import { ClankerWallet, InvalidTxError, validateTransfer, validateTx } from '../dist/index.js'
 import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from 'fs'
 import { join } from 'path'
 import { homedir } from 'os'
@@ -7,12 +7,21 @@ import { homedir } from 'os'
 // ── 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 +59,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 +128,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 +148,44 @@ 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
+}
 
+/** a ClankerWallet paired from a saved pairing */
+function pairedWallet(pairing) {
   const wallet = getWallet()
-  const pairingJson = JSON.stringify({
+  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 +203,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,
   })
 }
 
@@ -223,8 +318,9 @@ 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
 
 tx flags:
@@ -237,17 +333,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
-  4  not paired
+  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 (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
 
@@ -266,6 +374,9 @@ switch (cmd) {
   case 'tx':
     await cmdTx(flags)
     break
+  case 'send':
+    await cmdSend(flags)
+    break
   case 'status':
     cmdStatus()
     break

package/dist/bech32.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Bech32 / Bech32m decoding — a port of the BIP-173 / BIP-350 reference
+ * implementation (github.com/sipa/bech32 ref/python/segwit_addr.py).
+ * Used to check transfer recipients: bitcoin segwit addresses and chia
+ * puzzle-hash addresses (bech32m, hrp xch / txch).
+ */
+export type Bech32Encoding = 'bech32' | 'bech32m';
+/** validate a bech32/bech32m string; returns its hrp, data (checksum stripped) and encoding */
+export declare function bech32Decode(bech: string): {
+    hrp: string;
+    data: number[];
+    encoding: Bech32Encoding;
+} | null;
+/** general power-of-2 base conversion */
+export declare function convertBits(data: number[], fromBits: number, toBits: number, pad: boolean): number[] | null;
+/** decode a segwit address for the given hrp ('bc' mainnet, 'tb' testnet/signet) */
+export declare function decodeSegwitAddress(hrp: string, addr: string): {
+    version: number;
+    program: number[];
+} | null;
+/**
+ * a segwit address a wallet can pay today: v0 p2wpkh/p2wsh (20/32 bytes) or v1 p2tr (32 bytes).
+ * other versions and v1 lengths decode but are unspendable or anyone-can-spend, so transfers refuse them
+ */
+export declare function isStandardSegwitAddress(hrp: string, addr: string): boolean;
+/** decode a chia address (bech32m of a 32-byte puzzle hash) for the given hrp ('xch' / 'txch') */
+export declare function decodeChiaAddress(hrp: string, addr: string): number[] | null;

package/dist/bech32.js

@@ -0,0 +1,111 @@
+/**
+ * Bech32 / Bech32m decoding — a port of the BIP-173 / BIP-350 reference
+ * implementation (github.com/sipa/bech32 ref/python/segwit_addr.py).
+ * Used to check transfer recipients: bitcoin segwit addresses and chia
+ * puzzle-hash addresses (bech32m, hrp xch / txch).
+ */
+const CHARSET = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l';
+const BECH32M_CONST = 0x2bc830a3;
+const GENERATOR = [0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3];
+function polymod(values) {
+    let chk = 1;
+    for (const value of values) {
+        const top = chk >>> 25;
+        chk = (((chk & 0x1ffffff) << 5) ^ value) >>> 0;
+        for (let i = 0; i < 5; i++) {
+            if ((top >>> i) & 1)
+                chk = (chk ^ GENERATOR[i]) >>> 0;
+        }
+    }
+    return chk;
+}
+function hrpExpand(hrp) {
+    const codes = Array.from(hrp, (c) => c.charCodeAt(0));
+    return [...codes.map((c) => c >> 5), 0, ...codes.map((c) => c & 31)];
+}
+/** validate a bech32/bech32m string; returns its hrp, data (checksum stripped) and encoding */
+export function bech32Decode(bech) {
+    for (const c of bech) {
+        const code = c.charCodeAt(0);
+        if (code < 33 || code > 126)
+            return null;
+    }
+    if (bech.toLowerCase() !== bech && bech.toUpperCase() !== bech)
+        return null;
+    const lower = bech.toLowerCase();
+    const pos = lower.lastIndexOf('1');
+    if (pos < 1 || pos + 7 > lower.length || lower.length > 90)
+        return null;
+    const data = [];
+    for (const c of lower.slice(pos + 1)) {
+        const d = CHARSET.indexOf(c);
+        if (d === -1)
+            return null;
+        data.push(d);
+    }
+    const hrp = lower.slice(0, pos);
+    const check = polymod([...hrpExpand(hrp), ...data]);
+    const encoding = check === 1 ? 'bech32' : check === BECH32M_CONST ? 'bech32m' : null;
+    if (!encoding)
+        return null;
+    return { hrp, data: data.slice(0, -6), encoding };
+}
+/** general power-of-2 base conversion */
+export function convertBits(data, fromBits, toBits, pad) {
+    let acc = 0;
+    let bits = 0;
+    const ret = [];
+    const maxv = (1 << toBits) - 1;
+    const maxAcc = (1 << (fromBits + toBits - 1)) - 1;
+    for (const value of data) {
+        if (value < 0 || value >> fromBits)
+            return null;
+        acc = ((acc << fromBits) | value) & maxAcc;
+        bits += fromBits;
+        while (bits >= toBits) {
+            bits -= toBits;
+            ret.push((acc >> bits) & maxv);
+        }
+    }
+    if (pad) {
+        if (bits)
+            ret.push((acc << (toBits - bits)) & maxv);
+    }
+    else if (bits >= fromBits || ((acc << (toBits - bits)) & maxv)) {
+        return null;
+    }
+    return ret;
+}
+/** decode a segwit address for the given hrp ('bc' mainnet, 'tb' testnet/signet) */
+export function decodeSegwitAddress(hrp, addr) {
+    const decoded = bech32Decode(addr);
+    if (!decoded || decoded.hrp !== hrp || decoded.data.length === 0)
+        return null;
+    const [version, ...rest] = decoded.data;
+    const program = convertBits(rest, 5, 8, false);
+    if (!program || program.length < 2 || program.length > 40)
+        return null;
+    if (version > 16)
+        return null;
+    if (version === 0 && program.length !== 20 && program.length !== 32)
+        return null;
+    if ((version === 0) !== (decoded.encoding === 'bech32'))
+        return null;
+    return { version, program };
+}
+/**
+ * a segwit address a wallet can pay today: v0 p2wpkh/p2wsh (20/32 bytes) or v1 p2tr (32 bytes).
+ * other versions and v1 lengths decode but are unspendable or anyone-can-spend, so transfers refuse them
+ */
+export function isStandardSegwitAddress(hrp, addr) {
+    const decoded = decodeSegwitAddress(hrp, addr);
+    return !!decoded && (decoded.version === 0 || (decoded.version === 1 && decoded.program.length === 32));
+}
+/** decode a chia address (bech32m of a 32-byte puzzle hash) for the given hrp ('xch' / 'txch') */
+export function decodeChiaAddress(hrp, addr) {
+    const decoded = bech32Decode(addr);
+    if (!decoded || decoded.hrp !== hrp || decoded.encoding !== 'bech32m')
+        return null;
+    const puzzleHash = convertBits(decoded.data, 5, 8, false);
+    return puzzleHash && puzzleHash.length === 32 ? puzzleHash : null;
+}

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { TypedEmitter } from './events.js';
-import type { PairingData, RequestTxOptions } from './types.js';
+import type { PairingData, RequestTransferOptions, RequestTxOptions } from './types.js';
 export interface ClankerWalletOptions {
     /** agent display name (informational) */
     agentName?: string;
@@ -27,4 +27,13 @@ export declare class ClankerWallet extends TypedEmitter {
      * throws on rejection, timeout, or connection error.
      */
     requestTx(options: RequestTxOptions): Promise<string>;
+    /**
+     * send a bitcoin / chia transfer to the paired human and wait for their response.
+     * the family comes from the pairing; the human's wallet builds, signs and broadcasts
+     * the send. resolves with the txid on approval.
+     * throws InvalidTxError (before anything is sent), or on rejection, timeout, or connection error.
+     */
+    requestTransfer(options: RequestTransferOptions): Promise<string>;
+    /** encrypt a signed request to the paired human, send it through the relay, and wait for the answer */
+    private send;
 }

package/dist/client.js

@@ -1,7 +1,17 @@
 import { decryptMessage, encryptMessage, fromHex, generateKeypair, keypairFromSecret, signMessage, signingKeypairFromSeed, toHex } from './crypto.js';
 import { TypedEmitter } from './events.js';
-import { validateTx } from './validate.js';
+import { InvalidTxError, validateTransfer, validateTx } from './validate.js';
 const DEFAULT_TIMEOUT_MS = 3_600_000; // 1 hour
+const UNREACHABLE_HINT = 'if you run in a sandbox or behind a firewall, allow this host; otherwise the relay may be down or rate limiting, retry in a few seconds';
+/** node's WebSocket ignores HTTPS_PROXY unless NODE_USE_ENV_PROXY is set at startup, and sandboxes (claude code) only let traffic out through that proxy */
+function proxyHint() {
+    const env = globalThis.process?.env;
+    if (!env || env.NODE_USE_ENV_PROXY)
+        return '';
+    return env.HTTPS_PROXY || env.https_proxy || env.HTTP_PROXY || env.http_proxy
+        ? '; HTTPS_PROXY is set but node ignores it, rerun with NODE_USE_ENV_PROXY=1 (node 24+)'
+        : '';
+}
 export class ClankerWallet extends TypedEmitter {
     publicKey;
     secretKey;
@@ -45,6 +55,8 @@ export class ClankerWallet extends TypedEmitter {
             relayUrl: data.relay,
             humanWallet: data.wallet || null,
             mode: data.mode || 'encrypted',
+            chainFamily: data.chain_family || null,
+            chainNetwork: data.chain_network || null,
         };
         this.emit('paired', { relay: data.relay, wallet: data.wallet || '' });
         return data;
@@ -58,13 +70,16 @@ export class ClankerWallet extends TypedEmitter {
         if (!this.pairing) {
             throw new Error('not paired — call pair() first');
         }
+        // a bitcoin or chia pairing takes transfers only: its wallet can't sign an evm tx
+        const { chainFamily } = this.pairing;
+        if (chainFamily && chainFamily !== 'evm') {
+            throw new InvalidTxError('chain_family', `this pairing is for ${chainFamily}: use requestTransfer for bitcoin or chia`);
+        }
         // reject malformed requests before anything reaches the relay
         const { chain_id, transaction } = validateTx(options.chain_id, options.transaction);
-        const { humanPubkey, humanPubkeyHex, relayUrl, humanWallet, mode } = this.pairing;
-        const timeoutMs = options.timeout_ms ?? DEFAULT_TIMEOUT_MS;
-        const requestId = `req_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+        const { humanWallet, mode } = this.pairing;
         const txRequest = {
-            request_id: requestId,
+            request_id: newRequestId(),
             agent_id: this.agentId,
             timestamp: new Date().toISOString(),
             chain_id,
@@ -73,6 +88,46 @@ export class ClankerWallet extends TypedEmitter {
             signature: '', // set below after signing
         };
         txRequest.signature = signMessage(JSON.stringify(txRequest), this.signingSecretKey);
+        // managed mode: relay gets plaintext tx params so it can simulate
+        const simulate = mode === 'managed'
+            ? { from: humanWallet || '', to: transaction.to, value: transaction.value, data: transaction.data, chainId: chain_id }
+            : undefined;
+        return this.send(txRequest, options.timeout_ms ?? DEFAULT_TIMEOUT_MS, simulate);
+    }
+    /**
+     * send a bitcoin / chia transfer to the paired human and wait for their response.
+     * the family comes from the pairing; the human's wallet builds, signs and broadcasts
+     * the send. resolves with the txid on approval.
+     * throws InvalidTxError (before anything is sent), or on rejection, timeout, or connection error.
+     */
+    async requestTransfer(options) {
+        if (!this.pairing) {
+            throw new Error('not paired — call pair() first');
+        }
+        const { chainFamily, chainNetwork } = this.pairing;
+        // reject malformed requests before anything reaches the relay
+        const { chain_family, chain_network, transfer } = validateTransfer(chainFamily, options.chain_network, options.transfer);
+        if (chainNetwork && chainNetwork !== chain_network) {
+            throw new InvalidTxError('chain_network', `this pairing is for ${chain_family} ${chainNetwork}, got "${chain_network}"`);
+        }
+        const request = {
+            request_id: newRequestId(),
+            agent_id: this.agentId,
+            timestamp: new Date().toISOString(),
+            chain_family,
+            chain_network,
+            transfer,
+            context: options.context,
+            signature: '', // set below after signing
+        };
+        request.signature = signMessage(JSON.stringify(request), this.signingSecretKey);
+        // the relay simulator is evm-only: no simulate object for transfers, even on a managed pairing
+        return this.send(request, options.timeout_ms ?? DEFAULT_TIMEOUT_MS);
+    }
+    /** encrypt a signed request to the paired human, send it through the relay, and wait for the answer */
+    send(request, timeoutMs, simulate) {
+        const { humanPubkey, humanPubkeyHex, relayUrl } = this.pairing;
+        const requestId = request.request_id;
         return new Promise((resolve, reject) => {
             let ws;
             let timer;
@@ -103,8 +158,9 @@ export class ClankerWallet extends TypedEmitter {
                 return;
             }
             ws.addEventListener('error', () => {
+                // node's WebSocket error event carries no cause, so name the url: a sandbox or firewall blocking it looks the same as an outage
                 if (!settled)
-                    fail('relay connection error');
+                    fail(`relay connection error: could not reach ${relayUrl} (${UNREACHABLE_HINT}${proxyHint()})`);
             });
             ws.addEventListener('close', () => {
                 this.emit('disconnected', {});
@@ -128,7 +184,7 @@ export class ClankerWallet extends TypedEmitter {
                 }
                 if (msg.type === 'joined') {
                     this.emit('connected', { room: humanPubkeyHex });
-                    const ciphertext = encryptMessage(JSON.stringify(txRequest), humanPubkey, this.secretKey);
+                    const ciphertext = encryptMessage(JSON.stringify(request), humanPubkey, this.secretKey);
                     const envelope = {
                         sender_pubkey: this.agentPubkeyHex,
                         ciphertext,
@@ -139,16 +195,8 @@ export class ClankerWallet extends TypedEmitter {
                         room: humanPubkeyHex,
                         payload: JSON.stringify(envelope),
                     };
-                    // managed mode: relay gets plaintext tx params so it can simulate
-                    if (mode === 'managed') {
-                        wsMsg.simulate = {
-                            from: humanWallet || '',
-                            to: transaction.to,
-                            value: transaction.value,
-                            data: transaction.data,
-                            chainId: chain_id,
-                        };
-                    }
+                    if (simulate)
+                        wsMsg.simulate = simulate;
                     ws.send(JSON.stringify(wsMsg));
                     this.emit('request_sent', { request_id: requestId });
                     return;
@@ -196,3 +244,6 @@ export class ClankerWallet extends TypedEmitter {
         });
     }
 }
+function newRequestId() {
+    return `req_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+}

package/dist/index.d.ts

@@ -3,6 +3,6 @@ export type { ClankerWalletOptions } from './client.js';
 export { base64ToBytes, bytesToBase64, decryptMessage, encryptMessage, fromHex, generateKeypair, keypairFromSecret, signMessage, signingKeypairFromSeed, toHex, verifySignature } from './crypto.js';
 export { TypedEmitter } from './events.js';
 export type { EventMap } from './events.js';
-export { InvalidTxError, isChecksumAddress, validateTx } from './validate.js';
+export { InvalidTxError, isChecksumAddress, validateTransfer, validateTx } from './validate.js';
 export type { TxField } from './validate.js';
-export type { AgentEnvelope, PairingData, RequestTxOptions, Transaction, TxContext, TxInput, TxRequest, TxResponse, } from './types.js';
+export type { AgentEnvelope, PairingData, RequestTransferOptions, RequestTxOptions, Transaction, Transfer, TransferFamily, TransferInput, TransferRequest, TxContext, TxInput, TxRequest, TxResponse, } from './types.js';

package/dist/index.js

@@ -1,4 +1,4 @@
 export { ClankerWallet } from './client.js';
 export { base64ToBytes, bytesToBase64, decryptMessage, encryptMessage, fromHex, generateKeypair, keypairFromSecret, signMessage, signingKeypairFromSeed, toHex, verifySignature } from './crypto.js';
 export { TypedEmitter } from './events.js';
-export { InvalidTxError, isChecksumAddress, validateTx } from './validate.js';
+export { InvalidTxError, isChecksumAddress, validateTransfer, validateTx } from './validate.js';

package/dist/types.d.ts

@@ -48,6 +48,10 @@ export interface PairingData {
     wallet: string;
     /** "encrypted" (default): relay sees only ciphertext. "managed": relay also receives tx params for simulation. */
     mode?: 'encrypted' | 'managed';
+    /** "bitcoin" or "chia" for a non-evm wallet; absent for evm */
+    chain_family?: string;
+    /** the wallet's network, when the pairing names one */
+    chain_network?: string;
 }
 /** options for requestTx */
 export interface RequestTxOptions {
@@ -58,3 +62,43 @@ export interface RequestTxOptions {
     /** timeout in ms (default: 3_600_000 = 1hr) */
     timeout_ms?: number;
 }
+/** wallet families a transfer can go to */
+export type TransferFamily = 'bitcoin' | 'chia';
+/** an intent-level send: the human's wallet builds and signs it */
+export interface Transfer {
+    asset: 'btc' | 'xch';
+    /** bech32 / bech32m address on the request's network */
+    to: string;
+    /** integer string: sats for btc, mojos for xch */
+    amount: string;
+    /** chia only, in mojos (defaults to "0"); bitcoin wallets set their own fee */
+    fee?: string;
+}
+/** transfer as passed to requestTransfer: amounts as decimal strings or bigints */
+export interface TransferInput {
+    asset: 'btc' | 'xch';
+    to: string;
+    amount: string | bigint;
+    fee?: string | bigint;
+}
+/** bitcoin / chia request sent to the human: no chain_id, no transaction */
+export interface TransferRequest {
+    request_id: string;
+    agent_id: string;
+    timestamp: string;
+    chain_family: TransferFamily;
+    chain_network: string;
+    transfer: Transfer;
+    context?: TxContext;
+    signature: string;
+}
+/** options for requestTransfer; the family comes from the pairing */
+export interface RequestTransferOptions {
+    /** bitcoin: mainnet | testnet | signet; chia: mainnet | testnet11 */
+    chain_network: string;
+    /** checked before sending; an invalid field throws InvalidTxError */
+    transfer: TransferInput;
+    context?: TxContext;
+    /** timeout in ms (default: 3_600_000 = 1hr) */
+    timeout_ms?: number;
+}

package/dist/validate.d.ts

@@ -1,5 +1,5 @@
-import type { Transaction, TxInput } from './types.js';
-export type TxField = 'chain_id' | 'to' | 'value' | 'data';
+import type { Transaction, Transfer, TransferFamily, TransferInput, TxInput } from './types.js';
+export type TxField = 'chain_id' | 'to' | 'value' | 'data' | 'chain_family' | 'chain_network' | 'asset' | 'amount' | 'fee';
 /** a tx request field failed validation; nothing was sent */
 export declare class InvalidTxError extends Error {
     readonly field: TxField;
@@ -17,3 +17,14 @@ export declare function validateTx(chainId: unknown, tx: TxInput | Record<string
     chain_id: number;
     transaction: Transaction;
 };
+/**
+ * check a bitcoin / chia transfer before anything is signed or sent, and normalize it
+ * to the wire format (amounts as decimal strings, chia fee defaulting to "0").
+ * the recipient must decode as an address on `chainNetwork`. as strict as the web app,
+ * so a request it would refuse never leaves the agent. throws InvalidTxError.
+ */
+export declare function validateTransfer(chainFamily: unknown, chainNetwork: unknown, transfer: TransferInput | Record<string, unknown>): {
+    chain_family: TransferFamily;
+    chain_network: string;
+    transfer: Transfer;
+};

package/dist/validate.js

@@ -1,3 +1,4 @@
+import { decodeChiaAddress, isStandardSegwitAddress } from './bech32.js';
 import { keccak256 } from './keccak.js';
 /** a tx request field failed validation; nothing was sent */
 export class InvalidTxError extends Error {
@@ -63,3 +64,65 @@ export function validateTx(chainId, tx) {
     }
     return { chain_id: chainId, transaction: { to, value: wei, data } };
 }
+const TRANSFER_ASSET = { bitcoin: 'btc', chia: 'xch' };
+/** address hrp per network; the web app checks the same table */
+const ADDRESS_HRP = {
+    bitcoin: { mainnet: 'bc', testnet: 'tb', signet: 'tb' },
+    chia: { mainnet: 'xch', testnet11: 'txch' },
+};
+const NETWORK_NAMES = {
+    bitcoin: 'mainnet, testnet or signet',
+    chia: 'mainnet or testnet11',
+};
+const POSITIVE_INT_RE = /^[1-9][0-9]*$/;
+/** a decimal string or bigint amount as a decimal string, or null */
+function units(v, allowZero) {
+    if (typeof v === 'bigint')
+        return v > 0n || (allowZero && v === 0n) ? v.toString() : null;
+    if (typeof v !== 'string')
+        return null;
+    return POSITIVE_INT_RE.test(v) || (allowZero && v === '0') ? v : null;
+}
+/**
+ * check a bitcoin / chia transfer before anything is signed or sent, and normalize it
+ * to the wire format (amounts as decimal strings, chia fee defaulting to "0").
+ * the recipient must decode as an address on `chainNetwork`. as strict as the web app,
+ * so a request it would refuse never leaves the agent. throws InvalidTxError.
+ */
+export function validateTransfer(chainFamily, chainNetwork, transfer) {
+    if (chainFamily !== 'bitcoin' && chainFamily !== 'chia') {
+        throw new InvalidTxError('chain_family', `transfers need a bitcoin or chia pairing, got ${shown(chainFamily ?? 'evm')}`);
+    }
+    const family = chainFamily;
+    const hrp = typeof chainNetwork === 'string' ? ADDRESS_HRP[family][chainNetwork] : undefined;
+    if (!hrp)
+        throw new InvalidTxError('chain_network', `must be ${NETWORK_NAMES[family]}, got ${shown(chainNetwork)}`);
+    const network = chainNetwork;
+    const asset = TRANSFER_ASSET[family];
+    if (transfer.asset !== asset)
+        throw new InvalidTxError('asset', `${family} transfers must be ${shown(asset)}, got ${shown(transfer.asset)}`);
+    const unit = family === 'bitcoin' ? 'sats' : 'mojos';
+    const amount = units(transfer.amount, false);
+    if (!amount)
+        throw new InvalidTxError('amount', `must be a positive integer amount of ${unit} (decimal string or bigint), got ${shown(transfer.amount)}`);
+    const { to } = transfer;
+    if (family === 'bitcoin') {
+        if (transfer.fee !== undefined)
+            throw new InvalidTxError('fee', 'bitcoin transfers take no fee; the wallet sets it');
+        // the wallet api takes sats as a js number
+        if (BigInt(amount) > BigInt(Number.MAX_SAFE_INTEGER)) {
+            throw new InvalidTxError('amount', `must be at most ${Number.MAX_SAFE_INTEGER} sats, got ${shown(amount)}`);
+        }
+        if (typeof to !== 'string' || !isStandardSegwitAddress(hrp, to)) {
+            throw new InvalidTxError('to', `not a bitcoin ${network} address (segwit, ${hrp}1...), got ${shown(to)}`);
+        }
+        return { chain_family: family, chain_network: network, transfer: { asset, to, amount } };
+    }
+    const fee = transfer.fee === undefined ? '0' : units(transfer.fee, true);
+    if (!fee)
+        throw new InvalidTxError('fee', `must be a non-negative integer amount of mojos (decimal string or bigint), got ${shown(transfer.fee)}`);
+    if (typeof to !== 'string' || !decodeChiaAddress(hrp, to)) {
+        throw new InvalidTxError('to', `not a chia ${network} address (${hrp}1...), got ${shown(to)}`);
+    }
+    return { chain_family: family, chain_network: network, transfer: { asset, to, amount, fee } };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clanker-wallet",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",