wayfinder-paths 0.1.7__py3-none-any.whl

wayfinder_paths/core/clients/AuthClient.py

@@ -0,0 +1,83 @@
+import os
+from typing import Any
+
+from loguru import logger
+
+from wayfinder_paths.core.clients.WayfinderClient import WayfinderClient
+from wayfinder_paths.core.settings import settings
+
+
+class AuthClient(WayfinderClient):
+    def __init__(self, api_key: str | None = None):
+        """
+        Initialize AuthClient.
+
+        Args:
+            api_key: Optional API key for service account authentication.
+                    If provided, uses API key auth. Otherwise falls back to config.json.
+        """
+        super().__init__(api_key=api_key)
+
+        self.api_base_url = f"{settings.WAYFINDER_API_URL}"
+        self.logger = logger.bind(client="AuthClient")
+
+    def _is_using_api_key(self) -> bool:
+        """Check if API key authentication is being used."""
+        if self._api_key:
+            return True
+
+        try:
+            creds = self._load_config_credentials()
+            if creds.get("api_key"):
+                return True
+            if os.getenv("WAYFINDER_API_KEY"):
+                return True
+        except Exception:
+            pass
+
+        return False
+
+    async def authenticate(
+        self,
+        username: str | None = None,
+        password: str | None = None,
+        *,
+        refresh_token: str | None = None,
+    ) -> dict[str, Any]:
+        """
+        Obtain an access token via username/password or refresh token.
+
+        Expected endpoints:
+        - POST {api_base_url}/token/ (username, password) -> { access, refresh }
+        - POST {api_base_url}/token/refresh/ (refresh) -> { access }
+        """
+        if refresh_token:
+            self.logger.debug(
+                "AuthClient.authenticate -> POST /token/refresh (refresh provided)"
+            )
+            url = f"{self.api_base_url}/auth/token/refresh/"
+            payload = {"refresh": refresh_token}
+        elif username and password:
+            self.logger.debug(
+                f"AuthClient.authenticate -> POST /token (username provided={bool(username)})"
+            )
+            url = f"{self.api_base_url}/auth/token/"
+            payload = {"username": username, "password": password}
+        else:
+            raise ValueError(
+                "Credentials required: provide username+password or refresh_token"
+            )
+
+        response = await self._request("POST", url, json=payload)
+        response.raise_for_status()
+        data = response.json()
+
+        access = data.get("access") or data.get("access_token")
+        refresh = data.get("refresh") or data.get("refresh_token")
+        if access or refresh:
+            self.set_tokens(access, refresh)
+            self.logger.debug(
+                f"AuthClient.authenticate <- success (access={'yes' if access else 'no'}, refresh={'yes' if refresh else 'no'})"
+            )
+
+        return data

wayfinder_paths/core/clients/BRAPClient.py

@@ -0,0 +1,109 @@
+"""
+BRAP (Bridge/Router/Adapter Protocol) Client
+Provides access to quote operations via the public quote endpoint.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, NotRequired, Required, TypedDict
+
+from loguru import logger
+
+from wayfinder_paths.core.clients.AuthClient import AuthClient
+from wayfinder_paths.core.clients.WayfinderClient import WayfinderClient
+from wayfinder_paths.core.settings import settings
+
+
+class BRAPQuote(TypedDict):
+    """BRAP quote response structure"""
+
+    from_token_address: Required[str]
+    to_token_address: Required[str]
+    from_chain_id: Required[int]
+    to_chain_id: Required[int]
+    from_address: Required[str]
+    to_address: Required[str]
+    amount1: Required[str]
+    amount2: NotRequired[str]
+    routes: NotRequired[list[dict[str, Any]]]
+    fees: NotRequired[dict[str, Any] | None]
+    slippage: NotRequired[float | None]
+    wayfinder_fee: NotRequired[float | None]
+
+
+class BRAPClient(WayfinderClient):
+    """Client for BRAP quote 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_quote(
+        self,
+        *,
+        from_token_address: str,
+        to_token_address: str,
+        from_chain_id: int,
+        to_chain_id: int,
+        from_address: str,
+        to_address: str,
+        amount1: str,
+        slippage: float | None = None,
+        wayfinder_fee: float | None = None,
+    ) -> BRAPQuote:
+        """
+        Get a quote for a bridge/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
+            from_address: Source wallet address
+            to_address: Destination wallet address
+            amount1: Amount to swap (in smallest units)
+            slippage: Maximum slippage tolerance (optional)
+            wayfinder_fee: Wayfinder fee (optional)
+
+        Returns:
+            Quote data including routes, amounts, fees, etc.
+        """
+        logger.info(
+            f"Getting BRAP quote: {from_token_address} -> {to_token_address} (chain {from_chain_id} -> {to_chain_id})"
+        )
+        logger.debug(
+            f"Quote params: amount={amount1}, slippage={slippage}, wayfinder_fee={wayfinder_fee}"
+        )
+        start_time = time.time()
+
+        url = f"{self.api_base_url}/public/quotes/"
+
+        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,
+            "from_address": from_address,
+            "to_address": to_address,
+            "amount1": amount1,
+        }
+
+        # Only add optional parameters if they're provided
+        if slippage is not None:
+            payload["slippage"] = slippage
+        if wayfinder_fee is not None:
+            payload["wayfinder_fee"] = wayfinder_fee
+
+        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"BRAP quote request completed successfully in {elapsed:.2f}s")
+            return data.get("data", data)
+        except Exception as e:
+            elapsed = time.time() - start_time
+            logger.error(f"BRAP quote request failed after {elapsed:.2f}s: {e}")
+            raise

wayfinder_paths/core/clients/ClientManager.py

@@ -0,0 +1,210 @@
+"""
+Client Manager
+Consolidated client management for all API interactions
+"""
+
+from typing import Any
+
+from wayfinder_paths.core.clients.AuthClient import AuthClient
+from wayfinder_paths.core.clients.BRAPClient import BRAPClient
+from wayfinder_paths.core.clients.HyperlendClient import HyperlendClient
+from wayfinder_paths.core.clients.LedgerClient import LedgerClient
+from wayfinder_paths.core.clients.PoolClient import PoolClient
+from wayfinder_paths.core.clients.protocols import (
+    BRAPClientProtocol,
+    HyperlendClientProtocol,
+    LedgerClientProtocol,
+    PoolClientProtocol,
+    SimulationClientProtocol,
+    TokenClientProtocol,
+    TransactionClientProtocol,
+    WalletClientProtocol,
+)
+from wayfinder_paths.core.clients.SimulationClient import SimulationClient
+from wayfinder_paths.core.clients.TokenClient import TokenClient
+from wayfinder_paths.core.clients.TransactionClient import TransactionClient
+from wayfinder_paths.core.clients.WalletClient import WalletClient
+
+
+class ClientManager:
+    """
+    Manages all API client instances for a strategy job.
+
+    Args:
+        clients: Optional dict of pre-instantiated clients to inject directly.
+            Keys: 'token', 'hyperlend', 'ledger', 'wallet', 'transaction', 'pool', 'brap', 'simulation'.
+            If not provided, defaults to HTTP-based clients.
+        skip_auth: If True, skips authentication (for SDK usage).
+    """
+
+    def __init__(
+        self,
+        clients: dict[str, Any] | None = None,
+        skip_auth: bool = False,
+        api_key: str | None = None,
+    ):
+        """
+        Initialize ClientManager.
+
+        Args:
+            clients: Optional dict of pre-instantiated clients to inject directly.
+            skip_auth: If True, skips authentication (for SDK usage).
+            api_key: Optional API key for service account authentication.
+        """
+        self._injected_clients = clients or {}
+        self._skip_auth = skip_auth
+        self._api_key = api_key
+        self._access_token: str | None = None
+
+        self._auth_client: AuthClient | None = None
+        self._token_client: TokenClientProtocol | None = None
+        self._wallet_client: WalletClientProtocol | None = None
+        self._transaction_client: TransactionClientProtocol | None = None
+        self._ledger_client: LedgerClientProtocol | None = None
+        self._pool_client: PoolClientProtocol | None = None
+        self._hyperlend_client: HyperlendClientProtocol | None = None
+        self._brap_client: BRAPClientProtocol | None = None
+        self._simulation_client: SimulationClientProtocol | None = None
+
+    def _get_or_create_client(
+        self,
+        client_attr: str,
+        injected_key: str,
+        client_class: type[Any],
+    ) -> Any:
+        """
+        Helper method to get or create a client instance.
+
+        Args:
+            client_attr: Name of the private attribute storing the client (e.g., "_token_client").
+            injected_key: Key to look up in _injected_clients dict.
+            client_class: Client class to instantiate if not injected.
+
+        Returns:
+            Client instance.
+        """
+        client = getattr(self, client_attr)
+        if not client:
+            client = self._injected_clients.get(injected_key) or client_class(
+                api_key=self._api_key
+            )
+            setattr(self, client_attr, client)
+            if self._access_token and hasattr(client, "set_bearer_token"):
+                client.set_bearer_token(self._access_token)
+        return client
+
+    @property
+    def auth(self) -> AuthClient | None:
+        """Get or create auth client. Returns None if skip_auth=True."""
+        if self._skip_auth:
+            return None
+        if not self._auth_client:
+            self._auth_client = AuthClient(api_key=self._api_key)
+            if self._access_token:
+                self._auth_client.set_bearer_token(self._access_token)
+        return self._auth_client
+
+    @property
+    def token(self) -> TokenClientProtocol:
+        """Get or create token client"""
+        return self._get_or_create_client("_token_client", "token", TokenClient)
+
+    @property
+    def transaction(self) -> TransactionClientProtocol:
+        """Get or create transaction client"""
+        return self._get_or_create_client(
+            "_transaction_client", "transaction", TransactionClient
+        )
+
+    @property
+    def ledger(self) -> LedgerClientProtocol:
+        """Get or create ledger client"""
+        return self._get_or_create_client("_ledger_client", "ledger", LedgerClient)
+
+    @property
+    def pool(self) -> PoolClientProtocol:
+        """Get or create pool client"""
+        return self._get_or_create_client("_pool_client", "pool", PoolClient)
+
+    @property
+    def hyperlend(self) -> HyperlendClientProtocol:
+        """Get or create hyperlend client"""
+        return self._get_or_create_client(
+            "_hyperlend_client", "hyperlend", HyperlendClient
+        )
+
+    @property
+    def wallet(self) -> WalletClientProtocol:
+        """Get or create wallet client"""
+        return self._get_or_create_client("_wallet_client", "wallet", WalletClient)
+
+    @property
+    def brap(self) -> BRAPClientProtocol:
+        """Get or create BRAP client"""
+        return self._get_or_create_client("_brap_client", "brap", BRAPClient)
+
+    @property
+    def simulation(self) -> SimulationClientProtocol:
+        """Get or create simulation client"""
+        return self._get_or_create_client(
+            "_simulation_client", "simulation", SimulationClient
+        )
+
+    async def authenticate(
+        self,
+        username: str | None = None,
+        password: str | None = None,
+        *,
+        refresh_token: str | None = None,
+    ) -> dict[str, Any]:
+        """Authenticate with the API. Raises ValueError if skip_auth=True."""
+        if self._skip_auth:
+            raise ValueError(
+                "Authentication is disabled in SDK mode. SDK users handle their own authentication."
+            )
+        auth_client = self.auth
+        if auth_client is None:
+            raise ValueError("Auth client is not available")
+        data = await auth_client.authenticate(
+            username, password, refresh_token=refresh_token
+        )
+        access = data.get("access") or data.get("access_token")
+        if access:
+            self.set_access_token(access)
+        return data
+
+    def set_access_token(self, access_token: str) -> None:
+        """Set and propagate access token to all initialized clients."""
+        self._access_token = access_token
+        if self._auth_client:
+            self._auth_client.set_bearer_token(access_token)
+        if self._token_client and hasattr(self._token_client, "set_bearer_token"):
+            self._token_client.set_bearer_token(access_token)
+        if self._transaction_client and hasattr(
+            self._transaction_client, "set_bearer_token"
+        ):
+            self._transaction_client.set_bearer_token(access_token)
+        if self._ledger_client and hasattr(self._ledger_client, "set_bearer_token"):
+            self._ledger_client.set_bearer_token(access_token)
+        if self._pool_client and hasattr(self._pool_client, "set_bearer_token"):
+            self._pool_client.set_bearer_token(access_token)
+        if self._hyperlend_client and hasattr(
+            self._hyperlend_client, "set_bearer_token"
+        ):
+            self._hyperlend_client.set_bearer_token(access_token)
+        if self._wallet_client and hasattr(self._wallet_client, "set_bearer_token"):
+            self._wallet_client.set_bearer_token(access_token)
+
+    def get_all_clients(self) -> dict[str, Any]:
+        """Get all initialized clients for direct access"""
+        return {
+            "auth": self._auth_client,
+            "token": self._token_client,
+            "transaction": self._transaction_client,
+            "ledger": self._ledger_client,
+            "pool": self._pool_client,
+            "wallet": self._wallet_client,
+            "hyperlend": self._hyperlend_client,
+            "brap": self._brap_client,
+            "simulation": self._simulation_client,
+        }

wayfinder_paths/core/clients/HyperlendClient.py

@@ -0,0 +1,192 @@
+"""
+Hyperlend Client
+Provides access to Hyperlend stable markets data via public endpoints.
+"""
+
+from __future__ import annotations
+
+from typing import Any, NotRequired, Required, TypedDict
+
+from wayfinder_paths.core.clients.WayfinderClient import WayfinderClient
+from wayfinder_paths.core.settings import settings
+
+
+class StableMarket(TypedDict):
+    """Stable market data structure"""
+
+    chain_id: Required[int]
+    token_address: Required[str]
+    symbol: Required[str]
+    name: Required[str]
+    underlying_tokens: Required[float]
+    buffer_bps: Required[int]
+    min_buffer_tokens: Required[float]
+    is_stable_symbol: Required[bool]
+
+
+class AssetsView(TypedDict):
+    """Assets view response structure"""
+
+    chain_id: Required[int]
+    user_address: Required[str]
+    assets: Required[list[dict[str, Any]]]
+    total_value: NotRequired[float | None]
+
+
+class MarketEntry(TypedDict):
+    """Market entry data structure"""
+
+    chain_id: Required[int]
+    token_address: Required[str]
+    market_data: Required[dict[str, Any]]
+
+
+class LendRateHistory(TypedDict):
+    """Lend rate history response structure"""
+
+    chain_id: Required[int]
+    token_address: Required[str]
+    lookback_hours: Required[int]
+    rates: Required[list[dict[str, Any]]]
+
+
+class HyperlendClient(WayfinderClient):
+    """Client for Hyperlend-related operations"""
+
+    def __init__(self, api_key: str | None = None):
+        super().__init__(api_key=api_key)
+        self.api_base_url = f"{settings.WAYFINDER_API_URL}"
+
+    async def get_stable_markets(
+        self,
+        *,
+        chain_id: int,
+        required_underlying_tokens: float | None = None,
+        buffer_bps: int | None = None,
+        min_buffer_tokens: float | None = None,
+        is_stable_symbol: bool | None = None,
+    ) -> list[StableMarket]:
+        """
+        Fetch stable markets from Hyperlend.
+
+        Args:
+            chain_id: Chain ID to query markets for
+            required_underlying_tokens: Required underlying tokens amount
+            buffer_bps: Buffer in basis points
+            min_buffer_tokens: Minimum buffer in tokens
+            is_stable_symbol: Filter by stable symbol (optional)
+
+        Example:
+            GET /api/v1/public/hyperlend/stable-markets/?chain_id=999&required_underlying_tokens=1000.0&buffer_bps=100&min_buffer_tokens=100.0&is_stable_symbol=true
+
+        Returns:
+            Dictionary containing stable markets data
+        """
+        url = f"{self.api_base_url}/public/hyperlend/stable-markets/"
+        params: dict[str, Any] = {"chain_id": chain_id}
+        if required_underlying_tokens is not None:
+            params["required_underlying_tokens"] = required_underlying_tokens
+        if buffer_bps is not None:
+            params["buffer_bps"] = buffer_bps
+        if min_buffer_tokens is not None:
+            params["min_buffer_tokens"] = min_buffer_tokens
+        if is_stable_symbol is not None:
+            params["is_stable_symbol"] = "true" if is_stable_symbol else "false"
+
+        response = await self._authed_request("GET", url, params=params, headers={})
+        response.raise_for_status()
+        data = response.json()
+        return data.get("data", data)
+
+    async def get_assets_view(
+        self,
+        *,
+        chain_id: int,
+        user_address: str,
+    ) -> AssetsView:
+        """
+        Fetch assets view for a user address from Hyperlend.
+
+        Args:
+            chain_id: Chain ID to query assets for
+            user_address: User wallet address to query assets for
+
+        Example:
+            GET /api/v1/public/hyperlend/assets-view/?chain_id=999&user_address=0x0c737cB5934afCb5B01965141F865F795B324080
+
+        Returns:
+            Dictionary containing assets view data
+        """
+        url = f"{self.api_base_url}/public/hyperlend/assets-view/"
+        params: dict[str, Any] = {
+            "chain_id": chain_id,
+            "user_address": user_address,
+        }
+
+        response = await self._authed_request("GET", url, params=params, headers={})
+        response.raise_for_status()
+        data = response.json()
+        return data.get("data", data)
+
+    async def get_market_entry(
+        self,
+        *,
+        chain_id: int,
+        token_address: str,
+    ) -> MarketEntry:
+        """
+        Fetch market entry from Hyperlend.
+
+        Args:
+            chain_id: Chain ID to query market for
+            token_address: Token address to query market for
+
+        Example:
+            GET /api/v1/public/hyperlend/market-entry/?chain_id=999&token_address=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
+
+        Returns:
+            Dictionary containing market entry data
+        """
+        url = f"{self.api_base_url}/public/hyperlend/market-entry/"
+        params: dict[str, Any] = {
+            "chain_id": chain_id,
+            "token_address": token_address,
+        }
+
+        response = await self._authed_request("GET", url, params=params, headers={})
+        response.raise_for_status()
+        data = response.json()
+        return data.get("data", data)
+
+    async def get_lend_rate_history(
+        self,
+        *,
+        chain_id: int,
+        token_address: str,
+        lookback_hours: int,
+    ) -> LendRateHistory:
+        """
+        Fetch lend rate history from Hyperlend.
+
+        Args:
+            chain_id: Chain ID to query rate history for
+            token_address: Token address to query rate history for
+            lookback_hours: Number of hours to look back for rate history
+
+        Example:
+            GET /api/v1/public/hyperlend/lend-rate-history/?chain_id=999&token_address=0x5555555555555555555555555555555555555555&lookback_hours=24
+
+        Returns:
+            Dictionary containing lend rate history data
+        """
+        url = f"{self.api_base_url}/public/hyperlend/lend-rate-history/"
+        params: dict[str, Any] = {
+            "chain_id": chain_id,
+            "token_address": token_address,
+            "lookback_hours": lookback_hours,
+        }
+
+        response = await self._authed_request("GET", url, params=params, headers={})
+        response.raise_for_status()
+        data = response.json()
+        return data.get("data", data)