marketdata.v1.HeatmapService
GetOrderbookHeatmap
Retrieve historical orderbook heatmap data for a spot symbol. - All intervals (1s/1m/5m/1h) return snapshot + sparse delta chain. - Response may also include the latest live bucket state when available. Response always includes realtime stitching anchors.
Request
curl --request POST \ \
--url 'https://api.testnet.polyester.com/marketdata.v1.HeatmapService/GetOrderbookHeatmap' \
--header 'Content-Type: application/json' \
--header 'Connect-Protocol-Version: 1' \
--data '{
"depth": "DEPTH_1",
"interval": "INTERVAL_1S",
"limit": 100,
"pageToken": "eyJvZmZzZXQiOjEwMH0",
"quantityMode": "CLOSE",
"symbolId": 1,
"timeRange": {
"endTime": "2025-01-01T00:00:00Z",
"startTime": "2025-01-01T00:00:00Z"
}
}'Responses
{
"chain": {
"baseKeyframe": {
"asks": {
"priceTicks": [
"61000250000000"
],
"qtyScaled": [
"100000"
]
},
"bestAskTicks": "1",
"bestBidTicks": "1",
"bids": {
"priceTicks": [
"61000250000000"
],
"qtyScaled": [
"100000"
]
},
"bookSeq": "1",
"midTicks": "1",
"tsSec": "1735689600"
},
"deltas": [
{
"asks": {
"priceTicks": [
"61000250000000"
],
"qtyScaled": [
"100000"
]
},
"bids": {
"priceTicks": [
"61000250000000"
],
"qtyScaled": [
"100000"
]
},
"bookSeqEnd": "1",
"bookSeqStart": "1",
"tsSec": "1735689600",
"updatesInBucket": 1
}
]
},
"depth": "DEPTH_1",
"hasLiveAnchor": false,
"interval": "INTERVAL_1S",
"lastPersistedTsSec": "1735689600",
"liveBucket": {
"asks": {
"priceTicks": [
"61000250000000"
],
"qtyScaled": [
"100000"
]
},
"bids": {
"priceTicks": [
"61000250000000"
],
"qtyScaled": [
"100000"
]
},
"bookSeqEnd": "1",
"bookSeqStart": "1",
"effectiveBinTicks": "1",
"interval": "INTERVAL_1S",
"isFinal": false,
"quantityMode": "CLOSE",
"symbolId": 1,
"tsSec": "1735689600",
"updatesInBucket": 1
},
"liveFromBookSeqEnd": "1",
"nextPageToken": "eyJvZmZzZXQiOjIwMH0",
"quantityMode": "CLOSE",
"serverTimeSec": "1",
"symbolId": 1
}marketdata.v1.GetOrderbookHeatmapRequestmarketdata.v1.GetOrderbookHeatmapResponseNumeric spot market identifier.
Heatmap bucket interval.
Top-N levels per side included in each bucket.
Inclusive lower bound in UTC. Omit to leave the lower bound open.
Inclusive upper bound in UTC. Omit to leave the upper bound open.
Opaque keyset cursor from a previous response. The cursor is exclusive and bound to symbol, interval, depth, quantity mode, and the original time range.
Maximum number of delta buckets returned (min 1, max 20000). This limit counts only `chain.deltas`; `chain.base_keyframe` is not counted.
Quantity mode used for qty_scaled in snapshot/delta levels: - CLOSE: end-of-bucket quantity - PEAK: intra-bucket peak quantity
Numeric spot market identifier returned for the requested market.
Bucket interval used for the returned chain.
Top-N depth requested per side.
Snapshot timestamp (seconds since epoch, UTC).
Best bid price in quote units scaled by 1e9.
Best ask price in quote units scaled by 1e9.
Mid price in quote units scaled by 1e9.
Price levels in quote units scaled by 1e9.
Quantity at each price level according to quantity_mode, scaled by the pair's base_quantity_scale from GetSpotConfig.
Price levels in quote units scaled by 1e9.
Quantity at each price level according to quantity_mode, scaled by the pair's base_quantity_scale from GetSpotConfig.
Monotonic order book sequence at the snapshot.
Bucket start timestamp (seconds since epoch, UTC), aligned to `interval`.
Price levels in quote units scaled by 1e9.
Quantity at each price level, scaled by the pair's base_quantity_scale from GetSpotConfig. A zero value deletes the level at the matching price_ticks index.
Price levels in quote units scaled by 1e9.
Quantity at each price level, scaled by the pair's base_quantity_scale from GetSpotConfig. A zero value deletes the level at the matching price_ticks index.
Number of upstream L2 updates aggregated into this interval bucket.
Earliest monotonic order book sequence represented by this bucket.
Latest monotonic order book sequence represented by this bucket.
Latest finalized historical bucket timestamp in seconds since epoch (UTC).
Book sequence anchor for realtime continuation; apply live updates where book_seq_end is greater than this value.
True when live_from_book_seq_end is available and can be used as a realtime continuation anchor.
Opaque cursor for the next page. Empty when no more results exist.
Server response time in seconds since epoch (UTC).
Quantity mode used for all qty_scaled values in the response.
Numeric spot market identifier.
Bucket interval for this payload.
Bucket start timestamp (seconds since epoch, UTC), aligned to `interval`.
True when this bucket is finalized; false for provisional updates to an open bucket.
Price levels in quote units scaled by 1e9.
Quantity at each price level, scaled by the pair's base_quantity_scale from GetSpotConfig. A zero value deletes the level at the matching price_ticks index.
Price levels in quote units scaled by 1e9.
Quantity at each price level, scaled by the pair's base_quantity_scale from GetSpotConfig. A zero value deletes the level at the matching price_ticks index.
Number of upstream L2 updates aggregated into this interval bucket.
Earliest monotonic order book sequence represented by this bucket.
Latest monotonic order book sequence represented by this bucket.
Quantity semantics for qty_scaled in bids and asks.
Effective bin stride for this symbol as a price delta in 1e-9 quote-unit ticks.
| Key | HTTP status | Connect code | Error | When |
|---|---|---|---|---|
| bad-request | 400 | invalid_argument | Bad Request | The request was malformed or missing required parameters. |
| invalid-argument | 400 | invalid_argument | Invalid Argument | One or more request arguments are invalid. |
| not-found | 404 | not_found | Not Found | The requested resource was not found. |
| unavailable | 503 | unavailable | Service Unavailable | The service is temporarily unavailable. |
| unknown-symbol | 404 | invalid_argument | Unknown Symbol | The requested trading pair symbol was not found. |
| upstream-error | 502 | unavailable | Upstream Error | An upstream service error occurred. |