# Liquidation History (`derivatives_liquidations`)

> Market-wide long/short liquidations and venue splits, ranked against a year of daily totals. A separate order sample reveals timing, cascades and the largest forced exits; its coverage is stated, never scaled up to the whole market.

- Category: Derivatives
- MCP tool: `derivatives_liquidations`
- REST: `GET /derivatives/liquidations/{symbol}`
- MCP App: hosts that support MCP Apps render the result as an interactive view
- x402 price: $0.02 per call (USDC on Base)
- HTML: https://www.f1ow.com/docs/tools/derivatives_liquidations

## What it does

Liquidation history for one coin's perpetuals: market-wide long/short liquidations (USD) in 4h buckets and the 24h split by venue, plus a minute-level timing sample of individual liquidation orders from venues that publish them with detected cascades (time, side, size, order count, price range) and the largest orders. The sample is a share of the market, stated per bucket, never scaled up. Use it to say WHEN and WHICH SIDE was forced out, instead of inferring liquidations from price and open interest: flat OI can hide heavy liquidations that new positions replaced. A 1y baseline ranks the trailing ~24h of longs and shorts against a year of daily totals (percentile, 'largest since' date, median day, the year's three largest days per side), so a figure can be called big or routine for this coin.

## Parameters

| Name | Type | In | Required | Description |
| --- | --- | --- | --- | --- |
| `symbol` | string | path | yes | Coin symbol, e.g. "BTC". |
| `hours` | integer | query | no | Trailing window in hours, 1–72. Default 24. |
| `interval` | string | query | no | Bucket size for the timing sample. Default 15m. One of: `5m`, `15m`, `1h`. |
| `top_orders` | integer | query | no | Largest individual liquidations to list, 0–20. Default 5. |

## Call it

### cURL

```bash
curl "https://mcp.f1ow.com/v1/derivatives/liquidations/BTC?hours=24" \
  -H "Authorization: Bearer $F1OW_API_KEY"
```

### MCP

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "derivatives_liquidations",
    "arguments": {
      "symbol": "BTC",
      "hours": 24
    }
  }
}
```

### TypeScript

```ts
const res = await fetch("https://mcp.f1ow.com/v1/derivatives/liquidations/BTC?hours=24", {
  headers: { Authorization: `Bearer ${process.env.F1OW_API_KEY}` },
});
const data = await res.json(); // the tool's result as JSON, typed in the OpenAPI spec
console.log(data);
```

### Python

```python
import os, requests

res = requests.get(
    "https://mcp.f1ow.com/v1/derivatives/liquidations/BTC?hours=24",
    headers={"Authorization": f"Bearer {os.environ['F1OW_API_KEY']}"},
)
data = res.json()  # the tool's result as JSON, typed in the OpenAPI spec
print(data)
```

### WebSocket

```jsonc
// wss://mcp.f1ow.com/v1/ws — subprotocol "jsonrpc-2.0", Authorization: Bearer <key>
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "derivatives_liquidations",
    "arguments": {
      "symbol": "BTC",
      "hours": 24
    }
  }
}

// Or push a fresh result whenever it changes (minimum interval 15 s)
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "subscriptions/subscribe",
  "params": {
    "name": "derivatives_liquidations",
    "arguments": {
      "symbol": "BTC",
      "hours": 24
    },
    "intervalSeconds": 60
  }
}
```

### x402

```bash
# No account: the first call answers 402 with a PAYMENT-REQUIRED challenge;
# an x402 client pays it in USDC on Base and retries.
curl "https://mcp.f1ow.com/x402/v1/derivatives/liquidations/BTC?hours=24"
```

## Sample response

Captured 2026-11-13. The JSON is what REST and WebSocket return and the `structuredContent` of an MCP call (trimmed):

```json
{
  "baseline1y": {
    "available": true,
    "days": 364,
    "largestLongDays": [
      {
        "timeMs": 1770249600000,
        "usd": 977556697.513305
      },
      {
        "timeMs": 1780358400000,
        "usd": 799548479.571316
      },
      {
        "timeMs": 1763683200000,
        "usd": 764248113.28377
      }
    ],
    "largestShortDays": [
      {
        "timeMs": 1787097600000,
        "usd": 1361041105.36
      },
      {
        "timeMs": 1787270400000,
        "usd": 731337071.57
      },
      {
        "timeMs": 1789948800000,
        "usd": 558415324.29
      }
    ],
    "longs": {
      "largestSinceMs": 1770249600000,
      "medianDayUsd": 38453835.1137,
      "percentile": 99.7252747252747,
      "usd": 858428120.32
    },
    "shorts": {
      "medianDayUsd": 30201776.4148211,
      "percentile": 62.0879120879121,
      "usd": 42056273.4
    },
    "trailingFromMs": 1794484800000
  },
  "cascadeRule": "a timing-sample bucket is part of a cascade when one side is >= max($100k, 4x that side's mean bucket, 1.5x the mean bucket of both sides) over the window and >= 60% of the bucket; adjacent qualifying buckets on the same side merge",
  "cascades": [
    {
      "endMs": 1794493800000,
      "highPriceUsd": 72229,
      "lowPriceUsd": 71720.6,
      "orders": 700,
      "side": "long",
      "startMs": 1794492900000,
      "usd": 21191294.583974
    },
    {
      "endMs": 1794495600000,
      "highPriceUsd": 71715.8,
      "lowPriceUsd": 71245.9,
      "orders": 429,
      "side": "long",
      "startMs": 1794494700000,
      "usd": 6183549.798427
    },
    {
      "endMs": 1794530700000,
      "highPriceUsd": 71109.5,
      "lowPriceUsd": 70659.8922120961,
      "orders": 491,
      "side": "long",
      "startMs": 1794529800000,
      "usd": 10250743.079611
    },
    {
      "endMs": 1794540600000,
      "highPriceUsd": 69752.37,
      "lowPriceUsd": 68909,
      "orders": 1198,
      "side": "long",
      "startMs": 1794539700000,
      "usd": 20080680.410222
    },
    {
      "endMs": 1794542400000,
      "highPriceUsd": 69010.916872428,
      "lowPriceUsd": 68486,
      "orders": 647,
      "side": "long",
      "startMs": 1794541500000,
      "usd": 11734454.297147
    },
    {
      "endMs": 1794549600000,
      "highPriceUsd": 68625,
      "lowPriceUsd": 67513.8,
      "orders": 808,
      "side": "long",
      "startMs": 1794548700000,
      "usd": 30203884.520251
    }
  ],
  "interval": "15m",
  "largestOrders": [
    {
      "priceUsd": 67937.1923428,
      "side": "long",
      "timeMs": 1794549402000,
      "usd": 10190578.85142,
      "venue": "Gate"
    },
    {
      "priceUsd": 72085.2,
      "side": "long",
      "timeMs": 1794493229106,
      "usd": 9371140.87668,
      "venue": "OKX"
    },
    {
      "priceUsd": 70746.5,
      "side": "long",
      "timeMs": 1794530193231,
      "usd": 3537325,
      "venue": "OKX"
    },
    {
      "priceUsd": 70370.9,
      "side": "long",
      "timeMs": 1794536331213,
      "usd": 3518545,
      "venue": "OKX"
    },
    {
      "priceUsd": 69327.5,
      "side": "long",
      "timeMs": 1794540078190,
      "usd": 3466375,
      "venue": "OKX"
    }
  ],
  "marketBuckets4h": [
    {
      "forming": false,
      "longUsd": 17808650.61,
      "shortUsd": 330570.78,
      "timeMs": 1794470400000
    },
    {
      "forming": false,
      "longUsd": 227717223.97,
      "shortUsd": 5621167.07,
      "timeMs": 1794484800000
    },
    {
      "forming": false,
      "longUsd": 4711732.7,
      "shortUsd": 3012744.18,
      "timeMs": 1794499200000
    },
    {
      "forming": false,
      "longUsd": 7119806.57,
      "shortUsd": 396494.68,
      "timeMs": 1794513600000
    },
    {
      "forming": false,
      "longUsd": 452537567.26,
      "shortUsd": 17091522.68,
      "timeMs": 1794528000000
    },
    {
      "forming": false,
      "longUsd": 166208043.29,
      "shortUsd": 15934310.51,
      "timeMs": 1794542400000
    },
    "… 1 more"
  ],
  "marketWide24h": {
    "longUsd": 876235433.883851,
    "shortUsd": 42386549.6227622,
    "venues": [
      {
        "longUsd": 301152189.320499,
        "sharePct": 33.952881835436,
        "shortUsd": 10746447.25384,
        "venue": "Binance"
      },
      {
        "longUsd": 306265415.189667,
        "sharePct": 33.4356784258187,
        "shortUsd": 882077.164481,
        "venue": "Hyperliquid"
      },
      {
        "longUsd": 127257823.0347,
        "sharePct": 14.4159495196477,
        "shortUsd": 5170258.384,
        "venue": "Bybit"
      },
      {
        "longUsd": 60046180.306798,
        "sharePct": 7.01609609064206,
        "shortUsd": 4405220.765788,
        "venue": "Gate"
      },
      {
        "longUsd": 31252256.4577,
        "sharePct": 3.59383486073544,
        "shortUsd": 1761500.62394,
        "venue": "OKX"
      },
      {
        "longUsd": 28745064.0751413,
        "sharePct": 3.30494148968001,
        "shortUsd": 1614854.99109019,
        "venue": "Bitget"
      },
      "… 4 more"
    ]
  },
  "sample": {
    "coveredFromMs": 1794471065240,
    "note": "Timing sample from venues that publish individual liquidations; a share of the market, never scaled up.",
    "sharePct24h": 10.6099309513775,
    "venues": [
      "OKX",
      "Gate"
    ]
  },
  "sourcesFailed": [],
  "symbol": "BTC",
  "windowHours": 24,
  "generatedAt": "2026-11-13T08:06:07.5130301+00:00"
}
```

Over MCP the text report a model reads comes with it:

```text
BTC liquidations, last 24h (UTC)
  market-wide 24h (CoinGlass, 10 venues): longs $876.2M / shorts $42.4M
    by venue: Binance 34% · Hyperliquid 33% · Bybit 14% · Gate 7% · OKX 4% · Bitget 3%
  4h buckets, market-wide (CoinGlass):
    11-12 08:00  longs   $17.8M  shorts    $331k
    11-12 12:00  longs  $227.7M  shorts    $5.6M
    11-12 16:00  longs    $4.7M  shorts    $3.0M
    11-12 20:00  longs    $7.1M  shorts    $396k
    11-13 00:00  longs  $452.5M  shorts   $17.1M
    11-13 04:00  longs  $166.2M  shorts   $15.9M
    11-13 08:00  longs    $134k  shorts      $34  (forming)
  1y baseline (CoinGlass daily totals, 364 days): trailing 20h since 11-12 12:00 UTC ranked against whole days
    longs   $858.4M  100th percentile of days, largest since 2026-02-05 · median day $38.5M
    shorts   $42.1M  62nd percentile of days · median day $30.2M
    largest days: longs $977.6M (2026-02-05), $799.5M (2026-06-02), $764.2M (2025-11-21) | shorts $1.36B (2026-08-19), $731.3M (2026-08-21), $558.4M (2026-09-21)
  timing sample: OKX + Gate, 15m buckets (10.6% of the trailing 24h market-wide, by CoinGlass's split)
    cascades (6):
      11-12 14:15–14:30  longs    $21.2M   700 orders  $71720.60–$72229.00
      11-12 14:45–15:00  longs     $6.2M   429 orders  $71245.90–$71715.80
      11-13 00:30–00:45  longs    $10.3M   491 orders  $70659.89–$71109.50
      11-13 03:15–03:30  longs    $20.1M  1198 orders  $68909.00–$69752.37
      11-13 03:45–04:00  longs    $11.7M   647 orders  $68486.00–$69010.92
      11-13 05:45–06:00  longs    $30.2M   808 orders  $67513.80–$68625.00
    largest orders:
        $10.2M  long   Gate  11-13 05:56 at $67937.19
         $9.4M  long   OKX   11-12 14:20 at $72085.20
         $3.5M  long   OKX   11-13 00:36 at $70746.50
         $3.5M  long   OKX   11-13 02:18 at $70370.90
         $3.5M  long   OKX   11-13 03:21 at $69327.50
```

## Related tools

- [Perp Flow](https://www.f1ow.com/docs/tools/derivatives_flow) — Bucket-by-bucket open interest joined to taker buy/sell volume. Distinguish new positions from short covering and long unwind, with absorbed flow flagged. Coverage is stated; where taker data is unavailable, the read uses price direction and says so.
- [Funding](https://www.f1ow.com/docs/tools/funding_current) — Current perpetual funding, normalized to an eight-hour rate and annualized, with history and a one-year percentile baseline. Positive means longs pay shorts; it is a cost of holding, not a direction forecast.
- [Open Interest](https://www.f1ow.com/docs/tools/derivatives_open_interest) — Cross-exchange perpetual open interest with historical changes and a one-year baseline — how much leverage is committed, not merely how much changed hands. Venue-specific flow is a separate read.
- [Market Regime](https://www.f1ow.com/docs/tools/research_regime) — What kind of market you are trading in. Seven forces — trend, volatility, cycle, sentiment, leverage stress, ETF liquidity, rotation — each voting with its own reasoning and its own threshold for changing the call.