mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-05-01 16:31:56 +08:00
253c7abbe9
Addresses review findings: - Remove insecure automatic encrypted-file credential-store fallback. now only uses real OS/keyctl-backed stores, or remains unavailable. Headless users must use explicit HERMES_KEYSTORE_PASSPHRASE if desired. - Add shared wallet runtime so tools/CLI/approval use the same configured providers and persisted policy state. - Inject keystore-backed secrets into gateway/headless startup too, so migrated .env stubs don't break messaging deployments. - Persist wallet policy state (freeze, daily totals, rate-limit timestamps, cooldown timestamps) across invocations. - Persist transaction history to disk across invocations. - Make owner-approved sends execute through the same runtime/policy path and record policy state after successful approved sends. - Fix wallet export by allowing explicit CLI export reads of sealed keys via dedicated requester path () instead of generic CLI reads. - Make CLI wallet sends evaluate policy before execution and honor freeze. - Align docs with actual crypto primitive (XSalsa20-Poly1305 via SecretBox) and current policy-config scope. Validation: - 129 tests passing - freeze persistence verified manually - wallet export verified manually
84 lines
3.3 KiB
Markdown
84 lines
3.3 KiB
Markdown
# Wallet & Keystore
|
|
|
|
## Overview
|
|
|
|
Hermes Agent includes an optional crypto wallet with an encrypted keystore. The agent can hold funds, check balances, and send native tokens on Solana and EVM chains — with policy-controlled spending limits and owner approval for transactions.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
pip install 'hermes-agent[wallet]' # EVM chains
|
|
pip install 'hermes-agent[wallet-solana]' # + Solana
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
hermes keystore init # Set master passphrase
|
|
hermes wallet create --chain solana # Create wallet
|
|
hermes wallet fund # Show deposit address
|
|
hermes wallet balance # Check balance
|
|
```
|
|
|
|
Enable the `wallet` toolset in `config.yaml` or via `hermes chat -t hermes-cli,wallet`.
|
|
|
|
## Wallet CLI
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `hermes wallet create --chain <chain>` | Create a fresh user wallet |
|
|
| `hermes wallet create-agent --chain <chain>` | Create agent wallet (auto-approve within limits) |
|
|
| `hermes wallet import --chain <chain>` | Import from exported private key |
|
|
| `hermes wallet export` | Export private key for migration |
|
|
| `hermes wallet list` | List wallets + balances |
|
|
| `hermes wallet balance` | Check balance |
|
|
| `hermes wallet send <to> <amount>` | Send tokens (interactive confirmation) |
|
|
| `hermes wallet fund` | Show deposit address |
|
|
| `hermes wallet history` | Transaction history |
|
|
| `hermes wallet freeze` | Kill switch — block everything |
|
|
| `hermes wallet unfreeze` | Resume after freeze |
|
|
| `hermes wallet status` | Wallet overview |
|
|
|
|
## Keystore CLI
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `hermes keystore init` | Create encrypted keystore |
|
|
| `hermes keystore list` | List secrets (names only) |
|
|
| `hermes keystore set <name>` | Add/update a secret |
|
|
| `hermes keystore show <name>` | Decrypt and display |
|
|
| `hermes keystore delete <name>` | Remove a secret |
|
|
| `hermes keystore migrate` | Import from `.env` |
|
|
| `hermes keystore remember` | Cache passphrase in OS credential store (no insecure file fallback) |
|
|
| `hermes keystore forget` | Remove cached passphrase |
|
|
| `hermes keystore change-passphrase` | Re-encrypt everything |
|
|
| `hermes keystore audit` | Access log |
|
|
|
|
## Agent Tools
|
|
|
|
| Tool | Description |
|
|
|------|-------------|
|
|
| `wallet_list` | List wallets + balances |
|
|
| `wallet_balance` | Check specific balance |
|
|
| `wallet_address` | Get deposit address |
|
|
| `wallet_send` | Send tokens (policy-gated) |
|
|
| `wallet_estimate_gas` | Fee estimation |
|
|
| `wallet_history` | Transaction log |
|
|
| `wallet_networks` | Supported chains |
|
|
|
|
## Security
|
|
|
|
- **Encryption:** Argon2id KDF + XSalsa20-Poly1305 per-secret AEAD (libsodium SecretBox)
|
|
- **Agent never sees keys:** Private keys are `sealed` — the agent uses tools, not keys
|
|
- **Policies:** Spending limits, rate limits, daily caps, approval thresholds, recipient lists
|
|
- **User wallets:** Every transaction requires owner approval
|
|
- **Agent wallets:** Auto-approve within limits, escalate above threshold
|
|
- **Kill switch:** `hermes wallet freeze` — instant, no exceptions
|
|
|
|
## Supported Chains
|
|
|
|
**Mainnet:** Ethereum, Base, Polygon, Arbitrum, Optimism, Solana
|
|
**Testnet:** Ethereum Sepolia, Base Sepolia, Solana Devnet
|
|
|
|
Custom RPC endpoints via `wallet.rpc_endpoints` in `config.yaml`.
|