TWAK generates and stores private keys locally on the host machine. Keys never leave the device — not to Trust Wallet servers, not to the AI model provider, not anywhere.
When the agent wallet is initialized, a BIP39 HD wallet is generated via Trust Wallet Core. The mnemonic is encrypted immediately with AES-256-GCM, using a key derived from the user's password via PBKDF2, and written to ~/.twak/wallet.json. The mnemonic is never stored in plaintext.
What's stored on disk (~/.twak/wallet.json):
| Field | Type | Description |
|---|---|---|
encryptedMnemonic |
hex string | AES-256-GCM ciphertext of the mnemonic |
iv |
hex string | Random initialization vector |
authTag |
hex string | GCM authentication tag (detects tampering) |
salt |
hex string | Random PBKDF2 salt |
createdAt |
ISO 8601 | Wallet creation timestamp |
chains |
string[] | List of supported chain keys |
No plaintext keys, no plaintext mnemonic, no password on disk.
TWAK enforces a strict boundary between read-only queries and signing operations.
Without the wallet password, the agent can:
- Query any address balance
- Search tokens and fetch prices
- Get swap quotes
- Validate addresses and check token risk
- View transaction history
The following operations require the wallet password:
- Derive or reveal wallet addresses
- Sign or send transactions
- Execute swaps
- Approve token spending (ERC-20)
- Sign messages
The AI model never has direct access to the mnemonic or private keys. It interacts through TWAK's action layer, which gates all signing operations behind password authentication.
When a signing operation is requested, TWAK tries each source in order and uses the first one available:
| Source | Notes |
|---|---|
--password flag |
Checked first. Visible in shell history — avoid in production. |
TWAK_WALLET_PASSWORD env var |
Suitable for CI/CD and containerized environments. |
| OS keychain | macOS Keychain, Linux Secret Service. Most secure option. |
If none are available, the operation fails with an authentication error.
A single wallet derives keys for 25+ supported chains using standard BIP-44 derivation paths. All key derivation and transaction signing is handled by Trust Wallet Core:
- Ethereum and other EVM-compatible chains: shared address across all EVM networks
- Bitcoin: Legacy, SegWit, and Taproot derivation paths
- Solana: Ed25519 key derivation
- Cosmos, TON, SUI, NEAR, Aptos, Tron: chain-specific derivation
Wallet creation enforces password strength:
- Minimum 8 characters
- At least one uppercase letter, one lowercase letter, and one number
These can be bypassed with --skip-password-check for test environments. See CLI Reference for the full wallet create command.