Skip to main content
GET
/
api
/
v1
/
candles
Get Candles
curl --request GET \
  --url https://api.example.com/api/v1/candles
{
  "symbol": "<string>",
  "dbSymbol": "<string>",
  "interval": "<string>",
  "from": "<string>",
  "to": "<string>",
  "count": 123,
  "data": [
    {
      "time": "<string>",
      "open": 123,
      "high": 123,
      "low": 123,
      "close": 123,
      "volume": 123,
      "trade_count": 123
    }
  ]
}

​
Overview

The Get Candles endpoint retrieves historical OHLCV (Open, High, Low, Close, Volume) candlestick data from TimescaleDB. The endpoint automatically calculates appropriate time ranges based on the requested interval and supports multiple symbols including perpetual futures.

​
Request

​
Query Parameters

​
symbol
string
required
The trading symbol to retrieve candles for. Supports both USDT pairs and perpetual futures notation.Supported symbols:
  • BTCUSDT or BTC_USDC_PERP - Bitcoin perpetual future
  • ETHUSDT or ETH_USDC_PERP - Ethereum perpetual future
  • SOLUSDT or SOL_USDC_PERP - Solana perpetual future
Symbol matching is case-insensitive.
​
interval
string
required
The candlestick time interval.Allowed values:
  • 1m - 1 minute (returns last 24 hours)
  • 5m - 5 minutes (returns last 7 days)
  • 15m - 15 minutes (returns last 14 days)
  • 30m - 30 minutes (returns last 1 month)
  • 1h - 1 hour (returns last 3 months)
  • 4h - 4 hours (returns last 1 year)
  • 1d - 1 day (returns last 5 years)

​
Response

​
symbol
string
The requested symbol in its original format (e.g., BTCUSDT)
​
dbSymbol
string
The normalized symbol used for database queries (e.g., BTC_USDC_PERP)
​
interval
string
The requested time interval
​
from
string
ISO 8601 timestamp of the start of the time range
​
to
string
ISO 8601 timestamp of the end of the time range
​
count
number
Number of candlesticks returned
​
data
array
Array of candlestick objects, ordered by time (ascending)

​
Examples

​
Get 1-hour Bitcoin candles

cURL
curl -X GET "http://localhost:8787/api/v1/candles?symbol=BTCUSDT&interval=1h"
Response
{
  "symbol": "BTCUSDT",
  "dbSymbol": "BTC_USDC_PERP",
  "interval": "1h",
  "from": "2025-12-03T14:30:00.000Z",
  "to": "2026-03-03T14:30:00.000Z",
  "count": 2184,
  "data": [
    {
      "time": "2025-12-03T14:00:00.000Z",
      "open": 96500.50,
      "high": 96750.25,
      "low": 96400.00,
      "close": 96680.75,
      "volume": 125.45,
      "trade_count": 1523
    },
    {
      "time": "2025-12-03T15:00:00.000Z",
      "open": 96680.75,
      "high": 96890.00,
      "low": 96550.50,
      "close": 96820.25,
      "volume": 98.32,
      "trade_count": 1234
    }
  ]
}

​
Get 5-minute Ethereum candles

cURL
curl -X GET "http://localhost:8787/api/v1/candles?symbol=ETHUSDT&interval=5m"
Response
{
  "symbol": "ETHUSDT",
  "dbSymbol": "ETH_USDC_PERP",
  "interval": "5m",
  "from": "2026-02-24T14:30:00.000Z",
  "to": "2026-03-03T14:30:00.000Z",
  "count": 2016,
  "data": [
    {
      "time": "2026-02-24T14:25:00.000Z",
      "open": 3250.75,
      "high": 3255.50,
      "low": 3248.25,
      "close": 3252.00,
      "volume": 450.25,
      "trade_count": 892
    }
  ]
}

​
Get daily Solana candles

cURL
curl -X GET "http://localhost:8787/api/v1/candles?symbol=SOLUSDT&interval=1d"

​
Error Responses

​
Missing Parameters

400 Bad Request
{
  "error": "Missing required query parameters: symbol and interval"
}

​
Invalid Interval

400 Bad Request
{
  "error": "Invalid interval value",
  "allowedIntervals": ["1m", "5m", "15m", "30m", "1h", "4h", "1d"]
}

​
Internal Server Error

500 Internal Server Error
{
  "error": "Internal server error",
  "message": "Database connection failed"
}

​
Implementation Details

​
Data Sources

The endpoint retrieves data from TimescaleDB using a hybrid approach:
  1. Primary: Pre-aggregated continuous aggregate views (candles_1m, candles_5m, etc.)
  2. Fallback: Real-time aggregation from the trades table if aggregate data is unavailable

​
Time Range Defaults

When no explicit time range is provided, the endpoint automatically determines the optimal range based on the interval:
IntervalDefault Time Range
1mLast 24 hours
5mLast 7 days
15mLast 14 days
30mLast 1 month
1hLast 3 months
4hLast 1 year
1dLast 5 years

​
Symbol Mapping

The endpoint automatically maps common symbol formats to internal database symbols:
  • BTCUSDT → BTC_USDC_PERP
  • ETHUSDT → ETH_USDC_PERP
  • SOLUSDT → SOL_USDC_PERP
You can use either format in your requests.

​
Best Practices

  1. Choose appropriate intervals: Use shorter intervals (1m, 5m) for recent data and longer intervals (1h, 1d) for historical analysis
  2. Handle empty responses: The count field indicates if data is available for the requested symbol and time range
  3. Cache responses: Candlestick data for completed time buckets won’t change, making it suitable for caching
  4. Monitor trade_count: Use this field to assess liquidity and data quality for each candle

Build docs developers (and LLMs) love

Get started for freeTalk to us