Take Profit Heatmap

Returns take-profit heatmap data in the flat format (FlatHeatmap).

This endpoint is flat-only and single-exchange only (no aggregated exchange requests). It is available only for hyperliquid and hyperliquid-xyz.

Authentication

API key via X-API-Key header.

Endpoint

GET /api/v1/tp_heatmap

Example

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

Parameters

Parameter	Type	Required	Description
`exchange`	string	Yes	Single exchange ID. Allowed values: `hyperliquid`, `hyperliquid-xyz`. Aggregated exchange strings are not supported.
`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

Same limits as /heatmap_sd.

Weight Calculation

Single-exchange only:

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

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": "hyperliquid",
  "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 Envelope

Field	Type	Description
`data`	`FlatHeatmap[]`	Array of take-profit heatmap points
`exchange`	string	Exchange ID
`symbol`	string	Unified symbol
`tf`	string	Timeframe string
`from`	int64	Start timestamp (Unix seconds)
`to`	int64	End timestamp (Unix seconds)
`points`	int	Number of points returned

Response Type: FlatHeatmap

{"t": 1704067200, "pg": 10, "s": [100000, 250000, 500000], "lp": 42050.0, "si": 50, "minp": 41500.0, "maxp": 42500.0, "mins": 10000, "maxs": 1000000}

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

See Types for full details.

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 (including aggregated exchanges for this endpoint)
`MAX_POINTS_EXCEEDED`	400	Request exceeds 5,000 point limit
`TIER_RESTRICTED`	403	Request outside tier's allowed history range
`RATE_LIMITED`	429	Rate limit exceeded
`TIMEOUT`	504	Query exceeded 30 second timeout
`INTERNAL_ERROR`	500	Internal server error

Take Profit Heatmap

On this page