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-08-15T22:42:54.000Z",
      "market": "FARTCOIN-PERP",
      "market_variant": "FARTCOIN/USD[WSOL-USDC]",
      "side": "short",
      "size_usd": 50328.98615819216,
      "collateral_usd": 753.2680604812001,
      "price": 0.14485802923351,
      "address": "NiTo3rxvjJj27YYbgSGe1KqwkMUoaLNDBK3HMwfMjrEC",
      "tx": "w1XyxohpvKaKV1zZT8Q62yU2SeHM3QoAzFzhn8QzS7YAdq49bVAo3BpfaicaZWVqhRDZSNTgXC9T6d3SVVUPUpBu",
      "position_id": 33499378
    },
    {
      "time": "2026-08-15T22:42:39.000Z",
      "market": "FARTCOIN-PERP",
      "market_variant": "FARTCOIN/USD[WSOL-USDC]",
      "side": "short",
      "size_usd": 6685,
      "collateral_usd": 136.688931038652,
      "price": 0.14456227137044,
      "address": "efdYAqbJ8PnuG9pQ7XzYRwt1PYvkY6m4XN11YVFLUBC3",
      "tx": "wwV8tWDRM7GmCeFwCdvpXjheWLefAkZTVpmeHkEmKZMwqfSiRpNLjL2fwcJGk5anooKsUYXkPXbVMS2FposerWfx",
      "position_id": 33342983
    }
  ],
  "next_cursor": "MjAyNi0wOC0xMlQxMjozMDoxNS4wMDAwMDBafGRpWDhGMkd6aFRtSFlIbWtDQ3JxZGNGYmVDMjRqMUFTeUxOWFRUQ1R6QkVqS01WSnpRaDZRNktMM3BuaFczaFhhQ2Q2WEw0eXFucWdNeXpDWmttTHdpS3xIVGNZYzFzYkNNTHhZYmFMY0M5Tm8yUXdUSzZteXNXbldRc2tTQ2dIZFRjY3wyOWUyZGNmYmIxNmY"
}

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-08-01T23:39:02.304Z",
  "to": "2026-08-15T23:39:02.304Z",
  "data": [
    {
      "time": "2026-08-02T00:00:00.000Z",
      "count": 5,
      "long_usd": 0,
      "short_usd": 126943.35016,
      "total_usd": 126943.35016
    },
    {
      "time": "2026-08-02T01:00:00.000Z",
      "count": 41,
      "long_usd": 0,
      "short_usd": 1332641.1121472614,
      "total_usd": 1332641.1121472614
    }
  ]
}