@agentlayer.tech/wallet 0.1.10 → 0.1.12

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+- Added an optional Hermes Agent bridge plugin under `hermes/plugins/agent_wallet`
+  that forwards into the existing Python wallet CLI instead of duplicating
+  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
@@ -10,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,13 +1,21 @@
 ![AgentLayer](logo+name.png)
-
 # AgentLayer
 
+```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:
 
 - `agent-wallet/` - the main wallet backend for AgentLayer
 - `.openclaw/` - the local AgentLayer bridge layer
+- `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
 - `provider-gateway/` - shared provider access for Solana RPC, Bags, and related finance reads
@@ -33,12 +41,6 @@ System prerequisites:
 - `node`
 - `npm`
 
-Install from the latest GitHub release bundle:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/lopushok9/Agent-Layer/main/install-from-github.sh | sh
-```
-
 Install through npm:
 
 ```bash
@@ -66,6 +68,7 @@ Useful npm CLI commands:
 ```bash
 wallet status
 wallet doctor
+wallet hermes install --yes
 wallet update --yes
 wallet rollback
 ```
@@ -94,28 +97,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`:
 
@@ -143,9 +128,33 @@ Without those secrets, the installer still lays down the runtime and installs de
 }
 ```
 
+## Connect Hermes Agent
+
+OpenClaw remains the primary local environment, but the repo also ships an optional Hermes Agent bridge at:
+
+```bash
+hermes/plugins/agent_wallet
+```
+
+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
+```
+
+That command installs the Hermes plugin, runs `hermes plugins enable agent-wallet`, writes non-secret runtime paths into `~/.hermes/.env`, and points Hermes at a local boot-key file. Secrets stay in the existing protected OpenClaw runtime paths, especially `~/.openclaw/sealed_keys.json`; do not put wallet secrets into Hermes tool config.
+
 ## What you get after install
 
-If you install from GitHub release, the bundle is extracted under:
+If you install through npm, the runtime is extracted under:
 
 ```bash
 ~/.openclaw/agent-wallet-runtime/current
@@ -159,6 +168,7 @@ The installer then does the following:
 - creates a minimal `~/.openclaw/openclaw.json` if one does not exist
 - if the required secrets are already present, writes or updates `~/.openclaw/sealed_keys.json`
 - if the required secrets are already present, patches `~/.openclaw/openclaw.json` to load the `agent-wallet` extension and point it at the installed runtime
+- `wallet hermes install --yes` additionally connects Hermes Agent to the same runtime without copying wallet tools or policy
 
 When the installer reaches the final config step, the default plugin config is:
 
@@ -214,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

@@ -18,6 +18,7 @@ The package now includes a thin adapter for agent runtimes:
 - `agent_wallet.plugin_bundle.build_openclaw_plugin_bundle`
 - `agent_wallet.openclaw_runtime.onboard_openclaw_user_wallet`
 - `agent_wallet.openclaw_cli` for the official OpenClaw TypeScript plugin bridge
+- `hermes/plugins/agent_wallet` as an optional Hermes Agent bridge to the same CLI
 
 It provides:
 
@@ -27,6 +28,32 @@ It provides:
 - OpenClaw-style plugin manifest and skill bundle
 - explicit network-aware results so the host and agent can see `devnet` vs `mainnet`
 
+## Hermes integration
+
+The optional Hermes plugin is intentionally a bridge, not a port of the OpenClaw plugin. It registers:
+
+- `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:
+
+```bash
+npx @agentlayer.tech/wallet hermes install --yes
+```
+
+That command symlinks `hermes/plugins/agent_wallet` into `~/.hermes/plugins/agent_wallet`, enables the plugin with `hermes plugins enable agent-wallet`, and writes `AGENT_WALLET_PACKAGE_ROOT`, `AGENT_WALLET_PYTHON`, and `AGENT_WALLET_BOOT_KEY_FILE` into `~/.hermes/.env`. OpenClaw remains the canonical host integration and wallet safety policy remains in Python.
+
+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`
@@ -357,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/agent_wallet/config.py

@@ -13,6 +13,7 @@ class Settings(BaseSettings):
     agent_wallet_backend: str = "none"
     agent_wallet_sign_only: bool = False
     agent_wallet_boot_key: str = ""
+    agent_wallet_boot_key_file: str = ""
     agent_wallet_approval_ttl_seconds: int = 600
     agent_wallet_per_user_key_derivation: bool = True
     agent_wallet_encrypt_user_wallets: bool = True
@@ -297,7 +298,16 @@ def _env_bool(name: str, default: bool) -> bool:
 
 def resolve_boot_key() -> str:
     """Resolve the boot key used to unlock sealed secrets from disk."""
-    return os.getenv("AGENT_WALLET_BOOT_KEY", settings.agent_wallet_boot_key).strip()
+    direct = os.getenv("AGENT_WALLET_BOOT_KEY", settings.agent_wallet_boot_key).strip()
+    if direct:
+        return direct
+    key_file = os.getenv("AGENT_WALLET_BOOT_KEY_FILE", settings.agent_wallet_boot_key_file).strip()
+    if not key_file:
+        return ""
+    try:
+        return Path(key_file).expanduser().read_text(encoding="utf-8").strip()
+    except OSError:
+        return ""
 
 
 def _reject_legacy_runtime_secret_env(var_name: str) -> None:

package/agent-wallet/agent_wallet/openclaw_adapter.py

@@ -11,6 +11,14 @@ from agent_wallet.models import AgentToolResult, AgentToolSpec
 from agent_wallet.wallet_layer.base import AgentWalletBackend, WalletBackendError
 
 
+def _canonical_json_text(payload: dict[str, Any]) -> str:
+    return json.dumps(payload, sort_keys=True, separators=(",", ":"))
+
+
+def preview_payload_digest(preview: dict[str, Any]) -> str:
+    return hashlib.sha256(_canonical_json_text(preview).encode("utf-8")).hexdigest()
+
+
 WALLET_RUNTIME_INSTRUCTIONS = """
 Use wallet tools only when the user explicitly asks for wallet-related actions.
 Treat any signing request as sensitive.
@@ -4398,19 +4406,76 @@ class OpenClawWalletAdapter:
                         ),
                     )
 
-                execute_preview = await self.backend.preview_swap(
-                    input_mint=input_mint.strip(),
-                    output_mint=output_mint.strip(),
-                    amount_ui=float(amount),
-                    slippage_bps=slippage_bps,
+                approval_payload = inspect_approval_token(
+                    approval_token,
+                    tool_name=tool_name,
+                    network=str(getattr(self.backend, "network", "unknown")),
+                    require_mainnet_confirmation=self._is_mainnet_for_backend(self.backend),
                 )
+                approval_summary = approval_payload.get("binding", {}).get("summary")
+                if not isinstance(approval_summary, dict):
+                    raise WalletBackendError(
+                        "approval_token does not match the requested operation. Generate a new approval after previewing the exact action."
+                    )
+                expected_summary = {
+                    "operation": "Swap",
+                    "network": str(getattr(self.backend, "network", "unknown")),
+                    "input_mint": input_mint.strip(),
+                    "output_mint": output_mint.strip(),
+                    "slippage_bps": slippage_bps,
+                }
+                for key, expected_value in expected_summary.items():
+                    if approval_summary.get(key) != expected_value:
+                        raise WalletBackendError(
+                            "approval_token does not match the requested operation. Generate a new approval after previewing the exact action."
+                        )
+                try:
+                    approved_amount = float(approval_summary.get("input_amount_ui"))
+                except (TypeError, ValueError):
+                    raise WalletBackendError(
+                        "approval_token does not match the requested operation. Generate a new approval after previewing the exact action."
+                    )
+                if approved_amount != float(amount):
+                    raise WalletBackendError(
+                        "approval_token does not match the requested operation. Generate a new approval after previewing the exact action."
+                    )
+
+                approval_summary_copy = dict(approval_summary)
+                approved_preview = args.get("_approved_preview")
+                if isinstance(approval_summary_copy.get("_preview_digest"), str):
+                    if not isinstance(approved_preview, dict):
+                        raise WalletBackendError(
+                            "Approved swap preview payload is required for execute mode. Generate a new preview and approval before execute."
+                        )
+                    if preview_payload_digest(approved_preview) != approval_summary_copy["_preview_digest"]:
+                        raise WalletBackendError(
+                            "approved preview payload does not match the approval token. Generate a new preview and approval before execute."
+                        )
+                    preview_summary = self._build_confirmation_summary(
+                        action_label="Swap",
+                        payload=approved_preview,
+                    )
+                    summary_without_digest = {
+                        key: value
+                        for key, value in approval_summary_copy.items()
+                        if key != "_preview_digest"
+                    }
+                    if preview_summary != summary_without_digest:
+                        raise WalletBackendError(
+                            "approved preview payload does not match the approval token. Generate a new preview and approval before execute."
+                        )
+                    execute_preview = dict(approved_preview)
+                else:
+                    execute_preview = await self.backend.preview_swap(
+                        input_mint=input_mint.strip(),
+                        output_mint=output_mint.strip(),
+                        amount_ui=float(amount),
+                        slippage_bps=slippage_bps,
+                    )
                 self._require_execute_approval(
                     approval_token=approval_token,
                     tool_name=tool_name,
-                    summary=self._build_confirmation_summary(
-                        action_label="Swap",
-                        payload=execute_preview,
-                    ),
+                    summary=approval_summary_copy,
                     action_label="Swap",
                 )
 

package/agent-wallet/agent_wallet/providers/jupiter.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import json
 import os
 from typing import Any
 
@@ -54,6 +55,38 @@ def _gateway_route_missing(status_code: int, payload: Any) -> bool:
     return False
 
 
+async def _gateway_get(path_suffix: str, *, params: dict[str, Any] | None = None) -> tuple[int, Any]:
+    """Make a GET request through provider gateway."""
+    client = get_client()
+    response = await client.get(
+        f"{_gateway_base_url()}/v1/jupiter/swap/{path_suffix}",
+        params=params,
+        headers=_gateway_headers(),
+    )
+    if not response.content:
+        return response.status_code, {}
+    try:
+        return response.status_code, response.json()
+    except ValueError:
+        return response.status_code, response.text[:500]
+
+
+async def _gateway_post(path_suffix: str, *, body: dict[str, Any]) -> tuple[int, Any]:
+    """Make a POST request through provider gateway."""
+    client = get_client()
+    response = await client.post(
+        f"{_gateway_base_url()}/v1/jupiter/swap/{path_suffix}",
+        json=body,
+        headers={**_gateway_headers(), "Content-Type": "application/json"},
+    )
+    if not response.content:
+        return response.status_code, {}
+    try:
+        return response.status_code, response.json()
+    except ValueError:
+        return response.status_code, response.text[:500]
+
+
 def _direct_jupiter_enabled() -> bool:
     return bool(settings.jupiter_api_key.strip())
 
@@ -187,7 +220,58 @@ async def fetch_quote(
     only_direct_routes: bool = False,
     swap_mode: str = "ExactIn",
 ) -> dict[str, Any]:
-    """Fetch a Jupiter quote for an exact-in swap."""
+    """Fetch a Jupiter quote for an exact-in swap.
+
+    Tries direct Jupiter API first. On free-tier errors (TOKEN_NOT_TRADABLE,
+    NOT_SUPPORTED) falls back to provider gateway when configured.
+    """
+    # Try direct first
+    try:
+        return await _fetch_quote_direct(
+            input_mint=input_mint,
+            output_mint=output_mint,
+            amount_raw=amount_raw,
+            slippage_bps=slippage_bps,
+            restrict_intermediate_tokens=restrict_intermediate_tokens,
+            only_direct_routes=only_direct_routes,
+            swap_mode=swap_mode,
+        )
+    except ProviderError as exc:
+        error_msg = str(exc).lower()
+        # Only fall back for known free-tier limitations
+        gateway_fallback_errors = (
+            "not tradable",
+            "token_not_tradable",
+            "not supported",
+            "restrict_intermediate_tokens",
+        )
+        if not any(phrase in error_msg for phrase in gateway_fallback_errors):
+            raise
+        if not _gateway_enabled():
+            raise
+        # Retry via gateway with relaxed restrictions
+        return await _fetch_quote_via_gateway(
+            input_mint=input_mint,
+            output_mint=output_mint,
+            amount_raw=amount_raw,
+            slippage_bps=slippage_bps,
+            restrict_intermediate_tokens=False,
+            only_direct_routes=only_direct_routes,
+            swap_mode=swap_mode,
+        )
+
+
+async def _fetch_quote_direct(
+    *,
+    input_mint: str,
+    output_mint: str,
+    amount_raw: int,
+    slippage_bps: int = 50,
+    restrict_intermediate_tokens: bool = True,
+    only_direct_routes: bool = False,
+    swap_mode: str = "ExactIn",
+) -> dict[str, Any]:
+    """Fetch a Jupiter quote directly from Jupiter API."""
     client = get_client()
     params = {
         "inputMint": input_mint,
@@ -211,6 +295,38 @@ async def fetch_quote(
     return data
 
 
+async def _fetch_quote_via_gateway(
+    *,
+    input_mint: str,
+    output_mint: str,
+    amount_raw: int,
+    slippage_bps: int = 50,
+    restrict_intermediate_tokens: bool = False,
+    only_direct_routes: bool = False,
+    swap_mode: str = "ExactIn",
+) -> dict[str, Any]:
+    """Fetch a Jupiter quote via provider gateway (uses API key)."""
+    params: dict[str, Any] = {
+        "inputMint": input_mint,
+        "outputMint": output_mint,
+        "amount": str(amount_raw),
+        "slippageBps": str(slippage_bps),
+        "swapMode": swap_mode,
+    }
+    if only_direct_routes:
+        params["onlyDirectRoutes"] = "true"
+
+    status_code, payload = await _gateway_get("quote", params=params)
+    if status_code != 200:
+        error_msg = payload if isinstance(payload, str) else json.dumps(payload)
+        raise ProviderError("jupiter-gateway", f"HTTP {status_code}: {error_msg}")
+    if isinstance(payload, dict) and payload.get("errorCode"):
+        raise ProviderError("jupiter-gateway", str(payload.get("error") or payload.get("errorCode")))
+    if not isinstance(payload, dict) or "outAmount" not in payload:
+        raise ProviderError("jupiter-gateway", "Unexpected quote response from gateway.")
+    return payload
+
+
 async def fetch_ultra_order(
     *,
     input_mint: str,
@@ -257,7 +373,35 @@ async def build_swap_transaction(
     quote_response: dict[str, Any],
     wrap_and_unwrap_sol: bool = True,
 ) -> dict[str, Any]:
-    """Build a serialized swap transaction from a Jupiter quote."""
+    """Build a serialized swap transaction from a Jupiter quote.
+
+    Tries direct Jupiter API first. Falls back to provider gateway on error.
+    """
+    # Try direct first
+    try:
+        return await _build_swap_direct(
+            user_public_key=user_public_key,
+            quote_response=quote_response,
+            wrap_and_unwrap_sol=wrap_and_unwrap_sol,
+        )
+    except ProviderError as exc:
+        if not _gateway_enabled():
+            raise
+        # Fall back to gateway
+        return await _build_swap_via_gateway(
+            user_public_key=user_public_key,
+            quote_response=quote_response,
+            wrap_and_unwrap_sol=wrap_and_unwrap_sol,
+        )
+
+
+async def _build_swap_direct(
+    *,
+    user_public_key: str,
+    quote_response: dict[str, Any],
+    wrap_and_unwrap_sol: bool = True,
+) -> dict[str, Any]:
+    """Build a swap transaction directly via Jupiter API."""
     client = get_client()
     body = {
         "userPublicKey": user_public_key,
@@ -279,6 +423,31 @@ async def build_swap_transaction(
     return data
 
 
+async def _build_swap_via_gateway(
+    *,
+    user_public_key: str,
+    quote_response: dict[str, Any],
+    wrap_and_unwrap_sol: bool = True,
+) -> dict[str, Any]:
+    """Build a swap transaction via provider gateway (uses API key)."""
+    body = {
+        "userPublicKey": user_public_key,
+        "quoteResponse": quote_response,
+        "wrapAndUnwrapSol": wrap_and_unwrap_sol,
+        "dynamicComputeUnitLimit": True,
+        "prioritizationFeeLamports": "auto",
+    }
+    status_code, payload = await _gateway_post("swap", body=body)
+    if status_code != 200:
+        error_msg = payload if isinstance(payload, str) else json.dumps(payload)
+        raise ProviderError("jupiter-gateway", f"HTTP {status_code}: {error_msg}")
+    if isinstance(payload, dict) and payload.get("errorCode"):
+        raise ProviderError("jupiter-gateway", str(payload.get("error") or payload.get("errorCode")))
+    if not isinstance(payload, dict) or "swapTransaction" not in payload:
+        raise ProviderError("jupiter-gateway", "Unexpected swap response from gateway.")
+    return payload
+
+
 async def execute_ultra_order(
     *,
     signed_transaction_base64: str,

package/agent-wallet/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "openclaw-agent-wallet"
-version = "0.1.10"
+version = "0.1.12"
 description = "Plugin-friendly wallet backend for OpenClaw agents"
 requires-python = ">=3.10"
 dependencies = [
@@ -14,6 +14,7 @@ dependencies = [
     "pynacl>=1.5.0",
     "python-dotenv>=1.0.0",
     "solana>=0.36.0",
+    "solders>=0.27.0",
 ]
 
 [project.optional-dependencies]