client.market_data (alias client.candles) reads and streams public spot OHLCV data. No
authentication is required. Resolve symbol → symbol_id via catalogs (or pass symbol_id).
Supported timeframe aliases: 1s, 1m, 5m, 15m, 30m, 1h, 4h, 12h, 1d, 1w, 1mo (also accepts enum names like MIN_1).
OHLCV fields are decimal strings. Candle times are epoch seconds (ts_sec).
Row results are ordered newest-first. When requested, the open/incomplete candle is prepended
at index 0; never use [-1] as the latest candle. Reverse or sort row results by ts_sec before
feeding them to chronological indicators. The columns API is oldest-first.
Methods
| Method | Summary |
| --------------------- | ------------------------------------------------------ | ---------------------------------- |
| get_candles | Fetch candles as row objects. |
| get_candles_columns | Fetch columnar series, decoded to the same row result. |
| get_current_candle | Latest candle (Candle | None; None when no rows exist). |
| subscribe_candles | Stream live row candles. |
Get candles
result = await client.candles.get_candles(
symbol="BTC-USDT",
timeframe="1h",
limit=200,
)
if result.candles:
latest = result.candles[0]
print(latest.ts_sec, latest.open, latest.close, latest.volume, latest.is_closed)
chronological = list(reversed(result.candles))
# Feed chronological (oldest-first) to rolling indicators.| Field | Required | Notes |
|---|---|---|
symbol / symbol_id | one of | Pair or engine id |
timeframe | no | Default "1m" |
limit | no | Default 100 |
start_time / end_time | no | datetime range |
include_incomplete | no | Include forming bucket |
Get candles columns
Same filters as get_candles, columnar wire form decoded into CandlesResult rows (chart-friendly
upstream, same Python shape). Columnar decode does not populate is_closed (defaults to False); use row get_candles / stream when you need closed-bucket flags.
The SDK verifies that every OHLCV column has exactly one value per timestamp and raises PolyesterTransportError if the response is misaligned.
Get current candle
candle = await client.candles.get_current_candle(symbol="BTC-USDT", timeframe="1m")
if candle is not None:
print(candle.close, candle.is_closed)Subscribe candles
sub = await client.candles.subscribe_candles(symbol="BTC-USDT", timeframe="1m")
async with sub:
async for candle in sub:
print(candle.ts_sec, candle.close, candle.is_closed)
breakCandle shape
ts_sec, open, high, low, close, volume (strings), is_closed (bool).
is_closed comes from the wire is_closed / isClosed field on row candle points: False while the timeframe bucket is still forming, True when that bucket is complete.
Streamed candles may still emit multiple updates for the same ts_sec bucket before is_closed becomes True. Use include_incomplete on unary reads when you want the
still-forming bucket included. CandlesResult wraps symbol_id, timeframe, candles.