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

Thought	Correct action
"Let me read wallets_config.json"	agent-wallet list
"I can derive the address from the key"	agent-wallet resolve-address <id>
"User should run the command themselves since I need a password"	Ask user for password in conversation, then use --password '<pw>' in the Bash command — agent Bash execution does not write to shell history
"Let me build the transaction first"	Out of scope — request payload from user
"User wants to import a key/mnemonic"	Tell user to run add --private-key / add --mnemonic themselves in terminal — never pass key material through this conversation
"I already know the flags, I'll skip --help"	Always run --help first. Non-interactive errors happen when subcommands or required flags are missing. --help takes 1 second and prevents failed runs.

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.

Situation	Required flags
start, add (local_secure)	--wallet-id <id> + --generate
start, add (privy)	--wallet-id <id> + --app-id + --app-secret + --privy-wallet-id
use, inspect, resolve-address	Positional <wallet-id>
sign *	--network <net>
No runtime secrets configured	--password <pw>

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.

Command	Purpose
start local_secure --wallet-id <id> --generate	First-time setup: init + create encrypted wallet
list	List all wallets and active marker
resolve-address [id]	Show EVM + TRON addresses for a wallet
inspect <id> [--show-address]	Show wallet metadata (+ addresses)
use <id>	Switch active wallet
add local_secure --wallet-id <id> --generate	Add a new encrypted wallet
sign tx '<json>' --network <net>	Sign a transaction
sign msg '<text>' --network <net>	Sign a message (EIP-191)
sign typed-data '<json>' --network <net>	Sign EIP-712 typed data (EVM only)
remove <id> --yes	❌ agent-restricted — tell user to run manually
change-password	❌ agent-restricted — tell user to run manually
reset --yes	❌ agent-restricted — tell user to run manually

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

Error	Resolution
No wallets configured	agent-wallet start --save-runtime-secrets
Password required	Re-run setup with --save-runtime-secrets
DecryptionError / wrong password	Check AGENT_WALLET_PASSWORD or runtime secrets
Already initialized	Directory already set up — skip init, proceed to add
Wallet not found: <id>	agent-wallet list to see valid IDs
Network not supported	Use eip155:<chainId> or a canonical TRON CAIP-2 ID such as tron:0x2b6653dc/tron:0xcd8690dc
Private key must be 32 bytes	Invalid key format — user-side issue, run import manually