get-historical-ohlcv
Fetch historical OHLCV (open, high, low, close, volume) data for cryptocurrency trading pairs across multiple exchanges, enabling analysis of market trends and price movements. Specify symbol, timeframe, and days back for tailored results.
Instructions
Get historical OHLCV (candlestick) data for a trading pair
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| days_back | No | Number of days of historical data to fetch (default: 7, max: 30) | |
| exchange | No | Exchange to use (supported: binance, coinbase, kraken, kucoin, hyperliquid, huobi, bitfinex, bybit, okx, mexc) | binance |
| symbol | Yes | Trading pair symbol (e.g., BTC/USDT, ETH/USDT) | |
| timeframe | No | Timeframe for candlesticks (e.g., 1m, 5m, 15m, 1h, 4h, 1d) | 1h |
Implementation Reference
- src/server.py:288-305 (handler)The main handler logic for the 'get-historical-ohlcv' tool. It extracts parameters, calculates the 'since' timestamp, fetches OHLCV data using ccxt's fetch_ohlcv method, formats it with format_ohlcv_data, and returns a formatted text response.elif name == "get-historical-ohlcv": symbol = arguments.get("symbol", "").upper() timeframe = arguments.get("timeframe", "1h") days_back = min(int(arguments.get("days_back", 7)), 30) # Calculate timestamps since = int((datetime.now() - timedelta(days=days_back)).timestamp() * 1000) # Fetch historical data ohlcv = await exchange.fetch_ohlcv(symbol, timeframe, since=since) formatted_data = format_ohlcv_data(ohlcv, timeframe) return [ types.TextContent( type="text", text=f"Historical OHLCV data for {symbol} ({timeframe}) on {exchange_id.upper()}:\n\n{formatted_data}" ) ]
- src/server.py:158-184 (registration)Registration of the 'get-historical-ohlcv' tool in the list_tools handler, including its description and input schema definition.types.Tool( name="get-historical-ohlcv", description="Get historical OHLCV (candlestick) data for a trading pair", inputSchema={ "type": "object", "properties": { "symbol": { "type": "string", "description": "Trading pair symbol (e.g., BTC/USDT, ETH/USDT)", }, "timeframe": { "type": "string", "description": "Timeframe for candlesticks (e.g., 1m, 5m, 15m, 1h, 4h, 1d)", "enum": ["1m", "5m", "15m", "1h", "4h", "1d"], "default": "1h" }, "days_back": { "type": "number", "description": "Number of days of historical data to fetch (default: 7, max: 30)", "default": 7, "maximum": 30 }, "exchange": get_exchange_schema() }, "required": ["symbol"], }, ),
- src/server.py:161-183 (schema)Input schema for the 'get-historical-ohlcv' tool, defining parameters like symbol, timeframe, days_back, and exchange.inputSchema={ "type": "object", "properties": { "symbol": { "type": "string", "description": "Trading pair symbol (e.g., BTC/USDT, ETH/USDT)", }, "timeframe": { "type": "string", "description": "Timeframe for candlesticks (e.g., 1m, 5m, 15m, 1h, 4h, 1d)", "enum": ["1m", "5m", "15m", "1h", "4h", "1d"], "default": "1h" }, "days_back": { "type": "number", "description": "Number of days of historical data to fetch (default: 7, max: 30)", "default": 7, "maximum": 30 }, "exchange": get_exchange_schema() }, "required": ["symbol"], },
- src/server.py:69-97 (helper)Helper function to format the raw OHLCV data into a human-readable string, including price changes between candles.def format_ohlcv_data(ohlcv_data: List[List], timeframe: str) -> str: """Format OHLCV data into a readable string with price changes.""" formatted_data = [] for i, candle in enumerate(ohlcv_data): timestamp, open_price, high, low, close, volume = candle # Calculate price change from previous close if available price_change = "" if i > 0: prev_close = ohlcv_data[i-1][4] change_pct = ((close - prev_close) / prev_close) * 100 price_change = f"Change: {change_pct:+.2f}%" # Format the candle data dt = datetime.fromtimestamp(timestamp/1000).strftime('%Y-%m-%d %H:%M:%S') candle_str = ( f"Time: {dt}\n" f"Open: {open_price:.8f}\n" f"High: {high:.8f}\n" f"Low: {low:.8f}\n" f"Close: {close:.8f}\n" f"Volume: {volume:.2f}\n" f"{price_change}\n" "---" ) formatted_data.append(candle_str) return "\n".join(formatted_data)