zoa-wallet 0.3.3 → 0.3.5

package/README.md

@@ -24,13 +24,16 @@ 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
@@ -39,133 +42,476 @@ zoa chains
 zoa prices
 ```
 
-## Commands
+## 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>]
+```
+
+### `balance` — Check Balances
 
-| 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 |
+```bash
+zoa balance [--password <pw>] [--chain <chain>]
+```
 
-## JSON Mode (for Scripts & AI Agents)
+| Flag | Description |
+|------|-------------|
+| `--password <pw>` | Wallet password (skip prompt) |
+| `--chain <chain>` | Filter to a specific chain (`base`, `ethereum`, `solana`, etc.) |
 
-Every command supports `--json` for machine-readable output:
+### `send` — Send Tokens
 
+Interactive:
 ```bash
-# Create wallet non-interactively
-zoa --json init --mnemonic "your twelve word phrase here ..." --password "securepass"
+zoa send
+```
 
-# Get balances as JSON
-zoa --json balance --password "securepass"
+One-liner:
+```bash
+zoa send --chain base --to 0x... --amount 0.01 --password pw --yes
+```
 
-# Filter by chain
-zoa --json balance --password "securepass" --chain solana
+| 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 |
 
-# Get supported chains
-zoa --json chains
+### `receive` — Show Addresses & QR Codes
+
+```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
 
-# Get prices
-zoa --json prices --tokens "ethereum,solana,bitcoin"
+# Specify tokens
+zoa prices list --tokens "ethereum,solana,bitcoin"
 ```
 
-### Example JSON Output
+### `api` — Manage API Keys
 
 ```bash
-$ zoa --json chains
+# Set API key
+zoa api set <key>
+
+# Show current key
+zoa api show
+
+# Remove key
+zoa api remove
+```
+
+### `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` |
+| 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"
+}
+```
+
+**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 }
+}
+```
+
+**Get chains:**
+```bash
+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
 
-All commands accept flags for fully non-interactive usage — perfect for CI/CD, scripts, and AI agents:
+The ZOA backend API provides programmatic access. All `/v1` endpoints require an API key in the `Authorization` header.
+
+### 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
 

package/dist/index.mjs

@@ -36001,13 +36001,11 @@ var BaseEVMAdapter = class {
           if (!token || !result || result.status !== "success")
             continue;
           const balance = BigInt(result.result);
-          if (balance > 0n) {
-            balances.push({
-              token,
-              balance,
-              formatted: formatUnits(balance, token.decimals)
-            });
-          }
+          balances.push({
+            token,
+            balance,
+            formatted: formatUnits(balance, token.decimals)
+          });
         }
       } catch {
       }
@@ -36072,17 +36070,35 @@ var BaseEVMAdapter = class {
     });
   }
   async signAndSendNativeTransfer(params) {
+    this.initClient();
     const account = privateKeyToAccount(params.privateKey);
+    const viemChain = this.getViemChain();
+    const balance = await this.client.getBalance({ address: account.address });
+    let sendValue = params.value;
+    if (sendValue > 0n && sendValue >= balance) {
+      try {
+        const feeData = await this.client.estimateFeesPerGas();
+        const maxFeePerGas = feeData.maxFeePerGas ?? 0n;
+        const gasCost = 21000n * maxFeePerGas;
+        if (balance <= gasCost) {
+          throw new Error(`Insufficient balance. You have ${formatEther(balance)} ${this.config.nativeCurrency.symbol} which is not enough to cover gas fees.`);
+        }
+        sendValue = balance - gasCost;
+      } catch (err3) {
+        if (err3 instanceof Error && err3.message.includes("Insufficient balance"))
+          throw err3;
+      }
+    }
     const walletClient = createWalletClient({
       account,
-      chain: this.getViemChain(),
+      chain: viemChain,
       transport: http(this.config.rpcUrls[0])
     });
     const hash3 = await walletClient.sendTransaction({
       account,
       to: params.to,
-      value: params.value,
-      chain: this.getViemChain()
+      value: sendValue,
+      chain: viemChain
     });
     return { hash: hash3 };
   }
@@ -47984,12 +48000,13 @@ var SolanaAdapter = class {
     const secretBytes = Uint8Array.from((params.privateKey.startsWith("0x") ? params.privateKey.slice(2) : params.privateKey).match(/.{1,2}/g).map((byte) => Number.parseInt(byte, 16)));
     const keypair = Keypair.fromSecretKey(secretBytes);
     const balance = await this.connection.getBalance(keypair.publicKey);
-    const lamports = Number(params.value);
+    let lamports = Number(params.value);
     const estimatedFee = 5e3;
-    if (balance < lamports + estimatedFee) {
-      const balSOL = (balance / LAMPORTS_PER_SOL).toFixed(6);
-      const needed = ((lamports + estimatedFee) / LAMPORTS_PER_SOL).toFixed(6);
-      throw new Error(`Insufficient SOL balance. You have ${balSOL} SOL but need ${needed} SOL (${(lamports / LAMPORTS_PER_SOL).toFixed(6)} SOL + ~0.000005 SOL tx fee).`);
+    if (balance < estimatedFee + 1) {
+      throw new Error(`Insufficient SOL balance. You have ${(balance / LAMPORTS_PER_SOL).toFixed(6)} SOL which is not enough to cover the transaction fee.`);
+    }
+    if (lamports + estimatedFee > balance) {
+      lamports = balance - estimatedFee;
     }
     const transaction = new Transaction().add(SystemProgram.transfer({
       fromPubkey: keypair.publicKey,
@@ -49804,9 +49821,27 @@ function cleanErrorMessage(error) {
     return firstLine;
   return full.slice(0, 200);
 }
+function parseBatchString(batch) {
+  return batch.split(",").map((entry) => {
+    const parts = entry.trim().split(":");
+    if (parts.length < 2) {
+      throw new Error(`Invalid batch entry "${entry}". Format: address:amount[:token[:chain]]`);
+    }
+    return {
+      to: parts[0],
+      amount: parts[1],
+      token: parts[2] || void 0,
+      chain: parts[3] || void 0
+    };
+  });
+}
 function registerSendCommand(program2) {
-  program2.command("send").description("Send tokens to an address").option("--password <password>", "Wallet password (non-interactive)").option("--to <address>", "Recipient address").option("--amount <amount>", "Amount to send").option("--chain <chain>", "Chain to use (base, ethereum, solana, etc.)").option("--token <token>", "Token to send (symbol, e.g. USDT, USDC). Defaults to native.").option("--yes", "Skip confirmation prompt").action(async (opts) => {
+  program2.command("send").description("Send tokens to an address").option("--password <password>", "Wallet password (non-interactive)").option("--to <address>", "Recipient address").option("--amount <amount>", "Amount to send").option("--chain <chain>", "Chain to use (base, ethereum, solana, etc.)").option("--token <token>", "Token to send (symbol, e.g. USDT, USDC). Defaults to native.").option("--max", "Send maximum available balance (auto-deducts gas)").option("--batch <transfers>", 'Batch send: comma-separated "address:amount[:token[:chain]]"').option("--yes", "Skip confirmation prompt").action(async (opts) => {
     try {
+      if (opts.batch) {
+        await handleBatchSend(opts);
+        return;
+      }
       let password;
       if (opts.password) {
         password = opts.password;
@@ -49885,10 +49920,11 @@ function registerSendCommand(program2) {
       } else if (tokenBalances.length === 1) {
         selectedToken = tokenBalances[0];
       } else {
-        const choices = tokenBalances.map((tb) => ({
-          name: `${tb.token.symbol.padEnd(8)} ${formatBalance(tb.formatted)} ${tb.token.name}`,
-          value: tb.token.address
-        }));
+        const choices = tokenBalances.map((tb) => {
+          const bal = formatBalance(tb.formatted);
+          const label = tb.balance === 0n ? colors.muted(`${tb.token.symbol.padEnd(8)} 0.00     ${tb.token.name}`) : `${tb.token.symbol.padEnd(8)} ${bal.padEnd(10)} ${tb.token.name}`;
+          return { name: label, value: tb.token.address };
+        });
         const { tokenAddr } = await inquirer6.prompt([{
           type: "list",
           name: "tokenAddr",
@@ -49926,7 +49962,15 @@ function registerSendCommand(program2) {
         throw new Error(`Invalid EVM address: ${to}. Must be 0x followed by 40 hex characters.`);
       }
       let amount;
-      if (opts.amount) {
+      if (opts.max) {
+        amount = selectedToken.formatted;
+        if (Number.parseFloat(amount) <= 0) {
+          throw new Error(`No ${tokenSymbol} balance available to send.`);
+        }
+        if (!isJsonMode()) {
+          console.log(colors.muted(`  Using max balance: ${formatBalance(amount)} ${tokenSymbol}`));
+        }
+      } else if (opts.amount) {
         amount = opts.amount;
       } else {
         const { sendAmount } = await inquirer6.prompt([{
@@ -50074,6 +50118,163 @@ function registerSendCommand(program2) {
     }
   });
 }
+async function handleBatchSend(opts) {
+  const transfers = parseBatchString(opts.batch);
+  const defaultChain = opts.chain?.toLowerCase() || "base";
+  for (const t of transfers) {
+    const chain2 = t.chain || defaultChain;
+    const chainId = CHAIN_MAP2[chain2];
+    if (chainId === void 0)
+      throw new Error(`Unsupported chain "${chain2}" in batch entry for ${t.to}`);
+    const isSolana = chainId === ChainId.Solana;
+    if (isSolana && !isValidSolanaAddress(t.to)) {
+      throw new Error(`Invalid Solana address in batch: ${t.to}`);
+    }
+    if (!isSolana && !isValidEvmAddress(t.to)) {
+      throw new Error(`Invalid EVM address in batch: ${t.to}`);
+    }
+    const num2 = Number.parseFloat(t.amount);
+    if (Number.isNaN(num2) || num2 <= 0) {
+      throw new Error(`Invalid amount "${t.amount}" in batch entry for ${t.to}`);
+    }
+  }
+  let password;
+  if (opts.password) {
+    password = opts.password;
+  } else {
+    const { pwd } = await inquirer6.prompt([{
+      type: "password",
+      name: "pwd",
+      message: "Enter your wallet password:",
+      mask: "*"
+    }]);
+    password = pwd;
+  }
+  const spinner = createSpinner("Unlocking wallet...");
+  if (!isJsonMode())
+    spinner.start();
+  let keyring2, account;
+  try {
+    ({ keyring: keyring2, account } = await loadActiveWallet(password));
+  } catch (err3) {
+    if (!isJsonMode())
+      spinner.stop();
+    throw err3;
+  }
+  if (!isJsonMode())
+    spinner.stop();
+  const results = [];
+  if (!isJsonMode()) {
+    console.log(colors.brandBold("  Batch Send"));
+    console.log(colors.muted(`  ${transfers.length} transfer(s) queued
+`));
+  }
+  for (let i = 0; i < transfers.length; i++) {
+    const t = transfers[i];
+    const chain2 = t.chain || defaultChain;
+    const chainId = CHAIN_MAP2[chain2];
+    const adapter = chainRegistry.get(chainId);
+    const isSolana = chainId === ChainId.Solana;
+    const from14 = isSolana ? account.solanaAddress : account.evmAddress;
+    const transferLabel = `[${i + 1}/${transfers.length}] ${t.amount} ${t.token || adapter.config.nativeCurrency.symbol} \u2192 ${t.to.slice(0, 10)}...`;
+    if (!isJsonMode()) {
+      spinner.text = `  ${transferLabel}`;
+      spinner.start();
+    }
+    try {
+      let tokenBalances;
+      try {
+        tokenBalances = await adapter.getTokenBalances(from14);
+      } catch {
+        tokenBalances = [{
+          token: {
+            address: "native",
+            symbol: adapter.config.nativeCurrency.symbol,
+            name: adapter.config.nativeCurrency.name,
+            decimals: adapter.config.nativeCurrency.decimals,
+            chainId: adapter.config.chainId
+          },
+          balance: 0n,
+          formatted: "0"
+        }];
+      }
+      const tokenSymbol = t.token || adapter.config.nativeCurrency.symbol;
+      const selectedToken = tokenBalances.find((tb) => tb.token.symbol.toLowerCase() === tokenSymbol.toLowerCase());
+      if (!selectedToken)
+        throw new Error(`Token ${tokenSymbol} not found on ${adapter.config.name}`);
+      const isNativeTransfer = selectedToken.token.address === "native";
+      const value = BigInt(Math.floor(Number.parseFloat(t.amount) * 10 ** selectedToken.token.decimals));
+      if (value > selectedToken.balance) {
+        throw new Error(`Insufficient ${tokenSymbol} balance. Have ${formatBalance(selectedToken.formatted)}, need ${t.amount}.`);
+      }
+      const chainFamily = isSolana ? "solana" : "evm";
+      const privateKey = keyring2.exportPrivateKey(0, chainFamily);
+      let hash3;
+      if (isNativeTransfer) {
+        if (!adapter.signAndSendNativeTransfer)
+          throw new Error(`Native transfers not supported for ${adapter.config.name}`);
+        const result = await adapter.signAndSendNativeTransfer({ privateKey, to: t.to, value });
+        hash3 = result.hash;
+      } else {
+        if (!adapter.signAndSendTokenTransfer)
+          throw new Error(`Token transfers not supported for ${adapter.config.name}`);
+        const result = await adapter.signAndSendTokenTransfer({
+          privateKey,
+          tokenAddress: selectedToken.token.address,
+          to: t.to,
+          amount: value
+        });
+        hash3 = result.hash;
+      }
+      const explorerUrl = `${adapter.config.blockExplorerUrl}/tx/${hash3}`;
+      if (!isJsonMode())
+        spinner.stop();
+      if (!isJsonMode()) {
+        console.log(colors.success(`  \u2713 ${transferLabel}`));
+        console.log(colors.muted(`    ${explorerUrl}
+`));
+      }
+      results.push({
+        to: t.to,
+        amount: t.amount,
+        token: tokenSymbol,
+        chain: adapter.config.name,
+        status: "sent",
+        hash: hash3,
+        explorerUrl
+      });
+    } catch (err3) {
+      if (!isJsonMode())
+        spinner.stop();
+      const errMsg = cleanErrorMessage(err3);
+      if (!isJsonMode()) {
+        console.log(colors.error(`  \u2717 ${transferLabel}`));
+        console.log(colors.muted(`    ${errMsg}
+`));
+      }
+      results.push({
+        to: t.to,
+        amount: t.amount,
+        token: t.token || chain2,
+        chain: chain2,
+        status: "failed",
+        error: errMsg
+      });
+    }
+  }
+  const succeeded = results.filter((r) => r.status === "sent").length;
+  const failed = results.filter((r) => r.status === "failed").length;
+  output({ batch: true, results, summary: { total: results.length, succeeded, failed } }, () => {
+    console.log();
+    const summaryLines = [
+      kvLine("Total", String(results.length)),
+      kvLine("Succeeded", colors.success(String(succeeded))),
+      kvLine("Failed", failed > 0 ? colors.error(String(failed)) : "0")
+    ];
+    console.log(successBox("Batch Complete", summaryLines));
+    console.log();
+  });
+}
 
 // dist/commands/wallet.js
 import chalk3 from "chalk";
@@ -50577,7 +50778,7 @@ var zoaGradient2 = gradient2([
   "#c77dff"
 ]);
 var subtleGradient = gradient2(["#6b7280", "#9ca3af", "#6b7280"]);
-var VERSION = "0.3.3";
+var VERSION = "0.3.4";
 async function displayBanner() {
   const banner = figlet.textSync("ZOA-wallet", { font: "ANSI Shadow" });
   console.log();
@@ -50615,7 +50816,7 @@ program.hook("preAction", async (_thisCommand, actionCommand) => {
     }
   }
 });
-program.name("zoa").description("ZOA Wallet \u2014 API-First Crypto Wallet for Power-traders, Developers, & AI Agents").version("0.3.3");
+program.name("zoa").description("ZOA Wallet \u2014 API-First Crypto Wallet for Power-traders, Developers, & AI Agents").version("0.3.4");
 registerWalletCommand(program);
 registerBalanceCommand(program);
 registerSendCommand(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zoa-wallet",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "API-First Crypto Wallet CLI for Power-traders, Developers, & AI Agents. Manage multi-chain wallets from your terminal.",
   "type": "module",
   "license": "MIT",