1#!/usr/bin/env python3
2"""
3CoinGecko Derivatives Tools
4 
5Tools for fetching derivatives market data including tickers and exchanges.
6"""
7 
8import os
9from dotenv import load_dotenv
10import json
11import argparse
12from typing import Dict, Any
13 
14from core.http_client import proxied_get
15 
16# Load environment variables
17load_dotenv()
18 
19 
20# MCP Tool Schemas
21MCP_DERIVATIVES_SCHEMA = {
22    "name": "cg_derivatives",
23    "title": "CoinGecko Derivatives Tickers",
24    "description": "Get all derivatives tickers (perpetuals, futures).",
25    "inputSchema": {
26        "type": "object",
27        "properties": {
28            "include_tickers": {
29                "type": "string",
30                "description": "Filter: all, unexpired (default)",
31                "default": "unexpired",
32                "enum": ["all", "unexpired"]
33            }
34        },
35        "additionalProperties": False
36    }
37}
38 
39MCP_DERIVATIVES_EXCHANGES_SCHEMA = {
40    "name": "cg_derivatives_exchanges",
41    "title": "CoinGecko Derivatives Exchanges",
42    "description": "Get list of derivatives exchanges with ranking.",
43    "inputSchema": {
44        "type": "object",
45        "properties": {
46            "order": {
47                "type": "string",
48                "description": "Sort by: name_asc, name_desc, open_interest_btc_asc, open_interest_btc_desc, trade_volume_24h_btc_asc, trade_volume_24h_btc_desc",
49                "default": "open_interest_btc_desc"
50            },
51            "per_page": {
52                "type": "integer",
53                "description": "Results per page (max 100)",
54                "default": 50,
55                "minimum": 1,
56                "maximum": 100
57            }
58        },
59        "additionalProperties": False
60    }
61}
62 
63MCP_CATEGORIES_SCHEMA = {
64    "name": "cg_categories",
65    "title": "CoinGecko Coin Categories",
66    "description": "Get coin categories with market data (DeFi, L1, L2, Memes, etc.).",
67    "inputSchema": {
68        "type": "object",
69        "properties": {
70            "order": {
71                "type": "string",
72                "description": "Sort by: market_cap_desc, market_cap_asc, name_desc, name_asc, market_cap_change_24h_desc, market_cap_change_24h_asc",
73                "default": "market_cap_desc"
74            }
75        },
76        "additionalProperties": False
77    }
78}
79 
80 
81def get_api_key() -> str:
82    """Get CoinGecko API key from environment."""
83    api_key = os.getenv("COINGECKO_API_KEY")
84    if not api_key:
85        raise ValueError("COINGECKO_API_KEY environment variable is required")
86    return api_key
87 
88 
89def get_derivatives(include_tickers: str = "unexpired") -> Dict[str, Any]:
90    """
91    Get all derivatives tickers.
92 
93    Args:
94        include_tickers: Filter - all or unexpired
95 
96    Returns:
97        Dictionary with derivatives tickers
98    """
99    api_key = get_api_key()
100 
101    url = "https://pro-api.coingecko.com/api/v3/derivatives"
102    headers = {"x-cg-pro-api-key": api_key}
103    params = {"include_tickers": include_tickers}
104 
105    response = proxied_get(url, headers=headers, params=params, timeout=15)
106    response.raise_for_status()
107    data = response.json()
108 
109    tickers = []
110    for item in data:
111        tickers.append({
112            "market": item.get("market", ""),
113            "symbol": item.get("symbol", ""),
114            "index_id": item.get("index_id"),
115            "price": item.get("price"),
116            "price_percentage_change_24h": item.get("price_percentage_change_24h"),
117            "contract_type": item.get("contract_type"),
118            "index": item.get("index"),
119            "basis": item.get("basis"),
120            "spread": item.get("spread"),
121            "funding_rate": item.get("funding_rate"),
122            "open_interest": item.get("open_interest"),
123            "volume_24h": item.get("volume_24h"),
124            "last_traded_at": item.get("last_traded_at"),
125            "expired_at": item.get("expired_at")
126        })
127 
128    return {
129        "tickers": tickers,
130        "count": len(tickers),
131        "filter": include_tickers
132    }
133 
134 
135def get_derivatives_exchanges(
136    order: str = "open_interest_btc_desc",
137    per_page: int = 50
138) -> Dict[str, Any]:
139    """
140    Get list of derivatives exchanges with ranking.
141 
142    Args:
143        order: Sort order
144        per_page: Results per page (max 100)
145 
146    Returns:
147        Dictionary with derivatives exchanges
148    """
149    api_key = get_api_key()
150 
151    url = "https://pro-api.coingecko.com/api/v3/derivatives/exchanges"
152    headers = {"x-cg-pro-api-key": api_key}
153    params = {
154        "order": order,
155        "per_page": min(per_page, 100)
156    }
157 
158    response = proxied_get(url, headers=headers, params=params, timeout=15)
159    response.raise_for_status()
160    data = response.json()
161 
162    exchanges = []
163    for item in data:
164        exchanges.append({
165            "id": item.get("id", ""),
166            "name": item.get("name", ""),
167            "open_interest_btc": item.get("open_interest_btc"),
168            "trade_volume_24h_btc": item.get("trade_volume_24h_btc"),
169            "number_of_perpetual_pairs": item.get("number_of_perpetual_pairs"),
170            "number_of_futures_pairs": item.get("number_of_futures_pairs"),
171            "image": item.get("image"),
172            "year_established": item.get("year_established"),
173            "country": item.get("country"),
174            "url": item.get("url")
175        })
176 
177    return {
178        "exchanges": exchanges,
179        "count": len(exchanges),
180        "order": order
181    }
182 
183 
184def get_categories(order: str = "market_cap_desc") -> Dict[str, Any]:
185    """
186    Get coin categories with market data.
187 
188    Args:
189        order: Sort order (market_cap_desc, market_cap_change_24h_desc, etc.)
190 
191    Returns:
192        Dictionary with coin categories
193    """
194    api_key = get_api_key()
195 
196    url = "https://pro-api.coingecko.com/api/v3/coins/categories"
197    headers = {"x-cg-pro-api-key": api_key}
198    params = {"order": order}
199 
200    response = proxied_get(url, headers=headers, params=params, timeout=15)
201    response.raise_for_status()
202    data = response.json()
203 
204    categories = []
205    for item in data:
206        categories.append({
207            "id": item.get("id", ""),
208            "name": item.get("name", ""),
209            "market_cap": item.get("market_cap"),
210            "market_cap_change_24h": item.get("market_cap_change_24h"),
211            "content": item.get("content"),
212            "top_3_coins": item.get("top_3_coins", []),
213            "volume_24h": item.get("volume_24h"),
214            "updated_at": item.get("updated_at")
215        })
216 
217    return {
218        "categories": categories,
219        "count": len(categories),
220        "order": order
221    }
222 
223 
224def main():
225    """CLI interface for derivatives tools."""
226    parser = argparse.ArgumentParser(
227        description="CoinGecko Derivatives Tools",
228        formatter_class=argparse.RawDescriptionHelpFormatter
229    )
230 
231    subparsers = parser.add_subparsers(dest="command")
232 
233    # Derivatives tickers command
234    deriv_parser = subparsers.add_parser("derivatives", help="Get derivatives tickers")
235    deriv_parser.add_argument("--filter", default="unexpired", choices=["all", "unexpired"])
236 
237    # Exchanges command
238    exch_parser = subparsers.add_parser("exchanges", help="Get derivatives exchanges")
239    exch_parser.add_argument("--order", default="open_interest_btc_desc")
240    exch_parser.add_argument("--limit", type=int, default=50)
241 
242    # Categories command
243    cat_parser = subparsers.add_parser("categories", help="Get coin categories")
244    cat_parser.add_argument("--order", default="market_cap_desc")
245 
246    parser.add_argument("--schema", action="store_true", help="Output MCP schema")
247 
248    args = parser.parse_args()
249 
250    if args.schema:
251        schemas = {
252            "derivatives": MCP_DERIVATIVES_SCHEMA,
253            "derivatives_exchanges": MCP_DERIVATIVES_EXCHANGES_SCHEMA,
254            "categories": MCP_CATEGORIES_SCHEMA
255        }
256        print(json.dumps(schemas, indent=2))
257        return 0
258 
259    try:
260        if args.command == "derivatives":
261            result = get_derivatives(args.filter)
262        elif args.command == "exchanges":
263            result = get_derivatives_exchanges(args.order, args.limit)
264        elif args.command == "categories":
265            result = get_categories(args.order)
266        else:
267            parser.print_help()
268            return 0
269 
270        print(json.dumps(result, indent=2, ensure_ascii=False))
271        return 0
272 
273    except Exception as e:
274        print(json.dumps({"error": str(e)}, indent=2))
275        return 1
276 
277 
278if __name__ == "__main__":
279    exit(main())
280