gentsWallets
Get Started

Quick Start

Install the AgentsWallets CLI and create your first wallet in under 5 minutes.

Prerequisites

  • Node.js 20+
  • C/C++ build tools — required to compile better-sqlite3 native addon
    • macOS: xcode-select --install (Xcode Command Line Tools)
    • Linux: sudo apt install build-essential (or equivalent gcc / make)
  • Python 3 — required by node-gyp

Install the CLI

Install AgentsWallets globally via npm:

npm install -g @agentswallets/cli

Verify the installation:

aw --version
# 0.5.0

Initialize

Set up the local data store. This creates ~/.agentswallets/ with an encrypted SQLite database and sets your master password.

aw init

You will be prompted to create a master password. This password encrypts all private keys at rest.

Unlock a session

Before running write operations (send, buy, sell), unlock a session. Sessions auto-renew on each successful command (sliding window), so active agents stay unlocked.

aw unlock

For non-interactive use, pass the password via environment variable:

AW_MASTER_PASSWORD='your-password' aw unlock --json
{
  "ok": true,
  "data": { "status": "unlocked", "expires_at": "2026-03-01T10:15:00Z" }
}

Create a wallet

Create a new agent wallet. A 24-word BIP-39 mnemonic is generated locally, deriving both an EVM address and a Solana address.

aw wallet create --name bot
{
  "ok": true,
  "data": {
    "name": "bot",
    "evm_address": "0x4f3A...6a1",
    "solana_address": "7xKX...9vNq",
    "key_type": "hd",
    "supported_chains": ["ethereum", "bnb", "base", "polygon", "arbitrum", "solana"],
    "hint": "Fund your wallet by sending tokens to the EVM or Solana address above."
  }
}

Wallets can be referenced by name or EVM address in subsequent commands.

Get the deposit address

Get the address to fund your wallet.

aw wallet deposit-address bot

Send tokens on your chosen chain to this address. Use --chain solana to get the Solana deposit address.

Check balance

aw wallet balance bot
{
  "ok": true,
  "data": {
    "name": "bot",
    "address": "0x4f3A...6a1",
    "chain": "Ethereum",
    "chain_id": 1,
    "balances": { "ETH": "0.05", "USDC": "100.50", "USDT": "0.00" },
    "balances_number": { "ETH": 0.05, "USDC": 100.5, "USDT": 0.0 }
  }
}

The balances field contains string values for display. The balances_number field contains numeric values for direct comparison without parsing. Use --chain to query balances on a different chain (e.g., --chain polygon).

Use --all to check balances across all wallets at once:

aw wallet balance --all

Send a transfer

Send USDC to another address. The optional --idempotency-key flag prevents duplicate transactions (auto-generated if omitted).

aw send \
  --wallet bot \
  --to 0x9f4E...3bC1 \
  --amount 1 \
  --token USDC \
  --idempotency-key k1
{
  "ok": true,
  "data": { "tx_id": "tx_abc", "tx_hash": "0xdef...", "status": "confirmed" }
}

Swap tokens

Swap ETH to USDC via the OKX DEX aggregator.

aw swap exec \
  --wallet bot \
  --from ETH \
  --to USDC \
  --amount 0.01 \
  --chain ethereum
{
  "ok": true,
  "data": {
    "tx_hash": "0xabc...",
    "from_token": "ETH",
    "to_token": "USDC",
    "from_amount": "0.01",
    "to_amount": "18.25",
    "dex": "OKX DEX Aggregator",
    "chain": "Ethereum",
    "status": "confirmed"
  }
}

Search Polymarket

Search prediction markets — no unlock required.

aw predict markets -q "bitcoin" --limit 5

Next steps