agent-wallet

# Agent Wallet Self-custodial crypto wallet CLI for AI agents. Your keys, your coins — the agent never sees your mnemonic after init. - **Open source**: [github.com/donald-jackson/agent-wallet-cli](https://github.com/donald-jackson/agent-wallet-cli) — audit before use - **npm package**: [npmjs.com/package/agent-wallet-cli](https://www.npmjs.com/package/agent-wallet-cli) - **Self-custodial**: Keys encrypted locally with Argon2id + AES-256-GCM. No server, no third party. - **Session-based access**: Agents use time-limited tokens, never your password directly. - **Multi-chain**: Ethereum, Solana, Polygon, Arbitrum, Base — native coins and tokens. ## Security Model 1. **You** create or import a wallet with a password → encrypted on disk in `~/.agent-wallet-cli/` 2. **You** (or the agent) unlock with the password → get a time-limited session token (`wlt_...`) 3. **The agent** uses only the session token — it expires automatically (default 1hr, max 24hr) 4. **No telemetry, no analytics, no server calls** — only public blockchain RPCs for queries and transactions **Important: If you give the agent your WALLET_PASSWORD**, it can perform any password-level operation (init, import, unlock, and export). For maximum security, **unlock the wallet yourself** and only give the agent the session token. Session tokens cannot export mnemonics or change passwords — they can only sign transactions and read balances. **Before trusting this skill with real funds:** - Audit the source: [github.com/donald-jackson/agent-wallet-cli](https://github.com/donald-jackson/agent-wallet-cli) - Verify the npm package matches the repo: `npm info agent-wallet-cli` - Test with small amounts first - Use short session durations (1hr default) - Run in an isolated environment if possible ## Setup ```bash npm install -g agent-wallet-cli ``` Verify installation: `agent-wallet-cli --version` ## Workflow 1. **Init** (first time): `agent-wallet-cli init --password "$WALLET_PASSWORD"` - Displays mnemonic ONCE — save it securely 2. **Import** (existing wallet): `agent-wallet-cli import --password "$WALLET_PASSWORD" --mnemonic "word1 word2 ..."` 3. **Unlock**: `agent-wallet-cli unlock --password "$WALLET_PASSWORD" --duration 3600` - Returns session token (`wlt_...`) valid for specified duration 4. **Use**: Pass `--token wlt_...` to all commands (no password needed) 5. **Lock**: `agent-wallet-cli lock` when done **Note:** `--password` and `--mnemonic` can be omitted to be prompted securely via stdin (recommended for interactive use). When using in automation, `--password` is accepted but will show a warning about shell history visibility. ## Global Options All commands accept: - `--format json|text` (default: json) - `--wallet-dir <path>` (default: ~/.agent-wallet-cli) - `--quiet` — suppress output - `--name <name>` — wallet name (default: "default") ## Commands ### Wallet Management ```bash agent-wallet-cli init [--password <pw>] [--word-count 12|24] [--name <name>] agent-wallet-cli import [--password <pw>] [--mnemonic "<phrase>"] [--name <name>] agent-wallet-cli unlock [--password <pw>] [--duration <secs>] [--name <name>] agent-wallet-cli lock [--name <name>] agent-wallet-cli export [--password <pw>] --confirm [--name <name>] ``` ### Addresses & Balances ```bash agent-wallet-cli address --token <wlt_...> [--chain ethereum|solana] [--account-index 0] agent-wallet-cli balance --token <wlt_...> --chain <chain> [--network <network>] [--token-address usdc] ``` **Important:** `--chain` is **required** for balance/send/history. `--token` is the session token (wlt_...), `--token-address` is the coin/token contract or alias. **L2 networks:** For Base, Polygon, Arbitrum use `--chain ethereum --network base` (etc). Default network is `mainnet`. ### Transfers ```bash # Native (ETH/SOL) agent-wallet-cli send --token <wlt_...> --chain <chain> --to <addr> --amount <amt> --yes [--dry-run] [--no-relay] # ERC-20/SPL token agent-wallet-cli send --token <wlt_...> --chain <chain> --to <addr> --amount <amt> --token-address <addr|alias> --yes [--no-relay] ``` - **`--yes`**: Skip confirmation prompt (required for non-TTY/agent use) - **`--dry-run`**: Simulate transaction without sending - **`--no-relay`**: Disable gasless relay fallback - **`--network <network>`**: Target network (default: mainnet) ### x402 Payments ```bash agent-wallet-cli x402 <url> --token <wlt_...> [--method GET] [--header "Key:Value"] [--body <data|@file>] [--max-amount <amt>] [--dry-run] [--yes] ``` Make HTTP requests with automatic x402 payment. The CLI detects 402 Payment Required responses, pays the requested amount in stablecoins, and retries. - **`--max-amount <amount>`**: Maximum willing to pay (human-readable, e.g. "0.10") - **`--dry-run`**: Show payment requirements without paying - **`--yes`**: Skip payment confirmation - **`--header`**: Repeatable for multiple headers - **`--body`**: Request body, or `@filepath` to read from file ### Approvals (ERC-20/SPL) ```bash agent-wallet-cli approve --token <wlt_...> --chain <chain> --token-address <addr> --spender <addr> --amount <amt|unlimited> --yes [--network <net>] agent-wallet-cli allowance --chain <chain> --token-address <addr> --owner <addr> --spender <addr> [--network <net>] agent-wallet-cli transfer-from --token <wlt_...> --chain <chain> --token-address <addr> --from <addr> --to <addr> --amount <amt> --yes [--network <net>] agent-wallet-cli approvals --token <wlt_...> [--chain ethereum] [--network mainnet] [--limit 20] ``` ### Signing ```bash agent-wallet-cli sign --token <wlt_...> --chain <chain> --message "text" agent-wallet-cli sign --token <wlt_...> --chain <chain> --typed-data '<json|@file>' agent-wallet-cli sign --token <wlt_...> --chain <chain> --data <hex> ``` ### Transaction History ```bash agent-wallet-cli history --token <wlt_...> --chain <chain> [--network mainnet] [--limit 10] ``` ### Network Configuration ```bash agent-wallet-cli networks # list all agent-wallet-cli networks --set ethereum:mainnet --rpc-url <url> # custom RPC agent-wallet-cli networks --reset ethereum:mainnet # reset to default ``` ## Chains & Networks | Chain | Networks | |-------|----------| | ethereum | mainnet, sepolia, polygon, arbitrum, base, base-sepolia | | solana | mainnet, devnet | EVM L2s (Base, Polygon, Arbitrum) use `--chain ethereum --network <l2name>`. **`--chain` is required** for balance, send, history, approve, allowance, transfer-from, approvals, and sign. ## Token Aliases Use shorthand instead of contract addresses: `usdc`, `usdt`, `dai`, `weth`, `wbtc` ## Security Notes - **Self-custodial** — keys never leave your machine, encrypted at rest - **No analytics, no telemetry, no network calls** except to public RPCs for blockchain queries - Session tokens grant temporary fund access — treat as passwords - Always `--dry-run` before large transfers - Lock wallet when done - Never log or share session tokens or mnemonics - Audit the source: [github.com/donald-jackson/agent-wallet-cli](https://github.com/donald-jackson/agent-wallet-cli)