wayfinder-paths 0.1.1__py3-none-any.whl

wayfinder_paths/core/clients/BRAPClient.py

@@ -0,0 +1,90 @@
+"""
+BRAP (Bridge/Router/Adapter Protocol) Client
+Provides access to quote operations via the public quote endpoint.
+"""
+
+import time
+from typing import Any
+
+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 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,
+    ) -> dict[str, Any]:
+        """
+        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,231 @@
+"""
+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 vault 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
+
+    @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"""
+        if not self._token_client:
+            self._token_client = self._injected_clients.get("token") or TokenClient(
+                api_key=self._api_key
+            )
+            if self._access_token and hasattr(self._token_client, "set_bearer_token"):
+                self._token_client.set_bearer_token(self._access_token)
+        return self._token_client
+
+    @property
+    def transaction(self) -> TransactionClientProtocol:
+        """Get or create transaction client"""
+        if not self._transaction_client:
+            self._transaction_client = self._injected_clients.get(
+                "transaction"
+            ) or TransactionClient(api_key=self._api_key)
+            if self._access_token and hasattr(
+                self._transaction_client, "set_bearer_token"
+            ):
+                self._transaction_client.set_bearer_token(self._access_token)
+        return self._transaction_client
+
+    @property
+    def ledger(self) -> LedgerClientProtocol:
+        """Get or create ledger client"""
+        if not self._ledger_client:
+            self._ledger_client = self._injected_clients.get("ledger") or LedgerClient(
+                api_key=self._api_key
+            )
+            if self._access_token and hasattr(self._ledger_client, "set_bearer_token"):
+                self._ledger_client.set_bearer_token(self._access_token)
+        return self._ledger_client
+
+    @property
+    def pool(self) -> PoolClientProtocol:
+        """Get or create pool client"""
+        if not self._pool_client:
+            self._pool_client = self._injected_clients.get("pool") or PoolClient(
+                api_key=self._api_key
+            )
+            if self._access_token and hasattr(self._pool_client, "set_bearer_token"):
+                self._pool_client.set_bearer_token(self._access_token)
+        return self._pool_client
+
+    @property
+    def hyperlend(self) -> HyperlendClientProtocol:
+        """Get or create hyperlend client"""
+        if not self._hyperlend_client:
+            self._hyperlend_client = self._injected_clients.get(
+                "hyperlend"
+            ) or HyperlendClient(api_key=self._api_key)
+            if self._access_token and hasattr(
+                self._hyperlend_client, "set_bearer_token"
+            ):
+                self._hyperlend_client.set_bearer_token(self._access_token)
+        return self._hyperlend_client
+
+    @property
+    def wallet(self) -> WalletClientProtocol:
+        """Get or create wallet client"""
+        if not self._wallet_client:
+            self._wallet_client = self._injected_clients.get("wallet") or WalletClient(
+                api_key=self._api_key
+            )
+            if self._access_token and hasattr(self._wallet_client, "set_bearer_token"):
+                self._wallet_client.set_bearer_token(self._access_token)
+        return self._wallet_client
+
+    @property
+    def brap(self) -> BRAPClientProtocol:
+        """Get or create BRAP client"""
+        if not self._brap_client:
+            self._brap_client = self._injected_clients.get("brap") or BRAPClient(
+                api_key=self._api_key
+            )
+            if self._access_token and hasattr(self._brap_client, "set_bearer_token"):
+                self._brap_client.set_bearer_token(self._access_token)
+        return self._brap_client
+
+    @property
+    def simulation(self) -> SimulationClientProtocol:
+        """Get or create simulation client"""
+        if not self._simulation_client:
+            self._simulation_client = self._injected_clients.get(
+                "simulation"
+            ) or SimulationClient(api_key=self._api_key)
+            if self._access_token and hasattr(
+                self._simulation_client, "set_bearer_token"
+            ):
+                self._simulation_client.set_bearer_token(self._access_token)
+        return self._simulation_client
+
+    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,151 @@
+"""
+Hyperlend Client
+Provides access to Hyperlend stable markets data via public endpoints.
+"""
+
+from typing import Any
+
+from wayfinder_paths.core.clients.WayfinderClient import WayfinderClient
+from wayfinder_paths.core.settings import settings
+
+
+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,
+    ) -> dict[str, Any]:
+        """
+        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,
+    ) -> dict[str, Any]:
+        """
+        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,
+    ) -> dict[str, Any]:
+        """
+        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,
+    ) -> dict[str, Any]:
+        """
+        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)

wayfinder_paths/core/clients/LedgerClient.py

@@ -0,0 +1,222 @@
+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 LedgerClient(WayfinderClient):
+    """
+    Client for vault transaction history and bookkeeping operations.
+
+    Supports:
+    - GET vault transactions
+    - GET vault net deposit
+    - GET vault last rotation time
+    - POST add deposit
+    - POST add withdraw
+    - POST add operation
+    - POST add cashflow
+    """
+
+    def __init__(self, api_key: str | None = 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)
+
+    # ===================== Read Endpoints =====================
+
+    async def get_vault_transactions(
+        self,
+        *,
+        wallet_address: str,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> dict[str, Any]:
+        """
+        Fetch a paginated list of transactions for a given vault wallet and address.
+
+        GET /api/v1/public/vaults/transactions/?wallet_address=...&limit=...&offset=...
+        """
+        url = f"{self.api_base_url}/public/vaults/transactions/"
+        params = {
+            "wallet_address": wallet_address,
+            "limit": str(limit),
+            "offset": str(offset),
+        }
+        response = await self._authed_request("GET", url, params=params)
+        data = response.json()
+        return data.get("data", data)
+
+    async def get_vault_net_deposit(self, *, wallet_address: str) -> dict[str, Any]:
+        """
+        Fetch the net deposit (deposits - withdrawals) for a vault and address.
+
+        GET /api/v1/public/vaults/net-deposit/?wallet_address=...
+        """
+        url = f"{self.api_base_url}/public/vaults/net-deposit/"
+        params = {
+            "wallet_address": wallet_address,
+        }
+        response = await self._authed_request("GET", url, params=params)
+        data = response.json()
+        return data.get("data", data)
+
+    async def get_vault_latest_transactions(
+        self, *, wallet_address: str
+    ) -> dict[str, Any]:
+        """
+        Fetch the last rotation time for a vault and address.
+
+        GET /api/v1/public/vaults/last-rotation-time/?wallet_address=...
+        """
+        url = f"{self.api_base_url}/public/vaults/latest-transactions/"
+        params = {
+            "wallet_address": wallet_address,
+        }
+        response = await self._authed_request("GET", url, params=params)
+        data = response.json()
+        return data.get("data", data)
+
+    # ===================== Write Endpoints =====================
+
+    async def add_vault_deposit(
+        self,
+        *,
+        wallet_address: str,
+        chain_id: int,
+        token_address: str,
+        token_amount: str | float,
+        usd_value: str | float,
+        data: dict[str, Any] | None = None,
+        strategy_name: str | None = None,
+    ) -> dict[str, Any]:
+        """
+        Record a deposit for a vault.
+
+        POST /api/v1/public/vaults/deposits/
+        """
+        url = f"{self.api_base_url}/public/vaults/deposits/"
+        payload: dict[str, Any] = {
+            "wallet_address": wallet_address,
+            "chain_id": chain_id,
+            "token_address": token_address,
+            "token_amount": str(token_amount),
+            "usd_value": str(usd_value),
+            "data": data or {},
+        }
+        if strategy_name is not None:
+            payload["strategy_name"] = strategy_name
+        response = await self._authed_request("POST", url, json=payload)
+        data_resp = response.json()
+        return data_resp.get("data", data_resp)
+
+    async def add_vault_withdraw(
+        self,
+        *,
+        wallet_address: str,
+        chain_id: int,
+        token_address: str,
+        token_amount: str | float,
+        usd_value: str | float,
+        data: dict[str, Any] | None = None,
+        strategy_name: str | None = None,
+    ) -> dict[str, Any]:
+        """
+        Record a withdrawal for a vault.
+
+        POST /api/v1/public/vaults/withdrawals/
+        """
+        url = f"{self.api_base_url}/public/vaults/withdrawals/"
+        payload: dict[str, Any] = {
+            "wallet_address": wallet_address,
+            "chain_id": chain_id,
+            "token_address": token_address,
+            "token_amount": str(token_amount),
+            "usd_value": str(usd_value),
+            "data": data or {},
+        }
+        if strategy_name is not None:
+            payload["strategy_name"] = strategy_name
+        response = await self._authed_request("POST", url, json=payload)
+        data_resp = response.json()
+        return data_resp.get("data", data_resp)
+
+    async def add_vault_operation(
+        self,
+        *,
+        wallet_address: str,
+        operation_data: dict[str, Any],
+        usd_value: str | float,
+        strategy_name: str | None = None,
+    ) -> dict[str, Any]:
+        """
+        Record a vault operation (e.g., swaps, rebalances) for bookkeeping.
+
+        POST /api/v1/public/vaults/operations/
+        """
+        url = f"{self.api_base_url}/public/vaults/operations/"
+        payload: dict[str, Any] = {
+            "wallet_address": wallet_address,
+            "operation_data": operation_data,
+            "usd_value": str(usd_value),
+        }
+        if strategy_name is not None:
+            payload["strategy_name"] = strategy_name
+        response = await self._authed_request("POST", url, json=payload)
+        data_resp = response.json()
+        return data_resp.get("data", data_resp)
+
+    async def add_vault_cashflow(
+        self,
+        *,
+        wallet_address: str,
+        block_timestamp: int,
+        token_addr: str,
+        amount: str | int | float,
+        description: str,
+        strategy_name: str | None = None,
+    ) -> dict[str, Any]:
+        """
+        Record a cashflow for a vault (interest, funding, reward, or fee).
+
+        POST /api/v1/public/vaults/cashflows/
+
+        Args:
+            wallet_address: Vault wallet address
+            block_timestamp: Block timestamp (Unix timestamp)
+            token_addr: Token contract address
+            amount: Cashflow amount (in token units)
+            description: Cashflow type - must be one of: "interest", "funding", "reward", "fee", "lend", "unlend", "borrow"
+            strategy_name: Optional strategy name
+
+        Returns:
+            Dict containing the cashflow record or error details
+        """
+        valid_descriptions = [
+            "interest",
+            "funding",
+            "reward",
+            "fee",
+            "lend",
+            "unlend",
+            "borrow",
+        ]
+        if description not in valid_descriptions:
+            raise ValueError(
+                f"Invalid description '{description}'. Must be one of: {valid_descriptions}"
+            )
+
+        url = f"{self.api_base_url}/public/vaults/cashflows/"
+        payload: dict[str, Any] = {
+            "wallet_address": wallet_address,
+            "block_timestamp": block_timestamp,
+            "token_addr": token_addr,
+            "amount": str(amount),
+            "description": description,
+        }
+        if strategy_name is not None:
+            payload["strategy_name"] = strategy_name
+        response = await self._authed_request("POST", url, json=payload)
+        data_resp = response.json()
+        return data_resp.get("data", data_resp)