wayfinder-paths 0.1.1__py3-none-any.whl

wayfinder_paths/core/clients/PoolClient.py

@@ -0,0 +1,96 @@
+"""
+Pool Client
+Provides read-only access to pool metadata and analytics via public endpoints.
+"""
+
+from typing import Any
+
+from wayfinder_paths.core.clients.AuthClient import AuthClient
+from wayfinder_paths.core.clients.WayfinderClient import WayfinderClient
+from wayfinder_paths.core.settings import settings
+
+
+class PoolClient(WayfinderClient):
+    """Client for pool-related read operations"""
+
+    def __init__(self, api_key: str | None = None):
+        super().__init__(api_key=api_key)
+        self.api_base_url = f"{settings.WAYFINDER_API_URL}"
+        self._auth_client: AuthClient | None = AuthClient(api_key=api_key)
+
+    async def get_pools_by_ids(
+        self,
+        *,
+        pool_ids: str,
+        merge_external: bool | None = None,
+    ) -> dict[str, Any]:
+        """
+        Fetch pools by comma-separated pool ids.
+
+        Example:
+        GET /api/v1/public/pools/?pool_ids=a,b&merge_external=false
+        """
+        url = f"{self.api_base_url}/public/pools/"
+        params: dict[str, Any] = {"pool_ids": pool_ids}
+        if merge_external is not None:
+            params["merge_external"] = "true" if merge_external else "false"
+        response = await self._request("GET", url, params=params, headers={})
+        response.raise_for_status()
+        data = response.json()
+        return data.get("data", data)
+
+    async def get_all_pools(
+        self, *, merge_external: bool | None = None
+    ) -> dict[str, Any]:
+        """
+        Fetch all pools.
+
+        Example:
+        GET /api/v1/public/pools/?merge_external=false
+        """
+        url = f"{self.api_base_url}/public/pools/"
+        params: dict[str, Any] = {}
+        if merge_external is not None:
+            params["merge_external"] = "true" if merge_external else "false"
+        response = await self._request("GET", url, params=params, headers={})
+        response.raise_for_status()
+        data = response.json()
+        return data.get("data", data)
+
+    async def get_combined_pool_reports(self) -> dict[str, Any]:
+        """
+        Fetch combined pool reports.
+
+        GET /api/v1/public/pools/combined/
+        """
+        url = f"{self.api_base_url}/public/pools/combined/"
+        response = await self._request("GET", url, headers={})
+        response.raise_for_status()
+        data = response.json()
+        return data.get("data", data)
+
+    async def get_llama_matches(self) -> dict[str, Any]:
+        """
+        Fetch Llama matches for pools.
+
+        GET /api/v1/public/pools/llama/matches/
+        """
+        url = f"{self.api_base_url}/public/pools/llama/matches/"
+        response = await self._request("GET", url, headers={})
+        response.raise_for_status()
+        data = response.json()
+        return data.get("data", data)
+
+    async def get_llama_reports(self, *, identifiers: str) -> dict[str, Any]:
+        """
+        Fetch Llama reports using identifiers (token ids, address_network, or pool ids).
+
+        Example:
+        GET /api/v1/public/pools/llama/reports/?identifiers=pool-1,usd-coin
+        """
+        url = f"{self.api_base_url}/public/pools/llama/reports/"
+        params = {"identifiers": identifiers}
+        response = await self._request("GET", url, params=params, headers={})
+        response.raise_for_status()
+        data = response.json()
+        return data.get("data", data)

wayfinder_paths/core/clients/SimulationClient.py

@@ -0,0 +1,180 @@
+"""
+Simulation Client
+Handles blockchain transaction simulations via Gorlami/Tenderly
+"""
+
+import time
+from typing import Any
+
+from loguru import logger
+
+from wayfinder_paths.core.clients.WayfinderClient import WayfinderClient
+
+
+class SimulationClient(WayfinderClient):
+    """Client for blockchain transaction simulations"""
+
+    def __init__(self, api_key: str | None = None):
+        super().__init__(api_key=api_key)
+
+    async def simulate_send(
+        self,
+        from_address: str,
+        to_address: str,
+        token_address: str,
+        amount: str,
+        chain_id: int,
+        initial_balances: dict[str, str],
+    ) -> dict[str, Any]:
+        """
+        Simulate sending native ETH or ERC20 tokens.
+
+        Args:
+            from_address: Source wallet address
+            to_address: Destination wallet address
+            token_address: Token contract address (use 0x0 for native ETH)
+            amount: Amount to send
+            chain_id: Blockchain chain ID
+            initial_balances: Initial token balances for simulation
+
+        Returns:
+            Simulation result data
+        """
+        logger.info(
+            f"Simulating send: {amount} from {from_address} to {to_address} (chain {chain_id})"
+        )
+        start_time = time.time()
+
+        url = f"{self.api_base_url}public/simulate/send/"
+
+        payload = {
+            "from_address": from_address,
+            "to_address": to_address,
+            "token_address": token_address,
+            "amount": amount,
+            "chain_id": chain_id,
+            "initial_balances": initial_balances,
+        }
+
+        try:
+            response = await self._request("POST", url, json=payload, headers={})
+            response.raise_for_status()
+            data = response.json()
+            elapsed = time.time() - start_time
+            logger.info(f"Simulation request completed successfully in {elapsed:.2f}s")
+            return data.get("data", data)
+        except Exception as e:
+            elapsed = time.time() - start_time
+            logger.error(f"Simulation request failed after {elapsed:.2f}s: {e}")
+            raise
+
+    async def simulate_approve(
+        self,
+        from_address: str,
+        to_address: str,
+        token_address: str,
+        amount: str,
+        chain_id: int,
+        initial_balances: dict[str, str],
+        clear_approval_first: bool = False,
+    ) -> dict[str, Any]:
+        """
+        Simulate ERC20 token approval.
+
+        Args:
+            from_address: Address approving the tokens
+            to_address: Address being approved to spend tokens
+            token_address: ERC20 token contract address
+            amount: Amount to approve
+            chain_id: Blockchain chain ID
+            initial_balances: Initial token balances for simulation
+            clear_approval_first: Whether to clear existing approval before setting new one
+
+        Returns:
+            Simulation result data
+        """
+        logger.info(
+            f"Simulating approval: {amount} from {from_address} to {to_address} (chain {chain_id})"
+        )
+        start_time = time.time()
+
+        url = f"{self.api_base_url}public/simulate/approve/"
+
+        payload = {
+            "from_address": from_address,
+            "to_address": to_address,
+            "token_address": token_address,
+            "amount": amount,
+            "chain_id": chain_id,
+            "initial_balances": initial_balances,
+            "clear_approval_first": clear_approval_first,
+        }
+
+        try:
+            response = await self._request("POST", url, json=payload, headers={})
+            response.raise_for_status()
+            data = response.json()
+            elapsed = time.time() - start_time
+            logger.info(f"Simulation request completed successfully in {elapsed:.2f}s")
+            return data.get("data", data)
+        except Exception as e:
+            elapsed = time.time() - start_time
+            logger.error(f"Simulation request failed after {elapsed:.2f}s: {e}")
+            raise
+
+    async def simulate_swap(
+        self,
+        from_token_address: str,
+        to_token_address: str,
+        from_chain_id: int,
+        to_chain_id: int,
+        amount: str,
+        from_address: str,
+        slippage: float,
+        initial_balances: dict[str, str],
+    ) -> dict[str, Any]:
+        """
+        Simulate token swap operation.
+
+        Args:
+            from_token_address: Source token contract address
+            to_token_address: Destination token contract address
+            from_chain_id: Source chain ID
+            to_chain_id: Destination chain ID
+            amount: Amount to swap
+            from_address: Wallet address initiating swap
+            slippage: Maximum slippage tolerance
+            initial_balances: Initial token balances for simulation
+
+        Returns:
+            Simulation result data
+        """
+        logger.info(
+            f"Simulating swap: {from_token_address} -> {to_token_address} (chain {from_chain_id} -> {to_chain_id})"
+        )
+        start_time = time.time()
+
+        url = f"{self.api_base_url}public/simulate/swap/"
+
+        payload = {
+            "from_token_address": from_token_address,
+            "to_token_address": to_token_address,
+            "from_chain_id": from_chain_id,
+            "to_chain_id": to_chain_id,
+            "amount": amount,
+            "from_address": from_address,
+            "slippage": slippage,
+            "initial_balances": initial_balances,
+        }
+
+        try:
+            response = await self._request("POST", url, json=payload, headers={})
+            response.raise_for_status()
+            data = response.json()
+            elapsed = time.time() - start_time
+            logger.info(f"Simulation request completed successfully in {elapsed:.2f}s")
+            return data.get("data", data)
+        except Exception as e:
+            elapsed = time.time() - start_time
+            logger.error(f"Simulation request failed after {elapsed:.2f}s: {e}")
+            raise

wayfinder_paths/core/clients/TokenClient.py

@@ -0,0 +1,73 @@
+"""
+Token Adapter
+Handles token information, prices, and parsing
+"""
+
+from typing import Any
+
+from wayfinder_paths.core.clients.AuthClient import AuthClient
+from wayfinder_paths.core.clients.WayfinderClient import WayfinderClient
+from wayfinder_paths.core.settings import settings
+
+
+class TokenClient(WayfinderClient):
+    """Adapter for token-related operations"""
+
+    def __init__(self, api_key: str | None = None):
+        super().__init__(api_key=api_key)
+        self.api_base_url = f"{self.api_base_url}/tokens"
+        self._auth_client: AuthClient | None = AuthClient(api_key=api_key)
+
+    # ============== Public (No-Auth) Endpoints ==============
+
+    async def get_token_details(
+        self, token_id: str, force_refresh: bool = False
+    ) -> dict[str, Any]:
+        """
+        Get token data including price from the token-details endpoint
+
+        Args:
+            token_id: Token identifier or address
+
+        Returns:
+            Full token data including price information
+        """
+        url = f"{settings.WAYFINDER_API_URL}/public/tokens/detail/"
+        params = {
+            "query": token_id,
+            "get_chart": "false",
+            "force_refresh": str(force_refresh),
+        }
+        # Public endpoint: do not pass auth headers
+        response = await self._request("GET", url, params=params, headers={})
+        response.raise_for_status()
+        data = response.json()
+        return data.get("data", data)
+
+    async def get_gas_token(self, chain_code: str) -> dict[str, Any]:
+        """
+        Fetch the native gas token for a given chain code via public endpoint.
+        Example: GET /api/v1/public/tokens/gas/?chain_code=base
+        """
+        url = f"{settings.WAYFINDER_API_URL}/public/tokens/gas/"
+        params = {"chain_code": chain_code}
+        # Public endpoint: do not pass auth headers
+        response = await self._request("GET", url, params=params, headers={})
+        response.raise_for_status()
+        data = response.json()
+        return data.get("data", data)
+
+    async def is_native_token(
+        self, token_address: str, chain_id: int
+    ) -> dict[str, Any]:
+        """
+        Determine if a token address corresponds to the native gas token on a chain.
+        Returns the API payload (usually includes an `is_native` boolean).
+        """
+        url = f"{settings.WAYFINDER_API_URL}/public/tokens/is-native/"
+        params = {"token_address": token_address, "chain_id": str(chain_id)}
+        # Public endpoint: do not pass auth headers
+        response = await self._request("GET", url, params=params, headers={})
+        response.raise_for_status()
+        data = response.json()
+        return data.get("data", data)

wayfinder_paths/core/clients/TransactionClient.py

@@ -0,0 +1,47 @@
+"""
+Transaction Client
+Handles transaction building, gas estimation, and monitoring
+"""
+
+from typing import Any
+
+from wayfinder_paths.core.clients.AuthClient import AuthClient
+from wayfinder_paths.core.clients.WayfinderClient import WayfinderClient
+from wayfinder_paths.core.settings import settings
+
+
+class TransactionClient(WayfinderClient):
+    """Client for transaction operations"""
+
+    def __init__(self, api_key: str | None = None):
+        super().__init__(api_key=api_key)
+        self.api_base_url = f"{self.api_base_url}/transactions"
+        self._auth_client: AuthClient | None = AuthClient(api_key=api_key)
+
+    # ============== Protected (Auth Required) Endpoints ==============
+
+    async def build_send(
+        self,
+        from_address: str,
+        to_address: str,
+        token_address: str,
+        amount: float,
+        chain_id: int,
+    ) -> dict[str, Any]:
+        """
+        Build a send transaction payload for EVM tokens/native transfers.
+
+        GET /api/v1/public/transactions/build-send/?from_address=...&to_address=...&token_address=...&amount=...&chain_id=...
+        """
+        url = f"{settings.WAYFINDER_API_URL}/public/transactions/build-send/"
+        params = {
+            "from_address": from_address,
+            "to_address": to_address,
+            "token_address": token_address,
+            "amount": str(amount),
+            "chain_id": str(chain_id),
+        }
+        response = await self._authed_request("GET", url, params=params)
+        response.raise_for_status()
+        data = response.json()
+        return data.get("data", data)

wayfinder_paths/core/clients/WalletClient.py

@@ -0,0 +1,90 @@
+"""
+Wallet Client
+Fetches wallet-related data such as aggregated balances for the authenticated user.
+"""
+
+from typing import Any
+
+from wayfinder_paths.core.clients.AuthClient import AuthClient
+from wayfinder_paths.core.clients.WayfinderClient import WayfinderClient
+from wayfinder_paths.core.settings import settings
+
+
+class WalletClient(WayfinderClient):
+    def __init__(self, api_key: str | None = None):
+        super().__init__(api_key=api_key)
+        self.api_base_url = f"{settings.WAYFINDER_API_URL}"
+        self._auth_client = AuthClient(api_key=api_key)
+
+    async def get_token_balance_for_wallet(
+        self,
+        *,
+        token_id: str,
+        wallet_address: str,
+        human_readable: bool = True,
+    ) -> dict[str, Any]:
+        """
+        Fetch a single token balance for an explicit wallet address.
+
+        Mirrors POST /api/v1/public/balances/token/
+        """
+        url = f"{self.api_base_url}/public/balances/token/"
+        payload = {
+            "token_id": token_id,
+            "wallet_address": wallet_address,
+            "human_readable": human_readable,
+        }
+        response = await self._authed_request("POST", url, json=payload)
+        data = response.json()
+        return data.get("data", data)
+
+    async def get_pool_balance_for_wallet(
+        self,
+        *,
+        pool_address: str,
+        chain_id: int,
+        user_address: str,
+        human_readable: bool = True,
+    ) -> dict[str, Any]:
+        """
+        Fetch a wallet's LP/share balance for a given pool address and chain.
+
+        Mirrors POST /api/v1/public/balances/pool/
+        """
+        url = f"{self.api_base_url}/public/balances/pool/"
+        payload = {
+            "pool_address": pool_address,
+            "chain_id": chain_id,
+            "user_address": user_address,
+            "human_readable": human_readable,
+        }
+        response = await self._authed_request("POST", url, json=payload)
+        data = response.json()
+        return data.get("data", data)
+
+    async def get_all_enriched_token_balances_for_wallet(
+        self,
+        *,
+        wallet_address: str,
+        enrich: bool = True,
+        from_cache: bool = False,
+        add_llama: bool = True,
+    ) -> dict[str, Any]:
+        """
+        Fetch all token balances for a wallet with enrichment via the enriched endpoint.
+
+        Mirrors POST /api/v1/public/balances/enriched/
+        """
+        url = f"{self.api_base_url}/public/balances/enriched/"
+        payload = {
+            "wallet_address": wallet_address,
+            "enrich": enrich,
+            "from_cache": from_cache,
+            "add_llama": add_llama,
+        }
+        try:
+            response = await self._authed_request("POST", url, json=payload)
+            data = response.json()
+            return data.get("data", data)
+        except Exception:
+            raise