# Agent Wallet OpenClaw Extension

Workspace extension for the official OpenClaw agent.

External install path:

```bash
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 and Uniswap 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:

```json
{
  "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:

```bash
sh ./setup.sh
```

For packaged installs, keep the runtime installer path:

```bash
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:

```bash
~/.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 and Uniswap 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 core read and transfer tools accept an optional per-call `network` override for `ethereum`, `base`, or `robinhood`; Velora/Aave remain limited to Ethereum/Base, while Uniswap supports all three.
- 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, Ethereum, and Robinhood.
- `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:

```bash
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.