Hyperliquid liquidations: history by coin in Python

export VIKE_API_KEY=...
python hl-liquidations-around-move.py             # real run: needs the key
python hl-liquidations-around-move.py --dry-run   # prints the requests it would make, calls nothing

"""Find the biggest BTC hourly move of one day, then total the liquidations that landed in that hour.

Run:  VIKE_API_KEY=... python hl-liquidations-around-move.py    (--dry-run lists the requests and makes none)
"""
import os
import sys
from datetime import datetime, timezone
from urllib.parse import urlencode

NAME = "hl-liquidations-around-move"
BASE = "https://data.vike.io"
DRY = "--dry-run" in sys.argv


def fail(why):
    sys.exit(f"{NAME}: {why}")


def call(path, method="GET", **params):
    url = BASE + path + ("?" + urlencode(params) if params else "")
    if DRY:
        print(method, url)
        return None
    key = os.environ.get("VIKE_API_KEY") or fail("set VIKE_API_KEY")
    import requests

    r = requests.request(method, url, headers={"X-API-Key": key}, timeout=60)
    if r.status_code != 200:
        fail(f"{method} {path} answered HTTP {r.status_code}: {r.text[:200]}")
    return r.json()


def iso(ms):
    return datetime.fromtimestamp(ms / 1000, timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")


def main():
    # end is exclusive on /ohlcv: this is the 24 hourly bars of 2026-08-17.
    day = call("/v1/hyperliquid/ohlcv", symbol="BTC", interval="1h", limit=24,
               start="2026-08-17T00:00:00Z", end="2026-08-18T00:00:00Z")
    move_ts = 1786924800000  # --dry-run has no response to read
    if not DRY:
        if not day["candles"]:
            fail("no BTC candles for the day")
        biggest = max(day["candles"], key=lambda c: abs(c["close"] / c["open"] - 1))
        move_ts = biggest["ts"]
        print(f"biggest hour: {iso(move_ts)}  {biggest['close'] / biggest['open'] - 1:+.2%}  ({biggest['open']:g} -> {biggest['close']:g})")

    # /liquidations is newest-first, its bounds are whole seconds and its end is inclusive; 5000 is the most
    # one page holds. The hour's own end is passed, and a fill stamped exactly on it is dropped below.
    hour_end = move_ts + 3_600_000
    liqs = call("/v1/hyperliquid/liquidations", symbol="BTC", limit=5000, start=iso(move_ts), end=iso(hour_end))
    if DRY:
        return
    rows = [r for r in liqs["liquidations"] if datetime.fromisoformat(r["liq_ts"]).timestamp() * 1000 < hour_end]
    if not rows:
        fail("no BTC liquidations in the move's hour")
    if liqs["nextCursor"]:
        print("  (a full page: the totals below cover the newest 5000 rows of the hour only)")
    # `side` is the side of the position that was closed: "long" means longs were liquidated.
    for side in ("long", "short"):
        hit = [r for r in rows if r["side"] == side]
        print(f"  {side:5} liquidated: {len(hit):5} fills  ${sum(r['size_usd'] for r in hit):,.0f}")


if __name__ == "__main__":
    try:
        main()
    except Exception as e:  # a shape the example does not expect fails by name, not by traceback
        fail(f"{type(e).__name__}: {e}")