wayfinder-paths 0.1.22__py3-none-any.whl → 0.1.24__py3-none-any.whl

wayfinder_paths/adapters/hyperliquid_adapter/adapter.py

@@ -2,20 +2,34 @@ from __future__ import annotations
 
 import asyncio
 import time
+from decimal import ROUND_DOWN, Decimal, getcontext
 from typing import TYPE_CHECKING, Any
 
+from aiocache import Cache
+from eth_utils import to_checksum_address
+from loguru import logger
+
 from wayfinder_paths.core.adapters.BaseAdapter import BaseAdapter
+from wayfinder_paths.core.constants import ZERO_ADDRESS
+from wayfinder_paths.core.constants.hyperliquid import (
+    ARBITRUM_USDC_ADDRESS as _ARBITRUM_USDC_ADDRESS,
+)
+from wayfinder_paths.core.constants.hyperliquid import (
+    DEFAULT_HYPERLIQUID_BUILDER_FEE_TENTHS_BP,
+    HYPE_FEE_WALLET,
+)
+from wayfinder_paths.core.constants.hyperliquid import (
+    HYPERLIQUID_BRIDGE_ADDRESS as _HYPERLIQUID_BRIDGE_ADDRESS,
+)
 
 if TYPE_CHECKING:
     from wayfinder_paths.core.clients.protocols import (
         HyperliquidExecutorProtocol as HyperliquidExecutor,
     )
 
-# Hyperliquid L1 bridge address on Arbitrum - send USDC here to deposit
-HYPERLIQUID_BRIDGE_ADDRESS = "0x2Df1c51E09aECF9cacB7bc98cB1742757f163dF7"
-
-# USDC contract on Arbitrum
-ARBITRUM_USDC_ADDRESS = "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
+# Re-export Bridge2 constants for backwards compatibility.
+HYPERLIQUID_BRIDGE_ADDRESS = _HYPERLIQUID_BRIDGE_ADDRESS
+ARBITRUM_USDC_ADDRESS = _ARBITRUM_USDC_ADDRESS
 
 try:
     from hyperliquid.info import Info
@@ -28,36 +42,26 @@ except ImportError:
     constants = None
 
 
-class SimpleCache:
-    def __init__(self):
-        self._cache: dict[str, Any] = {}
-        self._expiry: dict[str, float] = {}
-
-    def get(self, key: str) -> Any | None:
-        if key in self._cache:
-            if time.time() < self._expiry.get(key, 0):
-                return self._cache[key]
-            del self._cache[key]
-            if key in self._expiry:
-                del self._expiry[key]
-        return None
-
-    def set(self, key: str, value: Any, timeout: int = 300) -> None:
-        self._cache[key] = value
-        self._expiry[key] = time.time() + timeout
-
-    def clear(self) -> None:
-        self._cache.clear()
-        self._expiry.clear()
-
-
 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__(
         self,
         config: dict[str, Any] | None = None,
         *,
+        simulation: bool = False,
         executor: HyperliquidExecutor | None = None,
     ) -> None:
         super().__init__("hyperliquid_adapter", config)
@@ -68,9 +72,11 @@ class HyperliquidAdapter(BaseAdapter):
                 "Install with: poetry add hyperliquid"
             )
 
-        self._cache = SimpleCache()
+        self.simulation = simulation
+        self._cache = Cache(Cache.MEMORY)
         self._executor = executor
 
+        # Initialize Hyperliquid Info client
         self.info = Info(constants.MAINNET_API_URL, skip_ws=True)
 
         # Cache asset mappings after first fetch
@@ -94,13 +100,14 @@ class HyperliquidAdapter(BaseAdapter):
 
     async def get_meta_and_asset_ctxs(self) -> tuple[bool, Any]:
         cache_key = "hl_meta_and_asset_ctxs"
-        cached = self._cache.get(cache_key)
+        cached = await self._cache.get(cache_key)
         if cached:
             return True, cached
 
         try:
             data = self.info.meta_and_asset_ctxs()
-            self._cache.set(cache_key, data, timeout=60)
+            # Cache for 1 minute
+            await self._cache.set(cache_key, data, ttl=60)
             return True, data
         except Exception as exc:
             self.logger.error(f"Failed to fetch meta_and_asset_ctxs: {exc}")
@@ -108,25 +115,85 @@ class HyperliquidAdapter(BaseAdapter):
 
     async def get_spot_meta(self) -> tuple[bool, Any]:
         cache_key = "hl_spot_meta"
-        cached = self._cache.get(cache_key)
+        cached = await 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()
             else:
                 data = spot_meta
-            self._cache.set(cache_key, data, timeout=60)
+            await self._cache.set(cache_key, data, ttl=60)
             return True, data
         except Exception as exc:
             self.logger.error(f"Failed to fetch spot_meta: {exc}")
             return False, str(exc)
 
+    async def get_spot_token_sz_decimals(self, coin: str) -> int | None:
+        try:
+            success, spot_meta = await self.get_spot_meta()
+            if not success or not isinstance(spot_meta, dict):
+                return None
+
+            for token in spot_meta.get("tokens", []):
+                name = token.get("name") or token.get("coin") or token.get("symbol")
+                if not name:
+                    continue
+                if str(name).upper() != str(coin).upper():
+                    continue
+                sz_decimals = token.get("szDecimals") or token.get("sz_decimals")
+                if sz_decimals is None:
+                    return None
+                return int(sz_decimals)
+        except Exception:  # noqa: BLE001
+            return None
+        return None
+
+    @staticmethod
+    def max_transferable_amount(
+        total: str,
+        hold: str,
+        *,
+        sz_decimals: int,
+        leave_one_tick: bool = True,
+    ) -> float:
+        """Compute a safe transferable amount (Decimal math, round down, leave 1 tick).
+
+        Hyperliquid requires amounts to respect szDecimals. This helper avoids
+        float rounding edge cases by:
+        - parsing balances as Decimal
+        - computing available = total - hold
+        - rounding down to sz_decimals
+        - optionally leaving 1 tick so we don't request the full balance
+        """
+        getcontext().prec = 50
+
+        if sz_decimals < 0:
+            sz_decimals = 0
+
+        step = Decimal(10) ** (-int(sz_decimals))
+
+        total_d = Decimal(str(total or "0"))
+        hold_d = Decimal(str(hold or "0"))
+        available = total_d - hold_d
+        if available <= 0:
+            return 0.0
+
+        safe = available - step if leave_one_tick else available
+        if safe <= 0:
+            return 0.0
+
+        quantized = (safe / step).to_integral_value(rounding=ROUND_DOWN) * step
+        if quantized <= 0:
+            return 0.0
+        return float(quantized)
+
     async def get_spot_assets(self) -> tuple[bool, dict[str, int]]:
         cache_key = "hl_spot_assets"
-        cached = self._cache.get(cache_key)
+        cached = await self._cache.get(cache_key)
         if cached:
             return True, cached
 
@@ -146,6 +213,7 @@ 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 {}
 
@@ -156,16 +224,19 @@ 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
+            await self._cache.set(cache_key, response, ttl=300)
             return True, response
 
         except Exception as exc:
             self.logger.error(f"Failed to get spot assets: {exc}")
             return False, {}
 
-    def get_spot_asset_id(self, base_coin: str, quote_coin: str = "USDC") -> int | None:
+    async def get_spot_asset_id(
+        self, base_coin: str, quote_coin: str = "USDC"
+    ) -> int | None:
         cache_key = "hl_spot_assets"
-        cached = self._cache.get(cache_key)
+        cached = await self._cache.get(cache_key)
         if cached:
             pair_name = f"{base_coin}/{quote_coin}"
             return cached.get(pair_name)
@@ -228,9 +299,63 @@ class HyperliquidAdapter(BaseAdapter):
             self.logger.error(f"Failed to fetch spot_user_state for {address}: {exc}")
             return False, str(exc)
 
+    async def get_full_user_state(
+        self,
+        *,
+        account: str,
+        include_spot: bool = True,
+        include_open_orders: bool = True,
+        include_frontend_open_orders: bool = True,
+    ) -> tuple[bool, dict[str, Any] | str]:
+        """
+        Full Hyperliquid user state snapshot.
+
+        Includes perp positions (user_state), optional spot balances, and optional open
+        orders (frontendOpenOrders by default, since it includes trigger orders).
+        """
+        out: dict[str, Any] = {
+            "protocol": "hyperliquid",
+            "account": account,
+            "perp": None,
+            "spot": None,
+            "openOrders": None,
+            "errors": {},
+        }
+
+        ok_any = False
+
+        ok_perp, perp = await self.get_user_state(account)
+        if ok_perp:
+            ok_any = True
+            out["perp"] = perp
+            out["positions"] = perp.get("assetPositions", [])
+        else:
+            out["errors"]["perp"] = perp
+
+        if include_spot:
+            ok_spot, spot = await self.get_spot_user_state(account)
+            if ok_spot:
+                ok_any = True
+                out["spot"] = spot
+            else:
+                out["errors"]["spot"] = spot
+
+        if include_open_orders:
+            if include_frontend_open_orders:
+                ok_orders, orders = await self.get_frontend_open_orders(account)
+            else:
+                ok_orders, orders = await self.get_open_orders(account)
+            if ok_orders:
+                ok_any = True
+                out["openOrders"] = orders
+            else:
+                out["errors"]["openOrders"] = orders
+
+        return ok_any, out
+
     async def get_margin_table(self, margin_table_id: int) -> tuple[bool, list[dict]]:
         cache_key = f"hl_margin_table_{margin_table_id}"
-        cached = self._cache.get(cache_key)
+        cached = await self._cache.get(cache_key)
         if cached:
             return True, cached
 
@@ -243,7 +368,7 @@ 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)
+            await self._cache.set(cache_key, data, ttl=86400)  # Cache for 24h
             return True, data
         except Exception as exc:
             self.logger.error(f"Failed to fetch margin_table {margin_table_id}: {exc}")
@@ -284,6 +409,7 @@ class HyperliquidAdapter(BaseAdapter):
 
     @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
@@ -296,10 +422,10 @@ class HyperliquidAdapter(BaseAdapter):
                 f"Unknown asset_id {asset_id}: missing szDecimals"
             ) from None
 
-    def refresh_mappings(self) -> None:
+    async def refresh_mappings(self) -> None:
         self._asset_to_sz_decimals = None
         self._coin_to_asset = None
-        self._cache.clear()
+        await self._cache.clear()
 
     # ------------------------------------------------------------------ #
     # Utility Methods                                                      #
@@ -315,8 +441,6 @@ class HyperliquidAdapter(BaseAdapter):
 
     def get_valid_order_size(self, asset_id: int, size: float) -> float:
         decimals = self.get_sz_decimals(asset_id)
-        from decimal import ROUND_DOWN, Decimal
-
         step = Decimal(10) ** (-decimals)
         if size <= 0:
             return 0.0
@@ -329,6 +453,49 @@ class HyperliquidAdapter(BaseAdapter):
     # Execution Methods (require signing callback)                         #
     # ------------------------------------------------------------------ #
 
+    def _mandatory_builder_fee(self, builder: dict[str, Any] | None) -> dict[str, Any]:
+        """
+        Resolve the builder fee config to attach to orders.
+
+        Builder attribution is mandatory in this repo and is always directed to
+        the Wayfinder builder wallet (`HYPE_FEE_WALLET`).
+        """
+        expected_builder = HYPE_FEE_WALLET.lower()
+
+        if isinstance(builder, dict) and builder.get("b") is not None:
+            provided_builder = str(builder.get("b") or "").strip()
+            if provided_builder and provided_builder.lower() != expected_builder:
+                raise ValueError(
+                    f"builder wallet must be {expected_builder} (got {provided_builder})"
+                )
+
+        fee = None
+        if isinstance(builder, dict) and builder.get("f") is not None:
+            fee = builder.get("f")
+
+        if fee is None and isinstance(self.config, dict):
+            cfg = self.config.get("builder_fee")
+            if isinstance(cfg, dict):
+                cfg_builder = str(cfg.get("b") or "").strip()
+                if cfg_builder and cfg_builder.lower() != expected_builder:
+                    raise ValueError(
+                        f"config builder_fee.b must be {expected_builder} (got {cfg_builder})"
+                    )
+                if cfg.get("f") is not None:
+                    fee = cfg.get("f")
+
+        if fee is None:
+            fee = DEFAULT_HYPERLIQUID_BUILDER_FEE_TENTHS_BP
+
+        try:
+            fee_i = int(fee)
+        except (TypeError, ValueError) as exc:
+            raise ValueError("builder fee f must be an int (tenths of bp)") from exc
+        if fee_i <= 0:
+            raise ValueError("builder fee f must be > 0 (tenths of bp)")
+
+        return {"b": expected_builder, "f": fee_i}
+
     async def place_market_order(
         self,
         asset_id: int,
@@ -341,6 +508,31 @@ 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: Builder fee config; if omitted, a mandatory default is applied.
+
+        Returns:
+            (success, response_data or error_message)
+        """
+        builder = self._mandatory_builder_fee(builder)
+
+        if self.simulation:
+            self.logger.info(
+                f"[SIMULATION] place_market_order: asset={asset_id}, "
+                f"is_buy={is_buy}, size={size}, address={address}"
+            )
+            return True, {"simulation": True, "status": "ok"}
+
         if not self._executor:
             raise NotImplementedError(
                 "No Hyperliquid executor configured. "
@@ -358,7 +550,17 @@ class HyperliquidAdapter(BaseAdapter):
             builder=builder,
         )
 
+        # Check both the API status and the order statuses for errors
         success = result.get("status") == "ok"
+        if success:
+            # Check if the order itself has errors in statuses
+            response = result.get("response", {})
+            data = response.get("data", {})
+            statuses = data.get("statuses", [])
+            for status in statuses:
+                if isinstance(status, dict) and status.get("error"):
+                    success = False
+                    break
         return success, result
 
     async def cancel_order(
@@ -367,6 +569,12 @@ class HyperliquidAdapter(BaseAdapter):
         order_id: int | str,
         address: str,
     ) -> tuple[bool, dict[str, Any]]:
+        if self.simulation:
+            self.logger.info(
+                f"[SIMULATION] cancel_order: asset={asset_id}, oid={order_id}"
+            )
+            return True, {"simulation": True, "status": "ok"}
+
         if not self._executor:
             raise NotImplementedError(
                 "No Hyperliquid executor configured. "
@@ -382,6 +590,163 @@ class HyperliquidAdapter(BaseAdapter):
         success = result.get("status") == "ok"
         return success, result
 
+    async def cancel_order_by_cloid(
+        self,
+        asset_id: int,
+        cloid: str,
+        address: str,
+    ) -> tuple[bool, dict[str, Any]]:
+        if self.simulation:
+            logger.info(
+                f"[SIMULATION] cancel_order_by_cloid: asset={asset_id}, cloid={cloid}"
+            )
+            return True, {"simulation": True, "status": "ok"}
+
+        if not self._executor:
+            raise NotImplementedError(
+                "No Hyperliquid executor configured. "
+                "Inject a HyperliquidExecutor implementation (e.g., LocalHyperliquidExecutor)."
+            )
+
+        result = await self._executor.cancel_order_by_cloid(
+            asset_id=asset_id,
+            cloid=cloid,
+            address=address,
+        )
+
+        success = result.get("status") == "ok"
+        return success, result
+
+    async def spot_transfer(
+        self,
+        *,
+        amount: float,
+        destination: str,
+        token: str,
+        address: str,
+    ) -> tuple[bool, dict[str, Any]]:
+        """
+        Transfer a spot token to a destination address (signed spotSend action).
+
+        This is used for:
+        - user-to-user spot transfers
+        - HyperCore → HyperEVM routing (destination = system address)
+        """
+        if self.simulation:
+            logger.info(
+                f"[SIMULATION] spot_transfer: token={token}, amount={amount}, destination={destination}"
+            )
+            return True, {"simulation": True, "status": "ok"}
+
+        if not self._executor:
+            raise NotImplementedError("No Hyperliquid executor configured.")
+
+        result = await self._executor.spot_transfer(
+            amount=float(amount),
+            destination=str(destination),
+            token=str(token),
+            address=address,
+        )
+
+        success = result.get("status") == "ok"
+        return success, result
+
+    @staticmethod
+    def hypercore_index_to_system_address(index: int) -> str:
+        if index == 150:
+            return "0x2222222222222222222222222222222222222222"
+
+        hex_index = f"{index:x}"
+        padding_length = 42 - len("0x20") - len(hex_index)
+        result = "0x20" + "0" * padding_length + hex_index
+        return to_checksum_address(result)
+
+    async def hypercore_get_token_metadata(
+        self, token_address: str | None
+    ) -> dict[str, Any] | None:
+        """
+        Resolve spot token metadata from Hyperliquid spot meta by EVM contract address.
+
+        Special-case: native HYPE uses the 0-address and maps to tokens[150].
+        """
+        token_addr = (token_address or ZERO_ADDRESS).strip()
+        token_addr_lower = token_addr.lower()
+
+        success, spot_meta = await self.get_spot_meta()
+        if not success or not isinstance(spot_meta, dict):
+            return None
+
+        tokens = spot_meta.get("tokens", [])
+        if not isinstance(tokens, list) or not tokens:
+            return None
+
+        if token_addr_lower == ZERO_ADDRESS.lower():
+            token = tokens[150] if len(tokens) > 150 else None
+            return token if isinstance(token, dict) else None
+
+        for token_data in tokens:
+            if not isinstance(token_data, dict):
+                continue
+            evm_contract = token_data.get("evmContract")
+            if not isinstance(evm_contract, dict):
+                continue
+            address = evm_contract.get("address")
+            if isinstance(address, str) and address.lower() == token_addr_lower:
+                return token_data
+
+        return None
+
+    async def hypercore_to_hyperevm(
+        self,
+        *,
+        amount: float,
+        address: str,
+        token_address: str | None = None,
+    ) -> tuple[bool, dict[str, Any]]:
+        """
+        Transfer a spot token from HyperCore (Hyperliquid spot) to HyperEVM.
+
+        Notes:
+        - destination is the token's HyperEVM system address (NOT the user's wallet)
+        - token is formatted as "name:tokenId" from spot meta
+        """
+        token_data = await self.hypercore_get_token_metadata(token_address)
+        if not token_data:
+            return False, {
+                "status": "err",
+                "response": {"type": "error", "data": "Token not found in spot meta"},
+            }
+
+        try:
+            index = int(token_data.get("index"))
+        except (TypeError, ValueError):
+            return False, {
+                "status": "err",
+                "response": {"type": "error", "data": "Token metadata missing index"},
+            }
+
+        destination = self.hypercore_index_to_system_address(index)
+        name = token_data.get("name")
+        token_id = token_data.get("tokenId")
+        if not isinstance(name, str) or not name:
+            return False, {
+                "status": "err",
+                "response": {"type": "error", "data": "Token metadata missing name"},
+            }
+        if token_id is None:
+            return False, {
+                "status": "err",
+                "response": {"type": "error", "data": "Token metadata missing tokenId"},
+            }
+        token_string = f"{name}:{token_id}"
+
+        return await self.spot_transfer(
+            amount=float(amount),
+            destination=destination,
+            token=token_string,
+            address=address,
+        )
+
     async def update_leverage(
         self,
         asset_id: int,
@@ -389,6 +754,12 @@ class HyperliquidAdapter(BaseAdapter):
         is_cross: bool,
         address: str,
     ) -> tuple[bool, dict[str, Any]]:
+        if self.simulation:
+            self.logger.info(
+                f"[SIMULATION] update_leverage: asset={asset_id}, leverage={leverage}"
+            )
+            return True, {"simulation": True, "status": "ok"}
+
         if not self._executor:
             raise NotImplementedError("No Hyperliquid executor configured.")
 
@@ -407,6 +778,10 @@ class HyperliquidAdapter(BaseAdapter):
         amount: float,
         address: str,
     ) -> tuple[bool, dict[str, Any]]:
+        if self.simulation:
+            self.logger.info(f"[SIMULATION] transfer_spot_to_perp: {amount} USDC")
+            return True, {"simulation": True, "status": "ok"}
+
         if not self._executor:
             raise NotImplementedError("No Hyperliquid executor configured.")
 
@@ -423,6 +798,10 @@ class HyperliquidAdapter(BaseAdapter):
         amount: float,
         address: str,
     ) -> tuple[bool, dict[str, Any]]:
+        if self.simulation:
+            self.logger.info(f"[SIMULATION] transfer_perp_to_spot: {amount} USDC")
+            return True, {"simulation": True, "status": "ok"}
+
         if not self._executor:
             raise NotImplementedError("No Hyperliquid executor configured.")
 
@@ -442,6 +821,13 @@ class HyperliquidAdapter(BaseAdapter):
         size: float,
         address: str,
     ) -> tuple[bool, dict[str, Any]]:
+        if self.simulation:
+            self.logger.info(
+                f"[SIMULATION] place_stop_loss: asset={asset_id}, "
+                f"trigger={trigger_price}, size={size}"
+            )
+            return True, {"simulation": True, "status": "ok"}
+
         if not self._executor:
             raise NotImplementedError("No Hyperliquid executor configured.")
 
@@ -464,6 +850,49 @@ class HyperliquidAdapter(BaseAdapter):
             self.logger.error(f"Failed to fetch user_fills for {address}: {exc}")
             return False, str(exc)
 
+    async def check_recent_liquidations(
+        self, address: str, since_ms: int
+    ) -> tuple[bool, list[dict[str, Any]]]:
+        """
+        Check if user was liquidated since a given timestamp.
+
+        Fills have an optional 'liquidation' field with:
+        - liquidatedUser: who got liquidated
+        - markPx: price at liquidation
+        - method: "market" or "backstop"
+
+        Args:
+            address: Wallet address
+            since_ms: Epoch milliseconds to check from
+
+        Returns:
+            (success, list of liquidation fills where user was liquidated)
+        """
+        try:
+            now_ms = int(time.time() * 1000)
+            body = {
+                "type": "userFillsByTime",
+                "user": address,
+                "startTime": since_ms,
+                "endTime": now_ms,
+            }
+            data = self.info.post("/info", body)
+            fills = data if isinstance(data, list) else []
+
+            # Filter for liquidation fills where we were the liquidated user
+            liquidation_fills = [
+                f
+                for f in fills
+                if f.get("liquidation")
+                and f["liquidation"].get("liquidatedUser", "").lower()
+                == address.lower()
+            ]
+
+            return True, liquidation_fills
+        except Exception as exc:
+            self.logger.error(f"Failed to check liquidations for {address}: {exc}")
+            return False, []
+
     async def get_order_status(
         self, address: str, order_id: int | str
     ) -> tuple[bool, dict[str, Any]]:
@@ -486,6 +915,18 @@ 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 []
@@ -501,6 +942,15 @@ 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 self.simulation:
+            self.logger.info(f"[SIMULATION] withdraw: {amount} USDC")
+            return True, {"simulation": True, "status": "ok"}
+
         if not self._executor:
             raise NotImplementedError("No Hyperliquid executor configured.")
 
@@ -511,22 +961,6 @@ class HyperliquidAdapter(BaseAdapter):
         success = result.get("status") == "ok"
         return success, result
 
-    # ------------------------------------------------------------------ #
-    # Health Check                                                        #
-    # ------------------------------------------------------------------ #
-
-    async def health_check(self) -> dict[str, Any]:
-        try:
-            success, meta = await self.get_meta_and_asset_ctxs()
-            if success and meta:
-                return {
-                    "status": "healthy",
-                    "perp_markets": len(meta[0].get("universe", [])) if meta else 0,
-                }
-            return {"status": "unhealthy", "error": "Failed to fetch metadata"}
-        except Exception as exc:
-            return {"status": "unhealthy", "error": str(exc)}
-
     # ------------------------------------------------------------------ #
     # Deposit/Withdrawal Helpers                                          #
     # ------------------------------------------------------------------ #
@@ -563,6 +997,13 @@ class HyperliquidAdapter(BaseAdapter):
         max_fee_rate: str,
         address: str,
     ) -> tuple[bool, dict[str, Any]]:
+        if self.simulation:
+            self.logger.info(
+                f"[SIMULATION] approve_builder_fee: builder={builder}, "
+                f"rate={max_fee_rate}, address={address}"
+            )
+            return True, {"simulation": True, "status": "ok"}
+
         if not self._executor:
             raise NotImplementedError("No Hyperliquid executor configured.")
 
@@ -575,6 +1016,47 @@ class HyperliquidAdapter(BaseAdapter):
         success = result.get("status") == "ok"
         return success, result
 
+    async def ensure_builder_fee_approved(
+        self,
+        address: str,
+        builder_fee: dict[str, Any] | None = None,
+    ) -> tuple[bool, str]:
+        if self.simulation:
+            return True, "Simulation mode - builder fee not needed"
+
+        # Resolve fee config from parameter or config
+        fee_config = builder_fee
+        if not fee_config and isinstance(self.config, dict):
+            fee_config = self.config.get("builder_fee")
+
+        if not fee_config or not isinstance(fee_config, dict):
+            return True, "No builder fee configured"
+
+        builder = fee_config.get("b")
+        required_fee = fee_config.get("f", 0)
+        if not builder or not required_fee:
+            return True, "Builder fee not configured"
+
+        # Check current approval
+        try:
+            ok, current_fee = await self.get_max_builder_fee(address, builder)
+            if ok and int(current_fee) >= int(required_fee):
+                return (
+                    True,
+                    f"Builder fee already approved ({current_fee} >= {required_fee})",
+                )
+        except Exception as e:
+            logger.warning(
+                f"Failed to check builder fee: {e}, proceeding with approval"
+            )
+
+        # Approve
+        max_fee_rate = f"{int(required_fee) / 1000:.3f}%"
+        ok, result = await self.approve_builder_fee(builder, max_fee_rate, address)
+        if ok:
+            return True, f"Builder fee approved: {max_fee_rate}"
+        return False, f"Builder fee approval failed: {result}"
+
     async def place_limit_order(
         self,
         asset_id: int,
@@ -586,6 +1068,32 @@ 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: Builder fee config; if omitted, a mandatory default is applied.
+
+        Returns:
+            (success, response_data or error_message)
+        """
+        builder = self._mandatory_builder_fee(builder)
+
+        if self.simulation:
+            self.logger.info(
+                f"[SIMULATION] place_limit_order: asset={asset_id}, "
+                f"is_buy={is_buy}, price={price}, size={size}"
+            )
+            return True, {"simulation": True, "status": "ok"}
+
         if not self._executor:
             raise NotImplementedError("No Hyperliquid executor configured.")
 
@@ -612,6 +1120,7 @@ class HyperliquidAdapter(BaseAdapter):
     ) -> tuple[bool, float]:
         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}")
@@ -649,8 +1158,9 @@ class HyperliquidAdapter(BaseAdapter):
 
         self.logger.warning(
             f"Hyperliquid deposit not confirmed after {timeout_s}s. "
-            f"Deposits typically take 1-2 minutes."
+            "Deposits typically credit in < 1 minute (but can take longer)."
         )
+        # 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
@@ -698,6 +1208,21 @@ 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 ~3-4 minutes to process (but can take longer).
+
+        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
@@ -719,7 +1244,7 @@ class HyperliquidAdapter(BaseAdapter):
             remaining_s = i * poll_interval_s
             self.logger.info(
                 f"Waiting for withdrawal to appear on-chain... "
-                f"{remaining_s}s remaining (withdrawals often take 10+ minutes)"
+                f"{remaining_s}s remaining (withdrawals often take a few minutes)"
             )
             await asyncio.sleep(poll_interval_s)