1#!/usr/bin/env python3
2"""
3Coinglass Liquidations Advanced Module
4 
5Provides detailed liquidation data: coin/pair history,
6coin list aggregation, liquidation orders, and heatmap data.
7"""
8 
9import sys
10import json
11import argparse
12from typing import Dict, Any, List, Optional
13 
14from ._api import cg_request
15 
16 
17def get_coin_liquidation_history(
18    symbol: str = "BTC",
19    interval: str = "h4"
20) -> Optional[List[Dict[str, Any]]]:
21    """
22    Get aggregated liquidation history for a coin.
23 
24    Args:
25        symbol: Coin symbol (BTC, ETH, SOL, etc.)
26        interval: Time interval (h1, h4, h12, h24).
27    """
28    return cg_request(
29        "api/futures/liquidation/aggregated-history",
30        params={"symbol": symbol, "interval": interval}
31    )
32 
33 
34def get_pair_liquidation_history(
35    symbol: str = "BTC",
36    exchange: str = "Binance",
37    interval: str = "h4"
38) -> Optional[List[Dict[str, Any]]]:
39    """
40    Get liquidation history for a specific trading pair.
41 
42    Args:
43        symbol: Coin symbol.
44        exchange: Exchange name.
45        interval: Time interval (h1, h4, h12, h24).
46    """
47    return cg_request(
48        "api/futures/liquidation/history",
49        params={
50            "symbol": symbol,
51            "exchange": exchange,
52            "interval": interval,
53        }
54    )
55 
56 
57def get_liquidation_coin_list(
58    symbol: Optional[str] = None
59) -> Optional[List[Dict[str, Any]]]:
60    """
61    Get liquidation summary aggregated by coin.
62 
63    Args:
64        symbol: Optional coin filter.
65    """
66    params = {}
67    if symbol:
68        params["symbol"] = symbol
69    return cg_request(
70        "api/futures/liquidation/coin-list",
71        params=params or None
72    )
73 
74 
75def get_liquidation_orders(
76    symbol: str = "BTC",
77    exchange: Optional[str] = None
78) -> Optional[List[Dict[str, Any]]]:
79    """
80    Get recent large liquidation orders.
81 
82    Args:
83        symbol: Coin symbol.
84        exchange: Optional exchange filter.
85    """
86    params = {"symbol": symbol}
87    if exchange:
88        params["exchange"] = exchange
89    return cg_request("api/futures/liquidation/order", params=params)
90 
91 
92def get_liquidation_heatmap(
93    symbol: str = "BTC",
94    exchange: str = "Binance"
95) -> Optional[Dict[str, Any]]:
96    """
97    Get liquidation heatmap data (price levels with liquidation density).
98 
99    Args:
100        symbol: Coin symbol.
101        exchange: Exchange name.
102    """
103    return cg_request(
104        "api/futures/liquidation/heatmap/model1",
105        params={"symbol": symbol, "exchange": exchange}
106    )
107 
108 
109def main():
110    """CLI entry point."""
111    parser = argparse.ArgumentParser(
112        description="Coinglass Liquidation Advanced Tools"
113    )
114    parser.add_argument("action", choices=[
115        "coin-history", "pair-history", "coin-list",
116        "orders", "heatmap"
117    ])
118    parser.add_argument("--symbol", "-s", default="BTC")
119    parser.add_argument("--exchange", "-e", default="Binance")
120    parser.add_argument("--interval", "-i", default="h4")
121    args = parser.parse_args()
122 
123    actions = {
124        "coin-history": lambda: get_coin_liquidation_history(
125            args.symbol, args.interval
126        ),
127        "pair-history": lambda: get_pair_liquidation_history(
128            args.symbol, args.exchange, args.interval
129        ),
130        "coin-list": lambda: get_liquidation_coin_list(args.symbol),
131        "orders": lambda: get_liquidation_orders(
132            args.symbol, args.exchange
133        ),
134        "heatmap": lambda: get_liquidation_heatmap(
135            args.symbol, args.exchange
136        ),
137    }
138 
139    try:
140        result = actions[args.action]()
141        print(json.dumps(result, indent=2))
142    except Exception as e:
143        print(f"Error: {e}", file=sys.stderr)
144        sys.exit(1)
145 
146 
147if __name__ == "__main__":
148    main()
149