1#!/usr/bin/env python3
2"""
3CoinGecko Coin Historical Chart Data within Time Range Tool
4 
5This tool provides access to the CoinGecko Pro API /coins/{id}/market-chart/range endpoint,
6which returns historical chart data for a specific coin by its id or symbol within a time range.
7 
8API Reference: https://docs.coingecko.com/reference/coins-id-market-chart-range
9 
10Usage Example:
11    from tools.coin_historical_chart_range_by_id import get_coin_historical_chart_range
12    
13    # Using symbol
14    data = get_coin_historical_chart_range('BTC', vs_currency='usd', from_timestamp=1672531200, to_timestamp=1672617600)
15    
16    # Using ID
17    data = get_coin_historical_chart_range('bitcoin', vs_currency='usd', from_timestamp=1672531200, to_timestamp=1672617600)
18    print(data)
19 
20Returns:
21    dict with keys: 'prices', 'market_caps', 'total_volumes'
22"""
23 
24import os
25from dotenv import load_dotenv
26import time
27import argparse
28import json
29 
30from core.http_client import proxied_get
31try:
32    from .utils import parse_flexible_time, split_time_range, merge_market_chart_data, get_days_difference, search_coin_by_name
33except ImportError:
34    from utils import parse_flexible_time, split_time_range, merge_market_chart_data, get_days_difference, search_coin_by_name
35 
36 
37# MCP Tool Schema
38MCP_TOOL_SCHEMA = {
39    "name": "get_coin_historical_chart_range_by_id",
40    "title": "CoinGecko Historical Chart Range",
41    "description": "Retrieve historical chart data (prices, market caps, total volumes) for a specific cryptocurrency within a custom time range. Automatically determines optimal data granularity based on the time range. Will return a lot of data, use with caution.",
42    "inputSchema": {
43        "$schema": "https://json-schema.org/draft/2020-12/schema",
44        "type": "object",
45        "properties": {
46            "coin_id": {
47                "type": "string",
48                "minLength": 1,
49                "description": "The coin id (e.g., 'bitcoin') or symbol (e.g., 'BTC')"
50            },
51            "vs_currency": {
52                "type": "string",
53                "default": "usd",
54                "description": "The target currency (e.g., 'usd')"
55            },
56            "from_timestamp": {
57                "type": ["string", "integer", "number"],
58                "description": "Start time - supports Unix timestamp (1640995200), ISO date ('2023-01-01' or '2023-01-01 10:30:00'), or natural language ('2 weeks ago', 'last month', 'yesterday')"
59            },
60            "to_timestamp": {
61                "type": ["string", "integer", "number"],
62                "description": "End time - same formats as from_timestamp"
63            }
64        },
65        "required": ["coin_id", "from_timestamp", "to_timestamp"],
66        "additionalProperties": False
67    },
68    "outputSchema": {
69        "$schema": "https://json-schema.org/draft/2020-12/schema",
70        "type": "object",
71        "properties": {
72            "prices": {
73                "type": "array",
74                "items": {
75                    "type": "array",
76                    "items": [
77                        {"type": "number", "description": "Unix timestamp in milliseconds"},
78                        {"type": "number", "description": "Price in the specified vs_currency"}
79                    ],
80                    "minItems": 2,
81                    "maxItems": 2
82                },
83                "description": "Array of [timestamp_ms, price] pairs showing coin price at each time point"
84            },
85            "market_caps": {
86                "type": "array",
87                "items": {
88                    "type": "array",
89                    "items": [
90                        {"type": "number", "description": "Unix timestamp in milliseconds"},
91                        {"type": "number", "description": "Market capitalization at this timestamp"}
92                    ],
93                    "minItems": 2,
94                    "maxItems": 2
95                },
96                "description": "Array of [timestamp_ms, market_cap] pairs showing market capitalization"
97            },
98            "total_volumes": {
99                "type": "array",
100                "items": {
101                    "type": "array",
102                    "items": [
103                        {"type": "number", "description": "Unix timestamp in milliseconds"},
104                        {"type": "number", "description": "Total trading volume"}
105                    ],
106                    "minItems": 2,
107                    "maxItems": 2
108                },
109                "description": "Array of [timestamp_ms, volume] pairs showing trading volume"
110            }
111        },
112        "required": ["prices", "market_caps", "total_volumes"],
113        "additionalProperties": False
114    },
115    "annotations": {
116        "path": "tools/coingecko/coin_historical_chart_range_by_id.py",
117        "function": "get_coin_historical_chart_range_by_id",
118        "examples": [
119            {
120                "name": "basic_auto_interval",
121                "arguments": {
122                    "coin_id": "BTC",
123                    "from_timestamp": "30 days ago",
124                    "to_timestamp": "today"
125                }
126            },
127            {
128                "name": "large_range_splitting",
129                "arguments": {
130                    "coin_id": "BTC",
131                    "from_timestamp": "2023-01-01",
132                    "to_timestamp": "2023-12-31"
133                }
134            }
135        ]
136    }
137}
138 
139 
140 
141# Load environment variables from project root directory
142project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), '../../../..'))
143load_dotenv(os.path.join(project_root, '.env'))
144 
145def get_coin_historical_chart_range_by_id(coin_id, vs_currency='usd', from_timestamp=None, to_timestamp=None):
146    """
147    Fetch historical chart data for a specific coin by its id or symbol within a time range from CoinGecko.
148    Automatically handles data splitting for large time ranges based on interval limits and flexible time input parsing.
149    
150    Args:
151        coin_id (str): The coin id (e.g., 'bitcoin') or symbol (e.g., 'BTC')
152        vs_currency (str): The target currency (e.g., 'usd')
153        from_timestamp (Union[str, int, float]): Start time - supports:
154            - Unix timestamp (1640995200)
155            - ISO date ('2023-01-01' or '2023-01-01 10:30:00')
156            - Natural language ('2 weeks ago', 'last month', 'yesterday')
157        to_timestamp (Union[str, int, float]): End time - same formats as from_timestamp
158    
159    Returns:
160        dict: Historical chart data with keys: 'prices', 'market_caps', 'total_volumes'
161              Automatically merges data from multiple API calls if needed for large ranges
162    
163    Raises:
164        ConnectionError: If API request fails after retries
165        ValueError: If parameters are invalid or time range exceeds interval limits
166        
167    Data Limitations (based on official CoinGecko API):
168        - Auto granularity: 1 day = 5-min, 1-90 days = hourly, >90 days = daily
169        - Cache frequency: 1 day = 30s, 2-90 days = 30min, >90 days = 12h
170        
171    Examples:
172        >>> # Get last 30 days of data
173        >>> data = get_coin_historical_chart_range_by_id('BTC', 'usd', '30 days ago', 'today')
174        
175        >>> # Get data for specific date range
176        >>> data = get_coin_historical_chart_range_by_id('ETH', 'usd', '2023-01-01', '2023-03-31')
177        
178        >>> # Large range with automatic splitting
179        >>> data = get_coin_historical_chart_range_by_id('BTC', 'usd', '2023-01-01', '2023-12-31')
180    """
181    if not coin_id:
182        raise ValueError("coin_id parameter is required")
183    
184    if not from_timestamp or not to_timestamp:
185        raise ValueError("Both from_timestamp and to_timestamp are required")
186    
187    # Convert symbol to ID if needed
188    coin_result = search_coin_by_name(coin_id)
189    if not coin_result:
190        raise ValueError(f"Could not find coin with symbol or name: {coin_id}")
191    actual_coin_id = coin_result['id']
192    
193    # Parse flexible time inputs
194    from_ts = parse_flexible_time(from_timestamp)
195    to_ts = parse_flexible_time(to_timestamp)
196    
197    if from_ts >= to_ts:
198        raise ValueError("from_timestamp must be earlier than to_timestamp")
199    
200    # Determine splitting strategy based on time range
201    days_diff = get_days_difference(from_ts, to_ts)
202    
203    # For better granularity, split at 90 days to maintain hourly data when possible
204    if days_diff <= 90:
205        return _fetch_single_range(actual_coin_id, vs_currency, from_ts, to_ts)
206    else:
207        return _fetch_with_splitting(actual_coin_id, vs_currency, from_ts, to_ts, max_days=90)
208 
209 
210def _fetch_single_range(coin_id, vs_currency, from_timestamp, to_timestamp):
211    """Fetch historical chart data for a single time range."""
212    url = f"https://pro-api.coingecko.com/api/v3/coins/{coin_id}/market_chart/range"
213    params = {
214        'vs_currency': vs_currency,
215        'from': from_timestamp,
216        'to': to_timestamp
217    }
218    
219    headers = {"x-cg-pro-api-key": os.getenv("COINGECKO_API_KEY")}
220    
221    if not headers["x-cg-pro-api-key"]:
222        raise ValueError("COINGECKO_API_KEY environment variable is required")
223    
224    for attempt in range(3):
225        try:
226            resp = proxied_get(url, params=params, headers=headers, timeout=15)
227            resp.raise_for_status()
228            return resp.json()
229        except Exception as e:
230            if attempt == 2:  # Last attempt
231                raise ConnectionError(f"API request failed after retries: {e}")
232            time.sleep(1)
233 
234 
235def _fetch_with_splitting(coin_id, vs_currency, from_ts, to_ts, max_days):
236    """Fetch historical chart data with automatic splitting for large ranges."""
237    time_chunks = split_time_range(from_ts, to_ts, max_days=max_days)
238    data_chunks = []
239    
240    for chunk_start, chunk_end in time_chunks:
241        chunk_data = _fetch_single_range(coin_id, vs_currency, chunk_start, chunk_end)
242        data_chunks.append(chunk_data)
243        # Small delay between requests to be respectful to the API
244        time.sleep(0.5)
245    
246    # Merge all chunks
247    return merge_market_chart_data(data_chunks)
248 
249def main():
250    """Main CLI function."""
251    parser = argparse.ArgumentParser(
252        description="Fetch historical chart data within a time range for a specific coin from CoinGecko API.",
253        epilog="""INPUT:
254  --coin_id: Coin ID/symbol (bitcoin, BTC, ethereum, ETH)
255  --from_timestamp: Start time ("30 days ago", "2023-01-01", timestamp)
256  --to_timestamp: End time ("today", "2023-12-31", timestamp)
257  --vs_currency: Target currency (default: usd)
258 
259OUTPUT:
260  JSON array of price and volume data:
261  [{"timestamp": 1640995200, "price": 46300.45, "market_cap": 874500000000, 
262    "total_volume": 34500000000}]
263 
264EXAMPLE:
265  python coin_historical_chart_range_by_id.py --coin_id BTC --from_timestamp "30 days ago" --to_timestamp "today"
266  python coin_historical_chart_range_by_id.py --coin_id ethereum --from_timestamp "2023-01-01" --to_timestamp "2023-06-30"
267        """,
268        formatter_class=argparse.RawDescriptionHelpFormatter
269    )
270    
271    # MCP Schema query options
272    parser.add_argument('--schema', action='store_true',
273                       help='Output complete MCP tool schema (JSON)')
274    parser.add_argument('--name', action='store_true',
275                       help='Output tool name from schema')
276    parser.add_argument('--title', action='store_true',
277                       help='Output tool title from schema')
278    parser.add_argument('--description', action='store_true',
279                       help='Output tool description from schema')
280    parser.add_argument('--inputSchema', action='store_true',
281                       help='Output input schema')
282    parser.add_argument('--outputSchema', action='store_true',
283                       help='Output output schema')
284    parser.add_argument('--annotations', action='store_true',
285                       help='Output annotations from schema')
286    
287    # Tool functionality options
288    parser.add_argument('--coin_id', type=str, help='Coin id (e.g., bitcoin) or symbol (e.g., BTC)')
289    parser.add_argument('--vs_currency', type=str, default='usd', help='Target currency (default: usd)')
290    parser.add_argument('--from_timestamp', type=str, 
291                       help='Start time - supports: Unix timestamp, ISO date (2023-01-01), natural language ("2 weeks ago", "last month")')
292    parser.add_argument('--to_timestamp', type=str,
293                       help='End time - same formats as from_timestamp')
294 
295    args = parser.parse_args()
296 
297    # Handle MCP schema queries first
298    if args.schema:
299        print(json.dumps(MCP_TOOL_SCHEMA, indent=2, sort_keys=True))
300        return
301    elif args.name:
302        print(MCP_TOOL_SCHEMA["name"])
303        return
304    elif args.title:
305        print(MCP_TOOL_SCHEMA["title"])
306        return
307    elif args.description:
308        print(MCP_TOOL_SCHEMA["description"])
309        return
310    elif args.inputSchema:
311        print(json.dumps(MCP_TOOL_SCHEMA["inputSchema"], indent=2, sort_keys=True))
312        return
313    elif args.outputSchema:
314        print(json.dumps(MCP_TOOL_SCHEMA["outputSchema"], indent=2, sort_keys=True))
315        return
316    elif args.annotations:
317        print(json.dumps(MCP_TOOL_SCHEMA["annotations"], indent=2, sort_keys=True))
318        return
319 
320    # Check required arguments only if not showing example
321    if not args.coin_id:
322        parser.error("--coin_id is required")
323    if not args.from_timestamp:
324        parser.error("--from_timestamp is required")
325    if not args.to_timestamp:
326        parser.error("--to_timestamp is required")
327 
328    try:
329        # Call the main function to fetch historical chart data using the provided arguments
330        data = get_coin_historical_chart_range_by_id(
331            coin_id=args.coin_id,
332            vs_currency=args.vs_currency,
333            from_timestamp=args.from_timestamp,
334            to_timestamp=args.to_timestamp
335        )
336        
337        # Print the result as pretty-formatted JSON
338        print(json.dumps(data, ensure_ascii=False, indent=2))
339            
340    except Exception as e:
341        # Print error message if the API call fails
342        print(f"Failed to fetch historical chart data: {e}")
343 
344 
345if __name__ == "__main__":
346    main()