wayfinder-paths 0.1.23__py3-none-any.whl → 0.1.25__py3-none-any.whl

wayfinder_paths/mcp/tools/balances.py

@@ -0,0 +1,290 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Literal
+
+import httpx
+
+from wayfinder_paths.core.config import get_api_base_url, get_api_key
+from wayfinder_paths.core.constants.base import DEFAULT_HTTP_TIMEOUT
+from wayfinder_paths.mcp.utils import err, find_wallet_by_label, normalize_address, ok
+
+
+class _BalanceClient:
+    def __init__(self):
+        self.api_base_url = get_api_base_url()
+        timeout = httpx.Timeout(DEFAULT_HTTP_TIMEOUT)
+        self.client = httpx.AsyncClient(timeout=timeout)
+        self._headers = {"Content-Type": "application/json"}
+        api_key = get_api_key()
+        if api_key:
+            self._headers["X-API-KEY"] = api_key
+
+    async def close(self):
+        await self.client.aclose()
+
+    async def get_enriched_wallet_balances(
+        self,
+        *,
+        wallet_address: str,
+        exclude_spam_tokens: bool = True,
+    ) -> dict:
+        url = f"{self.api_base_url}/blockchain/balances/enriched/"
+        params = {
+            "address": wallet_address,
+            "exclude_spam_tokens": str(exclude_spam_tokens).lower(),
+        }
+        response = await self.client.get(url, params=params, headers=self._headers)
+        response.raise_for_status()
+        return response.json()
+
+    async def get_wallet_activity(
+        self,
+        *,
+        wallet_address: str,
+        limit: int = 20,
+        offset: str | None = None,
+    ) -> dict:
+        url = f"{self.api_base_url}/blockchain/balances/activity/"
+        params: dict[str, str | int] = {"address": wallet_address, "limit": limit}
+        if offset:
+            params["offset"] = offset
+        response = await self.client.get(url, params=params, headers=self._headers)
+        response.raise_for_status()
+        return response.json()
+
+    async def get_token_balance(
+        self,
+        *,
+        wallet_address: str,
+        token_id: str,
+        human_readable: bool = True,
+    ) -> dict:
+        url = f"{self.api_base_url}/public/balances/token/"
+        params = {
+            "wallet_address": wallet_address,
+            "token_id": token_id,
+            "human_readable": str(human_readable).lower(),
+        }
+        response = await self.client.get(url, params=params, headers=self._headers)
+        response.raise_for_status()
+        return response.json()
+
+    async def get_pool_balance(
+        self,
+        *,
+        pool_address: str,
+        chain_id: int,
+        user_address: str,
+        human_readable: bool = True,
+    ) -> dict:
+        url = f"{self.api_base_url}/public/balances/pool/"
+        params = {
+            "pool_address": pool_address,
+            "chain_id": chain_id,
+            "user_address": user_address,
+            "human_readable": str(human_readable).lower(),
+        }
+        response = await self.client.get(url, params=params, headers=self._headers)
+        response.raise_for_status()
+        return response.json()
+
+
+def _dedupe_ordered(items: list[str]) -> list[str]:
+    seen: set[str] = set()
+    out: list[str] = []
+    for item in items:
+        key = item.lower()
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append(item)
+    return out
+
+
+def _is_evm_address(addr: str) -> bool:
+    a = (addr or "").strip()
+    return a.startswith("0x") and len(a) == 42
+
+
+def _balance_usd(entry: dict[str, Any]) -> float:
+    val = entry.get("balanceUSD", 0)
+    try:
+        return float(val or 0)
+    except (TypeError, ValueError):
+        return 0.0
+
+
+async def balances(
+    action: Literal["token", "pool", "enriched", "activity"],
+    *,
+    wallet_label: str | None = None,
+    wallet_address: str | None = None,
+    human_readable: bool = True,
+    include_solana: bool = False,
+    exclude_spam_tokens: bool = True,
+    limit: int = 20,
+    offset: str | None = None,
+    token_id: str | None = None,
+    token_ids: list[str] | None = None,
+    chain_id: int | None = None,
+    pool_address: str | None = None,
+    pool_addresses: list[str] | None = None,
+) -> dict[str, Any]:
+    waddr = normalize_address(wallet_address)
+    if not waddr:
+        want = (wallet_label or "").strip()
+        if want:
+            w = find_wallet_by_label(want)
+            if not w:
+                return err("not_found", f"Unknown wallet_label: {want}")
+            waddr = normalize_address(w.get("address"))
+
+    if not waddr:
+        return err(
+            "invalid_request", "wallet_label or wallet_address is required for balances"
+        )
+
+    client = _BalanceClient()
+
+    try:
+        if action == "enriched":
+            try:
+                data = await client.get_enriched_wallet_balances(
+                    wallet_address=waddr,
+                    exclude_spam_tokens=bool(exclude_spam_tokens),
+                )
+                if (
+                    not include_solana
+                    and _is_evm_address(waddr)
+                    and isinstance(data, dict)
+                    and isinstance(data.get("balances"), list)
+                ):
+                    balances_list = [b for b in data["balances"] if isinstance(b, dict)]
+                    filtered = [
+                        b
+                        for b in balances_list
+                        if str(b.get("network", "")).lower() != "solana"
+                    ]
+                    if len(filtered) != len(balances_list):
+                        out = dict(data)
+                        out["balances"] = filtered
+                        out["total_balance_usd"] = sum(
+                            _balance_usd(b) for b in filtered
+                        )
+                        breakdown: dict[str, float] = {}
+                        for b in filtered:
+                            net = str(b.get("network") or "").strip()
+                            if not net:
+                                continue
+                            breakdown[net] = breakdown.get(net, 0.0) + _balance_usd(b)
+                        out["chain_breakdown"] = breakdown
+                        out["filtered"] = {
+                            "excluded_networks": ["solana"],
+                            "original_count": len(balances_list),
+                            "filtered_count": len(filtered),
+                        }
+                        data = out
+
+                return ok(data)
+            except Exception as exc:  # noqa: BLE001
+                return err("balance_error", str(exc))
+
+        if action == "activity":
+            try:
+                data = await client.get_wallet_activity(
+                    wallet_address=waddr,
+                    limit=int(limit),
+                    offset=offset,
+                )
+                return ok(
+                    {
+                        "wallet_address": waddr,
+                        "activity": data.get("activity", []),
+                        "next_offset": data.get("next_offset"),
+                    }
+                )
+            except Exception as exc:  # noqa: BLE001
+                return err("activity_error", str(exc))
+
+        if action == "token":
+            raw_ids: list[str] = []
+            if token_id:
+                raw_ids.append(str(token_id).strip())
+            if token_ids:
+                raw_ids.extend(str(x).strip() for x in token_ids)
+
+            ids = _dedupe_ordered([x for x in raw_ids if x])
+            if not ids:
+                return err(
+                    "invalid_request",
+                    "token_id or token_ids is required for balances(action=token)",
+                )
+
+            async def _one(tid: str) -> dict[str, Any]:
+                try:
+                    data = await client.get_token_balance(
+                        token_id=tid,
+                        wallet_address=waddr,
+                        human_readable=bool(human_readable),
+                    )
+                    return {"ok": True, "token_id": tid, "data": data}
+                except Exception as exc:  # noqa: BLE001
+                    return {"ok": False, "token_id": tid, "error": str(exc)}
+
+            results = await asyncio.gather(*[_one(tid) for tid in ids])
+            return ok({"wallet_address": waddr, "balances": results})
+
+        if action == "pool":
+            if chain_id is None:
+                return err(
+                    "invalid_request", "chain_id is required for balances(action=pool)"
+                )
+
+            raw_pools: list[str] = []
+            if pool_address:
+                raw_pools.append(str(pool_address).strip())
+            if pool_addresses:
+                raw_pools.extend(str(x).strip() for x in pool_addresses)
+
+            pools = _dedupe_ordered([x for x in raw_pools if x])
+            if not pools:
+                return err(
+                    "invalid_request",
+                    "pool_address or pool_addresses is required for balances(action=pool)",
+                )
+
+            async def _one_pool(paddr: str) -> dict[str, Any]:
+                try:
+                    data = await client.get_pool_balance(
+                        pool_address=paddr,
+                        chain_id=int(chain_id),  # type: ignore[arg-type]
+                        user_address=waddr,
+                        human_readable=bool(human_readable),
+                    )
+                    return {
+                        "ok": True,
+                        "pool_address": paddr,
+                        "chain_id": int(chain_id),  # type: ignore[arg-type]
+                        "data": data,
+                    }
+                except Exception as exc:  # noqa: BLE001
+                    return {
+                        "ok": False,
+                        "pool_address": paddr,
+                        "chain_id": int(chain_id),  # type: ignore[arg-type]
+                        "error": str(exc),
+                    }
+
+            results = await asyncio.gather(*[_one_pool(p) for p in pools])
+            return ok(
+                {"wallet_address": waddr, "chain_id": int(chain_id), "pools": results}
+            )
+
+        return err("invalid_request", f"Unknown balances action: {action}")
+
+    finally:
+        try:
+            await client.close()
+        except Exception:  # noqa: BLE001
+            pass

wayfinder_paths/mcp/tools/discovery.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from wayfinder_paths.mcp.utils import err, ok, read_text_excerpt, read_yaml, repo_root
+
+
+async def discover(
+    kind: Literal["adapters", "strategies"],
+    detail: Literal["summary", "full"] = "summary",
+) -> dict[str, Any]:
+    root = repo_root()
+    base = (
+        root / "wayfinder_paths" / ("adapters" if kind == "adapters" else "strategies")
+    )
+    if not base.exists():
+        return err("not_found", f"Directory not found: {base}")
+
+    items: list[dict[str, Any]] = []
+    for child in sorted(base.iterdir()):
+        if not child.is_dir():
+            continue
+        manifest_path = child / "manifest.yaml"
+        if not manifest_path.exists():
+            continue
+        manifest = read_yaml(manifest_path)
+        rel_manifest = str(manifest_path.relative_to(root))
+
+        if kind == "adapters":
+            item = {
+                "name": child.name,
+                "entrypoint": manifest.get("entrypoint"),
+                "capabilities": manifest.get("capabilities", []),
+                "dependencies": manifest.get("dependencies", []),
+                "manifest_path": rel_manifest,
+            }
+        else:
+            adapters = manifest.get("adapters", [])
+            item = {
+                "name": child.name,
+                "entrypoint": manifest.get("entrypoint"),
+                "adapters": adapters if isinstance(adapters, list) else [],
+                "permissions_policy_present": bool(
+                    isinstance(manifest.get("permissions"), dict)
+                    and (manifest.get("permissions") or {}).get("policy")
+                ),
+                "manifest_path": rel_manifest,
+            }
+
+        if detail == "full":
+            readme = read_text_excerpt(child / "README.md")
+            if readme:
+                item["readme_excerpt"] = readme
+            item["manifest"] = manifest
+
+        items.append(item)
+
+    return ok({"kind": kind, "items": items})
+
+
+def _default_claude_notes_for_adapter(name: str) -> dict[str, Any] | None:
+    # Keep this deliberately small; the real docs live in .claude/skills.
+    if name == "brap_adapter":
+        return {
+            "reads": [
+                {
+                    "name": "quote_swap (via mcp__wayfinder__quote_swap)",
+                    "summary": "Get best BRAP route + fees; no on-chain effects.",
+                }
+            ],
+            "writes": [
+                {
+                    "name": "swap (via mcp__wayfinder__execute kind=swap)",
+                    "risk": "funds",
+                    "summary": "May submit ERC20 approvals and a swap/bridge tx.",
+                }
+            ],
+            "gotchas": [
+                "USDT-style tokens may require setting allowance to 0 before approve.",
+                "Cross-chain swaps still broadcast a tx on the source chain.",
+            ],
+        }
+    if name == "balance_adapter":
+        return {
+            "reads": [
+                {
+                    "name": "balances (via mcp__wayfinder__balances)",
+                    "summary": "Read token/pool balances via Wayfinder API.",
+                }
+            ],
+            "writes": [
+                {
+                    "name": "send (via mcp__wayfinder__execute kind=send)",
+                    "risk": "funds",
+                    "summary": "Native/ERC20 sends from a local wallet.",
+                }
+            ],
+            "gotchas": ["Prefer DRY_RUN=1 until ready to broadcast."],
+        }
+    if name == "hyperliquid_adapter":
+        return {
+            "reads": [
+                {
+                    "name": "hyperliquid (via mcp__wayfinder__hyperliquid)",
+                    "summary": "User state + market reads (no signing).",
+                }
+            ],
+            "writes": [
+                {
+                    "name": "hyperliquid_execute (via mcp__wayfinder__hyperliquid_execute)",
+                    "risk": "funds",
+                    "summary": "Perp orders/leverage/withdraw with local signing (gated by review prompt).",
+                }
+            ],
+            "gotchas": [
+                "Perp coins are mapped to asset_id (<10000).",
+                "Builder fees are attributed to 0xaA1D89f333857eD78F8434CC4f896A9293EFE65c and use tenths-of-bp units.",
+                "Prefer DRY_RUN=1 until ready to execute.",
+            ],
+        }
+    return None
+
+
+async def describe(
+    kind: Literal["adapter", "strategy"],
+    name: str,
+    include_manifest: bool = True,
+    include_readme_excerpt: bool = True,
+    include_claude_notes: bool = True,
+) -> dict[str, Any]:
+    root = repo_root()
+    base = (
+        root / "wayfinder_paths" / ("adapters" if kind == "adapter" else "strategies")
+    )
+    target = base / name
+    if not target.exists():
+        return err("not_found", f"Unknown {kind}: {name}")
+
+    manifest_path = target / "manifest.yaml"
+    if not manifest_path.exists():
+        return err("not_found", f"Missing manifest.yaml for {kind}: {name}")
+
+    out: dict[str, Any] = {"kind": kind, "name": name}
+    if include_manifest:
+        out["manifest"] = read_yaml(manifest_path)
+        out["manifest_path"] = str(manifest_path.relative_to(root))
+
+    if include_readme_excerpt:
+        readme = read_text_excerpt(target / "README.md")
+        if readme:
+            out["readme_excerpt"] = readme
+
+    if include_claude_notes and kind == "adapter":
+        notes = _default_claude_notes_for_adapter(name)
+        if notes:
+            out["claude_notes"] = notes
+
+    return ok(out)