Reference

Liquidations

Recent liquidation events and bucketed historical liquidation volume per protocol.

Liquidations search

GET

Search GMTrade liquidation events, newest first — cursor-paginated for deep history. Up to 500 rows per page.

History depth

Starter · 30dPro · 90dPremium · Full

Headers

x-api-keystringrequired

API key sent in the request header; never accepted as a query parameter.

Query parameters

marketstring

Filter to a market. Results may aggregate protocol-native variants that share the market symbol.

market_variantstring

Filter to a protocol-native market variant.

fromstring

Inclusive RFC 3339 window start; defaults to the plan's history limit.

tostring

Inclusive RFC 3339 window end; defaults to the current time.

cursorstring

Opaque token from the previous page; omit for the first page and keep all filters unchanged while paging.

Response

200

{ data: Liquidation[], next_cursor }

Liquidation

timeTimestamp when the liquidation executed.

market_variantProtocol-native market variant identifier; null when unavailable.

marketMarket symbol (e.g. SOL-PERP).

sideSide of the liquidated position.long | short

size_usdLiquidated notional (USD).

collateral_usdCollateral held at liquidation (USD).

priceOracle price at liquidation.

addressWallet address of the liquidated account.

txTransaction signature.

position_idIdentifier of the liquidated position lifecycle; null when unavailable.

next_cursorToken for the next older page; null on the final page or at the plan's history limit.

Request

cURL

curl --request GET \
  --url https://api.perpdb.xyz/v1/gmtrade/liquidations/search \
  --header 'x-api-key: ak_...'

Example

{
  "data": [
    {
      "time": "2026-10-24T23:33:16.000Z",
      "market": "FARTCOIN-PERP",
      "market_variant": "FARTCOIN/USD[WSOL-USDC]",
      "side": "short",
      "size_usd": 5000,
      "collateral_usd": 130.012214923068,
      "price": 0.12861146770624,
      "address": "4LzJpizGbXmwJ65PqBYJUqMroTsTKN4ZzbopV7o732D9",
      "tx": "Hc1uJqPQjQxrHkVSZnyJPu3XDA7yAT4Giwv12JZ8t7UULewgy42jUkCR2M6aVxQpi5dRW73E2A1vZtyNBCrN7usQ",
      "position_id": 43968884
    },
    {
      "time": "2026-10-24T23:33:14.000Z",
      "market": "ETH-PERP",
      "market_variant": "ETH/USD[USDC]",
      "side": "short",
      "size_usd": 10730,
      "collateral_usd": 195.79071028929002,
      "price": 2356.201984236652,
      "address": "VB1RYifkPTYvrVqpdEyadbH8bihTUERD4nMfrXdnJts9",
      "tx": "BwhChSCgjm1gebUcovnCZ6qnsgAuz31RcAGCXtTZmmiPrChkHN9m71gS4VcTH2tKyw26vQjbpf3UdGYGLbdPYMit",
      "position_id": 43968486
    }
  ],
  "next_cursor": "MjAyNi0xMC0yMFQxNToxMzo1Mi4wMDBafDVYS0dLUG05dEUxQ3AyejhGTWJFa3ZDTmM5R0FrVzhtYU5jVnViVFlxS3RSQ1Z6aUU0WGFham9VMmJEZ0p3bVZDaEM1bVRRRlV0d3ZUazhldHFaOUtqaUR8Q0RoZ0xoWkdrdjJqMTRQRkRoOVcySlp5UkFKMXRrVFU1eWY3UjhNdlptQlZ8MjllMmRjZmJiMTZm"
}

Liquidation history

GET

GMTrade liquidation volume bucketed by time (count, long/short/total).

History depth

Starter · 30dPro · 90dPremium · Full

Headers

x-api-keystringrequired

API key sent in the request header; never accepted as a query parameter.

Query parameters

marketstring

Filter to a market. Results may aggregate protocol-native variants that share the market symbol.

interval1h | 4h | 1d

Aggregation bucket size.

fromstring

Inclusive window start as an RFC 3339 timestamp; defaults per endpoint.

tostring

Exclusive window end as an RFC 3339 timestamp; defaults to the current time.

Response

200

{ interval, from, to, data: Bucket[] }

Bucket

timeStart of the aggregation bucket.

countNumber of liquidations in the bucket.

long_usdLiquidated long notional in the bucket (USD).

short_usdLiquidated short notional in the bucket (USD).

total_usdTotal liquidated notional in the bucket (USD).

Request

cURL

curl --request GET \
  --url https://api.perpdb.xyz/v1/gmtrade/liquidations/history?interval=1d \
  --header 'x-api-key: ak_...'

Example

{
  "interval": "1h",
  "from": "2026-10-11T01:27:30.492Z",
  "to": "2026-10-25T01:27:30.492Z",
  "data": [
    {
      "time": "2026-10-11T03:00:00.000Z",
      "count": 14,
      "long_usd": 47338.096189136995,
      "short_usd": 0,
      "total_usd": 47338.096189136995
    },
    {
      "time": "2026-10-11T04:00:00.000Z",
      "count": 3,
      "long_usd": 14861.788334813358,
      "short_usd": 0,
      "total_usd": 14861.788334813358
    }
  ]
}