1"""
2Hyperliquid Trading Tools — BaseTool subclasses for agent use.
3 
4Info tools (9): hl_account, hl_balances, hl_total_balance, hl_open_orders, hl_market,
5                hl_orderbook, hl_fills, hl_candles, hl_funding
6Exchange tools (10): hl_order, hl_spot_order, hl_cancel, hl_cancel_all,
7                     hl_modify, hl_leverage, hl_transfer_usd, hl_withdraw, hl_deposit,
8                     hl_set_abstraction
9"""
10 
11import time
12import math
13import logging
14 
15from core.tool import BaseTool, ToolContext, ToolResult
16from .client import HyperliquidClient
17 
18logger = logging.getLogger(__name__)
19 
20# Module-level shared client instance
21_client: HyperliquidClient = None
22 
23 
24def _get_client() -> HyperliquidClient:
25    global _client
26    if _client is None:
27        _client = HyperliquidClient()
28    return _client
29 
30 
31async def _get_address() -> str:
32    """Get the agent's EVM address."""
33    return await _get_client()._get_address()
34 
35 
36def _coerce_float(value, field_name: str):
37    """Best-effort numeric coercion for tolerant tool inputs."""
38    if isinstance(value, bool) or value is None:
39        raise ValueError(f"'{field_name}' must be a number")
40    if isinstance(value, (int, float)):
41        f = float(value)
42    elif isinstance(value, str):
43        s = value.strip()
44        if not s:
45            raise ValueError(f"'{field_name}' must be a number")
46        try:
47            f = float(s)
48        except ValueError:
49            raise ValueError(f"'{field_name}' must be a number")
50    else:
51        raise ValueError(f"'{field_name}' must be a number")
52 
53    if not math.isfinite(f):
54        raise ValueError(f"'{field_name}' must be a finite number")
55    return f
56 
57 
58def _coerce_int(value, field_name: str):
59    """Best-effort integer coercion with strict decimal rejection."""
60    if isinstance(value, bool) or value is None:
61        raise ValueError(f"'{field_name}' must be an integer")
62    if isinstance(value, int):
63        return value
64    if isinstance(value, float):
65        if value.is_integer() and math.isfinite(value):
66            return int(value)
67        raise ValueError(f"'{field_name}' must be an integer")
68    if isinstance(value, str):
69        s = value.strip()
70        if not s:
71            raise ValueError(f"'{field_name}' must be an integer")
72        if s.lstrip("+-").isdigit():
73            return int(s)
74        # allow "5.0" but reject "5.1"
75        try:
76            f = float(s)
77            if math.isfinite(f) and f.is_integer():
78                return int(f)
79        except ValueError:
80            pass
81    raise ValueError(f"'{field_name}' must be an integer")
82 
83 
84def _coerce_bool(value, field_name: str):
85    """Best-effort boolean coercion."""
86    if isinstance(value, bool):
87        return value
88    if isinstance(value, (int, float)) and value in (0, 1):
89        return bool(value)
90    if isinstance(value, str):
91        lowered = value.strip().lower()
92        if lowered in {"true", "1", "yes", "y", "on"}:
93            return True
94        if lowered in {"false", "0", "no", "n", "off"}:
95            return False
96    raise ValueError(f"'{field_name}' must be a boolean")
97 
98 
99# Accepted aliases for the `side` parameter across all Hyperliquid order tools.
100# Some models emit Hyperliquid's L1 wire codes (B/A) or natural-language
101# directions (long/short, 做多/做空) instead of the documented buy/sell.
102# Normalizing here is safer than silently falling back to sell when the input
103# doesn't match the literal "buy" — accidental direction reversal on a
104# leveraged order is the worst failure mode we can produce.
105_SIDE_BUY_ALIASES = frozenset({
106    "buy", "b", "bid", "long", "l", "做多",
107    "1", "true",  # some models stringify booleans when unsure
108})
109_SIDE_SELL_ALIASES = frozenset({
110    "sell", "s", "a", "ask", "short", "做空",
111    "0", "false",
112})
113 
114 
115def _coerce_side(value, field_name: str = "side") -> bool:
116    """Normalize a `side` parameter into a boolean ``is_buy``.
117 
118    Accepts the documented ``buy``/``sell`` plus common aliases that models
119    reach for when they guess:
120 
121      - Buy family:  buy, B, bid, long, L, 做多, 1, true
122      - Sell family: sell, S, A, ask, short, 做空, 0, false
123 
124    Also accepts a real ``bool`` (True → buy, False → sell) — some tool
125    runtimes pre-coerce boolean-looking strings.
126 
127    Raises ``ValueError`` for anything else. NEVER falls back to a default —
128    on a leveraged order, guessing the wrong direction is catastrophic.
129    """
130    # Pre-coerced boolean from the tool runtime or an explicit caller.
131    if isinstance(value, bool):
132        return value
133 
134    if value is None:
135        raise ValueError(f"'{field_name}' is required (one of: buy, sell)")
136 
137    if isinstance(value, (int, float)) and not isinstance(value, bool):
138        if value == 1:
139            return True
140        if value == 0:
141            return False
142        raise ValueError(
143            f"'{field_name}' numeric must be 1 (buy) or 0 (sell); got {value!r}"
144        )
145 
146    if isinstance(value, str):
147        s = value.strip().lower()
148        if not s:
149            raise ValueError(f"'{field_name}' is required (one of: buy, sell)")
150        if s in _SIDE_BUY_ALIASES:
151            return True
152        if s in _SIDE_SELL_ALIASES:
153            return False
154        raise ValueError(
155            f"'{field_name}' must be one of: buy/sell (also accepted: "
156            f"B/A, long/short, 做多/做空); got {value!r}"
157        )
158 
159    raise ValueError(
160        f"'{field_name}' must be a string like 'buy' or 'sell'; "
161        f"got {type(value).__name__}"
162    )
163 
164 
165# ── Info Tools ───────────────────────────────────────────────────────────────
166 
167 
168class HLAccountTool(BaseTool):
169    """Get perp account state — positions, margin, PnL."""
170 
171    @property
172    def name(self) -> str:
173        return "hl_account"
174 
175    @property
176    def description(self) -> str:
177        return """Get Hyperliquid perpetual account state: open positions, margin balances, unrealized PnL, and account value.
178 
179**⚠️ WARNING: This tool shows PERP account only! With unified account mode (default), your funds may be in SPOT.**
180**🎯 Use `hl_total_balance` instead to check if you have funds to place orders!**
181 
182**Understanding account modes:**
183- **Unified Account (default)**: Funds are shared across spot/perp. This tool may show $0 even if you have USDC in spot!
184- **Disabled mode**: Spot and perp are separate. This tool accurately shows perp margin.
185 
186**When to use this tool:**
187- To check open positions and their PnL
188- To see margin usage on perp side
189- To monitor position sizes and liquidation risk
190- NOT to check if you have funds to place orders (use `hl_total_balance` for that!)
191 
192**🚨 CRITICAL for RWA/Stock Perps (xyz:NVDA, xyz:TSLA, etc.):**
193- ✅ Check MAIN account (`hl_account()`) for positions, NOT for available funds
194- ❌ DO NOT check xyz dex (`hl_account(dex="xyz")`) before placing orders - it shows $0 until you have positions!
195- ✅ xyz dex showing $0 is NORMAL and EXPECTED before your first builder perp order
196- ✅ DEX abstraction auto-transfers funds from main → xyz dex when you place orders
197- ✅ Only check xyz dex AFTER placing orders to verify positions opened
198 
199Parameters:
200- dex: (optional) Builder dex name (e.g. "xyz"). Omit for main crypto perps account.
201 
202Returns: marginSummary (accountValue, totalMarginUsed, totalNtlPos), assetPositions array"""
203 
204    @property
205    def parameters(self) -> dict:
206        return {
207            "type": "object",
208            "properties": {
209                "dex": {
210                    "type": "string",
211                    "description": "Builder dex name (e.g. 'xyz') for RWA/stock perps. Omit for default crypto perps.",
212                },
213            },
214        }
215 
216    async def execute(self, ctx: ToolContext, dex: str = "", **kwargs) -> ToolResult:
217        try:
218            client = _get_client()
219            address = await _get_address()
220            data = await client.get_account_state(address, dex=dex if dex else None)
221            return ToolResult(success=True, output=data)
222        except Exception as e:
223            return ToolResult(success=False, error=str(e))
224 
225 
226class HLBalancesTool(BaseTool):
227    """Get spot token balances (USDC, tokens)."""
228 
229    @property
230    def name(self) -> str:
231        return "hl_balances"
232 
233    @property
234    def description(self) -> str:
235        return """Get Hyperliquid spot balances: USDC and all token holdings.
236 
237**⚠️ WARNING: This tool shows SPOT account only!**
238**🎯 Use `hl_total_balance` to check total available funds for trading!**
239 
240**Understanding account modes:**
241- **Unified Account (default)**: SPOT USDC is shared collateral for all trading (spot/perp/builder-dexes)
242- **Disabled mode**: Spot and perp are separate, you may need to transfer between them
243 
244**When to use this tool:**
245- To check spot token holdings (e.g. PURR, HYPE, etc.)
246- To see USDC available for spot trading
247- NOT as the sole indicator of available margin (use `hl_total_balance` for that!)
248 
249Returns: balances array with coin, hold, total for each token"""
250 
251    @property
252    def parameters(self) -> dict:
253        return {"type": "object", "properties": {}}
254 
255    async def execute(self, ctx: ToolContext, **kwargs) -> ToolResult:
256        try:
257            client = _get_client()
258            address = await _get_address()
259            data = await client.get_spot_state(address)
260            return ToolResult(success=True, output=data)
261        except Exception as e:
262            return ToolResult(success=False, error=str(e))
263 
264 
265class HLTotalBalanceTool(BaseTool):
266    """Get total available balance (accounts for unified account mode)."""
267 
268    @property
269    def name(self) -> str:
270        return "hl_total_balance"
271 
272    @property
273    def description(self) -> str:
274        return """Get total available balance across all Hyperliquid accounts.
275 
276**🎯 Use this to check if you have enough funds to place orders!**
277 
278This tool intelligently checks the RIGHT account based on your abstraction mode:
279- **Unified Account Mode (default)**: Returns SPOT balance (shared collateral for all trading)
280- **Disabled Mode**: Returns PERP balance separately
281 
282**Why use this instead of hl_account or hl_balances?**
283- hl_account shows perp only ($0 if funds are in spot with unified account)
284- hl_balances shows spot only
285- hl_total_balance shows ACTUAL available margin regardless of mode
286 
287Returns:
288- totalAvailable: Total USDC available for trading
289- abstractionMode: Current mode (unifiedAccount, disabled, etc.)
290- breakdown: Where the funds actually are (spot/perp)"""
291 
292    @property
293    def parameters(self) -> dict:
294        return {"type": "object", "properties": {}}
295 
296    async def execute(self, ctx: ToolContext, **kwargs) -> ToolResult:
297        try:
298            client = _get_client()
299            address = await _get_address()
300 
301            # Check abstraction mode
302            try:
303                abstraction_result = await client.get_user_abstraction_state(address)
304                if isinstance(abstraction_result, str):
305                    abstraction_mode = abstraction_result
306                elif isinstance(abstraction_result, dict):
307                    abstraction_mode = abstraction_result.get("type", abstraction_result.get("state", "default"))
308                else:
309                    abstraction_mode = "default"
310            except Exception:
311                abstraction_mode = "default"
312 
313            # Get spot and perp balances
314            spot_state = await client.get_spot_state(address)
315            perp_state = await client.get_account_state(address)
316 
317            # Calculate spot USDC
318            spot_usdc = 0.0
319            for bal in spot_state.get("balances", []):
320                if bal.get("coin") == "USDC":
321                    spot_usdc = float(bal.get("total", 0))
322                    break
323 
324            # Calculate perp margin
325            perp_margin = perp_state.get("marginSummary", {})
326            perp_value = float(perp_margin.get("accountValue", 0))
327            perp_used = float(perp_margin.get("totalMarginUsed", 0))
328            perp_available = perp_value - perp_used
329 
330            # Determine total available based on mode
331            if abstraction_mode == "unifiedAccount":
332                # Unified mode: all USDC is shared collateral
333                total_available = spot_usdc + perp_available
334                note = "Unified account: funds are shared across spot/perp/builder-dexes"
335            else:
336                # Separate mode: perp and spot are independent
337                total_available = perp_available
338                note = "Disabled mode: perp and spot are separate"
339 
340            return ToolResult(
341                success=True,
342                output={
343                    "totalAvailable": round(total_available, 2),
344                    "abstractionMode": abstraction_mode,
345                    "note": note,
346                    "breakdown": {
347                        "spot": {
348                            "usdc": round(spot_usdc, 2),
349                        },
350                        "perp": {
351                            "accountValue": round(perp_value, 2),
352                            "marginUsed": round(perp_used, 2),
353                            "available": round(perp_available, 2),
354                        },
355                    },
356                },
357            )
358        except Exception as e:
359            return ToolResult(success=False, error=str(e))
360 
361 
362class HLOpenOrdersTool(BaseTool):
363    """Get all open orders (perp + spot)."""
364 
365    @property
366    def name(self) -> str:
367        return "hl_open_orders"
368 
369    @property
370    def description(self) -> str:
371        return """Get all open orders on Hyperliquid (both perp and spot).
372 
373Use this to see pending limit orders, check order status, or find order IDs for cancellation.
374 
375Returns: array of orders with coin, side, sz, limitPx, oid, timestamp"""
376 
377    @property
378    def parameters(self) -> dict:
379        return {"type": "object", "properties": {}}
380 
381    async def execute(self, ctx: ToolContext, **kwargs) -> ToolResult:
382        try:
383            client = _get_client()
384            address = await _get_address()
385            data = await client.get_open_orders(address)
386            return ToolResult(success=True, output=data)
387        except Exception as e:
388            return ToolResult(success=False, error=str(e))
389 
390 
391class HLMarketTool(BaseTool):
392    """Get market info — mid prices, metadata."""
393 
394    @property
395    def name(self) -> str:
396        return "hl_market"
397 
398    @property
399    def description(self) -> str:
400        return """Get Hyperliquid market info: current mid prices and asset metadata.
401 
402If coin is specified, returns targeted info for that asset. Otherwise returns all mid prices.
403 
404**Crypto perps**: Use plain names — "BTC", "ETH", "SOL", etc.
405**RWA / stocks / commodities**: Use "xyz:TICKER" format — "xyz:NVDA", "xyz:TSLA", "xyz:AAPL", "xyz:GOLD", "xyz:SILVER", etc.
406Use dex="xyz" to list all available RWA/stock perps.
407 
408Parameters:
409- coin: (optional) Specific asset like "BTC", "ETH", "xyz:NVDA". Omit for all crypto perps.
410- dex: (optional) Builder dex name like "xyz" to list all assets on that dex (stocks/RWAs).
411 
412Returns: mid prices, and if coin specified: maxLeverage, szDecimals"""
413 
414    @property
415    def parameters(self) -> dict:
416        return {
417            "type": "object",
418            "properties": {
419                "coin": {
420                    "type": "string",
421                    "description": "Asset name (e.g. 'BTC', 'xyz:NVDA'). Omit for all.",
422                },
423                "dex": {
424                    "type": "string",
425                    "description": "Builder dex name (e.g. 'xyz') to list all RWA/stock perps on that dex.",
426                },
427            },
428        }
429 
430    async def execute(self, ctx: ToolContext, coin: str = "", dex: str = "", **kwargs) -> ToolResult:
431        try:
432            client = _get_client()
433 
434            # List all assets on a builder dex (e.g. dex="xyz" for RWA/stocks)
435            if dex and not coin:
436                await client._ensure_meta()
437                await client._ensure_builder_dex(dex)
438                mids = await client.get_all_mids(dex=dex)
439                return ToolResult(success=True, output=mids)
440 
441            if coin and ":" in coin:
442                # Builder perp (e.g. "xyz:NVDA")
443                dex_name = coin.split(":", 1)[0]
444                await client._ensure_meta()
445                await client._ensure_builder_dex(dex_name)
446                mids = await client.get_all_mids(dex=dex_name)
447                # allMids keys are prefixed: "xyz:NVDA"
448                mid = mids.get(coin)
449                if mid is None:
450                    return ToolResult(
451                        success=False,
452                        error=f"No mid price for {coin}. Available: {list(mids.keys())[:10]}",
453                    )
454                meta = client._builder_meta.get(dex_name, {})
455                universe = meta.get("universe", [])
456                asset_info = {}
457                for asset in universe:
458                    # meta returns names like "xyz:NVDA" (prefixed)
459                    if asset["name"] == coin or asset["name"] == coin.split(":", 1)[1]:
460                        asset_info = asset
461                        break
462                return ToolResult(
463                    success=True,
464                    output={
465                        "coin": coin,
466                        "dex": dex_name,
467                        "midPrice": mid,
468                        "maxLeverage": asset_info.get("maxLeverage"),
469                        "szDecimals": asset_info.get("szDecimals"),
470                    },
471                )
472 
473            mids = await client.get_all_mids()
474 
475            if coin:
476                mid = mids.get(coin)
477                # Case-insensitive fallback (e.g. "ai16z" -> "AI16Z")
478                if mid is None:
479                    coin_upper = coin.upper()
480                    for key, val in mids.items():
481                        if key.upper() == coin_upper:
482                            coin = key  # Use the canonical name
483                            mid = val
484                            break
485                if mid is None:
486                    return ToolResult(
487                        success=False,
488                        error=f"No data for {coin}. If this is a stock/RWA, use 'xyz:{coin}' format (e.g. 'xyz:NVDA'). Use hl_market(dex=\"xyz\") to list all available RWA/stock perps.",
489                    )
490                await client._ensure_meta()
491                meta = client._meta or {}
492                universe = meta.get("universe", [])
493                asset_info = {}
494                for asset in universe:
495                    if asset["name"] == coin:
496                        asset_info = asset
497                        break
498                return ToolResult(
499                    success=True,
500                    output={
501                        "coin": coin,
502                        "midPrice": mid,
503                        "maxLeverage": asset_info.get("maxLeverage"),
504                        "szDecimals": asset_info.get("szDecimals"),
505                    },
506                )
507 
508            return ToolResult(success=True, output=mids)
509        except Exception as e:
510            return ToolResult(success=False, error=str(e))
511 
512class HLOrderbookTool(BaseTool):
513    """Get L2 orderbook snapshot."""
514 
515    @property
516    def name(self) -> str:
517        return "hl_orderbook"
518 
519    @property
520    def description(self) -> str:
521        return """Get the L2 orderbook for a Hyperliquid asset.
522 
523Shows current bid/ask levels with sizes. Useful for checking liquidity and spread.
524Supports builder perps via "dex:COIN" format (e.g. "xyz:NVDA").
525 
526Parameters:
527- coin: Asset name (required, e.g. "BTC", "ETH", "xyz:NVDA")
528 
529Returns: levels array with [[price, size], ...] for bids and asks"""
530 
531    @property
532    def parameters(self) -> dict:
533        return {
534            "type": "object",
535            "properties": {
536                "coin": {
537                    "type": "string",
538                    "description": "Asset name (e.g. 'BTC', 'xyz:NVDA')",
539                },
540            },
541            "required": ["coin"],
542        }
543 
544    async def execute(self, ctx: ToolContext, coin: str = "", **kwargs) -> ToolResult:
545        if not coin:
546            return ToolResult(success=False, error="'coin' is required")
547        try:
548            client = _get_client()
549            data = await client.get_l2_book(coin)
550            return ToolResult(success=True, output=data)
551        except Exception as e:
552            return ToolResult(success=False, error=str(e))
553 
554 
555class HLFillsTool(BaseTool):
556    """Get recent trade fills."""
557 
558    @property
559    def name(self) -> str:
560        return "hl_fills"
561 
562    @property
563    def description(self) -> str:
564        return """Get recent trade fills (executed orders) for this wallet.
565 
566Use this to verify if orders were filled, check execution prices, or review trade history.
567 
568Parameters:
569- limit: Number of fills to return (default: 20)
570 
571Returns: array of fills with coin, side, px, sz, fee, time"""
572 
573    @property
574    def parameters(self) -> dict:
575        return {
576            "type": "object",
577            "properties": {
578                "limit": {
579                    "type": "integer",
580                    "description": "Number of fills (default: 20)",
581                },
582            },
583        }
584 
585    async def execute(self, ctx: ToolContext, limit: int = 20, **kwargs) -> ToolResult:
586        try:
587            client = _get_client()
588            address = await _get_address()
589            fills = await client.get_user_fills(address)
590            return ToolResult(success=True, output=fills[:limit])
591        except Exception as e:
592            return ToolResult(success=False, error=str(e))
593 
594 
595class HLCandlesTool(BaseTool):
596    """Get OHLCV candlestick data."""
597 
598    @property
599    def name(self) -> str:
600        return "hl_candles"
601 
602    @property
603    def description(self) -> str:
604        return """Get OHLCV candlestick data for a Hyperliquid asset.
605 
606Use this for price analysis, charting, and identifying trends.
607 
608Parameters:
609- coin: Asset name (required, e.g. "BTC")
610- interval: Candle interval (default: "1h"). Options: 1m, 5m, 15m, 1h, 4h, 1d
611- lookback: Hours of history to fetch (default: 24)
612 
613Returns: array of candles with t (time), o, h, l, c (prices), v (volume)"""
614 
615    @property
616    def parameters(self) -> dict:
617        return {
618            "type": "object",
619            "properties": {
620                "coin": {
621                    "type": "string",
622                    "description": "Asset name (e.g. 'BTC')",
623                },
624                "interval": {
625                    "type": "string",
626                    "description": "Candle interval: 1m, 5m, 15m, 1h, 4h, 1d (default: 1h)",
627                },
628                "lookback": {
629                    "type": "integer",
630                    "description": "Hours of history (default: 24)",
631                },
632            },
633            "required": ["coin"],
634        }
635 
636    async def execute(
637        self,
638        ctx: ToolContext,
639        coin: str = "",
640        interval: str = "1h",
641        lookback: int = 24,
642        **kwargs,
643    ) -> ToolResult:
644        if not coin:
645            return ToolResult(success=False, error="'coin' is required")
646        try:
647            client = _get_client()
648            end = int(time.time() * 1000)
649            start = end - (lookback * 3600 * 1000)
650            data = await client.get_candles(coin, interval, start, end)
651            return ToolResult(success=True, output=data)
652        except Exception as e:
653            return ToolResult(success=False, error=str(e))
654 
655 
656class HLFundingTool(BaseTool):
657    """Get funding rate info."""
658 
659    @property
660    def name(self) -> str:
661        return "hl_funding"
662 
663    @property
664    def description(self) -> str:
665        return """Get funding rate information for Hyperliquid perps.
666 
667Shows predicted next funding and recent historical funding rates. Positive = longs pay shorts.
668 
669Parameters:
670- coin: (optional) Specific asset. Omit for all predicted fundings.
671- lookback: Hours of funding history (default: 24, only used if coin specified)
672 
673Returns: predicted funding rates, and if coin specified: historical rates"""
674 
675    @property
676    def parameters(self) -> dict:
677        return {
678            "type": "object",
679            "properties": {
680                "coin": {
681                    "type": "string",
682                    "description": "Asset name (e.g. 'BTC'). Omit for all.",
683                },
684                "lookback": {
685                    "type": "integer",
686                    "description": "Hours of history (default: 24)",
687                },
688            },
689        }
690 
691    async def execute(
692        self, ctx: ToolContext, coin: str = "", lookback: int = 24, **kwargs
693    ) -> ToolResult:
694        try:
695            client = _get_client()
696            predicted = await client.get_predicted_fundings()
697 
698            if coin:
699                # predictedFundings returns [[coin, [[venue, data], ...]], ...]
700                coin_predicted = None
701                for entry in predicted:
702                    if isinstance(entry, list) and len(entry) >= 2 and entry[0] == coin:
703                        # entry[1] is [[venue, {fundingRate, ...}], ...]
704                        coin_predicted = {
705                            venue: data
706                            for venue, data in entry[1]
707                        }
708                        break
709 
710                # Fetch historical
711                start = int((time.time() - lookback * 3600) * 1000)
712                history = await client.get_funding_history(coin, start)
713 
714                return ToolResult(
715                    success=True,
716                    output={
717                        "coin": coin,
718                        "predicted": coin_predicted or "No predicted funding found",
719                        "history": history,
720                    },
721                )
722 
723            # Summarize all predicted fundings into a readable dict
724            summary = {}
725            for entry in predicted:
726                if isinstance(entry, list) and len(entry) >= 2:
727                    name = entry[0]
728                    venues = entry[1]
729                    # Pick HlPerp rate if available, otherwise first venue
730                    for venue, data in venues:
731                        if venue == "HlPerp":
732                            summary[name] = data.get("fundingRate", "N/A")
733                            break
734                    else:
735                        if venues:
736                            summary[name] = venues[0][1].get("fundingRate", "N/A")
737 
738            return ToolResult(success=True, output={"predicted": summary})
739        except Exception as e:
740            return ToolResult(success=False, error=str(e))
741 
742 
743# ── Exchange Tools ───────────────────────────────────────────────────────────
744 
745 
746class HLOrderTool(BaseTool):
747    """Place a perp limit or market order."""
748 
749    @property
750    def name(self) -> str:
751        return "hl_order"
752 
753    @property
754    def description(self) -> str:
755        return """Place a perpetual futures order on Hyperliquid.
756 
757**Crypto**: Use plain names — "BTC", "ETH", "SOL"
758**Stocks/RWA**: Use "xyz:TICKER" — "xyz:NVDA", "xyz:TSLA", "xyz:AAPL", "xyz:GOLD"
759 
760Parameters:
761- coin: Asset name (required, e.g. "BTC", "ETH", "xyz:NVDA")
762- side: Direction. **Use "buy" or "sell"** — these are the documented values.
763        Aliases are also accepted as a safety net (B/A, long/short, 做多/做空)
764        but "buy"/"sell" is strongly preferred for clarity and auditability.
765        An unrecognized value will FAIL the call rather than default, to
766        prevent accidental direction reversal on leveraged orders.
767- size: Order size in base asset (required, e.g. 0.01 for 0.01 BTC)
768- price: Limit price (optional — omit for market order)
769- order_type: "limit" (GTC, default), "ioc" (fill-or-kill), "alo" (post-only)
770- reduce_only: If true, only reduces existing position (default: false)
771 
772Market orders (no price): Uses IoC at mid price +/- 3% slippage.
773 
774Returns: order status with oid, filled size, price"""
775 
776    @property
777    def parameters(self) -> dict:
778        return {
779            "type": "object",
780            "properties": {
781                "coin": {
782                    "type": "string",
783                    "description": "Asset name (e.g. 'BTC', 'xyz:NVDA')",
784                },
785                "side": {
786                    "type": "string",
787                    "enum": ["buy", "sell"],
788                    "description": "Order side",
789                },
790                "size": {
791                    "type": "number",
792                    "description": "Order size in base asset",
793                },
794                "price": {
795                    "type": "number",
796                    "description": "Limit price (omit for market order)",
797                },
798                "order_type": {
799                    "type": "string",
800                    "enum": ["limit", "ioc", "alo"],
801                    "description": "Order type (default: limit)",
802                },
803                "reduce_only": {
804                    "type": "boolean",
805                    "description": "Reduce-only (default: false)",
806                },
807            },
808            "required": ["coin", "side", "size"],
809        }
810 
811    async def execute(
812        self,
813        ctx: ToolContext,
814        coin: str = "",
815        side: str = "",
816        size: float = 0,
817        price: float = None,
818        order_type: str = "limit",
819        reduce_only: bool = False,
820        **kwargs,
821    ) -> ToolResult:
822        try:
823            if not coin or not side:
824                return ToolResult(success=False, error="'coin' and 'side' are required")
825 
826            size = _coerce_float(size, "size")
827            if size <= 0:
828                return ToolResult(success=False, error="'size' must be positive")
829 
830            if price is not None:
831                price = _coerce_float(price, "price")
832                if price <= 0:
833                    return ToolResult(success=False, error="'price' must be positive when provided")
834 
835            reduce_only = _coerce_bool(reduce_only, "reduce_only")
836 
837            if isinstance(order_type, str):
838                order_type = order_type.strip().lower() or "limit"
839            if order_type not in {"limit", "ioc", "alo"}:
840                return ToolResult(success=False, error="'order_type' must be one of: limit, ioc, alo")
841 
842            is_buy = _coerce_side(side)
843            logger.info(
844                "hl_order: coin=%s side_raw=%r → is_buy=%s size=%s price=%s "
845                "order_type=%s reduce_only=%s",
846                coin, side, is_buy, size, price, order_type, reduce_only,
847            )
848 
849            client = _get_client()
850            data = await client.place_order(
851                coin=coin,
852                is_buy=is_buy,
853                size=size,
854                price=price,
855                order_type=order_type,
856                reduce_only=reduce_only,
857            )
858            return ToolResult(success=True, output=data)
859        except ValueError as e:
860            return ToolResult(success=False, error=str(e))
861        except Exception as e:
862            return ToolResult(success=False, error=str(e))
863 
864 
865class HLSpotOrderTool(BaseTool):
866    """Place a spot limit or market order."""
867 
868    @property
869    def name(self) -> str:
870        return "hl_spot_order"
871 
872    @property
873    def description(self) -> str:
874        return """Place a spot order on Hyperliquid.
875 
876Parameters:
877- coin: Token name (required, e.g. "PURR", "HYPE")
878- side: Direction. **Use "buy" or "sell"** — these are the documented values.
879        Aliases accepted (B/A, long/short, 做多/做空) but "buy"/"sell" is
880        preferred. Unknown values FAIL rather than default.
881- size: Order size in base token (required)
882- price: Limit price (optional — omit for market order)
883- order_type: "limit" (GTC, default), "ioc" (fill-or-kill), "alo" (post-only)
884 
885Market orders (no price): Uses IoC at mid price +/- 3% slippage.
886 
887Returns: order status with oid, filled size, price"""
888 
889    @property
890    def parameters(self) -> dict:
891        return {
892            "type": "object",
893            "properties": {
894                "coin": {
895                    "type": "string",
896                    "description": "Token name (e.g. 'PURR', 'HYPE')",
897                },
898                "side": {
899                    "type": "string",
900                    "enum": ["buy", "sell"],
901                    "description": "Order side",
902                },
903                "size": {
904                    "type": "number",
905                    "description": "Order size in base token",
906                },
907                "price": {
908                    "type": "number",
909                    "description": "Limit price (omit for market order)",
910                },
911                "order_type": {
912                    "type": "string",
913                    "enum": ["limit", "ioc", "alo"],
914                    "description": "Order type (default: limit)",
915                },
916            },
917            "required": ["coin", "side", "size"],
918        }
919 
920    async def execute(
921        self,
922        ctx: ToolContext,
923        coin: str = "",
924        side: str = "",
925        size: float = 0,
926        price: float = None,
927        order_type: str = "limit",
928        **kwargs,
929    ) -> ToolResult:
930        try:
931            if not coin or not side:
932                return ToolResult(success=False, error="'coin' and 'side' are required")
933 
934            size = _coerce_float(size, "size")
935            if size <= 0:
936                return ToolResult(success=False, error="'size' must be positive")
937 
938            if price is not None:
939                price = _coerce_float(price, "price")
940                if price <= 0:
941                    return ToolResult(success=False, error="'price' must be positive when provided")
942 
943            if isinstance(order_type, str):
944                order_type = order_type.strip().lower() or "limit"
945            if order_type not in {"limit", "ioc", "alo"}:
946                return ToolResult(success=False, error="'order_type' must be one of: limit, ioc, alo")
947 
948            is_buy = _coerce_side(side)
949            logger.info(
950                "hl_spot_order: coin=%s side_raw=%r → is_buy=%s size=%s price=%s "
951                "order_type=%s",
952                coin, side, is_buy, size, price, order_type,
953            )
954 
955            client = _get_client()
956            data = await client.place_order(
957                coin=coin,
958                is_buy=is_buy,
959                size=size,
960                price=price,
961                order_type=order_type,
962                is_spot=True,
963            )
964            return ToolResult(success=True, output=data)
965        except ValueError as e:
966            return ToolResult(success=False, error=str(e))
967        except Exception as e:
968            return ToolResult(success=False, error=str(e))
969 
970 
971class HLTPSLOrderTool(BaseTool):
972    """Place a stop loss or take profit order."""
973 
974    @property
975    def name(self) -> str:
976        return "hl_tpsl_order"
977 
978    @property
979    def description(self) -> str:
980        return """Place a stop loss or take profit order on Hyperliquid.
981 
982**Stop Loss**: Automatically sell when price drops to a trigger level to limit losses.
983**Take Profit**: Automatically sell when price rises to a trigger level to lock in gains.
984 
985**Crypto**: Use plain names — "BTC", "ETH", "SOL"
986**Stocks/RWA**: Use "xyz:TICKER" — "xyz:NVDA", "xyz:TSLA", "xyz:GOLD"
987 
988Parameters:
989- coin: Asset name (required, e.g. "BTC", "ETH", "xyz:NVDA")
990- side: Direction to close the position. **Use "buy" or "sell"** — these are
991        the documented values. For a long position, use "sell" to close; for a
992        short, use "buy". Aliases accepted (B/A, long/short, 做多/做空) but
993        "buy"/"sell" is preferred. Unknown values FAIL rather than default.
994- size: Order size in base asset (required, e.g. 0.01 for 0.01 BTC)
995- trigger_px: Price that triggers the order (required)
996- tpsl: "tp" for take profit, "sl" for stop loss (required)
997- is_market: If true, execute as market order when triggered. If false, use limit_px. (default: true)
998- limit_px: Limit price for the order when it triggers (optional, only used if is_market=false)
999- reduce_only: If true, only reduces existing position (default: true)
1000 
1001**How it works:**
10021. Order sits dormant until market price reaches trigger_px
10032. When triggered, executes immediately as market order (or limit if is_market=false)
10043. Use reduce_only=true to ensure it only closes positions (recommended for TP/SL)
1005 
1006**Examples:**
1007- Stop loss: If you're long BTC at $95k and want to exit if it drops to $90k:
1008  `hl_tpsl_order(coin="BTC", side="sell", size=0.1, trigger_px=90000, tpsl="sl")`
1009 
1010- Take profit: If you're long ETH and want to take profit at $3500:
1011  `hl_tpsl_order(coin="ETH", side="sell", size=1.0, trigger_px=3500, tpsl="tp")`
1012 
1013Returns: order status with oid, trigger details"""
1014 
1015    @property
1016    def parameters(self) -> dict:
1017        return {
1018            "type": "object",
1019            "properties": {
1020                "coin": {
1021                    "type": "string",
1022                    "description": "Asset name (e.g. 'BTC', 'xyz:NVDA')",
1023                },
1024                "side": {
1025                    "type": "string",
1026                    "enum": ["buy", "sell"],
1027                    "description": "Order side (usually opposite of your position)",
1028                },
1029                "size": {
1030                    "type": "number",
1031                    "description": "Order size in base asset",
1032                },
1033                "trigger_px": {
1034                    "type": "number",
1035                    "description": "Price that triggers the order",
1036                },
1037                "tpsl": {
1038                    "type": "string",
1039                    "enum": ["tp", "sl"],
1040                    "description": "Order type: 'tp' for take profit, 'sl' for stop loss",
1041                },
1042                "is_market": {
1043                    "type": "boolean",
1044                    "description": "Execute as market order when triggered (default: true)",
1045                },
1046                "limit_px": {
1047                    "type": "number",
1048                    "description": "Limit price when triggered (only if is_market=false)",
1049                },
1050                "reduce_only": {
1051                    "type": "boolean",
1052                    "description": "Only reduce position, don't open new (default: true)",
1053                },
1054            },
1055            "required": ["coin", "side", "size", "trigger_px", "tpsl"],
1056        }
1057 
1058    async def execute(
1059        self,
1060        ctx: ToolContext,
1061        coin: str = "",
1062        side: str = "",
1063        size: float = 0,
1064        trigger_px: float = 0,
1065        tpsl: str = "",
1066        is_market: bool = True,
1067        limit_px: float = None,
1068        reduce_only: bool = True,
1069        **kwargs,
1070    ) -> ToolResult:
1071        try:
1072            if not coin or not side or not tpsl:
1073                return ToolResult(
1074                    success=False,
1075                    error="'coin', 'side', and 'tpsl' are required",
1076                )
1077 
1078            size = _coerce_float(size, "size")
1079            trigger_px = _coerce_float(trigger_px, "trigger_px")
1080            if size <= 0:
1081                return ToolResult(success=False, error="'size' must be positive")
1082            if trigger_px <= 0:
1083                return ToolResult(success=False, error="'trigger_px' must be positive")
1084 
1085            is_market = _coerce_bool(is_market, "is_market")
1086            reduce_only = _coerce_bool(reduce_only, "reduce_only")
1087 
1088            if isinstance(tpsl, str):
1089                tpsl = tpsl.strip().lower()
1090            if tpsl not in ("tp", "sl"):
1091                return ToolResult(
1092                    success=False,
1093                    error="'tpsl' must be either 'tp' (take profit) or 'sl' (stop loss)",
1094                )
1095 
1096            if limit_px is not None:
1097                limit_px = _coerce_float(limit_px, "limit_px")
1098                if limit_px <= 0:
1099                    return ToolResult(success=False, error="'limit_px' must be positive when provided")
1100 
1101            is_buy = _coerce_side(side)
1102 
1103            # For trigger orders: always pass a limit price
1104            # - For market triggers: use the trigger price as limit (matches SDK)
1105            # - For limit triggers: use the specified limit price
1106            price = trigger_px if is_market else (limit_px or trigger_px)
1107 
1108            logger.info(
1109                "hl_tpsl_order: coin=%s side_raw=%r → is_buy=%s tpsl=%s "
1110                "size=%s trigger_px=%s is_market=%s reduce_only=%s",
1111                coin, side, is_buy, tpsl, size, trigger_px, is_market, reduce_only,
1112            )
1113 
1114            client = _get_client()
1115            data = await client.place_order(
1116                coin=coin,
1117                is_buy=is_buy,
1118                size=size,
1119                price=price,
1120                reduce_only=reduce_only,
1121                trigger_px=trigger_px,
1122                tpsl=tpsl,
1123            )
1124            return ToolResult(success=True, output=data)
1125        except ValueError as e:
1126            return ToolResult(success=False, error=str(e))
1127        except Exception as e:
1128            return ToolResult(success=False, error=str(e))
1129 
1130 
1131class HLCancelTool(BaseTool):
1132    """Cancel an order (perp or spot)."""
1133 
1134    @property
1135    def name(self) -> str:
1136        return "hl_cancel"
1137 
1138    @property
1139    def description(self) -> str:
1140        return """Cancel an open order on Hyperliquid by order ID.
1141 
1142Parameters:
1143- coin: Asset name (required, e.g. "BTC", "xyz:NVDA")
1144- order_id: Order ID to cancel (required — get from hl_open_orders)
1145 
1146Returns: cancel confirmation"""
1147 
1148    @property
1149    def parameters(self) -> dict:
1150        return {
1151            "type": "object",
1152            "properties": {
1153                "coin": {
1154                    "type": "string",
1155                    "description": "Asset name (e.g. 'BTC', 'xyz:NVDA')",
1156                },
1157                "order_id": {
1158                    "type": "integer",
1159                    "description": "Order ID (oid) to cancel",
1160                },
1161            },
1162            "required": ["coin", "order_id"],
1163        }
1164 
1165    async def execute(
1166        self, ctx: ToolContext, coin: str = "", order_id: int = 0, **kwargs
1167    ) -> ToolResult:
1168        try:
1169            if not coin:
1170                return ToolResult(success=False, error="'coin' is required")
1171 
1172            order_id = _coerce_int(order_id, "order_id")
1173            if order_id <= 0:
1174                return ToolResult(success=False, error="'order_id' must be positive")
1175 
1176            client = _get_client()
1177            data = await client.cancel_order(coin, order_id)
1178            return ToolResult(success=True, output=data)
1179        except ValueError as e:
1180            return ToolResult(success=False, error=str(e))
1181        except Exception as e:
1182            return ToolResult(success=False, error=str(e))
1183 
1184 
1185class HLCancelAllTool(BaseTool):
1186    """Cancel all open orders."""
1187 
1188    @property
1189    def name(self) -> str:
1190        return "hl_cancel_all"
1191 
1192    @property
1193    def description(self) -> str:
1194        return """Cancel all open orders on Hyperliquid.
1195 
1196Parameters:
1197- coin: (optional) Asset name to cancel orders for. Omit to cancel ALL orders.
1198 
1199Returns: array of cancel results"""
1200 
1201    @property
1202    def parameters(self) -> dict:
1203        return {
1204            "type": "object",
1205            "properties": {
1206                "coin": {
1207                    "type": "string",
1208                    "description": "Asset name (optional — omit for all)",
1209                },
1210            },
1211        }
1212 
1213    async def execute(self, ctx: ToolContext, coin: str = "", **kwargs) -> ToolResult:
1214        try:
1215            client = _get_client()
1216            results = await client.cancel_all(coin or None)
1217            return ToolResult(
1218                success=True,
1219                output={
1220                    "cancelled": len(results),
1221                    "results": results,
1222                },
1223            )
1224        except Exception as e:
1225            return ToolResult(success=False, error=str(e))
1226 
1227 
1228class HLModifyTool(BaseTool):
1229    """Modify an existing order."""
1230 
1231    @property
1232    def name(self) -> str:
1233        return "hl_modify"
1234 
1235    @property
1236    def description(self) -> str:
1237        return """Modify an existing order on Hyperliquid (change price or size).
1238 
1239Parameters:
1240- order_id: Order ID to modify (required)
1241- coin: Asset name (required, e.g. "BTC", "xyz:NVDA")
1242- side: Direction. **Use "buy" or "sell"** — these are the documented values.
1243        Aliases accepted (B/A, long/short, 做多/做空) but "buy"/"sell" is
1244        preferred. Unknown values FAIL rather than default.
1245- size: New size (required)
1246- price: New price (required)
1247 
1248Returns: modified order confirmation"""
1249 
1250    @property
1251    def parameters(self) -> dict:
1252        return {
1253            "type": "object",
1254            "properties": {
1255                "order_id": {
1256                    "type": "integer",
1257                    "description": "Order ID to modify",
1258                },
1259                "coin": {
1260                    "type": "string",
1261                    "description": "Asset name (e.g. 'BTC', 'xyz:NVDA')",
1262                },
1263                "side": {
1264                    "type": "string",
1265                    "enum": ["buy", "sell"],
1266                    "description": "Order side",
1267                },
1268                "size": {
1269                    "type": "number",
1270                    "description": "New order size",
1271                },
1272                "price": {
1273                    "type": "number",
1274                    "description": "New limit price",
1275                },
1276            },
1277            "required": ["order_id", "coin", "side", "size", "price"],
1278        }
1279 
1280    async def execute(
1281        self,
1282        ctx: ToolContext,
1283        order_id: int = 0,
1284        coin: str = "",
1285        side: str = "",
1286        size: float = 0,
1287        price: float = 0,
1288        **kwargs,
1289    ) -> ToolResult:
1290        try:
1291            if not coin or not side:
1292                return ToolResult(
1293                    success=False,
1294                    error="'coin' and 'side' are required",
1295                )
1296 
1297            order_id = _coerce_int(order_id, "order_id")
1298            size = _coerce_float(size, "size")
1299            price = _coerce_float(price, "price")
1300            if order_id <= 0:
1301                return ToolResult(success=False, error="'order_id' must be positive")
1302            if size <= 0:
1303                return ToolResult(success=False, error="'size' must be positive")
1304            if price <= 0:
1305                return ToolResult(success=False, error="'price' must be positive")
1306 
1307            is_buy = _coerce_side(side)
1308            logger.info(
1309                "hl_modify: order_id=%s coin=%s side_raw=%r → is_buy=%s "
1310                "size=%s price=%s",
1311                order_id, coin, side, is_buy, size, price,
1312            )
1313 
1314            client = _get_client()
1315            data = await client.modify_order(
1316                oid=order_id,
1317                coin=coin,
1318                is_buy=is_buy,
1319                size=size,
1320                price=price,
1321            )
1322            return ToolResult(success=True, output=data)
1323        except ValueError as e:
1324            return ToolResult(success=False, error=str(e))
1325        except Exception as e:
1326            return ToolResult(success=False, error=str(e))
1327 
1328 
1329class HLLeverageTool(BaseTool):
1330    """Set leverage for a perp."""
1331 
1332    @property
1333    def name(self) -> str:
1334        return "hl_leverage"
1335 
1336    @property
1337    def description(self) -> str:
1338        return """Set leverage for a Hyperliquid perpetual asset.
1339 
1340Parameters:
1341- coin: Asset name (required, e.g. "BTC", "xyz:NVDA")
1342- leverage: Leverage multiplier (required, e.g. 5 for 5x)
1343- cross: If true, use cross margin. If false, use isolated margin. (default: true)
1344 
1345Returns: leverage update confirmation"""
1346 
1347    @property
1348    def parameters(self) -> dict:
1349        return {
1350            "type": "object",
1351            "properties": {
1352                "coin": {
1353                    "type": "string",
1354                    "description": "Asset name (e.g. 'BTC', 'xyz:NVDA')",
1355                },
1356                "leverage": {
1357                    "type": "integer",
1358                    "description": "Leverage multiplier (e.g. 5)",
1359                },
1360                "cross": {
1361                    "type": "boolean",
1362                    "description": "Cross margin (default: true)",
1363                },
1364            },
1365            "required": ["coin", "leverage"],
1366        }
1367 
1368    async def execute(
1369        self,
1370        ctx: ToolContext,
1371        coin: str = "",
1372        leverage: int = 0,
1373        cross: bool = True,
1374        **kwargs,
1375    ) -> ToolResult:
1376        try:
1377            if not coin:
1378                return ToolResult(success=False, error="'coin' is required")
1379 
1380            leverage = _coerce_int(leverage, "leverage")
1381            cross = _coerce_bool(cross, "cross")
1382            if leverage <= 0:
1383                return ToolResult(success=False, error="'leverage' must be positive")
1384 
1385            client = _get_client()
1386            # Builder perps (HIP-3) require isolated margin
1387            if ":" in coin:
1388                cross = False
1389            data = await client.update_leverage(coin, leverage, is_cross=cross)
1390            return ToolResult(success=True, output=data)
1391        except ValueError as e:
1392            return ToolResult(success=False, error=str(e))
1393        except Exception as e:
1394            return ToolResult(success=False, error=str(e))
1395 
1396 
1397class HLTransferUsdTool(BaseTool):
1398    """Transfer USDC between spot and perp."""
1399 
1400    @property
1401    def name(self) -> str:
1402        return "hl_transfer_usd"
1403 
1404    @property
1405    def description(self) -> str:
1406        return """Transfer USDC between Hyperliquid spot and perp accounts.
1407 
1408**⚠️ IMPORTANT: This will FAIL if unified account mode is active!**
1409 
1410Unified account mode (default) shares funds automatically - manual transfers are disabled.
1411If you get "Action disabled when unified account is active", this is expected behavior.
1412 
1413**When to use:**
1414- Only when unified account is DISABLED
1415- To manually move USDC between spot ↔ perp
1416- Not needed when unified account is active (funds are already shared!)
1417 
1418**To check your mode:** Use `hl_total_balance` - it shows the current abstraction mode
1419 
1420Parameters:
1421- amount: USDC amount to transfer (required, e.g. 100.0)
1422- to_perp: If true, transfer from spot to perp. If false, from perp to spot. (default: true)
1423 
1424Returns: transfer confirmation"""
1425 
1426    @property
1427    def parameters(self) -> dict:
1428        return {
1429            "type": "object",
1430            "properties": {
1431                "amount": {
1432                    "type": "number",
1433                    "description": "USDC amount to transfer",
1434                },
1435                "to_perp": {
1436                    "type": "boolean",
1437                    "description": "True = spot→perp, False = perp→spot (default: true)",
1438                },
1439            },
1440            "required": ["amount"],
1441        }
1442 
1443    async def execute(
1444        self, ctx: ToolContext, amount: float = 0, to_perp: bool = True, **kwargs
1445    ) -> ToolResult:
1446        try:
1447            amount = _coerce_float(amount, "amount")
1448            to_perp = _coerce_bool(to_perp, "to_perp")
1449            if amount <= 0:
1450                return ToolResult(success=False, error="'amount' must be positive")
1451 
1452            client = _get_client()
1453            data = await client.transfer_usd(amount, to_perp=to_perp)
1454            return ToolResult(success=True, output=data)
1455        except ValueError as e:
1456            return ToolResult(success=False, error=str(e))
1457        except Exception as e:
1458            return ToolResult(success=False, error=str(e))
1459 
1460 
1461class HLWithdrawTool(BaseTool):
1462    """Withdraw USDC from Hyperliquid to Arbitrum wallet."""
1463 
1464    @property
1465    def name(self) -> str:
1466        return "hl_withdraw"
1467 
1468    @property
1469    def description(self) -> str:
1470        return """Withdraw USDC from Hyperliquid to an Arbitrum wallet (L1 bridge withdrawal).
1471 
1472Fee: 1 USDC (deducted by Hyperliquid). Processing time: ~5 minutes.
1473 
1474Parameters:
1475- amount: USDC amount to withdraw (required, e.g. 100.0)
1476- destination: Target wallet address (optional — defaults to this agent's own wallet)
1477 
1478Returns: withdrawal confirmation"""
1479 
1480    @property
1481    def parameters(self) -> dict:
1482        return {
1483            "type": "object",
1484            "properties": {
1485                "amount": {
1486                    "type": "number",
1487                    "description": "USDC amount to withdraw",
1488                },
1489                "destination": {
1490                    "type": "string",
1491                    "description": "Target Arbitrum wallet address (default: own wallet)",
1492                },
1493            },
1494            "required": ["amount"],
1495        }
1496 
1497    async def execute(
1498        self, ctx: ToolContext, amount: float = 0, destination: str = "", **kwargs
1499    ) -> ToolResult:
1500        try:
1501            amount = _coerce_float(amount, "amount")
1502            if amount <= 0:
1503                return ToolResult(success=False, error="'amount' must be positive")
1504 
1505            client = _get_client()
1506            data = await client.withdraw_from_bridge(
1507                amount, destination=destination or None
1508            )
1509            return ToolResult(success=True, output=data)
1510        except ValueError as e:
1511            return ToolResult(success=False, error=str(e))
1512        except Exception as e:
1513            return ToolResult(success=False, error=str(e))
1514 
1515 
1516class HLDepositTool(BaseTool):
1517    """Deposit USDC from Arbitrum wallet into Hyperliquid."""
1518 
1519    @property
1520    def name(self) -> str:
1521        return "hl_deposit"
1522 
1523    @property
1524    def description(self) -> str:
1525        return """Deposit USDC from this agent's Arbitrum wallet into Hyperliquid.
1526 
1527Sends an on-chain ERC-20 transfer of USDC to the Hyperliquid bridge contract.
1528Minimum deposit: 5 USDC. Requires USDC balance on Arbitrum.
1529 
1530Parameters:
1531- amount: USDC amount to deposit (required, minimum 5.0)
1532 
1533Returns: approve_tx_hash, transfer_tx_hash, amount_deposited"""
1534 
1535    @property
1536    def parameters(self) -> dict:
1537        return {
1538            "type": "object",
1539            "properties": {
1540                "amount": {
1541                    "type": "number",
1542                    "description": "USDC amount to deposit (minimum 5)",
1543                },
1544            },
1545            "required": ["amount"],
1546        }
1547 
1548    async def execute(
1549        self, ctx: ToolContext, amount: float = 0, **kwargs
1550    ) -> ToolResult:
1551        try:
1552            amount = _coerce_float(amount, "amount")
1553            if amount <= 0:
1554                return ToolResult(success=False, error="'amount' must be positive")
1555            if amount < 5:
1556                return ToolResult(
1557                    success=False,
1558                    error="Minimum Hyperliquid deposit is 5 USDC",
1559                )
1560 
1561            client = _get_client()
1562            data = await client.deposit_usdc(amount)
1563            return ToolResult(success=True, output=data)
1564        except ValueError as e:
1565            return ToolResult(success=False, error=str(e))
1566        except Exception as e:
1567            return ToolResult(success=False, error=str(e))
1568 
1569 
1570class HLSetAbstractionTool(BaseTool):
1571    """Enable or disable unified account (DEX abstraction)."""
1572 
1573    @property
1574    def name(self) -> str:
1575        return "hl_set_abstraction"
1576 
1577    @property
1578    def description(self) -> str:
1579        return """Set Hyperliquid account abstraction mode.
1580 
1581**Abstraction modes:**
1582- "unifiedAccount": Unified margin across spot and perp (auto-transfers, can't manually transfer)
1583- "disabled": Separate spot/perp accounts (can manually transfer between them)
1584- "portfolioMargin": Advanced portfolio margin (if eligible)
1585 
1586**When to use:**
1587- Disable unified account to manually transfer funds and trade builder perps (xyz:NVDA, etc.)
1588- Enable unified account for automatic fund management across spot and perp
1589 
1590Parameters:
1591- mode: Abstraction mode (required: "unifiedAccount", "disabled", or "portfolioMargin")
1592 
1593Returns: abstraction update confirmation"""
1594 
1595    @property
1596    def parameters(self) -> dict:
1597        return {
1598            "type": "object",
1599            "properties": {
1600                "mode": {
1601                    "type": "string",
1602                    "enum": ["unifiedAccount", "disabled", "portfolioMargin"],
1603                    "description": "Abstraction mode to set",
1604                },
1605            },
1606            "required": ["mode"],
1607        }
1608 
1609    async def execute(
1610        self, ctx: ToolContext, mode: str = "", **kwargs
1611    ) -> ToolResult:
1612        if mode not in ("unifiedAccount", "disabled", "portfolioMargin"):
1613            return ToolResult(
1614                success=False,
1615                error="'mode' must be 'unifiedAccount', 'disabled', or 'portfolioMargin'",
1616            )
1617        try:
1618            client = _get_client()
1619            address = await _get_address()
1620            # Call the private method directly for setting abstraction
1621            data = await client._user_set_abstraction(address, mode)
1622            return ToolResult(success=True, output=data)
1623        except Exception as e:
1624            return ToolResult(success=False, error=str(e))
1625