@agentlayer.tech/wallet 0.1.94 → 0.1.95

package/.openclaw/extensions/agent-wallet/dist/index.js

@@ -1995,6 +1995,44 @@ const evmToolDefinitions = [
       additionalProperties: false,
     },
   },
+  {
+    name: "get_evm_uniswap_pools",
+    description: "Find existing Uniswap V3/V4 pools through the official Pool Info API on ethereum, base, or robinhood. Returns the canonical poolReferenceIdentifier needed for an LP create request. Read-only: it does not approve, sign, or execute anything.",
+    parameters: {
+      type: "object",
+      properties: {
+        protocol: { type: "string", enum: ["V3", "V4"] },
+        pool_parameters: {
+          type: "object",
+          description: "Official Pool Info API token-pair parameters, such as tokenAddressA, tokenAddressB and optional fee/tickSpacing/hooks.",
+          additionalProperties: true,
+        },
+        pool_references: {
+          type: "array",
+          maxItems: 20,
+          items: { type: "object", additionalProperties: true },
+        },
+        page_size: { type: "integer", minimum: 1, maximum: 20 },
+        current_page: { type: "integer", minimum: 1 },
+        network: { type: "string", enum: EVM_CORE_NETWORKS },
+      },
+      required: ["protocol"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_evm_uniswap_positions",
+    description: "List the active wallet's Uniswap V3 LP NFTs on ethereum, base, or robinhood. Returns token ids, token pair, fee tier, ticks, liquidity, and owed fees. Read-only. V4 is excluded because its PositionManager is not enumerable without a verified indexed source.",
+    parameters: {
+      type: "object",
+      properties: {
+        protocol: { type: "string", enum: ["V3"] },
+        limit: { type: "integer", minimum: 1, maximum: 100 },
+        network: { type: "string", enum: EVM_CORE_NETWORKS },
+      },
+      additionalProperties: false,
+    },
+  },
   {
     name: "swap_evm_uniswap_tokens",
     description: "Preview, prepare, or execute a supported Uniswap path on ethereum, base, or robinhood: CLASSIC, UniswapX orders, or canonical ETH↔WETH wrap/unwrap. ERC-20 paths may use Permit2 EIP-712 or an UniswapX order signature. Preview or prepare first. After the user explicitly confirms the shown summary in chat, call execute; the OpenClaw plugin handles the internal execution authorization automatically.",
@@ -2017,7 +2055,7 @@ const evmToolDefinitions = [
   },
   {
     name: "manage_evm_uniswap_liquidity",
-    description: "Preview, prepare, or execute a Uniswap V3/V4 liquidity action on ethereum, base, or robinhood. Supported actions are create, increase, decrease, and claim_fees. The official Liquidity API builds the transaction again immediately before signing, so confirmation is scoped to the LP intent rather than fragile ticks or calldata.",
+    description: "Preview, prepare, or execute a Uniswap V3/V4 liquidity action on ethereum, base, or robinhood. Supported actions are create, increase, decrease, and claim_fees. Create needs existingPool.poolReference and position actions need an NFT token id: use get_evm_uniswap_pools or the V3 get_evm_uniswap_positions scanner to obtain them, never guess. The official Liquidity API builds the transaction again immediately before signing, so confirmation is scoped to the LP intent rather than fragile ticks or calldata.",
     optional: true,
     parameters: {
       type: "object",

package/.openclaw/extensions/agent-wallet/index.ts

@@ -1995,6 +1995,44 @@ const evmToolDefinitions = [
       additionalProperties: false,
     },
   },
+  {
+    name: "get_evm_uniswap_pools",
+    description: "Find existing Uniswap V3/V4 pools through the official Pool Info API on ethereum, base, or robinhood. Returns the canonical poolReferenceIdentifier needed for an LP create request. Read-only: it does not approve, sign, or execute anything.",
+    parameters: {
+      type: "object",
+      properties: {
+        protocol: { type: "string", enum: ["V3", "V4"] },
+        pool_parameters: {
+          type: "object",
+          description: "Official Pool Info API token-pair parameters, such as tokenAddressA, tokenAddressB and optional fee/tickSpacing/hooks.",
+          additionalProperties: true,
+        },
+        pool_references: {
+          type: "array",
+          maxItems: 20,
+          items: { type: "object", additionalProperties: true },
+        },
+        page_size: { type: "integer", minimum: 1, maximum: 20 },
+        current_page: { type: "integer", minimum: 1 },
+        network: { type: "string", enum: EVM_CORE_NETWORKS },
+      },
+      required: ["protocol"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_evm_uniswap_positions",
+    description: "List the active wallet's Uniswap V3 LP NFTs on ethereum, base, or robinhood. Returns token ids, token pair, fee tier, ticks, liquidity, and owed fees. Read-only. V4 is excluded because its PositionManager is not enumerable without a verified indexed source.",
+    parameters: {
+      type: "object",
+      properties: {
+        protocol: { type: "string", enum: ["V3"] },
+        limit: { type: "integer", minimum: 1, maximum: 100 },
+        network: { type: "string", enum: EVM_CORE_NETWORKS },
+      },
+      additionalProperties: false,
+    },
+  },
   {
     name: "swap_evm_uniswap_tokens",
     description: "Preview, prepare, or execute a supported Uniswap path on ethereum, base, or robinhood: CLASSIC, UniswapX orders, or canonical ETH↔WETH wrap/unwrap. ERC-20 paths may use Permit2 EIP-712 or an UniswapX order signature. Preview or prepare first. After the user explicitly confirms the shown summary in chat, call execute; the OpenClaw plugin handles the internal execution authorization automatically.",
@@ -2017,7 +2055,7 @@ const evmToolDefinitions = [
   },
   {
     name: "manage_evm_uniswap_liquidity",
-    description: "Preview, prepare, or execute a Uniswap V3/V4 liquidity action on ethereum, base, or robinhood. Supported actions are create, increase, decrease, and claim_fees. The official Liquidity API builds the transaction again immediately before signing, so confirmation is scoped to the LP intent rather than fragile ticks or calldata.",
+    description: "Preview, prepare, or execute a Uniswap V3/V4 liquidity action on ethereum, base, or robinhood. Supported actions are create, increase, decrease, and claim_fees. Create needs existingPool.poolReference and position actions need an NFT token id: use get_evm_uniswap_pools or the V3 get_evm_uniswap_positions scanner to obtain them, never guess. The official Liquidity API builds the transaction again immediately before signing, so confirmation is scoped to the LP intent rather than fragile ticks or calldata.",
     optional: true,
     parameters: {
       type: "object",

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.94",
+  "version": "0.1.95",
   "contracts": {
     "tools": [
       "agentlayer_autonomous_approve",
@@ -64,6 +64,8 @@
       "manage_evm_lido_withdrawal",
       "manage_evm_uniswap_liquidity",
       "search_uniswap_pairs",
+      "get_evm_uniswap_pools",
+      "get_evm_uniswap_positions",
       "set_evm_network",
       "set_wallet_backend",
       "sign_wallet_message",

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

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

package/VERSION

@@ -1 +1 @@
-0.1.94
+0.1.95

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.94"
+__version__ = "0.1.95"
 
 __all__ = [
     "config",

package/agent-wallet/agent_wallet/openclaw_adapter.py

@@ -1746,12 +1746,62 @@ class OpenClawWalletAdapter:
                 )
                 tools.insert(
                     13,
+                    AgentToolSpec(
+                        name="get_evm_uniswap_pools",
+                        description=(
+                            "Find existing Uniswap V3/V4 pool metadata on ethereum, base, or robinhood using the official "
+                            "Uniswap Pool Info API. Returns the canonical poolReferenceIdentifier required to create liquidity; "
+                            "this is read-only and does not approve, sign, or execute anything."
+                        ),
+                        input_schema={
+                            "type": "object",
+                            "properties": {
+                                "protocol": {"type": "string", "enum": ["V3", "V4"]},
+                                "pool_parameters": {"type": "object", "description": "Official Pool Info API token-pair parameters, such as tokenAddressA, tokenAddressB and optional fee/tickSpacing/hooks.", "additionalProperties": True},
+                                "pool_references": {"type": "array", "maxItems": 20, "items": {"type": "object", "additionalProperties": True}, "description": "One to twenty official Pool Info API pool reference objects."},
+                                "page_size": {"type": "integer", "minimum": 1, "maximum": 20},
+                                "current_page": {"type": "integer", "minimum": 1},
+                                "network": {"type": "string", "enum": ["ethereum", "base", "robinhood"]},
+                            },
+                            "required": ["protocol"],
+                            "additionalProperties": False,
+                        },
+                        read_only=True,
+                        risk_level="low",
+                    ),
+                )
+                tools.insert(
+                    14,
+                    AgentToolSpec(
+                        name="get_evm_uniswap_positions",
+                        description=(
+                            "List read-only Uniswap V3 LP position NFTs owned by the active wallet on ethereum, base, or robinhood. "
+                            "Returns NFT token ids, tokens, fee tier, tick range, liquidity, and currently owed fees. V4 discovery is "
+                            "not exposed until a verified indexed source is configured because V4 PositionManager is not enumerable."
+                        ),
+                        input_schema={
+                            "type": "object",
+                            "properties": {
+                                "protocol": {"type": "string", "enum": ["V3"], "description": "V3 is the currently enumerable, on-chain-supported position scanner."},
+                                "limit": {"type": "integer", "minimum": 1, "maximum": 100},
+                                "network": {"type": "string", "enum": ["ethereum", "base", "robinhood"]},
+                            },
+                            "additionalProperties": False,
+                        },
+                        read_only=True,
+                        risk_level="low",
+                    ),
+                )
+                tools.insert(
+                    15,
                     AgentToolSpec(
                         name="manage_evm_uniswap_liquidity",
                         description=(
                             "Preview, prepare, or execute a Uniswap V3/V4 liquidity action on ethereum, base, or robinhood. "
                             "Supported actions are create, increase, decrease, and claim_fees. The request is passed to the "
-                            "official Uniswap Liquidity API; execute refreshes the transaction immediately before signing."
+                            "official Uniswap Liquidity API; execute refreshes the transaction immediately before signing. "
+                            "Create requires existingPool.poolReference; increase/decrease/claim_fees require a position NFT token id. "
+                            "Use get_evm_uniswap_pools or get_evm_uniswap_positions to obtain these identifiers; never guess them."
                         ),
                         input_schema={
                             "type": "object",
@@ -5682,6 +5732,46 @@ class OpenClawWalletAdapter:
                 )
                 return AgentToolResult(tool=tool_name, ok=True, data=data)
 
+            if tool_name == "get_evm_uniswap_pools":
+                protocol = args.get("protocol")
+                pool_parameters = args.get("pool_parameters")
+                pool_references = args.get("pool_references")
+                page_size = args.get("page_size", 20)
+                current_page = args.get("current_page", 1)
+                if protocol not in {"V3", "V4"}:
+                    raise WalletBackendError("protocol must be V3 or V4.")
+                if (pool_parameters is None) == (pool_references is None):
+                    raise WalletBackendError("Provide exactly one of pool_parameters or pool_references.")
+                if pool_parameters is not None and not isinstance(pool_parameters, dict):
+                    raise WalletBackendError("pool_parameters must be an object.")
+                if pool_references is not None:
+                    if not isinstance(pool_references, list) or not 1 <= len(pool_references) <= 20:
+                        raise WalletBackendError("pool_references must contain between 1 and 20 objects.")
+                    if any(not isinstance(reference, dict) for reference in pool_references):
+                        raise WalletBackendError("pool_references must contain only objects.")
+                if not isinstance(page_size, int) or not 1 <= page_size <= 20:
+                    raise WalletBackendError("page_size must be an integer between 1 and 20.")
+                if not isinstance(current_page, int) or current_page < 1:
+                    raise WalletBackendError("current_page must be a positive integer.")
+                data = await active_backend.get_uniswap_liquidity_pools(
+                    protocol=protocol,
+                    pool_parameters=pool_parameters,
+                    pool_references=pool_references,
+                    page_size=page_size,
+                    current_page=current_page,
+                )
+                return AgentToolResult(tool=tool_name, ok=True, data=data)
+
+            if tool_name == "get_evm_uniswap_positions":
+                protocol = args.get("protocol", "V3")
+                limit = args.get("limit", 20)
+                if protocol != "V3":
+                    raise WalletBackendError("Only V3 position discovery is currently available; V4 PositionManager is not enumerable.")
+                if not isinstance(limit, int) or not 1 <= limit <= 100:
+                    raise WalletBackendError("limit must be an integer between 1 and 100.")
+                data = await active_backend.get_uniswap_liquidity_positions(protocol=protocol, limit=limit)
+                return AgentToolResult(tool=tool_name, ok=True, data=data)
+
             if tool_name == "swap_evm_uniswap_tokens":
                 token_in = args.get("token_in")
                 token_out = args.get("token_out")
@@ -5826,13 +5916,49 @@ class OpenClawWalletAdapter:
                     raise WalletBackendError("mode must be 'preview', 'prepare' or 'execute'.")
                 if not isinstance(purpose, str) or not purpose.strip():
                     raise WalletBackendError("purpose is required.")
+                normalized_request = dict(request)
+                if action == "create":
+                    existing_pool = normalized_request.get("existingPool")
+                    if not isinstance(existing_pool, dict):
+                        raise WalletBackendError(
+                            "create requires existingPool with token0Address, token1Address, and poolReference. "
+                            "Use get_evm_uniswap_pools to obtain the exact existing pool; do not infer it from market search data."
+                        )
+                    missing_pool_fields = [
+                        field
+                        for field in ("token0Address", "token1Address", "poolReference")
+                        if not isinstance(existing_pool.get(field), str) or not existing_pool[field].strip()
+                    ]
+                    if missing_pool_fields:
+                        raise WalletBackendError(
+                            "create existingPool is missing "
+                            f"{', '.join(missing_pool_fields)}. Ask the user for the exact existing Uniswap pool; do not infer it from market search data."
+                        )
+                elif action in {"increase", "decrease"}:
+                    nft_token_id = normalized_request.get("nftTokenId")
+                    if not isinstance(nft_token_id, str) or not nft_token_id.strip().isdigit() or int(nft_token_id.strip()) <= 0:
+                        raise WalletBackendError(
+                            f"{action} requires a positive nftTokenId. Use get_evm_uniswap_positions for V3 or request a verified V4 token id; never infer it."
+                        )
+                    normalized_request["nftTokenId"] = nft_token_id.strip()
+                else:  # claim_fees
+                    token_id = normalized_request.get("tokenId", normalized_request.get("nftTokenId"))
+                    if not isinstance(token_id, str) or not token_id.strip().isdigit() or int(token_id.strip()) <= 0:
+                        raise WalletBackendError(
+                            "claim_fees requires the user's positive tokenId (the LP position NFT id). "
+                            "Use get_evm_uniswap_positions for V3 or request a verified V4 token id; never infer it."
+                        )
+                    # The Liquidity API names this field tokenId for fee claims;
+                    # accept nftTokenId as the user-facing alias used by other LP actions.
+                    normalized_request["tokenId"] = token_id.strip()
+                    normalized_request.pop("nftTokenId", None)
                 # The caller must not override values that are derived from the
                 # active wallet/network in the WDK layer.
                 forbidden = {"walletAddress", "chainId", "protocol", "simulateTransaction", "signature", "batchPermitData", "v4BatchPermitData", "v3NftPermitData"}
                 overlap = forbidden.intersection(request)
                 if overlap:
                     raise WalletBackendError(f"request must not set wallet-controlled fields: {', '.join(sorted(overlap))}.")
-                preview_kwargs = {"action": action, "protocol": protocol, "request": dict(request)}
+                preview_kwargs = {"action": action, "protocol": protocol, "request": normalized_request}
                 if mode == "preview":
                     preview = await active_backend.preview_uniswap_liquidity(**preview_kwargs)
                     return AgentToolResult(tool=tool_name, ok=True, data=self._annotate_sensitive_payload(preview, action_label="Uniswap liquidity", mode="preview"))

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

@@ -337,6 +337,25 @@ class AgentWalletBackend(ABC):
     ) -> dict[str, Any]:
         raise WalletBackendError(f"{self.name} does not support Uniswap pair search.")
 
+    async def get_uniswap_liquidity_pools(
+        self,
+        *,
+        protocol: str,
+        pool_parameters: dict[str, Any] | None = None,
+        pool_references: list[dict[str, Any]] | None = None,
+        page_size: int = 20,
+        current_page: int = 1,
+    ) -> dict[str, Any]:
+        raise WalletBackendError(f"{self.name} does not support Uniswap liquidity pool discovery.")
+
+    async def get_uniswap_liquidity_positions(
+        self,
+        *,
+        protocol: str = "V3",
+        limit: int = 20,
+    ) -> dict[str, Any]:
+        raise WalletBackendError(f"{self.name} does not support Uniswap liquidity position discovery.")
+
     async def send_uniswap_swap(
         self,
         *,

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

@@ -1957,6 +1957,66 @@ class WdkEvmLocalWalletBackend(AgentWalletBackend):
             "source": "dexscreener",
         }
 
+    async def get_uniswap_liquidity_pools(
+        self,
+        *,
+        protocol: str,
+        pool_parameters: dict[str, Any] | None = None,
+        pool_references: list[dict[str, Any]] | None = None,
+        page_size: int = 20,
+        current_page: int = 1,
+    ) -> dict[str, Any]:
+        if protocol not in {"V3", "V4"}:
+            raise WalletBackendError("protocol must be V3 or V4.")
+        if (pool_parameters is None) == (pool_references is None):
+            raise WalletBackendError("Provide exactly one of pool_parameters or pool_references.")
+        if pool_parameters is not None and not isinstance(pool_parameters, dict):
+            raise WalletBackendError("pool_parameters must be an object.")
+        if pool_references is not None:
+            if not isinstance(pool_references, list) or not 1 <= len(pool_references) <= 20:
+                raise WalletBackendError("pool_references must contain between 1 and 20 objects.")
+            if any(not isinstance(reference, dict) for reference in pool_references):
+                raise WalletBackendError("pool_references must contain only objects.")
+        if not isinstance(page_size, int) or not 1 <= page_size <= 20:
+            raise WalletBackendError("page_size must be an integer between 1 and 20.")
+        if not isinstance(current_page, int) or current_page < 1:
+            raise WalletBackendError("current_page must be a positive integer.")
+        body: dict[str, Any] = {
+            "network": self.network,
+            "protocol": protocol,
+            "pageSize": page_size,
+            "currentPage": current_page,
+        }
+        if pool_parameters is not None:
+            body["poolParameters"] = pool_parameters
+        else:
+            body["poolReferences"] = pool_references
+        data = await self.client.post("/v1/evm/uniswap/liquidity/pools", body)
+        return dict(data)
+
+    async def get_uniswap_liquidity_positions(
+        self,
+        *,
+        protocol: str = "V3",
+        limit: int = 20,
+    ) -> dict[str, Any]:
+        if protocol not in {"V3", "V4"}:
+            raise WalletBackendError("protocol must be V3 or V4.")
+        if not isinstance(limit, int) or not 1 <= limit <= 100:
+            raise WalletBackendError("limit must be an integer between 1 and 100.")
+        data = await self.client.post(
+            "/v1/evm/uniswap/liquidity/positions",
+            {
+                "walletId": self.wallet_id,
+                "address": await self.get_address(),
+                "accountIndex": self.account_index,
+                "network": self.network,
+                "protocol": protocol,
+                "limit": limit,
+            },
+        )
+        return dict(data)
+
     async def send_uniswap_swap(
         self,
         *,

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.94",
+  "version": "0.1.95",
   "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.94"
+version = "0.1.95"
 description = "Plugin-friendly wallet backend for OpenClaw agents"
 requires-python = ">=3.10"
 dependencies = [

package/agent-wallet/scripts/install_agent_wallet.py

@@ -513,6 +513,26 @@ def _pip_install_editable(python_bin: Path, package_root: Path) -> None:
     )
 
 
+def _python_runtime_is_healthy(python_bin: Path) -> bool:
+    """Return whether a reusable venv has the installer dependencies available.
+
+    A shared runtime can be left half-created when an install is interrupted
+    between ``venv`` creation and the editable pip install.  The interpreter
+    itself then exists, but the next update must repair it rather than treating
+    it as a valid cache entry.
+    """
+    try:
+        result = subprocess.run(
+            [str(python_bin), "-c", "import pydantic, pydantic_settings"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return False
+    return result.returncode == 0
+
+
 def _ensure_python_runtime(
     venv_path: Path,
     package_root: Path,
@@ -529,9 +549,17 @@ def _ensure_python_runtime(
             created = True
             _bootstrap_venv_pip(python_bin)
             _pip_install_editable(python_bin, package_root)
+        elif not _python_runtime_is_healthy(python_bin):
+            # A prior update may have been interrupted after creating the venv
+            # but before pip finished. Repair the cache in place; release links
+            # continue to point at one verified shared environment.
+            _bootstrap_venv_pip(python_bin)
+            _pip_install_editable(python_bin, package_root)
+            plan["action"] = "repair"
         shared_wrapper = _ensure_python_wrapper(shared_venv_path)
         _replace_with_directory_symlink(venv_path, shared_venv_path)
-        plan["action"] = "create" if created else "reuse"
+        if created:
+            plan["action"] = "create"
         plan["exists"] = True
         return (
             venv_path / shared_wrapper.relative_to(shared_venv_path),

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

@@ -1,7 +1,7 @@
 {
   "name": "agent-wallet",
   "displayName": "Agent Wallet",
-  "version": "0.1.94",
+  "version": "0.1.95",
   "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/AGENTLAYER_AGENT_GUIDE.md

@@ -0,0 +1,282 @@
+# AgentLayer Wallet — Agent Guide
+
+> **Relationship to `skills/wallet-operator/SKILL.md`:** that file is the
+> authoritative, terse routing skill actually loaded by hosts (provider map, param
+> tables, approval-flow template) — keep changes to tool routing/params there, not
+> here. This document is a narrative companion: written the way an agent (or a human
+> reading over its shoulder) would want the product *explained*, not just routed —
+> modeled on how the `catena` CLI ships a self-contained `catena guide` command
+> alongside its terse `--help` output; the `/guide` command in this plugin serves
+> that exact role. Tool names below are short; the full MCP name is
+> `mcp__plugin_agent-wallet_agent-wallet__<name>`.
+
+This server holds funds in the local AgentLayer wallet across Solana, EVM
+(Ethereum, Base, Robinhood chain), and Bitcoin. It is not a generic
+crypto-data tool — every write here moves real money unless stated as
+mainnet-gated preview. Leverage markets (Flash Trade perps:
+`flash_trade_open_position`, `flash_trade_close_position`,
+`get_flash_trade_markets`, `get_flash_trade_positions`) are out of scope for
+this guide — do not use them without separate instructions.
+
+## What You Can Do
+
+- **Solana**: transfers, swaps via Jupiter, native staking, Kamino (lending +
+  earn vaults + LP positions), token launches via Bags.
+- **EVM** (Ethereum / Base / Robinhood): transfers, swaps (Velora or
+  Uniswap), and DeFi — Aave (lending), Lido (ETH staking), Morpho (markets +
+  vaults), and Uniswap concentrated liquidity positions (create / increase /
+  decrease / claim fees, V3 and V4 — existing V4 positions can't be
+  auto-discovered, only V3; for a V4 position the id has to come from the
+  user).
+- **Cross-chain bridging** (LI.FI): Ethereum / Base / Solana to each other.
+- **x402**: pay per-request HTTP 402 paywalls straight from the wallet —
+  preview the payment terms for free, then pay in one call.
+
+See the sections below for exact tool names and parameters.
+
+## Setup & Session State
+
+1. `get_active_wallet_backend` — which backend (solana / evm / btc) is live
+   for this session, and whether it differs from the startup default.
+2. `get_wallet_address` — the address for the active backend.
+3. `get_wallet_capabilities` — chain, backend, and the safety limits in force.
+4. `set_wallet_backend` (`backend`: solana / evm / ethereum / base /
+   robinhood / btc / bitcoin, optional `network`) — switch backend for this
+   session without touching config files.
+5. For EVM specifically: `get_evm_network` shows the effective network and
+   which networks support swaps; `set_evm_network` (ethereum / base /
+   robinhood) changes it.
+
+Balance reads (Solana): `get_wallet_balance` / `get_wallet_portfolio` are the
+same enriched payload (native SOL + non-zero SPL accounts + USD pricing via
+Jupiter) — `_portfolio` is just the more detailed name for the same call.
+`get_wallet_overview` does the same lookup for an arbitrary backend/network/
+address **without** switching the session's active wallet — use it to peek at
+another chain or address in passing.
+
+## Quick Commands (Claude Code slash commands)
+
+The plugin also ships fixed-format slash commands for the most common
+requests — faster and more predictable than a free-form tool call, but each
+covers only its one exact use case:
+
+| Command | What it does |
+|---|---|
+| `/wallet-setup` | Install or repair the local wallet backend runtime. |
+| `/wallet-sol` | Print the Solana wallet portfolio. |
+| `/wallet-evm` | Print the EVM wallet overview for the current/default network. |
+| `/wallet-base` | Print the Base wallet overview, and switch the session's active backend to Base. |
+| `/wallet-ethereum` | Print the Ethereum mainnet wallet overview. |
+| `/cards` | Buy a Laso Finance prepaid card (US or international), paid via x402 from the connected wallet. |
+| `/agentlayer-autonomous-approve` | Turn on the full autonomous permission group (see below), with an in-command confirmation step first. |
+| `/agentlayer-autonomous-revoke` | Turn it back off. |
+| `/guide` | Walk a new user through this document conversationally. |
+
+Every command except `/wallet-setup` requires the user to type it themselves
+— the agent cannot trigger them on its own.
+
+## The preview → prepare → execute → approve Pattern
+
+Nearly every write tool (transfers, swaps, staking, DeFi positions, BTC
+sends, token launch) shares one lifecycle via a `mode` argument:
+
+- `preview` — read-only summary of what the operation would do. No signing,
+  no broadcast. Always do this first.
+- `prepare` — returns an execution plan (unsigned) for the same operation.
+  Requires `user_intent: true`. Used when the host needs to inspect the plan
+  before approving.
+- `execute` — actually signs and broadcasts. Requires a host-issued approval
+  token bound to the exact previewed operation. In an interactive session the
+  host's own confirmation dialog supplies this. When it doesn't,
+  `issue_wallet_approval` is the explicit bridge step: call it with the
+  `tool_name` and the verbatim `confirmation_summary` from the prepare
+  response, plus `mainnet_confirmed: true` to acknowledge real funds are at
+  stake.
+
+In Claude Code, don't call `issue_wallet_approval` or ask the user for a raw
+`approval_token` yourself — the host's own confirmation dialog supplies it
+once the user approves the call.
+
+Never skip straight to `execute` on a mainnet operation the user has not
+explicitly approved. Preview it, show the human what it does, then execute.
+
+Always pass a short `purpose` string on write calls — it's the human-facing
+audit label for what the transaction is for.
+
+## Standing Authority: Autonomous Sessions
+
+Two separate mechanisms remove the per-transaction approval step. Both grant
+broad, real-money authority and must only be turned on when the user has
+explicitly asked for it:
+
+- **Scoped autonomous session** — `start_autonomous_session` (preview then
+  execute) opens a bounded session: `allowed_tools`, `allowed_networks`,
+  `allowed_recipients`, per-tx / hourly / daily spend caps, tx-rate cap,
+  operation count cap, and a session TTL. `allow_mainnet: true` is required to
+  let it touch real funds. `get_autonomous_session` reads current status
+  (active, limits, operations used, expiry); `stop_autonomous_session` always
+  works and hands control back to per-transaction approval.
+- **Full high-trust permission group** — `agentlayer_autonomous_approve`
+  (scope `all`) is broader and unbounded by comparison: it covers *every*
+  wallet write tool (transfers, bridges, Solana swaps, staking, x402
+  payments, contract calls, EVM DeFi management) with no per-operation
+  allow-list. Requires `user_intent: true` and an explicit purpose.
+  `agentlayer_autonomous_status` reads it; `agentlayer_autonomous_revoke`
+  turns it off.
+
+Prefer the scoped session over the full permission group whenever the task
+has a defined boundary (a specific token, a specific recipient, a spend cap)
+— it's the difference between "let the agent do this one job unattended" and
+"let the agent spend freely until told to stop."
+
+There is no narrower version of the full permission group — pass `scope:
+"all"`; for a bounded grant, use the scoped session instead.
+
+## Solana
+
+- **Transfers**: `transfer_sol` (native), `transfer_spl_token` (by mint
+  address, optional `decimals` override).
+- **Swaps**: `swap_solana_tokens` routes through Jupiter. Prefer
+  `mode: intent_preview` then `intent_execute` — it re-quotes fresh
+  immediately before sending and only executes within the previously
+  approved limits, which matters because Jupiter quotes expire fast. Legacy
+  `preview`/`prepare`/`execute` still works but is not preferred.
+- **Prices**: `get_solana_token_prices` — Jupiter prices for a list of mints.
+- **Housekeeping**: `close_empty_token_accounts` reclaims rent from
+  zero-balance SPL token accounts (preview lists them, execute closes up to
+  `limit`, default 8).
+- **Native staking** (Solana Stake Program, not a DeFi protocol):
+  `stake_sol_native` (to a validator vote account), `get_solana_stake_account`
+  (activation status of one stake account), `get_solana_staking_validators`
+  (list validators by commission/activated stake), `deactivate_solana_stake`,
+  `withdraw_solana_stake`.
+- **Kamino** (Solana's largest lend/earn/liquidity protocol):
+  - Discovery (read-only): `get_kamino_lend_markets` → main market first;
+    `get_kamino_lend_market_reserves` for per-token supply/borrow APY and
+    maxLtv; `get_kamino_vaults` for Earn-vault discovery
+    (`include_metrics: true` for APY/TVL, `token_mint` to filter).
+  - Lending writes: `kamino_lend_deposit`, `kamino_lend_borrow`,
+    `kamino_lend_repay`, `kamino_lend_withdraw` — all take `market`, `reserve`,
+    `amount_ui`; prefer `intent_preview` → `intent_execute` for the same
+    re-quote-before-send reason as swaps.
+  - Earn vault writes: `kamino_earn_deposit`, `kamino_earn_withdraw` (take
+    `kvault`, `amount_ui`).
+  - Position reads: `get_kamino_lend_user_obligations` (one market),
+    `get_kamino_open_positions` (all lending positions across markets),
+    `get_kamino_earn_positions`, `get_kamino_liquidity_positions`,
+    `get_kamino_lend_user_rewards`, and `get_kamino_portfolio` for the single
+    unified view across lending/earn/liquidity/staking.
+- **Token launch**: `launch_bags_token` creates a token via Bags with a
+  fee-share config (`claimers` + `basis_points`, must sum to 10000) and an
+  optional `initial_buy_sol`. Same preview/prepare/execute lifecycle.
+
+## EVM (Ethereum, Base, Robinhood chain)
+
+- **Read utilities**: `get_evm_token_balance`, `get_evm_token_metadata`,
+  `get_evm_transaction_receipt` (by tx hash), `get_evm_fee_rates`.
+- **Transfers**: `transfer_evm_native` (wei), `transfer_evm_token` (ERC-20,
+  raw base units + `token_address`).
+- **Swaps — two independent routers, pick one**:
+  - Velora: `get_evm_swap_quote` (read-only) → `swap_evm_tokens`. Ethereum/
+    Base only.
+  - Uniswap: `get_uniswap_swap_quote` → `swap_evm_uniswap_tokens`. Covers
+    CLASSIC pools, UniswapX orders, and ETH↔WETH wrap/unwrap; supports
+    Ethereum, Base, and Robinhood chain; has a `slippage_bps` param (default
+    300 = 3%).
+  - `search_uniswap_pairs` finds a token's contract address by ticker/name
+    via DexScreener — **security note**: free-text ticker search can surface
+    impersonator tokens with fabricated liquidity/FDV, especially for tickers
+    claiming to represent a real-world stock/ETF. Verify the resolved
+    `token_address` independently (`get_evm_token_metadata`, or the chain's
+    official contract list) before quoting or swapping a real-world-asset
+    ticker — a successful quote does not itself prove legitimacy.
+- **DeFi protocols** (read tools are free; every write follows preview →
+  execute):
+  - **Aave v3** (lending): `get_evm_aave_account` (health factor etc.),
+    `get_evm_aave_positions` (per-reserve supplied/borrowed),
+    `get_evm_aave_reserves` (market catalog) →
+    `manage_evm_aave_position` with `operation`: supply / withdraw / borrow /
+    repay.
+  - **Lido** (ETH liquid staking, Ethereum mainnet only):
+    `get_evm_lido_overview`, `get_evm_lido_positions` (stETH/wstETH),
+    `get_evm_lido_withdrawal_requests` →
+    `manage_evm_lido_position` (`stake_eth_for_wsteth` / `wrap_steth` /
+    `unwrap_wsteth`) and `manage_evm_lido_withdrawal`
+    (`request_withdrawal_steth` / `request_withdrawal_wsteth` /
+    `claim_withdrawal`, needs `request_id` to claim).
+  - **Morpho** (lending markets + curated vaults): `get_evm_morpho_markets` /
+    `get_evm_morpho_vaults` for discovery (filter by asset, sort by APY —
+    pair APY sorts with a `min_supply_usd`/`min_tvl_usd` floor to skip dust),
+    `get_evm_morpho_positions` for what the wallet currently holds →
+    `manage_evm_morpho_market_position` (supply_collateral / borrow / repay /
+    withdraw_collateral, isolated market by `market_id` or `market_preset`)
+    and `manage_evm_morpho_vault_position` (supply / withdraw, by
+    `vault_address` or `vault_preset`).
+  - **Uniswap Liquidity Provisioning** (concentrated LP positions, V3 and
+    V4): discovery first — `get_evm_uniswap_pools` finds an existing pool by
+    token pair and returns its `poolReferenceIdentifier`;
+    `get_evm_uniswap_positions` lists the wallet's V3 position NFTs (fee
+    tier, tick range, owed fees) — V4 position discovery isn't available
+    (V4's PositionManager isn't enumerable on-chain the way V3's is) →
+    `manage_evm_uniswap_liquidity` with `action`: create / increase /
+    decrease / claim_fees. `create` needs `existingPool.poolReference` (the
+    discovery tool's `poolReferenceIdentifier` value, under a different
+    field name); increase/decrease/claim_fees need the position's NFT token
+    id. Never guess either identifier — always discover it first, the tool
+    rejects the call outright if it's missing. This is a thin pass-through
+    to Uniswap's own official Liquidity API; deploying a brand-new pool is
+    out of scope.
+
+## Cross-Chain Bridging (LI.FI)
+
+- `get_lifi_supported_chains` — currently allowed chains for routing.
+- `get_lifi_quote` — read-only quote between any two of Ethereum / Base /
+  Solana (bridge preferences via `allow_bridges` / `deny_bridges` /
+  `prefer_bridges`, slippage as a decimal fraction).
+- `swap_evm_lifi_cross_chain_tokens` — execute EVM-origin (Ethereum/Base) →
+  Ethereum/Base/Solana.
+- `swap_solana_lifi_cross_chain_tokens` — execute Solana-origin →
+  Ethereum/Base.
+- `get_lifi_transfer_status` — poll a bridge transfer by source tx hash.
+
+Same preview/prepare/execute + approval-token discipline as everything else.
+Mayan routes are deliberately denied — see `skills/wallet-operator/SKILL.md`.
+
+## Bitcoin
+
+- `transfer_btc` — amount in `amount_sats`, optional `fee_rate` (sats/vB) or
+  `confirmation_target`.
+- `get_btc_fee_rates`, `get_btc_max_spendable` (post-fee spendable estimate),
+  `get_btc_transfer_history` (filter by `direction`, paginate with
+  `limit`/`skip`).
+
+## x402 — Paying HTTP 402 Endpoints
+
+- `x402_search_services` — read-only discovery of paid services via CDP
+  Bazaar or Agentic Market (filter by `query`, `max_usd_price`, `network`).
+- `x402_get_service_details` — resolve one service/resource URL into details.
+- `x402_preview_request` — makes the *unpaid* request, reads the 402
+  challenge, and summarizes payment options. Does not pay.
+- `x402_pay_request` — does the whole flow in one call: probes the endpoint,
+  validates it, signs the payment from the active wallet backend, and
+  returns the paid response. Requires `purpose`.
+
+This is the same x402 v2 protocol the `catena` MCP/CLI speaks — a discrete
+pay-per-request charge, not a subscription or usage meter — but here the
+payer is this wallet directly rather than a governed bank rail, so there is
+no separate approval-parking step: the preview → execute discipline above is
+what stands between the agent and the payment.
+
+## Explaining This to a Human
+
+If asked to summarize this server in plain terms: it's a direct line to the
+local AgentLayer wallet — Solana, an EVM chain (Ethereum/Base/Robinhood),
+and Bitcoin — plus the major yield/lending/LP protocols on those chains
+(Kamino, Aave, Lido, Morpho, Uniswap concentrated liquidity) and the ability
+to pay per-request API/data paywalls (x402) straight from the wallet.
+Everything that moves funds is gated by a preview step and an approval token
+by default; "autonomous session" and "autonomous permission group" are the
+two ways a human can explicitly grant the agent standing authority to skip
+that per-transaction gate, bounded (the former) or broad (the latter) —
+always confirm with the user before either one is enabled, and treat any
+operation on mainnet as real, irreversible money movement.

package/claude-code/plugins/agent-wallet/README.md

@@ -66,6 +66,8 @@ no-op once the backend is healthy.
   explicit in-command confirmation before enabling the standing permission.
 - `/agentlayer-autonomous-revoke` — disable the combined autonomous permission
   group for Base swaps and supported EVM DeFi tools.
+- `/guide` — walk a new user through what this plugin can do, conversationally
+  (see `AGENTLAYER_AGENT_GUIDE.md` for the source material).
 - `AGENT_WALLET_AUTO_BOOTSTRAP=0` — opt out of the auto-install: the
   `SessionStart` hook then only reminds you to run `/wallet-setup` instead of
   installing the backend itself.

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

@@ -0,0 +1,40 @@
+---
+description: Walk a new user through what the AgentLayer wallet plugin can do, conversationally.
+allowed-tools: Bash(cat:*)
+disable-model-invocation: true
+---
+
+Give the user a plain-language walkthrough of this wallet plugin, the way
+you'd onboard someone who has never used it before.
+
+1. Read the source material:
+
+```
+cat "${CLAUDE_PLUGIN_ROOT}/AGENTLAYER_AGENT_GUIDE.md"
+```
+
+2. Do not paste or summarize the raw file section-by-section. Retell it as a
+   conversational walkthrough, addressed directly to the user ("you"), in
+   the language they've been using. Cover, roughly in this order:
+
+   - **What it is** — a direct line to their own local AgentLayer wallet
+     (Solana, an EVM chain, Bitcoin), not a generic crypto-data tool; every
+     write moves real money unless it's an explicit preview.
+   - **What they can do** — the "What You Can Do" list: Solana (transfers,
+     Jupiter swaps, staking, Kamino, Bags launches), EVM (transfers, swaps,
+     Aave/Lido/Morpho/Uniswap LP), cross-chain bridging, x402 payments.
+   - **How a session works** — the agent checks which backend/network is
+     active before doing anything, and can switch between them.
+   - **The quick commands** — list the slash commands from the "Quick
+     Commands" table by name and one-line purpose only; skip why each one
+     is or isn't model-invokable, that's implementation detail.
+   - **How money-moving operations work** — preview first, then execute
+     only after they confirm; keep this to the outcome (see it, approve it,
+     then it happens), not the internal approval-token mechanics.
+   - **Autonomous mode** — that it exists as an opt-in way to skip
+     per-operation confirmation, with a bounded (scoped) and an unbounded
+     (full) version, and that either requires them to explicitly ask for it.
+
+3. Keep the whole thing skimmable — short paragraphs or a few bullets per
+   topic, no wall of text. Close by inviting them to ask about any specific
+   chain or protocol for the exact tool-level detail.

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

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

package/hermes/plugins/agent_wallet/plugin.yaml

@@ -1,5 +1,5 @@
 name: agent-wallet
-version: 0.1.94
+version: 0.1.95
 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.94",
+  "version": "0.1.95",
   "description": "Universal AgentLayer wallet installer for OpenClaw, Codex, Claude Code, and Hermes.",
   "type": "module",
   "repository": {

package/wdk-btc-wallet/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wdk-btc-wallet",
-  "version": "0.1.94",
+  "version": "0.1.95",
   "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.94",
+  "version": "0.1.95",
   "private": true,
   "type": "module",
   "description": "Separate EVM wallet service built on Tether WDK.",

package/wdk-evm-wallet/src/server.js

@@ -646,6 +646,18 @@ async function handleRequest(request, response) {
       return sendJson(response, 200, { ok: true, data });
     }
 
+    if (method === "POST" && url.pathname === "/v1/evm/uniswap/liquidity/pools") {
+      const body = await withResolvedNetwork(await readJsonBody(request));
+      const data = await service.getUniswapLiquidityPools(body);
+      return sendJson(response, 200, { ok: true, data });
+    }
+
+    if (method === "POST" && url.pathname === "/v1/evm/uniswap/liquidity/positions") {
+      const body = await withResolvedNetwork(await withResolvedSeedOrAddress(await readJsonBody(request)));
+      const data = await service.getUniswapLiquidityPositions(body);
+      return sendJson(response, 200, { ok: true, data });
+    }
+
     if (method === "POST" && url.pathname === "/v1/evm/uniswap/liquidity/send") {
       const body = await withResolvedNetwork(await withResolvedSeed(await readJsonBody(request)));
       const data = await service.sendUniswapLiquidity(body);

package/wdk-evm-wallet/src/wdk_evm_wallet.js

@@ -45,6 +45,14 @@ const UNISWAP_LIQUIDITY_POSITION_MANAGERS = {
 const ERC20_APPROVE_INTERFACE = new Interface([
   "function approve(address spender,uint256 amount) returns (bool)",
 ]);
+// V3 PositionManager is ERC-721 enumerable, so positions owned by the active
+// wallet can be discovered and then read directly from the canonical contract.
+// V4 deliberately is not enumerable; see getUniswapLiquidityPositions below.
+const UNISWAP_V3_POSITION_MANAGER_INTERFACE = new Interface([
+  "function balanceOf(address owner) view returns (uint256)",
+  "function tokenOfOwnerByIndex(address owner,uint256 index) view returns (uint256)",
+  "function positions(uint256 tokenId) view returns (uint96 nonce,address operator,address token0,address token1,uint24 fee,int24 tickLower,int24 tickUpper,uint128 liquidity,uint256 feeGrowthInside0LastX128,uint256 feeGrowthInside1LastX128,uint128 tokensOwed0,uint128 tokensOwed1)",
+]);
 // Every executable path is declared here rather than inferred from a Trading
 // API response. A new chain/router version therefore requires an explicit,
 // reviewed allow-list entry before it can receive a signed transaction.
@@ -6015,6 +6023,122 @@ export class WdkEvmWalletService {
     };
   }
 
+  async getUniswapLiquidityPools({ protocol, poolParameters, poolReferences, pageSize = 20, currentPage = 1, network }) {
+    const runtimeConfig = this.#resolveRuntimeConfig(network);
+    assertUniswapSupportedNetwork(runtimeConfig.network);
+    const normalizedProtocol = normalizeUniswapLiquidityProtocol(protocol);
+    const hasParameters = poolParameters !== undefined && poolParameters !== null;
+    const hasReferences = poolReferences !== undefined && poolReferences !== null;
+    if (hasParameters === hasReferences) {
+      throw new Error("Provide exactly one of poolParameters or poolReferences.");
+    }
+    const boundedPageSize = Number(pageSize);
+    const normalizedPageSize = Number.isInteger(boundedPageSize) && boundedPageSize > 0
+      ? Math.min(boundedPageSize, 20)
+      : 20;
+    const boundedCurrentPage = Number(currentPage);
+    const normalizedCurrentPage = Number.isInteger(boundedCurrentPage) && boundedCurrentPage > 0
+      ? boundedCurrentPage
+      : 1;
+    const body = {
+      protocol: normalizedProtocol,
+      chainId: runtimeConfig.chainId,
+      pageSize: normalizedPageSize,
+      currentPage: normalizedCurrentPage,
+    };
+    if (hasParameters) {
+      body.poolParameters = assertPlainObject(poolParameters, "poolParameters");
+    } else {
+      if (!Array.isArray(poolReferences) || poolReferences.length === 0 || poolReferences.length > 20) {
+        throw new Error("poolReferences must be an array containing between 1 and 20 references.");
+      }
+      body.poolReferences = poolReferences.map((reference, index) => assertPlainObject(reference, `poolReferences[${index}]`));
+    }
+    const payload = await this.#uniswapLiquidityApiRequest("pool_info", body);
+    return {
+      network: runtimeConfig.network,
+      chainId: runtimeConfig.chainId,
+      protocol: normalizedProtocol,
+      requestId: String(payload?.requestId || "").trim() || null,
+      pools: Array.isArray(payload?.pools) ? payload.pools : [],
+      pageSize: Number(payload?.pageSize ?? normalizedPageSize),
+      currentPage: Number(payload?.currentPage ?? normalizedCurrentPage),
+      source: "uniswap-liquidity-api",
+    };
+  }
+
+  async getUniswapLiquidityPositions({ seedPhrase, address, protocol = "V3", accountIndex = 0, network, limit = 20 }) {
+    return this.#withReadableAccount({ seedPhrase, address, accountIndex, network }, async (account, runtimeConfig) => {
+      assertUniswapSupportedNetwork(runtimeConfig.network);
+      const normalizedProtocol = normalizeUniswapLiquidityProtocol(protocol);
+      if (normalizedProtocol === "V4") {
+        // Uniswap's V4 PositionManager is intentionally not ERC-721 enumerable.
+        // Discovering token IDs requires a chain-specific indexed subgraph, then
+        // on-chain verification. Do not pretend balanceOf/tokenOfOwnerByIndex is
+        // available or ask an RPC provider to scan unbounded transfer history.
+        throw createTaggedError(
+          "Uniswap V4 position discovery requires a configured indexed subgraph; the V4 PositionManager is not ERC-721 enumerable.",
+          "uniswap_v4_position_discovery_unavailable",
+          { network: runtimeConfig.network }
+        );
+      }
+      const owner = await account.getAddress();
+      const positionManager = getUniswapLiquidityPositionManager(runtimeConfig.network, "V3");
+      const rawBalance = await callContract(
+        runtimeConfig.providerUrl,
+        positionManager,
+        UNISWAP_V3_POSITION_MANAGER_INTERFACE,
+        "balanceOf",
+        [owner]
+      );
+      const balance = BigInt(rawBalance[0]);
+      const requestedLimit = Number(limit);
+      const boundedLimit = Number.isInteger(requestedLimit) && requestedLimit > 0 ? Math.min(requestedLimit, 100) : 20;
+      const count = Number(balance > BigInt(boundedLimit) ? BigInt(boundedLimit) : balance);
+      const positions = [];
+      for (let index = 0; index < count; index += 1) {
+        const tokenIdResult = await callContract(
+          runtimeConfig.providerUrl,
+          positionManager,
+          UNISWAP_V3_POSITION_MANAGER_INTERFACE,
+          "tokenOfOwnerByIndex",
+          [owner, index]
+        );
+        const tokenId = BigInt(tokenIdResult[0]);
+        const position = await callContract(
+          runtimeConfig.providerUrl,
+          positionManager,
+          UNISWAP_V3_POSITION_MANAGER_INTERFACE,
+          "positions",
+          [tokenId]
+        );
+        positions.push({
+          tokenId: tokenId.toString(),
+          token0: String(position[2]),
+          token1: String(position[3]),
+          fee: Number(position[4]),
+          tickLower: Number(position[5]),
+          tickUpper: Number(position[6]),
+          liquidity: BigInt(position[7]).toString(),
+          tokensOwed0: BigInt(position[10]).toString(),
+          tokensOwed1: BigInt(position[11]).toString(),
+        });
+      }
+      return {
+        network: runtimeConfig.network,
+        chainId: runtimeConfig.chainId,
+        protocol: "V3",
+        owner,
+        positionManager,
+        totalCount: balance.toString(),
+        returnedCount: positions.length,
+        truncated: balance > BigInt(positions.length),
+        positions,
+        source: "uniswap-v3-position-manager",
+      };
+    });
+  }
+
   async quoteUniswapLiquidity({ seedPhrase, address, action, protocol, request, accountIndex = 0, network }) {
     return this.#withReadableAccount({ seedPhrase, address, accountIndex, network }, async (account, runtimeConfig) => {
       assertUniswapSupportedNetwork(runtimeConfig.network);