# Market data

Read candles, public trades, order books, and market overview, no credentials required.

Every service on this page is public. An unauthenticated `AsyncPolyester()` can call them.

```python
from polyester import AsyncPolyester

async with AsyncPolyester() as client:
    await client.wait_for_catalogs()
    ...
```

## Symbols

Prefer pair symbols like `"BTC-USDT"`. Services resolve them to engine ids via catalogs after hydration. You can also pass `symbol_id` directly.

Fetch the public raw spot-pair catalog directly when you need the wire snapshot:

```python
spot_config = await client.market_data.get_spot_config()
print(spot_config.raw)
```

## Market overview (tickers)

```python
overview = await client.market_overview.list(limit=50)
for m in overview.markets:
    print(m.symbol, m.last_price)

sub = await client.market_overview.create_subscription(limit=50)
async with sub:
    async for rows in sub:
        ...
```

Prefer `create_subscription` (snapshot-then-stream) over raw `subscribe`.

## Candles (OHLCV)

Alias: `client.candles` → `client.market_data`. Timeframes: `1s`, `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `12h`, `1d`, `1w`, `1mo`.

```python
result = await client.candles.get_candles(symbol="BTC-USDT", timeframe="1h", limit=200)
if result.candles:
    latest = result.candles[0]
    print(latest.close, latest.is_closed)

chronological = list(reversed(result.candles))
# Feed chronological (oldest-first) to rolling indicators.

live = await client.candles.subscribe_candles(symbol="BTC-USDT", timeframe="1m")
async with live:
    async for candle in live:
        print(candle.ts_sec, candle.close, candle.is_closed)
        break
```

Row results are newest-first, with the requested open/incomplete candle prepended. The columns API is oldest-first.

## Order book

```python
book = await client.orderbook.get(symbol="BTC-USDT", depth=20)
print(book.bids[0], book.asks[0], book.book_seq)

sub = await client.orderbook.create_subscription(symbol="BTC-USDT", depth=50)
async with sub:
    async for book in sub:
        print(book.book_seq)
        break
```

Managed subscriptions refetch on sequence gaps. See [Order book](https://testnet.polyester.com/docs/sdk/python/reference/order-book).

## Public trades

```python
tape = await client.market_data.get_trades(symbol="BTC-USDT", limit=20)
sub = await client.market_data.subscribe_trades(symbol="BTC-USDT")
```

Private fills are `client.trades`, not the public tape.

## Heatmap & chain analytics

`client.heatmap` and `client.chain_analytics` for L2 heatmap queries and chain analytics reads. See matching reference pages when present.

> **Streaming model**
>
> Centrifugo WebSocket + Protobuf. Details: [Streaming](https://testnet.polyester.com/docs/sdk/python/guides/streaming).

## Related

- [Order book](https://testnet.polyester.com/docs/sdk/python/reference/order-book) · [Candles](https://testnet.polyester.com/docs/sdk/python/reference/candles) · [Public trades](https://testnet.polyester.com/docs/sdk/python/reference/public-trades) · [Market overview](https://testnet.polyester.com/docs/sdk/python/reference/market-overview)