Agent Wallet OpenClaw Extension

Workspace extension for the official OpenClaw agent.

External install path:

openclaw plugins install clawhub:@agentlayertech/agent-wallet-plugin

This extension registers wallet tools through the official OpenClaw plugin API and forwards execution to the local Python agent-wallet backend.

It is designed so the OpenClaw agent sees a small operational wallet surface instead of raw key management. In practice this means the agent works through explicit tools for:

• BTC balance, fee-rate, max-spendable, history, and transfer flows through the local wdk-btc-wallet backend
• EVM native balance, ERC-20 balance/metadata, fee-rate, receipt, Velora swap quote/execute, Aave V3 account/reserve/position flows, and transfer flows through the local wdk-evm-wallet backend
• wallet address, balances, and portfolio reads
• native SOL and SPL token transfers
• Jupiter swap and price lookup, including Solana swap intent execution that refreshes quotes inside user-approved limits
• Kamino lending read/deposit/withdraw/borrow/repay flows
• native Solana staking, stake deactivation, and stake withdrawal

Expected local layout:

• this extension lives at .openclaw/extensions/agent-wallet
• the Python package lives at agent-wallet/

Recommended config:

{
  "plugins": {
    "allow": ["agent-wallet"],
    "entries": {
      "agent-wallet": {
        "enabled": true,
        "config": {
          "userId": "openclaw-local-user",
          "backend": "solana_local",
          "network": "mainnet",
          "rpcUrls": [
            "https://your-primary-rpc.example",
            "https://api.mainnet-beta.solana.com"
          ],
          "signOnly": false,
          "encryptUserWallets": true,
          "migratePlaintextUserWallets": true,
          "refuseMainnetWalletRecreation": true,
          "packageRoot": "/absolute/path/to/agent-wallet",
          "pythonBin": "/absolute/path/to/python"
        }
      }
    }
  }
}

Recommended local installer entrypoint:

sh ./setup.sh

For packaged installs, keep the runtime installer path:

npx @agentlayer.tech/wallet install --yes

The ClawHub plugin package only installs the native OpenClaw plugin. It expects the authoritative Python runtime to already exist, and by default it now looks for it at:

~/.openclaw/agent-wallet-runtime/current/agent-wallet

If that runtime is not present, set plugins.entries.agent-wallet.config.packageRoot explicitly.

That installs the Python backend, Node dependencies for the local BTC/EVM runtimes, patches the OpenClaw plugin config, and provisions the first encrypted per-user Solana mainnet wallet when no explicit signer is already configured. EVM readiness can still be auto-healed during normal wallet switching when the runtime has sealed local vault credentials.

For self-hosted installs, prefer SOLANA_RPC_URL / SOLANA_RPC_URLS in local env and treat the plugin rpcUrl / rpcUrls fields as fallback only. If the local runtime exposes ALCHEMY_API_KEY or HELIUS_API_KEY, the wallet can derive the Solana RPC URL automatically for mainnet. Local env always takes precedence over openclaw.json.

Provide only AGENT_WALLET_BOOT_KEY to the runtime. Provision master_key, approval_secret, and any signer private_key into sealed_keys.json, not openclaw.json.

Important:

• For a local official OpenClaw install, userId should represent the wallet owner for that agent install.
• The public OpenClaw plugin docs do not document a per-request end-user identifier in registerTool(...).execute(...), so dynamic multi-user wallet selection is intentionally kept in the Python/runtime layer, not inside the TypeScript plugin itself.
• Helper scripts in agent-wallet/scripts/ are generic patch/finalize utilities and no longer assume a specific local username, path, or temporary master key.
• The OpenClaw plugin API in this repo exposes tool registration, not host password prompts. EVM wallet create/unlock still is not a public agent tool, but the runtime can now auto-create or auto-unlock the local EVM wallet during set_wallet_backend or EVM tool calls when sealed_keys.json contains the local EVM vault password.
• For a one-command local BTC onboarding path, use agent-wallet/scripts/bootstrap_openclaw_btc.py, which both sets up the BTC wallet binding and patches local OpenClaw config for backend=wdk_btc_local.
• The BTC flow now only supports local service URLs (127.0.0.1 / localhost / ::1).
• The local BTC service is protected with a bearer token loaded from ~/.openclaw/wdk-btc-wallet/local-auth-token, not from plugin config JSON.
• When the BTC service URL is local, that bootstrap script can also auto-start wdk-btc-wallet before patching OpenClaw config.
• The EVM flow also only supports local service URLs (127.0.0.1 / localhost / ::1) and uses a bearer token loaded from ~/.openclaw/wdk-evm-wallet/local-auth-token.
• The installer now provisions a sealed local EVM vault password under sealed_keys.json by default, and host-side EVM setup helpers refresh that sealed value whenever the operator enters a new password.
• The EVM tool surface is intentionally narrow: Velora swap quote/execute, Aave V3 account/reserve/position flows, native transfers, ERC-20 transfers, fee quotes, and receipt lookup only. No arbitrary calldata, standalone approvals, or generic contract execution are exposed to the agent.
• Velora swap and Aave V3 support are currently limited to ethereum and base. Test carefully because the upstream WDK protocol packages are still beta.
• Agents can call set_wallet_backend to switch the active wallet for the current OpenClaw plugin session between Solana, EVM, and Bitcoin. This does not edit openclaw.json; plugin config remains the startup default.
• EVM read and write tools accept an optional per-call network override for ethereum or base.
• Agents can also call set_evm_network to select the active EVM network for the current OpenClaw plugin session. After that, EVM tools default to the selected network unless a specific call passes its own network value. Do not edit code, plugin config, or environment variables just to switch between Base and Ethereum.
• get_wallet_balance returns an enriched wallet overview for Solana and EVM: native balance, discovered token balances, per-asset USD values when pricing is available, and total_value_usd.
• Solana wallet overview uses Solana RPC only for balance and token-account discovery. Token prices come from Jupiter, not RPC, and internal transfer/staking checks continue to use native-only balance reads.
• If the user needs to recover the mnemonic later, host-side reveal stays outside the agent tool surface via agent-wallet/scripts/manage_openclaw_btc_wallet.py reveal-seed.
• Optional Jupiter overrides are available via jupiterBaseUrl, jupiterUltraBaseUrl, jupiterPriceBaseUrl, jupiterPortfolioBaseUrl, and jupiterApiKey.
• Optional Kamino overrides are available via kaminoBaseUrl and kaminoProgramId.
• Jupiter Portfolio implementation remains in the backend, but those agent-facing tools are temporarily disabled for now.
• Mainnet wallets are pinned by address. If a pinned mainnet wallet file disappears, the runtime refuses to silently create a replacement wallet.

OpenClaw UX

The intended user-facing flow inside OpenClaw is:

1. Read first: use wallet address, balance, portfolio, validator list, or stake account inspection tools.
2. Preview next: transfers, swaps, Aave position changes, staking, stake deactivation, and stake withdrawals should start in preview.
3. Prepare only with intent: prepare is for explicit execution planning intent and returns no signed transaction bytes.
4. Execute only after chat confirmation: after the user explicitly confirms the shown preview/prepare summary in chat, call execute with the same semantic params. The OpenClaw extension handles the internal execution authorization automatically and binds it to the cached operation.
5. On mainnet, restate the network, asset, amount, and destination, validator, or stake account before execute.

For staking specifically, the normal agent flow should be:

1. get_solana_staking_validators
2. stake_sol_native in preview
3. stake_sol_native in execute
4. get_solana_stake_account
5. later, deactivate_solana_stake and withdraw_solana_stake

Switching networks

The extension is already network-aware:

• plugins.entries.agent-wallet.config.network selects mainnet for Solana, bitcoin for BTC, or the supported EVM networks
• Solana mainnet wallets keep the same per-user file layout
• switching the configured backend network does not merge balances across chains

Recommended local switch helper:

python agent-wallet/scripts/switch_openclaw_wallet_network.py --network mainnet

Use --show-only first if you want to inspect the target wallet path before changing the config.