@blackpool/cli 0.1.0 → 0.2.1

package/AGENTS.md

@@ -0,0 +1,393 @@
+# AGENTS.md — Blackpool for agents
+
+Private payments for AI agents and scripts. This file is the complete guide to using Blackpool through its CLI: setup, every command, the JSON each one returns, chains and limits, recipes, integration code, errors and safety rules. Start with the quickstart; everything after it is reference.
+
+| | |
+|---|---|
+| This file | https://blackpool.cash/AGENTS.md (plain markdown, no JavaScript, no bot challenge) |
+| Mirrors | https://raw.githubusercontent.com/blackpooldev/blackpool/main/AGENTS.md · inside the npm package at `node_modules/@blackpool/cli/AGENTS.md` |
+| Index for LLMs | https://blackpool.cash/llms.txt |
+| CLI | [`@blackpool/cli`](https://www.npmjs.com/package/@blackpool/cli) — Node.js 18+ |
+| API | `https://api.blackpool.cash` (the CLI calls it for you) |
+| Live status | https://blackpool.cash/status |
+| Human docs | https://blackpool.cash/docs |
+
+---
+
+## 1. Quickstart (60 seconds)
+
+```sh
+npm i -g @blackpool/cli                 # or prefix every command with: npx -y @blackpool/cli@latest
+export BLACKPOOL_KEY=0x<agent-wallet-private-key>   # a dedicated wallet, never your main one
+export BLACKPOOL_JSON=1                 # every command prints one JSON object on stdout
+
+blackpool address                       # → {"ok":true,"command":"address","address":"0x…"}  fund this address
+blackpool deposit 25 --pool usdc --chain base          # shield 25 USDC (the only step that needs gas)
+blackpool send 0xRECIPIENT 10 --pool usdc --chain base # private payment, relayer pays gas
+blackpool balance --chain base --pool usdc             # → {"ok":true,…,"balance":"13.965",…}
+```
+
+Paste this into your agent's instructions:
+
+```text
+You can make private crypto payments with the `blackpool` CLI (env BLACKPOOL_KEY and BLACKPOOL_JSON=1 are set).
+Always run commands with a timeout of at least 300 seconds and parse the single JSON object on stdout.
+"ok": true means it succeeded; "ok": false has an "error" to report. Exit code 2 means you called it wrong.
+Before paying, check `blackpool balance --chain <c> --pool <p>`; if it is short, `blackpool deposit` first.
+Never retry deposit, send, swap or bridge after a timeout or unclear failure: run `blackpool balance --wait`
+(or `blackpool bridges`) to see whether it landed. `blackpool recover --chain all` is always safe to run.
+Never print, log or share BLACKPOOL_KEY or anything in ~/.blackpool.
+Full guide: https://blackpool.cash/AGENTS.md
+```
+
+---
+
+## 2. How Blackpool works (what an agent needs to know)
+
+- **Public balance**: tokens in the agent wallet, visible to everyone.
+- **Private balance**: notes inside a Blackpool pool contract. Spending them reveals neither the agent wallet nor which deposit paid.
+- **Shield (`deposit`)**: moves public funds into the pool. Signed and paid (gas) by the agent wallet. This is the only on-chain action that shows your wallet.
+- **Private operations (`send`, `swap`, `bridge`)**: a zero-knowledge proof spends notes; the Blackpool relayer submits the transaction and pays gas. The fee is taken from the amount moved, so the agent needs no gas for these.
+- **Burner**: a one-time wallet used inside `swap` and `bridge`. Its key is encrypted locally and registered before it is funded, so `recover` can always sweep it.
+- **Account**: derived from one signature of the Blackpool sign-in message by the agent wallet. Same key → same private account on every chain and machine.
+- **Pools are per chain and per asset.** A private USDC balance on Base cannot pay on Arbitrum; use `bridge` to move between chains.
+
+---
+
+## 3. Setup
+
+### 3.1 Install
+
+```sh
+npm i -g @blackpool/cli        # global: `blackpool …`
+npx -y @blackpool/cli@latest …  # no install, always the newest version
+blackpool version --json        # {"ok":true,"command":"version","version":"0.2.0"}
+blackpool latest --json         # {"ok":true,"command":"latest","installed":"0.2.0","latest":"0.2.0","upToDate":true}
+```
+
+### 3.2 Configure
+
+| Variable | Required | Purpose |
+|---|---|---|
+| `BLACKPOOL_KEY` | yes (or run `blackpool login` once) | Agent wallet private key, 0x-prefixed hex. Used only locally. |
+| `BLACKPOOL_JSON` | recommended | `1` = JSON output for every command (same as adding `--json`). |
+| `BLACKPOOL_HOME` | no | Config/cache directory, default `~/.blackpool`. Set it when the home directory is read-only (containers, serverless). |
+| `BLACKPOOL_API` | no | API base URL, default `https://api.blackpool.cash`. |
+
+Without `BLACKPOOL_KEY`, `blackpool login` asks for the key with a hidden prompt and stores it at `~/.blackpool/wallet.json` (mode 600). Agents should prefer the environment variable.
+
+### 3.3 Fund
+
+```sh
+blackpool address --json
+```
+
+Send the agent wallet the asset you want to shield **plus a little native gas for the deposit** (a deposit uses about 1.3M gas; keep at least 0.0005 ETH on Robinhood Chain, Base or Arbitrum, or 0.002 BNB on BNB Chain). After shielding, private operations need no gas.
+
+### 3.4 Verify
+
+```sh
+blackpool balance --chain all --json
+```
+
+---
+
+## 4. Command reference
+
+Every command accepts `--json`. Amounts are plain decimals in token units (`10`, `0.25`), never wei. `--chain` defaults to `base`. Typical durations assume a healthy network.
+
+### `address`
+Print the agent wallet address.
+```json
+{"ok":true,"command":"address","address":"0x70997970C51812dc3A010C7d01b50e0d17dc79C8"}
+```
+
+### `balance [--chain C|all] [--pool P] [--wait]`
+Private and public balances. `--pool` limits the answer to one private pool. `--wait` polls up to 30 s while a private balance reads 0 (use right after a deposit). ~5–15 s.
+```json
+{"ok":true,"command":"balance","chain":"base","pool":"usdc","address":"0x…","balance":"13.965","symbol":"USDC","utxos":2}
+```
+Without `--pool` (one entry per chain; `--chain all` returns four):
+```json
+{"ok":true,"command":"balance","balances":[{"chain":"base","address":"0x…",
+  "private":{"ETH":{"balance":"0.0","utxos":0},"USDC":{"balance":"13.965","utxos":2}},
+  "public":{"ETH":"0.00412","USDC":"0.0"}}]}
+```
+A value of `"?"` with an `error` field means that read failed; retry.
+
+### `deposit <amount> [--pool P] [--chain C]`
+Shield public funds from the agent wallet. ERC-20 pools approve first (one extra transaction). Needs native gas. ~30–90 s.
+```json
+{"ok":true,"command":"deposit","chain":"base","pool":"usdc","amount":25,"symbol":"USDC",
+ "txHash":"0x…","explorer":"https://basescan.org/tx/0x…","privateBalance":"25.0"}
+```
+`--pool` defaults to the chain's stablecoin pool.
+
+### `send <recipient> <amount> [--pool P] [--chain C]`
+Private payment to any EVM address on the same chain. `amount` is what leaves your private balance; the recipient gets `amount − fee`. No gas needed. ~30–90 s.
+```json
+{"ok":true,"command":"send","chain":"base","pool":"usdc","recipient":"0x…","amount":10,
+ "received":"8.965","fee":"1.035","symbol":"USDC","txHash":"0x…","explorer":"https://basescan.org/tx/0x…"}
+```
+To make the recipient receive exactly `X`, send `(X + flat) / (1 − 0.0035)` rounded up (see §5).
+
+### `swap <amount> --from P [--chain C] [--slippage BPS]`
+Private same-chain swap between the chain's native pool and stablecoin pool; the output is re-shielded into your private balance. `--slippage` in basis points, default `100` (1%). No gas needed. ~1–3 min.
+```json
+{"ok":true,"command":"swap","chain":"base","from":"eth","amount":0.01,"received":"22.41",
+ "symbol":"USDC","txHash":"0x…","explorer":"https://basescan.org/tx/0x…","privateBalance":"36.375"}
+```
+If it fails half-way, funds sit on a registered burner: run `recover`.
+
+### `bridge <dest-asset> <recipient> <amount> --from ORIGIN [--no-wait]`
+Private cross-chain transfer through NEAR Intents. `ORIGIN` is the private pool paying (default `base_usdc`); `dest-asset` and recipient format are listed in §6. The withdrawal is private; the solver delivers on the destination chain. Without `--no-wait` the CLI polls up to 6 minutes.
+```json
+{"ok":true,"command":"bridge","from":"base_usdc","to":"sol_usdc","recipient":"7Gx4…kQ2m","amount":10,
+ "amountOutQuote":"8.91","withdrawTx":"0x…","depositAddress":"0x…","statusUrl":"https://…",
+ "status":"SUCCESS","amountOut":"8.93"}
+```
+`status` is `SUBMITTED` (with `--no-wait`), `SUCCESS`, or `PENDING` (still running after 6 min; check `bridges` later). A refund or failure returns `"ok":false`; refunds go to the agent wallet on the origin chain.
+
+### `bridges`
+Every bridge this account has made, newest first, from the server-side intent registry (works from any machine).
+```json
+{"ok":true,"command":"bridges","bridges":[{"status":"SUCCESS","createdAt":1793760000000,"amountIn":"10",
+ "fromAsset":"base_usdc","toAsset":"sol_usdc","recipient":"7Gx4…","refundTo":"0x…","originChain":"base",
+ "amountOutQuote":"8.91","amountOut":"8.93","destTx":"…","depositAddress":"0x…","statusUrl":"https://…"}]}
+```
+
+### `assets`
+Bridge destinations and valid origins, live from the API.
+```json
+{"ok":true,"command":"assets","assets":{"sol_usdc":{"chain":"sol","symbol":"USDC","decimals":6,"isNative":false},"…":{}},
+ "origins":["base_eth","base_usdc","hood_eth","hood_usdg","arb_eth","arb_usdc","bsc_bnb","bsc_usdc","bsc_usdt"]}
+```
+
+### `recover [--to ADDR] [--chain C|all]`
+Sweep every registered burner that still holds funds to the agent wallet (or `--to`). Idempotent and safe at any time. Swept funds land in the **public** wallet; `deposit` again to make them private. ~10–60 s per chain.
+```json
+{"ok":true,"command":"recover","recovered":[{"chain":"base","to":"0x…","swept":1,"dust":0,"errors":0}]}
+```
+
+### `login`, `logout`, `version`, `latest`, `help`
+`login` signs and caches the sign-in message (`{"address"}`); `logout` deletes the stored key and cache (`{"removed":[…]}`); `version` and `latest` report versions.
+
+---
+
+## 5. Chains, pools, fees and minimums
+
+| `--chain` | Pools (`--pool`) | Min deposit | Min send / swap / bridge | Flat fee | DEX for `swap` |
+|---|---|---|---|---|---|
+| `base` (default) | `eth`, `usdc` | 0.001 ETH · 3 USDC | 0.001 ETH · 2 USDC | 0.00015 ETH · 1 USDC | Uniswap V3 |
+| `robinhood` | `eth`, `usdg` | 0.001 ETH · 3 USDG | 0.001 ETH · 2 USDG | 0.00015 ETH · 0.5 USDG | Uniswap V3 |
+| `arbitrum` | `eth`, `usdc` | 0.001 ETH · 3 USDC | 0.001 ETH · 2 USDC | 0.00015 ETH · 0.5 USDC | Uniswap V3 |
+| `bsc` | `bnb`, `usdc`, `usdt` | 0.02 BNB · 3 USDC/USDT | 0.001 BNB · 2 USDC/USDT | 0.001 BNB · 0.5 USDC/USDT | PancakeSwap V3 |
+
+- **Fee** on every private spend = flat fee + 0.35% of the amount, deducted from the amount. Example: `send 10` USDC on Base → fee 1 + 0.035 = 1.035, recipient gets 8.965.
+- A spend must be more than twice its own fee; the CLI enforces the minimums above before doing anything.
+- Bridges pay the pool fee plus the solver's quote (shown as `amountOutQuote`); each route also has a solver minimum.
+- `deposit` costs only network gas; there is no Blackpool fee on shielding.
+
+---
+
+## 6. Bridging
+
+**Origins** (`--from`): `base_eth`, `base_usdc`, `hood_eth`, `hood_usdg` (Robinhood Chain), `arb_eth`, `arb_usdc`, `bsc_bnb`, `bsc_usdc`, `bsc_usdt`.
+
+**Destinations** (`dest-asset`; run `blackpool assets` for the live list):
+
+| Chain | Assets | Recipient format |
+|---|---|---|
+| Base | `base_eth`, `base_weth`, `base_usdc`, `base_cbbtc` | EVM `0x…` |
+| Ethereum | `eth_eth`, `eth_weth`, `eth_usdc`, `eth_usdt`, `eth_cbbtc` | EVM `0x…` |
+| Arbitrum | `arb_eth`, `arb_weth`, `arb_usdc`, `arb_usdt`, `arb_arb` | EVM `0x…` |
+| BNB Chain | `bsc_bnb`, `bsc_usdc`, `bsc_usdt` | EVM `0x…` |
+| Robinhood Chain | `hood_eth`, `hood_usdg`, `hood_weth`, `hood_usde` | EVM `0x…` |
+| Solana | `sol_sol`, `sol_usdc`, `sol_usdt` | base58 public key |
+
+**Statuses** in `bridges`: `PENDING_DEPOSIT` → `PROCESSING` → `SUCCESS`, or `REFUNDED` / `FAILED` (refund to `refundTo` on `originChain`). Treat any other value as in progress.
+
+---
+
+## 7. Recipes
+
+### Pay an invoice exactly
+```sh
+# recipient must receive 50 USDC on Base: amount = (50 + 1) / 0.9965 = 51.18 (round up)
+blackpool balance --chain base --pool usdc --json        # need >= 51.18
+blackpool send 0xVENDOR 51.18 --pool usdc --chain base --json
+```
+
+### Top up only when needed
+```sh
+bal=$(blackpool balance --chain base --pool usdc --json | jq -r .balance)
+if (( $(echo "$bal < 51.18" | bc -l) )); then blackpool deposit 100 --pool usdc --chain base --json; fi
+```
+
+### Batch payouts (sequential, never parallel)
+```sh
+while IFS=, read -r to amount; do
+  out=$(blackpool send "$to" "$amount" --pool usdc --chain base --json)
+  echo "$out" >> payouts.jsonl
+  [ "$(echo "$out" | jq -r .ok)" = "true" ] || { echo "stopped at $to"; break; }
+done < payouts.csv
+```
+Run payouts one at a time: each spend consumes notes and returns change, so parallel sends from one account can race.
+
+### Swap ETH to USDC privately
+```sh
+blackpool swap 0.01 --from eth --chain base --json
+```
+
+### Bridge to Solana without blocking
+```sh
+blackpool bridge sol_usdc <solana-address> 10 --from base_usdc --no-wait --json
+blackpool bridges --json | jq '.bridges[0].status'     # poll every minute until SUCCESS / REFUNDED
+```
+
+### Move private funds to another chain (rebalance)
+```sh
+blackpool bridge arb_usdc $(blackpool address --json | jq -r .address) 20 --from base_usdc --json
+blackpool deposit 19 --pool usdc --chain arbitrum --json   # re-shield on the destination chain
+```
+The bridge delivers to a public address; shield it again on the destination chain.
+
+### Health check before a run
+```sh
+curl -s https://api.blackpool.cash/api/health | jq '.ok, .relayerGas'
+```
+
+### Clean up after an interrupted swap or bridge
+```sh
+blackpool recover --chain all --json
+```
+
+---
+
+## 8. Integration code
+
+### Node.js
+```js
+import { execFile } from 'node:child_process'
+
+export function blackpool(args, { timeoutMs = 300_000 } = {}) {
+  return new Promise((resolve) => {
+    execFile('blackpool', [...args, '--json'], { timeout: timeoutMs, env: process.env }, (err, stdout, stderr) => {
+      try { resolve(JSON.parse(stdout.trim().split('\n').pop())) }
+      catch { resolve({ ok: false, error: (stderr || err?.message || 'no output').trim(), exitCode: err?.code }) }
+    })
+  })
+}
+
+const r = await blackpool(['send', '0xRECIPIENT', '10', '--pool', 'usdc', '--chain', 'base'])
+if (!r.ok) throw new Error(r.error)
+console.log(r.txHash, r.received)
+```
+
+### Python
+```python
+import json, subprocess
+
+def blackpool(*args, timeout=300):
+    p = subprocess.run(["blackpool", *args, "--json"], capture_output=True, text=True, timeout=timeout)
+    try:
+        return json.loads(p.stdout.strip().splitlines()[-1])
+    except (ValueError, IndexError):
+        return {"ok": False, "error": (p.stderr or "no output").strip(), "exitCode": p.returncode}
+
+r = blackpool("balance", "--chain", "base", "--pool", "usdc")
+print(r["balance"] if r["ok"] else r["error"])
+```
+
+### Tool definition for function-calling models
+Expose one tool and let the model choose the command:
+```json
+{
+  "name": "blackpool",
+  "description": "Private crypto payments via the Blackpool CLI. Commands: address; balance [--chain base|robinhood|arbitrum|bsc|all] [--pool P] [--wait]; deposit <amount> [--pool P] [--chain C]; send <recipient> <amount> [--pool P] [--chain C]; swap <amount> --from P [--chain C]; bridge <dest-asset> <recipient> <amount> --from ORIGIN [--no-wait]; bridges; assets; recover [--chain C|all]. Returns one JSON object; ok=false carries an error. Never retry deposit/send/swap/bridge without checking balance first.",
+  "input_schema": {
+    "type": "object",
+    "properties": {
+      "args": { "type": "array", "items": { "type": "string" }, "description": "CLI arguments, e.g. [\"send\",\"0xabc…\",\"10\",\"--pool\",\"usdc\",\"--chain\",\"base\"]" }
+    },
+    "required": ["args"]
+  }
+}
+```
+Implement it with the Node or Python wrapper above. Allow-list the first argument to the commands you want the agent to use (for example only `balance`, `send` and `bridges`).
+
+---
+
+## 9. Output contract
+
+- stdout: exactly one line of JSON when `--json` (or `BLACKPOOL_JSON=1`) is set. stderr: human progress, safe to log.
+- Envelope: `{"ok": true, "command": "<name>", …fields}` or `{"ok": false, "command": "<name>", "error": "<message>"}`.
+- Amounts are decimal strings in token units (some input echoes such as `amount` are numbers). Tx hashes are 0x-hex; `explorer` is a full URL.
+- Exit codes: `0` success · `1` failed or refused (including amounts under a minimum) · `2` usage (unknown command, missing arguments).
+- New fields may be added; existing fields are not renamed or removed without a major version bump.
+
+---
+
+## 10. Errors and what to do
+
+| `error` contains | Meaning | Do |
+|---|---|---|
+| `no wallet configured` | `BLACKPOOL_KEY` missing | Set it, or run `blackpool login`. |
+| `invalid BLACKPOOL_KEY` / `stored key invalid` | Not a 0x hex private key | Fix the key. |
+| `minimum deposit is …` / `minimum send is …` | Below the floor in §5 | Use a larger amount. |
+| `unknown pool` / `unknown chain` / `unknown --from` | Wrong flag value | Use the values in §5–6. |
+| `invalid recipient address` | Wrong format for the destination | EVM `0x…` (40 hex) or Solana base58. |
+| `insufficient` / `no unspent` | Private balance too low | `balance`, then `deposit` more. |
+| `Withdrawal must be more than twice the fee` | Amount too close to the fee | Larger amount. |
+| `Amount is too low for this route. Minimum is …` | Solver minimum for that bridge | Bridge at least that much. |
+| `rate limited, slow down` | API limit (40 relay ops, 600 reads per minute per IP) | The CLI already waited and retried 4 times; pause a minute. |
+| `simulation failed: …` | The relayer refused a transaction that would revert | Do not retry blindly; check `balance`; report the message. |
+| `reshield would revert` / `swap output … too small` | Swap stopped after funds reached the burner | `recover`, then `deposit` again. |
+| `solver refunded` / `bridge failed at solver` | Bridge did not complete | Refund goes to the agent wallet on the origin chain; `deposit` to re-shield. |
+| `timeout` / `fetch failed` / `HTTP 5xx` | Network or service problem | Check https://blackpool.cash/status; for write commands check `balance --wait` before retrying. |
+
+---
+
+## 11. Retries, timeouts, concurrency
+
+- Safe to retry any time: `address`, `balance`, `assets`, `bridges`, `recover`, `version`, `latest`.
+- **Not** safe to retry blindly: `deposit`, `send`, `swap`, `bridge`. A timeout can mean the transaction landed. Check `balance --wait` (or `bridges`) and only retry if the balance is unchanged.
+- Give every command a timeout of **at least 300 s** (`bridge` without `--no-wait` up to 420 s).
+- One write command at a time per account. Reads can run in parallel.
+- A private balance can read `0` for a few seconds after a deposit while the indexer catches up; use `--wait`.
+
+---
+
+## 12. Security
+
+- **Dedicated agent wallet.** Fund it with only what the agent may spend. Never use a personal or treasury key.
+- `BLACKPOOL_KEY` never leaves the machine: it signs the sign-in message, deposit approvals and deposit transactions locally.
+- The **sign-in signature** is cached in `$BLACKPOOL_HOME/config.json` (mode 600) and sent to the API with each private operation. The API derives the private account keys from it in memory to build the proof and does not store or log it, but anyone holding that signature can spend the agent's private balance. Treat the config directory like a key: never print it, never put it in prompts, logs or tool output.
+- Only sign the Blackpool sign-in message on blackpool.cash or with this CLI.
+- The contracts and circuits have not been externally audited; pools are upgradeable by an admin key during launch. Size balances accordingly. Details: https://blackpool.cash/docs#security
+- Report vulnerabilities privately to hello@blackpool.cash (subject `security`).
+
+---
+
+## 13. Direct API (advanced)
+
+The CLI is the supported interface. If you cannot run Node.js, the same operations are HTTP calls on `https://api.blackpool.cash` (`/api/balance`, `/api/deposit/prepare`, `/api/withdraw`, `/api/swap-private`, `/api/bridge/quote`, `/api/swap`, `/api/intents`, `/api/burner/*`, `/api/health`), all JSON. They need the sign-in signature (EIP-191 signature of the exact message below by the agent wallet), and deposits need you to sign and broadcast the returned transaction yourself. Endpoint list: https://blackpool.cash/docs#api
+
+```text
+Welcome to Blackpool
+
+Sign this message to access your private account.
+
+- Gas free: no transaction is sent
+- Your private account keys are derived from this signature
+- It cannot move funds from your wallet or approve spending
+- Only sign it on blackpool.cash or the Blackpool CLI
+```
+
+The message is part of the account: a different message, even by one character, is a different (empty) account.
+
+---
+
+## 14. Working on this repository
+
+If you are a coding agent editing this repository rather than using the CLI: the CLI lives in `cli/`, contracts in `contracts/`, circuits in `circuits/`, client libraries in `src/`, the web app in `frontend/`. Run `npx hardhat test` before changing contracts or core libraries. Keep the sign-in message, note format and circuit byte-identical across `src/`, `cli/` and `frontend/` (changing any of them changes every account). Never commit keys, `.env` files or credentials. Keep this file in sync with `cli/bin/blackpool.js` when commands or output fields change.

package/README.md

@@ -127,3 +127,7 @@ Run `blackpool assets` for the full live list. Currently: **Base, Ethereum, BSC,
 ## Support
 
 Docs: [docs.blackpool.cash/agents](https://docs.blackpool.cash/agents) · Site: [blackpool.cash](https://blackpool.cash)
+
+## Agents
+
+Run any command with `--json` (or `BLACKPOOL_JSON=1`) to get one JSON object on stdout and progress on stderr; exit codes are `0` ok, `1` failed, `2` usage. [`AGENTS.md`](AGENTS.md) (also at https://blackpool.cash/AGENTS.md) documents every command's fields, minimums, retry rules and security notes.

package/bin/blackpool.js

@@ -24,9 +24,9 @@ const SIGN_MESSAGE =
   'Welcome to Blackpool\n\n' +
   'Sign this message to access your private account.\n\n' +
   '- Gas free: no transaction is sent\n' +
-  '- Your keys are derived locally and never leave this device\n' +
-  '- This signature cannot move funds or approve spending'
-const CONFIG_DIR = path.join(os.homedir(), '.blackpool')
+  '- Your private account keys are derived from this signature\n' +
+  '- It cannot move funds from your wallet or approve spending\n- Only sign it on blackpool.cash or the Blackpool CLI'
+const CONFIG_DIR = process.env.BLACKPOOL_HOME || path.join(os.homedir(), '.blackpool')
 const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json')   // cached BLACKPOOL sig
 const WALLET_FILE = path.join(CONFIG_DIR, 'wallet.json')   // stored priv key (chmod 600)
 
@@ -36,11 +36,21 @@ const c = {
   red: '\x1b[31m', green: '\x1b[32m', yellow: '\x1b[33m',
   blue: '\x1b[34m', cyan: '\x1b[36m', lime: '\x1b[38;5;155m'
 }
+// --json (or BLACKPOOL_JSON=1): stdout carries exactly one JSON object, human progress goes to stderr.
+const JSON_MODE = process.argv.includes('--json') || process.env.BLACKPOOL_JSON === '1'
+const RESULT = {}
+let CMD = null
+function result(obj) { Object.assign(RESULT, obj) }
+function out(line) { if (JSON_MODE) process.stderr.write(line + '\n'); else console.log(line) }
 function color(text, col) {
-  return process.stdout.isTTY ? `${col}${text}${c.reset}` : text
+  return !JSON_MODE && process.stdout.isTTY ? `${col}${text}${c.reset}` : text
+}
+function ok(msg)   { out(color('✓ ', c.green) + msg) }
+function fail(msg, code = 1) {
+  if (JSON_MODE) process.stdout.write(JSON.stringify({ ok: false, command: CMD, error: String(msg) }) + '\n')
+  else console.error(color('✗ ', c.red) + msg)
+  process.exit(code)
 }
-function ok(msg)   { console.log(color('✓ ', c.green) + msg) }
-function fail(msg) { console.error(color('✗ ', c.red) + msg); process.exit(1) }
 // Extract a human revert reason from ethers' verbose errors (which otherwise dump the entire tx,
 // calldata, and JSON-RPC request body into .message — unreadable in a terminal).
 function cleanErr(e) {
@@ -59,8 +69,8 @@ function cleanErr(e) {
   const m = e.message || String(e)
   return m.split(/\s*[\(\[]\s*(?:See:|error=|reason=)/)[0].trim().slice(0, 200)
 }
-function info(msg) { console.log(color('  ', c.dim) + msg) }
-function log(msg)  { console.log(msg) }
+function info(msg) { out(color('  ', c.dim) + msg) }
+function log(msg)  { out(msg) }
 
 // === config ===
 function loadConfig() {
@@ -140,8 +150,11 @@ function getWallet() {
   }
 }
 
+// Cached signatures are only valid for the message they signed: a new sign-in message means a new account.
+const SIGN_MESSAGE_ID = ethers.utils.id(SIGN_MESSAGE)
 function getCachedSignature(address) {
   const cfg = loadConfig()
+  if (cfg.signMessageId !== SIGN_MESSAGE_ID) return undefined
   return cfg.signatures?.[address.toLowerCase()]
 }
 
@@ -153,6 +166,8 @@ async function ensureSignature(wallet, { forceNew = false } = {}) {
   }
   const sig = await wallet.signMessage(SIGN_MESSAGE)
   const cfg = loadConfig()
+  if (cfg.signMessageId !== SIGN_MESSAGE_ID) cfg.signatures = {}
+  cfg.signMessageId = SIGN_MESSAGE_ID
   cfg.signatures = cfg.signatures || {}
   cfg.signatures[address.toLowerCase()] = sig
   saveConfig(cfg)
@@ -160,7 +175,18 @@ async function ensureSignature(wallet, { forceNew = false } = {}) {
 }
 
 // === HTTP ===
-async function apiPost(endpoint, body, { timeoutMs = 90_000 } = {}) {
+async function apiPost(endpoint, body, opts = {}) {
+  for (let attempt = 0; ; attempt++) {
+    try { return await apiPostOnce(endpoint, body, opts) }
+    catch (e) {
+      if (e.status !== 429 || attempt >= 4) throw e
+      const wait = Math.min(Math.max(Number(e.retryAfter) || 5, 1), 30)
+      info(`rate limited by the API, retrying in ${wait}s...`)
+      await new Promise(r => setTimeout(r, wait * 1000))
+    }
+  }
+}
+async function apiPostOnce(endpoint, body, { timeoutMs = 90_000 } = {}) {
   const controller = new AbortController()
   const t = setTimeout(() => controller.abort(), timeoutMs)
   try {
@@ -174,7 +200,7 @@ async function apiPost(endpoint, body, { timeoutMs = 90_000 } = {}) {
     try { json = await r.json() } catch {}
     if (!r.ok) {
       const msg = json?.error || `HTTP ${r.status}`
-      throw new Error(msg)
+      throw Object.assign(new Error(msg), { status: r.status, retryAfter: json?.retryAfter })
     }
     return json
   } finally { clearTimeout(t) }
@@ -206,6 +232,13 @@ async function cmdLogin() {
   const sig = await ensureSignature(wallet, { forceNew: true })
   ok(`logged in as ${color(wallet.address, c.cyan)}`)
   info(`signature cached at ${CONFIG_FILE}`)
+  result({ address: wallet.address })
+}
+
+async function cmdAddress() {
+  const wallet = getWallet()
+  log(wallet.address)
+  result({ address: wallet.address })
 }
 
 async function cmdLogout() {
@@ -215,6 +248,7 @@ async function cmdLogout() {
   }
   if (removed.length) { removed.forEach(f => ok(`removed ${f}`)) }
   else info('nothing to remove (already logged out)')
+  result({ removed })
 }
 
 // === Multi-chain registry (mirrors frontend app/page.tsx: CHAIN_POOLS + UNISWAP + POOL_META) ===
@@ -513,6 +547,14 @@ async function showChainBalance(chain, wallet, sig, wait) {
   log(`    ${color(stableSym.padEnd(5), c.dim)} ${color(pub.usdc, c.cyan)}`)
   if (pub.err) info(`  (public balance unavailable: ${pub.err} — retry, or set BLACKPOOL_${chain.toUpperCase()}_RPC to a private RPC)`)
   log('')
+  ;(RESULT.balances ||= []).push({
+    chain, address: wallet.address,
+    private: {
+      [nativeSym]: { balance: ethPriv.balance, utxos: ethPriv.utxoCount, ...(ethPriv.err ? { error: ethPriv.err } : {}) },
+      [stableSym]: { balance: stablePriv.balance, utxos: stablePriv.utxoCount, ...(stablePriv.err ? { error: stablePriv.err } : {}) },
+    },
+    public: { [nativeSym]: pub.eth, [stableSym]: pub.usdc, ...(pub.err ? { error: pub.err } : {}) },
+  })
 }
 
 async function cmdBalance(args) {
@@ -554,6 +596,7 @@ async function cmdBalance(args) {
     log(`  ${color('private balance', c.dim)}  ${color(res.balance, c.lime)} ${color(res.symbol, c.cyan)} ${color(`on ${C.label}`, c.dim)}`)
     log(`  ${color('utxos', c.dim)}            ${res.utxoCount}`)
     log('')
+    result({ chain, pool, address: wallet.address, balance: res.balance, symbol: res.symbol, utxos: res.utxoCount })
     return
   }
 
@@ -569,7 +612,7 @@ async function cmdDeposit(args) {
   const amount = args[0]
   const validPools = poolsForChain(chain)
   const pool = getFlag(args, '--pool') || C.stablePool
-  if (!amount || amount.startsWith('--')) fail(`usage: blackpool deposit <amount> [--pool ${validPools.join('|')}] [--chain ${CHAIN_LIST}]`)
+  if (!amount || amount.startsWith('--')) fail(`usage: blackpool deposit <amount> [--pool ${validPools.join('|')}] [--chain ${CHAIN_LIST}]`, 2)
   const n = Number(amount)
   if (isNaN(n) || n <= 0) fail(`invalid amount: ${amount}`)
   if (!validPools.includes(pool)) fail(`unknown pool "${pool}" on ${C.label} (supported: ${validPools.join(', ')})`)
@@ -642,6 +685,7 @@ async function cmdDeposit(args) {
   info(`new private balance: ${prep.newBalance} ${prep.symbol}`)
   info(`tx: ${explorerTx(chain, dep.hash)}`)
   log('')
+  result({ chain, pool, amount: n, symbol: prep.symbol, txHash: dep.hash, explorer: explorerTx(chain, dep.hash), privateBalance: prep.newBalance })
 }
 
 // === Uniswap V3 constants on Base (extracted from frontend bundle - do not change) ===
@@ -787,7 +831,7 @@ async function cmdBridge(args) {
   const recipient = args[1]
   const amount = args[2]
   if (!toAsset || toAsset.startsWith('--') || !recipient || !amount) {
-    fail(`usage: blackpool bridge <dest-asset> <recipient> <amount> [--from <origin>] [--chain ...]\n  origins: ${Object.keys(BRIDGE_ORIGINS).join('|')} (default base_usdc)\n  run 'blackpool assets' for destinations`)
+    fail(`usage: blackpool bridge <dest-asset> <recipient> <amount> [--from <origin>] [--chain ...]\n  origins: ${Object.keys(BRIDGE_ORIGINS).join('|')} (default base_usdc)\n  run 'blackpool assets' for destinations`, 2)
   }
   const fromAsset = getFlag(args, '--from') || 'base_usdc'
   // Recipient format follows the destination: Solana = base58 pubkey, everything else EVM 0x…
@@ -837,21 +881,23 @@ async function cmdBridge(args) {
   info(`withdraw tx: ${explorerTx(origin.chain, res.txHash)}`)
   info(`tracking: ${res.statusUrl}`)
   log('')
+  result({ from: fromAsset, to: toAsset, recipient, amount: n, amountOutQuote: res.amountOut, withdrawTx: res.txHash, depositAddress: res.depositAddress || null, statusUrl: res.statusUrl, status: 'SUBMITTED' })
 
-  if (res.depositAddress) {
+  if (res.depositAddress && !args.includes('--no-wait')) {
     info('polling solver status (Ctrl+C to stop; bridge continues regardless)...')
     const start = Date.now()
     while (Date.now() - start < 360_000) {
       await new Promise(r => setTimeout(r, 8000))
       try {
         const st = await apiGet(`/api/intent-status?depositAddress=${res.depositAddress}`)
-        if (st.status === 'SUCCESS') { ok(color(`delivered ${st.amountOut || res.amountOut} to recipient`, c.green)); log(''); return }
+        if (st.status === 'SUCCESS') { ok(color(`delivered ${st.amountOut || res.amountOut} to recipient`, c.green)); log(''); result({ status: 'SUCCESS', amountOut: st.amountOut || res.amountOut }); return }
         if (st.status === 'REFUNDED') { fail(`solver refunded (${st.refundReason || 'route unavailable'}). Funds auto-return to your wallet.`) }
         if (st.status === 'FAILED') { fail('bridge failed at solver. Funds auto-refund.') }
         info(`status: ${st.status}...`)
       } catch (e) { info(`status check: ${e.message}`) }
     }
     info('still processing after 6 min - check the tracking URL above.')
+    result({ status: 'PENDING' })
   }
   log('')
 }
@@ -962,6 +1008,7 @@ async function recoverOneChain(chain, wallet, sig, dest) {
   if (dust > 0) info(`(${dust} burner(s) hold only dust ETH below gas cost — not recoverable, safe to ignore)`)
   if (errors > 0) info(`${errors} burner(s) had errors — re-run recover to retry`)
   log('')
+  ;(RESULT.recovered ||= []).push({ chain, to: dest, swept, dust, errors })
   return { swept, dust, errors }
 }
 
@@ -993,7 +1040,7 @@ async function cmdSwap(args) {
   const stablePool = C.stablePool // 'usdc' on base, 'usdg' on robinhood, 'usdt' on bsc
   const nativePool = C.nativePool // 'eth' everywhere except bsc, where it's 'bnb'
   const validFrom = [nativePool, stablePool]
-  if (!amount || amount.startsWith('--') || !from) fail(`usage: blackpool swap <amount> --from ${validFrom.join('|')} [--chain ${CHAIN_LIST}] [--slippage 100]`)
+  if (!amount || amount.startsWith('--') || !from) fail(`usage: blackpool swap <amount> --from ${validFrom.join('|')} [--chain ${CHAIN_LIST}] [--slippage 100]`, 2)
   if (!validFrom.includes(from)) fail(`--from must be ${validFrom.join(' or ')} on ${C.label}`)
   const n = Number(amount)
   if (isNaN(n) || n <= 0) fail(`invalid amount: ${amount}`)
@@ -1198,15 +1245,17 @@ async function cmdSwap(args) {
   info(`new private balance: ${prep.newBalance} ${prep.symbol}`)
   info(`reshield tx: ${explorerTx(chain, rtx.hash)}`)
   log('')
+  result({ chain, from, amount: n, received: reshieldFmt, symbol: toSym, txHash: rtx.hash, explorer: explorerTx(chain, rtx.hash), privateBalance: prep.newBalance })
 }
 
 // blackpool bridges — list this wallet's NEAR Intents bridges (server-side intent registry, any device).
 async function cmdBridges() {
   const wallet = getWallet()
-  const sig = await getSig(wallet)
+  const sig = await ensureSignature(wallet)
   const authSig = await registryAuthSig(sig)
   const res = await apiPost('/api/intents', { authSig }, { timeoutMs: 60_000 })
   const list = res.intents || []
+  result({ bridges: list })
   if (!list.length) { log(color('  no bridges recorded for this wallet', c.dim)); return }
   log('')
   for (const it of list) {
@@ -1226,6 +1275,7 @@ async function cmdBridges() {
 async function cmdAssets() {
   info('fetching supported assets...')
   const res = await apiGet('/api/assets')
+  result({ assets: res.assets || {}, origins: Object.keys(BRIDGE_ORIGINS) })
   log('')
   log(color('  bridge destination assets:', c.bold))
   const byChain = {}
@@ -1251,7 +1301,7 @@ async function cmdSend(args) {
   const amount = args[1]
   const validPools = poolsForChain(chain)
   const pool = getFlag(args, '--pool') || C.stablePool
-  if (!recipient || !amount) fail(`usage: blackpool send <recipient> <amount> [--pool ${validPools.join('|')}] [--chain ${CHAIN_LIST}]`)
+  if (!recipient || !amount) fail(`usage: blackpool send <recipient> <amount> [--pool ${validPools.join('|')}] [--chain ${CHAIN_LIST}]`, 2)
   if (!/^0x[a-fA-F0-9]{40}$/.test(recipient)) fail(`invalid recipient address: ${recipient}`)
   const n = Number(amount)
   if (isNaN(n) || n <= 0) fail(`invalid amount: ${amount}`)
@@ -1277,6 +1327,7 @@ async function cmdSend(args) {
   info(`fee: ${res.fee} ${res.symbol}`)
   info(`tx:  ${explorerTx(chain, res.txHash)}`)
   log('')
+  result({ chain, pool, recipient, amount: n, received: res.recipientReceives, fee: res.fee, symbol: res.symbol, txHash: res.txHash, explorer: explorerTx(chain, res.txHash) })
 }
 
 function getFlag(args, name) {
@@ -1295,13 +1346,14 @@ ${color('Usage:', c.bold)}
 
 ${color('Commands:', c.bold)}
   login                          Store key (hidden prompt) + sign BLACKPOOL message.
+  address                        Print the wallet address (fund this to shield).
   logout                         Remove stored key and cached signature.
   balance [--pool] [--chain]     Show private + public balances (or one pool).
                                  --chain all shows every chain in one run.
   deposit <amount> [--pool] [--chain]   Shield public funds into private pool.
   send <to> <amount> [--pool] [--chain] Send privately to an address (no gas from you).
   swap <amount> --from <pool> [--chain] Private same-chain swap via Uniswap V3.
-  bridge <asset> <to> <amount>   Bridge cross-chain privately via NEAR Intents
+  bridge <asset> <to> <amount>   Bridge cross-chain privately via NEAR Intents (--no-wait: return once submitted)
                                  (--from ${Object.keys(BRIDGE_ORIGINS).join('|')}).
                                  Run 'blackpool assets' for the destination list.
   assets                         List supported bridge destination assets.
@@ -1318,13 +1370,20 @@ ${Object.entries(CHAINS).map(([k, v]) => `  --chain ${k.padEnd(10)} ${k === 'bas
 ${color('Environment (optional, for agents/CI):', c.bold)}
   BLACKPOOL_KEY   Agent private key (0x-hex). If set, skips interactive login.
   BLACKPOOL_API   API base URL (default: ${API}).
+  BLACKPOOL_HOME  Config directory (default: ~/.blackpool).
+  BLACKPOOL_JSON  Set to 1 for JSON output (same as --json).
+
+${color('Output:', c.bold)}
+  --json          One JSON object on stdout: {"ok":true,"command":...,...} or {"ok":false,"error":...}.
+                  Progress goes to stderr. Exit codes: 0 ok, 1 error, 2 usage.
 
 ${color('Config:', c.bold)}
   ~/.blackpool/wallet.json       Stored private key (chmod 600).
   ~/.blackpool/config.json       Cached signatures per wallet (chmod 600).
 
 ${color('Docs:', c.bold)}
-  https://docs.blackpool.cash/agents
+  https://blackpool.cash/docs#agents
+  https://blackpool.cash/AGENTS.md
 `)
 }
 
@@ -1336,6 +1395,7 @@ async function cmdLatest() {
     const r = await fetch('https://registry.npmjs.org/@blackpool/cli/latest', { headers: { 'Accept': 'application/json' } })
     if (!r.ok) fail(`npm registry error (HTTP ${r.status})`)
     const remote = (await r.json()).version
+    result({ installed: local, latest: remote, upToDate: local === remote })
     log('')
     log(`  ${color('installed', c.dim)}  ${color('v' + local, c.cyan)}`)
     log(`  ${color('latest   ', c.dim)}  ${color('v' + remote, c.lime)}`)
@@ -1351,11 +1411,13 @@ async function cmdLatest() {
 
 // === entrypoint ===
 async function main() {
-  const [cmd, ...args] = process.argv.slice(2)
+  const [cmd, ...args] = process.argv.slice(2).filter(a => a !== '--json')
+  CMD = cmd || 'help'
   try {
     switch (cmd) {
       case 'login':   await cmdLogin();          break
       case 'logout':  await cmdLogout();         break
+      case 'address': await cmdAddress();        break
       case 'balance': await cmdBalance(args);    break
       case 'deposit': await cmdDeposit(args);    break
       case 'send':    await cmdSend(args);       break
@@ -1369,6 +1431,7 @@ async function main() {
       case '--version': {
         const pkg = require('../package.json')
         log(pkg.version)
+        result({ version: pkg.version })
         break
       }
       case 'latest':
@@ -1377,8 +1440,9 @@ async function main() {
       case '-h':
       case '--help':
       case undefined: help();                    break
-      default: log(`unknown command: ${cmd}\n`); help(); process.exit(2)
+      default: if (!JSON_MODE) { log(`unknown command: ${cmd}\n`); help() } fail(`unknown command: ${cmd} (run blackpool help)`, 2)
     }
+    if (JSON_MODE) process.stdout.write(JSON.stringify({ ok: true, command: CMD, ...RESULT }) + '\n')
   } catch (e) {
     fail(cleanErr(e))
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackpool/cli",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Private payments for onchain agents. CLI for BLACKPOOL - shield, send, swap, bridge with zero-knowledge privacy on Base, Robinhood Chain, Arbitrum, and BNB Smart Chain.",
   "bin": {
     "blackpool": "bin/blackpool.js"
@@ -11,7 +11,8 @@
   },
   "files": [
     "bin/",
-    "README.md"
+    "README.md",
+    "AGENTS.md"
   ],
   "dependencies": {
     "ethers": "^5.7.2"