MarketDataService
Get Candles
Retrieve OHLCV candles for a spot symbol and timeframe, ordered newest first. Supports inclusive time bounds, optional current open candle inclusion, and optional composite reference candles.
Request
curl --request GET \ \ --url 'https://api.testnet.polyester.com/v1/spot/markets/BTC-USDT/candles?endTime=2025-01-01T00%3A00%3A00Z&includeIncomplete=false&includeReference=false&limit=100&pageToken=eyJvZmZzZXQiOjEwMH0&startTime=2025-01-01T00%3A00%3A00Z&timeframe=1s' \ --header 'Accept: */*'
Responses
{
"candles": [
[
"1735689600",
"42000.5",
"42150",
"41900",
"42080",
"1234567890000000000",
"12.3456"
]
],
"nextPageToken": "eyJvZmZzZXQiOjIwMH0",
"referenceCandles": [
[
"1735689600",
"42000500000000",
"42150000000000",
"41900000000000",
"42080000000000",
"1234567890000000000"
]
],
"symbol": "BTC-USDT",
"timeframe": "1s"
}Trading pair symbol, e.g. BTC-USDT
Filter candles with bucket start time at or before this time (inclusive, RFC3339).
Include the current open candle when available. It is prepended to the newest-first candle list and does not count toward limit.
Include the composite reference market candle series when available.
Maximum closed candles to return. Default 500, max 10000.
Opaque cursor from the previous response.
Filter candles with bucket start time at or after this time (inclusive, RFC3339).
Candle bucket timeframe, such as 1m, 5m, 1h, or 1d.
Primary market candle series, ordered newest-first by ts_sec.
[["1735689600","42000.5","42150","41900","42080","1234567890000000000","12.3456"]]Opaque cursor for the next page. Empty when no more results exist.
eyJvZmZzZXQiOjIwMH0Composite reference market candle series, ordered newest-first by ts_sec. Populated only when include_reference is true and reference data is available.
[["1735689600","42000500000000","42150000000000","41900000000000","42080000000000","1234567890000000000"]]Numeric spot market identifier echoed from the request.
BTC-USDTCandle bucket size used for the returned series.
1s| Key | Status | Error | When |
|---|---|---|---|
| unauthenticated | 401 | Unauthenticated | Authentication required. |
| permission-denied | 403 | Permission Denied | Permission denied. |
| invalid-argument | 400 | Invalid Argument | Invalid argument. |
| not-found | 404 | Not Found | Not found. |
| unavailable | 503 | Unavailable | Service unavailable. |