@agentlayer.tech/wallet 0.1.11 → 0.1.12

package/CHANGELOG.md

@@ -7,6 +7,14 @@
   OpenClaw wallet tools or policy.
 - Added `wallet hermes install --yes` and `AGENT_WALLET_BOOT_KEY_FILE` support
   for smoother Hermes onboarding without manual `.env` editing.
+- Added Hermes EVM onboarding helpers:
+  `agent_wallet_evm_status` and `agent_wallet_evm_setup`.
+- Added host-side EVM bootstrap scripts for packaged/runtime installs:
+  `manage_openclaw_evm_wallet.py`, `bootstrap_openclaw_evm.py`, and
+  `setup_evm_wallet.sh`.
+- Kept Hermes EVM routing on the existing `wdk-evm-wallet` and
+  `provider-gateway` path for `ethereum` and `base`, without copying wallet
+  policy or duplicating tool implementations.
 - Replaced the repo license with `PolyForm Small Business 1.0.0`.
 - Clarified in `README.md` that individuals can audit, fork, run, and modify
   the code for themselves, and that company use follows the PolyForm small
@@ -15,6 +23,23 @@
   `wdk-evm-wallet`; cross-chain swaps now stay on LI.FI/Jupiter-backed paths
   with Mayan denied as a LI.FI bridge.
 
+## v0.1.12 - 2026-05-06
+
+### Added
+
+- Hermes EVM runtime helpers for packaged installs:
+  `agent_wallet_evm_status` and `agent_wallet_evm_setup`.
+- Host-side EVM lifecycle scripts in the runtime bundle:
+  `manage_openclaw_evm_wallet.py`, `bootstrap_openclaw_evm.py`, and
+  `setup_evm_wallet.sh`.
+
+### Changed
+
+- Hermes installs now support the same local EVM onboarding shape as BTC:
+  inspect runtime health, auto-start the local service, create or unlock the
+  vault wallet, and bind paired `ethereum/base` networks through the thin
+  bridge.
+
 ## v0.1.0-beta.2 - 2026-03-31
 
 Second public beta release that expands the stack beyond the initial MCP, wallet, and AgentLayer bridge scope.

package/README.md

@@ -4,6 +4,11 @@
 ```bash
 npx @agentlayer.tech/wallet install --yes
 ```
+For install to Hermes use
+```bash
+npx @agentlayer.tech/wallet install --yes && npx @agentlayer.tech/wallet hermes install --yes
+```
+
 AgentLayer is a beta local-first wallet and finance stack for agents.
 
 The repository includes:
@@ -92,28 +97,10 @@ sh agent-wallet/scripts/setup_btc_wallet.sh
 EVM:
 
 ```bash
-cd wdk-evm-wallet && sh run-local.sh
+sh agent-wallet/scripts/setup_evm_wallet.sh
 ```
 
-Create a local EVM wallet binding for an OpenClaw user:
-
-```bash
-printf '%s\n' 'your-local-evm-password' | \
-agent-wallet/.venv/bin/python -m agent_wallet.openclaw_cli evm-wallet-create \
-  --user-id your-user-id \
-  --password-stdin \
-  --config-json '{"backend":"wdk_evm_local","network":"base","wdkEvmServiceUrl":"http://127.0.0.1:8081"}'
-```
-
-Unlock an existing EVM wallet binding:
-
-```bash
-printf '%s\n' 'your-local-evm-password' | \
-agent-wallet/.venv/bin/python -m agent_wallet.openclaw_cli evm-wallet-unlock \
-  --user-id your-user-id \
-  --password-stdin \
-  --config-json '{"backend":"wdk_evm_local","network":"base","wdkEvmServiceUrl":"http://127.0.0.1:8081"}'
-```
+That host-side bootstrap can auto-start the local `wdk-evm-wallet` service, create or unlock the vault wallet, bind both `base` and `ethereum` for the same local user, and patch OpenClaw config to `backend=wdk_evm_local`.
 
 That generates three fresh local secrets in the current shell session. If you prefer Python instead of `openssl`:
 
@@ -149,7 +136,15 @@ OpenClaw remains the primary local environment, but the repo also ships an optio
 hermes/plugins/agent_wallet
 ```
 
-It exposes only two Hermes tools: `agent_wallet_tools` for discovery and `agent_wallet_invoke` for forwarding a single call into the existing Python wallet CLI. Install it by symlinking the plugin directory into Hermes:
+It exposes a thin bridge, not a port of wallet logic:
+
+- `agent_wallet_tools`
+- `agent_wallet_invoke`
+- `agent_wallet_approve`
+- `agent_wallet_evm_status`
+- `agent_wallet_evm_setup`
+
+Install it by symlinking the plugin directory into Hermes:
 
 ```bash
 npx @agentlayer.tech/wallet hermes install --yes
@@ -229,49 +224,32 @@ sh agent-wallet/scripts/reveal_btc_seed.sh
 
 ## EVM setup
 
-The EVM runtime is installed by `setup.sh`, but the host-side wallet onboarding is still a manual CLI flow.
-
-Start the local EVM service:
+The EVM runtime is installed by `setup.sh`, and the host-side onboarding now has the same one-command shape as BTC:
 
 ```bash
-cd wdk-evm-wallet && sh run-local.sh
+sh agent-wallet/scripts/setup_evm_wallet.sh
 ```
 
-Create a local EVM wallet binding for an OpenClaw user:
+That flow:
 
-```bash
-printf '%s\n' 'your-local-evm-password' | \
-agent-wallet/.venv/bin/python -m agent_wallet.openclaw_cli evm-wallet-create \
-  --user-id your-user-id \
-  --password-stdin \
-  --config-json '{"backend":"wdk_evm_local","network":"base","wdkEvmServiceUrl":"http://127.0.0.1:8081"}'
-```
+- prompts for `user-id`
+- prompts for `ethereum`, `base`, `sepolia`, or `base-sepolia`
+- defaults to `http://127.0.0.1:8081`
+- 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`
+- patches OpenClaw config to `backend=wdk_evm_local`
 
-Unlock an existing EVM wallet binding:
+You can still use the lower-level CLI if needed:
 
 ```bash
 printf '%s\n' 'your-local-evm-password' | \
-agent-wallet/.venv/bin/python -m agent_wallet.openclaw_cli evm-wallet-unlock \
+agent-wallet/.venv/bin/python -m agent_wallet.openclaw_cli evm-wallet-create \
   --user-id your-user-id \
   --password-stdin \
   --config-json '{"backend":"wdk_evm_local","network":"base","wdkEvmServiceUrl":"http://127.0.0.1:8081"}'
 ```
 
-Then switch the OpenClaw plugin config to the EVM backend:
-
-```bash
-AGENT_WALLET_BOOT_KEY='...' \
-agent-wallet/.venv/bin/python agent-wallet/scripts/install_openclaw_local_config.py \
-  --backend wdk_evm_local \
-  --network base \
-  --user-id your-user-id \
-  --package-root agent-wallet \
-  --extension-path .openclaw/extensions/agent-wallet \
-  --python-bin agent-wallet/.venv/bin/python
-```
-
-That final config step assumes `~/.openclaw/sealed_keys.json` already exists. The normal path is to let the main installer create it by running install with `AGENT_WALLET_BOOT_KEY`, `AGENT_WALLET_MASTER_KEY`, and `AGENT_WALLET_APPROVAL_SECRET` available.
-
 Important EVM notes:
 
 - only localhost service URLs are supported for the OpenClaw EVM flow

package/agent-wallet/README.md

@@ -34,6 +34,9 @@ The optional Hermes plugin is intentionally a bridge, not a port of the OpenClaw
 
 - `agent_wallet_tools` - read-only discovery for the underlying Python adapter tool specs.
 - `agent_wallet_invoke` - a dispatcher that calls `python -m agent_wallet.openclaw_cli invoke`.
+- `agent_wallet_approve` - a host approval-token issuer for exact execute operations.
+- `agent_wallet_evm_status` - a read-only EVM runtime and binding inspector.
+- `agent_wallet_evm_setup` - a host-side EVM bootstrap helper for Hermes.
 
 Install it with:
 
@@ -45,6 +48,12 @@ That command symlinks `hermes/plugins/agent_wallet` into `~/.hermes/plugins/agen
 
 Hermes tool config must not contain wallet secrets. Use the existing sealed runtime path and host-issued approval tokens for execute flows. `AGENT_WALLET_BOOT_KEY_FILE` lets OpenClaw and Hermes reference one local boot-key file instead of duplicating the boot key across multiple env files.
 
+For EVM on Hermes, the intended host flow is:
+
+- call `agent_wallet_evm_status` to inspect `wdk-evm-wallet` health and current bindings
+- call `agent_wallet_evm_setup` once to auto-start the local service when needed, create or unlock the local EVM wallet, and patch local OpenClaw config to `backend=wdk_evm_local`
+- then use ordinary `agent_wallet_invoke` calls for EVM reads, transfers, swaps, and Aave flows
+
 Current safe tools:
 
 - `get_wallet_capabilities`
@@ -375,6 +384,21 @@ For the local EVM backend (`backend=wdk_evm_local`), the lifecycle mirrors the B
   - `evm-wallet-unlock`
   - `evm-wallet-lock`
 
+For a simpler host-side bootstrap, use:
+
+```bash
+sh agent-wallet/scripts/setup_evm_wallet.sh
+```
+
+That wrapper:
+
+- prompts for `user-id` and EVM network when run interactively
+- defaults to `http://127.0.0.1:8081`
+- 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`
+- patches OpenClaw config to `backend=wdk_evm_local`
+
 Example host-side EVM wallet creation:
 
 ```bash

package/agent-wallet/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "openclaw-agent-wallet"
-version = "0.1.11"
+version = "0.1.12"
 description = "Plugin-friendly wallet backend for OpenClaw agents"
 requires-python = ">=3.10"
 dependencies = [

package/agent-wallet/scripts/bootstrap_openclaw_evm.py

@@ -0,0 +1,291 @@
+#!/usr/bin/env python3
+"""One-command host bootstrap for the local OpenClaw EVM wallet flow."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+from urllib.error import URLError
+from urllib.parse import urlparse
+from urllib.request import urlopen
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from agent_wallet.file_ops import atomic_write_text, chmod_if_exists
+
+
+def _default_config_path() -> Path:
+    return Path(os.path.expanduser("~/.openclaw/openclaw.json"))
+
+
+def _default_user_id() -> str:
+    return f"{os.getenv('USER', 'openclaw-user')}-local"
+
+
+def _default_python_bin() -> str:
+    return os.getenv("OPENCLAW_AGENT_WALLET_PYTHON", sys.executable)
+
+
+def _package_root() -> Path:
+    return Path(__file__).resolve().parents[1]
+
+
+def _repo_root() -> Path:
+    return Path(__file__).resolve().parents[2]
+
+
+def _script_path(name: str) -> Path:
+    return _package_root() / "scripts" / name
+
+
+def _normalize_network(value: str) -> str:
+    network = str(value or "").strip().lower()
+    aliases = {
+        "mainnet": "ethereum",
+        "eth": "ethereum",
+        "eth-mainnet": "ethereum",
+        "base-mainnet": "base",
+        "base_sepolia": "base-sepolia",
+    }
+    network = aliases.get(network, network)
+    if network not in {"ethereum", "sepolia", "base", "base-sepolia"}:
+        return "ethereum"
+    return network
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--config-path", default=str(_default_config_path()))
+    parser.add_argument("--plugin-id", default="agent-wallet")
+    parser.add_argument("--user-id", default=_default_user_id())
+    parser.add_argument("--network", default="base")
+    parser.add_argument("--service-url", default="http://127.0.0.1:8081")
+    parser.add_argument("--wdk-wallet-root", default=str(_repo_root() / "wdk-evm-wallet"))
+    parser.add_argument("--label", default="Agent EVM Wallet")
+    parser.add_argument("--account-index", type=int, default=0)
+    parser.add_argument("--python-bin", default=_default_python_bin())
+    parser.add_argument("--package-root", default=str(_package_root()))
+    parser.add_argument("--password-stdin", action=argparse.BooleanOptionalAction, default=False)
+    parser.add_argument("--sign-only", action=argparse.BooleanOptionalAction, default=False)
+    parser.add_argument("--auto-start-service", action=argparse.BooleanOptionalAction, default=True)
+    parser.add_argument("--bind-network-pair", action=argparse.BooleanOptionalAction, default=True)
+    return parser
+
+
+def _ensure_openclaw_config(config_path: Path) -> bool:
+    if config_path.exists():
+        return False
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    atomic_write_text(
+        config_path,
+        json.dumps({"plugins": {"entries": {}}, "tools": {"alsoAllow": []}}, indent=2) + "\n",
+        mode=0o600,
+    )
+    chmod_if_exists(config_path, 0o600)
+    return True
+
+
+def _run_script(
+    python_bin: str,
+    script_name: str,
+    args: list[str],
+    *,
+    stdin_text: str | None = None,
+) -> dict:
+    completed = subprocess.run(
+        [python_bin, str(_script_path(script_name)), *args],
+        check=True,
+        capture_output=True,
+        text=True,
+        input=stdin_text,
+        env=os.environ.copy(),
+    )
+    return json.loads(completed.stdout)
+
+
+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 {"127.0.0.1", "localhost", "::1"}
+
+
+def _require_local_service_url(service_url: str) -> None:
+    if not _is_local_service_url(service_url):
+        raise SystemExit(
+            f"EVM bootstrap only supports a localhost service URL. Refusing non-local endpoint: {service_url}"
+        )
+
+
+def _service_log_dir(config_path: Path) -> Path:
+    return config_path.expanduser().parent / "logs"
+
+
+def _service_log_path(config_path: Path) -> Path:
+    return _service_log_dir(config_path) / "wdk-evm-wallet.log"
+
+
+def _auto_start_local_service(
+    *,
+    service_url: str,
+    network: str,
+    wdk_wallet_root: Path,
+    config_path: Path,
+) -> dict[str, object]:
+    if _service_is_healthy(service_url):
+        return {"started": False, "already_healthy": True}
+
+    if not _is_local_service_url(service_url):
+        raise SystemExit(
+            f"EVM service at {service_url} is unreachable and auto-start is only supported for localhost URLs."
+        )
+
+    run_local = wdk_wallet_root / "run-local.sh"
+    if not run_local.exists():
+        raise SystemExit(f"Could not find wdk-evm-wallet launcher: {run_local}")
+
+    parsed = urlparse(service_url)
+    host = parsed.hostname or "127.0.0.1"
+    port = parsed.port or 8081
+    log_dir = _service_log_dir(config_path)
+    log_dir.mkdir(parents=True, exist_ok=True)
+    log_path = _service_log_path(config_path)
+
+    env = os.environ.copy()
+    env["HOST"] = host
+    env["PORT"] = str(port)
+    env["WDK_EVM_NETWORK"] = network
+
+    with log_path.open("a", encoding="utf-8") as log_file:
+        process = subprocess.Popen(  # noqa: S603
+            ["sh", str(run_local)],
+            cwd=str(wdk_wallet_root),
+            env=env,
+            stdin=subprocess.DEVNULL,
+            stdout=log_file,
+            stderr=log_file,
+            start_new_session=True,
+        )
+
+    deadline = time.time() + 30.0
+    while time.time() < deadline:
+        if _service_is_healthy(service_url):
+            return {
+                "started": True,
+                "already_healthy": False,
+                "pid": process.pid,
+                "log_path": str(log_path),
+            }
+        if process.poll() is not None:
+            raise SystemExit(
+                f"wdk-evm-wallet exited before becoming healthy. Check log: {log_path}"
+            )
+        time.sleep(0.5)
+
+    raise SystemExit(
+        f"Timed out waiting for wdk-evm-wallet health at {_health_url(service_url)}. Check log: {log_path}"
+    )
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+    effective_network = _normalize_network(args.network)
+    _require_local_service_url(args.service_url)
+    config_path = Path(args.config_path).expanduser()
+    config_created = _ensure_openclaw_config(config_path)
+    service_bootstrap: dict[str, object] | None = None
+    if args.auto_start_service:
+        service_bootstrap = _auto_start_local_service(
+            service_url=args.service_url,
+            network=effective_network,
+            wdk_wallet_root=Path(args.wdk_wallet_root).expanduser(),
+            config_path=config_path,
+        )
+    elif not _service_is_healthy(args.service_url):
+        raise SystemExit(
+            f"EVM service is not healthy at {_health_url(args.service_url)} and --no-auto-start-service was set."
+        )
+
+    stdin_text = sys.stdin.read() if args.password_stdin else None
+    setup_payload = _run_script(
+        args.python_bin,
+        "manage_openclaw_evm_wallet.py",
+        [
+            "setup",
+            "--user-id",
+            args.user_id,
+            "--network",
+            effective_network,
+            "--service-url",
+            args.service_url,
+            "--label",
+            args.label,
+            "--account-index",
+            str(args.account_index),
+            *([] if not args.password_stdin else ["--password-stdin"]),
+            *(["--bind-network-pair"] if args.bind_network_pair else ["--no-bind-network-pair"]),
+        ],
+        stdin_text=stdin_text,
+    )
+
+    wallet = dict(setup_payload.get("wallet") or {})
+    install_args = [
+        "--config-path",
+        str(config_path),
+        "--plugin-id",
+        args.plugin_id,
+        "--user-id",
+        args.user_id,
+        "--backend",
+        "wdk_evm_local",
+        "--network",
+        effective_network,
+        "--wdk-evm-service-url",
+        args.service_url,
+        "--wdk-evm-wallet-id",
+        str(wallet.get("wallet_id") or ""),
+        "--wdk-evm-account-index",
+        str(wallet.get("account_index") or args.account_index),
+        "--package-root",
+        args.package_root,
+        "--python-bin",
+        args.python_bin,
+        "--sign-only" if args.sign_only else "--no-sign-only",
+    ]
+    install_payload = _run_script(
+        args.python_bin,
+        "install_openclaw_local_config.py",
+        install_args,
+    )
+
+    print(
+        json.dumps(
+            {
+                "ok": True,
+                "config_created": config_created,
+                "service_bootstrap": service_bootstrap,
+                "evm_setup": setup_payload,
+                "openclaw_install": install_payload,
+            }
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/agent-wallet/scripts/install_openclaw_local_config.py

@@ -72,6 +72,9 @@ def build_parser() -> argparse.ArgumentParser:
     parser.add_argument("--wdk-btc-service-url", default="")
     parser.add_argument("--wdk-btc-wallet-id", default="")
     parser.add_argument("--wdk-btc-account-index", type=int, default=0)
+    parser.add_argument("--wdk-evm-service-url", default="")
+    parser.add_argument("--wdk-evm-wallet-id", default="")
+    parser.add_argument("--wdk-evm-account-index", type=int, default=0)
     parser.add_argument("--sign-only", action=argparse.BooleanOptionalAction, default=False)
     parser.add_argument("--encrypt-user-wallets", action=argparse.BooleanOptionalAction, default=True)
     parser.add_argument(
@@ -183,6 +186,12 @@ def main() -> None:
         plugin_config["wdkBtcWalletId"] = args.wdk_btc_wallet_id.strip()
     if args.wdk_btc_account_index is not None:
         plugin_config["wdkBtcAccountIndex"] = int(args.wdk_btc_account_index)
+    if args.wdk_evm_service_url.strip():
+        plugin_config["wdkEvmServiceUrl"] = args.wdk_evm_service_url.strip()
+    if args.wdk_evm_wallet_id.strip():
+        plugin_config["wdkEvmWalletId"] = args.wdk_evm_wallet_id.strip()
+    if args.wdk_evm_account_index is not None:
+        plugin_config["wdkEvmAccountIndex"] = int(args.wdk_evm_account_index)
     if args.write_master_key:
         raise SystemExit(
             "Refusing to write masterKey into config. Runtime secrets must live in sealed_keys.json."

package/agent-wallet/scripts/manage_openclaw_evm_wallet.py

@@ -0,0 +1,343 @@
+#!/usr/bin/env python3
+"""Host-side helper for managing a local OpenClaw EVM wallet binding."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from getpass import getpass
+from pathlib import Path
+from urllib.error import URLError
+from urllib.request import urlopen
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[1]
+if str(PACKAGE_ROOT) not in sys.path:
+    sys.path.insert(0, str(PACKAGE_ROOT))
+
+from agent_wallet.config import settings  # noqa: E402
+from agent_wallet.evm_user_wallets import (  # noqa: E402
+    bind_user_evm_wallet,
+    create_user_evm_wallet,
+    get_user_evm_wallet_binding,
+    import_user_evm_wallet,
+    list_user_evm_wallet_bindings,
+    lock_user_evm_wallet,
+    unlock_user_evm_wallet,
+)
+from agent_wallet.providers.wdk_evm_local import WdkEvmLocalClient  # noqa: E402
+
+
+def _normalize_network(value: str) -> str:
+    network = str(value or "").strip().lower()
+    aliases = {
+        "mainnet": "ethereum",
+        "eth": "ethereum",
+        "eth-mainnet": "ethereum",
+        "base-mainnet": "base",
+        "base_sepolia": "base-sepolia",
+    }
+    network = aliases.get(network, network)
+    if network not in {"ethereum", "sepolia", "base", "base-sepolia"}:
+        return "ethereum"
+    return network
+
+
+def _paired_network(network: str) -> str | None:
+    mapping = {
+        "ethereum": "base",
+        "base": "ethereum",
+        "sepolia": "base-sepolia",
+        "base-sepolia": "sepolia",
+    }
+    return mapping.get(_normalize_network(network))
+
+
+def _read_secret(
+    *,
+    prompt: str,
+    confirm_prompt: str | None = None,
+    stdin_mode: bool = False,
+) -> str:
+    if stdin_mode:
+        value = sys.stdin.read().strip()
+        if not value:
+            raise SystemExit(f"{prompt.rstrip(':')} is required on stdin.")
+        return value
+    value = getpass(prompt)
+    if confirm_prompt is not None:
+        confirmed = getpass(confirm_prompt)
+        if value != confirmed:
+            raise SystemExit("Secrets did not match.")
+    if not value.strip():
+        raise SystemExit(f"{prompt.rstrip(':')} is required.")
+    return value.strip()
+
+
+def _read_password_and_seed_from_stdin() -> tuple[str, str]:
+    raw = sys.stdin.read().strip()
+    if not raw:
+        raise SystemExit("Password and seed phrase payload is required on stdin.")
+    lines = raw.splitlines()
+    if len(lines) < 2:
+        raise SystemExit(
+            "For import via stdin, provide password on the first line and the seed phrase on the remaining lines."
+        )
+    password = lines[0].strip()
+    seed_phrase = " ".join(line.strip() for line in lines[1:] if line.strip())
+    if not password or not seed_phrase:
+        raise SystemExit("Both password and seed phrase are required.")
+    return password, seed_phrase
+
+
+def _service_health(service_url: str | None) -> dict[str, object]:
+    target = str(service_url or "").strip()
+    if not target:
+        return {"service_url": None, "healthy": False, "error": "service_url is not configured"}
+    health_url = f"{target.rstrip('/')}/health"
+    try:
+        with urlopen(health_url, timeout=1.5) as response:
+            payload = json.loads(response.read().decode("utf-8"))
+            return {
+                "service_url": target,
+                "healthy": int(getattr(response, "status", 0) or 0) == 200,
+                "health": payload,
+            }
+    except (URLError, TimeoutError, OSError, ValueError) as exc:
+        return {"service_url": target, "healthy": False, "error": str(exc)}
+
+
+def _status_payload(user_id: str | None, network: str | None, service_url: str | None) -> dict[str, object]:
+    target_service_url = str(service_url or settings.wdk_evm_service_url).strip() or None
+    payload: dict[str, object] = {
+        "ok": True,
+        "network": _normalize_network(network or "ethereum"),
+        "service": _service_health(target_service_url),
+    }
+    target_network = _normalize_network(network or "ethereum")
+    if target_service_url:
+        try:
+            payload["network_info"] = WdkEvmLocalClient(target_service_url).get_sync("/v1/evm/network")
+        except Exception as exc:  # pragma: no cover - defensive
+            payload["network_info_error"] = str(exc)
+    if user_id:
+        payload["bindings"] = list_user_evm_wallet_bindings(user_id)
+        try:
+            payload["binding"] = get_user_evm_wallet_binding(user_id, network=target_network)
+        except Exception as exc:
+            payload["binding_error"] = str(exc)
+    return payload
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Manage a local OpenClaw EVM wallet binding")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    common_parent = argparse.ArgumentParser(add_help=False)
+    common_parent.add_argument("--network", default="ethereum")
+    common_parent.add_argument("--service-url")
+
+    get_parser = subparsers.add_parser("get", parents=[common_parent])
+    get_parser.add_argument("--user-id", required=True)
+
+    list_parser = subparsers.add_parser("list", parents=[common_parent])
+    list_parser.add_argument("--user-id", required=True)
+
+    status_parser = subparsers.add_parser("status", parents=[common_parent])
+    status_parser.add_argument("--user-id", default="")
+
+    setup_parser = subparsers.add_parser("setup", parents=[common_parent])
+    setup_parser.add_argument("--user-id", required=True)
+    setup_parser.add_argument("--label")
+    setup_parser.add_argument("--account-index", type=int)
+    setup_parser.add_argument("--password-stdin", action="store_true")
+    setup_parser.add_argument("--bind-network-pair", action=argparse.BooleanOptionalAction, default=True)
+
+    create_parser = subparsers.add_parser("create", parents=[common_parent])
+    create_parser.add_argument("--user-id", required=True)
+    create_parser.add_argument("--label")
+    create_parser.add_argument("--account-index", type=int)
+    create_parser.add_argument("--reveal-seed", action="store_true")
+    create_parser.add_argument("--password-stdin", action="store_true")
+    create_parser.add_argument("--bind-network-pair", action=argparse.BooleanOptionalAction, default=True)
+
+    import_parser = subparsers.add_parser("import", parents=[common_parent])
+    import_parser.add_argument("--user-id", required=True)
+    import_parser.add_argument("--label")
+    import_parser.add_argument("--account-index", type=int)
+    import_parser.add_argument("--password-stdin", action="store_true")
+    import_parser.add_argument("--seed-stdin", action="store_true")
+    import_parser.add_argument("--bind-network-pair", action=argparse.BooleanOptionalAction, default=True)
+
+    unlock_parser = subparsers.add_parser("unlock", parents=[common_parent])
+    unlock_parser.add_argument("--user-id", required=True)
+    unlock_parser.add_argument("--password-stdin", action="store_true")
+    unlock_parser.add_argument("--wallet-id", default="")
+    unlock_parser.add_argument("--account-index", type=int)
+    unlock_parser.add_argument("--bind-network-pair", action=argparse.BooleanOptionalAction, default=True)
+
+    lock_parser = subparsers.add_parser("lock", parents=[common_parent])
+    lock_parser.add_argument("--user-id", required=True)
+    lock_parser.add_argument("--wallet-id", default="")
+    lock_parser.add_argument("--account-index", type=int)
+
+    args = parser.parse_args()
+    effective_network = _normalize_network(args.network)
+
+    def _config_hint(wallet: dict[str, object]) -> dict[str, object]:
+        return {
+            "backend": "wdk_evm_local",
+            "network": effective_network,
+            "wdkEvmServiceUrl": args.service_url,
+            "wdkEvmWalletId": wallet.get("wallet_id"),
+            "wdkEvmAccountIndex": wallet.get("account_index"),
+        }
+
+    def _bind_pair(wallet: dict[str, object]) -> dict[str, object] | None:
+        if not getattr(args, "bind_network_pair", False):
+            return None
+        paired = _paired_network(effective_network)
+        if not paired:
+            return None
+        return bind_user_evm_wallet(
+            args.user_id,
+            wallet_id=str(wallet.get("wallet_id") or ""),
+            network=paired,
+            service_url=args.service_url,
+            account_index=wallet.get("account_index"),
+            tolerate_locked=True,
+            fallback_address=str(wallet.get("address") or "").strip() or None,
+        )
+
+    if args.command == "status":
+        payload = _status_payload(args.user_id or None, effective_network, args.service_url)
+    elif args.command == "list":
+        payload = {"ok": True, "wallets": list_user_evm_wallet_bindings(args.user_id)}
+    elif args.command == "get":
+        wallet = get_user_evm_wallet_binding(args.user_id, network=effective_network)
+        payload = {"ok": True, "wallet": wallet, "openclaw_config_hint": _config_hint(wallet)}
+    elif args.command == "setup":
+        password = _read_secret(
+            prompt="EVM wallet password: ",
+            confirm_prompt=None,
+            stdin_mode=bool(args.password_stdin),
+        )
+        try:
+            existing = get_user_evm_wallet_binding(args.user_id, network=effective_network)
+        except Exception:
+            existing = None
+
+        if existing is None:
+            wallet = create_user_evm_wallet(
+                args.user_id,
+                password=password,
+                label=args.label,
+                network=effective_network,
+                service_url=args.service_url,
+                account_index=args.account_index,
+            )
+            paired_binding = _bind_pair(wallet)
+            payload = {
+                "ok": True,
+                "action": "created",
+                "wallet": wallet,
+                "paired_binding": paired_binding,
+                "openclaw_config_hint": _config_hint(wallet),
+            }
+        else:
+            wallet = unlock_user_evm_wallet(
+                args.user_id,
+                password=password,
+                network=effective_network,
+                service_url=args.service_url,
+                account_index=args.account_index,
+            )
+            paired_binding = _bind_pair(wallet)
+            payload = {
+                "ok": True,
+                "action": "unlocked",
+                "wallet": wallet,
+                "paired_binding": paired_binding,
+                "openclaw_config_hint": _config_hint(wallet),
+            }
+    elif args.command == "create":
+        wallet = create_user_evm_wallet(
+            args.user_id,
+            password=_read_secret(
+                prompt="EVM wallet password: ",
+                confirm_prompt="Confirm EVM wallet password: ",
+                stdin_mode=bool(args.password_stdin),
+            ),
+            label=args.label,
+            network=effective_network,
+            service_url=args.service_url,
+            reveal_seed_phrase=bool(args.reveal_seed),
+            account_index=args.account_index,
+        )
+        payload = {
+            "ok": True,
+            "wallet": wallet,
+            "paired_binding": _bind_pair(wallet),
+        }
+    elif args.command == "import":
+        if args.password_stdin and args.seed_stdin:
+            password, seed_phrase = _read_password_and_seed_from_stdin()
+        else:
+            password = _read_secret(
+                prompt="EVM wallet password: ",
+                confirm_prompt="Confirm EVM wallet password: ",
+                stdin_mode=bool(args.password_stdin),
+            )
+            seed_phrase = _read_secret(
+                prompt="EVM seed phrase: ",
+                stdin_mode=bool(args.seed_stdin),
+            )
+        wallet = import_user_evm_wallet(
+            args.user_id,
+            password=password,
+            seed_phrase=seed_phrase,
+            label=args.label,
+            network=effective_network,
+            service_url=args.service_url,
+            account_index=args.account_index,
+        )
+        payload = {
+            "ok": True,
+            "wallet": wallet,
+            "paired_binding": _bind_pair(wallet),
+        }
+    elif args.command == "unlock":
+        wallet = unlock_user_evm_wallet(
+            args.user_id,
+            password=_read_secret(
+                prompt="EVM wallet password: ",
+                stdin_mode=bool(args.password_stdin),
+            ),
+            network=effective_network,
+            service_url=args.service_url,
+            wallet_id=args.wallet_id or None,
+            account_index=args.account_index,
+        )
+        payload = {
+            "ok": True,
+            "wallet": wallet,
+            "paired_binding": _bind_pair(wallet),
+        }
+    else:
+        payload = {
+            "ok": True,
+            "wallet": lock_user_evm_wallet(
+                args.user_id,
+                network=effective_network,
+                service_url=args.service_url,
+                wallet_id=args.wallet_id or None,
+                account_index=args.account_index,
+            ),
+        }
+
+    print(json.dumps(payload))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/agent-wallet/scripts/setup_evm_wallet.sh

@@ -0,0 +1,151 @@
+#!/bin/sh
+set -eu
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+PACKAGE_ROOT=$(CDPATH= cd -- "$SCRIPT_DIR/.." && pwd)
+
+resolve_python_bin() {
+  if [ -n "${OPENCLAW_AGENT_WALLET_PYTHON:-}" ] && [ -x "${OPENCLAW_AGENT_WALLET_PYTHON}" ]; then
+    printf "%s" "${OPENCLAW_AGENT_WALLET_PYTHON}"
+    return 0
+  fi
+
+  if [ -x "/tmp/agent-wallet-venv/bin/python" ]; then
+    printf "%s" "/tmp/agent-wallet-venv/bin/python"
+    return 0
+  fi
+
+  if [ -x "$PACKAGE_ROOT/.venv/bin/python" ]; then
+    printf "%s" "$PACKAGE_ROOT/.venv/bin/python"
+    return 0
+  fi
+
+  if command -v python3 >/dev/null 2>&1; then
+    command -v python3
+    return 0
+  fi
+
+  command -v python
+}
+
+PYTHON_BIN=$(resolve_python_bin)
+export OPENCLAW_AGENT_WALLET_PYTHON="$PYTHON_BIN"
+
+has_flag() {
+  flag=$1
+  shift
+  for arg in "$@"; do
+    case "$arg" in
+      "$flag"|"$flag"=*)
+        return 0
+        ;;
+    esac
+  done
+  return 1
+}
+
+prompt_with_default() {
+  label=$1
+  default_value=$2
+  if [ -t 0 ]; then
+    printf "%s [%s]: " "$label" "$default_value" >&2
+    read -r value
+    if [ -z "${value:-}" ]; then
+      printf "%s" "$default_value"
+    else
+      printf "%s" "$value"
+    fi
+    return 0
+  fi
+  printf "%s" "$default_value"
+}
+
+normalize_network_value() {
+  case $(printf "%s" "$1" | tr '[:upper:]' '[:lower:]') in
+    1|ethereum|eth|mainnet)
+      printf "ethereum"
+      ;;
+    2|base)
+      printf "base"
+      ;;
+    3|sepolia)
+      printf "sepolia"
+      ;;
+    4|base-sepolia|base_sepolia)
+      printf "base-sepolia"
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+prompt_network_choice() {
+  default_value=$1
+  if ! [ -t 0 ]; then
+    printf "%s" "$default_value"
+    return 0
+  fi
+
+  case "$default_value" in
+    ethereum) default_hint="1" ;;
+    base) default_hint="2" ;;
+    sepolia) default_hint="3" ;;
+    base-sepolia) default_hint="4" ;;
+    *) default_hint="2" ;;
+  esac
+
+  while true; do
+    printf "EVM network:\n" >&2
+    printf "  1) ethereum\n" >&2
+    printf "  2) base\n" >&2
+    printf "  3) sepolia\n" >&2
+    printf "  4) base-sepolia\n" >&2
+    printf "Choose network [%s]: " "$default_hint" >&2
+    read -r choice
+    if [ -z "${choice:-}" ]; then
+      choice=$default_hint
+    fi
+    if network=$(normalize_network_value "$choice"); then
+      printf "%s" "$network"
+      return 0
+    fi
+    printf "Invalid choice. Enter 1, 2, 3, 4, ethereum, base, sepolia, or base-sepolia.\n" >&2
+  done
+}
+
+DEFAULT_USER_ID=${OPENCLAW_EVM_USER_ID:-${USER:-openclaw-user}-local}
+DEFAULT_NETWORK=${OPENCLAW_EVM_NETWORK:-base}
+DEFAULT_SERVICE_URL=${OPENCLAW_EVM_SERVICE_URL:-http://127.0.0.1:8081}
+
+if ! has_flag --user-id "$@"; then
+  USER_ID=$(prompt_with_default "OpenClaw user id" "$DEFAULT_USER_ID")
+  set -- "$@" --user-id "$USER_ID"
+fi
+
+if ! has_flag --network "$@"; then
+  NETWORK=$(prompt_network_choice "$DEFAULT_NETWORK")
+  set -- "$@" --network "$NETWORK"
+fi
+
+if ! has_flag --service-url "$@"; then
+  set -- "$@" --service-url "$DEFAULT_SERVICE_URL"
+fi
+
+if ! has_flag --config-path "$@" && [ -n "${OPENCLAW_EVM_CONFIG_PATH:-}" ]; then
+  set -- "$@" --config-path "$OPENCLAW_EVM_CONFIG_PATH"
+fi
+
+if ! has_flag --wdk-wallet-root "$@" && [ -n "${OPENCLAW_EVM_WDK_WALLET_ROOT:-}" ]; then
+  set -- "$@" --wdk-wallet-root "$OPENCLAW_EVM_WDK_WALLET_ROOT"
+fi
+
+if ! has_flag --python-bin "$@"; then
+  set -- "$@" --python-bin "$PYTHON_BIN"
+fi
+
+if ! has_flag --package-root "$@"; then
+  set -- "$@" --package-root "$PACKAGE_ROOT"
+fi
+
+exec "$PYTHON_BIN" "$SCRIPT_DIR/bootstrap_openclaw_evm.py" "$@"

package/hermes/plugins/agent_wallet/__init__.py

@@ -1,7 +1,19 @@
 """Hermes Agent plugin bridge for AgentLayer wallet tools."""
 
-from .schemas import AGENT_WALLET_APPROVE, AGENT_WALLET_INVOKE, AGENT_WALLET_TOOLS
-from .tools import agent_wallet_approve, agent_wallet_invoke, agent_wallet_tools
+from .schemas import (
+    AGENT_WALLET_APPROVE,
+    AGENT_WALLET_EVM_SETUP,
+    AGENT_WALLET_EVM_STATUS,
+    AGENT_WALLET_INVOKE,
+    AGENT_WALLET_TOOLS,
+)
+from .tools import (
+    agent_wallet_approve,
+    agent_wallet_evm_setup,
+    agent_wallet_evm_status,
+    agent_wallet_invoke,
+    agent_wallet_tools,
+)
 
 
 def register(ctx):
@@ -27,3 +39,17 @@ def register(ctx):
         handler=agent_wallet_approve,
         description=AGENT_WALLET_APPROVE["description"],
     )
+    ctx.register_tool(
+        name=AGENT_WALLET_EVM_STATUS["name"],
+        toolset="agent_wallet",
+        schema=AGENT_WALLET_EVM_STATUS,
+        handler=agent_wallet_evm_status,
+        description=AGENT_WALLET_EVM_STATUS["description"],
+    )
+    ctx.register_tool(
+        name=AGENT_WALLET_EVM_SETUP["name"],
+        toolset="agent_wallet",
+        schema=AGENT_WALLET_EVM_SETUP,
+        handler=agent_wallet_evm_setup,
+        description=AGENT_WALLET_EVM_SETUP["description"],
+    )

package/hermes/plugins/agent_wallet/plugin.yaml

@@ -5,3 +5,5 @@ provides_tools:
   - agent_wallet_tools
   - agent_wallet_invoke
   - agent_wallet_approve
+  - agent_wallet_evm_status
+  - agent_wallet_evm_setup

package/hermes/plugins/agent_wallet/schemas.py

@@ -132,3 +132,75 @@ AGENT_WALLET_APPROVE = {
         "additionalProperties": False,
     },
 }
+
+AGENT_WALLET_EVM_STATUS = {
+    "name": "agent_wallet_evm_status",
+    "description": (
+        "Inspect the local EVM wallet runtime used by AgentLayer/OpenClaw. "
+        "Returns wdk-evm-wallet health, network info, and existing user wallet "
+        "bindings without changing wallet state."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "user_id": {
+                "type": "string",
+                "description": "Optional local wallet owner id to inspect.",
+            },
+            "network": {
+                "type": "string",
+                "description": "Optional EVM network hint, such as ethereum, base, sepolia, or base-sepolia.",
+            },
+            "service_url": {
+                "type": "string",
+                "description": "Optional localhost override for the wdk-evm-wallet service.",
+            },
+        },
+        "additionalProperties": False,
+    },
+}
+
+AGENT_WALLET_EVM_SETUP = {
+    "name": "agent_wallet_evm_setup",
+    "description": (
+        "Create or unlock the local EVM wallet binding used by AgentLayer/OpenClaw "
+        "for Hermes. This can auto-start the localhost-only wdk-evm-wallet service, "
+        "set up the selected network, and bind the same wallet to the paired EVM network "
+        "such as ethereum/base."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "password": {
+                "type": "string",
+                "description": "Local EVM wallet password used to create or unlock the vault wallet.",
+            },
+            "user_id": {
+                "type": "string",
+                "description": "Optional local wallet owner id. Defaults to AGENT_WALLET_USER_ID, USER, or hermes-local-user.",
+            },
+            "network": {
+                "type": "string",
+                "description": "Selected EVM network, typically ethereum or base.",
+            },
+            "label": {
+                "type": "string",
+                "description": "Optional wallet label used when creating a new local EVM wallet.",
+            },
+            "service_url": {
+                "type": "string",
+                "description": "Optional localhost override for the wdk-evm-wallet service.",
+            },
+            "auto_start_service": {
+                "type": "boolean",
+                "description": "Whether to auto-start the local wdk-evm-wallet service when it is not healthy. Defaults to true.",
+            },
+            "bind_network_pair": {
+                "type": "boolean",
+                "description": "Whether to also bind the paired EVM network such as ethereum/base. Defaults to true.",
+            },
+        },
+        "required": ["password"],
+        "additionalProperties": False,
+    },
+}

package/hermes/plugins/agent_wallet/tools.py

@@ -174,6 +174,13 @@ def _python_bin(package_root: Path) -> str:
     return "python3"
 
 
+def _script_path(package_root: Path, name: str) -> Path:
+    script = package_root / "scripts" / name
+    if not script.exists():
+        raise RuntimeError(f"Required host script is missing: {script}")
+    return script
+
+
 def _user_id(args: dict[str, Any]) -> str:
     value = (
         args.get("user_id")
@@ -277,6 +284,37 @@ def _call_wallet_cli(args: dict[str, Any]) -> dict[str, Any]:
         return {"ok": False, "error": f"wallet CLI returned invalid JSON: {exc}"}
 
 
+def _run_host_script(
+    package_root: Path,
+    script_name: str,
+    script_args: list[str],
+    *,
+    stdin_text: str | None = None,
+) -> dict[str, Any]:
+    command = [
+        _python_bin(package_root),
+        str(_script_path(package_root, script_name)),
+        *script_args,
+    ]
+    completed = subprocess.run(
+        command,
+        cwd=str(package_root),
+        env=_cli_env(package_root),
+        text=True,
+        input=stdin_text,
+        capture_output=True,
+        timeout=float(os.getenv("AGENT_WALLET_HERMES_TIMEOUT", "120")),
+        check=False,
+    )
+    if completed.returncode != 0:
+        detail = completed.stderr.strip() or completed.stdout.strip()
+        return {"ok": False, "error": detail or f"host script exited {completed.returncode}"}
+    try:
+        return json.loads(completed.stdout.strip() or "{}")
+    except json.JSONDecodeError as exc:
+        return {"ok": False, "error": f"host script returned invalid JSON: {exc}"}
+
+
 def _call_issue_approval(args: dict[str, Any]) -> dict[str, Any]:
     if args.get("user_confirmed") is not True:
         raise RuntimeError(
@@ -337,6 +375,54 @@ def _call_issue_approval(args: dict[str, Any]) -> dict[str, Any]:
         return {"ok": False, "error": f"wallet CLI returned invalid JSON: {exc}"}
 
 
+def _call_evm_status(args: dict[str, Any]) -> dict[str, Any]:
+    package_root = _resolve_package_root()
+    command = ["status"]
+    user_id = str(args.get("user_id") or "").strip()
+    network = str(args.get("network") or "").strip()
+    service_url = str(args.get("service_url") or "").strip()
+    if user_id:
+        command.extend(["--user-id", user_id])
+    if network:
+        command.extend(["--network", network])
+    if service_url:
+        command.extend(["--service-url", service_url])
+    return _run_host_script(package_root, "manage_openclaw_evm_wallet.py", command)
+
+
+def _call_evm_setup(args: dict[str, Any]) -> dict[str, Any]:
+    package_root = _resolve_package_root()
+    password = str(args.get("password") or "").strip()
+    if not password:
+        raise RuntimeError("password is required.")
+    command = [
+        "--user-id",
+        _user_id(args),
+        "--password-stdin",
+    ]
+    network = str(args.get("network") or "").strip()
+    label = str(args.get("label") or "").strip()
+    service_url = str(args.get("service_url") or "").strip()
+    auto_start_service = args.get("auto_start_service")
+    bind_network_pair = args.get("bind_network_pair")
+    if network:
+        command.extend(["--network", network])
+    if label:
+        command.extend(["--label", label])
+    if service_url:
+        command.extend(["--service-url", service_url])
+    if auto_start_service is False:
+        command.append("--no-auto-start-service")
+    if bind_network_pair is False:
+        command.append("--no-bind-network-pair")
+    return _run_host_script(
+        package_root,
+        "bootstrap_openclaw_evm.py",
+        command,
+        stdin_text=f"{password}\n",
+    )
+
+
 class _SchemaOnlyBackend:
     def __init__(self, *, name: str, chain: str, network: str):
         self.name = name
@@ -431,3 +517,17 @@ def agent_wallet_approve(args: dict, **kwargs) -> str:
         return _json(_call_issue_approval(args or {}))
     except Exception as exc:
         return _json({"ok": False, "error": str(exc)})
+
+
+def agent_wallet_evm_status(args: dict, **kwargs) -> str:
+    try:
+        return _json(_call_evm_status(args or {}))
+    except Exception as exc:
+        return _json({"ok": False, "error": str(exc)})
+
+
+def agent_wallet_evm_setup(args: dict, **kwargs) -> str:
+    try:
+        return _json(_call_evm_setup(args or {}))
+    except Exception as exc:
+        return _json({"ok": False, "error": str(exc)})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentlayer.tech/wallet",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "NPM installer for the OpenClaw Agent Wallet local runtime.",
   "type": "module",
   "repository": {