# Key Management

## How Keys Are Stored

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.

## What the Agent Can and Cannot Do

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.

## Password Resolution

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.

## Multi-Chain Key Derivation

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

## Password Requirements

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](/developer/agent-sdk/cli-reference.md) for the full `wallet create` command.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.trustwallet.com/developer/agent-sdk/key-management.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.