Map liquidation cascades from raw events in Python.
Optiom Research · runnable code, tested against the live API
Liquidations are forced orders: when price moves through a cluster of over-leveraged positions, the exchange closes them at market, amplifying the move. Optiom exposes the raw event stream — timestamp, side, price, quantity, notional, venue. This tutorial aggregates it into an hourly cascade map.
Fetch and aggregate
The endpoint returns individual liquidation events. Group by hour and side to see when cascades happened, then rank single events by notional to find the prints that mattered. 'long' means longs were liquidated (price moving down).
import pandas as pd
import requests
BASE = "https://www.getoptiom.com/api/tradinghub"
SYMBOL = "BTCUSDT"
res = requests.get(
f"{BASE}/liquidations",
params={"symbol": SYMBOL, "max_rows": 20_000},
timeout=30,
)
res.raise_for_status()
df = pd.DataFrame(res.json()["rows"])
df["ts"] = pd.to_datetime(df["ts"], utc=True, format="mixed")
print(df.groupby("side")["notional_usd"].agg(["count", "sum"]))
hourly = (
df.set_index("ts")
.groupby([pd.Grouper(freq="1h"), "side"])["notional_usd"]
.sum()
.unstack(fill_value=0.0)
)
print(hourly.tail(12).round(0))
print(df.nlargest(10, "notional_usd")[
["ts", "side", "price", "qty", "notional_usd", "venue"]
])Reading the output
Hours where one side dominates by 10x+ are cascade signatures — they often mark local extremes because the forced flow exhausts itself. Compare the top single events against your chart: large liquidations at a level frequently define support/resistance that the market retests.
Going further
The liquidation heatmap in the Optiom terminal is this same data binned by price and time. For a live workflow, poll this endpoint and alert on notional spikes, or join it with candles (GET /ohlcv) to backtest post-cascade mean reversion.
Run it on your own data.
Create a free account for CSV exports, then move to API access as your workflow grows.