Candles

client.candles reads and streams public spot OHLCV data. It uses the public transport, so no authentication is required. Every method takes a numeric symbolId and a timeframe.

Supported timeframes: 1s, 1m, 5m, 15m, 30m, 1h, 4h, 12h, 1d, 1w, 1mo.

Open, high, low, close, base volume, and quote-asset quoteVolume are decimal strings. Candle times are epoch seconds (time in row and columnar output, tsSec in the int variants).

Methods

list(input, options?)

Returns a Candle[] of row objects. symbolId and timeframe are required; the rest narrow the range.

const candles = await client.candles.list({
	symbolId: 1,
	timeframe: "1h",
	limit: 200,
});

const latest = candles[0];
console.log(latest.time, latest.open, latest.close, latest.volume, latest.quoteVolume);

GetCandlesInput

listColumnar(input, options?)

Returns a CandleColumnar: parallel arrays ordered oldest-first by bucket start time, which is the shape most charting libraries want.

const series = await client.candles.listColumnar({ symbolId: 1, timeframe: "5m", limit: 500 });
// series.time[i], series.open[i], series.high[i], series.low[i], series.close[i], series.volume[i]
// series.quoteVolume[i]

listColumnarInts(input, options?)

The same columnar series, but keyed by numeric bucket-start seconds (tsSec) instead of time.

const series = await client.candles.listColumnarInts({ symbolId: 1, timeframe: "1d" });
console.log(series.tsSec.at(-1), series.close.at(-1));

subscribe(input)

Streams live row candles for one symbol and timeframe. Returns an idempotent unsubscribe function.

const unsubscribe = client.candles.subscribe({
	symbolId: 1,
	timeframe: "1m",
	onEvent: (candle) => console.log(candle.time, candle.close, candle.isClosed),
	onError: (ctx) => console.error(ctx.channel, ctx.error),
});

// later
unsubscribe();

onEvent is required. onOpen, onClose, and onError are optional. See the realtime client reference for the handler contract.

subscribeInts(input)

The same live candle channel and input as subscribe, parsed through the int-form row schema.

const unsubscribe = client.candles.subscribeInts({
	symbolId: 1,
	timeframe: "1m",
	onEvent: (candle) => console.log(candle.time, candle.close),
});

The Candle shape

Row methods and both streams share this shape.

import type { Timeframe } from "@polyester/sdk";

interface Candle {
	symbolId: number;
	timeframe: Timeframe | "unspecified";
	time: number; // bucket start, epoch seconds
	open: string; // decimal string
	high: string;
	low: string;
	close: string;
	volume: string; // base-asset volume
	quoteVolume: string; // exact quote-asset volume
	isClosed: boolean; // false while the bucket is still forming
}

The columnar variants replace the scalar fields with arrays (time/tsSec, open, high, low, close, volume, quoteVolume) plus an optional reference series of the same shape.

quoteVolume is the sum of execution price times execution quantity, rather than the candle close multiplied by base volume.

Related

• Market data guide for the task-oriented walkthrough.
• Streaming guide for the subscription model.
• Market overview for per-market stats.
• Order book for depth.
• Public trades for prints.

Related Topics