Heatmap (High Density)

Retrieve orderbook heatmap data at high density with finer price grouping for detailed liquidity visualization.

Returns historical orderbook heatmap data at high density. HD heatmaps use finer price grouping for more granular visualization of orderbook liquidity over time. This provides detailed insight into where large orders are placed and how the orderbook structure evolves.

Recommended: Use /flat_heatmap_hd for new integrations. It returns the same data in a flat format optimized for rendering. /heatmap_hd remains for compatibility.

Authentication

API key via X-API-Key header.

Endpoint

GET /api/v1/heatmap_hd

Parameters

Parameter	Type	Required	Description
`exchange`	string	Yes	Exchange ID (e.g., `binancef`, `bybitf`). Aggregated format: colon-separated, unique, alphabetically ordered IDs (e.g., `binancef:bybitf`). Invalid aggregate strings return `INVALID_EXCHANGE`.
`symbol`	string	Yes	Trading pair with slash separator (e.g., `btc/usd`, `eth/usd`)
`tf`	string	Yes	Timeframe (e.g., `1m`, `5m`, `1h`)
`from`	int64	Yes	Start timestamp (Unix seconds, inclusive)
`to`	int64	Yes	End timestamp (Unix seconds, exclusive)

Example Request

curl -X GET "https://eu-central-1.mmt.gg/api/v1/heatmap_hd?exchange=binancef&symbol=btc/usd&tf=1m&from=1704067200&to=1704070800" \
  -H "X-API-Key: your-api-key"

Rate Limits

Metric	Value
Cost Multiplier	10x
Max Points	4,000

Weight Calculation

For single-exchange requests:

base_points = (to - from) / tf_seconds
weight = ceil(base_points / 1000) x 10

For multi-exchange aggregated requests, each exchange adds 20% to the base cost:

weight = ceil(base_points / 1000) x 10 x (1 + 0.2 x num_exchanges)

Example: 1 hour of 1-minute HD heatmap data (1 exchange):

base_points = 3600 / 60 = 60 points
weight = ceil(60 / 1000) x 10 = 10 weight

Example: 1 hour of 1-minute HD heatmap data (5 exchanges, aggregated):

base_points = 3600 / 60 = 60 points
base_weight = ceil(60 / 1000) x 10 = 10
exchange_multiplier = 1 + 0.2 x 5 = 2.0
weight = 10 x 2.0 = 20 weight

Response

{
  "data": [
    {
      "t": 1704067200,
      "pg": 5,
      "s": [100000, 250000, 500000, 750000, 400000, 300000, 150000],
      "lp": 42050.00,
      "si": 3,
      "minp": 41800.00,
      "maxp": 42300.00,
      "mins": 10000,
      "maxs": 750000
    },
    {
      "t": 1704067260,
      "pg": 5,
      "s": [120000, 280000, 520000, 720000, 380000, 320000, 170000],
      "lp": 42075.00,
      "si": 3,
      "minp": 41825.00,
      "maxp": 42325.00,
      "mins": 12000,
      "maxs": 720000
    }
  ],
  "exchange": "binancef",
  "symbol": "btc/usd",
  "tf": "1m",
  "from": 1704067200,
  "to": 1704070800,
  "points": 60
}

Types

Encoding: Supports both JSON and CBOR. Use format=cbor query param or Accept: application/cbor header.

Response Type: FlatHeatmap

{"t": 1704067200, "pg": 5, "s": [100000, 250000, 500000, 750000, 400000, 300000, 150000], "si": 3, "lp": 42050.0, "minp": 41800.0, "maxp": 42300.0, "mins": 10000, "maxs": 750000}

Field	Type	Description
`t`	`int64`	Unix timestamp (seconds)
`pg`	`float64`	Price grouping/bucket size
`s`	`[]float64`	Size values at each price level (bids below split index, asks at/above)
`si`	`int64`	Split index (divides bids/asks in sizes array)
`lp`	`float64`	Last traded price
`minp`, `maxp`	`float64`	Min/max price in range
`mins`, `maxs`	`float64`	Min/max size value

See Types for full details.

HD vs SD Heatmaps

Feature	HD (High Density)	SD (Standard Density)
Price grouping	Finer (smaller `pg`)	Coarser (larger `pg`)
Detail level	More granular	Less granular
Max points	4,000	5,000
Cost multiplier	10x	5x
Use case	Detailed analysis, zoomed views	Overview, longer time ranges

Errors

Code	HTTP	Description
`INVALID_API_KEY`	401	Missing or invalid API key
`INVALID_EXCHANGE`	400	Unknown/unsupported exchange ID, duplicate exchange in aggregate string, or non-alphabetical aggregate ordering
`INVALID_SYMBOL`	400	Unknown or unsupported trading symbol
`INVALID_TIMEFRAME`	400	Invalid timeframe format or outside allowed range
`INVALID_PARAMS`	400	Missing or invalid query parameters
`MAX_POINTS_EXCEEDED`	400	Request exceeds 4,000 point limit
`TIER_RESTRICTED`	403	Request outside tier's allowed history range
`AGG_NOT_ALLOWED`	403	Multi-exchange aggregation not allowed on tier
`RATE_LIMITED`	429	Rate limit exceeded
`TIMEOUT`	504	Query exceeded 30 second timeout
`INTERNAL_ERROR`	500	Internal server error

Example Error Response

{
  "error": {
    "code": "MAX_POINTS_EXCEEDED",
    "message": "Request exceeds max datapoints for stream",
    "details": {
      "requested": 5000,
      "max": 4000
    }
  }
}

Heatmap (High Density)

On this page