zoa-wallet 0.1.0

package/README.md

@@ -0,0 +1,172 @@
+# ZOA Wallet CLI
+
+**API-First Crypto Wallet for Developers & AI Agents**
+
+ZOA is a multi-chain crypto wallet designed for programmatic access. Manage wallets, check balances, send tokens, and more — all from your terminal or scripts.
+
+## Install
+
+```bash
+# Install globally
+npm install -g zoa-wallet
+
+# Or use directly with npx
+npx zoa-wallet
+
+# Or with pnpm
+pnpm add -g zoa-wallet
+
+# Or with yarn
+yarn global add zoa-wallet
+```
+
+## Quick Start
+
+```bash
+# Create a new wallet
+zoa init
+
+# Check balances across all chains
+zoa balance
+
+# Show receive addresses with QR codes
+zoa receive
+
+# View supported networks
+zoa chains
+
+# Check live token prices
+zoa prices
+```
+
+## Commands
+
+| 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 |
+
+## JSON Mode (for Scripts & AI Agents)
+
+Every command supports `--json` for machine-readable output:
+
+```bash
+# Create wallet non-interactively
+zoa --json init --mnemonic "your twelve word phrase here ..." --password "securepass"
+
+# Get balances as JSON
+zoa --json balance --password "securepass"
+
+# Filter by chain
+zoa --json balance --password "securepass" --chain solana
+
+# Get supported chains
+zoa --json chains
+
+# Get prices
+zoa --json prices --tokens "ethereum,solana,bitcoin"
+```
+
+### Example JSON Output
+
+```bash
+$ zoa --json chains
+```
+```json
+{
+  "chains": [
+    { "name": "Ethereum", "symbol": "ETH", "chainId": 1 },
+    { "name": "Base", "symbol": "ETH", "chainId": 8453 },
+    { "name": "Solana", "symbol": "SOL", "chainId": -1 },
+    ...
+  ]
+}
+```
+
+## Non-Interactive Mode
+
+All commands accept flags for fully non-interactive usage — perfect for CI/CD, scripts, and AI agents:
+
+```bash
+# Init without prompts
+zoa init --mnemonic "..." --password "..." --word-count 24
+
+# Balance without prompts
+zoa balance --password "..." --chain base
+
+# Send without prompts
+zoa send --password "..." --to 0x... --amount 0.1 --chain base --yes
+
+# Export without prompts
+zoa export --password "..." --type key --chain evm
+zoa export --password "..." --type mnemonic
+```
+
+## Supported Networks
+
+| Network | Symbol | Type |
+|---------|--------|------|
+| Ethereum | ETH | EVM |
+| Base | ETH | EVM |
+| BNB Smart Chain | BNB | EVM |
+| Polygon | POL | EVM |
+| Arbitrum One | ETH | EVM |
+| Optimism | ETH | EVM |
+| Solana | SOL | Non-EVM |
+| Hyperliquid | HYPE | Non-EVM |
+
+## Configuration
+
+ZOA stores configuration in `~/.zoa/`:
+
+```bash
+# View config
+zoa config show
+
+# Set default chain
+zoa config set defaultChain base
+
+# Set API key
+zoa api set zoa_sk_your_key_here
+
+# Set custom API URL
+zoa config set apiUrl https://api.zoa.fun
+```
+
+## SDK
+
+For programmatic usage in your applications, use the ZOA SDK:
+
+```typescript
+import { ZoaWallet } from '@zoa/sdk';
+
+// Create a new wallet
+const wallet = await ZoaWallet.create();
+console.log(wallet.evmAddress);    // 0x...
+console.log(wallet.solanaAddress); // ABC...
+
+// Sign data
+const sig = await wallet.sign(data, 'evm');
+
+// Export keys
+const pk = wallet.exportPrivateKey('evm');
+```
+
+## 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
+
+## License
+
+MIT