> For the complete documentation index, see [llms.txt](https://docs.heyhal.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heyhal.xyz/api-documentation/get-ohlc-data.md). # Get OHLC Data **Endpoint:** `GET /api/v1/coin/ohlc` ### Description This endpoint retrieves candlestick (OHLC) data for a specific token within an optional time range. The data is useful for creating price charts and analyzing token price movements over time. ### Authentication Required: No Type: None ### Request #### Headers #### Content-Type: application/json #### Query Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------- | | token | string | Yes | The mint address of the token | | from | number | No | Start timestamp in Unix seconds | | to | number | No | End timestamp in Unix seconds | Example Requests: GET /api/v1/coin/ohlc?token=ABC // All data for token GET /api/v1/coin/ohlc?token=ABC\&from=1234567890 // Data from timestamp GET /api/v1/coin/ohlc?token=ABC\&from=1234567890\&to=1234567899 // Data in range ### Response #### Success Response Status Code: 200 OK Content-Type: application/json type OHLCResponse = Array<{ id: number; coinId: string; timestamp: Date; unixTimestamp: string; open: string; high: string; low: string; close: string; volume: string; }> Example Response: \[ { "id": 1, "coinId": "TokenMintAddress123", "timestamp": "2024-02-20T12:00:00.000Z", "unixTimestamp": "1708428000", "open": "1.5", "high": "1.8", "low": "1.4", "close": "1.6", "volume": "1000000" }, // ... more candles ] #### Error Response Status Code: 500 Internal Server Error { "error": "An internal error occurred. Please try again later." } ### Example Usage ### interface OHLCData { ### id: number; ### coinId: string; ### timestamp: string; ### unixTimestamp: string; ### open: string; ### high: string; ### low: string; ### close: string; ### volume: string; ### } ### // Function to fetch OHLC data ### async function getOHLCData( ### tokenMintAddress: string, ### fromTimestamp?: number, ### toTimestamp?: number ### ) { ### try { ### let url = \`; ### ### if (fromTimestamp) { ### url += \`\&from=${fromTimestamp}\`; ### } ### if (toTimestamp) { ### url += \`\&to=${toTimestamp}\`; ### } ### ### const response = await fetch(url); ### ### if (!response.ok) { ### throw new Error(\`HTTP error! status: ${response.status}\`); ### } ### ### const candles: OHLCData\[] = await response.json(); ### return candles; ### } catch (error) { ### console.error('Error fetching OHLC data:', error); ### throw error; ### } ### } ### // Example usage with TradingView Lightweight Charts ### import { createChart } from 'lightweight-charts'; ### async function createPriceChart( ### containerId: string, ### tokenMintAddress: string ### ) { ### const chart = createChart(containerId, { ### width: 800, ### height: 400 ### }); ### ### const candlestickSeries = chart.addCandlestickSeries(); ### ### // Get last 7 days of data ### const toTimestamp = Math.floor(Date.now() / 1000); ### const fromTimestamp = toTimestamp - (7 \* 24 \* 60 \* 60); ### ### try { ### const ohlcData = await getOHLCData( ### tokenMintAddress, ### fromTimestamp, ### toTimestamp ### ); ### ### const formattedData = ohlcData.map(candle => ({ ### time: parseInt(candle.unixTimestamp), ### open: parseFloat(candle.open), ### high: parseFloat(candle.high), ### low: parseFloat(candle.low), ### close: parseFloat(candle.close) ### })); ### ### candlestickSeries.setData(formattedData); ### } catch (error) { ### console.error('Error creating chart:', error); ### } ### } ### Implementation Notes Time Range Handling If no time range is specified, returns all available data Timestamps should be in Unix seconds format Data is ordered by timestamp in descending order (newest first) Data Format All price values are returned as strings to preserve precision Volume is denominated in the smallest token unit Timestamps are provided in both ISO 8601 (timestamp) and Unix seconds (unixTimestamp) formats 3\. Performance Considerations // Example of paginated data fetching async function fetchAllOHLCData(tokenMintAddress: string) { const CHUNK\_SIZE = 7 \* 24 \* 60 \* 60; // 7 days in seconds const now = Math.floor(Date.now() / 1000); let currentTo = now; let allData: OHLCData\[] = \[]; while (true) { const from = currentTo - CHUNK\_SIZE; const chunk = await getOHLCData( tokenMintAddress, from, currentTo ); if (chunk.length === 0) break; allData = \[...allData, ...chunk]; currentTo = from; } return allData; } Data Analysis Utilities // Calculate moving average function calculateMA(candles: OHLCData\[], period: number) { return candles.map((candle, index) => { if (index < period - 1) return null; const sum = candles .slice(index - period + 1, index + 1) .reduce((acc, curr) => acc + parseFloat(curr.close), 0); return sum / period; }); } // Calculate daily returns function calculateDailyReturns(candles: OHLCData\[]) { return candles.map((candle, index) => { if (index === 0) return 0; const previousClose = parseFloat(candles\[index - 1].close); const currentClose = parseFloat(candle.close); return ((currentClose - previousClose) / previousClose) \* 100; }); } ### Best Practices Data Caching const CACHE\_DURATION = 60000; // 1 minute const cache = new Map\(); async function getCachedOHLCData( tokenMintAddress: string, fromTimestamp?: number, toTimestamp?: number ) { const cacheKey = \`${tokenMintAddress}-${fromTimestamp}-${toTimestamp}\`; const now = Date.now(); const cached = cache.get(cacheKey); if (cached && now - cached.timestamp < CACHE\_DURATION) { return cached.data; } const data = await getOHLCData(tokenMintAddress, fromTimestamp, toTimestamp); cache.set(cacheKey, { timestamp: now, data }); return data; } Error Handling function validateTimestamps(from?: number, to?: number) { if (from && to && from > to) { throw new Error('From timestamp must be less than to timestamp'); } if (from && from > Date.now() / 1000) { throw new Error('From timestamp cannot be in the future'); } }
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.heyhal.xyz/api-documentation/get-ohlc-data.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.