@agentlayer.tech/wallet 0.1.12 → 0.1.13

package/README.md

@@ -1,5 +1,9 @@
 ![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
@@ -193,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:

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

@@ -89,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`
@@ -116,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
@@ -185,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`
@@ -536,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}")

package/agent-wallet/agent_wallet/openclaw_adapter.py

@@ -265,6 +265,27 @@ class OpenClawWalletAdapter:
                 "transaction_data_hash": payload.get("transaction_data_hash"),
             }
 
+        if asset_type == "solana-private-swap":
+            return {
+                "operation": action_label,
+                "network": str(payload.get("network") or getattr(self.backend, "network", "unknown")),
+                "swap_provider": payload.get("source") or "houdini",
+                "owner": payload.get("owner"),
+                "destination_address": payload.get("destination_address"),
+                "input_token_id": payload.get("input_token_id"),
+                "output_token_id": payload.get("output_token_id"),
+                "input_token_symbol": payload.get("input_token_symbol"),
+                "output_token_symbol": payload.get("output_token_symbol"),
+                "input_token_address": payload.get("input_token_address"),
+                "output_token_address": payload.get("output_token_address"),
+                "input_amount_ui": payload.get("input_amount_ui"),
+                "estimated_output_amount_ui": payload.get("estimated_output_amount_ui"),
+                "private_duration_minutes": payload.get("private_duration_minutes"),
+                "quote_id": payload.get("quote_id"),
+                "anonymous": payload.get("anonymous"),
+                "use_xmr": payload.get("use_xmr"),
+            }
+
         if asset_type == "evm-lifi-cross-chain-swap":
             return {
                 "operation": action_label,
@@ -644,8 +665,8 @@ class OpenClawWalletAdapter:
         )
         annotated["confirmation_requirements"] = {
             "prepare_requires_user_intent": mode == "prepare",
-            "execute_requires_approval_token": mode == "execute",
-            "execute_requires_mainnet_confirmed_in_token": mode == "execute" and is_mainnet,
+            "execute_requires_approval_token": True,
+            "execute_requires_mainnet_confirmed_in_token": is_mainnet,
         }
         if mode == "preview":
             annotated["approval_hint"] = {
@@ -2154,6 +2175,112 @@ class OpenClawWalletAdapter:
                 )
             )
 
+            tools.append(
+                AgentToolSpec(
+                    name="swap_solana_privately",
+                    description=(
+                        "Preview or create a Solana private payout through Houdini's anonymous routing. "
+                        "The initial implementation supports same-token private payouts only, such as SOL->SOL or USDC->USDC. "
+                        "Use preview first, then execute after explicit approval. "
+                        "The first execute creates the Houdini order and returns the deposit address; use continue_solana_private_swap to submit the funding transfer."
+                    ),
+                    input_schema={
+                        "type": "object",
+                        "properties": {
+                            "input_token": {
+                                "type": "string",
+                                "description": "Source Solana token identifier. Symbol, name, mint address, or Houdini token id.",
+                            },
+                            "output_token": {
+                                "type": "string",
+                                "description": "Destination Solana token identifier. For the initial implementation, this must resolve to the same token as input_token.",
+                            },
+                            "destination_address": {
+                                "type": "string",
+                                "description": "Destination Solana wallet address that should receive the privately routed payout.",
+                            },
+                            "amount": {
+                                "type": "number",
+                                "description": "Input token amount in UI units.",
+                            },
+                            "use_xmr": {
+                                "type": "boolean",
+                                "description": "Optional. Force Houdini's XMR privacy hop when available.",
+                            },
+                            "mode": {
+                                "type": "string",
+                                "enum": ["preview", "execute"],
+                            },
+                            "purpose": {"type": "string"},
+                            "user_intent": {"type": "boolean"},
+                            "approval_token": {"type": "string"},
+                        },
+                        "required": [
+                            "input_token",
+                            "output_token",
+                            "destination_address",
+                            "amount",
+                            "mode",
+                            "purpose",
+                        ],
+                        "additionalProperties": False,
+                    },
+                    read_only=False,
+                    requires_explicit_user_intent=True,
+                    risk_level="high",
+                )
+            )
+
+            tools.append(
+                AgentToolSpec(
+                    name="continue_solana_private_swap",
+                    description=(
+                        "Continue a previously created Houdini Solana private payout and submit the funding transfer "
+                        "to the saved deposit address. Use this only after swap_solana_privately execute has returned "
+                        "a pending order with deposit address details."
+                    ),
+                    input_schema={
+                        "type": "object",
+                        "properties": {
+                            "houdini_id": {
+                                "type": "string",
+                                "description": "Optional Houdini order id for the pending private payout. If omitted, the host may use the latest cached pending order.",
+                            },
+                            "approval_token": {
+                                "type": "string",
+                                "description": "Approval token issued from the original private swap preview.",
+                            },
+                        },
+                        "required": ["approval_token"],
+                        "additionalProperties": False,
+                    },
+                    read_only=False,
+                    requires_explicit_user_intent=True,
+                    risk_level="high",
+                )
+            )
+
+            tools.append(
+                AgentToolSpec(
+                    name="get_solana_private_swap_status",
+                    description=(
+                        "Check Houdini status for a Solana private payout created by swap_solana_privately. "
+                        "Use houdini_id from the execute result. multi_id is still accepted for legacy multi-order flows."
+                    ),
+                    input_schema={
+                        "type": "object",
+                        "properties": {
+                            "multi_id": {"type": "string"},
+                            "houdini_id": {"type": "string"},
+                        },
+                        "anyOf": [{"required": ["multi_id"]}, {"required": ["houdini_id"]}],
+                        "additionalProperties": False,
+                    },
+                    read_only=True,
+                    risk_level="low",
+                )
+            )
+
             tools.append(
                 AgentToolSpec(
                     name="claim_bags_fees",
@@ -4490,6 +4617,238 @@ class OpenClawWalletAdapter:
                     ),
                 )
 
+            if tool_name == "swap_solana_privately":
+                input_token = args.get("input_token")
+                output_token = args.get("output_token")
+                destination_address = args.get("destination_address")
+                amount = args.get("amount")
+                use_xmr = args.get("use_xmr", False)
+                mode = args.get("mode")
+                purpose = args.get("purpose")
+                user_intent = args.get("user_intent", False)
+                approval_token = args.get("approval_token")
+
+                if not isinstance(input_token, str) or not input_token.strip():
+                    raise WalletBackendError("input_token is required.")
+                if not isinstance(output_token, str) or not output_token.strip():
+                    raise WalletBackendError("output_token is required.")
+                if not isinstance(destination_address, str) or not destination_address.strip():
+                    raise WalletBackendError("destination_address is required.")
+                if not isinstance(amount, (int, float)) or amount <= 0:
+                    raise WalletBackendError("amount must be a positive number.")
+                if not isinstance(use_xmr, bool):
+                    raise WalletBackendError("use_xmr must be a boolean when provided.")
+                if mode not in {"preview", "prepare", "execute"}:
+                    raise WalletBackendError("mode must be 'preview', 'prepare' or 'execute'.")
+                if not isinstance(purpose, str) or not purpose.strip():
+                    raise WalletBackendError("purpose is required.")
+
+                preview_kwargs = {
+                    "input_token": input_token.strip(),
+                    "output_token": output_token.strip(),
+                    "destination_address": destination_address.strip(),
+                    "amount_ui": float(amount),
+                    "use_xmr": use_xmr,
+                }
+
+                if mode == "preview":
+                    preview = await self.backend.preview_solana_private_swap(**preview_kwargs)
+                    return AgentToolResult(
+                        tool=tool_name,
+                        ok=True,
+                        data=self._annotate_sensitive_payload(
+                            preview,
+                            action_label="Solana private swap",
+                            mode="preview",
+                        ),
+                    )
+
+                if mode == "prepare":
+                    self._require_prepare_intent(user_intent)
+                    preview = await self.backend.preview_solana_private_swap(**preview_kwargs)
+                    return AgentToolResult(
+                        tool=tool_name,
+                        ok=True,
+                        data=self._annotate_sensitive_payload(
+                            self._build_prepare_plan(
+                                preview_payload=preview,
+                                action_label="Solana private swap",
+                            ),
+                            action_label="Solana private swap",
+                            mode="prepare",
+                        ),
+                    )
+
+                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": "Solana private swap",
+                    "network": str(getattr(self.backend, "network", "unknown")),
+                    "destination_address": destination_address.strip(),
+                    "use_xmr": use_xmr,
+                }
+                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")
+                resume_private_swap_order = args.get("_resume_private_swap_order")
+                if resume_private_swap_order is not None and not isinstance(resume_private_swap_order, dict):
+                    raise WalletBackendError("_resume_private_swap_order must be an object when provided.")
+                execute_preview = None
+                if isinstance(approval_summary_copy.get("_preview_digest"), str):
+                    if not isinstance(approved_preview, dict):
+                        raise WalletBackendError(
+                            "Approved private 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="Solana private 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)
+
+                self._require_execute_approval(
+                    approval_token=approval_token,
+                    tool_name=tool_name,
+                    summary=approval_summary_copy,
+                    action_label="Solana private swap",
+                )
+
+                result = await self.backend.execute_solana_private_swap(
+                    **preview_kwargs,
+                    approved_preview=execute_preview,
+                    existing_order=resume_private_swap_order,
+                )
+                return AgentToolResult(
+                    tool=tool_name,
+                    ok=True,
+                    data=self._annotate_sensitive_payload(
+                        result,
+                        action_label="Solana private swap",
+                        mode="execute",
+                    ),
+                )
+
+            if tool_name == "continue_solana_private_swap":
+                approval_token = args.get("approval_token")
+                approved_preview = args.get("_approved_preview")
+                resume_private_swap_order = args.get("_resume_private_swap_order")
+                if not isinstance(approved_preview, dict):
+                    raise WalletBackendError(
+                        "Approved private swap preview payload is required. Create the private swap order first."
+                    )
+                if not isinstance(resume_private_swap_order, dict) or not resume_private_swap_order:
+                    raise WalletBackendError(
+                        "A pending Houdini private swap order is required. Create the private swap order first."
+                    )
+
+                approval_payload = inspect_approval_token(
+                    approval_token,
+                    tool_name="swap_solana_privately",
+                    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 private swap. Generate a new approval from the preview first."
+                    )
+
+                approval_summary_copy = dict(approval_summary)
+                if isinstance(approval_summary_copy.get("_preview_digest"), str):
+                    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 continue."
+                        )
+                    preview_summary = self._build_confirmation_summary(
+                        action_label="Solana private 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 continue."
+                        )
+
+                self._require_execute_approval(
+                    approval_token=approval_token,
+                    tool_name="swap_solana_privately",
+                    summary=approval_summary_copy,
+                    action_label="Solana private swap",
+                )
+
+                result = await self.backend.continue_solana_private_swap(
+                    approved_preview=approved_preview,
+                    existing_order=resume_private_swap_order,
+                )
+                return AgentToolResult(
+                    tool=tool_name,
+                    ok=True,
+                    data=self._annotate_sensitive_payload(
+                        result,
+                        action_label="Solana private swap funding",
+                        mode="execute",
+                    ),
+                )
+
+            if tool_name == "get_solana_private_swap_status":
+                multi_id = args.get("multi_id")
+                houdini_id = args.get("houdini_id")
+                if multi_id is not None and not isinstance(multi_id, str):
+                    raise WalletBackendError("multi_id must be a string when provided.")
+                if houdini_id is not None and not isinstance(houdini_id, str):
+                    raise WalletBackendError("houdini_id must be a string when provided.")
+                normalized_multi_id = multi_id.strip() if isinstance(multi_id, str) and multi_id.strip() else None
+                normalized_houdini_id = (
+                    houdini_id.strip() if isinstance(houdini_id, str) and houdini_id.strip() else None
+                )
+                if normalized_multi_id is None and normalized_houdini_id is None:
+                    raise WalletBackendError("multi_id or houdini_id is required.")
+                data = await self.backend.get_solana_private_swap_status(
+                    multi_id=normalized_multi_id,
+                    houdini_id=normalized_houdini_id,
+                )
+                return AgentToolResult(tool=tool_name, ok=True, data=data)
+
             if tool_name == "swap_solana_lifi_cross_chain_tokens":
                 input_token = args.get("input_token")
                 destination_chain = args.get("destination_chain")

package/agent-wallet/agent_wallet/openclaw_cli.py

@@ -102,6 +102,12 @@ def _apply_config_overrides(config: dict[str, Any]) -> None:
         ),
         "jupiterLendBaseUrl": ("JUPITER_LEND_API_BASE_URL", config.get("jupiterLendBaseUrl"), True),
         "jupiterApiKey": ("JUPITER_API_KEY", config.get("jupiterApiKey"), True),
+        "houdiniBaseUrl": ("HOUDINI_API_BASE_URL", config.get("houdiniBaseUrl"), True),
+        "houdiniApiKey": ("HOUDINI_API_KEY", config.get("houdiniApiKey"), True),
+        "houdiniApiSecret": ("HOUDINI_API_SECRET", config.get("houdiniApiSecret"), True),
+        "houdiniUserIp": ("HOUDINI_USER_IP", config.get("houdiniUserIp"), True),
+        "houdiniUserAgent": ("HOUDINI_USER_AGENT", config.get("houdiniUserAgent"), True),
+        "houdiniUserTimezone": ("HOUDINI_USER_TIMEZONE", config.get("houdiniUserTimezone"), True),
         "kaminoBaseUrl": ("KAMINO_API_BASE_URL", config.get("kaminoBaseUrl"), True),
         "kaminoProgramId": ("KAMINO_PROGRAM_ID", config.get("kaminoProgramId"), True),
     }
@@ -615,7 +621,13 @@ def main() -> int:
                 )
             )
     except Exception as exc:
-        print(json.dumps({"ok": False, "error": str(exc)}), file=sys.stderr)
+        error_payload: dict[str, Any] = {"ok": False, "error": str(exc)}
+        if isinstance(exc, WalletBackendError):
+            if exc.code:
+                error_payload["code"] = exc.code
+            if exc.details is not None:
+                error_payload["details"] = exc.details
+        print(json.dumps(error_payload), file=sys.stderr)
         return 1
 
     print(json.dumps(payload))

package/agent-wallet/agent_wallet/openclaw_runtime.py

@@ -14,7 +14,7 @@ from agent_wallet.openclaw_adapter import OpenClawWalletAdapter
 from agent_wallet.plugin_bundle import build_openclaw_plugin_bundle
 from agent_wallet.providers.wdk_btc_local import WdkBtcLocalClient
 from agent_wallet.providers.wdk_evm_local import WdkEvmLocalClient
-from agent_wallet.user_wallets import create_wallet_backend_for_user, ensure_user_solana_wallet, resolve_user_wallet_path
+from agent_wallet.user_wallets import create_openclaw_solana_backend
 from agent_wallet.wallet_layer.base import AgentWalletBackend, WalletBackendError
 from agent_wallet.wallet_layer.wdk_evm import WdkEvmLocalWalletBackend
 from agent_wallet.wallet_layer.wdk_btc import WdkBtcLocalWalletBackend
@@ -251,10 +251,7 @@ def onboard_openclaw_user_wallet(
             plugin_bundle=plugin_bundle,
         )
 
-    wallet_path = resolve_user_wallet_path(user_id, network=network)
-    created_now = not wallet_path.exists()
-    wallet_info = ensure_user_solana_wallet(user_id, network=network)
-    backend = create_wallet_backend_for_user(
+    backend, wallet_info, created_now = create_openclaw_solana_backend(
         user_id,
         sign_only=sign_only,
         network=network,