Get Candles

Retrieve historical candlestick (OHLCV) data for a specified trading symbol and time interval

GET /api/v1/candles

Get Candles

cURL

curl --request GET \
  --url https://api.example.com/api/v1/candles

200

{
  "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)

Show Candlestick Object

time · string

Timestamp of the candlestick bucket (ISO 8601 format)

open · number

Opening price (first price in the time bucket)

high · number

Highest price in the time bucket

low · number

Lowest price in the time bucket

close · number

Closing price (last price in the time bucket)

volume · number

Total trading volume in the time bucket

trade_count · number

Number of trades executed in the time bucket

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:

Interval	Default Time Range
1m	Last 24 hours
5m	Last 7 days
15m	Last 14 days
30m	Last 1 month
1h	Last 3 months
4h	Last 1 year
1d	Last 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