1#!/usr/bin/env python3
2"""
3Coinglass Funding Rate Module
4 
5Fetch funding rates across major cryptocurrency exchanges including
6Binance, OKX, Bybit, KuCoin, MEXC, Bitfinex, Kraken, and more.
7 
8Funding rates are fees set by cryptocurrency exchanges to maintain balance
9between contract price and underlying asset price in perpetual futures contracts.
10Positive rates mean longs pay shorts; negative rates mean shorts pay longs.
11 
12Dependencies:
13- requests: For HTTP API calls
14- python-dotenv: For environment variable management
15 
16Environment Variables Required:
17- COINGLASS_API_KEY: Your Coinglass API key
18 
19Usage Example:
20    from tools.coinglass.funding_rate import get_funding_rates, get_symbol_funding_rate
21 
22    # Get all funding rates for BTC
23    rates = get_funding_rates(symbol="BTC")
24 
25    # Get funding rate for specific exchange
26    binance_rate = get_symbol_funding_rate(symbol="BTC", exchange="Binance")
27 
28CLI Usage:
29    python funding_rate.py --symbol BTC
30    python funding_rate.py --symbol ETH --exchange Binance
31    python funding_rate.py --all
32"""
33 
34import os
35import sys
36import json
37import argparse
38from typing import Dict, Any, Optional, List
39 
40try:
41    from dotenv import load_dotenv
42    project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), '../../../..'))
43    load_dotenv(os.path.join(project_root, '.env'))
44except ImportError:
45    pass
46 
47import requests
48from core.http_client import proxied_get
49 
50 
51def _fmt_rate(val):
52    """Format a funding rate value as a display string with % sign.
53    Coinglass returns values already in percent (0.01 means 0.01%), so NO multiplication."""
54    if val is None:
55        return None
56    sign = "+" if val >= 0 else ""
57    return f"{sign}{val:.4f}%"
58 
59 
60def _with_rate_unit(obj: dict, field: str):
61    """Normalize any funding-rate field to a display-safe percent string."""
62    if field not in obj or obj.get(field) is None:
63        return
64    obj[field] = _fmt_rate(_rate_num(obj, field, 0.0))
65 
66 
67def _rate_num(obj: dict, field: str, default: float = 0.0) -> float:
68    """Read numeric funding rate safely from number or percent-string values."""
69    v = obj.get(field)
70    if isinstance(v, (int, float)):
71        return float(v)
72    if isinstance(v, str):
73        s = v.strip()
74        if s.endswith('%'):
75            s = s[:-1]
76        try:
77            return float(s)
78        except ValueError:
79            return default
80    return default
81 
82# Coinglass Configuration
83BASE_URL = "https://open-api.coinglass.com/public/v2"
84HEADER_KEY = "coinglassSecret"
85 
86# Supported exchanges
87EXCHANGES = [
88    "Binance", "OKX", "Bybit", "KuCoin", "MEXC", "CoinEx",
89    "Bitfinex", "Kraken", "dYdX", "Gate", "Bitmex"
90]
91 
92# Common symbols
93SYMBOLS = ["BTC", "ETH", "SOL", "BNB", "XRP", "DOGE", "ADA", "AVAX", "LINK", "MATIC"]
94 
95 
96def _get_api_key() -> Optional[str]:
97    """Get Coinglass API key from environment."""
98    return os.getenv("COINGLASS_API_KEY")
99 
100 
101def get_funding_rates(symbol: Optional[str] = None) -> Optional[Dict[str, Any]]:
102    """
103    Fetch funding rates across all exchanges.
104 
105    Args:
106        symbol: Optional symbol filter (BTC, ETH, etc.). If None, returns all.
107 
108    Returns:
109        Dictionary with funding rate data:
110        {
111            "symbol": "BTC",
112            "uMarginList": [
113                {
114                    "exchangeName": "Binance",
115                    "rate": 0.0058,  # Funding rate already in % (i.e. 0.0058%)
116                    "nextFundingTime": 1765497600000,  # Unix ms
117                    "fundingIntervalHours": 8
118                },
119                ...
120            ]
121        }
122        Returns None if request fails.
123 
124    Example:
125        rates = get_funding_rates("BTC")
126        for exchange in rates["data"]:
127            if exchange["symbol"] == "BTC":
128                for rate_info in exchange["uMarginList"]:
129                    print(f"{rate_info['exchangeName']}: {rate_info['rate']:.4f}%")
130    """
131    api_key = _get_api_key()
132    if not api_key:
133        print("Error: COINGLASS_API_KEY not found in environment", file=sys.stderr)
134        return None
135 
136    url = f"{BASE_URL}/funding"
137    headers = {
138        "accept": "application/json",
139        HEADER_KEY: api_key
140    }
141 
142    try:
143        response = proxied_get(url, headers=headers, timeout=30)
144        response.raise_for_status()
145        data = response.json()
146 
147        if data.get("code") != "0":
148            print(f"API Error: {data.get('msg', 'Unknown error')}", file=sys.stderr)
149            return None
150 
151        # Normalize all funding-rate fields to strings with `%` suffix.
152        for symbol_entry in data.get("data", []):
153            for margin_list_key in ("uMarginList", "cMarginList"):
154                for ex in symbol_entry.get(margin_list_key, []):
155                    _with_rate_unit(ex, "rate")
156                    _with_rate_unit(ex, "predictedRate")
157 
158        if symbol:
159            # Filter for specific symbol
160            filtered = [d for d in data.get("data", []) if d.get("symbol", "").upper() == symbol.upper()]
161            return {"code": "0", "msg": "success", "data": filtered}
162 
163        return data
164 
165    except requests.exceptions.RequestException as e:
166        print(f"Request failed: {e}", file=sys.stderr)
167        return None
168    except json.JSONDecodeError as e:
169        print(f"Failed to parse response: {e}", file=sys.stderr)
170        return None
171 
172 
173def get_symbol_funding_rate(
174    symbol: str,
175    exchange: Optional[str] = None
176) -> Optional[Dict[str, Any]]:
177    """
178    Get funding rate for a specific symbol and optionally a specific exchange.
179 
180    Args:
181        symbol: Symbol to query (BTC, ETH, etc.)
182        exchange: Optional exchange name (Binance, OKX, Bybit, etc.)
183 
184    Returns:
185        Dictionary with funding rate info:
186        {
187            "symbol": "BTC",
188            "exchange": "Binance",  # or "average" if no exchange specified
189            "rate": "+0.0058%",
190            "next_funding_time": 1765497600000,
191            "funding_interval_hours": 8,
192            "predicted_rate": "+0.0059%"  # if available
193        }
194        Returns None if not found.
195 
196    Example:
197        rate = get_symbol_funding_rate("BTC", "Binance")
198        if rate:
199            print(f"BTC funding rate on Binance: {rate['rate']}")
200    """
201    data = get_funding_rates(symbol)
202    if not data or not data.get("data"):
203        return None
204 
205    symbol_data = data["data"][0] if data["data"] else None
206    if not symbol_data:
207        return None
208 
209    if exchange:
210        # Find specific exchange
211        for rate_info in symbol_data.get("uMarginList", []):
212            if rate_info.get("exchangeName", "").lower() == exchange.lower():
213                rate_num = _rate_num(rate_info, "rate", 0.0)
214                predicted_num = _rate_num(rate_info, "predictedRate", None) if rate_info.get("predictedRate") is not None else None
215                return {
216                    "symbol": symbol.upper(),
217                    "exchange": rate_info.get("exchangeName"),
218                    "rate": _fmt_rate(rate_num),
219                    "next_funding_time": rate_info.get("nextFundingTime"),
220                    "funding_interval_hours": rate_info.get("fundingIntervalHours"),
221                    "predicted_rate": _fmt_rate(predicted_num) if predicted_num is not None else None
222                }
223        return None
224    else:
225        # Return average across all exchanges
226        rates = [_rate_num(r, "rate", 0.0) for r in symbol_data.get("uMarginList", []) if (r.get("rate") is not None)]
227        if not rates:
228            return None
229        avg_rate = sum(rates) / len(rates)
230        return {
231            "symbol": symbol.upper(),
232            "exchange": "average",
233            "rate": _fmt_rate(avg_rate),
234            "num_exchanges": len(rates),
235            "exchanges_data": symbol_data.get("uMarginList", [])
236        }
237 
238 
239def get_funding_rate_by_exchange(exchange: str) -> Optional[List[Dict[str, Any]]]:
240    """
241    Get funding rates for all symbols on a specific exchange.
242 
243    Args:
244        exchange: Exchange name (Binance, OKX, Bybit, etc.)
245 
246    Returns:
247        List of funding rate dicts for each symbol on the exchange:
248        [
249            {"symbol": "BTC", "rate": "+0.0058%"},
250            {"symbol": "ETH", "rate": "+0.0042%"},
251            ...
252        ]
253        Returns None if request fails.
254    """
255    data = get_funding_rates()
256    if not data or not data.get("data"):
257        return None
258 
259    results = []
260    for symbol_data in data["data"]:
261        for rate_info in symbol_data.get("uMarginList", []):
262            if rate_info.get("exchangeName", "").lower() == exchange.lower():
263                rate_num = _rate_num(rate_info, "rate", 0.0)
264                predicted_num = _rate_num(rate_info, "predictedRate", None) if rate_info.get("predictedRate") is not None else None
265                results.append({
266                    "symbol": symbol_data.get("symbol"),
267                    "rate": _fmt_rate(rate_num),
268                    "next_funding_time": rate_info.get("nextFundingTime"),
269                    "funding_interval_hours": rate_info.get("fundingIntervalHours"),
270                    "predicted_rate": _fmt_rate(predicted_num) if predicted_num is not None else None
271                })
272 
273    return sorted(results, key=lambda x: abs(_rate_num(x, "rate", 0.0)), reverse=True) if results else None
274 
275 
276def analyze_funding_opportunity(symbol: str, threshold: float = 0.01) -> Optional[Dict[str, Any]]:
277    """
278    Analyze funding rate arbitrage opportunities across exchanges.
279 
280    Args:
281        symbol: Symbol to analyze (BTC, ETH, etc.)
282        threshold: Minimum rate difference to flag (default 0.01 = 1%)
283 
284    Returns:
285        Dictionary with arbitrage analysis:
286        {
287            "symbol": "BTC",
288            "highest": {"exchange": "CoinEx", "rate": "+0.0200%"},
289            "lowest": {"exchange": "Kraken", "rate": "-0.0010%"},
290            "spread": "+0.0210%",
291            "opportunity": True/False,
292            "all_rates": [...]
293        }
294    """
295    data = get_funding_rates(symbol)
296    if not data or not data.get("data") or not data["data"]:
297        return None
298 
299    symbol_data = data["data"][0]
300    rates_list = symbol_data.get("uMarginList", [])
301 
302    if not rates_list:
303        return None
304 
305    # Extract rates with exchange names
306    rates = [
307        {
308            "exchange": r.get("exchangeName"),
309            "rate": _fmt_rate(_rate_num(r, "rate", 0.0))
310        }
311        for r in rates_list
312        if (r.get("rate") is not None)
313    ]
314 
315    if not rates:
316        return None
317 
318    sorted_rates = sorted(rates, key=lambda x: _rate_num(x, "rate", 0.0))
319    lowest = sorted_rates[0]
320    highest = sorted_rates[-1]
321    spread = _rate_num(highest, "rate", 0.0) - _rate_num(lowest, "rate", 0.0)
322 
323    return {
324        "symbol": symbol.upper(),
325        "highest": highest,
326        "lowest": lowest,
327        "spread": _fmt_rate(spread),
328        "opportunity": spread >= threshold,
329        "all_rates": sorted_rates
330    }
331 
332 
333def main():
334    """CLI entry point."""
335    parser = argparse.ArgumentParser(description="Fetch Coinglass funding rates")
336    parser.add_argument("--symbol", "-s", help="Symbol to query (BTC, ETH, etc.)")
337    parser.add_argument("--exchange", "-e", help="Specific exchange (Binance, OKX, etc.)")
338    parser.add_argument("--all", "-a", action="store_true", help="Get all funding rates")
339    parser.add_argument("--analyze", action="store_true", help="Analyze arbitrage opportunities")
340    parser.add_argument("--by-exchange", help="Get all rates for an exchange")
341    parser.add_argument("--json", "-j", action="store_true", help="Output as JSON")
342 
343    args = parser.parse_args()
344 
345    if args.analyze and args.symbol:
346        result = analyze_funding_opportunity(args.symbol)
347        if result:
348            if args.json:
349                print(json.dumps(result, indent=2))
350            else:
351                print(f"\n{result['symbol']} Funding Rate Analysis")
352                print("=" * 50)
353                print(f"Highest: {result['highest']['exchange']}: {result['highest']['rate']}")
354                print(f"Lowest:  {result['lowest']['exchange']}: {result['lowest']['rate']}")
355                print(f"Spread:  {result['spread']}")
356                print(f"Opportunity: {'YES' if result['opportunity'] else 'NO'}")
357        else:
358            print(f"No data found for {args.symbol}")
359        return
360 
361    if args.by_exchange:
362        result = get_funding_rate_by_exchange(args.by_exchange)
363        if result:
364            if args.json:
365                print(json.dumps(result, indent=2))
366            else:
367                print(f"\n{args.by_exchange} Funding Rates")
368                print("=" * 50)
369                for r in result[:20]:  # Top 20
370                    print(f"{r['symbol']:10s} {r['rate']:>10s}")
371        else:
372            print(f"No data found for exchange {args.by_exchange}")
373        return
374 
375    if args.symbol:
376        result = get_symbol_funding_rate(args.symbol, args.exchange)
377        if result:
378            if args.json:
379                print(json.dumps(result, indent=2))
380            else:
381                print(f"\n{result['symbol']} Funding Rate")
382                print("=" * 50)
383                if args.exchange:
384                    print(f"Exchange: {result['exchange']}")
385                    print(f"Rate: {result['rate']}")
386                    if result.get('predicted_rate'):
387                        print(f"Predicted: {result['predicted_rate']}")
388                else:
389                    print(f"Average Rate: {result['rate']}")
390                    print(f"Exchanges: {result['num_exchanges']}")
391        else:
392            print(f"No funding rate found for {args.symbol}" + (f" on {args.exchange}" if args.exchange else ""))
393        return
394 
395    if args.all:
396        result = get_funding_rates()
397        if result and result.get("data"):
398            if args.json:
399                print(json.dumps(result, indent=2))
400            else:
401                print("\nAll Funding Rates")
402                print("=" * 50)
403                for symbol_data in result["data"][:20]:  # First 20 symbols
404                    symbol = symbol_data.get("symbol", "???")
405                    rates = symbol_data.get("uMarginList", [])
406                    if rates:
407                        numeric_rates = [_rate_num(r, "rate", 0.0) for r in rates if (r.get("rate") is not None)]
408                        if numeric_rates:
409                            avg = sum(numeric_rates) / len(numeric_rates)
410                            print(f"{symbol:10s} avg: {_fmt_rate(avg)}")
411        else:
412            print("Failed to fetch funding rates")
413        return
414 
415    # Default: show help
416    parser.print_help()
417 
418 
419if __name__ == "__main__":
420    main()
421