Agent Wallet

Agent Wallet Skill

CRITICAL: Never handle private keys or mnemonics directly. All cryptographic operations go through the CLI. Never read keystore files, parse private keys, or expose mnemonics in conversation — use CLI commands for everything.

This skill is sign-only — transaction building and broadcasting are out of scope.

Installation

Run agent-wallet --help to check if the CLI is already installed. If the command is not found, ask the user: stable or beta version?

# Node.js — stable
npm install -g @bankofai/agent-wallet

# Node.js — beta
npm install -g @bankofai/agent-wallet@beta

Interaction Workflow

Follow this 4-step pattern for every user request:

Step 1 — Check current state, then understand intent

Always run agent-wallet list first to see existing wallets and active wallet. Never assume it's a first-time setup.

• No wallets exist → first present the wallet type options with descriptions (do not skip this), then ask the user to choose. Present as:
  • local_secure — private key encrypted locally with a master password. Recommended for production.
  • privy — uses Privy hosted wallet via API credentials (App ID + App Secret + Privy Wallet ID). No private key stored locally.
  • (raw_secret is disabled — user must configure manually, agent cannot set it up)
• Wallets already exist → use add instead of start; do NOT re-run start (it will error unless --override is passed)

Step 2 — Look up the command (MANDATORY, no exceptions)

Run agent-wallet <command> --help BEFORE executing. Do not skip this step even if you think you know the flags.

agent-wallet start --help        # always run first
agent-wallet start local_secure --help   # then subcommand help if applicable

Step 3 — Ask once, ask everything

In a single message, collect all required information. Always include these privacy-sensitive choices with explanation:

• --save-runtime-secrets: saves password unencrypted to ~/.agent-wallet/runtime_secrets.json. Convenient on personal machines; avoid on shared environments.
• --dir: custom secrets directory. Ask only if user may have a non-default setup.

Step 4 — Execute

Use the user's answers to construct one complete command with all flags. Never run partial commands expecting to be prompted.

Restricted Operations

remove, reset, and change-password are agent-restricted — the agent must NOT execute these commands. Misuse can cause permanent, unrecoverable loss of wallet access (private keys cannot be restored).

When the user requests one of these:

1. Explain what the operation does and that it is irreversible
2. Tell the user to run the command themselves in their terminal
3. Provide the exact command to copy-paste, but do not execute it

# Examples to show the user — do NOT run via agent
agent-wallet remove <id> --yes
agent-wallet reset --yes
agent-wallet change-password -p 'OldPass' --new-password 'NewPass'

Red Flags — Use CLI Instead

Password Resolution (first match wins)

1. Runtime secrets (~/.agent-wallet/runtime_secrets.json) ← preferred after first setup
2. AGENT_WALLET_PASSWORD env var
3. --password '<pw>' flag ← use this in agent context when runtime secrets not yet set up
4. Interactive prompt (unavailable in non-interactive contexts)

--password exposes password in the user's shell history only when the user types it manually in a terminal. When the agent runs commands via Bash tool, there is no interactive shell history. It is safe and correct for the agent to ask the user for a password in conversation and pass it via --password.

Agent Context Rules

In agent contexts stdin is not a TTY — all interactive prompts are disabled. Always pass every required flag explicitly or the command will hang/fail.

Always quote user-supplied strings to prevent shell expansion of !, $, &, *, etc. Single quotes '...' work for bash, zsh, PowerShell 7, and fish. PowerShell 5 and cmd.exe need different handling for JSON payloads — see shell-quoting.md.

agent-wallet sign tx '{"to":"0x...","chainId":1}' --network eip155:1

Commands

Run agent-wallet <command> --help for full options. See commands-reference.md for all flags.

Network Identifiers

Format: eip155:<chainId> for EVM and canonical CAIP-2 IDs for TRON: tron:0x2b6653dc (Mainnet), tron:0xcd8690dc (Nile), or tron:0x94a9059e (Shasta).

Common: eip155:1 (Ethereum), eip155:137 (Polygon), eip155:56 (BSC), eip155:42161 (Arbitrum), eip155:8453 (Base).

One wallet derives separate EVM and TRON addresses from the same key — use resolve-address to see both.

Error Handling