1#!/usr/bin/env python3
2"""
3Coinglass Volume & Flow Module
4 
5Provides taker volume history, aggregated taker volume,
6cumulative volume delta (CVD), coin netflow, and vol-weighted OHLC.
7"""
8 
9import sys
10import json
11import argparse
12from typing import Dict, Any, Optional, List
13 
14from ._api import cg_request
15 
16 
17def _to_pair(symbol: str) -> str:
18    """Convert symbol to trading pair (BTC → BTCUSDT)."""
19    s = symbol.upper()
20    return s if s.endswith("USDT") else f"{s}USDT"
21 
22 
23def get_taker_volume_history(
24    symbol: str = "BTC",
25    exchange: str = "Binance",
26    interval: str = "1h",
27    limit: int = 1000,
28    start_time: int = None,
29    end_time: int = None
30) -> Optional[List[Dict[str, Any]]]:
31    """
32    Get taker buy/sell volume history for a coin.
33 
34    Args:
35        symbol: Coin symbol.
36        exchange: Exchange name.
37        interval: Time interval (1m, 5m, 15m, 30m, 1h, 4h, 12h, 1d).
38        limit: Number of results (default 1000, max 4500).
39        start_time: Start timestamp in seconds.
40        end_time: End timestamp in seconds.
41    """
42    params = {
43        "symbol": _to_pair(symbol),
44        "exchange": exchange,
45        "interval": interval,
46    }
47    if limit and limit != 1000:
48        params["limit"] = limit
49    if start_time:
50        params["startTime"] = start_time
51    if end_time:
52        params["endTime"] = end_time
53    return cg_request(
54        "api/futures/v2/taker-buy-sell-volume/history",
55        params=params
56    )
57 
58 
59def get_aggregated_taker_volume(
60    symbol: str = "BTC",
61    interval: str = "h4"
62) -> Optional[List[Dict[str, Any]]]:
63    """
64    Get aggregated taker buy/sell volume history across exchanges.
65 
66    Args:
67        symbol: Coin symbol.
68        interval: Time interval.
69    """
70    return cg_request(
71        "api/futures/aggregated-taker-buy-sell-volume/history",
72        params={"symbol": _to_pair(symbol), "interval": interval}
73    )
74 
75 
76def get_cumulative_volume_delta(
77    symbol: str = "BTC",
78    exchange: str = "Binance",
79    interval: str = "1h",
80    limit: int = 1000,
81    start_time: int = None,
82    end_time: int = None
83) -> Optional[List[Dict[str, Any]]]:
84    """
85    Get cumulative volume delta (CVD) history.
86 
87    CVD tracks net buying vs selling pressure over time.
88    Rising CVD = accumulation (bullish).
89    Falling CVD = distribution (bearish).
90 
91    Args:
92        symbol: Coin symbol.
93        exchange: Exchange name.
94        interval: Time interval (1m, 5m, 15m, 30m, 1h, 4h, 12h, 1d).
95        limit: Number of results (default 1000, max 4500).
96        start_time: Start timestamp in seconds.
97        end_time: End timestamp in seconds.
98    """
99    params = {
100        "symbol": _to_pair(symbol),
101        "exchange": exchange,
102        "interval": interval,
103    }
104    if limit and limit != 1000:
105        params["limit"] = limit
106    if start_time:
107        params["startTime"] = start_time
108    if end_time:
109        params["endTime"] = end_time
110    return cg_request(
111        "api/futures/cvd/history",
112        params=params
113    )
114 
115 
116def get_coin_netflow(
117    symbol: Optional[str] = None
118) -> Optional[List[Dict[str, Any]]]:
119    """
120    Get exchange netflow data by coin.
121 
122    Shows net inflow/outflow of coins across exchanges.
123 
124    Args:
125        symbol: Optional coin filter.
126    """
127    params = {}
128    if symbol:
129        params["symbol"] = symbol
130    return cg_request("api/futures/netflow-list", params=params or None)
131 
132 
133def get_volume_ohlc_history(
134    symbol: str = "BTC",
135    exchange: str = "Binance",
136    interval: str = "1h",
137    limit: int = 1000,
138    start_time: int = None,
139    end_time: int = None
140) -> Optional[List[Dict[str, Any]]]:
141    """
142    Get volume-weighted OHLC history.
143 
144    Args:
145        symbol: Coin symbol.
146        exchange: Exchange name.
147        interval: Time interval (1m, 5m, 15m, 30m, 1h, 4h, 12h, 1d).
148        limit: Number of results (default 1000, max 4500).
149        start_time: Start timestamp in seconds.
150        end_time: End timestamp in seconds.
151    """
152    params = {
153        "symbol": _to_pair(symbol),
154        "exchange": exchange,
155        "interval": interval,
156    }
157    if limit and limit != 1000:
158        params["limit"] = limit
159    if start_time:
160        params["startTime"] = start_time
161    if end_time:
162        params["endTime"] = end_time
163    return cg_request(
164        "api/futures/vol-weight-ohlc-history",
165        params=params
166    )
167 
168 
169def main():
170    """CLI entry point."""
171    parser = argparse.ArgumentParser(
172        description="Coinglass Volume & Flow Tools"
173    )
174    parser.add_argument("action", choices=[
175        "taker", "aggregated", "cvd", "netflow", "ohlc"
176    ])
177    parser.add_argument("--symbol", "-s", default="BTC")
178    parser.add_argument("--exchange", "-e", default=None)
179    parser.add_argument("--interval", "-i", default="h4")
180    args = parser.parse_args()
181 
182    actions = {
183        "taker": lambda: get_taker_volume_history(
184            args.symbol, args.exchange or "Binance", args.interval
185        ),
186        "aggregated": lambda: get_aggregated_taker_volume(
187            args.symbol, args.interval
188        ),
189        "cvd": lambda: get_cumulative_volume_delta(
190            args.symbol, args.exchange or "Binance", args.interval
191        ),
192        "netflow": lambda: get_coin_netflow(args.symbol),
193        "ohlc": lambda: get_volume_ohlc_history(
194            args.symbol, args.exchange or "Binance", args.interval
195        ),
196    }
197 
198    try:
199        result = actions[args.action]()
200        print(json.dumps(result, indent=2))
201    except Exception as e:
202        print(f"Error: {e}", file=sys.stderr)
203        sys.exit(1)
204 
205 
206if __name__ == "__main__":
207    main()
208