Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

7.0 KB
Raw Blame

description: >- A local, non-custodial multi-chain crypto wallet the agent can read balances from and prepare transfers with. Keys stay in the core and never cross the wire. icon: wallet

Wallet

The wallet is a basic, non-custodial multi-chain crypto wallet owned by the Rust core. It keeps one account per supported chain, all derived from a single recovery phrase. It reads balances and runs a strict prepare, confirm, execute flow for native sends and a small set of token transfers.

It is minimal on purpose: key and account management, plus the primitive on-chain operations. Higher-level DeFi (swaps, bridges, generic contract and dapp calls) lives in a separate web3 module and is not part of the wallet's agent or RPC surface.

The key point: signing and broadcast happen entirely in the core, from the decrypted recovery phrase. No private key ever leaves the device or crosses the network. This is your money, so the wallet is conservative by design.

Supported chains and token standards

Setup derives exactly one account per chain. The EVM account is reused across six networks. Only the standards below are supported for transfers. Anything else, such as swaps or arbitrary contract calls, is out of scope.

Chain Networks Native Token standard Notes
EVM Ethereum, Base, Arbitrum, Optimism, Polygon, BNB Chain ETH, BNB and others ERC-20 (BEP-20 on BNB Chain) One Evm account across all six. The network is chosen per request and defaults to Ethereum mainnet. EIP-1559 and typed-tx signing.
Bitcoin Mainnet BTC None P2WPKH (native SegWit). Rejects token transfers. Esplora REST for balance and broadcast.
Solana Mainnet or devnet (per RPC) SOL SPL ed25519 signing. Native and SPL token transfers.
Tron Mainnet TRX TRC-20 TronGrid REST for native and TRC-20 transfers.

The built-in asset catalogs include the native asset plus common stablecoins per chain, for example USDC and USDT as ERC-20 or BEP-20, USDC as SPL on Solana, and USDT as TRC-20 on Tron.

Onboarding and the recovery phrase

Setup is a single, all-or-nothing operation. It saves a consent flag, the mnemonic word count, the setup source, exactly one derived account per supported chain, and the encrypted recovery phrase. Valid BIP-39 word counts are 12, 15, 18, 21 and 24.

The recovery phrase is the only secret. The wallet stores the per-chain account addresses (safe to show) apart from the secret material. Only the encrypted phrase can rebuild private keys.

Key custody and security

The wallet is non-custodial and local. There is no server-side key escrow.

  • The recovery phrase is always encrypted at rest. The core encryption domain encrypts it before it is saved anywhere.
  • The preferred home is the OS keychain. The encrypted phrase lives there under the key wallet.mnemonic, scoped by a workspace-derived user id. The keyring consent policy gates access.
  • When the keychain is unavailable (for example on a headless machine), the encrypted phrase falls back to {workspace_dir}/state/wallet-state.json. When a keychain becomes available, any secret in that JSON is migrated into it and removed from the JSON.
  • Writes to wallet-state.json are atomic (temp file, fsync, persist) under a process-wide lock. Corrupt or invalid state files are quarantined, not trusted.
  • Chain signers decrypt the phrase in the core only when deriving a key to sign a confirmed transaction. Plaintext keys are never saved and never sent over the wire.

See OS keyring and secret storage for how secrets are stored on each platform, and Privacy and security for the broader model.

Reading balances and chain info

Read-only surfaces need no confirmation:

  • Status: onboarding state plus the safe per-chain account addresses.
  • Balances: native-asset balances per account. Only EVM balances read live today (Ethereum mainnet). BTC, Solana and Tron call their providers but fall back to a zero balance with a "provider missing" status on error.
  • Network defaults and supported assets: per-chain RPC and explorer URLs, capability flags and the built-in asset catalog.
  • Chain status: per-chain readiness and the active RPC URL.

You can override RPC endpoints per chain and network with OPENHUMAN_WALLET_RPC_* environment variables. Logs redact URLs to scheme and host.

Sending transfers: prepare, confirm, execute

Every write is a two-step, deliberate flow. The wallet never sends in one shot.

  1. Prepare (prepare_transfer) validates the amount, the destination address and (for tokens) the calldata, estimates fees, and returns a prepared quote with a quoteId. Quotes sit in an in-memory store with a 5-minute TTL, capped at 64. They are not kept across restarts.
  2. Confirm and execute (execute_prepared) needs confirmed: true and a valid quoteId. The quote is consumed atomically before broadcast, so concurrent confirmations cannot double-submit. On failure it is restored with a refreshed TTL, so you can retry.

Each quote is bound to the chat thread that prepared it. Only that owner can execute it. A quoteId leaked into a shared channel returns the same "not found" error as an unknown id, so another session cannot hijack it.

Transfers are limited to native sends and the token standards in the table above. Bitcoin rejects token transfers. Swaps, bridges and generic contract calls are not available here.

Transaction status tracking

After broadcast, three read-only tools let the agent follow a transaction by hash:

  • tx_status: lifecycle state (pending, confirmed, failed or not found).
  • tx_receipt: receipt details (success, fee, block).
  • lookup_tx: the raw transaction payload.

Agent tools and approval safety

The agent reaches the wallet through six tools:

Tool Purpose
wallet_status Onboarding status and account addresses.
wallet_chain_status Per-chain readiness and active RPC.
wallet_prepare_transfer Build a validated, fee-estimated quote.
wallet_tx_status Transaction lifecycle state by hash.
wallet_tx_receipt Transaction receipt by hash.
wallet_lookup_tx Raw transaction lookup by hash.

No agent tool executes a transfer. The agent can prepare a quote, but moving funds (execute_prepared) goes through the RPC surface, where it must be explicitly confirmed and pass the owner-binding check. Together with prepare-then-confirm and per-thread quote binding, this keeps the agent from spending funds silently.

A quote is bound to the conversation that asked for it, expires after five minutes and is consumed when it executes. The approval gate is the second layer. It applies only once you turn on the autonomy policy, which is off by default. Treat every transfer as high-stakes and read that page before relying on the gate.

See also