@blackpool/cli 0.1.0 → 0.2.0

package/AGENTS.md

@@ -0,0 +1,130 @@
+# AGENTS.md — Blackpool for agents
+
+This file tells an AI agent (or a script) how to make private payments with Blackpool through the CLI: install it, give it a wallet, read its JSON output, and handle failures safely. Humans can read it too.
+
+- Web: https://blackpool.cash · Docs: https://blackpool.cash/docs#agents · This file: https://blackpool.cash/AGENTS.md
+- Package: [`@blackpool/cli`](https://www.npmjs.com/package/@blackpool/cli) (Node.js 18+)
+- API: `https://api.blackpool.cash` (the CLI talks to it for you)
+
+## What you can do
+
+Shield funds into a zero-knowledge pool, then pay, swap or bridge them with no on-chain link back to your wallet. The relayer pays gas for every private operation, so the agent only needs gas for the initial shield.
+
+| Command | What it does |
+|---|---|
+| `blackpool address` | Print the agent wallet address (fund this). |
+| `blackpool balance [--chain C] [--pool P] [--wait]` | Private and public balances. `--chain all` covers every chain. |
+| `blackpool deposit <amount> [--pool P] [--chain C]` | Shield public funds from the agent wallet into the pool (the agent pays this gas). |
+| `blackpool send <to> <amount> [--pool P] [--chain C]` | Private payment to any address. No gas needed. |
+| `blackpool swap <amount> --from P [--chain C] [--slippage BPS]` | Private same-chain swap (native ⇄ stablecoin), output re-shielded. |
+| `blackpool bridge <dest-asset> <recipient> <amount> --from ORIGIN [--no-wait]` | Private cross-chain transfer via NEAR Intents. |
+| `blackpool assets` | Bridge destination assets and valid `--from` origins. |
+| `blackpool bridges` | Your bridges with status, and where a refund went. |
+| `blackpool recover [--to ADDR] [--chain C]` | Sweep anything stranded on one-time burner wallets. Idempotent. |
+| `blackpool login` / `logout` / `version` / `latest` / `help` | Housekeeping. |
+
+## Chains, pools and minimums
+
+| `--chain` | Pools (`--pool`) | Minimum shield | Minimum send / swap / bridge |
+|---|---|---|---|
+| `base` (default) | `eth`, `usdc` | 0.001 ETH · 3 USDC | 0.001 ETH · 2 USDC |
+| `robinhood` | `eth`, `usdg` | 0.001 ETH · 3 USDG | 0.001 ETH · 2 USDG |
+| `arbitrum` | `eth`, `usdc` | 0.001 ETH · 3 USDC | 0.001 ETH · 2 USDC |
+| `bsc` | `bnb`, `usdc`, `usdt` | 0.02 BNB · 3 USDC/USDT | 0.001 BNB · 2 USDC/USDT |
+
+When `--pool` is omitted, `deposit` and `send` use the chain's stablecoin pool. Fees: a flat fee (0.00015 ETH, 0.001 BNB, 1 USDC on Base, 0.5 on the other stablecoin pools) plus 0.35%, taken inside the proof from the amount you move. A spend must be more than twice its own fee. Bridge origins for `--from`: `base_eth`, `base_usdc`, `hood_eth`, `hood_usdg`, `arb_eth`, `arb_usdc`, `bsc_bnb`, `bsc_usdc`, `bsc_usdt`.
+
+## Setup
+
+```sh
+npm i -g @blackpool/cli          # or prefix every command with: npx -y @blackpool/cli
+export BLACKPOOL_KEY=0x...       # private key of a DEDICATED agent wallet (see Security)
+export BLACKPOOL_JSON=1          # machine-readable output (same as --json on every command)
+blackpool address                # fund this address with gas + the asset to shield
+```
+
+`BLACKPOOL_KEY` replaces the interactive `blackpool login`. The first command that needs your private account signs the Blackpool sign-in message with that key and caches the signature in `~/.blackpool/config.json` (mode 600). Set `BLACKPOOL_HOME` to keep that cache somewhere else, for example a writable directory inside a sandbox.
+
+| Variable | Purpose |
+|---|---|
+| `BLACKPOOL_KEY` | Agent wallet private key (0x-hex). Never sent anywhere. |
+| `BLACKPOOL_JSON` | `1` = JSON output for every command. |
+| `BLACKPOOL_HOME` | Config directory (default `~/.blackpool`). |
+| `BLACKPOOL_API` | API base URL (default `https://api.blackpool.cash`). |
+
+## JSON output
+
+With `--json` (or `BLACKPOOL_JSON=1`) stdout carries exactly one JSON object and nothing else; progress messages go to stderr. Parse stdout, log stderr if you want.
+
+```sh
+$ blackpool send 0x9f3c...41e7 5 --pool usdc --chain base --json
+{"ok":true,"command":"send","chain":"base","pool":"usdc","recipient":"0x9f3c...41e7","amount":5,
+ "received":"3.9825","fee":"1.0175","symbol":"USDC","txHash":"0x...","explorer":"https://basescan.org/tx/0x..."}
+
+$ blackpool send 0x9f3c...41e7 0.5 --json
+{"ok":false,"command":"send","error":"minimum send is 2 USDC on Base — smaller amounts are mostly consumed by the withdraw fee (flat + 0.35%)"}
+```
+
+| Command | Fields on success |
+|---|---|
+| `address`, `login` | `address` |
+| `balance` | `balances[]`: `{chain, address, private: {SYM: {balance, utxos}}, public: {SYM: amount}}`; with `--pool`: `{chain, pool, balance, symbol, utxos}` |
+| `deposit` | `chain, pool, amount, symbol, txHash, explorer, privateBalance` |
+| `send` | `chain, pool, recipient, amount, received, fee, symbol, txHash, explorer` |
+| `swap` | `chain, from, amount, received, symbol, txHash, explorer, privateBalance` |
+| `bridge` | `from, to, recipient, amount, amountOutQuote, withdrawTx, depositAddress, statusUrl, status` (`SUBMITTED`, `SUCCESS` or `PENDING`) |
+| `bridges` | `bridges[]` with `status`, `amountIn`, `fromAsset`, `toAsset`, `recipient`, `refundTo`, `statusUrl` |
+| `assets` | `assets{}`, `origins[]` |
+| `recover` | `recovered[]`: `{chain, to, swept, dust, errors}` |
+
+Balances and amounts are decimal strings in token units, never wei.
+
+**Exit codes:** `0` success · `1` the operation failed or was refused (including amounts under a minimum) · `2` usage error (unknown command or missing arguments). On `1` and `2` the JSON has `"ok": false` and an `error` message written for a human.
+
+## Recipes
+
+Pay someone privately (first time on a chain):
+
+```sh
+blackpool deposit 25 --pool usdc --chain base --json     # shield once
+blackpool send 0xRECIPIENT 10 --pool usdc --chain base --json
+```
+
+Check before paying:
+
+```sh
+blackpool balance --chain base --pool usdc --json        # .balance must cover amount
+```
+
+Bridge to Solana and return as soon as the solver has the funds:
+
+```sh
+blackpool bridge sol_usdc <solana-address> 10 --from base_usdc --no-wait --json
+blackpool bridges --json                                 # poll status later
+```
+
+After any swap or bridge that failed half-way:
+
+```sh
+blackpool recover --chain all --json                     # safe to run any time
+```
+
+## Failure handling
+
+- **Read-only commands** (`address`, `balance`, `assets`, `bridges`, `version`) are safe to retry.
+- **`recover` is idempotent**: run it again whenever a swap or bridge did not finish.
+- **Do not blindly retry `deposit`, `send`, `swap` or `bridge`.** A timeout can mean the transaction landed. Check `balance --wait` (or `bridges`) first, then decide.
+- A balance that reads `0` right after a deposit is usually the indexer catching up: use `balance --wait`.
+- `rate limited, slow down`: the API allows 40 relay operations and 600 reads per minute per IP. The CLI waits for the `retryAfter` the API sends and retries up to four times; space out bulk payments.
+- Proof generation takes about 30–90 seconds per private operation. Use a command timeout of at least 3 minutes (bridges without `--no-wait` can poll up to 6 minutes).
+
+## Security
+
+- **Use a dedicated agent wallet** holding only what the agent should spend. Never give an agent your main wallet key.
+- `BLACKPOOL_KEY` stays on the machine. It is used to sign the sign-in message and the deposit transaction locally; it is never sent to the API.
+- The sign-in signature **is** sent to the API with each private operation: the API derives your private account keys from it in memory to build the proof, and does not store or log it. Anyone holding that signature can spend the agent's private balance, so protect `~/.blackpool/config.json` like a key, and never paste the signature into prompts, logs or tool output.
+- Pools and circuits have not been externally audited yet. Keep balances proportional to that risk. Details: https://blackpool.cash/docs#security
+
+## 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/`, 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), and never commit keys, `.env` files or credentials.

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.0",
   "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"