wayfinder-paths 0.1.19__py3-none-any.whl → 0.1.21__py3-none-any.whl

wayfinder_paths/adapters/hyperliquid_adapter/adapter.py

@@ -1,5 +1,3 @@
-"""HyperliquidAdapter - wraps hyperliquid SDK for market data and order execution."""
-
 from __future__ import annotations
 
 import asyncio
@@ -31,8 +29,6 @@ except ImportError:
 
 
 class SimpleCache:
-    """Simple in-memory cache with TTL for local caching."""
-
     def __init__(self):
         self._cache: dict[str, Any] = {}
         self._expiry: dict[str, float] = {}
@@ -56,18 +52,6 @@ class SimpleCache:
 
 
 class HyperliquidAdapter(BaseAdapter):
-    """
-    Adapter for Hyperliquid exchange operations.
-
-    Wraps the hyperliquid SDK directly for market data access.
-    Uses Hyperliquid's public API for:
-    - Market metadata (perp and spot)
-    - Funding rate history
-    - Price candles
-    - Order book snapshots
-    - User positions and balances
-    """
-
     adapter_type = "HYPERLIQUID"
 
     def __init__(
@@ -87,7 +71,6 @@ class HyperliquidAdapter(BaseAdapter):
         self._cache = SimpleCache()
         self._executor = executor
 
-        # Initialize Hyperliquid Info client
         self.info = Info(constants.MAINNET_API_URL, skip_ws=True)
 
         # Cache asset mappings after first fetch
@@ -95,7 +78,6 @@ class HyperliquidAdapter(BaseAdapter):
         self._coin_to_asset: dict[str, int] | None = None
 
     async def connect(self) -> bool:
-        """Verify connection by fetching market metadata."""
         try:
             meta = self.info.meta_and_asset_ctxs()
             if meta:
@@ -111,11 +93,6 @@ class HyperliquidAdapter(BaseAdapter):
     # ------------------------------------------------------------------ #
 
     async def get_meta_and_asset_ctxs(self) -> tuple[bool, Any]:
-        """
-        Get perpetual market metadata and asset contexts.
-
-        Returns combined [meta, assetCtxs] from Hyperliquid API.
-        """
         cache_key = "hl_meta_and_asset_ctxs"
         cached = self._cache.get(cache_key)
         if cached:
@@ -123,25 +100,19 @@ class HyperliquidAdapter(BaseAdapter):
 
         try:
             data = self.info.meta_and_asset_ctxs()
-            self._cache.set(cache_key, data, timeout=60)  # Cache for 1 minute
+            self._cache.set(cache_key, data, timeout=60)
             return True, data
         except Exception as exc:
             self.logger.error(f"Failed to fetch meta_and_asset_ctxs: {exc}")
             return False, str(exc)
 
     async def get_spot_meta(self) -> tuple[bool, Any]:
-        """
-        Get spot market metadata.
-
-        Returns spot market information including tokens and pairs.
-        """
         cache_key = "hl_spot_meta"
         cached = self._cache.get(cache_key)
         if cached:
             return True, cached
 
         try:
-            # Handle both callable and property access patterns
             spot_meta = self.info.spot_meta
             if callable(spot_meta):
                 data = spot_meta()
@@ -154,13 +125,6 @@ class HyperliquidAdapter(BaseAdapter):
             return False, str(exc)
 
     async def get_spot_assets(self) -> tuple[bool, dict[str, int]]:
-        """
-        Get mapping of spot pair names to asset IDs.
-
-        Returns:
-            Dict mapping "BASE/QUOTE" names to spot asset IDs (index + 10000).
-            Example: {"PURR/USDC": 10000, "HYPE/USDC": 10107, ...}
-        """
         cache_key = "hl_spot_assets"
         cached = self._cache.get(cache_key)
         if cached:
@@ -182,7 +146,6 @@ class HyperliquidAdapter(BaseAdapter):
 
                 base_idx, quote_idx = pair_tokens[0], pair_tokens[1]
 
-                # Get token names
                 base_info = tokens[base_idx] if base_idx < len(tokens) else {}
                 quote_info = tokens[quote_idx] if quote_idx < len(tokens) else {}
 
@@ -193,7 +156,7 @@ class HyperliquidAdapter(BaseAdapter):
                 spot_asset_id = pair.get("index", 0) + 10000
                 response[name] = spot_asset_id
 
-            self._cache.set(cache_key, response, timeout=300)  # Cache for 5 min
+            self._cache.set(cache_key, response, timeout=300)
             return True, response
 
         except Exception as exc:
@@ -201,16 +164,6 @@ class HyperliquidAdapter(BaseAdapter):
             return False, {}
 
     def get_spot_asset_id(self, base_coin: str, quote_coin: str = "USDC") -> int | None:
-        """
-        Synchronous helper to get spot asset ID from cached data.
-
-        Args:
-            base_coin: Base token name (e.g., "HYPE", "ETH", "BTC")
-            quote_coin: Quote token name (default: "USDC")
-
-        Returns:
-            Spot asset ID or None if not found.
-        """
         cache_key = "hl_spot_assets"
         cached = self._cache.get(cache_key)
         if cached:
@@ -224,17 +177,6 @@ class HyperliquidAdapter(BaseAdapter):
         start_time_ms: int,
         end_time_ms: int | None = None,
     ) -> tuple[bool, list[dict[str, Any]]]:
-        """
-        Get funding rate history for a perpetual.
-
-        Args:
-            coin: Coin symbol (e.g., "ETH", "BTC")
-            start_time_ms: Start time in milliseconds
-            end_time_ms: End time in milliseconds (optional)
-
-        Returns:
-            List of funding rate records with time and fundingRate fields.
-        """
         try:
             data = self.info.funding_history(coin, start_time_ms, end_time_ms)
             return True, data
@@ -249,18 +191,6 @@ class HyperliquidAdapter(BaseAdapter):
         start_time_ms: int,
         end_time_ms: int | None = None,
     ) -> tuple[bool, list[dict[str, Any]]]:
-        """
-        Get OHLCV candle data.
-
-        Args:
-            coin: Coin symbol (e.g., "ETH", "BTC")
-            interval: Candle interval (e.g., "1h", "4h", "1d")
-            start_time_ms: Start time in milliseconds
-            end_time_ms: End time in milliseconds (optional)
-
-        Returns:
-            List of candle records with t, o, h, l, c, v fields.
-        """
         try:
             data = self.info.candles_snapshot(
                 coin, interval, start_time_ms, end_time_ms
@@ -275,16 +205,6 @@ class HyperliquidAdapter(BaseAdapter):
         coin: str,
         n_levels: int = 20,
     ) -> tuple[bool, dict[str, Any]]:
-        """
-        Get L2 order book snapshot.
-
-        Args:
-            coin: Coin symbol (e.g., "ETH", "BTC", or spot pair like "HYPE/USDC")
-            n_levels: Number of price levels to fetch
-
-        Returns:
-            Order book with levels containing px, sz, n fields.
-        """
         try:
             data = self.info.l2_snapshot(coin)
             return True, data
@@ -293,15 +213,6 @@ class HyperliquidAdapter(BaseAdapter):
             return False, str(exc)
 
     async def get_user_state(self, address: str) -> tuple[bool, dict[str, Any]]:
-        """
-        Get user's perpetual account state including positions and margin.
-
-        Args:
-            address: Wallet address
-
-        Returns:
-            User state with assetPositions, crossMarginSummary, etc.
-        """
         try:
             data = self.info.user_state(address)
             return True, data
@@ -310,15 +221,6 @@ class HyperliquidAdapter(BaseAdapter):
             return False, str(exc)
 
     async def get_spot_user_state(self, address: str) -> tuple[bool, dict[str, Any]]:
-        """
-        Get user's spot account balances.
-
-        Args:
-            address: Wallet address
-
-        Returns:
-            Spot balances for the user.
-        """
         try:
             data = self.info.spot_user_state(address)
             return True, data
@@ -327,15 +229,6 @@ class HyperliquidAdapter(BaseAdapter):
             return False, str(exc)
 
     async def get_margin_table(self, margin_table_id: int) -> tuple[bool, list[dict]]:
-        """
-        Get tiered margin table for an asset.
-
-        Args:
-            margin_table_id: Margin table ID from asset context
-
-        Returns:
-            List of margin tiers with notional and maintenance rate.
-        """
         cache_key = f"hl_margin_table_{margin_table_id}"
         cached = self._cache.get(cache_key)
         if cached:
@@ -350,22 +243,13 @@ class HyperliquidAdapter(BaseAdapter):
             except Exception:  # noqa: BLE001 - try alternate payload key
                 body = {"type": "marginTable", "marginTableId": int(margin_table_id)}
                 data = self.info.post("/info", body)
-            self._cache.set(cache_key, data, timeout=86400)  # Cache for 24h
+            self._cache.set(cache_key, data, timeout=86400)
             return True, data
         except Exception as exc:
             self.logger.error(f"Failed to fetch margin_table {margin_table_id}: {exc}")
             return False, str(exc)
 
     async def get_spot_l2_book(self, spot_asset_id: int) -> tuple[bool, dict[str, Any]]:
-        """
-        Get L2 order book for a spot market by asset ID.
-
-        Args:
-            spot_asset_id: Spot asset ID (>= 10000)
-
-        Returns:
-            Order book with levels.
-        """
         try:
             # Spot L2 uses different coin names based on spot index:
             # - Index 0 (PURR): use "PURR/USDC"
@@ -394,20 +278,17 @@ class HyperliquidAdapter(BaseAdapter):
 
     @property
     def asset_to_sz_decimals(self) -> dict[int, int]:
-        """Get asset ID to size decimals mapping."""
         if self._asset_to_sz_decimals is None:
             self._asset_to_sz_decimals = dict(self.info.asset_to_sz_decimals)
         return self._asset_to_sz_decimals
 
     @property
     def coin_to_asset(self) -> dict[str, int]:
-        """Get coin name to asset ID mapping (perps only)."""
         if self._coin_to_asset is None:
             self._coin_to_asset = dict(self.info.coin_to_asset)
         return self._coin_to_asset
 
     def get_sz_decimals(self, asset_id: int) -> int:
-        """Get size decimals for an asset."""
         try:
             return self.asset_to_sz_decimals[asset_id]
         except KeyError:
@@ -416,7 +297,6 @@ class HyperliquidAdapter(BaseAdapter):
             ) from None
 
     def refresh_mappings(self) -> None:
-        """Force refresh of cached asset mappings."""
         self._asset_to_sz_decimals = None
         self._coin_to_asset = None
         self._cache.clear()
@@ -426,7 +306,6 @@ class HyperliquidAdapter(BaseAdapter):
     # ------------------------------------------------------------------ #
 
     async def get_all_mid_prices(self) -> tuple[bool, dict[str, float]]:
-        """Get mid prices for all markets."""
         try:
             data = self.info.all_mids()
             return True, {k: float(v) for k, v in data.items()}
@@ -435,7 +314,6 @@ class HyperliquidAdapter(BaseAdapter):
             return False, str(exc)
 
     def get_valid_order_size(self, asset_id: int, size: float) -> float:
-        """Round size to valid lot size for asset."""
         decimals = self.get_sz_decimals(asset_id)
         from decimal import ROUND_DOWN, Decimal
 
@@ -463,22 +341,6 @@ class HyperliquidAdapter(BaseAdapter):
         cloid: str | None = None,
         builder: dict[str, Any] | None = None,
     ) -> tuple[bool, dict[str, Any]]:
-        """
-        Place a market order (IOC with slippage).
-
-        Args:
-            asset_id: Asset ID (perp < 10000, spot >= 10000)
-            is_buy: True for buy, False for sell
-            slippage: Slippage tolerance (0.0 to 1.0)
-            size: Order size in base units
-            address: Wallet address
-            reduce_only: If True, only reduce existing position
-            cloid: Client order ID (optional)
-            builder: Optional builder fee config with keys 'b' (address) and 'f' (fee bps)
-
-        Returns:
-            (success, response_data or error_message)
-        """
         if not self._executor:
             raise NotImplementedError(
                 "No Hyperliquid executor configured. "
@@ -505,17 +367,6 @@ class HyperliquidAdapter(BaseAdapter):
         order_id: int | str,
         address: str,
     ) -> tuple[bool, dict[str, Any]]:
-        """
-        Cancel an open order.
-
-        Args:
-            asset_id: Asset ID
-            order_id: Order ID to cancel
-            address: Wallet address
-
-        Returns:
-            (success, response_data or error_message)
-        """
         if not self._executor:
             raise NotImplementedError(
                 "No Hyperliquid executor configured. "
@@ -538,18 +389,6 @@ class HyperliquidAdapter(BaseAdapter):
         is_cross: bool,
         address: str,
     ) -> tuple[bool, dict[str, Any]]:
-        """
-        Update leverage for an asset.
-
-        Args:
-            asset_id: Asset ID
-            leverage: Target leverage
-            is_cross: True for cross margin, False for isolated
-            address: Wallet address
-
-        Returns:
-            (success, response_data or error_message)
-        """
         if not self._executor:
             raise NotImplementedError("No Hyperliquid executor configured.")
 
@@ -568,7 +407,6 @@ class HyperliquidAdapter(BaseAdapter):
         amount: float,
         address: str,
     ) -> tuple[bool, dict[str, Any]]:
-        """Transfer USDC from spot to perp balance."""
         if not self._executor:
             raise NotImplementedError("No Hyperliquid executor configured.")
 
@@ -585,7 +423,6 @@ class HyperliquidAdapter(BaseAdapter):
         amount: float,
         address: str,
     ) -> tuple[bool, dict[str, Any]]:
-        """Transfer USDC from perp to spot balance."""
         if not self._executor:
             raise NotImplementedError("No Hyperliquid executor configured.")
 
@@ -605,19 +442,6 @@ class HyperliquidAdapter(BaseAdapter):
         size: float,
         address: str,
     ) -> tuple[bool, dict[str, Any]]:
-        """
-        Place a stop-loss order.
-
-        Args:
-            asset_id: Asset ID
-            is_buy: True to buy (close short), False to sell (close long)
-            trigger_price: Price at which to trigger
-            size: Order size
-            address: Wallet address
-
-        Returns:
-            (success, response_data or error_message)
-        """
         if not self._executor:
             raise NotImplementedError("No Hyperliquid executor configured.")
 
@@ -633,15 +457,6 @@ class HyperliquidAdapter(BaseAdapter):
         return success, result
 
     async def get_user_fills(self, address: str) -> tuple[bool, list[dict[str, Any]]]:
-        """
-        Get recent fills for a user.
-
-        Args:
-            address: Wallet address
-
-        Returns:
-            List of fill records
-        """
         try:
             data = self.info.user_fills(address)
             return True, data if isinstance(data, list) else []
@@ -652,16 +467,6 @@ class HyperliquidAdapter(BaseAdapter):
     async def get_order_status(
         self, address: str, order_id: int | str
     ) -> tuple[bool, dict[str, Any]]:
-        """
-        Get status of a specific order.
-
-        Args:
-            address: Wallet address
-            order_id: Order ID (numeric) or client order ID (string)
-
-        Returns:
-            Order status data
-        """
         try:
             body = {"type": "orderStatus", "user": address, "oid": order_id}
             data = self.info.post("/info", body)
@@ -671,15 +476,6 @@ class HyperliquidAdapter(BaseAdapter):
             return False, str(exc)
 
     async def get_open_orders(self, address: str) -> tuple[bool, list[dict[str, Any]]]:
-        """
-        Get open orders for a user.
-
-        Args:
-            address: Wallet address
-
-        Returns:
-            List of open order records
-        """
         try:
             data = self.info.open_orders(address)
             return True, data if isinstance(data, list) else []
@@ -690,18 +486,6 @@ class HyperliquidAdapter(BaseAdapter):
     async def get_frontend_open_orders(
         self, address: str
     ) -> tuple[bool, list[dict[str, Any]]]:
-        """
-        Get all open orders including trigger orders (stop-loss, take-profit).
-
-        Uses frontendOpenOrders endpoint which returns both limit and trigger orders
-        with full order details including orderType and triggerPx.
-
-        Args:
-            address: Wallet address
-
-        Returns:
-            List of open order records including trigger orders
-        """
         try:
             data = self.info.frontend_open_orders(address)
             return True, data if isinstance(data, list) else []
@@ -717,11 +501,6 @@ class HyperliquidAdapter(BaseAdapter):
         amount: float,
         address: str,
     ) -> tuple[bool, dict[str, Any]]:
-        """
-        Withdraw USDC from Hyperliquid to Arbitrum.
-
-        Note: This is an L1 withdrawal handled by the Hyperliquid executor (signing required).
-        """
         if not self._executor:
             raise NotImplementedError("No Hyperliquid executor configured.")
 
@@ -737,7 +516,6 @@ class HyperliquidAdapter(BaseAdapter):
     # ------------------------------------------------------------------ #
 
     async def health_check(self) -> dict[str, Any]:
-        """Check adapter health by verifying API connectivity."""
         try:
             success, meta = await self.get_meta_and_asset_ctxs()
             if success and meta:
@@ -754,15 +532,6 @@ class HyperliquidAdapter(BaseAdapter):
     # ------------------------------------------------------------------ #
 
     def get_perp_margin_amount(self, user_state: dict[str, Any]) -> float:
-        """
-        Extract perp margin amount from user state.
-
-        Args:
-            user_state: User state from get_user_state()
-
-        Returns:
-            Perp margin balance in USD
-        """
         try:
             margin_summary = user_state.get("marginSummary", {})
             account_value = margin_summary.get("accountValue")
@@ -779,17 +548,6 @@ class HyperliquidAdapter(BaseAdapter):
         user: str,
         builder: str,
     ) -> tuple[bool, int]:
-        """
-        Get the current max builder fee approval for a user/builder pair.
-
-        Args:
-            user: User wallet address
-            builder: Builder wallet address
-
-        Returns:
-            (success, fee_in_tenths_bp) - The approved fee in tenths of basis points.
-            Returns 0 if no approval exists.
-        """
         try:
             body = {"type": "maxBuilderFee", "user": user, "builder": builder}
             data = self.info.post("/info", body)
@@ -805,17 +563,6 @@ class HyperliquidAdapter(BaseAdapter):
         max_fee_rate: str,
         address: str,
     ) -> tuple[bool, dict[str, Any]]:
-        """
-        Approve a builder fee for a user.
-
-        Args:
-            builder: Builder wallet address
-            max_fee_rate: Fee rate as percentage string (e.g., "0.030%" for 30 tenths bp)
-            address: User wallet address
-
-        Returns:
-            (success, response_data or error_message)
-        """
         if not self._executor:
             raise NotImplementedError("No Hyperliquid executor configured.")
 
@@ -839,23 +586,6 @@ class HyperliquidAdapter(BaseAdapter):
         reduce_only: bool = False,
         builder: dict[str, Any] | None = None,
     ) -> tuple[bool, dict[str, Any]]:
-        """
-        Place a limit order (GTC - Good Till Cancelled).
-
-        Used for spot stop-loss orders in basis trading.
-
-        Args:
-            asset_id: Asset ID (perp < 10000, spot >= 10000)
-            is_buy: True for buy, False for sell
-            price: Limit price
-            size: Order size
-            address: Wallet address
-            reduce_only: If True, only reduces existing position
-            builder: Optional builder fee config
-
-        Returns:
-            (success, response_data or error_message)
-        """
         if not self._executor:
             raise NotImplementedError("No Hyperliquid executor configured.")
 
@@ -880,21 +610,8 @@ class HyperliquidAdapter(BaseAdapter):
         timeout_s: int = 120,
         poll_interval_s: int = 5,
     ) -> tuple[bool, float]:
-        """
-        Wait for a deposit to be credited on Hyperliquid L1.
-
-        Args:
-            address: Wallet address
-            expected_increase: Expected USD amount to be deposited
-            timeout_s: Maximum time to wait in seconds
-            poll_interval_s: Time between polling attempts
-
-        Returns:
-            (success, final_balance) - True if deposit confirmed within timeout
-        """
         iterations = timeout_s // poll_interval_s
 
-        # Get initial balance
         success, initial_state = await self.get_user_state(address)
         if not success:
             self.logger.warning(f"Could not fetch initial state: {initial_state}")
@@ -934,7 +651,6 @@ class HyperliquidAdapter(BaseAdapter):
             f"Hyperliquid deposit not confirmed after {timeout_s}s. "
             f"Deposits typically take 1-2 minutes."
         )
-        # Return current balance even if not confirmed
         success, state = await self.get_user_state(address)
         final_balance = (
             self.get_perp_margin_amount(state) if success else initial_balance
@@ -946,16 +662,6 @@ class HyperliquidAdapter(BaseAdapter):
         address: str,
         from_timestamp_ms: int,
     ) -> tuple[bool, dict[str, float]]:
-        """
-        Get user withdrawal history from Hyperliquid.
-
-        Args:
-            address: Wallet address
-            from_timestamp_ms: Start time in milliseconds
-
-        Returns:
-            (success, {tx_hash: usdc_amount})
-        """
         try:
             from eth_utils import to_checksum_address
 
@@ -992,21 +698,6 @@ class HyperliquidAdapter(BaseAdapter):
         max_poll_time_s: int = 30 * 60,
         poll_interval_s: int = 5,
     ) -> tuple[bool, dict[str, float]]:
-        """
-        Wait for a withdrawal to appear on-chain.
-
-        Polls Hyperliquid's ledger updates until a withdrawal is detected.
-        Withdrawals typically take 5-15 minutes to process.
-
-        Args:
-            address: Wallet address
-            lookback_s: How far back to look for withdrawals (small buffer for latency)
-            max_poll_time_s: Maximum time to wait (default 30 minutes)
-            poll_interval_s: Time between polls
-
-        Returns:
-            (success, {tx_hash: usdc_amount}) - withdrawals found
-        """
         import time
 
         start_time_ms = time.time() * 1000