@agentlayer.tech/wallet 0.1.18 → 0.1.19

package/.openclaw/AGENTS.md

@@ -7,22 +7,16 @@ These instructions apply to the entire `.openclaw/` tree.
 This tree contains local OpenClaw host-side workspace assets. In the current repo, its main responsibilities are:
 
 - the `agent-wallet` extension that bridges OpenClaw to the authoritative Python `agent-wallet` backend
-- the `pay-bridge` extension that bridges OpenClaw to the local `pay` CLI for paid API discovery and execution
 
 ## Current structure
 - `.openclaw/extensions/agent-wallet/index.ts` — TypeScript extension entrypoint registered by OpenClaw.
 - `.openclaw/extensions/agent-wallet/openclaw.plugin.json` — plugin manifest and config schema.
 - `.openclaw/extensions/agent-wallet/package.json` — extension package metadata.
 - `.openclaw/extensions/agent-wallet/skills/wallet-operator/SKILL.md` — user-facing operational wallet safety guidance.
-- `.openclaw/extensions/pay-bridge/index.ts` — TypeScript entrypoint for the local `pay` CLI bridge.
-- `.openclaw/extensions/pay-bridge/openclaw.plugin.json` — plugin manifest and config schema for pay tools.
-- `.openclaw/extensions/pay-bridge/core.mjs` — local `pay` command execution and output shaping.
-- `.openclaw/extensions/pay-bridge/skills/pay-operator/SKILL.md` — user-facing operational guidance for paid API usage.
 
 ## Design intent
 - Keep the TypeScript extension thin and host-oriented.
 - Let Python own wallet logic, policy, approvals, signing rules, and Solana implementation details.
-- Let `pay` remain the source of truth for paid API wallet/account behavior.
 - Let the extension focus on:
   - resolving config
   - locating the Python package
@@ -35,7 +29,6 @@ This tree contains local OpenClaw host-side workspace assets. In the current rep
 
 ### Keep bridge logic thin
 - Do not duplicate business logic from Python unless OpenClaw requires it at registration time.
-- Do not duplicate payment protocol logic from `pay`; prefer invoking the local CLI and shaping its output.
 - Do not reimplement approval validation, transaction policy, wallet derivation, or Solana-specific rules in TypeScript.
 - Prefer forwarding config into the CLI bridge and letting Python decide runtime behavior.
 - Treat this layer as a transport and schema bridge, not an execution authority.

package/.openclaw/extensions/agent-wallet/README.md

@@ -77,7 +77,7 @@ The ClawHub plugin package only installs the native OpenClaw plugin. It expects
 
 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, and patches the OpenClaw plugin config. Wallet creation, unlock, and local service start stay as separate host-side steps.
+That installs the Python backend, Node dependencies for the local BTC/EVM runtimes, and patches the OpenClaw plugin config. Solana stays ready immediately; EVM readiness can now 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` or `devnet`. Local env always takes precedence over `openclaw.json`.
 
@@ -88,12 +88,13 @@ 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, so BTC and EVM wallet create/unlock remain host-shell or CLI flows outside the agent tool surface.
+- 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.

package/.openclaw/extensions/agent-wallet/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentlayertech/agent-wallet-plugin",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "description": "OpenClaw plugin bridge for the AgentLayer wallet runtime.",
   "type": "module",
   "license": "SEE LICENSE IN ../../../LICENSE",

package/README.md

@@ -18,7 +18,7 @@ AgentLayer is a beta local-first wallet and finance stack for agents.
 The repository includes:
 
 - `agent-wallet/` - the main wallet backend for AgentLayer
-- `.openclaw/` - the local AgentLayer bridge layer, including the OpenClaw wallet bridge and the `pay.sh` API-payments bridge
+- `.openclaw/` - the local AgentLayer bridge layer for the OpenClaw wallet integration
 - `hermes/` - optional Hermes Agent plugin bridge for the same wallet backend
 - `wdk-btc-wallet/` - the local Bitcoin wallet service
 - `wdk-evm-wallet/` - the local EVM wallet service
@@ -55,7 +55,6 @@ Install the native OpenClaw plugins from ClawHub:
 
 ```bash
 openclaw plugins install clawhub:@agentlayertech/agent-wallet-plugin
-openclaw plugins install clawhub:@agentlayertech/pay-bridge-plugin
 ```
 
 Those ClawHub packages do not replace the npm installer. Keep `npx @agentlayer.tech/wallet install --yes` for laying down the local wallet runtime, Python backend, and helper services. The ClawHub packages only install the OpenClaw plugin surfaces that point at that runtime.
@@ -92,7 +91,6 @@ Use ClawHub when you want the plugin itself to be installed through OpenClaw:
 
 ```bash
 openclaw plugins install clawhub:@agentlayertech/agent-wallet-plugin
-openclaw plugins install clawhub:@agentlayertech/pay-bridge-plugin
 ```
 
 Recommended order:

package/RELEASING.md

@@ -12,11 +12,10 @@ The public install command is:
 npx @agentlayer.tech/wallet install --yes
 ```
 
-The repo also ships two native OpenClaw plugin packages for ClawHub:
+The repo also ships a native OpenClaw plugin package for ClawHub:
 
 ```text
 @agentlayertech/agent-wallet-plugin
-@agentlayertech/pay-bridge-plugin
 ```
 
 ## When npm Publishes
@@ -200,7 +199,6 @@ Dry-run the package contents from each plugin directory:
 
 ```bash
 (cd .openclaw/extensions/agent-wallet && npm pack --dry-run)
-(cd .openclaw/extensions/pay-bridge && npm pack --dry-run)
 ```
 
 Publish to ClawHub with the package-specific command documented by OpenClaw:
@@ -208,16 +206,12 @@ Publish to ClawHub with the package-specific command documented by OpenClaw:
 ```bash
 clawhub package publish .openclaw/extensions/agent-wallet --dry-run
 clawhub package publish .openclaw/extensions/agent-wallet
-
-clawhub package publish .openclaw/extensions/pay-bridge --dry-run
-clawhub package publish .openclaw/extensions/pay-bridge
 ```
 
 Users then install them natively through OpenClaw:
 
 ```bash
 openclaw plugins install clawhub:@agentlayertech/agent-wallet-plugin
-openclaw plugins install clawhub:@agentlayertech/pay-bridge-plugin
 ```
 
 GitHub Actions can publish the same packages automatically from tags and manual
@@ -231,14 +225,13 @@ CLAWHUB_TOKEN
 
 Workflow behavior:
 
-- `pull_request`: packs both plugins and runs ClawHub `--dry-run`
+- `pull_request`: packs the plugin and runs ClawHub `--dry-run`
 - `workflow_dispatch`: publishes or dry-runs based on the `dry_run` input
-- `push` on `v*` tags: publishes both plugins automatically
+- `push` on `v*` tags: publishes the plugin automatically
 
 The workflow currently publishes:
 
 - `.openclaw/extensions/agent-wallet` as `bundle-plugin`
-- `.openclaw/extensions/pay-bridge` as `code-plugin`
 
 `agent-wallet` stays on `bundle-plugin` because that package name was first
 published to ClawHub with that family, and ClawHub does not allow family
@@ -298,17 +291,16 @@ It publishes these ClawHub packages:
 
 ```text
 @agentlayertech/agent-wallet-plugin
-@agentlayertech/pay-bridge-plugin
 ```
 
 ### Triggers
 
 - `pull_request`
-  - runs ClawHub publish in `--dry-run` mode for both plugin packages
+  - runs ClawHub publish in `--dry-run` mode for the plugin package
 - `workflow_dispatch`
   - supports manual runs with a `dry_run` boolean input
 - `push` on git tags matching `v*`
-  - publishes both plugin packages to ClawHub
+  - publishes the plugin package to ClawHub
 
 ### Required secret
 
@@ -330,7 +322,6 @@ publisher access to:
 The workflow currently publishes:
 
 - `.openclaw/extensions/agent-wallet` as `bundle-plugin`
-- `.openclaw/extensions/pay-bridge` as `code-plugin`
 
 `agent-wallet` remains on `bundle-plugin` because the package
 `@agentlayertech/agent-wallet-plugin` was first created in ClawHub with that
@@ -346,7 +337,6 @@ If you want one git tag to publish both npm and ClawHub surfaces together:
 package.json
 agent-wallet/pyproject.toml
 .openclaw/extensions/agent-wallet/package.json
-.openclaw/extensions/pay-bridge/package.json
 ```
 
 2. Commit the release version bump.

package/agent-wallet/README.md

@@ -405,6 +405,7 @@ For the local EVM backend (`backend=wdk_evm_local`), the lifecycle mirrors the B
 - the EVM service is localhost-only and no longer accepts remote service URLs through the OpenClaw EVM flow
 - `agent-wallet` talks to it through a local bearer token loaded from `~/.openclaw/wdk-evm-wallet/local-auth-token`
 - `agent-wallet` stores only a per-user EVM wallet binding under `~/.openclaw/users/<normalized-user-id>/wallets/evm-<network>-agent.json`
+- the runtime can auto-create missing EVM bindings or auto-unlock the local vault during ordinary OpenClaw switching/tool calls when `sealed_keys.json` contains `wdk_evm_wallet_password`
 - supported EVM networks are `ethereum`, `sepolia`, `base`, and `base-sepolia`
 - OpenClaw-facing EVM tools accept an optional per-call `network` override for `ethereum` or `base`, so the agent can switch between the two mainnet EVM paths without editing host config
 - EVM `get_wallet_balance` now returns an enriched portfolio-style payload with native balance, discovered ERC-20 balances, and USD values when token discovery and pricing are available
@@ -429,6 +430,7 @@ That wrapper:
 - can auto-start `wdk-evm-wallet/run-local.sh` if the local service is not already healthy
 - creates or unlocks the local EVM wallet binding
 - also binds the paired EVM network by default: `ethereum <-> base`, `sepolia <-> base-sepolia`
+- stores the entered EVM vault password into `sealed_keys.json` when `AGENT_WALLET_BOOT_KEY` is available, so later OpenClaw wallet switching can auto-raise the EVM backend without another password prompt
 - patches OpenClaw config to `backend=wdk_evm_local`
 
 Example host-side EVM wallet creation:
@@ -453,6 +455,7 @@ Per-user wallets are now encrypted at rest in one hardened mode:
 
 Do not store `masterKey`, `privateKey`, or approval secrets in plugin config JSON or direct runtime environment variables.
 `AGENT_WALLET_MASTER_KEY`, `AGENT_WALLET_APPROVAL_SECRET`, and `SOLANA_AGENT_PRIVATE_KEY` are now provisioning-only inputs for installer/admin scripts and are rejected by the runtime.
+The installer also provisions a sealed `wdk_evm_wallet_password` by default so greenfield EVM wallet setup can happen automatically on first switch.
 Create or update that sealed file with:
 
 ```bash

package/agent-wallet/agent_wallet/config.py

@@ -368,6 +368,17 @@ def resolve_solana_private_key() -> str:
     )
 
 
+def resolve_evm_wallet_password() -> str:
+    """Resolve the local EVM vault password from env or the sealed secret store."""
+    direct = os.getenv("WDK_EVM_WALLET_PASSWORD", "").strip()
+    if direct:
+        return direct
+    return _resolve_sealed_secret(
+        "wdk_evm_wallet_password",
+        "evm_wallet_password",
+    )
+
+
 def use_encrypted_user_wallets() -> bool:
     """Per-user wallet files are always encrypted in the hardened runtime."""
     return True

package/agent-wallet/agent_wallet/evm_user_wallets.py

@@ -3,14 +3,28 @@
 from __future__ import annotations
 
 import json
+import os
+import secrets
+import subprocess
+import time
 from pathlib import Path
 from typing import Any
-
-from agent_wallet.config import resolve_openclaw_home, settings
+from urllib.error import URLError
+from urllib.parse import urlparse
+from urllib.request import urlopen
+
+from agent_wallet.config import (
+    resolve_boot_key,
+    resolve_evm_wallet_password,
+    resolve_openclaw_home,
+    settings,
+)
 from agent_wallet.providers.wdk_evm_local import WdkEvmLocalClient
 from agent_wallet.user_wallets import normalize_user_id
 from agent_wallet.wallet_layer.base import WalletBackendError
 
+LOCAL_WDK_EVM_HOSTS = {"127.0.0.1", "localhost", "::1"}
+
 
 def _normalize_evm_network(value: str | None) -> str:
     network = str(value or "").strip().lower()
@@ -34,6 +48,87 @@ def _resolve_service_url(service_url: str | None = None) -> str:
     return effective
 
 
+def _paired_network(network: str) -> str | None:
+    mapping = {
+        "ethereum": "base",
+        "base": "ethereum",
+        "sepolia": "base-sepolia",
+        "base-sepolia": "sepolia",
+    }
+    return mapping.get(_normalize_evm_network(network))
+
+
+def _health_url(service_url: str) -> str:
+    return f"{service_url.rstrip('/')}/health"
+
+
+def _service_is_healthy(service_url: str) -> bool:
+    try:
+        with urlopen(_health_url(service_url), timeout=1.5) as response:
+            return int(getattr(response, "status", 0) or 0) == 200
+    except (URLError, TimeoutError, OSError):
+        return False
+
+
+def _is_local_service_url(service_url: str) -> bool:
+    parsed = urlparse(service_url)
+    return parsed.scheme in {"http", "https"} and parsed.hostname in LOCAL_WDK_EVM_HOSTS
+
+
+def _resolve_local_wdk_evm_root() -> Path | None:
+    configured = os.getenv("OPENCLAW_EVM_WDK_WALLET_ROOT", "").strip()
+    candidates = [configured] if configured else []
+    candidates.extend(
+        [
+            str(Path(__file__).resolve().parents[2] / "wdk-evm-wallet"),
+            str(resolve_openclaw_home() / "agent-wallet-runtime" / "current" / "wdk-evm-wallet"),
+        ]
+    )
+    for candidate in candidates:
+        root = Path(candidate).expanduser()
+        if (root / "run-local.sh").exists():
+            return root
+    return None
+
+
+def _auto_start_local_service(service_url: str, network: str) -> None:
+    if _service_is_healthy(service_url):
+        return
+    if not _is_local_service_url(service_url):
+        raise WalletBackendError(
+            f"wdk-evm-wallet is unreachable at {_health_url(service_url)} and auto-start only supports localhost URLs."
+        )
+    wallet_root = _resolve_local_wdk_evm_root()
+    if wallet_root is None:
+        raise WalletBackendError(
+            "wdk-evm-wallet is not healthy and the local launcher could not be found."
+        )
+    parsed = urlparse(service_url)
+    env = os.environ.copy()
+    env["HOST"] = parsed.hostname or "127.0.0.1"
+    env["PORT"] = str(parsed.port or 8081)
+    env["WDK_EVM_NETWORK"] = _normalize_evm_network(network)
+    process = subprocess.Popen(  # noqa: S603
+        ["sh", str(wallet_root / "run-local.sh")],
+        cwd=str(wallet_root),
+        env=env,
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        start_new_session=True,
+    )
+    deadline = time.time() + 30.0
+    while time.time() < deadline:
+        if _service_is_healthy(service_url):
+            return
+        if process.poll() is not None:
+            raise WalletBackendError("wdk-evm-wallet exited before becoming healthy.")
+        time.sleep(0.5)
+    raise WalletBackendError(
+        f"Timed out waiting for wdk-evm-wallet health at {_health_url(service_url)}."
+    )
+
+
 def _resolve_user_evm_wallet_dir(user_id: str) -> Path:
     return resolve_openclaw_home() / "users" / normalize_user_id(user_id) / "wallets"
 
@@ -98,6 +193,58 @@ def list_user_evm_wallet_bindings(user_id: str) -> list[dict[str, Any]]:
     return bindings
 
 
+def _maybe_store_evm_wallet_password(password: str) -> bool:
+    value = str(password or "").strip()
+    if not value:
+        return False
+    boot_key = resolve_boot_key()
+    if not boot_key:
+        return False
+    from agent_wallet.sealed_keys import resolve_sealed_keys_path, seal_keys, unseal_keys
+
+    sealed_path = resolve_sealed_keys_path()
+    existing = unseal_keys(boot_key) if sealed_path.exists() else {}
+    if existing.get("wdk_evm_wallet_password") == value:
+        return False
+    seal_keys(boot_key, {**existing, "wdk_evm_wallet_password": value})
+    return True
+
+
+def _ensure_evm_wallet_password() -> str:
+    existing = resolve_evm_wallet_password()
+    if existing:
+        return existing
+    boot_key = resolve_boot_key()
+    if not boot_key:
+        return ""
+    generated = secrets.token_urlsafe(24)
+    _maybe_store_evm_wallet_password(generated)
+    return generated
+
+
+def _bind_network_pair(
+    user_id: str,
+    *,
+    wallet_id: str,
+    network: str,
+    service_url: str,
+    account_index: int,
+    address: str | None,
+) -> None:
+    paired = _paired_network(network)
+    if not paired:
+        return
+    bind_user_evm_wallet(
+        user_id,
+        wallet_id=wallet_id,
+        network=paired,
+        service_url=service_url,
+        account_index=account_index,
+        tolerate_locked=True,
+        fallback_address=address,
+    )
+
+
 def bind_user_evm_wallet(
     user_id: str,
     *,
@@ -208,6 +355,164 @@ def ensure_user_evm_wallet_binding(
     )
 
 
+def ensure_user_evm_wallet_ready(
+    user_id: str,
+    *,
+    network: str | None = None,
+    service_url: str | None = None,
+    wallet_id: str | None = None,
+    account_index: int | None = None,
+    auto_start_service: bool = True,
+) -> dict[str, Any]:
+    effective_network = _normalize_evm_network(network or settings.solana_network)
+    effective_service_url = _resolve_service_url(service_url)
+    effective_account_index = settings.wdk_evm_account_index if account_index is None else int(account_index)
+    if auto_start_service:
+        _auto_start_local_service(effective_service_url, effective_network)
+    elif not _service_is_healthy(effective_service_url):
+        raise WalletBackendError(
+            f"wdk-evm-wallet is not healthy at {_health_url(effective_service_url)}."
+        )
+
+    client = WdkEvmLocalClient(effective_service_url)
+    explicit_wallet_id = str(wallet_id or "").strip()
+    binding: dict[str, Any] | None = None
+    if explicit_wallet_id:
+        binding = ensure_user_evm_wallet_binding(
+            user_id,
+            network=effective_network,
+            service_url=effective_service_url,
+            wallet_id=explicit_wallet_id,
+            account_index=effective_account_index,
+        )
+    else:
+        try:
+            binding = get_user_evm_wallet_binding(user_id, network=effective_network)
+        except WalletBackendError:
+            binding = None
+
+    if binding is None:
+        existing_bindings = list_user_evm_wallet_bindings(user_id)
+        wallet_ids = {
+            str(item.get("wallet_id") or "").strip()
+            for item in existing_bindings
+            if str(item.get("wallet_id") or "").strip()
+        }
+        if len(wallet_ids) > 1:
+            raise WalletBackendError(
+                "Multiple EVM wallet bindings exist for this user. Set wdk_evm_wallet_id explicitly to auto-bind a new network."
+            )
+        if wallet_ids:
+            binding = bind_user_evm_wallet(
+                user_id,
+                wallet_id=next(iter(wallet_ids)),
+                network=effective_network,
+                service_url=effective_service_url,
+                account_index=effective_account_index,
+                tolerate_locked=True,
+                fallback_address=str(existing_bindings[0].get("address") or "").strip() or None,
+            )
+        else:
+            service_wallets = client.list_wallets_sync()
+            service_wallet_ids = {
+                str(item.get("walletId") or "").strip()
+                for item in service_wallets
+                if str(item.get("walletId") or "").strip()
+            }
+            if len(service_wallet_ids) > 1:
+                raise WalletBackendError(
+                    "Multiple local EVM vault wallets exist. Set wdk_evm_wallet_id explicitly before automatic switching."
+                )
+            if service_wallet_ids:
+                binding = bind_user_evm_wallet(
+                    user_id,
+                    wallet_id=next(iter(service_wallet_ids)),
+                    network=effective_network,
+                    service_url=effective_service_url,
+                    account_index=effective_account_index,
+                    tolerate_locked=True,
+                )
+            else:
+                password = _ensure_evm_wallet_password()
+                if not password:
+                    raise WalletBackendError(
+                        "EVM wallet is not set up yet and no sealed local EVM wallet password is available for automatic creation."
+                    )
+                created = create_user_evm_wallet(
+                    user_id,
+                    password=password,
+                    network=effective_network,
+                    service_url=effective_service_url,
+                    account_index=effective_account_index,
+                )
+                binding = get_user_evm_wallet_binding(user_id, network=effective_network)
+                _bind_network_pair(
+                    user_id,
+                    wallet_id=str(created.get("wallet_id") or ""),
+                    network=effective_network,
+                    service_url=effective_service_url,
+                    account_index=effective_account_index,
+                    address=str(created.get("address") or "").strip() or None,
+                )
+
+    resolved_wallet_id = str(binding.get("wallet_id") or explicit_wallet_id).strip()
+    if not resolved_wallet_id:
+        raise WalletBackendError("EVM wallet binding is missing wallet_id.")
+
+    def _resolve_address() -> str:
+        payload = client.post_sync(
+            "/v1/evm/address/resolve",
+            {
+                "walletId": resolved_wallet_id,
+                "accountIndex": effective_account_index,
+                "network": effective_network,
+            },
+        )
+        address = str(payload.get("address") or "").strip()
+        if not address:
+            raise WalletBackendError("wdk-evm-wallet did not return an address.")
+        return address
+
+    try:
+        resolved_address = _resolve_address()
+    except WalletBackendError as exc:
+        is_locked = exc.code == "wallet_locked" or "wallet is locked" in str(exc).strip().lower()
+        if not is_locked:
+            raise
+        password = resolve_evm_wallet_password()
+        if not password:
+            raise WalletBackendError(
+                "EVM wallet exists but cannot be unlocked automatically because no sealed local EVM wallet password is available."
+            ) from exc
+        unlock_user_evm_wallet(
+            user_id,
+            password=password,
+            network=effective_network,
+            service_url=effective_service_url,
+            wallet_id=resolved_wallet_id,
+            account_index=effective_account_index,
+        )
+        resolved_address = _resolve_address()
+
+    binding = bind_user_evm_wallet(
+        user_id,
+        wallet_id=resolved_wallet_id,
+        network=effective_network,
+        service_url=effective_service_url,
+        account_index=effective_account_index,
+        fallback_address=resolved_address,
+    )
+    _bind_network_pair(
+        user_id,
+        wallet_id=resolved_wallet_id,
+        network=effective_network,
+        service_url=effective_service_url,
+        account_index=effective_account_index,
+        address=resolved_address,
+    )
+    return binding
+
+
 def create_user_evm_wallet(
     user_id: str,
     *,
@@ -251,6 +556,7 @@ def create_user_evm_wallet(
         "updated_at": created.get("updatedAt"),
     }
     _write_wallet_binding(resolve_user_evm_wallet_path(user_id, effective_network), binding)
+    _maybe_store_evm_wallet_password(password)
     return {
         **binding,
         "unlocked": bool(created.get("unlocked", True)),
@@ -302,6 +608,7 @@ def import_user_evm_wallet(
         "updated_at": created.get("updatedAt"),
     }
     _write_wallet_binding(resolve_user_evm_wallet_path(user_id, effective_network), binding)
+    _maybe_store_evm_wallet_password(password)
     return {
         **binding,
         "unlocked": bool(created.get("unlocked", True)),
@@ -334,6 +641,7 @@ def unlock_user_evm_wallet(
             "timeoutSeconds": 0,
         },
     )
+    _maybe_store_evm_wallet_password(password)
     return {
         **binding,
         "unlocked": bool(payload.get("unlocked", True)),

package/agent-wallet/agent_wallet/openclaw_runtime.py

@@ -8,7 +8,7 @@ from typing import Any
 from agent_wallet.approval import issue_approval_token
 from agent_wallet.btc_user_wallets import get_user_btc_wallet_binding
 from agent_wallet.config import settings
-from agent_wallet.evm_user_wallets import ensure_user_evm_wallet_binding, get_user_evm_wallet_binding
+from agent_wallet.evm_user_wallets import ensure_user_evm_wallet_ready
 from agent_wallet.models import OpenClawWalletSessionMetadata
 from agent_wallet.openclaw_adapter import OpenClawWalletAdapter
 from agent_wallet.plugin_bundle import build_openclaw_plugin_bundle
@@ -173,38 +173,17 @@ def onboard_openclaw_user_wallet(
             "base_sepolia": "base-sepolia",
         }
         effective_network = aliases.get(requested_network, requested_network)
-        binding: dict[str, Any] | None = None
         wallet_id = str(wdk_evm_wallet_id or settings.wdk_evm_wallet_id).strip()
         if not service_url:
             raise WalletBackendError("wdk_evm_service_url is required for backend=wdk_evm_local.")
-        if wallet_id:
-            try:
-                binding = get_user_evm_wallet_binding(user_id, network=effective_network)
-            except WalletBackendError:
-                binding = ensure_user_evm_wallet_binding(
-                    user_id,
-                    network=effective_network,
-                    service_url=service_url,
-                    wallet_id=wallet_id,
-                    account_index=account_index,
-                )
-            else:
-                if str(binding.get("wallet_id") or "").strip() != wallet_id:
-                    binding = ensure_user_evm_wallet_binding(
-                        user_id,
-                        network=effective_network,
-                        service_url=service_url,
-                        wallet_id=wallet_id,
-                        account_index=account_index,
-                    )
-        else:
-            binding = ensure_user_evm_wallet_binding(
-                user_id,
-                network=effective_network,
-                service_url=service_url,
-                account_index=account_index,
-            )
-            wallet_id = str(binding.get("wallet_id") or "").strip()
+        binding = ensure_user_evm_wallet_ready(
+            user_id,
+            network=effective_network,
+            service_url=service_url,
+            wallet_id=wallet_id or None,
+            account_index=account_index,
+        )
+        wallet_id = str(binding.get("wallet_id") or wallet_id).strip()
         if not wallet_id:
             raise WalletBackendError(
                 "wdk_evm_wallet_id is required for backend=wdk_evm_local, or create a bound user EVM wallet first."
@@ -212,17 +191,7 @@ def onboard_openclaw_user_wallet(
 
         client = WdkEvmLocalClient(service_url)
         wallet_meta = client.post_sync("/v1/evm/wallets/get", {"walletId": wallet_id})
-        resolved_address = str((binding or {}).get("address") or "").strip()
-        if not resolved_address:
-            address_payload = client.post_sync(
-                "/v1/evm/address/resolve",
-                {
-                    "walletId": wallet_id,
-                    "accountIndex": account_index,
-                    "network": effective_network,
-                },
-            )
-            resolved_address = str(address_payload.get("address") or "").strip()
+        resolved_address = str(binding.get("address") or "").strip()
         backend = WdkEvmLocalWalletBackend(
             service_url=service_url,
             wallet_id=wallet_id,