GateData.AI

Derivatives · Liquidation aggregates

Query aggregated long and short liquidation data at different time granularities for a pair or a coin across venues.

GET/api/v1/markets/derivatives/liquidations/aggregates
Domain
Market & Liquidity
Level
Crypto liquidation time buckets
MCP tool
market_data_query (task=liquidation_aggregates)

Available data

Returns
Aggregated long and short liquidation data at different time granularities for a pair or a coin across venues
Market coverage
Crypto derivatives markets
Query granularity
PAIR returns one venue pair; COIN aggregates a coin across venues. Missing buckets are not filled with zero

Authentication

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

Query Parameters

Aggregation scope

scope is required. PAIR queries one venue pair; COIN aggregates by coin.

scopePAIR | COINqueryExampleCOINrequired

PAIR aggregates one venue pair; COIN aggregates by coin.

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

Venue and pair

PAIR requires venue and venue_symbol. COIN may use venue, but must not include venue_symbol.

venuestringqueryExamplebinanceconditional

Trading venue code to query

venue_symbolstringqueryExampleBTCUSDTconditional

Venue pair such as BTCUSDT. Used only by PAIR and required in PAIR mode.

Time range and interval

Times accept Unix milliseconds or RFC 3339; only the 1h interval is currently available.

interval1hqueryExample1hoptional

Bucket interval; currently only 1h is supported and is the default.

start_timestringqueryExample1789977600000optional

Start of the query time range

end_timestringqueryExample1790582400000optional

End of the query time range

limitintegerqueryExample1000optional

Maximum records returned per request

Response

items[]object[]

Liquidation amount time buckets

bucket_startintegerExample1789977600000

Bucket start in Unix milliseconds

bucket_endintegerExample1789981200000

Bucket end in Unix milliseconds

scopePAIR | COINExampleCOIN

Aggregation scope

asset_idstringExampleasset_btc

GateData asset identifier

base_assetstringExampleBTC

Base asset symbol

venuestringExamplebinance

Venue code

venue_symbolstring

Venue pair in PAIR scope

long_liquidation_usdstringExample501202.3

Long-position liquidation amount

short_liquidation_usdstringExample78877728

Short-position liquidation amount

total_liquidation_usdstringExample79378930.3

Total long and short liquidation amount

intervalstringExample1h

Bucket interval

start_timeintegerExample1789977600000

Effective query start time

end_timeintegerExample1790582400000

Effective query end time

coverageobject

Requested range and data coverage

disclaimerstringExampleMissing buckets do not mean zero liquida…

Aggregate data disclaimer

metadataobject

Response status and resolution information

data_statusDataStatusExampleready

Business data availability status

limitations[]string[]

Known data limitations

updated_atdatetime | stringExample2026-09-28T08:26:01Z

Most recent object or response update time

partialboolean

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_fromstring

Input used to resolve the object

resolution_confidencestring

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.