Candles

Candles summarize a Pair's trades per time bucket: open, high, low, close, base volume, and quote volume. Read history with GET /v1/spot/markets/{symbol}/candles or MarketDataService.GetCandles, and follow the current candle on the public candles channel. Both are public and need no authentication.

Timeframes

All buckets are in UTC; daylight saving time never shifts a boundary.

Fixed-length buckets up to 1d start at whole multiples of their length since 1970-01-01T00:00:00Z, so they always align to UTC midnight. The REST timeframe parameter is required and takes only the strings above. A missing value is rejected with HTTP 400 (INVALID_ARGUMENT), and any other value with HTTP 400 (BAD_REQUEST).

Read candles

GET https://api.testnet.polyester.com/v1/spot/markets/BTC-USDT/candles?timeframe=1m&limit=3&includeIncomplete=true

{
	"nextPageToken": "cGcBEm1hcmtldGRhdGEuY2FuZGxlcw...",
	"symbol": "BTC-USDT",
	"timeframe": "1m",
	"candles": [
		[
			"1793914620",
			"76135.97",
			"76135.97",
			"76044.66",
			"76059.87",
			"0.78155926",
			"59468.9262044147"
		],
		[
			"1793914560",
			"76105.51",
			"76166.43",
			"76090.29",
			"76135.97",
			"0.7577467",
			"57690.8632925045"
		],
		[
			"1793914500",
			"76075.08",
			"76151.2",
			"76075.08",
			"76105.51",
			"0.46245503",
			"35196.8818432678"
		],
		[
			"1793914440",
			"76090.29",
			"76120.74",
			"76029.45",
			"76075.08",
			"0.31737989",
			"24144.8216305437"
		]
	],
	"referenceCandles": []
}

POST https://api.testnet.polyester.com/marketdata.v1.MarketDataService/GetCandles
Content-Type: application/json

{"symbolId": 1, "timeframe": "MIN_1", "limit": 2, "includeIncomplete": true}

{
	"symbolId": 1,
	"timeframe": "MIN_1",
	"candles": [
		{
			"tsSec": "1793914620",
			"open": "76135970000000",
			"high": "76135970000000",
			"low": "76044660000000",
			"close": "76059870000000",
			"volume": "78155926",
			"quoteVolume": "59468.9262044147"
		},
		{
			"tsSec": "1793914560",
			"open": "76105510000000",
			"high": "76166430000000",
			"low": "76090290000000",
			"close": "76135970000000",
			"volume": "75774670",
			"isClosed": true,
			"quoteVolume": "57690.8632925045"
		}
	],
	"nextPageToken": "cGcBEm1hcmtldGRhdGEuY2FuZGxlcw..."
}

These responses were captured on 5 November 2026; page tokens are shortened.

Every parameter is listed in the API reference. The rules that matter when you read history:

• limit counts closed candles only: default 500, maximum 10000. With includeIncomplete, the open candle is added on top, which is why the REST request above for limit=3 returned four candles.
• startTime and endTime are inclusive bounds on the bucket start time. Neither may be more than 5 minutes in the future, and endTime may not be before startTime.
• includeIncomplete adds the current open candle only when it is inside the requested range.
• includeReference adds the reference candles for the same timeframe and range.
• Send pageToken with the same Pair, timeframe, and bounds as the request that returned it.

Candles are ordered newest first. An empty nextPageToken means there are no more pages. A limit above the maximum is rejected with HTTP 400 (INVALID_ARGUMENT). An unknown symbol answers HTTP 404 on REST; an unknown symbolId answers HTTP 400 (invalid_argument) on ConnectRPC.

Empty series

A series without closed candles answers with empty arrays, not missing fields. Right after a Pair opens, for example, every daily and weekly series is empty until its first bucket closes:

{
	"nextPageToken": "",
	"symbol": "BTC-USDT",
	"timeframe": "1d",
	"candles": [],
	"referenceCandles": []
}

REST always sends candles, referenceCandles, and nextPageToken. Test whether they are empty, not whether they are present. REST symbol is the Pair symbol from the request path. ConnectRPC JSON omits empty fields, as usual.

Open and closed candles

History returns closed candles only. With includeIncomplete, the current open candle is added in front of them, so it is always the first candle on the first page.

• ConnectRPC sets isClosed: true on every closed candle. The open candle has no isClosed, which means false.
• REST tuples carry no closed flag. With includeIncomplete=true, the first tuple is the open candle when its tsSec is the start of the current bucket; every other tuple is closed.
• An open candle changes until its bucket ends. Never store it as final.

How a candle is built

• A candle opens at the previous candle's close, so consecutive candles join at every timeframe. A Pair's first candle opens at its first trade.
• high and low include the open.
• A bucket without trades is flat at the previous close, with zero volume.
• volume is the traded base quantity. quoteVolume is the exact traded quote amount, the sum of price times quantity of each trade, not close times volume.

Reference candles

With includeReference, the response adds referenceCandles: a composite candle series of the same market on other venues. Use it to draw price history from before the Pair was listed on Polyester.

• The reference series covers the time before the Pair's listingAt. In the example below, the last BTC-USDT reference minute is 1793880720 (2026-11-05T12:12:00Z), right before that Pair's listingAt of 12:13:33Z.
• REST reference tuples have six slots, [tsSec, open, high, low, close, volume], without quoteVolume.
• Reference prices use the Pair's referencePriceScale on ConnectRPC, not the fixed scale of 9. Volume uses marketDataVolumeScale.
• Reference volume was 0 in every reference candle captured for this page. ConnectRPC JSON omits it.
• The 1s timeframe has no reference series; referenceCandles is empty.

{
	"referenceCandles": [
		["1793880720", "80219.15", "80219.16", "80199.99", "80218", "0"],
		["1793880660", "80153.6", "80219.16", "80153.59", "80219.16", "0"]
	]
}

When a reference series is requested but temporarily unavailable, the request fails as unavailable instead of returning an empty list. Retry with backoff.

Backfill

Live candles

Subscribe to one timeframe of one Pair, using the REST timeframe string:

public:spot:market:candles:<timeframe>:<symbolId>
public:spot:market:candles:<timeframe>:<symbolId>:proto

The JSON channel publishes one candle object with decimal strings; the Protobuf channel publishes marketdata.v1.CandlePoint. These updates were sent on public:spot:market:candles:1m:1, in this order:

{"tsSec":"1793914200","open":"75983.86","high":"75983.86","low":"75983.86","close":"75983.86","volume":"0","quoteVolume":"0","isClosed":false}
{"tsSec":"1793914140","open":"75983.86","high":"76014.26","low":"75923.1","close":"75983.86","volume":"0.16636898","quoteVolume":"12640.141624887","isClosed":true}
{"tsSec":"1793914200","open":"75983.86","high":"76029.46","low":"75983.86","close":"76029.46","volume":"0.00249794","quoteVolume":"189.9170000951","isClosed":false}

• Each update for the open bucket has isClosed: false and replaces the previous update of that bucket.
• After a bucket ends, one terminal update with isClosed: true carries its final values.
• The next bucket's first update can arrive before the previous bucket's terminal update, as above. Key every update by tsSec; never assume the latest update is the newest bucket.

See Realtime channels for connecting, Rate limits for quotas, and the API reference for the full schema.

Related Topics