# AgentsWallets

> Multi-chain wallet CLI for AI agents. HD wallets with BIP-39 mnemonic, supporting Ethereum, BNB, Base, Polygon, Arbitrum, and Solana.

## Quick Start (3 commands to get running)

npm install -g @agentswallets/cli

# 1. Initialize
aw init --json
# Expected: {"ok":true,"data":{"data_dir":"/home/user/.agentswallets"}}

# 2. Create wallet (derives both EVM + Solana addresses from one mnemonic)
aw wallet create --name my-agent --json
# Expected: {"ok":true,"data":{"name":"my-agent","evm_address":"0x...","solana_address":"7xK...","key_type":"hd","supported_chains":["ethereum","bnb","base","polygon","arbitrum","solana"]}}

# 3. Unlock session (required before write operations)
export AW_MASTER_PASSWORD="your-password"
aw unlock --json
# Expected: {"ok":true,"data":{"status":"unlocked","token_file":"...","expires_at":"2026-03-02T17:30:00.000Z"}}

## IMPORTANT NOTES FOR AI MODELS

- All commands support --json flag for structured output
- All responses follow envelope: {"ok":bool,"data":{},"error":{"code":"ERR_xxx","message":"...","recovery_hint":"..."}}
- Exit codes: 0=success, 1=business error, 2=system error, 3=auth error
- Write operations (send, predict buy/sell, swap exec, bridge exec, perp open/close/cancel) require active session via `aw unlock`
- Use --idempotency-key to prevent duplicate transactions
- Use --dry-run to validate before executing
- Non-interactive mode: set AW_NON_INTERACTIVE=1 and AW_JSON=1
- Default chain is Ethereum. Use --chain to switch (e.g., --chain solana, --chain polygon)
- Wallets are identified by name or EVM address. Solana addresses cannot be used as identifiers.
- Polymarket commands are hardcoded to Polygon (--chain flag not applicable)
- OKX DEX integration: swap tokens and bridge cross-chain on supported EVM chains
- Hyperliquid integration: trade perpetual contracts (0.05% builder fee applies)
- Security Guard: red-line rules block dangerous operations, yellow-line rules warn. Use --force to bypass warnings, --yes to confirm blocks.

## Supported Chains & Tokens

- Ethereum (chain_id: 1): ETH, USDC, USDT
- BNB Chain (chain_id: 56): BNB, USDC, USDT
- Base (chain_id: 8453): ETH, USDC
- Polygon (chain_id: 137): POL, USDC, USDC.e, USDT
- Arbitrum (chain_id: 42161): ETH, USDC, USDT
- Solana: SOL, USDC, USDT

## Machine Contract

### Response envelope
Success:
{"ok":true,"data":{...},"error":null,"meta":{"request_id":"req_..."}}

Failure:
{"ok":false,"data":null,"error":{"code":"ERR_xxx","message":"...","details":{},"recovery_hint":"..."},"meta":{"request_id":"req_..."}}

### Error codes (retryable)
- ERR_NEED_UNLOCK → run `aw unlock --json` then retry
- ERR_RPC_UNAVAILABLE → retry with backoff, or set AW_RPC_URL to a different endpoint

### Error codes (non-retryable)
- ERR_INSUFFICIENT_FUNDS → need more funds, check with `aw wallet balance`
- ERR_TX_FAILED → transaction failed on-chain, check explorer
- ERR_PER_TX_LIMIT_EXCEEDED → reduce amount or raise per-tx limit with `aw policy set`
- ERR_DAILY_LIMIT_EXCEEDED → wait for UTC midnight or raise limit with `aw policy set`
- ERR_TX_COUNT_LIMIT_EXCEEDED → wait for UTC midnight or raise max-tx-per-day
- ERR_TOKEN_NOT_ALLOWED → token not in allowlist, update with `aw policy set`
- ERR_ADDRESS_NOT_ALLOWED → address not in allowlist, update with `aw policy set`
- ERR_WALLET_NOT_FOUND → check wallet name with `aw wallet list`
- ERR_INVALID_PARAMS → check command arguments and input format
- ERR_AUTH_FAILED → check master password

### Environment variables
- AW_MASTER_PASSWORD — master password for non-interactive unlock
- AW_NON_INTERACTIVE=1 — disable all prompts
- AW_JSON=1 — force JSON output globally
- AW_RPC_URL — default RPC (fallback for chain-specific vars), comma-separated for failover
- AW_RPC_URL_ETHEREUM / AW_RPC_URL_BNB / AW_RPC_URL_BASE / AW_RPC_URL_POLYGON / AW_RPC_URL_ARBITRUM / AW_RPC_URL_SOLANA — chain-specific RPC endpoints
- AW_SESSION_TTL_MINUTES — session duration (default: 15, max: 15)
- AW_REQUEST_ID — request ID for tracing (also via --request-id flag)
- AW_ALLOW_EXPORT=1 — enable wallet export-key command (off by default)

## Commands Reference

### Init & Session
aw init --json                          # Initialize data store
aw unlock --json                        # Start session (15min, auto-renews)
aw lock --json                          # End session
aw health --json                        # Check system health (DB, RPC, session)

### Wallet
aw wallet create --name NAME --json     # Create HD wallet (EVM + Solana)
aw wallet list --json                   # List wallets
aw wallet balance WALLET --json         # Check balance (default chain: ethereum)
aw wallet balance WALLET --chain solana --json  # Check Solana balance
aw wallet balance --all --json          # Check all wallets
aw wallet deposit-address WALLET --json # Get deposit address
aw wallet deposit-address WALLET --chain solana --json  # Get Solana deposit address
aw wallet info WALLET --json            # Get wallet details
aw wallet drain WALLET --to ADDR --json # Drain all tokens to address
aw wallet drain WALLET --to ADDR --chain polygon --json  # Drain on specific chain

### Send Tokens
aw send --wallet W --to ADDR --amount N --token TOKEN --json                    # Send on default chain (ethereum)
aw send --wallet W --to ADDR --amount N --token TOKEN --chain polygon --json    # Send on specific chain
aw send --wallet W --to ADDR --amount N --token SOL --chain solana --json       # Send SOL on Solana
aw send --wallet W --to ADDR --amount N --token TOKEN --dry-run --json          # Validate only
aw send --wallet W --to ADDR --amount N --token TOKEN --idempotency-key KEY --json  # Idempotent send

### Policy
aw policy show WALLET --json                           # View spending limits
aw policy set WALLET --limit-per-tx N --limit-daily N --max-tx-per-day N --json  # Set limits

### Transactions
aw tx list --wallet W --json            # Transaction history
aw tx status TX_ID --json               # Check transaction status

### Polymarket (Prediction Markets — Polygon only)
aw predict markets -q QUERY --json                                       # Search markets
aw predict buy --wallet W --market M --outcome yes --size N --price P --json  # Buy position
aw predict sell --wallet W --position POS --size N --json                # Sell position
aw predict positions --wallet W --json                                   # View positions
aw predict orders --wallet W --json                                      # View open orders
aw predict cancel --wallet W --order-id ID --json                        # Cancel order
aw predict approve-set --wallet W --json                                 # First-time contract approvals (required before trading)

### DEX Swaps (OKX DEX Aggregator)
aw swap chains --json                                                          # List supported chains
aw swap quote --from ETH --to USDC --amount 0.1 --json                        # Get swap quote
aw swap exec --wallet W --from ETH --to USDC --amount 0.1 --json             # Execute swap

### Cross-Chain Bridge (OKX)
aw bridge chains --json                                                        # List bridge routes
aw bridge quote --from-chain ethereum --to-chain base --from-token ETH --to-token ETH --amount 0.1 --json  # Get quote
aw bridge exec --wallet W --from-chain ethereum --to-chain base --from-token ETH --to-token ETH --amount 0.1 --json  # Execute bridge
aw bridge status --bridge-id ID --json                                        # Check bridge status

### Market Data
aw market price --token ETH --json                                            # Get token price
aw market candles --token ETH --interval 1h --limit 24 --json                # Get OHLCV data
aw market trades --token ETH --limit 10 --json                               # Get recent trades

### Token Discovery
aw token search --keyword "pepe" --json                                       # Search tokens
aw token info --address 0x... --json                                          # Token details
aw token trending --json                                                      # Trending tokens
aw token holders --address 0x... --json                                       # Top holders

### On-Chain History
aw history list --wallet W --limit 20 --json                                  # On-chain tx history

### Perpetual Contracts (Hyperliquid)
aw perp assets --json                                                         # List available assets
aw perp prices --json                                                         # Current prices
aw perp funding --asset BTC --json                                            # Funding rates
aw perp account --wallet W --json                                             # Account summary
aw perp positions --wallet W --json                                           # Open positions
aw perp orders --wallet W --json                                              # Open orders
aw perp open --wallet W --asset BTC --side long --size 0.01 --leverage 10 --json  # Open position
aw perp close --wallet W --asset BTC --json                                   # Close position
aw perp cancel --wallet W --order-id ID --json                               # Cancel order

### Security
aw security status --json                                                     # Security Guard status
aw security blacklist add --address ADDR --reason "..." --json               # Add to blacklist
aw security blacklist remove --address ADDR --json                           # Remove from blacklist
aw security blacklist list --json                                            # List blacklisted addresses
aw security baseline init --json                                             # Init config baseline
aw security baseline verify --json                                           # Verify baseline
aw security report --json                                                    # Security report
aw security anomaly WALLET --json                                            # Anomaly detection

### Audit
aw audit list --wallet W --json         # View audit logs

## Error codes (new in v0.5.0)

### OKX-related
- ERR_OKX_AUTH → OKX API authentication failed
- ERR_OKX_API_FAILED → OKX API request failed, retry
- ERR_OKX_TIMEOUT → OKX API timeout, retry with backoff
- ERR_OKX_QUOTE_FAILED → Failed to get swap/bridge quote
- ERR_SWAP_FAILED → Token swap failed on-chain
- ERR_BRIDGE_FAILED → Cross-chain bridge failed

### Hyperliquid-related
- ERR_HL_API_FAILED → Hyperliquid API failed, retry
- ERR_HL_ORDER_FAILED → Order rejected, check params
- ERR_HL_INVALID_ASSET → Invalid asset, check `aw perp assets`
- ERR_HL_INSUFFICIENT_MARGIN → Insufficient margin, reduce size/leverage
- ERR_HL_BUILDER_FEE_FAILED → Builder fee failed, retry

### Security Guard-related
- ERR_RED_LINE_BLOCKED → Blocked by red-line rule, use --yes to confirm
- ERR_RATE_LIMITED → Rate limit exceeded, wait and retry
- ERR_BLACKLISTED_ADDRESS → Address is blacklisted
- ERR_BASELINE_TAMPERED → Config baseline mismatch, investigate
- ERR_PREFLIGHT_FAILED → Security preflight check failed

## Full documentation
- Quick Start: https://agentswallets.com/docs/quickstart
- Commands: https://agentswallets.com/docs/commands
- Agent Integration: https://agentswallets.com/docs/agent-integration
- Security: https://agentswallets.com/docs/security
- Policy Engine: https://agentswallets.com/docs/policy
- Error Reference: https://agentswallets.com/docs/errors
- DeFi & Trading: https://agentswallets.com/docs/defi
- Perpetual Contracts: https://agentswallets.com/docs/perpetuals
- Examples: https://agentswallets.com/docs/examples
- Full docs (single file): https://agentswallets.com/llms-full.txt