Heatmap (Standard Density)

Retrieve orderbook heatmap data at standard density with wider price grouping for a broader view of liquidity distribution.

Returns orderbook heatmap data at standard density (wider price grouping). Standard density heatmaps provide a broader view of orderbook liquidity distribution across price levels with less granular price buckets compared to HD heatmaps.

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

Authentication

API key via X-API-Key header.

Endpoint

GET /api/v1/heatmap_sd

Example

GET /api/v1/heatmap_sd?exchange=binancef&symbol=btc/usd&tf=1m&from=1704067200&to=1704070800

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`)
`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)

Rate Limits

Property	Value
Cost Multiplier	5x
Max Points	5,000

Weight Calculation

For single-exchange requests:

base_points = (to - from) / tf_seconds
weight = ceil(base_points / 1000) * 5

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

weight = ceil(base_points / 1000) * 5 * (1 + 0.2 * num_exchanges)

Examples

Requesting 1 hour of 1-minute heatmap_sd (1 exchange):

base_points = 3600 / 60 = 60 points
weight = ceil(60 / 1000) * 5 = 1 * 5 = 5 weight

Requesting 1 hour of 1-minute heatmap_sd (3 exchanges, aggregated):

base_points = 3600 / 60 = 60 points
base_weight = ceil(60 / 1000) * 5 = 5
exchange_multiplier = 1 + 0.2 * 3 = 1.6
weight = 5 * 1.6 = 8 weight

Response

{
  "data": [
    {
      "t": 1704067200,
      "pg": 10,
      "s": [100000, 250000, 500000, 300000, 150000, 200000, 350000, 180000],
      "lp": 42050.00,
      "si": 4,
      "minp": 41500.00,
      "maxp": 42500.00,
      "mins": 10000,
      "maxs": 500000
    }
  ],
  "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": 10, "s": [100000, 250000, 500000, 300000, 150000, 200000, 350000, 180000], "si": 4, "lp": 42050.0, "minp": 42000.0, "maxp": 42070.0, "mins": 100000, "maxs": 500000}

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.

Errors

Validation Errors

Code	HTTP	Description
`INVALID_PARAMS`	400	Missing or invalid parameters
`INVALID_EXCHANGE`	400	Unknown exchange ID, duplicate exchange in aggregate string, or non-alphabetical aggregate ordering
`INVALID_TIMEFRAME`	400	Invalid timeframe format or outside allowed range

{
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Invalid request parameters",
    "details": {
      "message": "from and to are required"
    }
  }
}

Tier Errors

Code	HTTP	Description
`TIER_RESTRICTED`	403	Request outside tier's allowed history
`AGG_NOT_ALLOWED`	403	Multi-exchange aggregation not allowed on tier
`MAX_POINTS_EXCEEDED`	400	Request exceeds 5,000 point limit

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

Rate Limit Errors

Code	HTTP	Description
`RATE_LIMITED`	429	Rate limit exceeded

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "details": {
      "retry_after": 45
    }
  }
}

Server Errors

Code	HTTP	Description
`TIMEOUT`	504	Query exceeded 30 second timeout
`INTERNAL_ERROR`	500	Internal server error

{
  "error": {
    "code": "TIMEOUT",
    "message": "Query exceeded 30s timeout"
  }
}

Heatmap (Standard Density)

On this page