agent-wallet-cli

A cross-platform TypeScript CLI wallet for Ethereum and Solana, designed for AI agent integration.

Risks & Security Warnings

Read this section before using agent-wallet-cli.

Experimental software. This tool is provided as-is with no warranty. Use at your own risk.
Do not use on mainnet with significant funds without reading and understanding the source code.
Mnemonic is displayed once on init. Secure your terminal — anyone who sees it controls your funds.
Session tokens grant access to funds. Treat them like passwords. Never log or share them.
JavaScript cannot guarantee secrets are purged from memory. Buffers are zeroed on a best-effort basis, but the V8 garbage collector may retain copies.
argon2 requires native bindings (C compiler toolchain). It will not work in all environments (e.g., some Docker images, serverless runtimes).
Public RPCs may be rate-limited or unreliable. Configure your own RPC endpoints for production use.
No security audit has been performed on this code.

Features

Multi-chain: Ethereum (+ Polygon, Arbitrum, Base) and Solana
BIP-39 HD wallet: 12 or 24-word mnemonic, multiple account indices
ERC-20 & SPL tokens: balance, transfer, approve, transferFrom, allowance
Gasless relay: Automatic fallback for ERC-20 transfers when wallet has no ETH for gas (EIP-3009 authorization)
Strong encryption: Argon2id key derivation + AES-256-GCM
Session tokens: Time-limited unlock (default 1h, max 24h) so agents don't need your password
Message signing: Plain text, EIP-712 typed data, raw bytes
Transaction history: Recent transactions with explorer links
Approval discovery: Scan recent ERC-20 Approval events
x402 payments: Automatic HTTP 402 stablecoin payments via EIP-3009 TransferWithAuthorization (no gas required)
JSON-first output: Machine-readable by default, human-readable --format text option
Token aliases: Use usdc instead of 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48

Quick Start

# Create a new wallet
npx agent-wallet-cli init --password "my-secure-password"

# Unlock (creates a session token valid for 1 hour)
npx agent-wallet-cli unlock --password "my-secure-password"

# Check balance
npx agent-wallet-cli balance --token wlt_... --chain ethereum --network mainnet

# Send ETH
npx agent-wallet-cli send --token wlt_... --chain ethereum --to 0x... --amount 0.01

# Lock when done
npx agent-wallet-cli lock

Installation

npx (no install)

npx agent-wallet-cli <command> [options]

npm global install

npm install -g agent-wallet-cli
agent-wallet-cli <command> [options]

From source

git clone https://github.com/bvnk/agent-wallet-cli.git
cd agent-wallet-cli
npm install
npm run build
node dist/index.js <command> [options]

Commands Reference

Global Options

All commands accept these options:

Flag	Description	Default
`--format <format>`	Output format (`json` or `text`)	`json`
`--wallet-dir <path>`	Wallet storage directory	`~/.agent-wallet-cli`
`--quiet`	Suppress output

Wallet Management

Command	Description	Key Flags
`init`	Create a new wallet	`--password` (required), `--word-count 12\|24`, `--name`
`import`	Import from mnemonic	`--password` (required), `--mnemonic` (required), `--name`
`unlock`	Create session token	`--password` (required), `--duration <seconds>`, `--name`
`lock`	Revoke session token	`--name`
`export`	Export mnemonic phrase	`--password` (required), `--confirm` (required), `--name`

Addresses & Balances

Command	Description	Key Flags
`address`	Show wallet addresses	`--token`, `--chain`, `--account-index`, `--name`
`balance`	Query native or token balance	`--token`, `--chain` (required), `--network`, `--token-address`, `--account-index`

Transfers & Approvals

Command	Description	Key Flags
`send`	Transfer native coin or token	`--token`, `--chain` (required), `--to` (required), `--amount` (required), `--token-address`, `--dry-run`, `--no-relay`
`approve`	Approve ERC-20/SPL spender	`--token`, `--chain` (required), `--token-address` (required), `--spender` (required), `--amount` (required)
`allowance`	Query approval amount	`--chain` (required), `--token-address` (required), `--owner` (required), `--spender` (required)
`transfer-from`	Delegated transfer	`--token`, `--chain` (required), `--token-address` (required), `--from` (required), `--to` (required), `--amount` (required)
`approvals`	Discover ERC-20 approvals	`--token`, `--chain`, `--network`, `--limit`

x402 Payments

Command	Description	Key Flags
`x402`	HTTP request with automatic payment	`<url>`, `--token`, `--method`, `--header`, `--body`, `--dry-run`, `--yes`, `--max-amount`

History & Signing

Command	Description	Key Flags
`history`	List recent transactions	`--token`, `--chain` (required), `--network`, `--limit`
`sign`	Sign message or data	`--token`, `--chain` (required), `--message` / `--typed-data` / `--data`

Network Configuration

Command	Description	Key Flags
`networks`	List or configure RPCs	`--set <chain:network>`, `--rpc-url <url>`, `--reset <chain:network>`

AI Agent Integration

Install as Claude Code Skill

Install the agent-wallet-cli skill so Claude Code (or any Agent Skills-compatible tool) knows how to use the wallet:

# Project-scoped (writes to .claude/skills/ in current directory)
npx agent-wallet-cli install-skill

# User-wide (writes to ~/.claude/skills/)
npx agent-wallet-cli install-skill --global

Or use the universal Agent Skills installer:

npx skills add bvnk/agent-wallet-cli

Using with OpenClaw

Option A: AgentSkill (recommended)

Create a skill file that teaches the agent how to use agent-wallet-cli. Place this as wallet.md in your OpenClaw skills directory:

# Wallet Management Skill

You have access to `agent-wallet-cli`, a CLI wallet for Ethereum and Solana.

## Setup

The wallet is already initialized. To use it, first unlock with:
\`\`\`bash
agent-wallet-cli unlock --password "$WALLET_PASSWORD" --format json
\`\`\`
Save the `token` field from the JSON response. Pass it to all subsequent commands with `--token <token>`.

## Check Balance

\`\`\`bash
agent-wallet-cli balance --token <token> --chain ethereum --network mainnet --format json
\`\`\`

For ERC-20 tokens, add `--token-address <alias-or-address>`:
\`\`\`bash
agent-wallet-cli balance --token <token> --chain ethereum --network base --token-address usdc --format json
\`\`\`

## Send Funds

\`\`\`bash
agent-wallet-cli send --token <token> --chain ethereum --to <address> --amount <amount> --format json
\`\`\`

For tokens:
\`\`\`bash
agent-wallet-cli send --token <token> --chain ethereum --token-address usdc --to <address> --amount <amount> --format json
\`\`\`

Use `--dry-run` to simulate before sending.

Token transfers automatically use a gasless relay when the wallet has no ETH for gas.
The relay fee (e.g. 0.01 USDC) is deducted from the token amount. Check for `"relay_used": true` in the response.
To disable: add `--no-relay` to the send command.

## Show Addresses

\`\`\`bash
agent-wallet-cli address --token <token> --format json
\`\`\`

## Lock When Done

\`\`\`bash
agent-wallet-cli lock
\`\`\`

## Supported Token Aliases

Ethereum mainnet: usdc, usdt, dai, weth, wbtc
Base: usdc
Polygon: usdc, usdt
Arbitrum: usdc, usdt
Solana mainnet: usdc, usdt

## Important

- Always use `--format json` and parse the JSON response.
- Check `"ok": true` in the response before proceeding.
- Never send more than instructed. Always confirm amounts with the user first.
- Use `--dry-run` for sends when uncertain.

Reference it in your openclaw.json:

{
  "skills": [
    {
      "name": "wallet",
      "file": "skills/wallet.md"
    }
  ]
}

Option B: Shell execution

OpenClaw agents with shell access can invoke agent-wallet-cli directly. Add instructions to your agent's system prompt:

You can manage crypto wallets using the `agent-wallet-cli` command.
All commands return JSON with an "ok" field. Always check "ok": true before proceeding.
First unlock the wallet: agent-wallet-cli unlock --password "$WALLET_PASSWORD" --format json
Then use the returned token for subsequent commands.

Using with Other AI Agents

agent-wallet-cli is designed for programmatic use:

JSON output — all commands return structured JSON by default:

{
  "ok": true,
  "balance": "1.5",
  "symbol": "ETH"
}

Session token pattern — unlock once, reuse the token:

# Unlock and capture token
TOKEN=$(agent-wallet-cli unlock --password "pass" --format json | jq -r '.token')

# Use token for subsequent commands
agent-wallet-cli balance --token "$TOKEN" --chain ethereum --format json
agent-wallet-cli send --token "$TOKEN" --chain ethereum --to 0x... --amount 0.01

Environment variable — set AGENT_WALLET_CLI_TOKEN to avoid passing --token every time:

export AGENT_WALLET_CLI_TOKEN=$(agent-wallet-cli unlock --password "pass" --format json | jq -r '.token')
agent-wallet-cli balance --chain ethereum
agent-wallet-cli send --chain ethereum --to 0x... --amount 0.01

Gasless Relay

When an EVM wallet has no native tokens (ETH/MATIC/etc.) for gas, ERC-20 token transfers normally fail. The gasless relay solves this using EIP-3009 authorization signatures — the user signs a ReceiveWithAuthorization off-chain, a relayer submits the transaction on-chain, and the relay fee is deducted from the token amount itself (in USDC, not ETH).

How It Works

The CLI detects that your wallet has insufficient native balance for gas
It gets a fee quote from the relay API
You sign an EIP-3009 authorization (off-chain, no gas required)
The relay submits the transaction on-chain and pays gas on your behalf
The relay fee is deducted from your token transfer (e.g., 0.01 USDC)

Supported Chains

Chain	Chain ID
Ethereum	1
Base	8453
Sepolia	11155111
Base Sepolia	84532

Supported Tokens

EIP-3009 compatible tokens — primarily USDC.

Example

# Wallet has 20 USDC but 0 ETH — relay kicks in automatically
agent-wallet-cli send --token wlt_... --chain ethereum --network base-sepolia \
  --token-address usdc --to 0x... --amount 2

# Output includes relay metadata:
# {
#   "ok": true,
#   "tx_hash": "0xead7d546...",
#   "chain": "ethereum",
#   "network": "base-sepolia",
#   "dry_run": false,
#   "explorer_url": "https://sepolia.basescan.org/tx/0xead7d546...",
#   "relay_used": true,
#   "relay_request_id": "req_ea1385df2c2e",
#   "relay_fee": "0.01",
#   "relay_fee_symbol": "USDC",
#   "amount_received": "2"
# }

Disabling the Relay

# Per-command: use --no-relay flag
agent-wallet-cli send --no-relay --token wlt_... --chain ethereum --to 0x... --amount 2 --token-address usdc

# Via environment variable
export AGENT_WALLET_CLI_RELAY_ENABLED=false

# Via config.json
# Add to ~/.agent-wallet-cli/config.json:
# { "relay": { "enabled": false } }

If the wallet has sufficient native balance for gas, the standard transfer path is used regardless of relay settings.

x402 Payments (HTTP 402)

x402 is an open HTTP payment protocol that uses the 402 Payment Required status code for automatic stablecoin payments. When a server returns 402, the CLI signs a gasless EIP-3009 TransferWithAuthorization, retries the request with the payment signature, and the facilitator settles on-chain.

How It Works

The CLI makes an HTTP request to the target URL
If the server returns 402 with payment requirements, the CLI parses them
It selects a compatible EVM payment option (scheme exact, supported chain)
Signs an EIP-3009 TransferWithAuthorization (no gas required — facilitator pays gas)
Retries the request with the PAYMENT-SIGNATURE header
Returns the response along with settlement details (tx hash, network)

Example

# Preview payment requirements (no payment)
agent-wallet-cli x402 https://x402stt.dtelecom.org/v1/session \
  --token wlt_... --method POST \
  --header "Content-Type:application/json" \
  --body '{"minutes":5}' --dry-run

# Make the payment
agent-wallet-cli x402 https://x402stt.dtelecom.org/v1/session \
  --token wlt_... --method POST \
  --header "Content-Type:application/json" \
  --body '{"minutes":5}' --yes --max-amount 0.05

Options

Flag	Description	Default
`--method <method>`	HTTP method	`GET`
`--header <header...>`	HTTP headers (`Key:Value`, repeatable)
`--body <body>`	Request body (`@filepath` to read from file)
`--dry-run`	Show payment requirements without paying
`--yes`	Skip payment confirmation prompt
`--max-amount <amount>`	Max payment in human-readable units (e.g. `0.10`)
`--account-index <n>`	Account index	`0`

Supported Networks

x402 payments work on any EVM chain configured in the wallet:

Chain	CAIP-2 ID	Asset
Ethereum	`eip155:1`	USDC
Base	`eip155:8453`	USDC
Base Sepolia	`eip155:84532`	USDC
Polygon	`eip155:137`	USDC
Arbitrum	`eip155:42161`	USDC

Supported Networks

Ethereum

Network	Chain ID	RPC	Explorer
mainnet	1	https://eth.llamarpc.com	https://etherscan.io
sepolia	11155111	https://rpc.sepolia.org	https://sepolia.etherscan.io
polygon	137	https://polygon-rpc.com	https://polygonscan.com
arbitrum	42161	https://arb1.arbitrum.io/rpc	https://arbiscan.io
base	8453	https://mainnet.base.org	https://basescan.org
base-sepolia	84532	https://sepolia.base.org	https://sepolia.basescan.org

Solana

Warning: Solana support is not heavily tested. Use at your own risk.

Network	RPC	Explorer
mainnet	https://api.mainnet-beta.solana.com	https://explorer.solana.com
devnet	https://api.devnet.solana.com	https://explorer.solana.com

Security Model

Keystore Encryption

Wallets are encrypted at rest using a two-layer scheme:

Key derivation: Argon2id (time_cost=3, memory_cost=64 MB, parallelism=4) derives a 32-byte key from your password + random salt
Encryption: AES-256-GCM encrypts the mnemonic with a random 12-byte IV and produces a 16-byte authentication tag

Keystore files are stored in ~/.agent-wallet-cli/keystores/ with 0600 permissions.

Session Tokens

When you unlock, the CLI:

Decrypts the mnemonic with your password
Re-encrypts it with a random session key (via HKDF-SHA256)
Returns a token (wlt_ prefix) containing token ID + token secret
Validates tokens using HMAC-SHA256

Tokens expire after the configured duration (default 1 hour, max 24 hours). Session files are stored with 0600 permissions.

Memory Clearing

All sensitive buffers (mnemonic bytes, derived keys, decrypted material) are zeroed after use via try/finally blocks. This is best-effort — the JavaScript runtime cannot guarantee that the garbage collector hasn't copied the data.

File Permissions

Keystore files: 0600 (owner read/write only)
Session files: 0600
Wallet directories: 0700 (owner only)

Token Aliases

Use token names instead of contract addresses:

Ethereum

Alias	Mainnet	Polygon	Arbitrum	Base	Base Sepolia
`usdc`	`0xA0b8...eB48`	`0x3c49...3359`	`0xaf88...5831`	`0x8335...2913`	`0x036C...cF7e`
`usdt`	`0xdAC1...1ec7`	`0xc213...8e8F`	`0xFd08...cbb9`	—	—
`dai`	`0x6B17...1d0F`	—	—	—	—
`weth`	`0xC02a...6Cc2`	—	—	—	—
`wbtc`	`0x2260...C599`	—	—	—	—

Solana

Alias	Mainnet	Devnet
`usdc`	`EPjFW...Dt1v`	`4zMMC...ncDU`
`usdt`	`Es9vM...wNYB`	—

Configuration

Custom RPC Endpoints

# Set a custom RPC
agent-wallet-cli networks --set ethereum:mainnet --rpc-url https://your-rpc.example.com

# Reset to default
agent-wallet-cli networks --reset ethereum:mainnet

# List all configured networks
agent-wallet-cli networks

Environment Variables

Variable	Description
`AGENT_WALLET_CLI_TOKEN`	Session token (avoids `--token` flag on every command)
`AGENT_WALLET_CLI_RELAY_ENABLED`	Enable/disable gasless relay (`true`/`false`, default `true`)
`AGENT_WALLET_CLI_RELAY_API_URL`	Custom relay API endpoint

Development

Build from source

git clone https://github.com/bvnk/agent-wallet-cli.git
cd agent-wallet-cli
npm install
npm run build

Run tests

npm test

Project structure

src/
  index.ts          # CLI entry point (Commander.js)
  commands/         # Command implementations (one file per command)
  chains/           # Chain adapters (Ethereum via viem, Solana via @solana/web3.js)
  relay/            # Gasless relay (API client, EIP-3009 authorization signing, orchestrator)
  x402/             # x402 HTTP payment protocol (EIP-3009 signing, header parsing)
  core/             # Keystore, session management, mnemonic derivation, config
  security/         # Encryption (Argon2id + AES-256-GCM), memory clearing, file permissions
  output/           # JSON/text formatters, error codes
tests/
  unit/             # Unit tests for encryption, keystore, mnemonic, memory, session, config, relay
  integration/      # End-to-end CLI flow tests

License

MIT — see LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
skills/agent-wallet-cli		skills/agent-wallet-cli
src		src
tests		tests
.gitignore		.gitignore
.npmignore		.npmignore
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

License

bvnk/agent-wallet-cli

Folders and files

Latest commit

History

Repository files navigation

agent-wallet-cli

Risks & Security Warnings

Features

Quick Start

Installation

npx (no install)

npm global install

From source

Commands Reference

Global Options

Wallet Management

Addresses & Balances

Transfers & Approvals

x402 Payments

History & Signing

Network Configuration

AI Agent Integration

Install as Claude Code Skill

Using with OpenClaw

Option A: AgentSkill (recommended)

Option B: Shell execution

Using with Other AI Agents

Gasless Relay

How It Works

Supported Chains

Supported Tokens

Example

Disabling the Relay

x402 Payments (HTTP 402)

How It Works

Example

Options

Supported Networks

Supported Networks

Ethereum

Solana

Security Model

Keystore Encryption

Session Tokens

Memory Clearing

File Permissions

Token Aliases

Ethereum

Solana

Configuration

Custom RPC Endpoints

Environment Variables

Development

Build from source

Run tests

Project structure

License

About

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

Packages