@agentlayer.tech/wallet 0.1.55 → 0.1.58

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

@@ -2,7 +2,7 @@
   "id": "agent-wallet",
   "name": "Agent Wallet",
   "description": "Official OpenClaw plugin bridge for the agent-wallet backends, including Solana, local BTC, and local EVM.",
-  "version": "0.1.55",
+  "version": "0.1.58",
   "contracts": {
     "tools": [
       "agentlayer_autonomous_approve",

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

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

package/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 ## Unreleased
 
+## v0.1.58 - 2026-07-01
+
+- Resolved SPL token symbol/name in `get_wallet_portfolio` via a batched,
+  concurrent Jupiter token-search lookup, so `/wallet-sol` shows tickers
+  (e.g. `USDC`) instead of raw mint addresses. The mint/token_address is
+  still returned in full and rendered shortened next to the label rather
+  than dropped. Falls back gracefully (symbol=None) when a mint isn't
+  indexed or the lookup provider is unavailable.
+  - `agent-wallet/agent_wallet/providers/jupiter.py`
+  - `agent-wallet/agent_wallet/wallet_layer/solana.py`
+  - `claude-code/plugins/agent-wallet/commands/wallet-sol.md`
+  - `codex/plugins/agent-wallet/skills/wallet-sol/SKILL.md`
+- Dropped the `/wallet-sol` source-metadata footer line (`source`,
+  `token_discovery_source`, `pricing_source`, `pricing_errors`) from the
+  rendered chat output for a more compact report.
+  - `claude-code/plugins/agent-wallet/commands/wallet-sol.md`
+  - `codex/plugins/agent-wallet/skills/wallet-sol/SKILL.md`
+
+## v0.1.57 - 2026-07-01
+
+- Added a bundled Codex `wallet-sol` skill so Codex users can render the
+  connected Solana wallet portfolio in chat the same way Claude Code's
+  `/wallet-sol` command does.
+  - `codex/plugins/agent-wallet/skills/wallet-sol/SKILL.md`
+  - `codex/plugins/agent-wallet/README.md`
+- Fixed the resident read worker (used by `get_wallet_balance` /
+  `get_wallet_portfolio`, e.g. `/wallet-sol`) decrypting the wallet's private
+  key on every read-only cold start even though it never needed it. Read-only
+  onboarding now resolves the address from the existing plaintext wallet pin
+  file once a wallet has been provisioned, instead of unsealing secrets and
+  deriving a signer just to discard it.
+  - `agent-wallet/agent_wallet/user_wallets.py`
+- Reduced `/wallet-sol` context payload by dropping the unused raw Jupiter
+  price blob (`price_raw`) from portfolio token entries.
+  - `agent-wallet/agent_wallet/wallet_layer/solana.py`
+- Parallelized Jupiter price batch fetches in `get_portfolio` instead of
+  awaiting each 20-mint batch sequentially, speeding up portfolio lookups for
+  wallets with many SPL token accounts.
+  - `agent-wallet/agent_wallet/wallet_layer/solana.py`
+- Added a background prewarm of the resident read worker at MCP server
+  startup so interpreter boot and onboarding overlap with the user issuing
+  the first read-only command instead of blocking it. Opt out with
+  `AGENT_WALLET_PREWARM_READ_WORKER=0`.
+  - `codex/plugins/agent-wallet/server.py`
+- Added idle eviction for resident read workers left over from a stale
+  config (e.g. after switching Solana network or wallet backend), bounded by
+  `AGENT_WALLET_READ_WORKER_IDLE_SECONDS` (default 10 minutes), and closed
+  resident read workers on SIGTERM in addition to the existing `atexit`
+  cleanup, since Python does not run `atexit` hooks on signal termination.
+  - `codex/plugins/agent-wallet/server.py`
+
 ## v0.1.54 - 2026-06-29
 
 - Fixed Claude Code autonomous-mode slash command activation so

package/VERSION

@@ -1 +1 @@
-0.1.55
+0.1.58

package/agent-wallet/.env.example

@@ -43,6 +43,7 @@ SOLANA_AGENT_KEYPAIR_PATH=
 JUPITER_API_BASE_URL=https://lite-api.jup.ag/swap/v1
 JUPITER_ULTRA_API_BASE_URL=https://lite-api.jup.ag/ultra/v1
 JUPITER_PRICE_API_BASE_URL=https://lite-api.jup.ag/price/v3
+JUPITER_TOKEN_SEARCH_API_BASE_URL=https://lite-api.jup.ag/tokens/v2
 JUPITER_API_KEY=
 
 # LI.FI cross-chain routing. API key is optional for basic read-only quote/status calls.

package/agent-wallet/agent_wallet/__init__.py

@@ -2,7 +2,7 @@
 
 # Keep in sync with package.json, pyproject.toml, and the npm installer version.
 # scripts/check_release_version.mjs enforces this on release.
-__version__ = "0.1.55"
+__version__ = "0.1.58"
 
 __all__ = [
     "config",

package/agent-wallet/agent_wallet/config.py

@@ -48,6 +48,7 @@ class Settings(BaseSettings):
     jupiter_swap_v2_api_base_url: str = "https://api.jup.ag/swap/v2"
     jupiter_ultra_api_base_url: str = "https://lite-api.jup.ag/ultra/v1"
     jupiter_price_api_base_url: str = "https://lite-api.jup.ag/price/v3"
+    jupiter_token_search_api_base_url: str = "https://lite-api.jup.ag/tokens/v2"
     jupiter_api_key: str = ""
     lifi_api_base_url: str = "https://li.quest/v1"
     lifi_api_key: str = ""
@@ -74,6 +75,14 @@ class Settings(BaseSettings):
 settings = Settings()
 
 
+def reload_settings() -> Settings:
+    """Reload settings from the current environment without changing object identity."""
+    refreshed = Settings()
+    for field_name in Settings.model_fields:
+        setattr(settings, field_name, getattr(refreshed, field_name))
+    return settings
+
+
 def normalize_solana_network(network: str | None) -> str:
     """Canonicalize supported Solana network names and reject test clusters."""
     normalized = str(network or "").strip().lower() or "mainnet"

package/agent-wallet/agent_wallet/openclaw_cli.py

@@ -33,6 +33,12 @@ def _parse_csv(value: Any) -> str:
 
 
 SECRET_CONFIG_KEYS = {"privateKey", "masterKey", "approvalSecret"}
+READ_ONLY_WORKER_TOOLS = frozenset(
+    {
+        "get_wallet_balance",
+        "get_wallet_portfolio",
+    }
+)
 
 
 def _reject_secret_config_json(config: dict[str, Any]) -> None:
@@ -117,6 +123,9 @@ def _apply_config_overrides(config: dict[str, Any]) -> None:
         if not allow_override and os.getenv(env_name, "").strip():
             continue
         os.environ[env_name] = text
+    from agent_wallet.config import reload_settings
+
+    reload_settings()
 
 
 def _load_json(raw: str | None, default: dict[str, Any] | None = None) -> dict[str, Any]:
@@ -138,10 +147,23 @@ def _read_stdin_secret(field_name: str) -> str:
 async def _run_onboard(user_id: str, config: dict[str, Any]) -> dict[str, Any]:
     from agent_wallet.openclaw_runtime import onboard_openclaw_user_wallet
 
-    context = onboard_openclaw_user_wallet(
+    context = _build_runtime_context(user_id, config)
+    return context.serializable_bundle()
+
+
+def _build_runtime_context(
+    user_id: str,
+    config: dict[str, Any],
+    *,
+    read_only: bool = False,
+) -> Any:
+    from agent_wallet.openclaw_runtime import onboard_openclaw_user_wallet
+
+    return onboard_openclaw_user_wallet(
         user_id,
         backend=config.get("backend"),
         sign_only=config.get("signOnly"),
+        read_only=read_only,
         network=config.get("network"),
         rpc_url=config.get("rpcUrl"),
         wdk_btc_service_url=config.get("wdkBtcServiceUrl"),
@@ -151,7 +173,6 @@ async def _run_onboard(user_id: str, config: dict[str, Any]) -> dict[str, Any]:
         wdk_evm_wallet_id=config.get("wdkEvmWalletId"),
         wdk_evm_account_index=config.get("wdkEvmAccountIndex"),
     )
-    return context.serializable_bundle()
 
 
 async def _run_invoke(
@@ -160,21 +181,7 @@ async def _run_invoke(
     arguments: dict[str, Any],
     config: dict[str, Any],
 ) -> dict[str, Any]:
-    from agent_wallet.openclaw_runtime import onboard_openclaw_user_wallet
-
-    context = onboard_openclaw_user_wallet(
-        user_id,
-        backend=config.get("backend"),
-        sign_only=config.get("signOnly"),
-        network=config.get("network"),
-        rpc_url=config.get("rpcUrl"),
-        wdk_btc_service_url=config.get("wdkBtcServiceUrl"),
-        wdk_btc_wallet_id=config.get("wdkBtcWalletId"),
-        wdk_btc_account_index=config.get("wdkBtcAccountIndex"),
-        wdk_evm_service_url=config.get("wdkEvmServiceUrl"),
-        wdk_evm_wallet_id=config.get("wdkEvmWalletId"),
-        wdk_evm_account_index=config.get("wdkEvmAccountIndex"),
-    )
+    context = _build_runtime_context(user_id, config)
     result = await context.adapter.invoke(tool_name, arguments)
     return result.model_dump()
 
@@ -188,21 +195,7 @@ async def _run_issue_approval(
     mainnet_confirmed: bool = False,
     ttl_seconds: int | None = None,
 ) -> dict[str, Any]:
-    from agent_wallet.openclaw_runtime import onboard_openclaw_user_wallet
-
-    context = onboard_openclaw_user_wallet(
-        user_id,
-        backend=config.get("backend"),
-        sign_only=config.get("signOnly"),
-        network=config.get("network"),
-        rpc_url=config.get("rpcUrl"),
-        wdk_btc_service_url=config.get("wdkBtcServiceUrl"),
-        wdk_btc_wallet_id=config.get("wdkBtcWalletId"),
-        wdk_btc_account_index=config.get("wdkBtcAccountIndex"),
-        wdk_evm_service_url=config.get("wdkEvmServiceUrl"),
-        wdk_evm_wallet_id=config.get("wdkEvmWalletId"),
-        wdk_evm_account_index=config.get("wdkEvmAccountIndex"),
-    )
+    context = _build_runtime_context(user_id, config)
     token = context.issue_execute_approval(
         tool_name=tool_name,
         confirmation_summary=summary,
@@ -250,6 +243,69 @@ def _run_autonomous_permission(action: str, scope: str) -> dict[str, Any]:
     raise WalletBackendError("action must be approve, revoke, or status.")
 
 
+def _error_payload_for_exception(exc: Exception) -> dict[str, Any]:
+    payload: dict[str, Any] = {"ok": False, "error": str(exc)}
+    if isinstance(exc, WalletBackendError):
+        if exc.code:
+            payload["code"] = exc.code
+        if exc.details is not None:
+            payload["details"] = exc.details
+    return payload
+
+
+async def _run_read_worker_tool(context: Any, request: dict[str, Any]) -> dict[str, Any]:
+    tool_name = str(request.get("tool") or "").strip()
+    if tool_name not in READ_ONLY_WORKER_TOOLS:
+        raise WalletBackendError(
+            f"read-worker only allows read-only tools: {', '.join(sorted(READ_ONLY_WORKER_TOOLS))}."
+        )
+    arguments = request.get("arguments") or {}
+    if not isinstance(arguments, dict):
+        raise WalletBackendError("read-worker request arguments must be a JSON object.")
+    result = await context.adapter.invoke(tool_name, arguments)
+    return result.model_dump()
+
+
+async def _serve_read_worker(user_id: str, config: dict[str, Any]) -> int:
+    context = _build_runtime_context(user_id, config, read_only=True)
+    while True:
+        line = sys.stdin.readline()
+        if not line:
+            break
+        text = line.strip()
+        if not text:
+            continue
+        request_id: str | None = None
+        try:
+            request = _load_json(text)
+            request_id = str(request.get("id") or "").strip() or None
+            if request.get("op") == "shutdown":
+                print(json.dumps({"id": request_id, "ok": True, "stopped": True}), flush=True)
+                break
+            payload = await _run_read_worker_tool(context, request)
+            print(
+                json.dumps(
+                    {
+                        "id": request_id,
+                        "ok": True,
+                        "payload": payload,
+                    }
+                ),
+                flush=True,
+            )
+        except Exception as exc:
+            print(
+                json.dumps(
+                    {
+                        "id": request_id,
+                        **_error_payload_for_exception(exc),
+                    }
+                ),
+                flush=True,
+            )
+    return 0
+
+
 async def _run_btc_wallet_get(user_id: str, config: dict[str, Any]) -> dict[str, Any]:
     from agent_wallet.btc_user_wallets import get_user_btc_wallet_binding
 
@@ -522,6 +578,10 @@ def main() -> int:
     evm_lock_parser.add_argument("--user-id", required=True)
     evm_lock_parser.add_argument("--config-json", default="{}")
 
+    read_worker_parser = subparsers.add_parser("read-worker")
+    read_worker_parser.add_argument("--user-id", required=True)
+    read_worker_parser.add_argument("--config-json", default="{}")
+
     args = parser.parse_args()
 
     try:
@@ -643,6 +703,8 @@ def main() -> int:
             )
         elif args.command == "evm-wallet-lock":
             payload = asyncio.run(_run_evm_wallet_lock(args.user_id, config))
+        elif args.command == "read-worker":
+            return asyncio.run(_serve_read_worker(args.user_id, config))
         else:
             payload = asyncio.run(
                 _run_invoke(
@@ -662,13 +724,7 @@ def main() -> int:
                 backend=str(locals().get("config", {}).get("backend", "") or ""),
                 ok=False,
             )
-        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)
+        print(json.dumps(_error_payload_for_exception(exc)), file=sys.stderr)
         return 1
 
     if getattr(args, "command", "") == "invoke":

package/agent-wallet/agent_wallet/openclaw_runtime.py

@@ -87,6 +87,7 @@ def onboard_openclaw_user_wallet(
     *,
     backend: str | None = None,
     sign_only: bool | None = None,
+    read_only: bool = False,
     network: str | None = None,
     rpc_url: str | None = None,
     wdk_btc_service_url: str | None = None,
@@ -98,6 +99,9 @@ def onboard_openclaw_user_wallet(
 ) -> OpenClawWalletRuntimeContext:
     """Provision and assemble a runtime-ready wallet context for one OpenClaw user."""
     backend_name = str(backend or settings.agent_wallet_backend).strip().lower()
+    effective_sign_only = True if read_only else (
+        settings.agent_wallet_sign_only if sign_only is None else sign_only
+    )
     if backend_name in {"wdk_btc_local", "wdk-btc-local", "btc_local", "btc-local"}:
         service_url = str(wdk_btc_service_url or settings.wdk_btc_service_url).strip()
         account_index = (
@@ -133,7 +137,7 @@ def onboard_openclaw_user_wallet(
             wallet_id=wallet_id,
             network=effective_network,
             account_index=account_index,
-            sign_only=settings.agent_wallet_sign_only if sign_only is None else sign_only,
+            sign_only=effective_sign_only,
             address=str(address_payload.get("address") or "").strip() or None,
         )
         wallet_info = {
@@ -188,7 +192,7 @@ def onboard_openclaw_user_wallet(
             wallet_id=wallet_id,
             network=effective_network,
             account_index=account_index,
-            sign_only=settings.agent_wallet_sign_only if sign_only is None else sign_only,
+            sign_only=effective_sign_only,
             address=resolved_address or None,
         )
         wallet_info = {
@@ -213,7 +217,8 @@ def onboard_openclaw_user_wallet(
 
     backend, wallet_info, created_now = create_openclaw_solana_backend(
         user_id,
-        sign_only=sign_only,
+        sign_only=effective_sign_only,
+        read_only=read_only,
         network=network,
         rpc_url=rpc_url,
     )

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

@@ -483,3 +483,37 @@ async def fetch_prices(
     if not isinstance(data, dict):
         raise ProviderError("jupiter", "Unexpected price response from Jupiter.")
     return data
+
+
+async def fetch_token_metadata(*, mints: list[str]) -> dict[str, dict[str, Any]]:
+    """Look up token symbol/name for a batch of mints via Jupiter's token
+    search API. Keyed by mint address; mints Jupiter doesn't index (very new
+    or illiquid tokens) are simply absent from the result rather than
+    raising, since this is display-only enrichment on top of the price data.
+    """
+    if not mints:
+        return {}
+    client = get_client()
+    params = {"query": ",".join(mints)}
+    response = await client.get(
+        f"{settings.jupiter_token_search_api_base_url.rstrip('/')}/search",
+        params=params,
+        headers=_headers(),
+    )
+    if response.status_code != 200:
+        raise ProviderError("jupiter", f"HTTP {response.status_code}: {response.text[:300]}")
+    data = response.json()
+    if not isinstance(data, list):
+        raise ProviderError("jupiter", "Unexpected token search response from Jupiter.")
+    result: dict[str, dict[str, Any]] = {}
+    for item in data:
+        if not isinstance(item, dict):
+            continue
+        mint = str(item.get("id") or "").strip()
+        if not mint:
+            continue
+        result[mint] = {
+            "symbol": item.get("symbol"),
+            "name": item.get("name"),
+        }
+    return result

package/agent-wallet/agent_wallet/user_wallets.py

@@ -147,10 +147,31 @@ def _load_user_wallet_secret_material(
     )
 
 
-def ensure_user_solana_wallet(user_id: str, network: str | None = None) -> dict[str, str]:
+def ensure_user_solana_wallet(
+    user_id: str,
+    network: str | None = None,
+    *,
+    read_only: bool = False,
+) -> dict[str, str]:
     """Provision a per-user Solana wallet if it does not exist yet."""
     effective_network = _resolve_effective_network(network)
     path = resolve_user_wallet_path(user_id, network=effective_network)
+    if read_only and path.exists():
+        # Read-only callers only need the address. The pin file already stores
+        # it in plaintext, so skip decrypting the wallet secret material and
+        # deriving the signer entirely rather than paying for a KDF unseal +
+        # keypair derivation just to read (and immediately discard) a private
+        # key. Falls through to the full decrypt path below if no pin exists
+        # yet (e.g. a wallet file predating pin files).
+        pin = load_wallet_pin(path)
+        if pin is not None and pin["network"] == effective_network:
+            return {
+                "user_id": user_id,
+                "address": pin["address"],
+                "path": str(path),
+                "storage_format": "encrypted",
+                "key_scope": "pinned-address-only",
+            }
     if path.exists():
         secret_material, storage_format, key_scope = _load_user_wallet_secret_material(
             path,
@@ -362,6 +383,7 @@ def create_openclaw_solana_backend(
     user_id: str,
     *,
     sign_only: bool | None = None,
+    read_only: bool = False,
     network: str | None = None,
     rpc_url: str | None = None,
 ) -> tuple[SolanaWalletBackend, dict[str, str], bool]:
@@ -396,6 +418,11 @@ def create_openclaw_solana_backend(
         raise WalletBackendError(
             "Configured Solana publicKey does not match the signer derived from keypairPath/runtime secret."
         )
+    effective_sign_only = True if read_only else (
+        settings.agent_wallet_sign_only if sign_only is None else sign_only
+    )
+    if read_only:
+        signer = None
 
     rpc_config = resolve_runtime_solana_rpc_config(
         effective_network,
@@ -411,7 +438,7 @@ def create_openclaw_solana_backend(
             network=effective_network,
             signer=signer,
             address=resolved_address or None,
-            sign_only=settings.agent_wallet_sign_only if sign_only is None else sign_only,
+            sign_only=effective_sign_only,
             rpc_provider_mode=str(rpc_config["mode"]),
             rpc_provider=str(rpc_config["provider"]),
             rpc_transport=str(rpc_config["transport"]),
@@ -429,11 +456,27 @@ def create_openclaw_solana_backend(
 
     wallet_path = resolve_user_wallet_path(user_id, network=effective_network)
     created_now = not wallet_path.exists()
+    wallet_info = ensure_user_solana_wallet(user_id, network=effective_network, read_only=read_only)
+    if read_only:
+        backend = SolanaWalletBackend(
+            rpc_url=rpc_config["rpc_urls"],
+            commitment=settings.solana_commitment,
+            network=effective_network,
+            signer=None,
+            address=wallet_info["address"] or None,
+            sign_only=effective_sign_only,
+            rpc_provider_mode=str(rpc_config["mode"]),
+            rpc_provider=str(rpc_config["provider"]),
+            rpc_transport=str(rpc_config["transport"]),
+            swap_provider=str(swap_config["provider"]),
+            swap_transport=str(swap_config["transport"]),
+        )
+        return backend, wallet_info, created_now
+
     backend = create_wallet_backend_for_user(
         user_id,
         sign_only=sign_only,
         network=effective_network,
         rpc_url=rpc_url,
     )
-    wallet_info = ensure_user_solana_wallet(user_id, network=effective_network)
     return backend, wallet_info, created_now

package/agent-wallet/agent_wallet/wallet_layer/solana.py

@@ -339,17 +339,37 @@ class SolanaWalletBackend(AgentWalletBackend):
 
         price_data_by_mint: dict[str, dict[str, Any]] = {}
         price_errors: list[str] = []
-        for index in range(0, len(mints), 20):
-            batch = mints[index : index + 20]
-            try:
-                price_data = await jupiter.fetch_prices(mints=batch)
-            except ProviderError as exc:
-                price_errors.append(str(exc))
+        token_metadata_by_mint: dict[str, dict[str, Any]] = {}
+        token_metadata_errors: list[str] = []
+        price_batches = [mints[index : index + 20] for index in range(0, len(mints), 20)]
+        # Independent HTTP calls against a shared async client, so fetch every
+        # price batch AND every token symbol/name lookup batch concurrently
+        # instead of paying sequential round trips for wallets with many SPL
+        # token accounts.
+        all_results = await asyncio.gather(
+            *(jupiter.fetch_prices(mints=batch) for batch in price_batches),
+            *(jupiter.fetch_token_metadata(mints=batch) for batch in price_batches),
+            return_exceptions=True,
+        )
+        batch_results = all_results[: len(price_batches)]
+        metadata_batch_results = all_results[len(price_batches) :]
+        for batch, result in zip(price_batches, batch_results):
+            if isinstance(result, ProviderError):
+                price_errors.append(str(result))
                 continue
+            if isinstance(result, BaseException):
+                raise result
             for mint in batch:
-                entry = _jupiter_price_entry(price_data, mint)
+                entry = _jupiter_price_entry(result, mint)
                 if entry is not None:
                     price_data_by_mint[mint] = entry
+        for result in metadata_batch_results:
+            if isinstance(result, ProviderError):
+                token_metadata_errors.append(str(result))
+                continue
+            if isinstance(result, BaseException):
+                raise result
+            token_metadata_by_mint.update(result)
 
         native_price = _jupiter_usd_price(price_data_by_mint.get(NATIVE_SOL_MINT))
         native_amount = _coerce_decimal(native_balance.get("balance_native"))
@@ -379,13 +399,15 @@ class SolanaWalletBackend(AgentWalletBackend):
             if value is not None:
                 total_value += value
                 priced_asset_count += 1
+            metadata = token_metadata_by_mint.get(mint) or {}
             enriched_tokens.append(
                 {
                     **token,
+                    "symbol": metadata.get("symbol"),
+                    "name": metadata.get("name"),
                     "price_usd": str(price) if price is not None else None,
                     "value_usd": _format_decimal(value),
                     "pricing_source": "jupiter-price" if price is not None else None,
-                    "price_raw": price_data_by_mint.get(mint),
                 }
             )
 
@@ -410,6 +432,8 @@ class SolanaWalletBackend(AgentWalletBackend):
             {
                 "asset_type": "spl-token",
                 "mint": token.get("mint"),
+                "symbol": token.get("symbol"),
+                "name": token.get("name"),
                 "token_account": token.get("token_account"),
                 "amount_raw": token.get("amount_raw"),
                 "amount_ui": token.get("amount_ui"),
@@ -442,6 +466,8 @@ class SolanaWalletBackend(AgentWalletBackend):
             "total_value_usd": formatted_total_value,
             "pricing_source": "jupiter-price" if price_data_by_mint else None,
             "pricing_errors": price_errors,
+            "token_metadata_source": "jupiter-token-search" if token_metadata_by_mint else None,
+            "token_metadata_errors": token_metadata_errors,
             "token_discovery_source": "solana-rpc",
             "source": "solana-rpc+jupiter-price",
         }

package/agent-wallet/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "agent-wallet",
   "name": "Agent Wallet",
   "description": "Plugin-friendly wallet backend for OpenClaw agents with safe wallet tools and runtime instructions across Solana, local BTC, and local EVM.",
-  "version": "0.1.55",
+  "version": "0.1.58",
   "skills": ["skills/wallet-operator"],
   "configSchema": {
     "type": "object",

package/agent-wallet/pyproject.toml

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

package/claude-code/plugins/agent-wallet/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-wallet",
   "displayName": "Agent Wallet",
-  "version": "0.1.55",
+  "version": "0.1.58",
   "description": "Claude Code bridge for the existing AgentLayer wallet runtime. Connects to Solana, Bitcoin, and EVM wallets without creating a new one.",
   "author": {
     "name": "AgentLayer"

package/claude-code/plugins/agent-wallet/commands/wallet-sol.md

@@ -1,17 +1,15 @@
 ---
-description: Show the connected Solana wallet overview directly in chat.
-allowed-tools: mcp__agent_wallet__get_wallet_overview
+description: Show the connected Solana wallet portfolio directly in chat.
+allowed-tools: mcp__agent_wallet__get_wallet_portfolio
 disable-model-invocation: true
 ---
 
-Show the connected Solana wallet overview directly in chat.
+Show the connected Solana wallet portfolio directly in chat.
 
-1. Call `get_wallet_overview` with:
+1. Call `get_wallet_portfolio` with:
 
 ```json
-{
-  "backend": "solana"
-}
+{}
 ```
 
 2. Format the response as a compact wallet report:
@@ -21,16 +19,12 @@ Show the connected Solana wallet overview directly in chat.
 - render a Markdown table with columns: `Asset | Type | Amount | USD Value`
 - use `assets` when present
 - for each asset row, prefer:
-  - asset label: `symbol`, then `mint`, then `token_address`, then `asset_type`
+  - asset label: `symbol`, then `name`, then `mint`, then `token_address`, then `asset_type`
+  - when the label came from `symbol`/`name` (not the mint/token_address itself) and a `mint` or `token_address` is present, append it shortened in parentheses next to the label as `first6…last4` (e.g. `USDC (EPjFWd…TDt1v)`) — keep the contract visible but compact, never show it twice
   - amount: `amount_ui`, then `balance_ui`, then `balance_native`, then `amount_raw`
   - usd value: `value_usd`, then `balance_usd`
 - omit zero-value rows only when both the amount and USD value are clearly zero
 - if no asset rows are available, still report the native balance summary in prose
+- do not include source metadata lines or footer fields such as `source`, `token_discovery_source`, `pricing_source`, or `pricing_errors`
 
-3. After the table, add one short metadata line with any available sources:
-
-- `source`
-- `token_discovery_source`
-- `pricing_source`
-
-4. Do not suggest transfers, swaps, or other write actions unless the user explicitly asks for them.
+3. Do not suggest transfers, swaps, or other write actions unless the user explicitly asks for them.

package/codex/plugins/agent-wallet/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-wallet",
-  "version": "0.1.55",
+  "version": "0.1.58",
   "description": "Codex plugin bridge for the AgentLayer wallet runtime.",
   "author": {
     "name": "AgentLayer"

package/codex/plugins/agent-wallet/README.md

@@ -21,6 +21,8 @@ Primary design rules:
 - session wallet selection with `set_wallet_backend`
 - EVM network selection with `set_evm_network`
 - auto-managed approval binding for `preview -> execute` write flows
+- bundled Codex skills, including `wallet-sol` for showing the Solana wallet
+  portfolio directly in chat
 
 ## Runtime requirements
 
@@ -28,6 +30,13 @@ Primary design rules:
 - keep the local wallet files and `~/.openclaw/sealed_keys.json` in place
 - use `wallet codex install --yes` to install this plugin into Codex
 
+## Bundled skill
+
+After `wallet codex install --yes` and a Codex restart, the plugin ships a
+bundled `wallet-sol` skill. In Codex you can invoke it from the slash menu or
+explicitly as `$wallet-sol` to render the connected Solana wallet portfolio as a
+compact chat table.
+
 ## Path resolution
 
 The bridge resolves the wallet runtime from:

package/codex/plugins/agent-wallet/server.py

@@ -2,12 +2,15 @@
 
 from __future__ import annotations
 
+import atexit
 import asyncio
 import copy
 import base64
 import hashlib
 import json
 import os
+import selectors
+import signal
 import subprocess
 import sys
 import threading
@@ -75,15 +78,21 @@ APPROVAL_CONTEXT_MISSING_MESSAGE = (
     "operation again, wait for explicit user confirmation, then retry execute. Do not ask the "
     "user for a manual approval token."
 )
+RESIDENT_READ_ONLY_TOOLS = {
+    "get_wallet_balance",
+    "get_wallet_portfolio",
+}
 
 selected_wallet_backend: str | None = None
 selected_solana_network: str | None = None
 selected_evm_network: str | None = None
 selected_btc_network: str | None = None
 approval_preview_cache: dict[str, dict[str, Any]] = {}
+resident_read_workers: dict[str, "_ResidentReadWorker"] = {}
 # Guards approval_preview_cache against races once wallet calls run concurrently
 # via asyncio.to_thread. Reentrant so prune helpers can be nested under writers.
 _approval_cache_lock = threading.RLock()
+_resident_worker_lock = threading.RLock()
 
 
 class WalletCliError(RuntimeError):
@@ -93,6 +102,10 @@ class WalletCliError(RuntimeError):
         self.details = details or {}
 
 
+class ResidentReadWorkerTransportError(RuntimeError):
+    """Raised when the long-lived read worker transport fails."""
+
+
 def _plugin_root() -> Path:
     return Path(__file__).resolve().parent
 
@@ -625,6 +638,311 @@ def _invoke_tool(tool_name: str, arguments: dict[str, Any], config: dict[str, An
     )
 
 
+class _ResidentReadWorker:
+    def __init__(self, *, user_id: str, config: dict[str, Any]):
+        self.user_id = user_id
+        self.config = copy.deepcopy(config)
+        self.package_root = _resolve_package_root()
+        self._process: subprocess.Popen[str] | None = None
+        self._lock = threading.RLock()
+        self._request_id = 0
+        self._stderr_lines: list[str] = []
+        self._stderr_thread: threading.Thread | None = None
+        self._last_used = time.monotonic()
+
+    def touch(self) -> None:
+        self._last_used = time.monotonic()
+
+    def idle_seconds(self) -> float:
+        return time.monotonic() - self._last_used
+
+    def _command(self) -> list[str]:
+        return [
+            _python_bin(self.package_root),
+            "-m",
+            "agent_wallet.openclaw_cli",
+            "read-worker",
+            "--user-id",
+            self.user_id,
+            "--config-json",
+            json.dumps(self.config),
+        ]
+
+    def _drain_stderr(self) -> None:
+        process = self._process
+        if process is None or process.stderr is None:
+            return
+        try:
+            for raw_line in process.stderr:
+                line = raw_line.strip()
+                if not line:
+                    continue
+                with self._lock:
+                    self._stderr_lines.append(line)
+                    if len(self._stderr_lines) > 20:
+                        self._stderr_lines = self._stderr_lines[-20:]
+        except Exception:
+            return
+
+    def _stderr_summary(self) -> str:
+        with self._lock:
+            if not self._stderr_lines:
+                return ""
+            return " | ".join(self._stderr_lines[-5:])
+
+    def _ensure_started(self) -> subprocess.Popen[str]:
+        with self._lock:
+            process = self._process
+            if process is not None and process.poll() is None:
+                return process
+            try:
+                process = subprocess.Popen(
+                    self._command(),
+                    cwd=str(self.package_root),
+                    env=_cli_env(self.package_root),
+                    text=True,
+                    stdin=subprocess.PIPE,
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.PIPE,
+                    bufsize=1,
+                )
+            except Exception as exc:
+                raise ResidentReadWorkerTransportError(
+                    f"Could not start resident read worker: {exc}"
+                ) from exc
+            self._process = process
+            self._stderr_lines = []
+            self._stderr_thread = threading.Thread(
+                target=self._drain_stderr,
+                name="agent-wallet-read-worker-stderr",
+                daemon=True,
+            )
+            self._stderr_thread.start()
+            return process
+
+    def warm(self) -> None:
+        """Spawn the worker eagerly, without waiting for a request/response.
+
+        Lets the interpreter boot, module imports, and read-only onboarding
+        happen off the critical path of the first real read-only tool call.
+        """
+        try:
+            self._ensure_started()
+        except ResidentReadWorkerTransportError:
+            pass
+
+    def close(self) -> None:
+        with self._lock:
+            process = self._process
+            self._process = None
+        if process is None:
+            return
+        try:
+            if process.poll() is None and process.stdin is not None:
+                process.stdin.write(json.dumps({"op": "shutdown"}) + "\n")
+                process.stdin.flush()
+        except Exception:
+            pass
+        try:
+            process.wait(timeout=1)
+        except Exception:
+            try:
+                process.terminate()
+                process.wait(timeout=1)
+            except Exception:
+                try:
+                    process.kill()
+                except Exception:
+                    pass
+
+    def invoke(self, tool_name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+        with self._lock:
+            self.touch()
+            process = self._ensure_started()
+            if process.stdin is None or process.stdout is None:
+                self.close()
+                raise ResidentReadWorkerTransportError("Resident read worker stdio is unavailable.")
+            self._request_id += 1
+            request_id = str(self._request_id)
+            request = {
+                "id": request_id,
+                "tool": tool_name,
+                "arguments": arguments,
+            }
+            try:
+                process.stdin.write(json.dumps(request) + "\n")
+                process.stdin.flush()
+            except Exception as exc:
+                self.close()
+                raise ResidentReadWorkerTransportError(
+                    f"Could not write to resident read worker: {exc}"
+                ) from exc
+
+            selector = selectors.DefaultSelector()
+            selector.register(process.stdout, selectors.EVENT_READ)
+            events = selector.select(timeout=_cli_timeout_seconds())
+            selector.close()
+            if not events:
+                self.close()
+                raise ResidentReadWorkerTransportError(
+                    f"Resident read worker timed out after {_cli_timeout_seconds():g}s."
+                )
+            response_line = process.stdout.readline()
+            if not response_line:
+                self.close()
+                stderr_summary = self._stderr_summary()
+                detail = f" Worker stderr: {stderr_summary}" if stderr_summary else ""
+                raise ResidentReadWorkerTransportError(
+                    "Resident read worker exited without a response." + detail
+                )
+            try:
+                response = json.loads(response_line)
+            except json.JSONDecodeError as exc:
+                self.close()
+                raise ResidentReadWorkerTransportError(
+                    f"Resident read worker returned invalid JSON: {exc}"
+                ) from exc
+            if str(response.get("id") or "") != request_id:
+                self.close()
+                raise ResidentReadWorkerTransportError(
+                    "Resident read worker response id did not match the request."
+                )
+            if response.get("ok") is False:
+                raise WalletCliError(
+                    str(response.get("error") or "resident read worker failed."),
+                    code=str(response.get("code") or ""),
+                    details=response.get("details")
+                    if isinstance(response.get("details"), dict)
+                    else {},
+                )
+            payload = response.get("payload")
+            if not isinstance(payload, dict):
+                raise ResidentReadWorkerTransportError(
+                    "Resident read worker returned a non-object payload."
+                )
+            return payload
+
+
+def _resident_worker_cache_key(user_id: str, config: dict[str, Any]) -> str:
+    return _canonical_json_text(
+        {
+            "user_id": user_id,
+            "config": config,
+        }
+    )
+
+
+def _resident_worker_idle_seconds() -> float:
+    """Idle threshold (seconds) after which an unused resident worker for a
+    config that is no longer the active one gets reaped. Falls back to 10
+    minutes on bad values."""
+    raw = os.getenv("AGENT_WALLET_READ_WORKER_IDLE_SECONDS", "600")
+    try:
+        value = float(raw)
+    except (TypeError, ValueError):
+        return 600.0
+    return value if value > 0 else 600.0
+
+
+def _evict_idle_resident_read_workers(*, keep_key: str) -> None:
+    """Close resident workers other than `keep_key` that have been idle past
+    the configured threshold.
+
+    Each distinct (user_id, config) pair (e.g. switching Solana network or
+    wallet backend mid-session) keeps its own resident subprocess alive
+    indefinitely otherwise, since nothing previously evicted them. This
+    bounds that growth without adding a background timer thread: eviction
+    piggybacks on the next lookup instead.
+    """
+    idle_limit = _resident_worker_idle_seconds()
+    with _resident_worker_lock:
+        stale_keys = [
+            key
+            for key, worker in resident_read_workers.items()
+            if key != keep_key and worker.idle_seconds() > idle_limit
+        ]
+        stale_workers = [resident_read_workers.pop(key) for key in stale_keys]
+    for worker in stale_workers:
+        worker.close()
+
+
+def _resident_read_worker_for_config(user_id: str, config: dict[str, Any]) -> _ResidentReadWorker:
+    key = _resident_worker_cache_key(user_id, config)
+    _evict_idle_resident_read_workers(keep_key=key)
+    with _resident_worker_lock:
+        worker = resident_read_workers.get(key)
+        if worker is None:
+            worker = _ResidentReadWorker(user_id=user_id, config=config)
+            resident_read_workers[key] = worker
+        return worker
+
+
+def _shutdown_resident_read_workers() -> None:
+    with _resident_worker_lock:
+        workers = list(resident_read_workers.values())
+        resident_read_workers.clear()
+    for worker in workers:
+        worker.close()
+
+
+atexit.register(_shutdown_resident_read_workers)
+
+
+def _handle_termination_signal(signum: int, frame: Any) -> None:
+    """Close resident read worker subprocesses on SIGTERM, then terminate
+    normally.
+
+    atexit handlers only run on normal interpreter shutdown; Python's
+    default SIGTERM disposition terminates the process immediately without
+    unwinding to atexit. Hosts that gracefully stop this MCP server (e.g.
+    closing a Claude Code / Codex session) send SIGTERM, so without this the
+    resident worker subprocesses leaked past every normal shutdown, not just
+    an abrupt kill -9. (SIGINT is not handled here: Python's default handler
+    raises KeyboardInterrupt, which unwinds to a normal interpreter
+    shutdown and already triggers the atexit hook above.)
+    """
+    _shutdown_resident_read_workers()
+    signal.signal(signum, signal.SIG_DFL)
+    os.kill(os.getpid(), signum)
+
+
+def _install_termination_signal_handlers() -> None:
+    try:
+        signal.signal(signal.SIGTERM, _handle_termination_signal)
+    except (ValueError, OSError):
+        # e.g. signal.signal() called outside the main thread.
+        pass
+
+
+def _prewarm_resident_read_worker() -> None:
+    """Best-effort background warm-up of the default resident read worker.
+
+    server.py is a persistent stdio MCP process kept alive for the whole
+    host session, but the resident worker itself only used to spawn lazily
+    on the first read-only tool call (get_wallet_balance /
+    get_wallet_portfolio, e.g. /wallet-sol), putting interpreter boot +
+    onboarding on the critical path of that first call. Kick it off in a
+    daemon thread instead so it overlaps with the user issuing the command.
+    Failures here are silently ignored: the lazy path in
+    _invoke_read_tool_blocking remains the source of truth and will retry.
+    """
+    if os.getenv("AGENT_WALLET_PREWARM_READ_WORKER", "1").strip().lower() in {"0", "false", "no"}:
+        return
+
+    def _run() -> None:
+        try:
+            config = _base_config({}, tool_name="get_wallet_portfolio")
+            _resident_read_worker_for_config(_user_id(), config).warm()
+        except Exception:
+            pass
+
+    threading.Thread(
+        target=_run,
+        name="agent-wallet-read-worker-prewarm",
+        daemon=True,
+    ).start()
+
+
 def _issue_approval_token(
     tool_name: str,
     config: dict[str, Any],
@@ -654,6 +972,15 @@ def _issue_approval_token(
     return token
 
 
+def _invoke_resident_read_tool(tool_name: str, arguments: dict[str, Any], config: dict[str, Any]) -> dict[str, Any]:
+    worker = _resident_read_worker_for_config(_user_id(), config)
+    try:
+        return worker.invoke(tool_name, arguments)
+    except ResidentReadWorkerTransportError:
+        worker.close()
+        raise
+
+
 def _is_solana_swap_intent_execute(params: dict[str, Any]) -> bool:
     return str(params.get("mode") or "") == "intent_execute"
 
@@ -1033,7 +1360,9 @@ async def _handle_get_wallet_overview(params: dict[str, Any]) -> dict[str, Any]:
     if params.get("address") is not None:
         effective_params["address"] = params.get("address")
 
-    payload = await asyncio.to_thread(_invoke_tool, "get_wallet_balance", effective_params, config)
+    payload = await asyncio.to_thread(
+        _invoke_read_tool_blocking, "get_wallet_balance", effective_params, config
+    )
     if payload.get("ok") is False:
         raise RuntimeError(str(payload.get("error") or "get_wallet_overview failed"))
     data = payload.get("data", {})
@@ -1072,6 +1401,19 @@ def _invoke_wallet_tool_blocking(
     return payload
 
 
+def _invoke_read_tool_blocking(
+    tool_name: str,
+    effective_params: dict[str, Any],
+    config: dict[str, Any],
+) -> dict[str, Any]:
+    if tool_name not in RESIDENT_READ_ONLY_TOOLS:
+        return _invoke_tool(tool_name, effective_params, config)
+    try:
+        return _invoke_resident_read_tool(tool_name, effective_params, config)
+    except ResidentReadWorkerTransportError:
+        return _invoke_tool(tool_name, effective_params, config)
+
+
 async def _handle_wallet_tool(tool_name: str, params: dict[str, Any]) -> dict[str, Any]:
     config = _base_config(params, tool_name=tool_name)
     backend = _normalize_wallet_backend(config.get("backend"))
@@ -1080,9 +1422,14 @@ async def _handle_wallet_tool(tool_name: str, params: dict[str, Any]) -> dict[st
         config["network"] = selected_evm_network
 
     effective_params = dict(params)
-    payload = await asyncio.to_thread(
-        _invoke_wallet_tool_blocking, tool_name, config, effective_params
-    )
+    if tool_name in RESIDENT_READ_ONLY_TOOLS:
+        payload = await asyncio.to_thread(
+            _invoke_read_tool_blocking, tool_name, effective_params, config
+        )
+    else:
+        payload = await asyncio.to_thread(
+            _invoke_wallet_tool_blocking, tool_name, config, effective_params
+        )
 
     if payload.get("ok") is False:
         raise RuntimeError(str(payload.get("error") or f"{tool_name} failed"))
@@ -1173,6 +1520,8 @@ def build_server():
 
 
 def main() -> None:
+    _install_termination_signal_handlers()
+    _prewarm_resident_read_worker()
     build_server().run(show_banner=False)
 
 

package/codex/plugins/agent-wallet/skills/wallet-sol/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: "wallet-sol"
+description: "Show the current Solana wallet portfolio from the local AgentLayer wallet in a compact chat table. Use when the user asks for /wallet-sol or wants the Solana wallet shown directly in chat."
+---
+
+# Solana Wallet Portfolio
+
+Use the local AgentLayer wallet MCP tools only.
+
+Workflow:
+
+1. Call `set_wallet_backend` with `backend=solana`.
+2. Call `get_wallet_portfolio` with no address override.
+3. Render the result directly in chat in this shape:
+   - title: `Solana Wallet Portfolio`
+   - bullets for `Chain`, `Network`, `Address`, and `Total Value (USD)` when available
+   - one compact Markdown table with columns: `Asset | Type | Amount | USD Value`
+
+Formatting rules:
+
+- Use `assets` when present.
+- For the asset label, prefer `symbol`, then `name`, then `mint`, then `token_address`, then `asset_type`.
+- When the label came from `symbol`/`name` (not the mint/token_address itself) and a `mint` or `token_address` is present, append it shortened in parentheses next to the label as `first6…last4` (e.g. `USDC (EPjFWd…TDt1v)`) — keep the contract visible but compact, never show it twice.
+- For the asset type, use `asset_type` when present; otherwise infer `native` for the native asset and `token` for the rest.
+- For the amount, prefer `amount_ui`, then `balance_ui`, then `balance_native`, then `amount_raw`.
+- For the USD value, prefer `value_usd`, then `balance_usd`.
+- Do not include source metadata lines or extra footer fields such as `source`, `token_discovery_source`, `pricing_source`, or `pricing_errors`.
+- Keep the response concise. Do not add strategy suggestions, swap ideas, or write actions unless the user explicitly asks for them.
+- If the wallet tool fails, surface the tool error plainly and stop.

package/hermes/plugins/agent_wallet/plugin.yaml

@@ -1,5 +1,5 @@
 name: agent-wallet
-version: 0.1.55
+version: 0.1.58
 description: Thin Hermes Agent bridge to the existing AgentLayer/OpenClaw wallet backend
 provides_tools:
   - agent_wallet_tools

package/package.json

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

package/wdk-btc-wallet/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wdk-btc-wallet",
-  "version": "0.1.55",
+  "version": "0.1.58",
   "private": true,
   "type": "module",
   "description": "Separate BTC-only wallet service built on Tether WDK.",

package/wdk-evm-wallet/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wdk-evm-wallet",
-  "version": "0.1.55",
+  "version": "0.1.58",
   "private": true,
   "type": "module",
   "description": "Separate EVM wallet service built on Tether WDK.",