WalletSuite uses the Open Wallet Standard (OWS) for local key management. Keys are generated, stored, and used entirely on the host where the agent runtime executes. WalletSuite never receives or transmits private key material.
OWS Vault
| Property | Detail |
|---|
| Location | ~/.ows (configurable via OWS_VAULT_PATH) |
| Encryption | AES-256-GCM |
| Key derivation | BIP-39 mnemonic → BIP-44 hierarchical deterministic paths |
| Supported signing chains | Ethereum (eip155:1), Tron (tron:mainnet) |
| Read/prepare chains | See supported chains (signing not required for queries) |
Two Access Modes
Owner Mode
Direct control of the vault using a passphrase.
| Setting | Value |
|---|
OWS_AUTH_MODE | owner |
OWS_PASSPHRASE | Your vault passphrase |
Agent Mode
Delegated control using a pre-created scoped token.
| Setting | Value |
|---|
OWS_AUTH_MODE | agent |
OWS_AGENT_TOKEN | Token from create_agent_api_key |
Key Lifecycle
1. Create
create_wallet (owner mode) generates a BIP-39 mnemonic, derives addresses for all supported signing chains, and stores the key material encrypted in the vault.
- The mnemonic is displayed once during creation — it is never stored in plaintext or returned again.
- Derived addresses are returned in the response so you know where to send funds.
- Default derivation path:
m/44'/60'/0'/0/0 (Ethereum), chain-specific paths for other networks.
2. Use
sign_transaction decrypts the key from the vault, signs the provided unsigned transaction hex, and returns the signature.
- Key material exists in memory only during the signing operation.
- After signing, the decrypted key is wiped from memory.
- The MCP server receives only the signature — never the key.
3. Delegate
create_agent_api_key (owner mode) creates a scoped token bound to a specific wallet and optional policy.
- The token is written to a local file with mode
0600 (owner-readable only).
- The token is never returned in chat or logged.
- Restart the MCP server in agent mode with
OWS_AGENT_TOKEN sourced from that file.
4. Revoke
Delete the agent token file. The agent can no longer sign. The wallet and keys remain in the vault — only the delegation is removed.
What the MCP Server Never Sees
| Secret | Where It Lives | MCP Server Access |
|---|
| Private keys | OWS vault (encrypted) | Never |
| Mnemonics | Shown once at creation | Never stored, never returned |
| Passphrases | Environment variable | Read once at startup, never logged |
| Agent tokens | Environment variable | Read once at startup, never logged |
Encryption Details
| Layer | Algorithm | Purpose |
|---|
| Vault encryption | AES-256-GCM | Encrypt key material at rest |
| Agent key wrapping | HKDF-SHA256 → AES-256-GCM | Re-encrypt the wallet secret under a key derived from the agent token — the token is both authentication credential and decryption capability |
| Key derivation | BIP-39 → BIP-44 | Deterministic address generation from mnemonic |
| Signing | secp256k1 ECDSA (Ethereum), chain-specific (Tron) | Transaction signature |
| Memory protection | Zeroize on drop | Wipe key material from memory after use |
Token-as-capability
When an owner mints an agent API key, OWS decrypts the wallet secret with the owner passphrase and re-encrypts it under a fresh AES-256-GCM key derived via HKDF-SHA256 from the agent token itself. The encrypted copy is stored with the API key record; the raw token is written only to the operator’s token file (mode 0600). At runtime, the agent presents the token and OWS re-derives the decryption key — the token functions as both authentication credential and decryption capability. Revoking a single token invalidates only that wrapped copy; disk access alone cannot decrypt without the token, and the token alone cannot decrypt without disk access.
Backup
Back up the OWS vault directory (~/.ows or your custom OWS_VAULT_PATH). The vault contains the encrypted key material — without it, keys cannot be recovered.
The vault is encrypted, so a backup is safe to store in a secure location. The passphrase is required to decrypt it.
If you lose both the vault and the mnemonic, the keys are permanently lost. There is no recovery path. Back up your vault and store your mnemonic securely.
