1"""
2Coinglass Tool Wrappers
3 
4Wraps tools from /tools/coinglass/ for use in Agent framework.
5Provides derivatives data: funding rates, open interest, liquidations, long/short ratios.
6"""
7import asyncio
8import logging
9from typing import Optional
10 
11from core.tool import BaseTool, ToolContext, ToolResult
12 
13logger = logging.getLogger(__name__)
14 
15# Import original tools from local tools directory
16try:
17    from .tools.funding_rate import get_funding_rates, get_symbol_funding_rate
18    from .tools.long_short_ratio import get_long_short_ratio
19    from .tools.long_short_advanced import (
20        get_global_account_ratio,
21        get_top_account_ratio,
22        get_top_position_ratio,
23        get_taker_buysell_exchanges,
24        get_net_position
25    )
26    from .tools.open_interest import get_open_interest
27    from .tools.liquidations import get_liquidations, get_liquidation_aggregated
28    from .tools.liquidations_advanced import (
29        get_coin_liquidation_history,
30        get_pair_liquidation_history,
31        get_liquidation_coin_list,
32        get_liquidation_orders
33    )
34    from .tools.hyperliquid import (
35        get_whale_alerts,
36        get_whale_positions,
37        get_positions_by_coin,
38        get_position_distribution
39    )
40    from .tools.futures_market import (
41        get_supported_coins,
42        get_supported_exchanges,
43        get_coins_data,
44        get_pair_data,
45        get_ohlc_history
46    )
47    from .tools.volume_flow import (
48        get_taker_volume_history,
49        get_aggregated_taker_volume,
50        get_cumulative_volume_delta,
51        get_coin_netflow
52    )
53    from .tools.whale_transfer import get_whale_transfers
54    from .tools._api import CoinglassError
55    from .tools.bitcoin_etf import (
56        get_btc_etf_flows,
57        get_btc_etf_premium_discount,
58        get_btc_etf_history,
59        get_btc_etf_list,
60        get_hk_btc_etf_flows
61    )
62    from .tools.other_etfs import (
63        get_eth_etf_flows,
64        get_eth_etf_list,
65        get_sol_etf_flows,
66        get_xrp_etf_flows
67    )
68    COINGLASS_AVAILABLE = True
69except ImportError as e:
70    logger.warning(f"Coinglass tools not available: {e}")
71    COINGLASS_AVAILABLE = False
72 
73 
74class FundingRateTool(BaseTool):
75    """
76    Get perpetual futures funding rates across exchanges.
77 
78    Funding rates indicate market sentiment:
79    - Positive rates: Longs pay shorts (bullish bias)
80    - Negative rates: Shorts pay longs (bearish bias)
81    - Extreme rates often precede reversals
82    """
83 
84    @property
85    def name(self) -> str:
86        return "funding_rate"
87 
88    @property
89    def description(self) -> str:
90        return """Get perpetual futures funding rates across exchanges.
91 
92Positive rates = longs pay shorts (bullish sentiment)
93Negative rates = shorts pay longs (bearish sentiment)
94Extreme funding often signals reversal risk.
95 
96Examples:
97- Get BTC funding rates: funding_rate(symbol="BTC")
98- Get ETH funding on Binance: funding_rate(symbol="ETH", exchange="Binance")"""
99 
100    @property
101    def parameters(self) -> dict:
102        return {
103            "type": "object",
104            "properties": {
105                "symbol": {
106                    "type": "string",
107                    "description": "Symbol (BTC, ETH, SOL, etc.)"
108                },
109                "exchange": {
110                    "type": "string",
111                    "description": "Optional: specific exchange (Binance, OKX, Bybit, etc.)"
112                }
113            },
114            "required": ["symbol"]
115        }
116 
117    async def execute(
118        self,
119        ctx: ToolContext,
120        symbol: str,
121        exchange: Optional[str] = None
122    ) -> ToolResult:
123        if not COINGLASS_AVAILABLE:
124            return ToolResult(
125                success=False,
126                output=None,
127                error="Coinglass tools not available."
128            )
129 
130        try:
131            if exchange:
132                result = await asyncio.to_thread(get_symbol_funding_rate, symbol=symbol, exchange=exchange)
133            else:
134                result = await asyncio.to_thread(get_funding_rates, symbol=symbol)
135 
136            if result is None:
137                return ToolResult(
138                    success=False,
139                    output=None,
140                    error="No data returned. The API returned an empty result."
141                )
142 
143            return ToolResult(success=True, output=result)
144        except CoinglassError as e:
145            msg = f"Coinglass: {e}"
146            if e.suggestion:
147                msg += f" ({e.suggestion})"
148            return ToolResult(
149                success=False, output=None, error=msg)
150        except Exception as e:
151            return ToolResult(
152                success=False, output=None,
153                error=f"Coinglass: {type(e).__name__}: {e}")
154 
155 
156class LongShortRatioTool(BaseTool):
157    """
158    Get long/short ratio for a cryptocurrency.
159 
160    Shows the ratio of long vs short positions across exchanges.
161    Useful for sentiment analysis.
162    """
163 
164    @property
165    def name(self) -> str:
166        return "long_short_ratio"
167 
168    @property
169    def description(self) -> str:
170        return """Get long/short position ratio across exchanges.
171 
172Ratio > 1: More longs than shorts
173Ratio < 1: More shorts than longs
174Extreme ratios often signal crowded trades.
175 
176Examples:
177- Get BTC L/S ratio: long_short_ratio(symbol="BTC")
178- Get ETH L/S ratio with timeframe: long_short_ratio(symbol="ETH", interval="h4")"""
179 
180    @property
181    def parameters(self) -> dict:
182        return {
183            "type": "object",
184            "properties": {
185                "symbol": {
186                    "type": "string",
187                    "description": "Symbol (BTC, ETH, SOL, etc.)"
188                },
189                "interval": {
190                    "type": "string",
191                    "description": "Time interval: h1, h4, h12, h24",
192                    "default": "h4"
193                }
194            },
195            "required": ["symbol"]
196        }
197 
198    async def execute(
199        self,
200        ctx: ToolContext,
201        symbol: str,
202        interval: str = "h4"
203    ) -> ToolResult:
204        if not COINGLASS_AVAILABLE:
205            return ToolResult(
206                success=False,
207                output=None,
208                error="Coinglass tools not available."
209            )
210 
211        try:
212            result = await asyncio.to_thread(get_long_short_ratio, symbol=symbol, time_type=interval)
213 
214            if result is None:
215                return ToolResult(
216                    success=False,
217                    output=None,
218                    error="No data returned. The API returned an empty result."
219                )
220 
221            return ToolResult(success=True, output=result)
222        except CoinglassError as e:
223            msg = f"Coinglass: {e}"
224            if e.suggestion:
225                msg += f" ({e.suggestion})"
226            return ToolResult(
227                success=False, output=None, error=msg)
228        except Exception as e:
229            return ToolResult(
230                success=False, output=None,
231                error=f"Coinglass: {type(e).__name__}: {e}")
232 
233 
234# ==================== Advanced Long/Short Ratio Tools ====================
235 
236class GlobalAccountRatioTool(BaseTool):
237    """Get global long/short account ratio history."""
238 
239    @property
240    def name(self) -> str:
241        return "cg_global_account_ratio"
242 
243    @property
244    def description(self) -> str:
245        return """Get global long/short account ratio history for a trading pair.
246 
247Shows the percentage of accounts holding long vs short positions over time.
248 
249Examples:
250- Get BTC global ratio: cg_global_account_ratio(symbol="BTC", exchange="Binance")
251- Get ETH with 4h interval: cg_global_account_ratio(symbol="ETH", exchange="OKX", interval="4h")"""
252 
253    @property
254    def parameters(self) -> dict:
255        return {
256            "type": "object",
257            "properties": {
258                "symbol": {"type": "string", "description": "Trading coin (BTC, ETH, SOL, etc.)"},
259                "exchange": {"type": "string", "description": "Exchange name (Binance, OKX, Bybit, etc.)"},
260                "interval": {"type": "string", "description": "Time interval: 1m, 5m, 15m, 30m, 1h, 4h, 12h, 1d, 1w", "default": "1h"},
261                "limit": {"type": "integer", "description": "Number of results (default: 100)", "default": 100}
262            },
263            "required": ["symbol", "exchange"]
264        }
265 
266    async def execute(self, ctx: ToolContext, symbol: str, exchange: str, interval: str = "1h", limit: int = 100) -> ToolResult:
267        if not COINGLASS_AVAILABLE:
268            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
269 
270        try:
271            result = await asyncio.to_thread(get_global_account_ratio, symbol, exchange, interval, limit)
272            if result is None:
273                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
274            return ToolResult(success=True, output=result)
275        except CoinglassError as e:
276            msg = f"Coinglass: {e}"
277            if e.suggestion:
278                msg += f" ({e.suggestion})"
279            return ToolResult(
280                success=False, output=None, error=msg)
281        except Exception as e:
282            return ToolResult(
283                success=False, output=None,
284                error=f"Coinglass: {type(e).__name__}: {e}")
285 
286 
287class TopAccountRatioTool(BaseTool):
288    """Get top traders long/short account ratio."""
289 
290    @property
291    def name(self) -> str:
292        return "cg_top_account_ratio"
293 
294    @property
295    def description(self) -> str:
296        return """Get long/short account ratio for top traders only.
297 
298Shows what the most successful traders are doing. More reliable than global ratios.
299 
300Examples:
301- Get BTC top trader ratio: cg_top_account_ratio(symbol="BTC", exchange="Binance")
302- Get ETH 4h: cg_top_account_ratio(symbol="ETH", exchange="OKX", interval="4h")"""
303 
304    @property
305    def parameters(self) -> dict:
306        return {
307            "type": "object",
308            "properties": {
309                "symbol": {"type": "string", "description": "Trading coin (BTC, ETH, SOL, etc.)"},
310                "exchange": {"type": "string", "description": "Exchange name (Binance, OKX, Bybit, etc.)"},
311                "interval": {"type": "string", "description": "Time interval: 1m, 5m, 15m, 30m, 1h, 4h, 12h, 1d, 1w", "default": "1h"},
312                "limit": {"type": "integer", "description": "Number of results (default: 100)", "default": 100}
313            },
314            "required": ["symbol", "exchange"]
315        }
316 
317    async def execute(self, ctx: ToolContext, symbol: str, exchange: str, interval: str = "1h", limit: int = 100) -> ToolResult:
318        if not COINGLASS_AVAILABLE:
319            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
320 
321        try:
322            result = await asyncio.to_thread(get_top_account_ratio, symbol, exchange, interval, limit)
323            if result is None:
324                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
325            return ToolResult(success=True, output=result)
326        except CoinglassError as e:
327            msg = f"Coinglass: {e}"
328            if e.suggestion:
329                msg += f" ({e.suggestion})"
330            return ToolResult(
331                success=False, output=None, error=msg)
332        except Exception as e:
333            return ToolResult(
334                success=False, output=None,
335                error=f"Coinglass: {type(e).__name__}: {e}")
336 
337 
338class TopPositionRatioTool(BaseTool):
339    """Get top traders long/short position ratio."""
340 
341    @property
342    def name(self) -> str:
343        return "cg_top_position_ratio"
344 
345    @property
346    def description(self) -> str:
347        return """Get long/short position ratio for top traders (by position size, not account count).
348 
349Shows the actual $ amount split between longs and shorts for top traders.
350 
351Examples:
352- Get BTC top position ratio: cg_top_position_ratio(symbol="BTC", exchange="Binance")
353- Get ETH 4h: cg_top_position_ratio(symbol="ETH", exchange="OKX", interval="4h")"""
354 
355    @property
356    def parameters(self) -> dict:
357        return {
358            "type": "object",
359            "properties": {
360                "symbol": {"type": "string", "description": "Trading coin (BTC, ETH, SOL, etc.)"},
361                "exchange": {"type": "string", "description": "Exchange name (Binance, OKX, Bybit, etc.)"},
362                "interval": {"type": "string", "description": "Time interval: 1m, 5m, 15m, 30m, 1h, 4h, 12h, 1d, 1w", "default": "1h"},
363                "limit": {"type": "integer", "description": "Number of results (default: 100)", "default": 100}
364            },
365            "required": ["symbol", "exchange"]
366        }
367 
368    async def execute(self, ctx: ToolContext, symbol: str, exchange: str, interval: str = "1h", limit: int = 100) -> ToolResult:
369        if not COINGLASS_AVAILABLE:
370            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
371 
372        try:
373            result = await asyncio.to_thread(get_top_position_ratio, symbol, exchange, interval, limit)
374            if result is None:
375                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
376            return ToolResult(success=True, output=result)
377        except CoinglassError as e:
378            msg = f"Coinglass: {e}"
379            if e.suggestion:
380                msg += f" ({e.suggestion})"
381            return ToolResult(
382                success=False, output=None, error=msg)
383        except Exception as e:
384            return ToolResult(
385                success=False, output=None,
386                error=f"Coinglass: {type(e).__name__}: {e}")
387 
388 
389class TakerBuySellExchangesTool(BaseTool):
390    """Get exchanges with taker buy/sell volume data."""
391 
392    @property
393    def name(self) -> str:
394        return "cg_taker_exchanges"
395 
396    @property
397    def description(self) -> str:
398        return """Get list of exchanges with taker buy/sell volume data available.
399 
400Shows which exchanges provide taker volume metrics and their current ratios.
401 
402Examples:
403- Get BTC exchanges (1h): cg_taker_exchanges(symbol="BTC")
404- Get ETH exchanges (24h): cg_taker_exchanges(symbol="ETH", range="24h")"""
405 
406    @property
407    def parameters(self) -> dict:
408        return {
409            "type": "object",
410            "properties": {
411                "symbol": {"type": "string", "description": "Trading coin (BTC, ETH, SOL, etc.)"},
412                "range": {"type": "string", "description": "Time range: 1h, 4h, 12h, 24h (default: 1h)", "default": "1h"}
413            },
414            "required": ["symbol"]
415        }
416 
417    async def execute(self, ctx: ToolContext, symbol: str, range: str = "1h") -> ToolResult:
418        if not COINGLASS_AVAILABLE:
419            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
420 
421        try:
422            result = await asyncio.to_thread(get_taker_buysell_exchanges, symbol, range)
423            if result is None:
424                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
425            return ToolResult(success=True, output=result)
426        except CoinglassError as e:
427            msg = f"Coinglass: {e}"
428            if e.suggestion:
429                msg += f" ({e.suggestion})"
430            return ToolResult(
431                success=False, output=None, error=msg)
432        except Exception as e:
433            return ToolResult(
434                success=False, output=None,
435                error=f"Coinglass: {type(e).__name__}: {e}")
436 
437 
438class NetPositionTool(BaseTool):
439    """Get net position changes (net long/short delta)."""
440 
441    @property
442    def name(self) -> str:
443        return "cg_net_position"
444 
445    @property
446    def description(self) -> str:
447        return """Get historical net position data showing net long/short changes.
448 
449Net position = difference between long and short positions opened.
450Useful for tracking institutional positioning.
451 
452Examples:
453- Get BTC net position: cg_net_position(symbol="BTC", exchange="Binance")
454- Get ETH 4h: cg_net_position(symbol="ETH", exchange="OKX", interval="4h")"""
455 
456    @property
457    def parameters(self) -> dict:
458        return {
459            "type": "object",
460            "properties": {
461                "symbol": {"type": "string", "description": "Trading coin (BTC, ETH, SOL, etc.)"},
462                "exchange": {"type": "string", "description": "Exchange name (Binance, OKX, Bybit, etc.)"},
463                "interval": {"type": "string", "description": "Time interval: 1m, 5m, 15m, 30m, 1h, 4h, 12h, 1d, 1w", "default": "1h"},
464                "limit": {"type": "integer", "description": "Number of results (default: 100)", "default": 100}
465            },
466            "required": ["symbol", "exchange"]
467        }
468 
469    async def execute(self, ctx: ToolContext, symbol: str, exchange: str, interval: str = "1h", limit: int = 100) -> ToolResult:
470        if not COINGLASS_AVAILABLE:
471            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
472 
473        try:
474            result = await asyncio.to_thread(get_net_position, symbol, exchange, interval, limit)
475            if result is None:
476                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
477            return ToolResult(success=True, output=result)
478        except CoinglassError as e:
479            msg = f"Coinglass: {e}"
480            if e.suggestion:
481                msg += f" ({e.suggestion})"
482            return ToolResult(
483                success=False, output=None, error=msg)
484        except Exception as e:
485            return ToolResult(
486                success=False, output=None,
487                error=f"Coinglass: {type(e).__name__}: {e}")
488 
489 
490# ==================== Open Interest Tools ====================
491 
492class OpenInterestTool(BaseTool):
493    """
494    Get aggregate open interest across exchanges.
495    """
496 
497    @property
498    def name(self) -> str:
499        return "cg_open_interest"
500 
501    @property
502    def description(self) -> str:
503        return """Get aggregate open interest across exchanges for a symbol.
504 
505Open interest = total outstanding derivative contracts.
506Rising OI + rising price = new money entering (bullish)
507Rising OI + falling price = new shorts opening (bearish)
508Falling OI = positions closing (trend weakening)
509 
510Examples:
511- Get BTC open interest: cg_open_interest(symbol="BTC")
512- Get ETH open interest: cg_open_interest(symbol="ETH")"""
513 
514    @property
515    def parameters(self) -> dict:
516        return {
517            "type": "object",
518            "properties": {
519                "symbol": {
520                    "type": "string",
521                    "description": "Symbol (BTC, ETH, SOL, etc.)"
522                }
523            },
524            "required": ["symbol"]
525        }
526 
527    async def execute(
528        self,
529        ctx: ToolContext,
530        symbol: str
531    ) -> ToolResult:
532        if not COINGLASS_AVAILABLE:
533            return ToolResult(
534                success=False,
535                output=None,
536                error="Coinglass tools not available."
537            )
538 
539        try:
540            result = await asyncio.to_thread(get_open_interest, symbol)
541 
542            if result is None:
543                return ToolResult(
544                    success=False,
545                    output=None,
546                    error="No data returned. The API returned an empty result."
547                )
548 
549            return ToolResult(success=True, output=result)
550        except CoinglassError as e:
551            msg = f"Coinglass: {e}"
552            if e.suggestion:
553                msg += f" ({e.suggestion})"
554            return ToolResult(
555                success=False, output=None, error=msg)
556        except Exception as e:
557            return ToolResult(
558                success=False, output=None,
559                error=f"Coinglass: {type(e).__name__}: {e}")
560 
561 
562# ==================== Liquidation Tools ====================
563 
564class LiquidationsTool(BaseTool):
565    """
566    Get recent liquidation data.
567    """
568 
569    @property
570    def name(self) -> str:
571        return "cg_liquidations"
572 
573    @property
574    def description(self) -> str:
575        return """Get recent liquidation data across exchanges.
576 
577Liquidations = forced position closures due to insufficient margin.
578More long liquidations = bearish pressure (longs being squeezed)
579More short liquidations = bullish pressure (shorts being squeezed)
580 
581Examples:
582- Get BTC liquidations (24h): cg_liquidations(symbol="BTC")
583- Get ETH liquidations (4h): cg_liquidations(symbol="ETH", time_type="h4")"""
584 
585    @property
586    def parameters(self) -> dict:
587        return {
588            "type": "object",
589            "properties": {
590                "symbol": {
591                    "type": "string",
592                    "description": "Symbol (BTC, ETH, SOL, etc.)"
593                },
594                "time_type": {
595                    "type": "string",
596                    "description": "Time window: h1, h4, h12, h24",
597                    "default": "h24"
598                }
599            },
600            "required": ["symbol"]
601        }
602 
603    async def execute(
604        self,
605        ctx: ToolContext,
606        symbol: str,
607        time_type: str = "h24"
608    ) -> ToolResult:
609        if not COINGLASS_AVAILABLE:
610            return ToolResult(
611                success=False,
612                output=None,
613                error="Coinglass tools not available."
614            )
615 
616        try:
617            result = await asyncio.to_thread(get_liquidations, symbol, time_type)
618 
619            if result is None:
620                return ToolResult(
621                    success=False,
622                    output=None,
623                    error="No data returned. The API returned an empty result."
624                )
625 
626            return ToolResult(success=True, output=result)
627        except CoinglassError as e:
628            msg = f"Coinglass: {e}"
629            if e.suggestion:
630                msg += f" ({e.suggestion})"
631            return ToolResult(
632                success=False, output=None, error=msg)
633        except Exception as e:
634            return ToolResult(
635                success=False, output=None,
636                error=f"Coinglass: {type(e).__name__}: {e}")
637 
638 
639class LiquidationAnalysisTool(BaseTool):
640    """
641    Get liquidation data with sentiment analysis.
642    """
643 
644    @property
645    def name(self) -> str:
646        return "cg_liquidation_analysis"
647 
648    @property
649    def description(self) -> str:
650        return """Get liquidation data with market sentiment analysis.
651 
652Includes interpretation of liquidation imbalances.
653 
654Examples:
655- Analyze BTC liquidations: cg_liquidation_analysis(symbol="BTC")
656- Analyze ETH (4h): cg_liquidation_analysis(symbol="ETH", time_type="h4")"""
657 
658    @property
659    def parameters(self) -> dict:
660        return {
661            "type": "object",
662            "properties": {
663                "symbol": {
664                    "type": "string",
665                    "description": "Symbol (BTC, ETH, SOL, etc.)"
666                },
667                "time_type": {
668                    "type": "string",
669                    "description": "Time window: h1, h4, h12, h24",
670                    "default": "h24"
671                }
672            },
673            "required": ["symbol"]
674        }
675 
676    async def execute(
677        self,
678        ctx: ToolContext,
679        symbol: str,
680        time_type: str = "h24"
681    ) -> ToolResult:
682        if not COINGLASS_AVAILABLE:
683            return ToolResult(
684                success=False,
685                output=None,
686                error="Coinglass tools not available."
687            )
688 
689        try:
690            result = await asyncio.to_thread(get_liquidation_aggregated, symbol, time_type)
691 
692            if result is None:
693                return ToolResult(
694                    success=False,
695                    output=None,
696                    error="No data returned. The API returned an empty result."
697                )
698 
699            return ToolResult(success=True, output=result)
700        except CoinglassError as e:
701            msg = f"Coinglass: {e}"
702            if e.suggestion:
703                msg += f" ({e.suggestion})"
704            return ToolResult(
705                success=False, output=None, error=msg)
706        except Exception as e:
707            return ToolResult(
708                success=False, output=None,
709                error=f"Coinglass: {type(e).__name__}: {e}")
710 
711 
712# ==================== Advanced Liquidation Tools ====================
713 
714class CoinLiquidationHistoryTool(BaseTool):
715    """Get aggregated liquidation history for a coin across all exchanges."""
716 
717    @property
718    def name(self) -> str:
719        return "cg_coin_liquidation_history"
720 
721    @property
722    def description(self) -> str:
723        return """Get aggregated liquidation history across all exchanges for a coin.
724 
725Shows total long/short liquidations over time, aggregated across all exchanges.
726 
727Examples:
728- Get BTC liquidation history: cg_coin_liquidation_history(symbol="BTC", interval="1h", limit=100)
729- Get ETH 4h intervals: cg_coin_liquidation_history(symbol="ETH", interval="4h", limit=50)"""
730 
731    @property
732    def parameters(self) -> dict:
733        return {
734            "type": "object",
735            "properties": {
736                "symbol": {"type": "string", "description": "Trading coin (BTC, ETH, SOL, etc.)"},
737                "exchange_list": {"type": "string", "description": "Comma-separated exchange list (e.g. 'Binance,OKX,Bybit')"},
738                "interval": {"type": "string", "description": "Time interval: 1m, 3m, 5m, 15m, 30m, 1h, 4h, 6h, 8h, 12h, 1d, 1w", "default": "1h"},
739                "limit": {"type": "integer", "description": "Number of results (default: 1000, max: 4500)", "default": 1000},
740                "start_time": {"type": "integer", "description": "Start timestamp in milliseconds"},
741                "end_time": {"type": "integer", "description": "End timestamp in milliseconds"}
742            },
743            "required": ["symbol", "exchange_list"]
744        }
745 
746    async def execute(self, ctx: ToolContext, symbol: str, exchange_list: str, interval: str = "1h", limit: int = 1000,
747                     start_time: Optional[int] = None, end_time: Optional[int] = None) -> ToolResult:
748        if not COINGLASS_AVAILABLE:
749            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
750 
751        try:
752            result = await asyncio.to_thread(get_coin_liquidation_history, symbol, exchange_list, interval, limit, start_time, end_time)
753            if result is None:
754                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
755            return ToolResult(success=True, output=result)
756        except CoinglassError as e:
757            msg = f"Coinglass: {e}"
758            if e.suggestion:
759                msg += f" ({e.suggestion})"
760            return ToolResult(
761                success=False, output=None, error=msg)
762        except Exception as e:
763            return ToolResult(
764                success=False, output=None,
765                error=f"Coinglass: {type(e).__name__}: {e}")
766 
767 
768class PairLiquidationHistoryTool(BaseTool):
769    """Get liquidation history for a specific trading pair on an exchange."""
770 
771    @property
772    def name(self) -> str:
773        return "cg_pair_liquidation_history"
774 
775    @property
776    def description(self) -> str:
777        return """Get liquidation history for a specific pair on a specific exchange.
778 
779Shows long/short liquidations over time for exchange-specific pairs.
780 
781Examples:
782- Get BTC/USDT on Binance: cg_pair_liquidation_history(symbol="BTC", exchange="Binance", interval="1h")
783- Get ETH/USDT on OKX: cg_pair_liquidation_history(symbol="ETH", exchange="OKX", interval="4h")"""
784 
785    @property
786    def parameters(self) -> dict:
787        return {
788            "type": "object",
789            "properties": {
790                "symbol": {"type": "string", "description": "Trading coin (BTC, ETH, SOL, etc.)"},
791                "exchange": {"type": "string", "description": "Exchange name (Binance, OKX, Bybit, etc.)"},
792                "interval": {"type": "string", "description": "Time interval: 1h, 4h, 12h, 24h", "default": "1h"},
793                "limit": {"type": "integer", "description": "Number of results (default: 1000, max: 4500)", "default": 1000},
794                "start_time": {"type": "integer", "description": "Start timestamp in seconds"},
795                "end_time": {"type": "integer", "description": "End timestamp in seconds"}
796            },
797            "required": ["symbol", "exchange"]
798        }
799 
800    async def execute(self, ctx: ToolContext, symbol: str, exchange: str, interval: str = "1h", limit: int = 1000,
801                     start_time: Optional[int] = None, end_time: Optional[int] = None) -> ToolResult:
802        if not COINGLASS_AVAILABLE:
803            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
804 
805        try:
806            result = await asyncio.to_thread(get_pair_liquidation_history, symbol, exchange, interval, limit, start_time, end_time)
807            if result is None:
808                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
809            return ToolResult(success=True, output=result)
810        except CoinglassError as e:
811            msg = f"Coinglass: {e}"
812            if e.suggestion:
813                msg += f" ({e.suggestion})"
814            return ToolResult(
815                success=False, output=None, error=msg)
816        except Exception as e:
817            return ToolResult(
818                success=False, output=None,
819                error=f"Coinglass: {type(e).__name__}: {e}")
820 
821 
822class LiquidationCoinListTool(BaseTool):
823    """Get liquidation data for all coins on a specific exchange."""
824 
825    @property
826    def name(self) -> str:
827        return "cg_liquidation_coin_list"
828 
829    @property
830    def description(self) -> str:
831        return """Get liquidation data for all coins on a specific exchange.
832 
833Shows liquidation amounts across multiple timeframes (1h, 4h, 12h, 24h) for all coins on an exchange.
834 
835Examples:
836- Get all Binance liquidations: cg_liquidation_coin_list(exchange="Binance")
837- Get all OKX liquidations: cg_liquidation_coin_list(exchange="OKX")"""
838 
839    @property
840    def parameters(self) -> dict:
841        return {
842            "type": "object",
843            "properties": {
844                "exchange": {"type": "string", "description": "Exchange name (Binance, OKX, Bybit, etc.)"}
845            },
846            "required": ["exchange"]
847        }
848 
849    async def execute(self, ctx: ToolContext, exchange: str) -> ToolResult:
850        if not COINGLASS_AVAILABLE:
851            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
852 
853        try:
854            result = await asyncio.to_thread(get_liquidation_coin_list, exchange)
855            if result is None:
856                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
857            return ToolResult(success=True, output=result)
858        except CoinglassError as e:
859            msg = f"Coinglass: {e}"
860            if e.suggestion:
861                msg += f" ({e.suggestion})"
862            return ToolResult(
863                success=False, output=None, error=msg)
864        except Exception as e:
865            return ToolResult(
866                success=False, output=None,
867                error=f"Coinglass: {type(e).__name__}: {e}")
868 
869 
870class LiquidationOrdersTool(BaseTool):
871    """Get individual liquidation orders (past 7 days)."""
872 
873    @property
874    def name(self) -> str:
875        return "cg_liquidation_orders"
876 
877    @property
878    def description(self) -> str:
879        return """Get individual liquidation orders with price, side, and USD value (past 7 days only).
880 
881Shows actual liquidation events. Max 200 records per request.
882 
883Examples:
884- Get BTC liquidations on Binance (min $10K): cg_liquidation_orders(symbol="BTC", exchange="Binance", min_liquidation_amount="10000")
885- Get ETH liquidations on OKX (min $5K): cg_liquidation_orders(symbol="ETH", exchange="OKX", min_liquidation_amount="5000")"""
886 
887    @property
888    def parameters(self) -> dict:
889        return {
890            "type": "object",
891            "properties": {
892                "symbol": {"type": "string", "description": "Trading coin (BTC, ETH, SOL, etc.)"},
893                "exchange": {"type": "string", "description": "Exchange name (Binance, OKX, Bybit, etc.)"},
894                "min_liquidation_amount": {"type": "string", "description": "Minimum threshold for liquidation events (USD)"},
895                "start_time": {"type": "integer", "description": "Start timestamp in milliseconds"},
896                "end_time": {"type": "integer", "description": "End timestamp in milliseconds"}
897            },
898            "required": ["symbol", "exchange", "min_liquidation_amount"]
899        }
900 
901    async def execute(self, ctx: ToolContext, symbol: str, exchange: str, min_liquidation_amount: str,
902                     start_time: Optional[int] = None, end_time: Optional[int] = None) -> ToolResult:
903        if not COINGLASS_AVAILABLE:
904            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
905 
906        try:
907            result = await asyncio.to_thread(get_liquidation_orders, symbol, exchange, min_liquidation_amount, start_time, end_time)
908            if result is None:
909                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
910            return ToolResult(success=True, output=result)
911        except CoinglassError as e:
912            msg = f"Coinglass: {e}"
913            if e.suggestion:
914                msg += f" ({e.suggestion})"
915            return ToolResult(
916                success=False, output=None, error=msg)
917        except Exception as e:
918            return ToolResult(
919                success=False, output=None,
920                error=f"Coinglass: {type(e).__name__}: {e}")
921 
922 
923# ==================== Futures Market Data Tools (V4 API) ====================
924 
925class SupportedCoinsTool(BaseTool):
926    """Get list of all supported coins for futures trading."""
927 
928    @property
929    def name(self) -> str:
930        return "cg_supported_coins"
931 
932    @property
933    def description(self) -> str:
934        return """Get list of all supported coins for futures trading on Coinglass.
935 
936Returns array of coin symbols (BTC, ETH, SOL, XRP, HYPE, DOGE, etc.)
937 
938Use this for:
939- Market discovery
940- Checking if a coin has futures markets
941- Finding new trading opportunities
942 
943Examples:
944- Get all supported coins: cg_supported_coins()"""
945 
946    @property
947    def parameters(self) -> dict:
948        return {"type": "object", "properties": {}, "required": []}
949 
950    async def execute(self, ctx: ToolContext) -> ToolResult:
951        if not COINGLASS_AVAILABLE:
952            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
953 
954        try:
955            result = await asyncio.to_thread(get_supported_coins)
956            if result is None:
957                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
958            return ToolResult(success=True, output=result)
959        except CoinglassError as e:
960            msg = f"Coinglass: {e}"
961            if e.suggestion:
962                msg += f" ({e.suggestion})"
963            return ToolResult(
964                success=False, output=None, error=msg)
965        except Exception as e:
966            return ToolResult(
967                success=False, output=None,
968                error=f"Coinglass: {type(e).__name__}: {e}")
969 
970 
971class SupportedExchangesTool(BaseTool):
972    """Get all supported exchanges with their trading pairs."""
973 
974    @property
975    def name(self) -> str:
976        return "cg_supported_exchanges"
977 
978    @property
979    def description(self) -> str:
980        return """Get all supported exchanges with trading pairs and specs.
981 
982Returns dictionary with exchange pairs including leverage limits, funding intervals, tick sizes.
983 
984Examples:
985- Get all exchanges: cg_supported_exchanges()"""
986 
987    @property
988    def parameters(self) -> dict:
989        return {"type": "object", "properties": {}, "required": []}
990 
991    async def execute(self, ctx: ToolContext) -> ToolResult:
992        if not COINGLASS_AVAILABLE:
993            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
994 
995        try:
996            result = await asyncio.to_thread(get_supported_exchanges)
997            if result is None:
998                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
999            return ToolResult(success=True, output=result)
1000        except CoinglassError as e:
1001            msg = f"Coinglass: {e}"
1002            if e.suggestion:
1003                msg += f" ({e.suggestion})"
1004            return ToolResult(
1005                success=False, output=None, error=msg)
1006        except Exception as e:
1007            return ToolResult(
1008                success=False, output=None,
1009                error=f"Coinglass: {type(e).__name__}: {e}")
1010 
1011 
1012class CoinsMarketDataTool(BaseTool):
1013    """Get comprehensive market data for ALL coins in one request."""
1014 
1015    @property
1016    def name(self) -> str:
1017        return "cg_coins_market_data"
1018 
1019    @property
1020    def description(self) -> str:
1021        return """Get market data for ALL coins in ONE request.
1022 
1023Returns: price, funding rates, OI, volume, long/short ratios, liquidations for 100+ coins.
1024 
1025Use this for market screening and bulk analysis. MUCH more efficient than individual calls.
1026 
1027Examples:
1028- Get all coins data: cg_coins_market_data()"""
1029 
1030    @property
1031    def parameters(self) -> dict:
1032        return {"type": "object", "properties": {}, "required": []}
1033 
1034    async def execute(self, ctx: ToolContext) -> ToolResult:
1035        if not COINGLASS_AVAILABLE:
1036            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
1037 
1038        try:
1039            result = await asyncio.to_thread(get_coins_data)
1040            if result is None:
1041                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
1042            return ToolResult(success=True, output=result)
1043        except CoinglassError as e:
1044            msg = f"Coinglass: {e}"
1045            if e.suggestion:
1046                msg += f" ({e.suggestion})"
1047            return ToolResult(
1048                success=False, output=None, error=msg)
1049        except Exception as e:
1050            return ToolResult(
1051                success=False, output=None,
1052                error=f"Coinglass: {type(e).__name__}: {e}")
1053 
1054 
1055class PairMarketDataTool(BaseTool):
1056    """Get detailed market data for a specific trading pair."""
1057 
1058    @property
1059    def name(self) -> str:
1060        return "cg_pair_market_data"
1061 
1062    @property
1063    def description(self) -> str:
1064        return """Get detailed market data for a specific pair on an exchange.
1065 
1066Returns: price, volume, OI, funding rate, liquidations, long/short volumes.
1067 
1068Examples:
1069- Get BTC/USDT on Binance: cg_pair_market_data(symbol="BTC", exchange="Binance")
1070- Get ETH/USDT on OKX: cg_pair_market_data(symbol="ETH", exchange="OKX")"""
1071 
1072    @property
1073    def parameters(self) -> dict:
1074        return {
1075            "type": "object",
1076            "properties": {
1077                "symbol": {"type": "string", "description": "Coin symbol (BTC, ETH, SOL, etc.)"},
1078                "exchange": {"type": "string", "description": "Exchange name (Binance, OKX, Bybit, Gate, etc.)"}
1079            },
1080            "required": ["symbol", "exchange"]
1081        }
1082 
1083    async def execute(self, ctx: ToolContext, symbol: str, exchange: str) -> ToolResult:
1084        if not COINGLASS_AVAILABLE:
1085            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
1086 
1087        try:
1088            result = await asyncio.to_thread(get_pair_data, symbol, exchange)
1089            if result is None:
1090                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
1091            return ToolResult(success=True, output=result)
1092        except CoinglassError as e:
1093            msg = f"Coinglass: {e}"
1094            if e.suggestion:
1095                msg += f" ({e.suggestion})"
1096            return ToolResult(
1097                success=False, output=None, error=msg)
1098        except Exception as e:
1099            return ToolResult(
1100                success=False, output=None,
1101                error=f"Coinglass: {type(e).__name__}: {e}")
1102 
1103 
1104class OHLCHistoryTool(BaseTool):
1105    """Get OHLC price history for a trading pair."""
1106 
1107    @property
1108    def name(self) -> str:
1109        return "cg_ohlc_history"
1110 
1111    @property
1112    def description(self) -> str:
1113        return """Get OHLC candlestick data for price analysis.
1114 
1115Returns array of candles with: timestamp, open, high, low, close.
1116 
1117Examples:
1118- Get BTC 1h candles: cg_ohlc_history(symbol="BTC", exchange="Binance", interval="h1", limit=100)
1119- Get ETH daily: cg_ohlc_history(symbol="ETH", exchange="OKX", interval="d1", limit=30)"""
1120 
1121    @property
1122    def parameters(self) -> dict:
1123        return {
1124            "type": "object",
1125            "properties": {
1126                "symbol": {"type": "string", "description": "Coin symbol (BTC, ETH, SOL, etc.)"},
1127                "exchange": {"type": "string", "description": "Exchange name (Binance, OKX, Bybit, etc.)"},
1128                "interval": {"type": "string", "description": "Time interval: m1, m5, m15, m30, h1, h4, h12, d1", "default": "h1"},
1129                "limit": {"type": "integer", "description": "Number of candles (default: 100)", "default": 100}
1130            },
1131            "required": ["symbol", "exchange"]
1132        }
1133 
1134    async def execute(self, ctx: ToolContext, symbol: str, exchange: str, interval: str = "h1", limit: int = 100) -> ToolResult:
1135        if not COINGLASS_AVAILABLE:
1136            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
1137 
1138        try:
1139            result = await asyncio.to_thread(get_ohlc_history, symbol, exchange, interval, limit)
1140            if result is None:
1141                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
1142            return ToolResult(success=True, output=result)
1143        except CoinglassError as e:
1144            msg = f"Coinglass: {e}"
1145            if e.suggestion:
1146                msg += f" ({e.suggestion})"
1147            return ToolResult(
1148                success=False, output=None, error=msg)
1149        except Exception as e:
1150            return ToolResult(
1151                success=False, output=None,
1152                error=f"Coinglass: {type(e).__name__}: {e}")
1153 
1154 
1155# ==================== Hyperliquid Tools ====================
1156 
1157class HyperliquidWhaleAlertsTool(BaseTool):
1158    """Get recent whale alerts on Hyperliquid (positions > $1M)."""
1159 
1160    @property
1161    def name(self) -> str:
1162        return "cg_hyperliquid_whale_alerts"
1163 
1164    @property
1165    def description(self) -> str:
1166        return """Get recent whale alerts on Hyperliquid (positions > $1M).
1167 
1168Returns approximately 200 most recent large position opens/closes.
1169 
1170Examples:
1171- Get whale alerts: cg_hyperliquid_whale_alerts()"""
1172 
1173    @property
1174    def parameters(self) -> dict:
1175        return {"type": "object", "properties": {}, "required": []}
1176 
1177    async def execute(self, ctx: ToolContext) -> ToolResult:
1178        if not COINGLASS_AVAILABLE:
1179            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
1180 
1181        try:
1182            result = await asyncio.to_thread(get_whale_alerts)
1183            if result is None:
1184                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
1185            return ToolResult(success=True, output=result)
1186        except CoinglassError as e:
1187            msg = f"Coinglass: {e}"
1188            if e.suggestion:
1189                msg += f" ({e.suggestion})"
1190            return ToolResult(
1191                success=False, output=None, error=msg)
1192        except Exception as e:
1193            return ToolResult(
1194                success=False, output=None,
1195                error=f"Coinglass: {type(e).__name__}: {e}")
1196 
1197 
1198class HyperliquidWhalePositionsTool(BaseTool):
1199    """Get current whale positions on Hyperliquid."""
1200 
1201    @property
1202    def name(self) -> str:
1203        return "cg_hyperliquid_whale_positions"
1204 
1205    @property
1206    def description(self) -> str:
1207        return """Get current whale positions on Hyperliquid.
1208 
1209Shows large active positions with entry price, PnL, leverage, and margin data.
1210 
1211Examples:
1212- Get whale positions: cg_hyperliquid_whale_positions()"""
1213 
1214    @property
1215    def parameters(self) -> dict:
1216        return {"type": "object", "properties": {}, "required": []}
1217 
1218    async def execute(self, ctx: ToolContext) -> ToolResult:
1219        if not COINGLASS_AVAILABLE:
1220            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
1221 
1222        try:
1223            result = await asyncio.to_thread(get_whale_positions)
1224            if result is None:
1225                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
1226            return ToolResult(success=True, output=result)
1227        except CoinglassError as e:
1228            msg = f"Coinglass: {e}"
1229            if e.suggestion:
1230                msg += f" ({e.suggestion})"
1231            return ToolResult(
1232                success=False, output=None, error=msg)
1233        except Exception as e:
1234            return ToolResult(
1235                success=False, output=None,
1236                error=f"Coinglass: {type(e).__name__}: {e}")
1237 
1238 
1239class HyperliquidPositionsByCoinTool(BaseTool):
1240    """Get wallet positions organized by coin on Hyperliquid."""
1241 
1242    @property
1243    def name(self) -> str:
1244        return "cg_hyperliquid_positions_by_coin"
1245 
1246    @property
1247    def description(self) -> str:
1248        return """Get real-time wallet positions for a specific coin on Hyperliquid.
1249 
1250Shows all open positions for the specified cryptocurrency.
1251 
1252Examples:
1253- Get BTC positions: cg_hyperliquid_positions_by_coin(symbol="BTC")
1254- Get ETH positions: cg_hyperliquid_positions_by_coin(symbol="ETH")"""
1255 
1256    @property
1257    def parameters(self) -> dict:
1258        return {
1259            "type": "object",
1260            "properties": {
1261                "symbol": {"type": "string", "description": "Trading coin (BTC, ETH, SOL, etc.)"}
1262            },
1263            "required": ["symbol"]
1264        }
1265 
1266    async def execute(self, ctx: ToolContext, symbol: str) -> ToolResult:
1267        if not COINGLASS_AVAILABLE:
1268            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
1269 
1270        try:
1271            result = await asyncio.to_thread(get_positions_by_coin, symbol)
1272            if result is None:
1273                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
1274            return ToolResult(success=True, output=result)
1275        except CoinglassError as e:
1276            msg = f"Coinglass: {e}"
1277            if e.suggestion:
1278                msg += f" ({e.suggestion})"
1279            return ToolResult(
1280                success=False, output=None, error=msg)
1281        except Exception as e:
1282            return ToolResult(
1283                success=False, output=None,
1284                error=f"Coinglass: {type(e).__name__}: {e}")
1285 
1286 
1287class HyperliquidPositionDistributionTool(BaseTool):
1288    """Get wallet position distribution on Hyperliquid."""
1289 
1290    @property
1291    def name(self) -> str:
1292        return "cg_hyperliquid_position_distribution"
1293 
1294    @property
1295    def description(self) -> str:
1296        return """Get wallet position distribution on Hyperliquid.
1297 
1298Shows distribution by size tiers including address counts, long/short values, sentiment, and P/L distribution.
1299 
1300Examples:
1301- Get position distribution: cg_hyperliquid_position_distribution()"""
1302 
1303    @property
1304    def parameters(self) -> dict:
1305        return {"type": "object", "properties": {}, "required": []}
1306 
1307    async def execute(self, ctx: ToolContext) -> ToolResult:
1308        if not COINGLASS_AVAILABLE:
1309            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
1310 
1311        try:
1312            result = await asyncio.to_thread(get_position_distribution)
1313            if result is None:
1314                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
1315            return ToolResult(success=True, output=result)
1316        except CoinglassError as e:
1317            msg = f"Coinglass: {e}"
1318            if e.suggestion:
1319                msg += f" ({e.suggestion})"
1320            return ToolResult(
1321                success=False, output=None, error=msg)
1322        except Exception as e:
1323            return ToolResult(
1324                success=False, output=None,
1325                error=f"Coinglass: {type(e).__name__}: {e}")
1326 
1327# ==================== Volume & Flow Tools ====================
1328 
1329class TakerVolumeHistoryTool(BaseTool):
1330    """Get taker buy/sell volume history for a specific trading pair."""
1331 
1332    @property
1333    def name(self) -> str:
1334        return "cg_taker_volume_history"
1335 
1336    @property
1337    def description(self) -> str:
1338        return """Get historical taker buy/sell volume data for a specific trading pair.
1339 
1340Taker volume = aggressive market orders (vs passive limit orders).
1341Higher taker buy volume = bullish pressure.
1342Higher taker sell volume = bearish pressure.
1343 
1344Examples:
1345- Get BTC taker volume on Binance: cg_taker_volume_history(symbol="BTC", exchange="Binance", interval="1h")
1346- Get ETH 4h intervals: cg_taker_volume_history(symbol="ETH", exchange="OKX", interval="4h", limit=50)"""
1347 
1348    @property
1349    def parameters(self) -> dict:
1350        return {
1351            "type": "object",
1352            "properties": {
1353                "symbol": {"type": "string", "description": "Trading coin (BTC, ETH, SOL, etc.)"},
1354                "exchange": {"type": "string", "description": "Exchange name (Binance, OKX, Bybit, etc.)"},
1355                "interval": {"type": "string", "description": "Time interval: 1m, 3m, 5m, 15m, 30m, 1h, 4h, 6h, 8h, 12h, 1d, 1w", "default": "1h"},
1356                "limit": {"type": "integer", "description": "Number of results (default: 1000, max: 4500)", "default": 1000},
1357                "start_time": {"type": "integer", "description": "Start timestamp in seconds"},
1358                "end_time": {"type": "integer", "description": "End timestamp in seconds"}
1359            },
1360            "required": ["symbol", "exchange"]
1361        }
1362 
1363    async def execute(self, ctx: ToolContext, symbol: str, exchange: str, interval: str = "1h", limit: int = 1000,
1364                     start_time: Optional[int] = None, end_time: Optional[int] = None) -> ToolResult:
1365        if not COINGLASS_AVAILABLE:
1366            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
1367 
1368        try:
1369            result = await asyncio.to_thread(get_taker_volume_history, symbol, exchange, interval, limit, start_time, end_time)
1370            if result is None:
1371                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
1372            return ToolResult(success=True, output=result)
1373        except CoinglassError as e:
1374            msg = f"Coinglass: {e}"
1375            if e.suggestion:
1376                msg += f" ({e.suggestion})"
1377            return ToolResult(
1378                success=False, output=None, error=msg)
1379        except Exception as e:
1380            return ToolResult(
1381                success=False, output=None,
1382                error=f"Coinglass: {type(e).__name__}: {e}")
1383 
1384 
1385class AggregatedTakerVolumeTool(BaseTool):
1386    """Get aggregated taker buy/sell volume across all exchanges."""
1387 
1388    @property
1389    def name(self) -> str:
1390        return "cg_aggregated_taker_volume"
1391 
1392    @property
1393    def description(self) -> str:
1394        return """Get aggregated taker buy/sell volume across all exchanges for a coin.
1395 
1396Shows total market pressure across all major exchanges.
1397More comprehensive than single-exchange data.
1398 
1399Examples:
1400- Get BTC aggregated volume: cg_aggregated_taker_volume(symbol="BTC", interval="1h")
1401- Get ETH 4h: cg_aggregated_taker_volume(symbol="ETH", interval="4h", limit=100)"""
1402 
1403    @property
1404    def parameters(self) -> dict:
1405        return {
1406            "type": "object",
1407            "properties": {
1408                "symbol": {"type": "string", "description": "Trading coin (BTC, ETH, SOL, etc.)"},
1409                "exchange_list": {"type": "string", "description": "Comma-separated exchange list (e.g. 'Binance,OKX,Bybit')"},
1410                "interval": {"type": "string", "description": "Time interval: 1m, 3m, 5m, 15m, 30m, 1h, 4h, 6h, 8h, 12h, 1d, 1w", "default": "1h"},
1411                "limit": {"type": "integer", "description": "Number of results (default: 1000, max: 4500)", "default": 1000},
1412                "start_time": {"type": "integer", "description": "Start timestamp in seconds"},
1413                "end_time": {"type": "integer", "description": "End timestamp in seconds"}
1414            },
1415            "required": ["symbol", "exchange_list"]
1416        }
1417 
1418    async def execute(self, ctx: ToolContext, symbol: str, exchange_list: str, interval: str = "1h", limit: int = 1000,
1419                     start_time: Optional[int] = None, end_time: Optional[int] = None) -> ToolResult:
1420        if not COINGLASS_AVAILABLE:
1421            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
1422 
1423        try:
1424            result = await asyncio.to_thread(get_aggregated_taker_volume, symbol, exchange_list, interval, limit, start_time, end_time)
1425            if result is None:
1426                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
1427            return ToolResult(success=True, output=result)
1428        except CoinglassError as e:
1429            msg = f"Coinglass: {e}"
1430            if e.suggestion:
1431                msg += f" ({e.suggestion})"
1432            return ToolResult(
1433                success=False, output=None, error=msg)
1434        except Exception as e:
1435            return ToolResult(
1436                success=False, output=None,
1437                error=f"Coinglass: {type(e).__name__}: {e}")
1438 
1439 
1440class CumulativeVolumeDeltaTool(BaseTool):
1441    """Get Cumulative Volume Delta (CVD) for trend analysis."""
1442 
1443    @property
1444    def name(self) -> str:
1445        return "cg_cumulative_volume_delta"
1446 
1447    @property
1448    def description(self) -> str:
1449        return """Get Cumulative Volume Delta (CVD) history for a trading pair.
1450 
1451CVD = Running total of (taker buy volume - taker sell volume).
1452Rising CVD = accumulation (bullish).
1453Falling CVD = distribution (bearish).
1454Divergences between price and CVD signal trend weakness.
1455 
1456Examples:
1457- Get BTC CVD on Binance: cg_cumulative_volume_delta(symbol="BTC", exchange="Binance", interval="1h")
1458- Get ETH CVD: cg_cumulative_volume_delta(symbol="ETH", exchange="OKX", interval="4h", limit=100)"""
1459 
1460    @property
1461    def parameters(self) -> dict:
1462        return {
1463            "type": "object",
1464            "properties": {
1465                "symbol": {"type": "string", "description": "Trading coin (BTC, ETH, SOL, etc.)"},
1466                "exchange": {"type": "string", "description": "Exchange name (Binance, OKX, Bybit, etc.)"},
1467                "interval": {"type": "string", "description": "Time interval: 1m, 3m, 5m, 15m, 30m, 1h, 4h, 6h, 8h, 12h, 1d, 1w", "default": "1h"},
1468                "limit": {"type": "integer", "description": "Number of results (default: 1000, max: 4500)", "default": 1000},
1469                "start_time": {"type": "integer", "description": "Start timestamp in seconds"},
1470                "end_time": {"type": "integer", "description": "End timestamp in seconds"}
1471            },
1472            "required": ["symbol", "exchange"]
1473        }
1474 
1475    async def execute(self, ctx: ToolContext, symbol: str, exchange: str, interval: str = "1h", limit: int = 1000,
1476                     start_time: Optional[int] = None, end_time: Optional[int] = None) -> ToolResult:
1477        if not COINGLASS_AVAILABLE:
1478            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
1479 
1480        try:
1481            result = await asyncio.to_thread(get_cumulative_volume_delta, symbol, exchange, interval, limit, start_time, end_time)
1482            if result is None:
1483                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
1484            return ToolResult(success=True, output=result)
1485        except CoinglassError as e:
1486            msg = f"Coinglass: {e}"
1487            if e.suggestion:
1488                msg += f" ({e.suggestion})"
1489            return ToolResult(
1490                success=False, output=None, error=msg)
1491        except Exception as e:
1492            return ToolResult(
1493                success=False, output=None,
1494                error=f"Coinglass: {type(e).__name__}: {e}")
1495 
1496 
1497class CoinNetflowTool(BaseTool):
1498    """Get netflow data for all futures coins."""
1499 
1500    @property
1501    def name(self) -> str:
1502        return "cg_coin_netflow"
1503 
1504    @property
1505    def description(self) -> str:
1506        return """Get coin netflow data for all futures coins.
1507 
1508Netflow = Capital flowing into/out of a coin across exchanges.
1509Positive netflow = accumulation (bullish signal).
1510Negative netflow = distribution (bearish signal).
1511 
1512Use for identifying which coins are seeing the strongest capital inflows.
1513 
1514Examples:
1515- Get all coin netflows: cg_coin_netflow()"""
1516 
1517    @property
1518    def parameters(self) -> dict:
1519        return {"type": "object", "properties": {}, "required": []}
1520 
1521    async def execute(self, ctx: ToolContext) -> ToolResult:
1522        if not COINGLASS_AVAILABLE:
1523            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
1524 
1525        try:
1526            result = await asyncio.to_thread(get_coin_netflow)
1527            if result is None:
1528                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
1529            return ToolResult(success=True, output=result)
1530        except CoinglassError as e:
1531            msg = f"Coinglass: {e}"
1532            if e.suggestion:
1533                msg += f" ({e.suggestion})"
1534            return ToolResult(
1535                success=False, output=None, error=msg)
1536        except Exception as e:
1537            return ToolResult(
1538                success=False, output=None,
1539                error=f"Coinglass: {type(e).__name__}: {e}")
1540 
1541 
1542# ==================== Whale Transfer Tools ====================
1543 
1544class WhaleTransferTool(BaseTool):
1545    """Get large on-chain transfers (minimum $10M) across major blockchains."""
1546 
1547    @property
1548    def name(self) -> str:
1549        return "cg_whale_transfers"
1550 
1551    @property
1552    def description(self) -> str:
1553        return """Get large on-chain whale transfers (minimum $10M) within the past 6 months.
1554 
1555Covers major blockchains: Bitcoin, Ethereum, Tron, Ripple, Dogecoin, Litecoin, Polygon, Algorand, Bitcoin Cash, Solana.
1556 
1557Shows transaction hash, asset, amount, exchanges involved, and transfer direction.
1558Useful for tracking institutional movements and market impact events.
1559 
1560Transfer types:
1561- 1 = Inflow (to exchange)
1562- 2 = Outflow (from exchange)
1563- 3 = Internal (between exchange wallets)
1564 
1565Examples:
1566- Get recent whale transfers: cg_whale_transfers()"""
1567 
1568    @property
1569    def parameters(self) -> dict:
1570        return {"type": "object", "properties": {}, "required": []}
1571 
1572    async def execute(self, ctx: ToolContext) -> ToolResult:
1573        if not COINGLASS_AVAILABLE:
1574            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
1575 
1576        try:
1577            result = await asyncio.to_thread(get_whale_transfers)
1578            if result is None:
1579                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
1580            return ToolResult(success=True, output=result)
1581        except CoinglassError as e:
1582            msg = f"Coinglass: {e}"
1583            if e.suggestion:
1584                msg += f" ({e.suggestion})"
1585            return ToolResult(
1586                success=False, output=None, error=msg)
1587        except Exception as e:
1588            return ToolResult(
1589                success=False, output=None,
1590                error=f"Coinglass: {type(e).__name__}: {e}")
1591 
1592 
1593# ==================== Bitcoin ETF Tools ====================
1594 
1595class BTCETFFlowsTool(BaseTool):
1596    """Get Bitcoin ETF flow history (inflows/outflows)."""
1597 
1598    @property
1599    def name(self) -> str:
1600        return "cg_btc_etf_flows"
1601 
1602    @property
1603    def description(self) -> str:
1604        return """Get Bitcoin ETF flow history including daily net inflows and outflows.
1605 
1606Shows institutional money movement into/out of Bitcoin through ETFs.
1607Large inflows = institutional accumulation (bullish).
1608Large outflows = institutional distribution (bearish).
1609 
1610Examples:
1611- Get BTC ETF flows: cg_btc_etf_flows()"""
1612 
1613    @property
1614    def parameters(self) -> dict:
1615        return {"type": "object", "properties": {}, "required": []}
1616 
1617    async def execute(self, ctx: ToolContext) -> ToolResult:
1618        if not COINGLASS_AVAILABLE:
1619            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
1620 
1621        try:
1622            result = await asyncio.to_thread(get_btc_etf_flows)
1623            if result is None:
1624                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
1625            return ToolResult(success=True, output=result)
1626        except CoinglassError as e:
1627            msg = f"Coinglass: {e}"
1628            if e.suggestion:
1629                msg += f" ({e.suggestion})"
1630            return ToolResult(
1631                success=False, output=None, error=msg)
1632        except Exception as e:
1633            return ToolResult(
1634                success=False, output=None,
1635                error=f"Coinglass: {type(e).__name__}: {e}")
1636 
1637 
1638class BTCETFPremiumDiscountTool(BaseTool):
1639    """Get Bitcoin ETF premium/discount rates."""
1640 
1641    @property
1642    def name(self) -> str:
1643        return "cg_btc_etf_premium_discount"
1644 
1645    @property
1646    def description(self) -> str:
1647        return """Get Bitcoin ETF premium/discount rates.
1648 
1649Shows how ETF market prices compare to their net asset value (NAV).
1650Premium (positive) = trading above NAV (high demand).
1651Discount (negative) = trading below NAV (low demand).
1652 
1653Examples:
1654- Get BTC ETF premium/discount: cg_btc_etf_premium_discount()"""
1655 
1656    @property
1657    def parameters(self) -> dict:
1658        return {"type": "object", "properties": {}, "required": []}
1659 
1660    async def execute(self, ctx: ToolContext) -> ToolResult:
1661        if not COINGLASS_AVAILABLE:
1662            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
1663 
1664        try:
1665            result = await asyncio.to_thread(get_btc_etf_premium_discount)
1666            if result is None:
1667                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
1668            return ToolResult(success=True, output=result)
1669        except CoinglassError as e:
1670            msg = f"Coinglass: {e}"
1671            if e.suggestion:
1672                msg += f" ({e.suggestion})"
1673            return ToolResult(
1674                success=False, output=None, error=msg)
1675        except Exception as e:
1676            return ToolResult(
1677                success=False, output=None,
1678                error=f"Coinglass: {type(e).__name__}: {e}")
1679 
1680 
1681class BTCETFHistoryTool(BaseTool):
1682    """Get comprehensive Bitcoin ETF history."""
1683 
1684    @property
1685    def name(self) -> str:
1686        return "cg_btc_etf_history"
1687 
1688    @property
1689    def description(self) -> str:
1690        return """Get comprehensive Bitcoin ETF history.
1691 
1692Includes market price, NAV, premium/discount %, shares outstanding, and net assets.
1693 
1694Examples:
1695- Get IBIT history: cg_btc_etf_history(ticker="IBIT")
1696- Get FBTC history: cg_btc_etf_history(ticker="FBTC")"""
1697 
1698    @property
1699    def parameters(self) -> dict:
1700        return {
1701            "type": "object",
1702            "properties": {
1703                "ticker": {"type": "string", "description": "ETF ticker symbol (e.g. IBIT, FBTC, GBTC)"}
1704            },
1705            "required": ["ticker"]
1706        }
1707 
1708    async def execute(self, ctx: ToolContext, ticker: str) -> ToolResult:
1709        if not COINGLASS_AVAILABLE:
1710            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
1711 
1712        try:
1713            result = await asyncio.to_thread(get_btc_etf_history, ticker)
1714            if result is None:
1715                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
1716            return ToolResult(success=True, output=result)
1717        except CoinglassError as e:
1718            msg = f"Coinglass: {e}"
1719            if e.suggestion:
1720                msg += f" ({e.suggestion})"
1721            return ToolResult(
1722                success=False, output=None, error=msg)
1723        except Exception as e:
1724            return ToolResult(
1725                success=False, output=None,
1726                error=f"Coinglass: {type(e).__name__}: {e}")
1727 
1728 
1729class BTCETFListTool(BaseTool):
1730    """Get list of Bitcoin ETFs."""
1731 
1732    @property
1733    def name(self) -> str:
1734        return "cg_btc_etf_list"
1735 
1736    @property
1737    def description(self) -> str:
1738        return """Get list of Bitcoin ETFs with key status information.
1739 
1740Returns ticker symbols, names, inception dates, and other ETF metadata.
1741 
1742Examples:
1743- Get BTC ETF list: cg_btc_etf_list()"""
1744 
1745    @property
1746    def parameters(self) -> dict:
1747        return {"type": "object", "properties": {}, "required": []}
1748 
1749    async def execute(self, ctx: ToolContext) -> ToolResult:
1750        if not COINGLASS_AVAILABLE:
1751            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
1752 
1753        try:
1754            result = await asyncio.to_thread(get_btc_etf_list)
1755            if result is None:
1756                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
1757            return ToolResult(success=True, output=result)
1758        except CoinglassError as e:
1759            msg = f"Coinglass: {e}"
1760            if e.suggestion:
1761                msg += f" ({e.suggestion})"
1762            return ToolResult(
1763                success=False, output=None, error=msg)
1764        except Exception as e:
1765            return ToolResult(
1766                success=False, output=None,
1767                error=f"Coinglass: {type(e).__name__}: {e}")
1768 
1769 
1770class HKBTCETFFlowsTool(BaseTool):
1771    """Get Hong Kong Bitcoin ETF flow history."""
1772 
1773    @property
1774    def name(self) -> str:
1775        return "cg_hk_btc_etf_flows"
1776 
1777    @property
1778    def description(self) -> str:
1779        return """Get Hong Kong Bitcoin ETF flow history.
1780 
1781Shows ETF flow activity for Bitcoin ETFs in the Hong Kong market.
1782Useful for tracking Asian institutional demand.
1783 
1784Examples:
1785- Get HK BTC ETF flows: cg_hk_btc_etf_flows()"""
1786 
1787    @property
1788    def parameters(self) -> dict:
1789        return {"type": "object", "properties": {}, "required": []}
1790 
1791    async def execute(self, ctx: ToolContext) -> ToolResult:
1792        if not COINGLASS_AVAILABLE:
1793            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
1794 
1795        try:
1796            result = await asyncio.to_thread(get_hk_btc_etf_flows)
1797            if result is None:
1798                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
1799            return ToolResult(success=True, output=result)
1800        except CoinglassError as e:
1801            msg = f"Coinglass: {e}"
1802            if e.suggestion:
1803                msg += f" ({e.suggestion})"
1804            return ToolResult(
1805                success=False, output=None, error=msg)
1806        except Exception as e:
1807            return ToolResult(
1808                success=False, output=None,
1809                error=f"Coinglass: {type(e).__name__}: {e}")
1810 
1811 
1812# ==================== Ethereum & Other ETF Tools ====================
1813 
1814class ETHETFFlowsTool(BaseTool):
1815    """Get Ethereum ETF flow history."""
1816 
1817    @property
1818    def name(self) -> str:
1819        return "cg_eth_etf_flows"
1820 
1821    @property
1822    def description(self) -> str:
1823        return """Get Ethereum ETF flow history including daily net inflows and outflows.
1824 
1825Shows institutional money movement into/out of Ethereum through ETFs.
1826 
1827Examples:
1828- Get ETH ETF flows: cg_eth_etf_flows()"""
1829 
1830    @property
1831    def parameters(self) -> dict:
1832        return {"type": "object", "properties": {}, "required": []}
1833 
1834    async def execute(self, ctx: ToolContext) -> ToolResult:
1835        if not COINGLASS_AVAILABLE:
1836            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
1837 
1838        try:
1839            result = await asyncio.to_thread(get_eth_etf_flows)
1840            if result is None:
1841                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
1842            return ToolResult(success=True, output=result)
1843        except CoinglassError as e:
1844            msg = f"Coinglass: {e}"
1845            if e.suggestion:
1846                msg += f" ({e.suggestion})"
1847            return ToolResult(
1848                success=False, output=None, error=msg)
1849        except Exception as e:
1850            return ToolResult(
1851                success=False, output=None,
1852                error=f"Coinglass: {type(e).__name__}: {e}")
1853 
1854 
1855class ETHETFListTool(BaseTool):
1856    """Get list of Ethereum ETFs."""
1857 
1858    @property
1859    def name(self) -> str:
1860        return "cg_eth_etf_list"
1861 
1862    @property
1863    def description(self) -> str:
1864        return """Get list of Ethereum ETFs with key status information.
1865 
1866Examples:
1867- Get ETH ETF list: cg_eth_etf_list()"""
1868 
1869    @property
1870    def parameters(self) -> dict:
1871        return {"type": "object", "properties": {}, "required": []}
1872 
1873    async def execute(self, ctx: ToolContext) -> ToolResult:
1874        if not COINGLASS_AVAILABLE:
1875            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
1876 
1877        try:
1878            result = await asyncio.to_thread(get_eth_etf_list)
1879            if result is None:
1880                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
1881            return ToolResult(success=True, output=result)
1882        except CoinglassError as e:
1883            msg = f"Coinglass: {e}"
1884            if e.suggestion:
1885                msg += f" ({e.suggestion})"
1886            return ToolResult(
1887                success=False, output=None, error=msg)
1888        except Exception as e:
1889            return ToolResult(
1890                success=False, output=None,
1891                error=f"Coinglass: {type(e).__name__}: {e}")
1892 
1893 
1894class SOLETFFlowsTool(BaseTool):
1895    """Get Solana ETF flow history."""
1896 
1897    @property
1898    def name(self) -> str:
1899        return "cg_sol_etf_flows"
1900 
1901    @property
1902    def description(self) -> str:
1903        return """Get Solana ETF flow history including daily net inflows and outflows.
1904 
1905Examples:
1906- Get SOL ETF flows: cg_sol_etf_flows()"""
1907 
1908    @property
1909    def parameters(self) -> dict:
1910        return {"type": "object", "properties": {}, "required": []}
1911 
1912    async def execute(self, ctx: ToolContext) -> ToolResult:
1913        if not COINGLASS_AVAILABLE:
1914            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
1915 
1916        try:
1917            result = await asyncio.to_thread(get_sol_etf_flows)
1918            if result is None:
1919                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
1920            return ToolResult(success=True, output=result)
1921        except CoinglassError as e:
1922            msg = f"Coinglass: {e}"
1923            if e.suggestion:
1924                msg += f" ({e.suggestion})"
1925            return ToolResult(
1926                success=False, output=None, error=msg)
1927        except Exception as e:
1928            return ToolResult(
1929                success=False, output=None,
1930                error=f"Coinglass: {type(e).__name__}: {e}")
1931 
1932 
1933class XRPETFFlowsTool(BaseTool):
1934    """Get XRP ETF flow history."""
1935 
1936    @property
1937    def name(self) -> str:
1938        return "cg_xrp_etf_flows"
1939 
1940    @property
1941    def description(self) -> str:
1942        return """Get XRP ETF flow history including daily net inflows and outflows.
1943 
1944Examples:
1945- Get XRP ETF flows: cg_xrp_etf_flows()"""
1946 
1947    @property
1948    def parameters(self) -> dict:
1949        return {"type": "object", "properties": {}, "required": []}
1950 
1951    async def execute(self, ctx: ToolContext) -> ToolResult:
1952        if not COINGLASS_AVAILABLE:
1953            return ToolResult(success=False, output=None, error="Coinglass tools not available.")
1954 
1955        try:
1956            result = await asyncio.to_thread(get_xrp_etf_flows)
1957            if result is None:
1958                return ToolResult(success=False, output=None, error="No data returned. The API returned an empty result.")
1959            return ToolResult(success=True, output=result)
1960        except CoinglassError as e:
1961            msg = f"Coinglass: {e}"
1962            if e.suggestion:
1963                msg += f" ({e.suggestion})"
1964            return ToolResult(
1965                success=False, output=None, error=msg)
1966        except Exception as e:
1967            return ToolResult(
1968                success=False, output=None,
1969                error=f"Coinglass: {type(e).__name__}: {e}")
1970 
1971 
1972