@agentlayer.tech/wallet 0.1.55 → 0.1.64

package/agent-wallet/agent_wallet/keystore.py

@@ -0,0 +1,303 @@
+"""Cross-platform, dependency-free secret storage for the wallet boot key.
+
+Backends shell out to tools already present on each desktop OS:
+  - macOS:   /usr/bin/security (generic password in the login keychain)
+  - Windows: powershell DPAPI (ConvertFrom/ConvertTo-SecureString), per-user+machine
+  - Linux:   secret-tool (libsecret) iff a Secret Service is reachable
+  - fallback: a 0600 plaintext file (current behavior) — never chosen over a
+              working keystore.
+
+The store holds ONE install-level secret (the boot key). See
+BOOT_KEY_KEYCHAIN_ARCHITECTURE.md.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from agent_wallet.config import resolve_openclaw_home
+from agent_wallet.file_ops import atomic_write_text, chmod_if_exists
+
+KEYSTORE_SERVICE = "ai.agentlayer.wallet"
+BOOT_KEY_ITEM = "boot_key"
+_PROBE_ITEM = "__probe__"
+_KEYSTORE_BACKEND_ENV = "AGENT_WALLET_KEYSTORE_BACKEND"
+
+_SECURITY_BIN = "/usr/bin/security"
+_SUBPROCESS_TIMEOUT = 10.0
+
+
+def _service() -> str:
+    """Keychain/Secret-Service service name. Overridable so tests never touch the
+    real shared slot (the OS keychain is global, not scoped to OPENCLAW_HOME)."""
+    return os.getenv("AGENT_WALLET_KEYSTORE_SERVICE", "").strip() or KEYSTORE_SERVICE
+
+
+def _backend_preference() -> str:
+    """Selected keystore backend.
+
+    auto (default) prefers the native OS keystore (macOS Keychain / Windows DPAPI /
+    Linux Secret Service) and falls back to a 0600 plaintext file. macOS Keychain
+    is prompt-free because set() writes with `-A` (open ACL, no partition-list).
+    Override with AGENT_WALLET_KEYSTORE_BACKEND=plaintext|macos-keychain|native|...
+    """
+    return os.getenv(_KEYSTORE_BACKEND_ENV, "auto").strip().lower()
+
+
+class KeyStoreError(Exception):
+    """Raised when a keystore backend operation fails unexpectedly."""
+
+
+@runtime_checkable
+class KeyStore(Protocol):
+    backend_id: str
+
+    def available(self) -> bool: ...
+    def get(self, name: str) -> str | None: ...
+    def set(self, name: str, value: str) -> None: ...
+    def delete(self, name: str) -> None: ...
+
+
+def _timeout_output(value: str | bytes | None) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, bytes):
+        return value.decode(errors="replace")
+    return value
+
+
+def _run(
+    argv: list[str],
+    *,
+    input_text: str | None = None,
+    timeout: float = _SUBPROCESS_TIMEOUT,
+) -> subprocess.CompletedProcess[str]:
+    kwargs: dict[str, object] = {
+        "capture_output": True,
+        "text": True,
+        "timeout": timeout,
+        "check": False,
+    }
+    if input_text is None:
+        kwargs["stdin"] = subprocess.DEVNULL
+    else:
+        kwargs["input"] = input_text
+    try:
+        return subprocess.run(argv, **kwargs)
+    except subprocess.TimeoutExpired as exc:
+        return subprocess.CompletedProcess(
+            argv,
+            124,
+            _timeout_output(exc.stdout),
+            _timeout_output(exc.stderr) or f"timed out after {timeout:g}s",
+        )
+
+
+class MacKeychainStore:
+    backend_id = "macos-keychain"
+
+    def available(self) -> bool:
+        return platform.system() == "Darwin" and Path(_SECURITY_BIN).exists()
+
+    def get(self, name: str) -> str | None:
+        proc = _run([_SECURITY_BIN, "find-generic-password", "-s", _service(), "-a", name, "-w"])
+        if proc.returncode != 0:
+            return None  # item not found (44) or other non-fatal lookup miss
+        value = proc.stdout.rstrip("\n")
+        return value or None
+
+    def set(self, name: str, value: str) -> None:
+        # Recreate the item fresh with an open ACL. This is the ONLY reliably
+        # prompt-free way to write a login-keychain item non-interactively:
+        #   -A          -> accessible to any application without a prompt, and it
+        #                  bypasses the Sierra+ partition-list mechanism entirely.
+        #   delete+add  -> never -U-update an existing item; updating one created
+        #                  with a different ACL (or setting its partition list)
+        #                  pops a GUI keychain-password dialog in the background.
+        # Trade-off: any process running as this user can read the key without a
+        # prompt — the same runtime exposure as a 0600 file. At-rest protection
+        # (backups, synced home dirs, a stolen disk) is fully preserved.
+        _run([_SECURITY_BIN, "delete-generic-password", "-s", _service(), "-a", name])
+        proc = _run([
+            _SECURITY_BIN, "add-generic-password",
+            "-s", _service(), "-a", name,
+            "-w", value, "-A",
+        ])
+        if proc.returncode != 0:
+            raise KeyStoreError(f"security add-generic-password failed: {proc.stderr.strip()}")
+
+    def delete(self, name: str) -> None:
+        _run([_SECURITY_BIN, "delete-generic-password", "-s", _service(), "-a", name])
+
+
+class WindowsDpapiStore:
+    backend_id = "windows-dpapi"
+
+    def _blob_path(self, name: str) -> Path:
+        return resolve_openclaw_home() / "keystore" / f"{name}.dpapi"
+
+    def available(self) -> bool:
+        return platform.system() == "Windows" and shutil.which("powershell") is not None
+
+    def get(self, name: str) -> str | None:
+        path = self._blob_path(name)
+        if not path.exists():
+            return None
+        blob = path.read_text(encoding="utf-8").strip()
+        if not blob:
+            return None
+        script = (
+            "$ErrorActionPreference='Stop';"
+            "$b=[Console]::In.ReadToEnd().Trim();"
+            "$ss=ConvertTo-SecureString $b;"
+            "$p=[Runtime.InteropServices.Marshal]::PtrToStringUni("
+            "[Runtime.InteropServices.Marshal]::SecureStringToBSTR($ss));"
+            "[Console]::Out.Write($p)"
+        )
+        proc = _run(["powershell", "-NoProfile", "-NonInteractive", "-Command", script], input_text=blob)
+        if proc.returncode != 0:
+            return None
+        return proc.stdout or None
+
+    def set(self, name: str, value: str) -> None:
+        script = (
+            "$ErrorActionPreference='Stop';"
+            "$v=[Console]::In.ReadToEnd();"
+            "$ss=ConvertTo-SecureString $v -AsPlainText -Force;"
+            "[Console]::Out.Write((ConvertFrom-SecureString $ss))"
+        )
+        proc = _run(["powershell", "-NoProfile", "-NonInteractive", "-Command", script], input_text=value)
+        if proc.returncode != 0 or not proc.stdout.strip():
+            raise KeyStoreError(f"DPAPI ConvertFrom-SecureString failed: {proc.stderr.strip()}")
+        atomic_write_text(self._blob_path(name), proc.stdout.strip() + "\n", mode=0o600)
+
+    def delete(self, name: str) -> None:
+        path = self._blob_path(name)
+        try:
+            path.unlink()
+        except FileNotFoundError:
+            pass
+
+
+class LinuxSecretServiceStore:
+    backend_id = "linux-secretservice"
+
+    def available(self) -> bool:
+        if platform.system() != "Linux" or shutil.which("secret-tool") is None:
+            return False
+        # A probe lookup succeeds (rc 0/1) only when a Secret Service answers;
+        # a missing/unreachable service errors out (rc >1) or times out.
+        try:
+            proc = _run(["secret-tool", "lookup", "service", _service(), "account", "__probe__"])
+        except subprocess.TimeoutExpired:
+            return False
+        return proc.returncode in (0, 1)
+
+    def get(self, name: str) -> str | None:
+        proc = _run(["secret-tool", "lookup", "service", _service(), "account", name])
+        if proc.returncode != 0:
+            return None
+        value = proc.stdout.rstrip("\n")
+        return value or None
+
+    def set(self, name: str, value: str) -> None:
+        proc = _run(
+            ["secret-tool", "store", "--label", f"{_service()} {name}",
+             "service", _service(), "account", name],
+            input_text=value,
+        )
+        if proc.returncode != 0:
+            raise KeyStoreError(f"secret-tool store failed: {proc.stderr.strip()}")
+
+    def delete(self, name: str) -> None:
+        _run(["secret-tool", "clear", "service", _service(), "account", name])
+
+
+class PlaintextFileStore:
+    """Fallback: a 0600 file under OPENCLAW_HOME/keystore. Always available."""
+
+    backend_id = "plaintext-file"
+
+    def _path(self, name: str) -> Path:
+        return resolve_openclaw_home() / "keystore" / f"{name}.plaintext"
+
+    def available(self) -> bool:
+        return True
+
+    def get(self, name: str) -> str | None:
+        path = self._path(name)
+        if not path.exists():
+            return None
+        chmod_if_exists(path)
+        value = path.read_text(encoding="utf-8").strip()
+        return value or None
+
+    def set(self, name: str, value: str) -> None:
+        atomic_write_text(self._path(name), value.strip() + "\n", mode=0o600)
+
+    def delete(self, name: str) -> None:
+        try:
+            self._path(name).unlink()
+        except FileNotFoundError:
+            pass
+
+
+def resolve_keystore() -> KeyStore:
+    """Return the first available OS-native backend, else the plaintext fallback."""
+    preference = _backend_preference()
+    if preference in {"plain", "plaintext", "plaintext-file", "file"}:
+        return PlaintextFileStore()
+
+    candidates: list[KeyStore]
+    if preference in {"macos", "macos-keychain", "keychain"}:
+        candidates = [MacKeychainStore()]
+    elif preference in {"windows", "windows-dpapi", "dpapi"}:
+        candidates = [WindowsDpapiStore()]
+    elif preference in {"linux", "linux-secretservice", "secretservice"}:
+        candidates = [LinuxSecretServiceStore()]
+    elif preference == "native":
+        candidates = [MacKeychainStore(), WindowsDpapiStore(), LinuxSecretServiceStore()]
+    else:
+        # Auto: native OS keystore first, plaintext fallback last. macOS Keychain
+        # is prompt-free now that set() uses `-A` (open ACL, no partition-list) and
+        # _backend_usable falls back gracefully if a session still can't authorize.
+        candidates = [MacKeychainStore(), WindowsDpapiStore(), LinuxSecretServiceStore()]
+
+    for candidate in candidates:
+        try:
+            if candidate.available() and _backend_usable(candidate):
+                return candidate
+        except Exception:
+            continue
+    return PlaintextFileStore()
+
+
+def _backend_usable(candidate: KeyStore) -> bool:
+    """Return true when a native backend can read the live key or write safely.
+
+    A desktop keystore binary can exist while the session cannot authorize
+    non-interactive writes. Treat that as unavailable so install/migration uses
+    the bounded fallback instead of hanging or repeatedly failing.
+    """
+    try:
+        if candidate.get(BOOT_KEY_ITEM):
+            return True
+    except Exception:
+        pass
+
+    probe_value = "ok"
+    try:
+        candidate.set(_PROBE_ITEM, probe_value)
+        return candidate.get(_PROBE_ITEM) == probe_value
+    except Exception:
+        return False
+    finally:
+        try:
+            candidate.delete(_PROBE_ITEM)
+        except Exception:
+            pass

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,19 @@ 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="{}")
+
+    subparsers.add_parser("boot-key-export")
+
+    boot_key_import_parser = subparsers.add_parser("boot-key-import")
+    boot_key_import_parser.add_argument(
+        "--key-stdin",
+        action="store_true",
+        help="Read the boot key to import from stdin.",
+    )
+
     args = parser.parse_args()
 
     try:
@@ -643,6 +712,19 @@ 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))
+        elif args.command == "boot-key-export":
+            from agent_wallet.boot_key_recovery import export_boot_key, export_warning
+
+            print(export_warning(), file=sys.stderr)
+            payload = {"boot_key": export_boot_key()}
+        elif args.command == "boot-key-import":
+            if not args.key_stdin:
+                raise WalletBackendError("boot-key-import requires --key-stdin.")
+            from agent_wallet.boot_key_recovery import import_boot_key
+
+            payload = import_boot_key(_read_stdin_secret("boot key"))
         else:
             payload = asyncio.run(
                 _run_invoke(
@@ -662,13 +744,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

@@ -6,6 +6,7 @@ from dataclasses import dataclass
 from typing import Any
 
 from agent_wallet.approval import issue_approval_token
+from agent_wallet.boot_key_migration import migrate_boot_key_to_keystore
 from agent_wallet.btc_user_wallets import get_user_btc_wallet_binding
 from agent_wallet.config import normalize_btc_network, normalize_evm_network, settings
 from agent_wallet.evm_user_wallets import ensure_user_evm_wallet_ready
@@ -19,6 +20,24 @@ from agent_wallet.wallet_layer.base import AgentWalletBackend, WalletBackendErro
 from agent_wallet.wallet_layer.wdk_evm import WdkEvmLocalWalletBackend
 from agent_wallet.wallet_layer.wdk_btc import WdkBtcLocalWalletBackend
 
+_boot_key_migration_done = False
+
+
+def ensure_boot_key_migrated_once() -> None:
+    """Run the boot-key keystore migration at most once per process. Never raises.
+
+    Best-effort: a failure here must never block wallet onboarding — the legacy
+    plaintext sources still resolve via ``resolve_boot_key``.
+    """
+    global _boot_key_migration_done
+    if _boot_key_migration_done:
+        return
+    _boot_key_migration_done = True
+    try:
+        migrate_boot_key_to_keystore()
+    except Exception:
+        pass
+
 
 @dataclass(slots=True)
 class OpenClawWalletRuntimeContext:
@@ -87,6 +106,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,
@@ -97,7 +117,11 @@ def onboard_openclaw_user_wallet(
     wdk_evm_account_index: int | None = None,
 ) -> OpenClawWalletRuntimeContext:
     """Provision and assemble a runtime-ready wallet context for one OpenClaw user."""
+    ensure_boot_key_migrated_once()
     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 +157,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 +212,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 +237,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