---
title: "Liquidation History"
method: GET
path: "/derivatives/liquidations/{symbol}"
tags: ["derivatives"]
---

# Liquidation History

`GET /derivatives/liquidations/{symbol}`

## Request

- Base URL: `https://mcp.f1ow.com/v1`
- URL: `https://mcp.f1ow.com/v1/derivatives/liquidations/{symbol}`
- Auth: one of:
  - HTTP bearer
  - none

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 (OKX, Gate) 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.

## Path parameters

- `symbol` string, required: Coin symbol, e.g. "BTC".

## Query parameters

- `hours` integer: Trailing window in hours, 1–72. Default 24.
- `interval` '5m' | '15m' | '1h': Bucket size for the timing sample. Default 15m.
- `top_orders` integer: Largest individual liquidations to list, 0–20. Default 5.

## Response `200`

The result.

- object
  - `data` object
    - `symbol` string, required
    - `windowHours` integer
    - `interval` string
    - `marketWide24h` object: CoinGlass trailing-24h totals and per-venue split
      - `longUsd` number
      - `shortUsd` number
      - `venues` object[]
        - `venue` string
        - `longUsd` number
        - `shortUsd` number
        - `sharePct` number
    - `marketBuckets4h` object[]: Market-wide 4h buckets overlapping the window, oldest first
      - `timeMs` integer
      - `longUsd` number
      - `shortUsd` number
      - `forming` boolean: Bucket still open; its totals will grow
    - `sample` object
      - `venues` string[]
      - `sharePct24h` number: Sample venues' share of the trailing-24h market-wide total
      - `coveredFromMs` integer: Earliest time every sample venue covers; earlier is unknown, not quiet
      - `note` string
    - `baseline1y` object: The trailing ~24h (newest six 4h buckets) ranked against a year of CoinGlass daily totals over the same venues
      - `available` boolean
      - `note` string, nullable: Why the baseline is missing
      - `days` integer, nullable: Settled days ranked against
      - `trailingFromMs` integer, nullable: Start of the trailing window (20-24h back)
      - `longs` object, nullable
        - `usd` number: Trailing-window total
        - `percentile` number: Rank among the year's settled daily totals, 0-100
        - `medianDayUsd` number
        - `largestSinceMs` integer, nullable: Newest day at or above this total, set only from the 75th percentile up; null there means above every day of the year
      - `shorts` object, nullable
        - `usd` number: Trailing-window total
        - `percentile` number: Rank among the year's settled daily totals, 0-100
        - `medianDayUsd` number
        - `largestSinceMs` integer, nullable: Newest day at or above this total, set only from the 75th percentile up; null there means above every day of the year
      - `largestLongDays` object[]
        - `timeMs` integer
        - `usd` number
      - `largestShortDays` object[]
        - `timeMs` integer
        - `usd` number
    - `cascades` object[]
      - `startMs` integer
      - `endMs` integer
      - `side` 'long' | 'short'
      - `usd` number
      - `orders` integer
      - `lowPriceUsd` number
      - `highPriceUsd` number
    - `cascadeRule` string
    - `largestOrders` object[]
      - `timeMs` integer
      - `venue` string
      - `side` string
      - `usd` number
      - `priceUsd` number
    - `sourcesFailed` object[]
      - `source` string
      - `error` string
  - `text` string, required: Human-readable rendering of the result.
  - `meta` ResponseMeta
    - `generatedAt` string, date-time: When the data was produced (source timestamp where the provider has one), ISO 8601 UTC

## Other responses

- `400`: An argument is missing or invalid.
- `401`: No credential was sent.
- `402`: x402 route: a priced call without a valid payment (challenge in the base64 PAYMENT-REQUIRED header). Metered routes: the account balance or access period is spent.
- `403`: The credential was rejected.
- `500`: Unexpected server error.
- `502`: The data source could not answer.

---

[API](https://skmtc.dev/f1ow/apis/f1ow-api.md) · [All operations](https://skmtc.dev/f1ow/apis/f1ow-api/llms.txt) · [OpenAPI document](https://skmtc.dev/f1ow/apis/f1ow-api/revisions/6974f25b6067?raw)