Heatmap

client.heatmap reads historical order book liquidity heatmaps and streams live buckets. It uses the public transport, so no authentication is required.

A heatmap is a time series of resting-liquidity snapshots: each bucket has bid and ask levels as { price[], qty[] } decimal-string columns. Historical responses arrive as a delta chain (a base keyframe plus per-bucket deltas) to keep the payload small.

Intervals: 1s, 1m, 5m, 1h. Depths are fixed steps: 1, 5, 10, 20, 50, 100, 200, 500, 1000.

Methods

getOrderbookHeatmap(input, options?)

Returns an OrderbookHeatmapResponse. symbolId and limit are required, and you must supply either a time range (startTsSec and/or endTsSec) or a pageToken. Passing neither is a validation error.

const now = Math.floor(Date.now() / 1000);
const heatmap = await client.heatmap.getOrderbookHeatmap({
	symbolId: 1,
	interval: "1m",
	depth: 100,
	limit: 60,
	quantityMode: "close",
	startTsSec: now - 3600,
	endTsSec: now,
});

console.log(heatmap.chain?.baseKeyframe?.mid);
console.log(heatmap.chain?.deltas.length, "delta buckets");

Page forward with the returned token instead of a time range:

const next = await client.heatmap.getOrderbookHeatmap({
	symbolId: 1,
	interval: "1m",
	limit: 60,
	pageToken: heatmap.nextPageToken,
});

GetOrderbookHeatmapInput

subscribeLive(input)

Streams live heatmap buckets for one symbol and interval. Returns an idempotent unsubscribe function.

const unsubscribe = client.heatmap.subscribeLive({
	symbolId: 1,
	interval: "1m",
	onEvent: (bucket) => {
		console.log(bucket.tsSec, bucket.isFinal, bucket.bids?.price.length);
	},
	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.

Shapes

import type {
	OrderbookHeatmapLevels,
	OrderbookHeatmapLiveBucket,
	OrderbookHeatmapResponse,
} from "@polyester/sdk";

Levels are { price: string[]; qty: string[] } decimal-string columns. Historical responses are a delta chain (chain.baseKeyframe plus chain.deltas). interval / quantityMode include "unspecified" when the server omits a label. depth is one of 1 | 5 | 10 | 20 | 50 | 100 | 200 | 500 | 1000 | "unspecified".

Related

• Market data guide for the task-oriented walkthrough.
• Streaming guide for the subscription model.
• Order book for live depth.
• Candles for OHLCV series.

Related Topics