@agentlayer.tech/wallet 0.1.11 → 0.1.13

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

@@ -1,9 +1,18 @@
 ![AgentLayer](logo+name.png)
-# AgentLayer
+
+
+[![npm version](https://img.shields.io/npm/v/%40agentlayer.tech%2Fwallet)](https://www.npmjs.com/package/@agentlayer.tech/wallet)
+[![npm downloads](https://img.shields.io/npm/dm/%40agentlayer.tech%2Fwallet)](https://www.npmjs.com/package/@agentlayer.tech/wallet)
+[![license](https://img.shields.io/github/license/lopushok9/Agent-Layer)](https://github.com/lopushok9/Agent-Layer/blob/main/LICENSE)
 
 ```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 +101,10 @@ sh agent-wallet/scripts/setup_btc_wallet.sh
 EVM:
 
 ```bash
-cd wdk-evm-wallet && sh run-local.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"}'
+sh agent-wallet/scripts/setup_evm_wallet.sh
 ```
 
-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 +140,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
@@ -198,6 +197,16 @@ For Solana specifically, install alone does not make signed transactions availab
 - read-only mode: `SOLANA_AGENT_PUBLIC_KEY`
 - signing mode: a sealed `private_key` or `SOLANA_AGENT_KEYPAIR_PATH`
 
+Optional private Solana payout routing is also available through Houdini. To enable it, add the Houdini partner credentials to the wallet runtime:
+
+- `HOUDINI_API_KEY`
+- `HOUDINI_API_SECRET`
+- `HOUDINI_USER_IP`
+
+The first supported flow is intentionally narrow: same-token private Solana payouts (`SOL->SOL` and `USDC->USDC`) through the existing preview/prepare/execute safety model. The runtime binds execute to the approved Houdini `quoteId`, creates a single private exchange, and then sends the exact deposit locally from the wallet. That removes the extra Solana batch-tx relay step and keeps signing local.
+
+For production, prefer placing the Houdini partner secrets on `provider-gateway` and exposing only the authenticated Houdini relay endpoints to `agent-wallet`. That keeps `HOUDINI_API_KEY` and `HOUDINI_API_SECRET` out of end-user runtimes while preserving local signing.
+
 ## BTC setup
 
 The BTC path already has a one-command host bootstrap wrapper:
@@ -229,49 +238,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/.env.example

@@ -54,6 +54,17 @@ LIFI_API_KEY=
 LIFI_INTEGRATOR=openclaw
 LIFI_DEFAULT_DENY_BRIDGES=mayan
 
+# Houdini Partner API for private Solana payouts.
+# HOUDINI_USER_IP is required because Houdini rejects requests without compliance headers.
+# If PROVIDER_GATEWAY_URL points at a gateway with Houdini enabled,
+# the wallet runtime can omit these partner secrets and route through the gateway instead.
+HOUDINI_API_BASE_URL=https://api-partner.houdiniswap.com/v2
+HOUDINI_API_KEY=
+HOUDINI_API_SECRET=
+HOUDINI_USER_IP=
+HOUDINI_USER_AGENT=AgentLayer/0.1.12
+HOUDINI_USER_TIMEZONE=UTC
+
 # Kamino REST lending
 KAMINO_API_BASE_URL=https://api.kamino.finance
 KAMINO_PROGRAM_ID=KLend2g3cP87fffoy8q1mQqGKjrxjC8boSyAYavgmjD

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`
@@ -80,6 +89,8 @@ Current safe tools:
 - `stake_sol_native`
 - `transfer_spl_token`
 - `swap_solana_tokens`
+- `swap_solana_privately` - Houdini-backed private Solana payout flow for same-token `SOL->SOL` or `USDC->USDC` transfers to a destination wallet.
+- `get_solana_private_swap_status`
 - `get_jupiter_earn_tokens`
 - `get_jupiter_earn_positions`
 - `get_jupiter_earn_earnings`
@@ -107,6 +118,8 @@ Temporarily disabled but kept in the codebase for later re-enable:
 The signing tool still requires explicit `user_confirmed=true`.
 Transfer, native staking, swap, and Aave position-management tools support `preview`, `prepare`, and `execute` modes. The safe operational path is still preview-first. `prepare` now returns an execution plan only and never exposes signed transaction bytes to the agent. `execute` works only when the backend has a signer and `sign_only=false`.
 
+Exception: `swap_solana_privately` is intentionally optimized for `preview -> execute`. Hosts should not insert a separate `prepare` step for Houdini private payouts because it adds no execution value and only burns additional provider quota.
+
 Policy defaults:
 
 - read-only tools are always allowed
@@ -176,6 +189,30 @@ For production `mainnet`, prefer a dedicated RPC instead of the public Solana en
 
 Production recommendation: treat RPC as deployment-owned config, not wallet logic. Runtime env wins over `openclaw.json` plugin config, so keep `Alchemy/Helius/QuickNode` endpoints in deployment secrets or service env and use plugin `rpcUrl` / `rpcUrls` only as local fallback.
 
+For Houdini-backed private Solana payouts, also provide:
+
+- `HOUDINI_API_KEY`
+- `HOUDINI_API_SECRET`
+- `HOUDINI_USER_IP`
+- optional `HOUDINI_USER_AGENT`
+- optional `HOUDINI_USER_TIMEZONE`
+
+The current MVP intentionally keeps the scope narrow:
+
+- supported private routes are same-token Solana payouts only
+- `SOL -> SOL`
+- `USDC -> USDC`
+- execution binds to the approved Houdini `quoteId`, creates a single private exchange, and sends the exact Solana deposit locally from the wallet
+
+This is a private payout flow expressed in Houdini's swap terminology. Cross-token private swaps can be added later without changing the OpenClaw/Hermes approval model.
+
+For production, the cleaner setup is to place Houdini partner secrets on `provider-gateway` and let `agent-wallet` consume the narrow gateway endpoints through `PROVIDER_GATEWAY_URL` and optional `PROVIDER_GATEWAY_BEARER_TOKEN`. In that mode:
+
+- the gateway owns `HOUDINI_API_KEY` / `HOUDINI_API_SECRET`
+- the gateway derives the authoritative user IP from ingress
+- `agent-wallet` still performs preview/prepare/execute, local transaction verification, signing, and broadcast
+- direct Houdini env vars can be omitted from the wallet runtime
+
 For OpenClaw onboarding, `agent-wallet` now ships with a hosted default provider gateway:
 
 - `https://agent-layer-production.up.railway.app`
@@ -375,6 +412,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
@@ -512,6 +564,7 @@ Public-safe helper scripts are available in `agent-wallet/scripts/`:
 - `finalize_openclaw_local_wallet_config.py`
 
 Both scripts now use generic defaults instead of hardcoded local usernames or paths. Sensitive secrets must be supplied via protected environment variables, not config JSON or CLI arguments.
+When `~/.openclaw/agent-wallet-runtime/current` exists, the config installer now prefers that trusted runtime path over a workspace checkout for the plugin manifest, package root, and Python bridge launcher.
 
 Recommended devnet setup:
 

package/agent-wallet/agent_wallet/approval.py

@@ -3,9 +3,11 @@
 from __future__ import annotations
 
 import base64
+import functools
 import hashlib
 import hmac
 import json
+import secrets
 import time
 from typing import Any
 
@@ -33,6 +35,7 @@ def _sign_payload(payload: dict[str, Any], secret: str) -> str:
     return _urlsafe_b64(digest)
 
 
+@functools.lru_cache(maxsize=1)
 def _approval_secret() -> str:
     secret = resolve_approval_secret().strip()
     if not secret:
@@ -70,6 +73,7 @@ def issue_approval_token(
         "v": APPROVAL_TOKEN_VERSION,
         "iat": now,
         "exp": now + ttl,
+        "jti": secrets.token_urlsafe(16),
         "issued_by": issued_by,
         "binding": build_operation_binding(tool_name=tool_name, network=network, summary=summary),
         "mainnet_confirmed": bool(mainnet_confirmed),

package/agent-wallet/agent_wallet/config.py

@@ -54,6 +54,12 @@ class Settings(BaseSettings):
     lifi_api_key: str = ""
     lifi_integrator: str = "openclaw"
     lifi_default_deny_bridges: str = "mayan"
+    houdini_api_base_url: str = "https://api-partner.houdiniswap.com/v2"
+    houdini_api_key: str = ""
+    houdini_api_secret: str = ""
+    houdini_user_ip: str = ""
+    houdini_user_agent: str = "AgentLayer/0.1.12"
+    houdini_user_timezone: str = "UTC"
     kamino_api_base_url: str = "https://api.kamino.finance"
     kamino_program_id: str = "KLend2g3cP87fffoy8q1mQqGKjrxjC8boSyAYavgmjD"
     alchemy_api_key: str = ""

package/agent-wallet/agent_wallet/exceptions.py

@@ -4,6 +4,7 @@
 class ProviderError(Exception):
     """A provider failed to return data."""
 
-    def __init__(self, provider: str, message: str):
+    def __init__(self, provider: str, message: str, *, details: dict | None = None):
         self.provider = provider
+        self.details = dict(details) if isinstance(details, dict) else None
         super().__init__(f"[{provider}] {message}")