1"""
2Hyperliquid API Client — wraps /info (read-only) and /exchange (signed) endpoints.
3 
4Uses the hyperliquid-python-sdk Info class for reads, and custom signing
5(via wallet service) for exchange actions.
6"""
7 
8import logging
9import os
10import time
11from decimal import Decimal
12from typing import Any, Dict, Optional
13 
14import aiohttp
15 
16from .signing import sign_l1_action, sign_user_action, sign_user_set_abstraction
17 
18logger = logging.getLogger(__name__)
19 
20DEFAULT_API_URL = "https://api.hyperliquid.xyz"
21DEFAULT_SLIPPAGE = 0.03  # 3% for market orders
22 
23 
24def float_to_wire(x: float) -> str:
25    """Convert a float to a string matching Hyperliquid's server-side normalization.
26 
27    Matches the official Hyperliquid Python SDK: rounds to 8 decimal places,
28    then strips trailing zeros via Decimal.normalize().
29    """
30    rounded = f"{x:.8f}"
31    if abs(float(rounded) - x) >= 1e-12:
32        raise ValueError(f"float_to_wire: rounding loses precision for {x}")
33    if rounded == "-0.00000000":
34        rounded = "0.00000000"
35    normalized = Decimal(rounded).normalize()
36    return f"{normalized:f}"
37 
38# Hyperliquid bridge contract (for USDC deposits)
39BRIDGE_ADDRESS = "0x2Df1c51E09aECF9cacB7bc98cB1742757f163dF7"
40 
41# USDC on Arbitrum
42USDC_ADDRESS = "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
43USDC_DECIMALS = 6
44ARBITRUM_CHAIN_ID = 42161
45MIN_DEPOSIT_USDC = 5
46 
47 
48class HyperliquidClient:
49    """
50    Async Hyperliquid client.
51 
52    - Info methods: POST to /info (no auth)
53    - Exchange methods: POST to /exchange (signed)
54    """
55 
56    def __init__(self, api_url: Optional[str] = None):
57        self.api_url = api_url or os.environ.get(
58            "HYPERLIQUID_API_URL", DEFAULT_API_URL
59        )
60        # Cached metadata
61        self._meta: Optional[dict] = None
62        self._spot_meta: Optional[dict] = None
63        self._name_to_index: Dict[str, int] = {}
64        self._spot_name_to_index: Dict[str, int] = {}
65        self._spot_mid_key: Dict[str, str] = {}  # user name → allMids key
66        self._sz_decimals: Dict[str, int] = {}
67        # Builder dex (HIP-3) metadata — lazy loaded
68        self._perp_dexs: Optional[list] = None         # perpDexs API response
69        self._dex_offsets: Dict[str, int] = {}          # dex_name -> asset index offset
70        self._builder_meta: Dict[str, dict] = {}        # dex_name -> meta response
71 
72    # ── Internal helpers ─────────────────────────────────────────────────
73 
74    async def _post(self, endpoint: str, payload: dict) -> Any:
75        """POST to Hyperliquid API."""
76        url = f"{self.api_url}{endpoint}"
77        async with aiohttp.ClientSession() as session:
78            async with session.post(
79                url,
80                json=payload,
81                timeout=aiohttp.ClientTimeout(total=15),
82            ) as resp:
83                if resp.status >= 400:
84                    body = await resp.text()
85                    raise Exception(f"Hyperliquid API {resp.status}: {body}")
86                data = await resp.json()
87                # Hyperliquid returns HTTP 200 with {"status": "err", "response": "..."} for API-level errors
88                if isinstance(data, dict) and data.get("status") == "err":
89                    raise Exception(f"Hyperliquid error: {data.get('response', data)}")
90                return data
91 
92    async def _info(self, req_type: str, **kwargs) -> Any:
93        """Query the /info endpoint."""
94        payload = {"type": req_type, **kwargs}
95        return await self._post("/info", payload)
96 
97    async def _exchange(
98        self,
99        action: dict,
100        nonce: Optional[int] = None,
101        vault_address: Optional[str] = None,
102    ) -> Any:
103        """Submit a signed action to the /exchange endpoint.
104 
105        Matches SDK's Exchange._post_action() behavior.
106        """
107        if nonce is None:
108            nonce = int(time.time() * 1000)
109 
110        action_type = action.get("type", "unknown")
111        wallet_addr = self._cached_address or "unknown"
112        logger.info(
113            f"_exchange: action_type={action_type}, wallet={wallet_addr}, nonce={nonce}"
114        )
115 
116        signature = await sign_l1_action(action, nonce, vault_address)
117 
118        # Match SDK payload structure exactly
119        # vaultAddress: included for most actions, None for usdClassTransfer/sendAsset
120        # expiresAfter: None by default (matches SDK's expires_after = None)
121        payload = {
122            "action": action,
123            "nonce": nonce,
124            "signature": signature,
125            "vaultAddress": vault_address if action_type not in ["usdClassTransfer", "sendAsset"] else None,
126            "expiresAfter": None,  # matches SDK default
127        }
128 
129        try:
130            return await self._post("/exchange", payload)
131        except Exception as e:
132            logger.error(
133                f"_exchange FAILED: action_type={action_type}, wallet={wallet_addr}, "
134                f"nonce={nonce}, error={e}"
135            )
136            raise
137 
138    async def _ensure_meta(self) -> None:
139        """Fetch and cache perp + spot metadata for asset index resolution."""
140        if self._meta is None:
141            self._meta = await self._info("meta")
142            for i, asset in enumerate(self._meta.get("universe", [])):
143                name = asset["name"]
144                self._name_to_index[name] = i
145                self._sz_decimals[name] = asset.get("szDecimals", 0)
146 
147        if self._spot_meta is None:
148            try:
149                self._spot_meta = await self._info("spotMeta")
150                for pair in self._spot_meta.get("universe", []):
151                    # universe entries: {"tokens": [1,0], "name": "PURR/USDC", "index": 0}
152                    # Non-canonical entries have names like "@1", "@2"
153                    pair_name = pair.get("name", "")
154                    idx = pair.get("index", 0)
155                    if "/" in pair_name:
156                        # Canonical pair like "PURR/USDC" — map base name
157                        base = pair_name.split("/")[0]
158                        self._spot_name_to_index[base] = idx
159                        self._spot_mid_key[base] = pair_name  # allMids uses "PURR/USDC"
160                    elif pair_name:
161                        # Non-canonical like "@1" — map as-is
162                        self._spot_name_to_index[pair_name] = idx
163                        self._spot_mid_key[pair_name] = pair_name
164            except Exception:
165                self._spot_meta = {}
166 
167    async def _ensure_builder_dex(self, dex_name: str) -> None:
168        """Lazy-load builder dex metadata (HIP-3 perps like xyz:NVDA).
169 
170        Called only when a coin with ':' prefix is encountered.
171        Fetches perpDexs once to discover all builder dexes and compute offsets,
172        then fetches meta for the specific builder dex.
173        """
174        # Already loaded this dex
175        if dex_name in self._builder_meta:
176            return
177 
178        # Fetch perpDexs list once to compute offsets
179        if self._perp_dexs is None:
180            raw = await self._info("perpDexs")
181            # perpDexs returns [null, {"name": "xyz", ...}, {"name": "rage", ...}, ...]
182            # First element is null (default dex), rest are builder dex objects.
183            # Offset formula matches SDK: skip index 0, then 110000 + i * 10000
184            self._perp_dexs = raw
185            idx = 0
186            for entry in raw:
187                if entry is None:
188                    continue
189                name = entry if isinstance(entry, str) else entry.get("name", "")
190                if name:
191                    self._dex_offsets[name] = 110000 + idx * 10000
192                    idx += 1
193 
194        if dex_name not in self._dex_offsets:
195            raise ValueError(
196                f"Unknown builder dex: {dex_name}. "
197                f"Available: {list(self._dex_offsets.keys())}"
198            )
199 
200        # Fetch meta for this specific builder dex
201        meta = await self._info("meta", dex=dex_name)
202        self._builder_meta[dex_name] = meta
203        offset = self._dex_offsets[dex_name]
204 
205        for i, asset in enumerate(meta.get("universe", [])):
206            asset_name = asset["name"]
207            # meta(dex="xyz") returns names already prefixed: "xyz:NVDA"
208            # Use the name as-is if it contains ':', otherwise prefix it
209            full_name = asset_name if ":" in asset_name else f"{dex_name}:{asset_name}"
210            self._name_to_index[full_name] = offset + i
211            self._sz_decimals[full_name] = asset.get("szDecimals", 0)
212 
213    async def _resolve_asset(self, coin: str) -> int:
214        """Resolve coin name to perp asset index.
215 
216        Supports builder perps via 'dex:COIN' format (e.g. 'xyz:NVDA').
217        """
218        # Try direct match first
219        idx = self._name_to_index.get(coin)
220        if idx is not None:
221            return idx
222 
223        # Case-insensitive fallback (e.g. "ai16z" -> "AI16Z")
224        coin_upper = coin.upper()
225        for name, i in self._name_to_index.items():
226            if name.upper() == coin_upper:
227                return i
228 
229        # If coin contains ':', try loading the builder dex
230        if ":" in coin:
231            dex_name = coin.split(":")[0]
232            await self._ensure_builder_dex(dex_name)
233            idx = self._name_to_index.get(coin)
234            if idx is not None:
235                return idx
236 
237        raise ValueError(
238            f"Unknown perp asset: {coin}. "
239            f"Available: {list(self._name_to_index.keys())[:20]}..."
240        )
241 
242    async def _resolve_any_asset(self, coin: str) -> int:
243        """Resolve coin name to asset index — tries perps, builder perps, then spot."""
244        await self._ensure_meta()
245        try:
246            return await self._resolve_asset(coin)
247        except ValueError:
248            pass
249        # Try spot (exact then case-insensitive)
250        idx = self._spot_name_to_index.get(coin)
251        if idx is not None:
252            return 10000 + idx
253        coin_upper = coin.upper()
254        for name, i in self._spot_name_to_index.items():
255            if name.upper() == coin_upper:
256                return 10000 + i
257        raise ValueError(f"Unknown asset: {coin}")
258 
259    def _resolve_spot_asset(self, coin: str) -> int:
260        """Resolve coin name to spot asset index (10000 + idx)."""
261        idx = self._spot_name_to_index.get(coin)
262        if idx is None:
263            raise ValueError(
264                f"Unknown spot asset: {coin}. "
265                f"Available: {list(self._spot_name_to_index.keys())[:20]}..."
266            )
267        return 10000 + idx
268 
269    def _format_size(self, coin: str, size: float) -> str:
270        """Format size using float_to_wire for exact Hyperliquid normalization."""
271        return float_to_wire(size)
272 
273    def _format_price(self, price: float, coin: str = "", is_spot: bool = False) -> str:
274        """Format price matching the official SDK's rounding rules.
275 
276        Prices can have up to 5 significant figures, but no more than
277        (MAX_DECIMALS - szDecimals) decimal places where MAX_DECIMALS is 6
278        for perps and 8 for spot. Integer prices are always allowed.
279        """
280        # Step 1: round to 5 significant figures
281        rounded = float(f"{price:.5g}")
282        # Step 2: constrain decimal places based on szDecimals
283        sz_decimals = self._sz_decimals.get(coin, 0)
284        max_decimals = 8 if is_spot else 6
285        max_dp = max_decimals - sz_decimals
286        if max_dp >= 0:
287            rounded = round(rounded, max_dp)
288        return float_to_wire(rounded)
289 
290    async def _validate_order_margin(
291        self,
292        coin: str,
293        size: float,
294        price: float,
295        leverage: int = 1,
296        is_spot: bool = False,
297    ) -> tuple[bool, str]:
298        """Validate if account has sufficient margin for an order.
299 
300        Returns: (is_valid, error_message)
301        """
302        try:
303            # Spot orders don't use leverage/margin
304            if is_spot:
305                return (True, "")
306 
307            # Calculate order notional value
308            order_value = size * price
309 
310            # Check minimum order value ($10)
311            if order_value < 10:
312                return (
313                    False,
314                    f"Order value ${order_value:.2f} is below minimum $10. "
315                    f"Increase size to at least {10 / price:.4f} {coin}",
316                )
317 
318            # Calculate required margin (notional / leverage)
319            required_margin = order_value / max(leverage, 1)
320 
321            # CRITICAL: Check abstraction mode FIRST to determine which account to query
322            # Unified account mode keeps funds in SPOT, not PERP
323            address = await self._get_address()
324            current_mode = "default"
325            try:
326                abstraction_state = await self.get_user_abstraction_state(address)
327                if isinstance(abstraction_state, str):
328                    current_mode = abstraction_state
329                elif isinstance(abstraction_state, dict):
330                    current_mode = abstraction_state.get("type", abstraction_state.get("state", "default"))
331            except Exception:
332                current_mode = "default"
333 
334            # Get account state based on abstraction mode
335            if current_mode == "unifiedAccount":
336                # Unified account: funds are in SPOT (shared collateral)
337                spot_state = await self.get_spot_state(address)
338                # Find USDC balance in spot
339                usdc_balance = 0.0
340                for bal in spot_state.get("balances", []):
341                    if bal.get("coin") == "USDC":
342                        usdc_balance = float(bal.get("total", 0))
343                        break
344 
345                # Use SPOT balance as available margin
346                account_value = usdc_balance
347                total_margin_used = 0.0  # Unified account shares collateral
348                available_margin = account_value
349 
350                logger.info(
351                    f"Margin validation for {coin} (UNIFIED ACCOUNT): "
352                    f"spot_usdc=${usdc_balance:.2f}, "
353                    f"available=${available_margin:.2f}"
354                )
355            else:
356                # Default/disabled mode: check PERP account
357                state = await self.get_account_state(address)
358                margin_summary = state.get("marginSummary", {})
359                account_value = float(margin_summary.get("accountValue", 0))
360                total_margin_used = float(margin_summary.get("totalMarginUsed", 0))
361                available_margin = account_value - total_margin_used
362 
363                logger.info(
364                    f"Margin validation for {coin} (PERP ACCOUNT): "
365                    f"accountValue=${account_value:.2f}, "
366                    f"totalMarginUsed=${total_margin_used:.2f}, "
367                    f"available=${available_margin:.2f}"
368                )
369 
370            # Require a safety buffer (5%)
371            safe_available = available_margin * 0.95
372 
373            if required_margin > safe_available:
374                error_msg = (
375                    f"Insufficient margin for {coin} order. "
376                    f"Required: ${required_margin:.2f}, "
377                    f"Available: ${safe_available:.2f} "
378                    f"(Account value: ${account_value:.2f}, Used: ${total_margin_used:.2f}). "
379                )
380 
381                # Add mode-specific guidance
382                if current_mode == "unifiedAccount":
383                    error_msg += (
384                        f"\n\n⚠️ UNIFIED ACCOUNT MODE ACTIVE: Checked SPOT balance (${account_value:.2f}) where your collateral is. "
385                        f"If you think you have more funds, use `hl_total_balance` tool to see the complete picture. "
386                        f"DO NOT use `hl_account` or `hl_balances` alone - they only show partial balances!"
387                    )
388                elif account_value == 0:
389                    error_msg += (
390                        "\n\n💡 NOTE: Showing $0 balance in PERP account."
391                        " If you have funds in SPOT, enable unified"
392                        " account mode to share collateral across"
393                        " spot/perp, or manually transfer USDC to"
394                        " perp using `hl_transfer_usd`."
395                    )
396 
397                if ":" in coin:
398                    # Builder perp specific guidance
399                    dex_name = coin.split(":")[0]
400                    error_msg += (
401                        f"\n\n🏗️  BUILDER PERP ({dex_name}): "
402                        f"DEX abstraction auto-transfers funds from main account → {dex_name} dex when order is placed. "
403                        f"Validation checks main account available margin (not {dex_name} dex balance)."
404                    )
405 
406                error_msg += (
407                    f"\n\n✅ SOLUTIONS:\n"
408                    f"1) Use `hl_total_balance` to check actual available funds\n"
409                    f"2) Reduce size to {safe_available * leverage / price:.4f} {coin} or less\n"
410                    f"3) Increase leverage (if below max for this asset)\n"
411                    f"4) Deposit more USDC to your Hyperliquid account\n"
412                    f"5) Close other positions to free up margin"
413                )
414 
415                return (False, error_msg)
416 
417            return (True, "")
418 
419        except Exception as e:
420            logger.warning(f"Order validation failed: {e}")
421            # Don't block order on validation errors - let exchange validate
422            return (True, "")
423 
424    # ── Info Methods (read-only, no auth) ────────────────────────────────
425 
426    async def get_account_state(self, address: str, dex: Optional[str] = None) -> dict:
427        """Get perp positions, margin, account value.
428 
429        Args:
430            address: Wallet address
431            dex: Builder dex name (e.g. 'xyz') for HIP-3 perp positions.
432                 None for default perp positions.
433        """
434        if dex:
435            return await self._info("clearinghouseState", user=address, dex=dex)
436        return await self._info("clearinghouseState", user=address)
437 
438    async def get_spot_state(self, address: str) -> dict:
439        """Get spot token balances."""
440        return await self._info("spotClearinghouseState", user=address)
441 
442    async def get_open_orders(self, address: str) -> list:
443        """Get all open orders."""
444        return await self._info("openOrders", user=address)
445 
446    async def get_all_mids(self, dex: Optional[str] = None) -> dict:
447        """Get current mid prices for all assets.
448 
449        Args:
450            dex: Builder dex name (e.g. 'xyz') for builder perp mid prices.
451                 None for default perp/spot mid prices.
452        """
453        if dex:
454            return await self._info("allMids", dex=dex)
455        return await self._info("allMids")
456 
457    async def get_l2_book(self, coin: str) -> dict:
458        """Get L2 orderbook snapshot."""
459        return await self._info("l2Book", coin=coin)
460 
461    async def get_meta(self) -> dict:
462        """Get perp universe metadata."""
463        await self._ensure_meta()
464        return self._meta
465 
466    async def get_spot_meta(self) -> dict:
467        """Get spot universe metadata."""
468        await self._ensure_meta()
469        return self._spot_meta
470 
471    async def get_candles(
472        self, coin: str, interval: str, start: int, end: int
473    ) -> list:
474        """Get OHLCV candlestick data."""
475        return await self._info(
476            "candleSnapshot",
477            req={"coin": coin, "interval": interval, "startTime": start, "endTime": end},
478        )
479 
480    async def get_user_fills(self, address: str) -> list:
481        """Get recent trade fills."""
482        return await self._info("userFills", user=address)
483 
484    async def get_funding_history(
485        self, coin: str, start: int
486    ) -> list:
487        """Get historical funding rates."""
488        return await self._info(
489            "fundingHistory", coin=coin, startTime=start
490        )
491 
492    async def get_predicted_fundings(self) -> list:
493        """Get predicted next funding rates for all assets."""
494        return await self._info("predictedFundings")
495 
496    async def get_user_fees(self, address: str) -> dict:
497        """Get user fee schedule."""
498        return await self._info("userFees", user=address)
499 
500    async def get_user_abstraction_state(self, address: str) -> dict:
501        """Query current abstraction state for a user.
502 
503        Returns abstraction mode: "default", "unifiedAccount", "portfolioMargin", or "disabled"
504        """
505        return await self._info("userAbstraction", user=address)
506 
507    async def get_order_status(self, address: str, oid: int) -> dict:
508        """Look up a single order by oid."""
509        return await self._info("orderStatus", user=address, oid=oid)
510 
511    # ── Exchange Methods (require signing) ───────────────────────────────
512 
513    async def place_order(
514        self,
515        coin: str,
516        is_buy: bool,
517        size: float,
518        price: Optional[float] = None,
519        order_type: str = "limit",
520        reduce_only: bool = False,
521        cloid: Optional[str] = None,
522        is_spot: bool = False,
523        trigger_px: Optional[float] = None,
524        tpsl: Optional[str] = None,
525    ) -> dict:
526        """
527        Place a perp or spot order.
528 
529        Args:
530            coin: Asset name (e.g. "BTC", "ETH")
531            is_buy: True for buy, False for sell
532            size: Order size in base asset
533            price: Limit price. None = market order (IoC with slippage)
534            order_type: "limit" (GTC), "ioc", "alo" (post-only)
535            reduce_only: If True, only reduces position
536            cloid: Optional client order ID
537            is_spot: If True, use spot asset index
538            trigger_px: Trigger price for stop loss / take profit orders
539            tpsl: "tp" for take profit, "sl" for stop loss
540        """
541        await self._ensure_meta()
542 
543        # Builder perps (HIP-3) need DEX abstraction for collateral
544        # Enable BEFORE validation so we can check actual available margin
545        logger.info(f"place_order DEX check: coin={coin}, is_spot={is_spot}, has_colon={':' in coin}")
546        if not is_spot and ":" in coin:
547            logger.info(f"place_order: triggering DEX abstraction for builder perp {coin}")
548            await self.ensure_dex_abstraction()
549        else:
550            logger.info(f"place_order: skipping DEX abstraction (is_spot={is_spot}, coin={coin})")
551 
552        asset_idx = (
553            self._resolve_spot_asset(coin)
554            if is_spot
555            else await self._resolve_asset(coin)
556        )
557 
558        # Market order: fetch mid price and apply slippage
559        # IMPORTANT: Skip this for trigger orders - they use trigger_px, not current mid
560        if price is None and trigger_px is None:
561            # Regular market order (non-trigger)
562            # Builder perps use dex-specific allMids
563            if not is_spot and ":" in coin:
564                dex_name = coin.split(":")[0]
565                mids = await self.get_all_mids(dex=dex_name)
566                # allMids(dex="xyz") returns keys like "xyz:NVDA", use full coin name
567                mid_key = coin
568            else:
569                mids = await self.get_all_mids()
570                # Spot uses pair name in allMids (e.g. "PURR/USDC" or "@1")
571                if is_spot:
572                    mid_key = self._spot_mid_key.get(coin, coin)
573                else:
574                    mid_key = coin
575            mid_str = mids.get(mid_key)
576            if not mid_str:
577                raise ValueError(f"No mid price for {coin} (looked up '{mid_key}')")
578            mid = float(mid_str)
579            slippage = DEFAULT_SLIPPAGE
580            price = mid * (1 + slippage) if is_buy else mid * (1 - slippage)
581            order_type = "ioc"  # Force IoC for market orders
582 
583        # Pre-flight validation: check margin requirements
584        # CRITICAL: When unified account is active, funds are shared across spot/perp/builder-dexes
585        # Check SPOT balance instead of perp, since that's where the collateral actually is
586        if not is_spot and not reduce_only:
587            try:
588                address = await self._get_address()
589 
590                # Check if unified account is active
591                try:
592                    abstraction_state = await self.get_user_abstraction_state(address)
593                    if isinstance(abstraction_state, str):
594                        current_abstraction = abstraction_state
595                    elif isinstance(abstraction_state, dict):
596                        current_abstraction = abstraction_state.get("type", abstraction_state.get("state", "default"))
597                    else:
598                        current_abstraction = "default"
599                except Exception:
600                    current_abstraction = "default"
601 
602                # Get margin state - check SPOT if unified, otherwise check perp
603                if current_abstraction == "unifiedAccount":
604                    # Unified account: check SPOT balance (where collateral actually is)
605                    spot_state = await self.get_spot_state(address)
606                    # Find USDC balance in spot
607                    usdc_balance = 0.0
608                    for bal in spot_state.get("balances", []):
609                        if bal.get("coin") == "USDC":
610                            usdc_balance = float(bal.get("total", 0))
611                            break
612 
613                    # Create a synthetic margin summary from spot balance
614                    state = {
615                        "marginSummary": {
616                            "accountValue": str(usdc_balance),
617                            "totalMarginUsed": "0.0",  # Unified account shares collateral
618                            "totalNtlPos": "0.0",
619                            "totalRawUsd": str(usdc_balance),
620                        },
621                        "assetPositions": [],  # Will check metadata for leverage
622                    }
623                    logger.info(f"Unified account active: using SPOT balance ${usdc_balance:.2f} for margin validation")
624                else:
625                    # Default mode: check perp clearinghouse
626                    state = await self.get_account_state(address)
627 
628                # Extract leverage from assetPositions or use default
629                leverage = 1
630                for pos in state.get("assetPositions", []):
631                    position = pos.get("position", pos)
632                    if position.get("coin") == coin:
633                        lev_info = position.get("leverage", {})
634                        leverage = lev_info.get("value", 1)
635                        break
636 
637                # If no position, check metadata for default/max leverage
638                if leverage == 1:
639                    if ":" in coin:
640                        dex_name = coin.split(":")[0]
641                        meta = self._builder_meta.get(dex_name, {})
642                        for asset in meta.get("universe", []):
643                            if asset["name"] == coin or asset["name"] == coin.split(":", 1)[-1]:
644                                # Use max leverage as estimate if no position exists
645                                leverage = asset.get("maxLeverage", 1)
646                                break
647                    else:
648                        if self._meta:
649                            for asset in self._meta.get("universe", []):
650                                if asset["name"] == coin:
651                                    leverage = asset.get("maxLeverage", 1)
652                                    break
653 
654                # Validate margin
655                is_valid, error_msg = await self._validate_order_margin(
656                    coin=coin,
657                    size=size,
658                    price=price,
659                    leverage=leverage,
660                    is_spot=is_spot,
661                )
662 
663                if not is_valid:
664                    raise ValueError(error_msg)
665 
666            except ValueError:
667                # Re-raise validation errors
668                raise
669            except Exception as e:
670                # Don't block order on validation errors
671                logger.warning(f"Order validation error (non-blocking): {e}")
672 
673        # Build order type spec
674        if trigger_px is not None:
675            # Trigger order - use float_to_wire directly (matches SDK)
676            # This ensures consistent serialization when price == trigger_px
677            formatted_trigger = float_to_wire(trigger_px)
678            formatted_price = float_to_wire(price)
679 
680            is_market_trigger = (price == trigger_px) if price is not None else True
681            # CRITICAL: Field order must match SDK exactly for msgpack hash consistency
682            # SDK uses: isMarket, triggerPx, tpsl (not triggerPx first!)
683            trigger_spec = {
684                "isMarket": is_market_trigger,
685                "triggerPx": formatted_trigger,
686                "tpsl": tpsl or "tp",
687            }
688            tif_spec = {"trigger": trigger_spec}
689        elif order_type == "limit":
690            # Regular orders - keep existing validation
691            formatted_price = self._format_price(price, coin=coin, is_spot=is_spot)
692            tif_spec = {"limit": {"tif": "Gtc"}}
693        elif order_type == "ioc":
694            formatted_price = self._format_price(price, coin=coin, is_spot=is_spot)
695            tif_spec = {"limit": {"tif": "Ioc"}}
696        elif order_type == "alo":
697            formatted_price = self._format_price(price, coin=coin, is_spot=is_spot)
698            tif_spec = {"limit": {"tif": "Alo"}}
699        else:
700            formatted_price = self._format_price(price, coin=coin, is_spot=is_spot)
701            tif_spec = {"limit": {"tif": "Gtc"}}
702 
703        order = {
704            "a": asset_idx,
705            "b": is_buy,
706            "p": formatted_price,
707            "s": self._format_size(coin, size),
708            "r": reduce_only,
709            "t": tif_spec,
710        }
711        if cloid:
712            order["c"] = cloid
713 
714        action = {
715            "type": "order",
716            "orders": [order],
717            "grouping": "na",
718        }
719 
720        logger.info(
721            f"place_order: coin={coin}, is_buy={is_buy}, size={size}, "
722            f"price={formatted_price}, order_type={order_type}, "
723            f"asset_idx={asset_idx}"
724        )
725 
726        # DEBUG: Log the full action structure for trigger orders
727        if trigger_px is not None:
728            import json
729            logger.info(f"TRIGGER ORDER ACTION: {json.dumps(action, indent=2)}")
730 
731        result = await self._exchange(action)
732        logger.info(f"place_order result: {result}")
733        return result
734 
735    async def cancel_order(self, coin: str, oid: int) -> dict:
736        """Cancel an order by oid."""
737        await self._ensure_meta()
738        asset_idx = await self._resolve_any_asset(coin)
739 
740        action = {
741            "type": "cancel",
742            "cancels": [{"a": asset_idx, "o": oid}],
743        }
744        return await self._exchange(action)
745 
746    async def cancel_by_cloid(self, coin: str, cloid: str) -> dict:
747        """Cancel an order by client order ID."""
748        await self._ensure_meta()
749        asset_idx = await self._resolve_any_asset(coin)
750 
751        action = {
752            "type": "cancelByCloid",
753            "cancels": [{"asset": asset_idx, "cloid": cloid}],
754        }
755        return await self._exchange(action)
756 
757    async def cancel_all(self, coin: Optional[str] = None) -> list:
758        """
759        Cancel all open orders, optionally filtered by coin.
760        Returns list of cancel results.
761        """
762        # No batch cancel action in HL — cancel individually
763        address = await self._get_address()
764        orders = await self.get_open_orders(address)
765 
766        if coin:
767            orders = [o for o in orders if o.get("coin") == coin]
768 
769        results = []
770        for order in orders:
771            try:
772                r = await self.cancel_order(
773                    order["coin"], order["oid"]
774                )
775                results.append(r)
776            except Exception as e:
777                results.append({"error": str(e), "oid": order.get("oid")})
778 
779        return results
780 
781    async def modify_order(
782        self,
783        oid: int,
784        coin: str,
785        is_buy: bool,
786        size: float,
787        price: float,
788        order_type: str = "limit",
789    ) -> dict:
790        """Modify an existing order."""
791        await self._ensure_meta()
792        asset_idx = await self._resolve_any_asset(coin)
793 
794        if order_type == "limit":
795            tif_spec = {"limit": {"tif": "Gtc"}}
796        elif order_type == "ioc":
797            tif_spec = {"limit": {"tif": "Ioc"}}
798        elif order_type == "alo":
799            tif_spec = {"limit": {"tif": "Alo"}}
800        else:
801            tif_spec = {"limit": {"tif": "Gtc"}}
802 
803        action = {
804            "type": "modify",
805            "oid": oid,
806            "order": {
807                "a": asset_idx,
808                "b": is_buy,
809                "p": self._format_price(price, coin=coin),
810                "s": self._format_size(coin, size),
811                "r": False,
812                "t": tif_spec,
813            },
814        }
815        return await self._exchange(action)
816 
817    # ── DEX Abstraction (HIP-3 builder perps collateral) ─────────────────
818 
819    _dex_abstraction_enabled: bool = False
820 
821    async def ensure_dex_abstraction(self) -> dict:
822        """Enable DEX abstraction so collateral auto-transfers to builder dexes.
823 
824        Required for trading HIP-3 builder perps (xyz:NVDA, xyz:TSLA, etc.).
825        Without this, the wallet has no collateral in builder dex clearinghouses
826        and all orders fail with "Insufficient margin".
827 
828        Checks current abstraction state first, then tries multiple methods:
829        1. agentSetAbstraction("u") - modern agent-signed approach
830        2. agentEnableDexAbstraction - legacy agent-signed approach
831        3. userSetAbstraction("unifiedAccount") - user-signed fallback
832 
833        Safe to call multiple times — Hyperliquid handles idempotency.
834        """
835        address = await self._get_address()
836 
837        # ALWAYS check current state first - don't trust cache
838        # The cache might be stale if the state was changed externally or if enable failed
839        try:
840            state_result = await self.get_user_abstraction_state(address)
841            # API may return string ("default") or dict ({"type": "default"})
842            if isinstance(state_result, str):
843                current_state = state_result
844            elif isinstance(state_result, dict):
845                current_state = state_result.get("type", state_result.get("state", "unknown"))
846            else:
847                current_state = "unknown"
848 
849            logger.info(f"DEX abstraction: current state for {address} = {current_state}")
850 
851            # If already in unifiedAccount mode, we're done
852            if current_state == "unifiedAccount":
853                logger.info("DEX abstraction: already enabled (unifiedAccount mode)")
854                self._dex_abstraction_enabled = True
855                return {"status": "already_enabled", "state": current_state}
856 
857            # If cache says enabled but state check shows otherwise, reset cache
858            if self._dex_abstraction_enabled and current_state != "unifiedAccount":
859                logger.warning(
860                    f"DEX abstraction: cache says enabled but state is '{current_state}'. "
861                    f"Resetting cache and retrying enable."
862                )
863                self._dex_abstraction_enabled = False
864 
865            # SDK comment says: "the account must be in 'default' mode to succeed"
866            if current_state not in ("default", "disabled"):
867                logger.warning(
868                    f"DEX abstraction: account in {current_state} mode. "
869                    f"Transitions may fail if not in 'default' mode."
870                )
871        except Exception as e:
872            logger.warning(f"DEX abstraction: failed to query current state: {e}")
873            # Continue anyway, state check is informational
874 
875        # Try Method 1: agentSetAbstraction with "u" (unified account)
876        logger.info(f"DEX abstraction: trying agentSetAbstraction(u) for {address}")
877        action = {
878            "type": "agentSetAbstraction",
879            "abstraction": "u",  # "u" = unified account (DEX abstraction enabled)
880        }
881 
882        try:
883            result = await self._exchange(action, vault_address=None)
884            logger.info(f"DEX abstraction: agentSetAbstraction result = {result}")
885            self._dex_abstraction_enabled = True
886            return result
887        except Exception as e:
888            err_str = str(e).lower()
889            logger.warning(f"DEX abstraction: agentSetAbstraction failed: {e}")
890 
891            # If it says "already" or "enabled", that's success
892            if "already" in err_str or "enabled" in err_str:
893                self._dex_abstraction_enabled = True
894                return {"status": "ok", "detail": str(e)}
895 
896        # Try Method 2: agentEnableDexAbstraction (legacy)
897        logger.info(f"DEX abstraction: trying agentEnableDexAbstraction for {address}")
898        action = {
899            "type": "agentEnableDexAbstraction",
900        }
901 
902        try:
903            result = await self._exchange(action, vault_address=None)
904            logger.info(f"DEX abstraction: agentEnableDexAbstraction result = {result}")
905            self._dex_abstraction_enabled = True
906            return result
907        except Exception as e:
908            err_str = str(e).lower()
909            logger.warning(f"DEX abstraction: agentEnableDexAbstraction failed: {e}")
910 
911            if "already" in err_str or "enabled" in err_str:
912                self._dex_abstraction_enabled = True
913                return {"status": "ok", "detail": str(e)}
914 
915        # Try Method 3: userSetAbstraction (user-signed, not agent-signed)
916        # This uses a different signing domain (HyperliquidSignTransaction vs Agent)
917        # SDK example shows this works when account is in "default" mode
918        logger.info(f"DEX abstraction: trying userSetAbstraction(unifiedAccount) for {address}")
919 
920        try:
921            result = await self._user_set_abstraction(address, "unifiedAccount")
922            logger.info(f"DEX abstraction: userSetAbstraction result = {result}")
923 
924            # Verify the state actually changed
925            try:
926                new_state_result = await self.get_user_abstraction_state(address)
927                if isinstance(new_state_result, str):
928                    new_state = new_state_result
929                elif isinstance(new_state_result, dict):
930                    new_state = new_state_result.get("type", new_state_result.get("state", "unknown"))
931                else:
932                    new_state = "unknown"
933                logger.info(f"DEX abstraction: state AFTER userSetAbstraction = {new_state}")
934 
935                if new_state == "unifiedAccount":
936                    logger.info("DEX abstraction: successfully enabled (verified)")
937                    self._dex_abstraction_enabled = True
938                    return result
939                else:
940                    logger.warning(
941                        f"DEX abstraction: userSetAbstraction returned success but state is still '{new_state}', not 'unifiedAccount'. "
942                        f"This may indicate the account has restrictions. Full result: {result}"
943                    )
944            except Exception as verify_err:
945                logger.warning(f"DEX abstraction: failed to verify state after userSetAbstraction: {verify_err}")
946 
947            self._dex_abstraction_enabled = True
948            return result
949        except Exception as e:
950            err_str = str(e).lower()
951            logger.error(f"DEX abstraction: userSetAbstraction failed: {e}")
952 
953            if "already" in err_str or "enabled" in err_str:
954                self._dex_abstraction_enabled = True
955                return {"status": "ok", "detail": str(e)}
956 
957        # All methods failed
958        raise RuntimeError(
959            f"Failed to enable DEX abstraction for {address}. "
960            f"Your account may have DEX abstraction manually disabled. "
961            f"Please enable it at app.hyperliquid.xyz:\n"
962            f"1. Go to Settings (top right)\n"
963            f"2. Find 'Disable HIP-3 Dex Abstraction' checkbox\n"
964            f"3. UNCHECK it to enable DEX abstraction\n"
965            f"4. Then retry your order"
966        )
967 
968    async def _user_set_abstraction(self, user: str, abstraction: str) -> dict:
969        """Set abstraction mode for user (user-signed action).
970 
971        Matches SDK's user_set_abstraction exactly.
972 
973        Args:
974            user: User wallet address
975            abstraction: "unifiedAccount", "portfolioMargin", or "disabled"
976 
977        Returns: API response
978        """
979        nonce = int(time.time() * 1000)
980 
981        # Action payload must include signatureChainId and hyperliquidChain
982        # These are required for all user-signed actions
983        action = {
984            "type": "userSetAbstraction",
985            "user": user.lower(),
986            "abstraction": abstraction,
987            "nonce": nonce,
988            "signatureChainId": "0xa4b1",  # 42161 in hex (Arbitrum mainnet)
989            "hyperliquidChain": "Mainnet",
990        }
991 
992        signature = await sign_user_set_abstraction(
993            user=user,
994            abstraction=abstraction,
995            nonce=nonce,
996        )
997 
998        payload = {
999            "action": action,
1000            "nonce": nonce,
1001            "signature": signature,
1002        }
1003        return await self._post("/exchange", payload)
1004 
1005    async def update_leverage(
1006        self, coin: str, leverage: int, is_cross: bool = True
1007    ) -> dict:
1008        """Set leverage for a perp."""
1009        await self._ensure_meta()
1010        # Builder perps need DEX abstraction
1011        logger.info(f"update_leverage DEX check: coin={coin}, has_colon={':' in coin}")
1012        if ":" in coin:
1013            logger.info(f"update_leverage: triggering DEX abstraction for builder perp {coin}")
1014            await self.ensure_dex_abstraction()
1015        else:
1016            logger.info(f"update_leverage: skipping DEX abstraction for {coin}")
1017        asset_idx = await self._resolve_asset(coin)
1018 
1019        action = {
1020            "type": "updateLeverage",
1021            "asset": asset_idx,
1022            "isCross": is_cross,
1023            "leverage": leverage,
1024        }
1025        return await self._exchange(action)
1026 
1027    async def market_open(
1028        self,
1029        coin: str,
1030        is_buy: bool,
1031        size: float,
1032        slippage: float = DEFAULT_SLIPPAGE,
1033        is_spot: bool = False,
1034    ) -> dict:
1035        """Convenience: open a position with an IoC market order."""
1036        return await self.place_order(
1037            coin=coin,
1038            is_buy=is_buy,
1039            size=size,
1040            price=None,  # triggers market order logic
1041            order_type="ioc",
1042            is_spot=is_spot,
1043        )
1044 
1045    async def market_close(
1046        self, coin: str, address: str, slippage: float = DEFAULT_SLIPPAGE
1047    ) -> dict:
1048        """Close entire perp position for a coin."""
1049        # Builder perps (HIP-3) have separate clearinghouse state per dex
1050        if ":" in coin:
1051            dex_name = coin.split(":")[0]
1052            state = await self._info("clearinghouseState", user=address, dex=dex_name)
1053        else:
1054            state = await self.get_account_state(address)
1055        positions = state.get("assetPositions", [])
1056 
1057        pos = None
1058        for p in positions:
1059            position = p.get("position", p)
1060            if position.get("coin") == coin:
1061                pos = position
1062                break
1063 
1064        if not pos:
1065            raise ValueError(f"No open position for {coin}")
1066 
1067        size = abs(float(pos["szi"]))
1068        is_buy = float(pos["szi"]) < 0  # Close short = buy, close long = sell
1069 
1070        return await self.place_order(
1071            coin=coin,
1072            is_buy=is_buy,
1073            size=size,
1074            price=None,
1075            order_type="ioc",
1076            reduce_only=True,
1077        )
1078 
1079    async def transfer_usd(
1080        self, amount: float, to_perp: bool = True
1081    ) -> dict:
1082        """
1083        Transfer USDC between spot and perp.
1084        Uses user-signed action (HyperliquidSignTransaction domain).
1085        """
1086        address = await self._get_address()
1087 
1088        # Query balances BEFORE transfer for verification
1089        try:
1090            perp_state_before = await self.get_account_state(address)
1091            spot_state_before = await self.get_spot_state(address)
1092            perp_value_before = float(perp_state_before.get("marginSummary", {}).get("accountValue", 0))
1093            spot_balances_before = spot_state_before.get("balances", [])
1094            logger.info(
1095                f"transfer_usd: BEFORE transfer - "
1096                f"perp_value=${perp_value_before:.2f}, "
1097                f"spot_balances={spot_balances_before}"
1098            )
1099        except Exception as e:
1100            logger.warning(f"transfer_usd: failed to query balances before transfer: {e}")
1101 
1102        nonce = int(time.time() * 1000)
1103 
1104        action = {
1105            "type": "usdClassTransfer",
1106            "amount": str(amount),
1107            "toPerp": to_perp,
1108            "nonce": nonce,
1109            "signatureChainId": "0xa4b1",  # 42161 in hex (Arbitrum mainnet)
1110            "hyperliquidChain": "Mainnet",
1111        }
1112 
1113        types = {
1114            "HyperliquidTransaction:UsdClassTransfer": [
1115                {"name": "hyperliquidChain", "type": "string"},
1116                {"name": "amount", "type": "string"},
1117                {"name": "toPerp", "type": "bool"},
1118                {"name": "nonce", "type": "uint64"},
1119            ]
1120        }
1121 
1122        signature = await sign_user_action(
1123            action={
1124                "hyperliquidChain": "Mainnet",
1125                "amount": str(amount),
1126                "toPerp": to_perp,
1127                "nonce": nonce,
1128            },
1129            types=types,
1130            primary_type="HyperliquidTransaction:UsdClassTransfer",
1131        )
1132 
1133        payload = {
1134            "action": action,
1135            "nonce": nonce,
1136            "signature": signature,
1137        }
1138 
1139        logger.info(f"transfer_usd: submitting ${amount} transfer ({'spot→perp' if to_perp else 'perp→spot'})")
1140 
1141        try:
1142            result = await self._post("/exchange", payload)
1143            logger.info(f"transfer_usd: API response SUCCESS = {result}")
1144        except Exception as api_error:
1145            logger.error(f"transfer_usd: API call FAILED: {api_error}", exc_info=True)
1146            # Re-raise so caller sees the error
1147            raise
1148 
1149        # Query balances AFTER transfer for verification
1150        try:
1151            perp_state_after = await self.get_account_state(address)
1152            spot_state_after = await self.get_spot_state(address)
1153            perp_value_after = float(perp_state_after.get("marginSummary", {}).get("accountValue", 0))
1154            spot_balances_after = spot_state_after.get("balances", [])
1155            logger.info(
1156                f"transfer_usd: AFTER transfer - "
1157                f"perp_value=${perp_value_after:.2f}, "
1158                f"spot_balances={spot_balances_after}"
1159            )
1160        except Exception as e:
1161            logger.warning(f"transfer_usd: failed to query balances after transfer: {e}")
1162 
1163        return result
1164 
1165    async def withdraw_from_bridge(
1166        self, amount: float, destination: Optional[str] = None
1167    ) -> dict:
1168        """
1169        Withdraw USDC from Hyperliquid to an Arbitrum wallet (L1 bridge withdrawal).
1170 
1171        Fee: 1 USDC (deducted by Hyperliquid). Processing: ~5 minutes.
1172 
1173        Args:
1174            amount: USDC amount to withdraw
1175            destination: Target wallet address (defaults to agent's own wallet)
1176        """
1177        if not destination:
1178            destination = await self._get_address()
1179 
1180        nonce = int(time.time() * 1000)
1181 
1182        action = {
1183            "type": "withdraw3",
1184            "hyperliquidChain": "Mainnet",
1185            "signatureChainId": "0xa4b1",  # 42161 in hex (Arbitrum mainnet)
1186            "destination": destination,
1187            "amount": str(amount),
1188            "time": nonce,
1189        }
1190 
1191        types = {
1192            "HyperliquidTransaction:Withdraw": [
1193                {"name": "hyperliquidChain", "type": "string"},
1194                {"name": "destination", "type": "string"},
1195                {"name": "amount", "type": "string"},
1196                {"name": "time", "type": "uint64"},
1197            ]
1198        }
1199 
1200        signature = await sign_user_action(
1201            action={
1202                "hyperliquidChain": "Mainnet",
1203                "destination": destination,
1204                "amount": str(amount),
1205                "time": nonce,
1206            },
1207            types=types,
1208            primary_type="HyperliquidTransaction:Withdraw",
1209        )
1210 
1211        payload = {
1212            "action": action,
1213            "nonce": nonce,
1214            "signature": signature,
1215        }
1216        return await self._post("/exchange", payload)
1217 
1218    async def deposit_usdc(self, amount: float) -> dict:
1219        """
1220        Deposit USDC from agent's Arbitrum wallet into Hyperliquid.
1221 
1222        Sends an ERC-20 transfer of USDC to the Hyperliquid bridge contract.
1223        Minimum deposit: 5 USDC.
1224 
1225        Args:
1226            amount: USDC amount to deposit (minimum 5)
1227        """
1228        from eth_utils import keccak
1229        from core.wallet_runtime import wallet_request as _wallet_request, is_fly_machine as _is_fly_machine
1230        if not _is_fly_machine():
1231            raise RuntimeError("Not running on a Fly Machine — wallet unavailable")
1232 
1233        if amount < MIN_DEPOSIT_USDC:
1234            raise ValueError(f"Minimum deposit is {MIN_DEPOSIT_USDC} USDC")
1235 
1236        amount_base = int(amount * (10 ** USDC_DECIMALS))
1237 
1238        # Step 1: ERC-20 approve(bridge, amount)
1239        approve_selector = keccak(b"approve(address,uint256)")[:4]
1240        bridge_bytes = bytes.fromhex(BRIDGE_ADDRESS.replace("0x", "")).rjust(32, b"\x00")
1241        amount_bytes = amount_base.to_bytes(32, "big")
1242        approve_data = "0x" + (approve_selector + bridge_bytes + amount_bytes).hex()
1243 
1244        logger.info(f"HL deposit: approve TX (amount_base={amount_base})")
1245        approve_result = await _wallet_request("POST", "/agent/transfer", {
1246            "to": USDC_ADDRESS,
1247            "amount": "0",
1248            "data": approve_data,
1249            "chain_id": ARBITRUM_CHAIN_ID,
1250        })
1251        approve_tx = approve_result.get("tx_hash", approve_result.get("hash", "unknown"))
1252        logger.info(f"HL deposit: approve TX = {approve_tx}")
1253 
1254        # Step 2: ERC-20 transfer(bridge, amount)
1255        transfer_selector = keccak(b"transfer(address,uint256)")[:4]
1256        transfer_data = "0x" + (transfer_selector + bridge_bytes + amount_bytes).hex()
1257 
1258        logger.info(f"HL deposit: transfer TX to bridge {BRIDGE_ADDRESS}")
1259        transfer_result = await _wallet_request("POST", "/agent/transfer", {
1260            "to": USDC_ADDRESS,
1261            "amount": "0",
1262            "data": transfer_data,
1263            "chain_id": ARBITRUM_CHAIN_ID,
1264        })
1265        transfer_tx = transfer_result.get("tx_hash", transfer_result.get("hash", "unknown"))
1266        logger.info(f"HL deposit: transfer TX = {transfer_tx}")
1267 
1268        return {
1269            "approve_tx_hash": approve_tx,
1270            "transfer_tx_hash": transfer_tx,
1271            "amount_deposited": amount,
1272            "amount_base_units": amount_base,
1273            "bridge_contract": BRIDGE_ADDRESS,
1274            "chain_id": ARBITRUM_CHAIN_ID,
1275        }
1276 
1277    # ── Address helper ───────────────────────────────────────────────────
1278 
1279    _cached_address: Optional[str] = None
1280 
1281    async def _get_address(self) -> str:
1282        """Get the agent's EVM address from wallet service (cached)."""
1283        if self._cached_address:
1284            return self._cached_address
1285 
1286        from core.wallet_runtime import wallet_request as _wallet_request, is_fly_machine as _is_fly_machine
1287        if not _is_fly_machine():
1288            raise RuntimeError("Not running on Fly — wallet unavailable")
1289 
1290        data = await _wallet_request("GET", "/agent/wallet")
1291        wallets = data if isinstance(data, list) else data.get("wallets", [])
1292        for w in wallets:
1293            if w.get("chain_type") == "ethereum":
1294                self._cached_address = w["wallet_address"]
1295                return self._cached_address
1296 
1297        raise RuntimeError("No ethereum wallet found")
1298