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

> Learn to configure a multi-chain crypto wallet with Bitcoin P2WPKH and EVM signing for OpenHuman. Set up RPC endpoints, initialize the wallet, and execute transfers easily.

- Repository: [Tiny Humans/openhuman](https://github.com/tinyhumansai/openhuman)
- Tags: how-to-guide
- Published: 2026-08-27

---

**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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/web3/wallet/schemas.rs), with network transport handled by [`src/openhuman/web3/wallet/rpc.rs`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/web3/wallet/abi.rs).

**Execution**: The `sign_and_broadcast_evm` function (re-exported from [`execution.rs`](https://github.com/tinyhumansai/openhuman/blob/main/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:

```json
{
  "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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/web3/wallet/defaults.rs) with the new chain ID, RPC URL, and explorer base. The executor in [`evm.rs`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/rpc.rs) respects these overrides without code changes.

**Modifying Derivation Paths**: Change the derivation paths in [`chains/btc.rs`](https://github.com/tinyhumansai/openhuman/blob/main/chains/btc.rs) (for alternative Bitcoin address types) or [`chains/evm.rs`](https://github.com/tinyhumansai/openhuman/blob/main/chains/evm.rs) (for non-standard EVM hierarchies). Ensure consistency between signing operations and address display logic.

**Example: Preparing a Transfer in Rust**

```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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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.