marketdata.v1.MarketDataService
GetCandles
Retrieve OHLCV candles for a spot market and timeframe. Results are ordered newest-first and support inclusive time bounds, optional current open candle inclusion, and optional composite reference candles.
Request
curl --request POST \ \
--url 'https://api.testnet.polyester.com/marketdata.v1.MarketDataService/GetCandles' \
--header 'Content-Type: application/json' \
--header 'Connect-Protocol-Version: 1' \
--data '{
"endTime": "2025-01-01T00:00:00Z",
"includeIncomplete": false,
"includeReference": false,
"limit": 100,
"pageToken": "eyJvZmZzZXQiOjEwMH0",
"startTime": "2025-01-01T00:00:00Z",
"symbolId": 1,
"timeframe": "SEC_1"
}'Responses
{
"candles": [
{
"close": "42080000000000",
"high": "42150000000000",
"isClosed": false,
"low": "41900000000000",
"open": "42000500000000",
"quoteVolume": "12.3456",
"tsSec": "1735689600",
"volume": "1234567890000000000"
}
],
"nextPageToken": "eyJvZmZzZXQiOjIwMH0",
"referenceCandles": [
{
"close": "42080000000000",
"high": "42150000000000",
"isClosed": false,
"low": "41900000000000",
"open": "42000500000000",
"quoteVolume": "12.3456",
"tsSec": "1735689600",
"volume": "1234567890000000000"
}
],
"symbolId": 1,
"timeframe": "SEC_1"
}marketdata.v1.GetCandlesRequestmarketdata.v1.GetCandlesResponseNumeric spot market identifier.
Candle bucket size. Required for ConnectRPC clients.
Maximum number of closed candles to return. Defaults to 500 when unset; max 10000.
Inclusive lower bound for candle bucket start time, as a UTC timestamp. Must not be more than 5 minutes in the future.
Inclusive upper bound for candle bucket start time, as a UTC timestamp. Must be greater than or equal to start_time when both are set, and must not be more than 5 minutes in the future.
Include the current open candle when it is available and inside the requested range. The open candle is prepended to the newest-first candle list and does not count toward the closed-candle limit.
Include the composite reference market candle series for the same market, timeframe, and time range. The reference series can be empty when no reference series is available for the requested timeframe.
Opaque keyset cursor from a previous response. The cursor is exclusive and bound to symbol, timeframe, time bounds, and newest-first candle ordering. Inclusion flags affect response enrichment and may change between pages.
Numeric spot market identifier echoed from the request.
Candle bucket size used for the returned series.
Candle bucket start timestamp, in seconds since epoch (UTC).
Opening price in quote units: for a primary candle, the previous candle's close, or the first trade for a market's first candle. Primary candles use scale 9; composite reference candles use the pair's reference_price_scale from GetSpotConfig.
Highest price in the bucket, including the open, using the same scale as open.
Lowest price in the bucket, including the open, using the same scale as open.
Closing price, using the same scale as open.
Traded base-asset quantity scaled by the base asset's market_data_volume_scale from GetSpotConfig.
True for a closed candle bucket, including historical API rows and WebSocket terminal updates. False only while the bucket is still open.
Exact traded quote-asset volume as a human-readable decimal string. This is sum(execution price × execution quantity), not close × base volume.
Candle bucket start timestamp, in seconds since epoch (UTC).
Opening price in quote units: for a primary candle, the previous candle's close, or the first trade for a market's first candle. Primary candles use scale 9; composite reference candles use the pair's reference_price_scale from GetSpotConfig.
Highest price in the bucket, including the open, using the same scale as open.
Lowest price in the bucket, including the open, using the same scale as open.
Closing price, using the same scale as open.
Traded base-asset quantity scaled by the base asset's market_data_volume_scale from GetSpotConfig.
True for a closed candle bucket, including historical API rows and WebSocket terminal updates. False only while the bucket is still open.
Exact traded quote-asset volume as a human-readable decimal string. This is sum(execution price × execution quantity), not close × base volume.
Opaque cursor for the next page. Empty when no more results exist.
| Key | HTTP status | Connect code | Error | When |
|---|---|---|---|---|
| bad-request | 400 | invalid_argument | Bad Request | The request was malformed or missing required parameters. |
| invalid-argument | 400 | invalid_argument | Invalid Argument | One or more request arguments are invalid. |
| not-found | 404 | not_found | Not Found | The requested resource was not found. |
| unavailable | 503 | unavailable | Service Unavailable | The service is temporarily unavailable. |
| unknown-symbol | 404 | invalid_argument | Unknown Symbol | The requested trading pair symbol was not found. |
| upstream-error | 502 | unavailable | Upstream Error | An upstream service error occurred. |