mirror of https://github.com/NousResearch/hermes-agent.git synced 2026-05-01 16:31:56 +08:00

Files

Shannon Sands 253c7abbe9 fix(wallet): harden keystore fallback, persist policy/history, wire gateway injection

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

2026-03-29 08:38:29 +10:00

3.3 KiB

Raw Blame History

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

pip install 'hermes-agent[wallet]'          # EVM chains
pip install 'hermes-agent[wallet-solana]'    # + Solana

Quick Start

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.

3.3 KiB Raw Blame History