Candles — TAAPI.IO v2

Returns an array of OHLCV (Open, High, Low, Close, Volume) candles ordered oldest to newest. Use this for charting, backtesting, or building custom indicators on raw price data.

Parameters

Name	Type	Required	Default	Description
`exchange`	string	Yes	—	Exchange identifier, e.g. `binance`, `bybit`. See Exchanges.
`symbol`	string	Yes	—	Trading pair, e.g. `BTCUSDT`.
`timeframe`	string	Yes	—	Candle interval: `1m`, `5m`, `15m`, `1h`, `4h`, `1d`, `1w`.
`results`	integer	No	1	Number of candles to return. Use `max` to return all available candles.
`backtrack`	integer	No	0	Candles to skip from the most recent. Shifts the result window back in time.

TODO(human): Confirm the maximum number of candles returnable by this endpoint.

Example

curl -G https://v2.taapi.io/candles \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "exchange=binance" \
  --data-urlencode "symbol=BTCUSDT" \
  --data-urlencode "timeframe=1h" \
  --data-urlencode "results=3"

const res = await fetch(
  'https://v2.taapi.io/candles' +
  '?exchange=binance&symbol=BTCUSDT&timeframe=1h&results=3',
  { headers: { Authorization: 'Bearer YOUR_API_KEY' } }
);
const candles = await res.json();

import requests

resp = requests.get(
    'https://v2.taapi.io/candles',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={
        'exchange':  'binance',
        'symbol':    'BTCUSDT',
        'timeframe': '1h',
        'results':   3,
    }
)
candles = resp.json()

Response

Returns an array of candle objects, ordered oldest to newest. The last element in the array is the most recent candle.

200 OK — array of candles

[
  {
    "timestamp":      1708293600,
    "timestampHuman": "2024-02-19 00:00:00",
    "open":   51200.5,
    "high":   52100.0,
    "low":    50900.25,
    "close":  51850.75,
    "volume": 1234.56
  },
  {
    "timestamp":      1708297200,
    "timestampHuman": "2024-02-19 01:00:00",
    "open":   51850.75,
    "high":   52300.0,
    "low":    51600.0,
    "close":  52150.0,
    "volume": 987.32
  },
  {
    "timestamp":      1708300800,
    "timestampHuman": "2024-02-19 02:00:00",
    "open":   52150.0,
    "high":   52400.0,
    "low":    51900.5,
    "close":  52050.25,
    "volume": 1102.88
  }
]

Candle fields

Field	Type	Description
`timestamp`	integer	Unix timestamp (seconds) of the candle open.
`timestampHuman`	string	Human-readable UTC datetime: `YYYY-MM-DD HH:MM:SS`.
`open`	number	Opening price.
`high`	number	Highest price during the candle.
`low`	number	Lowest price during the candle.
`close`	number	Closing price.
`volume`	number	Trading volume during the candle.

Errors

Response

[{ "timestamp": 1708300800, "open": 52150.0, ... }]

Data is being fetched. Retry after 1–2 seconds.

Response

{ "pending": true, "key": "ta:binance:BTCUSDT:1h:..." }

Response

{ "error": "Missing required: ex, sym, tf" }

Response

{ "error": "Invalid or missing API key." }

Response

{ "error": "Rate limit exceeded. Your plan allows 30 requests per 15 seconds." }

Bringing your own candles

To compute indicators on your own candle data, use Data Injection — POST /indicator/{indicator} or POST /bulk-candles. No exchange, symbol, or timeframe required.