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