# Market data services

Reference for the public services: market data, overview, candles, order book, heatmap, chain analytics, zipper, and lifecycle.

All services on this page use the public transport. No authentication required. Methods marked **stream** return an unsubscribe function `() => void` and take handler fields (`onEvent` required; `onOpen` / `onClose` / `onError` optional) alongside the listed inputs. Every `symbolId` is a positive uint32, from 1 through 4,294,967,295.

## `client.marketData`

Public spot trades, spot configuration, and live trade streams.

| Method                        | Input → Result                                                                                                        | Notes                                  |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `listTrades(input, options?)` | `symbolId`, `limit?` (integer 1-1,000), `side?`, `startTsNs?`, `endTsNs?`, `pageToken?` → `{ trades, nextPageToken }` | Newest first.                          |
| `getSpotConfig(options?)`     | → `SpotConfig`                                                                                                        | Raw reference data; feeds the catalog. |
| `subscribeTrades(input)`      | `symbolId` → **stream** of `MarketTrade`                                                                              |                                        |

## `client.marketOverview`

Ticker-style per-market stats.

| Method                                   | Input → Result                                                                                                                                                                                | Notes                                                                                      |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `list(input?, options?)`                 | `symbolIds?`, `limit?` (positive uint32, default 500), `pageToken?`, `orderBy?` (default `"volume_24h_usd"`), `sort?` (`"asc"`/`"desc"`), `includeSparklines?` → `{ markets, nextPageToken }` | Canonical USD volume; unvalued markets sort last.                                          |
| `getSpotVolumeHistory(input?, options?)` | `symbolIds?` (up to 2,000) → aligned 97-point trailing-24h USD-volume series                                                                                                                  | 15-minute samples; overlapping samples must not be summed.                                 |
| `subscribe(input)`                       | `symbolIds?` → **stream** of `MarketOverview[]`                                                                                                                                               | Snapshot-then-stream; `symbolIds` filters snapshots and all updates, including reconnects. |

`getCurrencyConversionConfig(options?)` returns fiat and stablecoin display metadata. `getCurrencyConversionRates(options?)` returns decimal rates, observation times, and staleness: fiat is units per USD; stablecoins are USD per unit. See [Market overview](https://testnet.polyester.com/docs/sdk/typescript/reference/market-overview#getcurrencyconversionratesoptions) for the result shape and unavailable-rate behavior.

## `client.candles`

OHLCV candles. Timeframes: `1s` `1m` `5m` `15m` `30m` `1h` `4h` `12h` `1d` `1w` `1mo`.

| Method                              | Input → Result                                                                                | Notes                                                   |
| ----------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| `list(input, options?)`             | `symbolId`, `timeframe`, `limit?` (integer 1-10,000), `startTsSec?`, `endTsSec?` → `Candle[]` | Rows include base `volume` and quote `quoteVolume`.     |
| `listColumnar(input, options?)`     | same → `CandleColumnar`                                                                       | Parallel arrays, including `quoteVolume`, oldest first. |
| `listColumnarInts(input, options?)` | same → `CandleColumnarInt`                                                                    | Keyed by numeric `tsSec`.                               |
| `subscribe(input)`                  | `symbolId`, `timeframe` → **stream** of `Candle`                                              |                                                         |
| `subscribeInts(input)`              | `symbolId`, `timeframe` → **stream** of `CandleInt`                                           |                                                         |

## `client.orderbook`

Depth snapshots and a stateful live book.

| Method                      | Input → Result                                                                                | Notes                                                                                                        |
| --------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `get(input, options?)`      | `symbolId`, `depth?` (default 50) → `OrderbookData`                                           | `bids` / `asks` as decimal-string levels.                                                                    |
| `createSubscription(input)` | `symbolId`, `depth?` (`[1, 500]`, default 50), `bucket?` + handlers → `OrderbookSubscription` | Snapshot + sequence-checked deltas; refetches on sequence gaps or reconnect, not on a silent connected feed. |
| `subscribe(input)`          | same → **stream** of `OrderbookData`                                                          | Shorthand for `createSubscription(...).unsubscribe`.                                                         |

`OrderbookSubscription`: `unsubscribe()`, `setBucket(bucket)` to change local price-bucket aggregation without reconnecting.

## `client.heatmap`

Order book liquidity heatmaps. Intervals: `1s` `1m` `5m` `1h`; depths: 1-1000 (fixed steps).

| Method                                 | Input → Result                                                                                                                                          | Notes                                                     |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `getOrderbookHeatmap(input, options?)` | `symbolId`, `limit` (integer 1-20,000), `interval?`, `depth?`, `quantityMode?`, `startTsSec?` / `endTsSec?` or `pageToken` → `OrderbookHeatmapResponse` | Time-range or cursor pagination; one of the two required. |
| `subscribeLive(input)`                 | `symbolId`, `interval` → **stream** of live buckets                                                                                                     |                                                           |

## `client.chainAnalytics`

Public chain chart series (columnar).

| Method                                       | Input → Result                                         |
| -------------------------------------------- | ------------------------------------------------------ |
| `getZippedAssetSupply(input, options?)`      | `zippedAssetId` + window → `ZippedAssetSupplyResponse` |
| `getZippedAssetSupplyGroup(input, options?)` | `groupId` + window → `ZippedAssetSupplyGroupResponse`  |
| `getUnifiedAssetBalances(input, options?)`   | `assetId` + window → `UnifiedAssetBalancesResponse`    |

## `client.zipper`

Deposit/withdraw configuration and supply streams.

| Method                               | Input → Result                       | Notes                                                                   |
| ------------------------------------ | ------------------------------------ | ----------------------------------------------------------------------- |
| `getDepositWithdrawConfig(options?)` | → `DepositWithdrawConfig`            | Chains, unified assets, routes, fees, minimums. Feeds `catalog.zipper`. |
| `subscribeZippedAssetSupply(input)`  | → **stream** of route supply updates |                                                                         |

## `client.lifecycle`

Cross-chain flow state (deposits, withdrawals, and related): history, detail, and live progress.

| Method                           | Input → Result                                                               | Notes                                                           |
| -------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `listFlows(input, options?)`     | kind/state/scope/account/tx/chain/asset filters → `{ flows, nextPageToken }` |                                                                 |
| `getFlow(input, options?)`       | `flowId` → flow summary, steps, timeline, live state                         |                                                                 |
| `listFlowsByTx(input, options?)` | `txHash` (+ mode) → matching flows                                           | Source-only or any-reference matching.                          |
| `subscribeOpenFlows(input)`      | account scope → **stream** of open-flow summaries                            | Private channel when an `accountId` is given, public otherwise. |
| `subscribeFlowDetail(input)`     | `flowId` → **stream** of flow detail                                         | Invalid `flowId` returns a no-op unsubscribe.                   |

## Related

- Reference data, symbol lookups, and conversions: the catalog. See [Catalog & precision](https://testnet.polyester.com/docs/sdk/typescript/concepts/catalog-and-precision).
- Handler contract and reconnect semantics for all streams: [Streaming](https://testnet.polyester.com/docs/sdk/typescript/guides/streaming).