zoa-wallet 0.3.4 → 0.3.6

package/README.md

@@ -24,148 +24,545 @@ yarn global add zoa-wallet
 
 ```bash
 # Create a new wallet
-zoa init
+zoa wallet create --password mypassword
 
 # Check balances across all chains
-zoa balance
+zoa balance --password mypassword
+
+# Send ETH on Base
+zoa send --chain base --to 0x1234...abcd --amount 0.01 --password mypassword --yes
 
 # Show receive addresses with QR codes
-zoa receive
+zoa receive --password mypassword
 
 # View supported networks
 zoa chains
 
 # Check live token prices
 zoa prices
+
+# Link wallet to Agenteur (or other apps)
+zoa link agenteur --api-key <YOUR_API_KEY>
+```
+
+## Command Reference
+
+### `wallet` — Manage Wallets
+
+```bash
+# Create a new wallet
+zoa wallet create [--label <name>] [--color <hex>] [--password <pw>] [--word-count 12|24]
+
+# Import from recovery phrase
+zoa wallet import [--label <name>] [--mnemonic "phrase ..."] [--password <pw>]
+
+# List all wallets
+zoa wallet list [--password <pw>]
+
+# Switch active wallet
+zoa wallet switch [id-or-label]
+
+# Rename a wallet
+zoa wallet rename <id> <new-label>
+
+# Change wallet color
+zoa wallet color <id> <hex>
+
+# Remove a wallet
+zoa wallet remove <id> [--yes]
+
+# Show active wallet details
+zoa wallet info [--password <pw>]
 ```
 
-## Commands
+### `balance` — Check Balances
+
+```bash
+zoa balance [--password <pw>] [--chain <chain>]
+```
 
-| Command | Description |
-|---------|-------------|
-| `zoa init` | Create a new wallet or import from recovery phrase |
-| `zoa balance` | Check balances across all supported networks |
-| `zoa send` | Send tokens to an address |
-| `zoa receive` | Show wallet addresses with QR codes |
-| `zoa history` | View transaction history |
-| `zoa export` | Export private keys or recovery phrase |
-| `zoa chains` | List all supported blockchain networks |
-| `zoa prices` | View live token prices |
-| `zoa config` | Manage configuration (~/.zoa/config.json) |
-| `zoa api` | Manage API keys for programmatic access |
+| Flag | Description |
+|------|-------------|
+| `--password <pw>` | Wallet password (skip prompt) |
+| `--chain <chain>` | Filter to a specific chain (`base`, `ethereum`, `solana`, etc.) |
 
-## JSON Mode (for Scripts & AI Agents)
+### `send` — Send Tokens
 
-Every command supports `--json` for machine-readable output:
+Interactive:
+```bash
+zoa send
+```
 
+One-liner:
 ```bash
-# Create wallet non-interactively
-zoa --json init --mnemonic "your twelve word phrase here ..." --password "securepass"
+zoa send --chain base --to 0x... --amount 0.01 --password pw --yes
+```
 
-# Get balances as JSON
-zoa --json balance --password "securepass"
+| Flag | Description |
+|------|-------------|
+| `--password <pw>` | Wallet password |
+| `--to <address>` | Recipient address |
+| `--amount <amount>` | Amount to send |
+| `--chain <chain>` | Network (`base`, `ethereum`, `arbitrum`, `optimism`, `bsc`, `solana`) |
+| `--token <symbol>` | Token symbol (e.g. `USDT`, `USDC`). Defaults to native currency |
+| `--max` | Send maximum available balance (auto-deducts gas for native transfers) |
+| `--batch <transfers>` | Batch send: comma-separated `address:amount[:token[:chain]]` |
+| `--yes` | Skip confirmation prompt |
 
-# Filter by chain
-zoa --json balance --password "securepass" --chain solana
+### `receive` — Show Addresses & QR Codes
 
-# Get supported chains
-zoa --json chains
+```bash
+zoa receive [--password <pw>] [--chain <chain>]
+```
+
+### `history` — Transaction History
+
+```bash
+zoa history [--password <pw>] [--chain <chain>] [--limit <n>]
+```
+
+### `export` — Export Keys
+
+```bash
+# Export private key
+zoa export --password pw --type key --chain evm
+
+# Export recovery phrase
+zoa export --password pw --type mnemonic
+```
+
+| Flag | Description |
+|------|-------------|
+| `--password <pw>` | Wallet password |
+| `--type <type>` | `key` or `mnemonic` |
+| `--chain <chain>` | `evm` or `solana` (for `--type key`) |
+
+### `chains` — List Supported Networks
+
+```bash
+zoa chains
+```
+
+### `prices` — Token Prices
+
+```bash
+# Default price table
+zoa prices
+
+# Search for a specific token
+zoa prices search bitcoin
+
+# Browse popular tokens interactively
+zoa prices browse
+
+# Specify tokens
+zoa prices list --tokens "ethereum,solana,bitcoin"
+```
+
+### `api` — Manage API Keys
+
+```bash
+# Set API key
+zoa api set <key>
+
+# Show current key
+zoa api show
+
+# Remove key
+zoa api remove
+```
+
+### `link` — Link Wallet to External Apps
+
+Connect your ZOA wallet to external apps like Agenteur using EIP-191 signed proof of ownership.
+
+```bash
+# Link to Agenteur (interactive — prompts for API key and password)
+zoa link agenteur
+
+# Non-interactive with all flags
+zoa link agenteur --api-key ak_your_key_here --password mypassword
+```
+
+| Flag | Description |
+|------|-------------|
+| `<app>` | App name to link to (currently: `agenteur`) |
+| `--api-key <key>` | API key from the target app's dashboard |
+| `--password <pw>` | Wallet password (skip prompt) |
+
+**How it works:**
+1. Signs a structured message with your EVM key (EIP-191)
+2. Sends your wallet addresses + cryptographic proof to the app's API
+3. The app verifies the signature on-chain — no shared secrets needed
+4. Stores the link in `~/.zoa/config.json` for future reference
+
+**Web flow alternative:**
+You can also link via the ZOA web app at `wallet.zoa.fun/link?app=agenteur` — paste your app's Link Code and approve.
+
+### `config` — Configuration
+
+```bash
+# Show config
+zoa config show
+
+# Set a value
+zoa config set <key> <value>
+```
+
+## One-Liner Reference
+
+| Task | Command |
+|------|---------|
+| Send ETH on Base | `zoa send --chain base --to 0x... --amount 0.01 --password pw --yes` |
+| Send USDC on Ethereum | `zoa send --chain ethereum --token USDC --to 0x... --amount 100 --password pw --yes` |
+| Send max ETH | `zoa send --chain base --to 0x... --max --password pw --yes` |
+| Send SOL on Solana | `zoa send --chain solana --to ABC... --amount 1.5 --password pw --yes` |
+| Check balance (Base only) | `zoa balance --chain base --password pw` |
+| Export EVM private key | `zoa export --type key --chain evm --password pw` |
+| Link to Agenteur | `zoa link agenteur --api-key ak_... --password pw` |
+| Get JSON balances | `zoa --json balance --password pw` |
+| Get JSON prices | `zoa --json prices --tokens "ethereum,solana"` |
+
+## Batch Send
+
+Send to multiple recipients, tokens, and chains in a single command.
+
+**Format:** `address:amount[:token[:chain]]`
+- `token` defaults to the native currency (ETH, SOL, BNB, etc.)
+- `chain` defaults to the `--chain` flag value, or `base` if not specified
+
+### Examples
+
+```bash
+# Same chain, same token, multiple recipients
+zoa send --chain base --batch "0xAAA...111:0.01,0xBBB...222:0.02,0xCCC...333:0.03" --password pw --yes
+
+# Multiple tokens on the same chain
+zoa send --chain ethereum --batch "0xAAA...111:100:USDC,0xBBB...222:50:USDT,0xCCC...333:0.1" --password pw --yes
+
+# Multiple chains and tokens in one command
+zoa send --batch "0xAAA...111:100:USDC:ethereum,4Jyn...abc:0.5:SOL:solana,0xBBB...222:50:USDT:base" --password pw --yes
+```
+
+### Batch Output
+
+- Each transfer executes sequentially with progress indicators
+- Failed transfers do not stop remaining transfers
+- A summary is shown at the end with success/failure counts
+- JSON mode returns an array of results
+
+## JSON Mode for AI Agents
+
+Every command supports `--json` for machine-readable output. Place the flag before the command name.
+
+```bash
+zoa --json <command> [options]
+```
+
+### Example Outputs
+
+**Create wallet:**
+```bash
+zoa --json wallet create --password "securepass"
+```
+```json
+{
+  "address": "0x1234...abcd",
+  "solanaAddress": "ABC...xyz",
+  "label": "Wallet 1"
+}
+```
+
+**Get balances:**
+```bash
+zoa --json balance --password pw
+```
+```json
+{
+  "balances": [
+    { "chain": "Base", "token": "ETH", "balance": "0.0542", "usd": "170.21" },
+    { "chain": "Base", "token": "USDC", "balance": "100.0", "usd": "100.00" }
+  ]
+}
+```
+
+**Send tokens:**
+```bash
+zoa --json send --chain base --to 0x... --amount 0.01 --password pw --yes
+```
+```json
+{
+  "status": "sent",
+  "hash": "0xabc...def",
+  "from": "0x1234...abcd",
+  "to": "0x5678...efgh",
+  "token": "ETH",
+  "amount": "0.01",
+  "chain": "Base",
+  "explorerUrl": "https://basescan.org/tx/0xabc...def"
+}
+```
 
-# Get prices
-zoa --json prices --tokens "ethereum,solana,bitcoin"
+**Batch send:**
+```bash
+zoa --json send --batch "0xA:0.01,0xB:0.02" --chain base --password pw --yes
+```
+```json
+{
+  "batch": true,
+  "results": [
+    { "to": "0xA...", "amount": "0.01", "token": "ETH", "chain": "Base", "status": "sent", "hash": "0x..." },
+    { "to": "0xB...", "amount": "0.02", "token": "ETH", "chain": "Base", "status": "sent", "hash": "0x..." }
+  ],
+  "summary": { "total": 2, "succeeded": 2, "failed": 0 }
+}
 ```
 
-### Example JSON Output
+**Link wallet:**
+```bash
+zoa --json link agenteur --api-key ak_your_key --password pw
+```
+```json
+{
+  "app": "agenteur",
+  "signer": "0x742d...abcd",
+  "addresses": {
+    "ethereum": "0x742d...abcd",
+    "base": "0x742d...abcd",
+    "polygon": "0x742d...abcd",
+    "arbitrum": "0x742d...abcd",
+    "optimism": "0x742d...abcd",
+    "avalanche": "0x742d...abcd"
+  },
+  "linkedAt": 1709472000000
+}
+```
 
+**Get chains:**
 ```bash
-$ zoa --json chains
+zoa --json chains
 ```
 ```json
 {
   "chains": [
     { "name": "Ethereum", "symbol": "ETH", "chainId": 1 },
     { "name": "Base", "symbol": "ETH", "chainId": 8453 },
-    { "name": "Solana", "symbol": "SOL", "chainId": -1 },
-    ...
+    { "name": "Solana", "symbol": "SOL", "chainId": -1 }
+  ]
+}
+```
+
+**Get prices:**
+```bash
+zoa --json prices --tokens "ethereum,solana"
+```
+```json
+{
+  "prices": [
+    { "id": "ethereum", "symbol": "ETH", "price": 3245.67, "change24h": 2.34 },
+    { "id": "solana", "symbol": "SOL", "price": 142.89, "change24h": -1.12 }
   ]
 }
 ```
 
-## Non-Interactive Mode
+## API Reference
+
+The ZOA backend API provides programmatic access. All `/v1` endpoints require an API key in the `Authorization` header.
 
-All commands accept flags for fully non-interactive usage — perfect for CI/CD, scripts, and AI agents:
+### Authentication
 
 ```bash
-# Init without prompts
-zoa init --mnemonic "..." --password "..." --word-count 24
+# Set your API key
+zoa api set zoa_sk_your_key_here
 
-# Balance without prompts
-zoa balance --password "..." --chain base
+# Use with curl
+curl -H "Authorization: Bearer zoa_sk_your_key_here" https://api.zoa.fun/v1/chains
+```
 
-# Send without prompts
-zoa send --password "..." --to 0x... --amount 0.1 --chain base --yes
+### Endpoints
 
-# Export without prompts
-zoa export --password "..." --type key --chain evm
-zoa export --password "..." --type mnemonic
+#### `GET /v1/chains`
+List all supported blockchain networks.
+```bash
+curl -H "Authorization: Bearer $API_KEY" https://api.zoa.fun/v1/chains
+```
+```json
+{
+  "data": {
+    "chains": [
+      { "id": 1, "name": "Ethereum", "symbol": "ETH", "type": "evm" },
+      { "id": 8453, "name": "Base", "symbol": "ETH", "type": "evm" },
+      { "id": 56, "name": "BNB Smart Chain", "symbol": "BNB", "type": "evm" },
+      { "id": 42161, "name": "Arbitrum One", "symbol": "ETH", "type": "evm" },
+      { "id": 10, "name": "Optimism", "symbol": "ETH", "type": "evm" },
+      { "id": 0, "name": "Solana", "symbol": "SOL", "type": "non-evm" }
+    ]
+  }
+}
 ```
 
-## Supported Networks
+#### `POST /v1/wallets`
+Create a managed wallet. Requires `write` permission.
+```bash
+curl -X POST -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"label": "Trading Bot"}' \
+  https://api.zoa.fun/v1/wallets
+```
 
-| Network | Symbol | Type |
-|---------|--------|------|
-| Ethereum | ETH | EVM |
-| Base | ETH | EVM |
-| BNB Smart Chain | BNB | EVM |
+#### `GET /v1/wallets`
+List all wallets associated with your API key.
+```bash
+curl -H "Authorization: Bearer $API_KEY" https://api.zoa.fun/v1/wallets
+```
 
-| Arbitrum One | ETH | EVM |
-| Optimism | ETH | EVM |
-| Solana | SOL | Non-EVM |
-| Hyperliquid | HYPE | Non-EVM |
+#### `GET /v1/wallets/{id}`
+Get a specific wallet by UUID.
+```bash
+curl -H "Authorization: Bearer $API_KEY" https://api.zoa.fun/v1/wallets/{id}
+```
 
-## Configuration
+#### `GET /v1/balances/{address}`
+Get token balances for an address. Optionally filter by chain.
+```bash
+curl -H "Authorization: Bearer $API_KEY" "https://api.zoa.fun/v1/balances/0x1234...?chain=8453"
+```
 
-ZOA stores configuration in `~/.zoa/`:
+#### `GET /v1/balances/{address}/all`
+Get balances across all supported chains.
+```bash
+curl -H "Authorization: Bearer $API_KEY" https://api.zoa.fun/v1/balances/0x1234.../all
+```
 
+#### `POST /v1/transfer`
+Create a transfer. Requires `write` permission.
 ```bash
-# View config
-zoa config show
+curl -X POST -H "Authorization: Bearer $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "from_wallet_id": "uuid",
+    "to_address": "0x...",
+    "chain_id": 8453,
+    "amount": "0.01",
+    "token_address": null,
+    "priority": "standard"
+  }' \
+  https://api.zoa.fun/v1/transfer
+```
 
-# Set default chain
-zoa config set defaultChain base
+#### `GET /v1/transactions/{address}`
+Get transaction history for an address.
+```bash
+curl -H "Authorization: Bearer $API_KEY" "https://api.zoa.fun/v1/transactions/0x1234...?chain=8453&limit=10&offset=0"
+```
 
-# Set API key
-zoa api set zoa_sk_your_key_here
+#### `GET /v1/transactions/hash/{hash}`
+Get a specific transaction by hash.
+```bash
+curl -H "Authorization: Bearer $API_KEY" "https://api.zoa.fun/v1/transactions/hash/0xabc...?chain=8453"
+```
 
-# Set custom API URL
-zoa config set apiUrl https://api.zoa.fun
+#### `GET /v1/prices`
+Get cached token prices.
+```bash
+curl -H "Authorization: Bearer $API_KEY" "https://api.zoa.fun/v1/prices?tokens=ethereum,solana,bitcoin"
 ```
 
-## SDK
+#### `GET /v1/prices/{token_id}`
+Get price for a single token.
+```bash
+curl -H "Authorization: Bearer $API_KEY" https://api.zoa.fun/v1/prices/ethereum
+```
 
-For programmatic usage in your applications, use the ZOA SDK:
+#### `GET /v1/gas/{chain_id}`
+Get gas estimates (slow/standard/fast) for a chain.
+```bash
+curl -H "Authorization: Bearer $API_KEY" https://api.zoa.fun/v1/gas/8453
+```
+```json
+{
+  "data": {
+    "chain_id": 8453,
+    "slow": { "gwei": "0.001", "estimated_seconds": 30 },
+    "standard": { "gwei": "0.002", "estimated_seconds": 15 },
+    "fast": { "gwei": "0.005", "estimated_seconds": 5 }
+  }
+}
+```
 
-```typescript
-import { ZoaWallet } from '@zoa/sdk';
+#### Key Management
 
-// Create a new wallet
-const wallet = await ZoaWallet.create();
-console.log(wallet.evmAddress);    // 0x...
-console.log(wallet.solanaAddress); // ABC...
+```bash
+# Create API key (requires admin permission)
+curl -X POST -H "Authorization: Bearer $ADMIN_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "My Bot", "permissions": ["read", "write"], "rate_limit_per_min": 60}' \
+  https://api.zoa.fun/v1/keys
 
-// Sign data
-const sig = await wallet.sign(data, 'evm');
+# List API keys
+curl -H "Authorization: Bearer $ADMIN_KEY" https://api.zoa.fun/v1/keys
 
-// Export keys
-const pk = wallet.exportPrivateKey('evm');
+# Revoke an API key
+curl -X DELETE -H "Authorization: Bearer $ADMIN_KEY" https://api.zoa.fun/v1/keys/{id}
 ```
 
+## Supported Networks
+
+| Network | Symbol | Chain ID | Type | Explorer |
+|---------|--------|----------|------|----------|
+| Ethereum | ETH | 1 | EVM | etherscan.io |
+| Base | ETH | 8453 | EVM | basescan.org |
+| BNB Smart Chain | BNB | 56 | EVM | bscscan.com |
+| Arbitrum One | ETH | 42161 | EVM | arbiscan.io |
+| Optimism | ETH | 10 | EVM | optimistic.etherscan.io |
+| Solana | SOL | — | Non-EVM | solscan.io |
+| Hyperliquid | HYPE | 999 | Non-EVM | — |
+
+### Known ERC-20 Tokens
+
+Automatically detected in balance checks and available in the send token picker:
+
+| Token | Ethereum | Base | Arbitrum | Optimism | BSC |
+|-------|----------|------|----------|----------|-----|
+| USDT | Yes | — | Yes | Yes | Yes |
+| USDC | Yes | Yes | Yes | Yes | Yes |
+| DAI | Yes | Yes | Yes | Yes | Yes |
+| WBTC | Yes | — | Yes | Yes | Yes |
+| LINK | Yes | — | — | — | — |
+| UNI | Yes | — | — | — | — |
+| WETH | — | Yes | — | — | — |
+
 ## Security
 
-- Wallet data is encrypted with AES-256-GCM (PBKDF2 600k iterations)
-- Private keys are held in memory only during the session
-- Vault is stored locally at `~/.zoa/vault.json`
-- No data is sent to any server unless you explicitly use API features
+- **Encryption:** Wallet data is encrypted with AES-256-GCM using PBKDF2 (600k iterations) key derivation
+- **Key isolation:** Private keys are held in memory only during the active session
+- **Local storage:** Vault is stored locally at `~/.zoa/vault.json` — no cloud sync
+- **No telemetry:** No data is sent to any server unless you explicitly use API features
+- **API keys:** Scoped permissions (read/write/admin) with optional expiry and rate limits
+
+## Configuration
+
+ZOA stores data in `~/.zoa/`:
+
+| File | Description |
+|------|-------------|
+| `vault.json` | Encrypted wallet data |
+| `config.json` | User preferences and settings |
+| `wallets.json` | Wallet metadata (labels, colors, active wallet) |
+
+```bash
+# View config
+zoa config show
+
+# Set default chain
+zoa config set defaultChain base
+
+# Set API URL
+zoa config set apiUrl https://api.zoa.fun
+
+# Set API key
+zoa api set zoa_sk_your_key_here
+```
 
 ## License