How to Configure a Multi-Chain Crypto Wallet with Bitcoin P2WPKH and EVM Signing for OpenHuman

Configure a multi-chain crypto wallet with Bitcoin P2WPKH and EVM signing for OpenHuman by setting environment variables for RPC endpoints, initializing the wallet through the wallet_status agent tool, and executing transfers via the wallet_prepare_transfer flow that routes through chain-specific executors in src/openhuman/web3/wallet/chains/.

OpenHuman provides a core-owned wallet module that supports single-account, multi-chain operations for both Bitcoin P2WPKH and EVM networks (Ethereum, Base, Arbitrum, Optimism, Polygon, and BNB Chain). To configure a multi-chain crypto wallet with Bitcoin P2WPKH and EVM signing for OpenHuman, you must interface with three architectural layers: secret persistence and onboarding, chain-specific executors, and the RPC execution surface.

Wallet Architecture Overview

The OpenHuman wallet architecture consists of three distinct layers, each implemented in specific source files within the repository.

Onboarding and Secret Persistence handles mnemonic generation, encrypted storage, and user consent. According to the tinyhumansai/openhuman source code, this logic resides in src/openhuman/web3/wallet/ops.rs. The system prefers OS keychain storage under the key wallet.mnemonic, falling back to an encrypted JSON file at state/wallet-state.json.

Chain-Specific Executors implement the cryptographic operations for each supported network. The Bitcoin P2WPKH implementation lives in src/openhuman/web3/wallet/chains/btc.rs, while EVM support (including EIP-1559 and ERC-20 transfers) is defined in src/openhuman/web3/wallet/chains/evm.rs. Both modules expose a minimal surface: address validation, balance lookup, and the execute_quote primitive for transaction signing and broadcast.

Execution and RPC Surface provides the public API through wallet_* JSON-RPC controllers and agent tools. The execution engine in src/openhuman/web3/wallet/execution.rs manages a short-lived quote cache with a 64-second TTL, tying prepared transfers to specific chat threads. RPC schemas are defined in src/openhuman/web3/wallet/schemas.rs, with network transport handled by src/openhuman/web3/wallet/rpc.rs.

Configuring RPC Endpoints and Defaults

Before executing transactions, you must configure the RPC endpoints that serve blockchain state and handle transaction broadcast.

Set the following environment variables to override defaults defined in src/openhuman/web3/wallet/defaults.rs:

• OPENHUMAN_WALLET_BTC_RPC – JSON-RPC endpoint for Bitcoin (optional if using Esplora)
• OPENHUMAN_WALLET_BTC_EXPLORER – Esplora REST API base URL (default: https://mempool.space/api)
• OPENHUMAN_WALLET_EVM_<NETWORK>_RPC – Per-network RPC URLs (e.g., OPENHUMAN_WALLET_EVM_ETHEREUM_RPC)

If these variables are unset, the wallet falls back to the EvmNetwork enum values defined in defaults.rs, which includes public endpoints like https://rpc.ankr.com/eth for Ethereum mainnet.

Implementing Bitcoin P2WPKH Signing

The Bitcoin implementation in src/openhuman/web3/wallet/chains/btc.rs provides native SegWit (P2WPKH) support through BIP-84 derivation.

Derivation Path: The wallet derives addresses using path m/84'/0'/0'/0/<index>, producing native bech32 addresses. The bitcoin crate handles BIP-32/39 key management.

Transaction Flow:

1. Balance Query: Calls the configured Esplora endpoint (GET /address/<addr>) to fetch confirmed balances.
2. Signing: Constructs an unsigned transaction, signs inputs with the derived secp256k1 private key, and serializes to raw hex.
3. Broadcast: Posts the signed transaction via POST /tx to the Esplora endpoint.

All operations are encapsulated behind the wallet_prepare_transfer and internal execute_prepared functions.

Implementing EVM Signing

The EVM executor in src/openhuman/web3/wallet/chains/evm.rs supports EIP-1559 transactions and ERC-20 token transfers across six networks.

Derivation Path: Uses standard BIP-44 path m/44'/60'/0'/0/<index> via the ethers_signers crate.

Transaction Construction:

• Native Transfers: Builds EIP-1559 transactions with maxFeePerGas and maxPriorityFeePerGas parameters.
• ERC-20 Transfers: Encodes transfer(address,uint256) calldata using the helper in src/openhuman/web3/wallet/abi.rs.

Execution: The sign_and_broadcast_evm function (re-exported from execution.rs) signs with the derived private key and submits via eth_sendRawTransaction to the configured RPC endpoint.

Executing Transactions via RPC and Agent Tools

OpenHuman exposes wallet functionality through both JSON-RPC controllers and three registered agent tools: wallet_status, wallet_chain_status, and wallet_prepare_transfer.

Typical Execution Sequence:

1. Verify Setup: Call wallet_status (tool or RPC openhuman.wallet_status) to check consent status and derived addresses.

2. Prepare Transfer: Invoke wallet_prepare_transfer with the target chain and amount:

{
  "chain": "btc",
  "to": "bc1qexampleaddress",
  "amount": "0.001",
  "token": null
}

For EVM ERC-20 transfers, specify the contract address in the token field and use the evm_ethereum (or equivalent) chain identifier.

3. Execute: After user confirmation, the core automatically calls execute_prepared from src/openhuman/web3/wallet/execution.rs, broadcasting the transaction and returning a tx_hash.

4. Check Status: Query wallet_tx_status with the transaction hash to monitor confirmation.

Customizing and Extending the Wallet

You can extend wallet functionality by modifying the chain definitions and derivation logic.

Adding EVM Networks: Extend the EvmNetwork enum in src/openhuman/web3/wallet/defaults.rs with the new chain ID, RPC URL, and explorer base. The executor in evm.rs automatically supports any valid EvmNetwork variant.

Custom RPCs: Override default endpoints by setting the appropriate OPENHUMAN_WALLET_*_RPC environment variables; the transport layer in rpc.rs respects these overrides without code changes.

Modifying Derivation Paths: Change the derivation paths in chains/btc.rs (for alternative Bitcoin address types) or chains/evm.rs (for non-standard EVM hierarchies). Ensure consistency between signing operations and address display logic.

Example: Preparing a Transfer in Rust

use openhuman::web3::wallet::{self, WalletChain};
use openhuman::core::Harness;

// Initialize harness (provider and workspace setup omitted)
let harness = Harness::builder()
    .access(openhuman::core::Access::full())
    .build()
    .await?;

// Check wallet status
let status = harness
    .rpc_client()
    .call("openhuman.wallet_status", serde_json::json!({}))
    .await?;

// Prepare Bitcoin transfer
let prep = harness
    .rpc_client()
    .call(
        "openhuman.wallet_prepare_transfer",
        serde_json::json!({
            "chain": "btc",
            "to": "bc1qexampleaddress",
            "amount": "0.001",
            "token": null
        }),
    )
    .await?;

let quote_id = prep["quote_id"].as_str().unwrap();

// Execute after confirmation
let result = wallet::execution::execute_prepared(
    harness.core(),
    quote_id,
    true,
).await?;

Summary

• Configure RPC endpoints using OPENHUMAN_WALLET_BTC_RPC, OPENHUMAN_WALLET_BTC_EXPLORER, and OPENHUMAN_WALLET_EVM_<NETWORK>_RPC environment variables, or rely on defaults in src/openhuman/web3/wallet/defaults.rs.
• Bitcoin P2WPKH signing uses BIP-84 derivation (m/84'/0'/0'/0/<index>) and Esplora REST APIs, implemented in src/openhuman/web3/wallet/chains/btc.rs.
• EVM signing supports EIP-1559 transactions and ERC-20 transfers via BIP-44 derivation (m/44'/60'/0'/0/<index>) in src/openhuman/web3/wallet/chains/evm.rs.
• Execute transfers through the wallet_prepare_transfer agent tool or RPC method, followed by automatic execution via src/openhuman/web3/wallet/execution.rs after user confirmation.
• Extend networks by modifying the EvmNetwork enum and setting custom RPC URLs without altering core execution logic.

Frequently Asked Questions

What derivation paths does OpenHuman use for Bitcoin and EVM wallets?

OpenHuman uses BIP-84 derivation path m/84'/0'/0'/0/<index> for Bitcoin P2WPKH addresses (native SegWit), implemented in src/openhuman/web3/wallet/chains/btc.rs. For EVM chains, it uses BIP-44 path m/44'/60'/0'/0/<index> as defined in src/openhuman/web3/wallet/chains/evm.rs.

How do I add a custom EVM network to OpenHuman's wallet?

Extend the EvmNetwork enum in src/openhuman/web3/wallet/defaults.rs with the new chain ID, default RPC URL, and explorer base. Then set the OPENHUMAN_WALLET_EVM_<NETWORK>_RPC environment variable to point to your custom endpoint. The executor in evm.rs handles any valid EvmNetwork variant without additional code changes.

Where does OpenHuman store wallet mnemonics and private keys?

The wallet stores the BIP-39 mnemonic encrypted in the OS keychain under the key wallet.mnemonic. If the OS keychain is unavailable, it falls back to an encrypted JSON file at state/wallet-state.json. Private keys are derived on-demand from this stored mnemonic and never persisted separately, according to the implementation in src/openhuman/web3/wallet/ops.rs.

What is the quote cache and why does it expire after 64 seconds?

The execution engine in src/openhuman/web3/wallet/execution.rs maintains a short-lived cache of prepared transaction quotes to tie transfer requests to specific chat threads. The 64-second TTL ensures that stale quotes cannot be executed accidentally after significant time has passed, preventing errors from outdated gas prices or blockchain state while allowing sufficient time for user confirmation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}