1#!/usr/bin/env python3
2"""
3CoinGecko Coin Prices at Multiple Timestamps Tool
4 
5This tool provides functionality to fetch coin prices at multiple specific timestamps
6using the CoinGecko Pro API. It supports flexible time input formats including "now"
7for current prices and various date formats for historical prices.
8 
9MCP Tool Schema compliant with CLI interface supporting:
10- --help: Output complete Schema (JSON, pretty-printed)
11- --<field>: Output specific Schema field
12 
13Dependencies:
14- requests: For HTTP API calls
15- python-dotenv: For environment variable management
16 
17Environment Variables Required:
18- COINGECKO_API_KEY: Your CoinGecko Pro API key (required for API access)
19 
20API Limitations:
21- Rate limits apply based on your CoinGecko Pro subscription
22- Historical data available from February 9, 2018 onwards
23- Current price endpoint updates every 20 seconds for Pro API tiers
24"""
25 
26import os
27from dotenv import load_dotenv
28import time
29import argparse
30import json
31from typing import List, Dict, Any, Union
32from datetime import datetime
33 
34try:
35    from .utils import parse_flexible_time, format_dd_mm_yyyy_date, search_coin_by_name
36except ImportError:
37    from utils import parse_flexible_time, format_dd_mm_yyyy_date, search_coin_by_name
38 
39from core.http_client import proxied_get
40 
41# Load environment variables from agent_framework root directory
42# Path: extensions/trading/tools/coingecko/ -> go up 4 levels to agent_framework/
43project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..', '..', '..'))
44load_dotenv(os.path.join(project_root, '.env'))
45 
46# MCP Tool Schema
47MCP_TOOL_SCHEMA = {
48    "name": "get_coin_prices_at_timestamps",
49    "title": "CoinGecko Coin Prices at Multiple Timestamps",
50    "description": "Fetch cryptocurrency prices at multiple specific timestamps using CoinGecko Pro API. Supports flexible time input formats including 'now' for current prices and various date formats for historical prices.",
51    "inputSchema": {
52        "type": "object",
53        "properties": {
54            "coin_ids": {
55                "type": ["string", "array"],
56                "items": {
57                    "type": "string"
58                },
59                "description": "Single coin ID/symbol or list of coin IDs/symbols. Supports comma-separated strings, individual strings, or arrays. Accepts both full names ('bitcoin') and symbols ('BTC'). Case-insensitive.",
60                "examples": ["bitcoin", "BTC", "BTC,ETH,SOL", ["bitcoin", "ethereum", "solana"]]
61            },
62            "timestamps": {
63                "type": "array",
64                "items": {
65                    "type": "string"
66                },
67                "description": "List of timestamp strings in various formats. Supports 'now' for current price, Unix timestamps, ISO dates, and natural language expressions.",
68                "default": ["now"],
69                "examples": [["now"], ["now", "2023-01-01", "yesterday"], ["now", "1640995200", "last month"]]
70            },
71            "vs_currency": {
72                "type": "string",
73                "description": "The target currency for price quotes",
74                "default": "usd",
75                "examples": ["usd", "eur", "btc"]
76            },
77            "rate_limit_delay": {
78                "type": "number",
79                "description": "Delay between API calls in seconds to respect rate limits",
80                "default": 1.0,
81                "minimum": 0.1,
82                "maximum": 10.0
83            }
84        },
85        "required": ["coin_ids"],
86        "additionalProperties": False
87    },
88    "outputSchema": {
89        "type": "array",
90        "items": {
91            "type": "object",
92            "properties": {
93                "timestamp": {
94                    "type": "string",
95                    "description": "Original timestamp input"
96                },
97                "parsed_timestamp": {
98                    "type": ["integer", "null"],
99                    "description": "Unix timestamp (for historical data) or null for errors"
100                },
101                "date": {
102                    "type": "string",
103                    "description": "Human readable date"
104                },
105                "price": {
106                    "type": ["number", "null"],
107                    "description": "Price in specified currency or null for errors"
108                },
109                "coin_id": {
110                    "type": "string",
111                    "description": "CoinGecko coin ID used for API call"
112                },
113                "coin_symbol": {
114                    "type": "string",
115                    "description": "Coin symbol (e.g., 'BTC')"
116                },
117                "coin_name": {
118                    "type": "string",
119                    "description": "Coin name (e.g., 'Bitcoin')"
120                },
121                "status": {
122                    "type": "string",
123                    "enum": ["success", "error"],
124                    "description": "Status of the price fetch operation"
125                },
126                "error": {
127                    "type": ["string", "null"],
128                    "description": "Error message if status is 'error', otherwise null"
129                }
130            },
131            "required": ["timestamp", "parsed_timestamp", "date", "price", "coin_id", "coin_symbol", "coin_name", "status", "error"]
132        }
133    },
134    "annotations": {
135        "path": "tools/coingecko/coin_prices.py",
136        "function":  "get_coin_prices_at_timestamps",
137        "examples": [
138            {
139                "name": "Single coin current price",
140                "input": {
141                    "coin_ids": "bitcoin"
142                },
143                "output": [
144                    {
145                        "timestamp": "now",
146                        "parsed_timestamp": 1672531200,
147                        "date": "2023-01-01 00:00:00 UTC",
148                        "price": 16547.32,
149                        "coin_id": "bitcoin",
150                        "coin_symbol": "BTC",
151                        "coin_name": "Bitcoin",
152                        "status": "success",
153                        "error": None
154                    }
155                ]
156            },
157            {
158                "name": "Multiple coins with timestamps",
159                "input": {
160                    "coin_ids": "BTC,ETH,SOL",
161                    "timestamps": ["now", "yesterday"]
162                },
163                "output": [
164                    {
165                        "timestamp": "now",
166                        "parsed_timestamp": 1672531200,
167                        "date": "2023-01-01 00:00:00 UTC",
168                        "price": 16547.32,
169                        "coin_id": "bitcoin",
170                        "coin_symbol": "BTC",
171                        "coin_name": "Bitcoin",
172                        "status": "success",
173                        "error": None
174                    },
175                    {
176                        "timestamp": "yesterday",
177                        "parsed_timestamp": 1672444800,
178                        "date": "2022-12-31 00:00:00 UTC",
179                        "price": 16625.11,
180                        "coin_id": "bitcoin",
181                        "coin_symbol": "BTC",
182                        "coin_name": "Bitcoin",
183                        "status": "success",
184                        "error": None
185                    }
186                ]
187            }
188        ],
189        "env_vars": {
190            "COINGECKO_API_KEY": {
191                "description": "CoinGecko Pro API key for authentication",
192                "required": True,
193                "url": "https://coingecko.com/en/api"
194            }
195        },
196        "data_availability": {
197            "current": "Real-time updates every 20 seconds",
198            "historical": "Available from February 9, 2018 onwards"
199        }
200    }
201}
202 
203 
204def get_coin_prices_at_timestamps(coin_ids: Union[str, List[str]], 
205                                timestamps: List[str] = None, 
206                                vs_currency: str = 'usd',
207                                rate_limit_delay: float = 1.0) -> List[Dict[str, Any]]:
208    """
209    Get multiple coin prices at multiple specific timestamps.
210    
211    This function fetches prices for one or more coins at multiple timestamps using CoinGecko API.
212    It automatically handles different time input formats and uses appropriate 
213    API endpoints for current vs historical prices with rate limiting protection.
214    
215    Args:
216        coin_ids (Union[str, List[str]]): Single coin ID/symbol or list of coin IDs/symbols
217            - String: "bitcoin" or "BTC" for single coin
218            - String with comma-separation: "BTC,ETH,SOL" for multiple coins
219            - List: ["bitcoin", "ethereum", "solana"] for multiple coins
220        timestamps (List[str], optional): List of timestamp strings in various formats (default: ["now"]):
221            - "now": Current price
222            - Unix timestamp (1640995200)
223            - ISO date ('2023-01-01' or '2023-01-01 10:30:00')
224            - Natural language ('2 weeks ago', 'last month', 'yesterday')
225        vs_currency (str): The target currency (default: 'usd')
226        rate_limit_delay (float): Delay between API calls in seconds (default: 1.0)
227    
228    Returns:
229        List[Dict[str, Any]]: List of price data dictionaries with:
230            - timestamp: Original timestamp input
231            - parsed_timestamp: Unix timestamp (for historical data)
232            - date: Human readable date
233            - price: Price in specified currency
234            - coin_id: CoinGecko coin ID used for API call
235            - coin_symbol: Coin symbol (e.g., 'BTC')
236            - coin_name: Coin name (e.g., 'Bitcoin')
237            - status: 'success' or 'error'
238            - error: Error message (if status is 'error')
239    
240    Raises:
241        ValueError: If coin_ids is invalid
242        ConnectionError: If API requests fail after retries
243        
244    Example Usage:
245        # Single coin with multiple timestamps
246        timestamps = ["now", "2023-01-01", "30 days ago"]
247        prices = get_coin_prices_at_timestamps("BTC", timestamps)
248        
249        # Multiple coins with single timestamp
250        prices = get_coin_prices_at_timestamps(["BTC", "ETH", "SOL"], ["now"])
251        
252        # Multiple coins with multiple timestamps (comma-separated string)
253        prices = get_coin_prices_at_timestamps("BTC,ETH,SOL", ["now", "yesterday"])
254        
255        for price_data in prices:
256            print(f"{price_data['coin_symbol']} on {price_data['date']}: ${price_data['price']}")
257    """
258    if not coin_ids:
259        raise ValueError("coin_ids parameter is required")
260    
261    # Default to current price if no timestamps provided
262    if timestamps is None:
263        timestamps = ["now"]
264    elif not isinstance(timestamps, list):
265        raise ValueError("timestamps must be a list")
266    
267    # Parse coin_ids input - handle string, comma-separated string, or list
268    if isinstance(coin_ids, str):
269        # Check if it's comma-separated
270        if ',' in coin_ids:
271            coin_list = [coin.strip() for coin in coin_ids.split(',') if coin.strip()]
272        else:
273            coin_list = [coin_ids.strip()]
274    elif isinstance(coin_ids, list):
275        coin_list = [str(coin).strip() for coin in coin_ids if str(coin).strip()]
276    else:
277        raise ValueError("coin_ids must be a string or list of strings")
278    
279    if not coin_list:
280        raise ValueError("No valid coin IDs provided")
281    
282    # Resolve all coin IDs
283    resolved_coins = []
284    for coin_input in coin_list:
285        coin_result = search_coin_by_name(coin_input)
286        if not coin_result:
287            raise ValueError(f"Could not find coin with symbol or name: {coin_input}")
288        resolved_coins.append(coin_result)
289    
290    results = []
291    total_api_calls = len(resolved_coins) * len(timestamps)
292    call_count = 0
293    
294    # Get prices for each coin at each timestamp
295    for coin_data in resolved_coins:
296        actual_coin_id = coin_data['id']
297        coin_symbol = coin_data['symbol']
298        coin_name = coin_data['name']
299        
300        for timestamp in timestamps:
301            try:
302                result = _get_single_price(actual_coin_id, timestamp, vs_currency)
303                result['coin_id'] = actual_coin_id
304                result['coin_symbol'] = coin_symbol
305                result['coin_name'] = coin_name
306                results.append(result)
307                
308                call_count += 1
309                # Add rate limiting delay between API calls (except after the last call)
310                if call_count < total_api_calls:
311                    time.sleep(rate_limit_delay)
312                    
313            except Exception as e:
314                error_result = {
315                    'timestamp': timestamp,
316                    'parsed_timestamp': None,
317                    'date': str(timestamp),
318                    'price': None,
319                    'coin_id': actual_coin_id,
320                    'coin_symbol': coin_symbol,
321                    'coin_name': coin_name,
322                    'status': 'error',
323                    'error': str(e)
324                }
325                results.append(error_result)
326                continue
327    
328    return results
329 
330 
331def _get_single_price(coin_id: str, timestamp: str, vs_currency: str) -> Dict[str, Any]:
332    """Get price for a single timestamp."""
333    timestamp_str = str(timestamp).strip().lower()
334    
335    # Handle "now" case - get current price
336    if timestamp_str == "now":
337        return _get_current_price(coin_id, vs_currency, timestamp)
338    
339    # Parse timestamp and get historical price
340    try:
341        parsed_ts = parse_flexible_time(timestamp)
342        return _get_historical_price(coin_id, parsed_ts, vs_currency, timestamp)
343    except Exception as e:
344        raise ValueError(f"Invalid timestamp format '{timestamp}': {e}")
345 
346 
347def _get_current_price(coin_id: str, vs_currency: str, original_timestamp: str) -> Dict[str, Any]:
348    """Get current price using simple/price endpoint."""
349    url = "https://pro-api.coingecko.com/api/v3/simple/price"
350    params = {
351        'ids': coin_id,
352        'vs_currencies': vs_currency,
353        'include_last_updated_at': 'true'
354    }
355    
356    headers = {"x-cg-pro-api-key": os.getenv("COINGECKO_API_KEY")}
357    
358    if not headers["x-cg-pro-api-key"]:
359        raise ValueError("COINGECKO_API_KEY environment variable is required")
360    
361    # Retry logic
362    for attempt in range(3):
363        try:
364            resp = proxied_get(url, params=params, headers=headers, timeout=15)
365            resp.raise_for_status()
366            data = resp.json()
367            
368            if coin_id not in data:
369                raise ValueError(f"Coin '{coin_id}' not found")
370            
371            coin_data = data[coin_id]
372            price = coin_data.get(vs_currency)
373            last_updated = coin_data.get('last_updated_at')
374            
375            if price is None:
376                raise ValueError(f"Price not available for currency '{vs_currency}'")
377            
378            return {
379                'timestamp': original_timestamp,
380                'parsed_timestamp': last_updated,
381                'date': datetime.utcfromtimestamp(last_updated).strftime('%Y-%m-%d %H:%M:%S UTC') if last_updated else 'now',
382                'price': price,
383                'status': 'success',
384                'error': None
385            }
386            
387        except Exception as e:
388            if attempt == 2:  # Last attempt
389                raise ConnectionError(f"Failed to fetch current price: {e}")
390            time.sleep(1)
391 
392 
393def _get_historical_price(coin_id: str, timestamp: int, vs_currency: str, original_timestamp: str) -> Dict[str, Any]:
394    """Get historical price using history endpoint."""
395    # Format date for CoinGecko API (dd-mm-yyyy)
396    date_str = format_dd_mm_yyyy_date(timestamp)
397    
398    url = f"https://pro-api.coingecko.com/api/v3/coins/{coin_id}/history"
399    params = {
400        'date': date_str,
401        'localization': 'false'
402    }
403    
404    headers = {"x-cg-pro-api-key": os.getenv("COINGECKO_API_KEY")}
405    
406    if not headers["x-cg-pro-api-key"]:
407        raise ValueError("COINGECKO_API_KEY environment variable is required")
408    
409    # Retry logic
410    for attempt in range(3):
411        try:
412            resp = proxied_get(url, params=params, headers=headers, timeout=15)
413            resp.raise_for_status()
414            data = resp.json()
415            
416            # Extract price from market_data
417            if 'market_data' not in data or 'current_price' not in data['market_data']:
418                raise ValueError(f"Price data not available for date {date_str}")
419            
420            price_data = data['market_data']['current_price']
421            price = price_data.get(vs_currency)
422            
423            if price is None:
424                raise ValueError(f"Price not available for currency '{vs_currency}' on date {date_str}")
425            
426            return {
427                'timestamp': original_timestamp,
428                'parsed_timestamp': timestamp,
429                'date': datetime.utcfromtimestamp(timestamp).strftime('%Y-%m-%d %H:%M:%S UTC'),
430                'price': price,
431                'status': 'success',
432                'error': None
433            }
434            
435        except Exception as e:
436            if attempt == 2:  # Last attempt
437                raise ConnectionError(f"Failed to fetch historical price for {date_str}: {e}")
438            time.sleep(1)
439 
440 
441def main():
442    """Command-line interface for the coin prices at timestamps tool with MCP Schema support."""
443    
444    import sys
445    
446    # Handle MCP Schema CLI arguments (only if they don't contain coin_ids or timestamps)
447    if len(sys.argv) > 1 and not any("coin_ids" in arg or "timestamps" in arg for arg in sys.argv[1:]):
448        arg = sys.argv[1]
449        
450        # Handle --help (complete schema) - only if no other arguments
451        if arg == "--schema" and len(sys.argv) == 2:
452            print(json.dumps(MCP_TOOL_SCHEMA, indent=2, sort_keys=True, ensure_ascii=False))
453            return 0
454        
455        # Handle specific field requests (e.g., --name, --description, --inputSchema)
456        if arg.startswith("--") and len(arg) > 2 and len(sys.argv) == 2:
457            field_name = arg[2:]  # Remove "--" prefix
458            if field_name in MCP_TOOL_SCHEMA:
459                field_value = MCP_TOOL_SCHEMA[field_name]
460                print(json.dumps(field_value, indent=2, sort_keys=True, ensure_ascii=False))
461                return 0
462 
463    # Original CLI functionality
464    parser = argparse.ArgumentParser(
465        description="Get coin prices at multiple specific timestamps from CoinGecko API.",
466        epilog="""INPUT:
467  --coin_ids: Coin symbols/names (BTC, bitcoin, "BTC,ETH,SOL")
468  --timestamps: Time points ("now,yesterday,2023-01-01,last month")
469 
470OUTPUT:
471  JSON array with price data for each coin-timestamp combination:
472  [{"timestamp": "now", "price": 16547.32, "coin_symbol": "BTC", 
473    "coin_name": "Bitcoin", "date": "2023-01-01 00:00:00 UTC", "status": "success"}]
474 
475EXAMPLE:
476  python coin_prices.py --coin_ids BTC --timestamps "now,yesterday"
477  python coin_prices.py --coin_ids "BTC,ETH" --timestamps "now"
478        """,
479        formatter_class=argparse.RawDescriptionHelpFormatter
480    )
481    
482    parser.add_argument('--coin_ids', required=True, 
483                       help='Coin id(s), symbol(s), or comma-separated list (e.g., "bitcoin", "BTC", "BTC,ETH,SOL")')
484    parser.add_argument('--timestamps', 
485                       help='Comma-separated list of timestamps (e.g., "now,2023-01-01,yesterday"). Default: "now"')
486 
487    args = parser.parse_args()
488 
489    try:
490        # Parse comma-separated timestamps or use default
491        if args.timestamps:
492            timestamps = [ts.strip() for ts in args.timestamps.split(',') if ts.strip()]
493            if not timestamps:
494                raise ValueError("No valid timestamps provided")
495        else:
496            timestamps = None  # Will default to ["now"] in function
497 
498        # Call main function with fixed parameters
499        results = get_coin_prices_at_timestamps(
500            coin_ids=args.coin_ids,
501            timestamps=timestamps,
502            vs_currency='usd',
503            rate_limit_delay=1.0
504        )
505        
506        # Output in JSON format only
507        print(json.dumps(results, ensure_ascii=False, indent=2))
508            
509    except Exception as e:
510        error_result = {
511            "error": str(e),
512            "timestamp": datetime.now().isoformat(),
513            "status": "failed"
514        }
515        print(json.dumps(error_result, indent=2, ensure_ascii=False))
516        return 1
517        
518    return 0
519 
520 
521if __name__ == "__main__":
522    exit(main())