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 — audit before use
• npm package: 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. 1. You create or import a wallet with a password → encrypted on disk in INLINECODE0
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
• Verify the npm package matches the repo: INLINECODE2
• Test with small amounts first
• Use short session durations (1hr default)
• Run in an isolated environment if possible

Setup

CODEBLOCK0

Verify installation: INLINECODE3

Workflow

1. 1. Init (first time): INLINECODE4

1. 2. Import (existing wallet): INLINECODE5
2. Unlock: INLINECODE6

1. 4. Use: Pass --token wlt_... to all commands (no password needed)
2. 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)
• INLINECODE14 (default: ~/.agent-wallet-cli)
• INLINECODE15 — suppress output
• INLINECODE16 — wallet name (default: "default")

Commands

Wallet Management

Addresses & Balances

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

• - --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

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)

Signing

Transaction History

Network Configuration

Chains & Networks

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, INLINECODE38

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