GateData.AI

Exchange token liquidity history

Query historical token liquidity changes within exchanges.

GET/api/v1/markets/liquidity/history
Domain
Market & Liquidity
Level
Crypto listing
MCP tool
market_data_query (task=liquidity)

Available data

Returns
Historical token liquidity changes within exchanges
Market coverage
Crypto listings
Query granularity
One listing per query; each row is an interval aggregate of historical snapshots, not the live order book

Authentication

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

Query Parameters

Object positioning

Provide at least one of listing_id, query, or base. Gate may return no_liquidity_history; Binance/OKX have data.

listing_idstringqueryExamplelisting_binance_BTC_USDT_spotoptional

Canonical listing identifier

querystringqueryExampleBTCoptional

Search text used to resolve the query object

basestringqueryExampleBTCoptional

Base asset code of the trading pair

Market routing

All optional.

venuestringqueryExamplebinanceoptional

Trading venue code to query

market_typeMarketTypequeryExamplespotoptional

Type of traded product

quotestringqueryExampleUSDToptional

Quote asset code of the trading pair

Aggregation

All optional.

timeframeHistoryTimeframequeryExample1hoptional

Aggregation period for each record

Time range

Prefer start_time with end_time.

start_timedatetimequeryExample2026-07-01T00:00:00Zoptional

Start of the query time range

end_timedatetimequeryExample2026-07-31T23:59:59Zoptional

End of the query time range

Response

items[]array[object (LiquidityHistoryItem)]

Business records

time_bucketdatetimeExample2026-06-12T05:00:00Z

Start time of the historical data bucket

timeframeHistoryTimeframeExample1h

Aggregation period for this record

mid_pricenumber | nullExample63400.004

Midpoint of the best bid and best ask

spread_bpsnumber | nullExample0.001577

Bid-ask spread in basis points

bid_depth_1pct_usdnumber | nullExample1092819.4

Bid notional within the 1% price band

ask_depth_1pct_usdnumber | nullExample267901.38

Ask notional within the 1% price band

two_sided_depth_1pct_usdnumber | nullExample1360720.8

Two-sided notional within the 1% price band

snapshot_countintegerExample4

Number of source order-book snapshots in the bucket

source_snapshot_timedatetime

Latest source snapshot time used by the bucket

data_statusDataStatusExampleready

Availability of this business record

timeframestringExample1h

Aggregation period for each record

reasonstring

Human-readable explanation for an empty result

next_actionstring

Suggested action when no result is available

try_paramsobject

Suggested parameters for a retry

asset_idstring

Canonical asset identifier

basestring

Base asset code

listing_idstring

Canonical listing identifier

marketMarket

Market of the query object

market_typeMarketType

Type of traded product

quotestring

Quote asset code

timeframestring

Aggregation period for each record

venuestring

Trading venue code

empty_reasonstring | null

Reason code for missing data or fields

data_statusDataStatusExampleready

Availability of the business data

metadataobject

Response status and resolution information

data_statusDataStatusExampleready

Availability of the business data

actual_taskstring

Task that was actually executed

route_reasonstring

Reason the task or object was selected

limitations[]string[]

Known data limitations

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

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_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.