Derivatives · Liquidation heatmap

Query long and short liquidation intensity across price levels for a trading object, for a liquidation heatmap.

GET/api/v1/markets/liquidation-heatmap

Domain

Market & Liquidity

Level

Crypto asset and price range

MCP tool

market_data_query (task=liquidation_heatmap)

Available data

Returns: Long and short liquidation intensity across price levels for a trading object, for a liquidation heatmap
Market coverage: Crypto markets
Query granularity: One asset and price range per query; the grid is a heatmap estimate rather than a ledger of completed liquidations

Authentication

Send Authorization: Bearer YOUR_API_KEY or X-API-KEY on every request.

Query Parameters

Asset positioning

Provide at least one of asset_id or query.

asset_idstringqueryExampleasset_btcconditional

Canonical asset identifier

querystringqueryExampleBTCconditional

Search text used to resolve the query object

Response

items[]array[object (LiquidationHeatmapItem)]

Business records

price_levelnumber | nullExample60244.95

Heatmap price level

y_indexinteger

Heatmap vertical-axis level index

liq_amount_usdnumber | nullExample287566211.9399997

Liquidation notional in USD

estimated_liq_longnumber | null

Estimated long-side liquidation notional

estimated_liq_shortnumber | null

Estimated short-side liquidation notional

exchangestring | null

Exchange or platform code

rangestringExample3d

Query or model coverage range

snapshot_timedatetimeExample2026-08-17T16:00:00Z

Source snapshot time for the heatmap

liquidation_24hnumber | nullExample109064634278.62999

Liquidation notional over the past 24 hours

liquidation_windowstringExample24h

Liquidation measurement window

heatmap_rangestring | nullExample3d

Heatmap coverage range

aggregation_scopestringExampleall_cex

Aggregation scope covered by the metric

data_statusDataStatusExamplepartial

Availability of the business data

metadataobject

Response status and resolution information

data_statusDataStatusExamplepartial

Availability of the business data

missing_fields[]string[]Exampleestimated_liq_long

Contract fields omitted from the response

actual_taskstring

Task that was actually executed

route_reasonstring

Reason the task or object was selected

limitations[]string[]Exampledata_partial

Known data limitations

updated_atdatetime | stringExample2026-08-17T17:07:22Z

Most recent object or response update time

partialbooleanExampletrue

Whether the response contains only a subset of fields

resolution_reasonstring

Reason code for the object-resolution outcome

object_refs[]object[]

Unified object references

typeObjectRefTypeExampleasset

Object reference type

idstringExampleasset_btc

Canonical object identifier

entity_idstring

Canonical entity identifier

asset_idstringExampleasset_btc

Canonical asset identifier

listing_idstring

Canonical listing identifier

instrument_idstring

Canonical financial instrument identifier

venue_idstring

Canonical trading venue identifier

event_refstring

Related event identifier

market_idstring

Canonical market object identifier

venuestring

Related platform code

resolved_fromstringExampleasset_entity

Input used to resolve the object

resolution_confidencestringExampleresolved

Object resolution confidence

Errors & fallback

200

assets_resolve name multi-match; confirm from data[] candidates.

200

The object resolved but no data is available; empty_reason may be not_covered_by_source, unsupported_metric, or limited_depth.

400

Invalid parameters or an ambiguous market listing; ambiguity responses include required_params + candidates.

401

The API key is missing or invalid.

403

The current key scope or plan cannot access this data domain.

404

The requested resource does not exist; source coverage gaps are not 404 responses.

402

Credits or monthly quota exhausted.

429

Request rate exceeded; retry_after is returned in the body and Retry-After in the response headers.