v2.4.0

agent-wallet v2.4.0

New Features

Privy Wallet Support

• Added Privy-backed wallet adapter for both TypeScript (@bankofai/agent-wallet) and Python (bankofai-agent-wallet)
• Supports EVM and TRON chain types — chain type is auto-detected from Privy wallet metadata
• Implements full signing interface: sign tx, sign msg, sign typed-data
• New CLI subcommands: start privy, add privy with --app-id, --app-secret, --privy-wallet-id flags
• Rate-limit retry with exponential backoff for Privy API requests

resolve-address Command

• New command to show EVM + TRON addresses for any wallet without signing

Non-interactive change-password

• Added --new-password flag to both TypeScript and Python CLIs — fully scriptable without prompts

Password Attempt Logic Refactor

• Improved password retry flow in CLI — weak password attempts are retried with clearer error messages instead of exiting

Docs

• Added doc/how-to-add-privy-wallet.md — step-by-step guide for Privy wallet setup
• Updated doc/getting-started.md and README.md

v2.3.1

agent-wallet v2.3.1

New Features

• Windows support — CI now runs on both ubuntu-latest and windows-latest. Path handling updated to support Windows-style backslash (~\) in both TypeScript and Python.
• Strict CI smoke tests — Added end-to-end CLI smoke tests for both Python and TypeScript in CI: init → add → sign → verify expected files exist.

Fixes

• Windows chmod crash — Python's os.chmod fails on Windows; replaced with a new safe_chmod utility that warns instead of crashing (secrets remain protected by encryption).
• Path expansion on Windows — expandTilde now handles ~\ (backslash) in addition to ~/ for both resolver.ts and cli.ts.

Docs

• Updated README with improved documentation.

v2.3.0

agent-wallet v2.3.0

Breaking Changes

• Provider architecture rewrite — WalletProviderFactory / createWalletProvider has been replaced by a new two-provider system:

  • ConfigWalletProvider — file-backed encrypted wallets from wallets_config.json
  • EnvWalletProvider — fallback to AGENT_WALLET_* environment variables
  • resolveWalletProvider() / resolveWallet() — new resolver that selects the right provider automatically
  • Removed: factory.ts/py, local.ts/py, static.ts/py, base.ts/py

• Signer hierarchy restructured — Adapters split into clear responsibilities:

  • LocalSigner — base class holding private key + network delegation
  • LocalSecureSigner — decrypts from Keystore V3 via secretLoader
  • RawSecretSigner — resolves from plaintext private key or mnemonic

• Config module extracted — local/config.ts/py replaced by core/config.ts/py with WalletsTopology, WalletConfig types and loadConfig / saveConfig helpers

• ~/.agent-wallet/ config format not backward-compatible — The wallet configuration files under ~/.agent-wallet/ are not compatible with previous versions. If upgrading from an older version, run agent-wallet reset to reset your wallet directory, then re-initialize with agent-wallet start.

New Features

• Multi-wallet management — ConfigWalletProvider supports multiple wallets with addWallet, removeWallet, setActive, listWallets
• CLI double-check flow — start command now prompts for confirmation when wallets already exist, preventing accidental overwrites
• CLI UX improvements — Better interactive flows, password retry with 3 attempts, wallet type/ID prompts with defaults
• Secret loader — New loadLocalSecret / load_local_secret module for Keystore V3 decryption
• Wallet builder — New createAdapter / create_adapter factory for constructing the correct signer from wallet config
• PR audit workflow — Added audit-pr.yml GitHub Actions workflow

Fixes

• Reset command bug — Fixed wallet reset not cleaning up properly
• Import cycle — Resolved circular dependency between modules
• Prettier config — Unified formatting: single quotes, no semicolons (TypeScript)

v2.2.1

agent-wallet v2.2.1

New Features

• createWalletProvider / create_wallet_provider — New unified factory function that creates wallet providers from explicit options, supporting four modes:
  • Private key — Pass a hex private key + network directly
  • Mnemonic — Pass a BIP-39 mnemonic + network (+ optional account index)
  • Local (password) — Pass a password to use encrypted keystore
  • Env fallback — No explicit credentials, resolves from AGENT_WALLET_* environment variables (same behavior as resolveWalletProvider)

v2.2.0

agent-wallet v2.2.0

New Features

Core

Multi-Chain Wallet Support

• EVM-compatible chains — Ethereum, BSC, Polygon, Base, Arbitrum, and any EVM chain
• TRON — Full transaction and message signing via secp256k1

Signing-Only Design

• Pure local signing; no network calls, no RPC dependencies
• Caller builds and broadcasts transactions; SDK handles signing only
• signTransaction, signMessage, signRaw, signTypedData via unified BaseWallet interface

Mnemonic & HD Wallet Support

• Derive wallets from BIP-39 mnemonic phrases via AGENT_WALLET_MNEMONIC
• Configurable account index via AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX
• EVM derivation path: m/44'/60'/0'/0/{index}
• TRON derivation path: m/44'/195'/0'/0/{index}

CAIP-2 Network Identifier

• resolveWalletProvider({ network }) accepts CAIP-2 strings: eip155, eip155:1, tron, tron:nile
• Network parameter required for private key / mnemonic mode to determine chain type

Dual-Language SDK with Cross-Compatibility

• Python and TypeScript SDKs with identical API surface
• Same keystore format — files created by Python can be read by TypeScript and vice versa
• Same private key + same data = same signature, regardless of language

Dual ESM + CJS Build (TypeScript)

• TypeScript SDK ships both ESM (dist/index.js) and CJS (dist/index.cjs) bundles
• Full exports map with import, require, and types conditions
• Compatible with both import and require() consumers out of the box

EIP-712 Typed Data Signing

• Full structured data signing support (x402, Permit2, Uniswap, etc.)
• Available on both EVM and TRON wallets

Security

Keystore V3 Encryption

• Private keys encrypted at rest with scrypt (N=262144, r=8, p=1) + AES-128-CTR
• Keccak256 MAC verification for integrity checking
• Password discarded from memory after provider initialization

Password Strength Enforcement

• Minimum 8 characters, requiring uppercase, lowercase, digit, and special character
• Auto-generation of secure 16-character passwords when not provided

File-Level Security

• Directory permissions set to 0o700 (owner only)
• Encrypted files: master.json (sentinel), id_*.json (private keys), cred_*.json (credentials)
• No private keys ever transmitted over the network in local mode

CLI

Quick Start Command (start)

• One command to initialize wallet storage, set password, and create default wallets
• agent-wallet start — auto-generates password + creates default EVM and TRON wallets
• agent-wallet start -p <password> -i tron — custom password + import private key
• Idempotent: running again verifies password and shows existing wallets

Full Wallet Management

• init — Initialize secrets directory and set master password
• add — Add wallet with interactive prompts (key generation or import)
• list — List all wallets with type and address in table format
• use <id> — Set active wallet (default for signing commands)
• inspect <id> — Show wallet details
• remove <id> — Remove wallet and associated encrypted files

Signing Commands (Positional Arguments)

• sign msg <message> — Sign arbitrary message
• sign tx <payload> — Sign transaction (JSON)
• sign typed-data <data> — Sign EIP-712 typed data (JSON)

Password & Data Management

• change-password — Re-encrypts all wallet files with new password
• reset — Delete all wallet data with double confirmation (-y to skip)

Environment Variable Support

• AGENT_WALLET_PASSWORD — Master password (skips CLI prompt)
• AGENT_WALLET_DIR — Custom secrets directory path
• AGENT_WALLET_PRIVATE_KEY — Private key hex for static wallet mode
• AGENT_WALLET_MNEMONIC — BIP-39 mnemonic for HD wallet derivation
• AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX — HD derivation account index (default: 0)
• Password priority: -p flag > env var > interactive prompt > auto-generate

Global Options

• -p/--password — Pass password inline (all commands that require authentication)
• -d/--dir — Custom secrets directory
• -w/--wallet — Specify wallet for signing (overrides active wallet)
• -y/--yes — Skip confirmation prompts (remove, reset)

SDK

Wallet Providers

• resolveWalletProvider({ network }) / resolve_wallet_provider(network) — Environment-driven factory; auto-selects LocalWalletProvider or StaticWalletProvider based on env vars
• new LocalWalletProvider(secretsDir, password) — File-backed multi-wallet provider
• new StaticWalletProvider(wallet) — Single-wallet provider for private key / mnemonic mode

LocalWalletProvider Interface

• listWallets() / list_wallets() — List all configured wallets
• getWallet(id) / get_wallet(id) — Get wallet instance by ID
• getActiveWallet() / get_active_wallet() — Get active wallet
• setActive(id) / set_active(id) — Set active wallet

WalletProvider (abstract base)

• getActiveWallet() / get_active_wallet() — Get active wallet (implemented by all providers)

BaseWallet Interface

• getAddress() / get_address() — Returns wallet address
• signTransaction(payload) / sign_transaction(payload) — Sign transaction
• signMessage(msg) / sign_message(msg) — Sign arbitrary message
• signTypedData(data) / sign_typed_data(data) — Sign EIP-712 typed data
• signRaw(raw) / sign_raw(raw) — Sign pre-serialized raw bytes

Error Handling

• WalletError, WalletNotFoundError, DecryptionError, SigningError, NetworkError, UnsupportedOperationError
• Helpful guidance messages (e.g., "Wallet not initialized. Run 'agent-wallet init' first.")

v2.2.0-beta

agent-wallet v2.2.0-beta

New Features

Core

Multi-Chain Wallet Support

• EVM-compatible chains — Ethereum, BSC, Polygon, Base, Arbitrum, and any EVM chain
• TRON — Full transaction and message signing via secp256k1

Signing-Only Design

• Pure local signing; no network calls, no RPC dependencies
• Caller builds and broadcasts transactions; SDK handles signing only
• signTransaction, signMessage, signRaw, signTypedData via unified BaseWallet interface

Mnemonic & HD Wallet Support

• Derive wallets from BIP-39 mnemonic phrases via AGENT_WALLET_MNEMONIC
• Configurable account index via AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX
• EVM derivation path: m/44'/60'/0'/0/{index}
• TRON derivation path: m/44'/195'/0'/0/{index}

CAIP-2 Network Identifier

• resolveWalletProvider({ network }) accepts CAIP-2 strings: eip155, eip155:1, tron, tron:nile
• Network parameter required for private key / mnemonic mode to determine chain type

Dual-Language SDK with Cross-Compatibility

• Python and TypeScript SDKs with identical API surface
• Same keystore format — files created by Python can be read by TypeScript and vice versa
• Same private key + same data = same signature, regardless of language

Dual ESM + CJS Build (TypeScript)

• TypeScript SDK ships both ESM (dist/index.js) and CJS (dist/index.cjs) bundles
• Full exports map with import, require, and types conditions
• Compatible with both import and require() consumers out of the box

EIP-712 Typed Data Signing

• Full structured data signing support (x402, Permit2, Uniswap, etc.)
• Available on both EVM and TRON wallets

Security

Keystore V3 Encryption

• Private keys encrypted at rest with scrypt (N=262144, r=8, p=1) + AES-128-CTR
• Keccak256 MAC verification for integrity checking
• Password discarded from memory after provider initialization

Password Strength Enforcement

• Minimum 8 characters, requiring uppercase, lowercase, digit, and special character
• Auto-generation of secure 16-character passwords when not provided

File-Level Security

• Directory permissions set to 0o700 (owner only)
• Encrypted files: master.json (sentinel), id_*.json (private keys), cred_*.json (credentials)
• No private keys ever transmitted over the network in local mode

CLI

Quick Start Command (start)

• One command to initialize wallet storage, set password, and create default wallets
• agent-wallet start — auto-generates password + creates default EVM and TRON wallets
• agent-wallet start -p <password> -i tron — custom password + import private key
• Idempotent: running again verifies password and shows existing wallets

Full Wallet Management

• init — Initialize secrets directory and set master password
• add — Add wallet with interactive prompts (key generation or import)
• list — List all wallets with type and address in table format
• use <id> — Set active wallet (default for signing commands)
• inspect <id> — Show wallet details
• remove <id> — Remove wallet and associated encrypted files

Signing Commands (Positional Arguments)

• sign msg <message> — Sign arbitrary message
• sign tx <payload> — Sign transaction (JSON)
• sign typed-data <data> — Sign EIP-712 typed data (JSON)

Password & Data Management

• change-password — Re-encrypts all wallet files with new password
• reset — Delete all wallet data with double confirmation (-y to skip)

Environment Variable Support

• AGENT_WALLET_PASSWORD — Master password (skips CLI prompt)
• AGENT_WALLET_DIR — Custom secrets directory path
• AGENT_WALLET_PRIVATE_KEY — Private key hex for static wallet mode
• AGENT_WALLET_MNEMONIC — BIP-39 mnemonic for HD wallet derivation
• AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX — HD derivation account index (default: 0)
• Password priority: -p flag > env var > interactive prompt > auto-generate

Global Options

• -p/--password — Pass password inline (all commands that require authentication)
• -d/--dir — Custom secrets directory
• -w/--wallet — Specify wallet for signing (overrides active wallet)
• -y/--yes — Skip confirmation prompts (remove, reset)

SDK

Wallet Providers

• resolveWalletProvider({ network }) / resolve_wallet_provider(network) — Environment-driven factory; auto-selects LocalWalletProvider or StaticWalletProvider based on env vars
• new LocalWalletProvider(secretsDir, password) — File-backed multi-wallet provider
• new StaticWalletProvider(wallet) — Single-wallet provider for private key / mnemonic mode

LocalWalletProvider Interface

• listWallets() / list_wallets() — List all configured wallets
• getWallet(id) / get_wallet(id) — Get wallet instance by ID
• getActiveWallet() / get_active_wallet() — Get active wallet
• setActive(id) / set_active(id) — Set active wallet

WalletProvider (abstract base)

• getActiveWallet() / get_active_wallet() — Get active wallet (implemented by all providers)

BaseWallet Interface

• getAddress() / get_address() — Returns wallet address
• signTransaction(payload) / sign_transaction(payload) — Sign transaction
• signMessage(msg) / sign_message(msg) — Sign arbitrary message
• signTypedData(data) / sign_typed_data(data) — Sign EIP-712 typed data
• signRaw(raw) / sign_raw(raw) — Sign pre-serialized raw bytes

Error Handling

• WalletError, WalletNotFoundError, DecryptionError, SigningError, NetworkError, UnsupportedOperationError
• Helpful guidance messages (e.g., "Wallet not initialized. Run 'agent-wallet init' first.")