---
title: "Squeeze Alerts"
method: GET
path: "/api/v1/market-intelligence/squeeze-alerts"
tags: ["Market Intelligence"]
---

# Squeeze Alerts

`GET /api/v1/market-intelligence/squeeze-alerts`

## Request

- Base URL: `https://cryptodataapi.com`
- URL: `https://cryptodataapi.com/api/v1/market-intelligence/squeeze-alerts`
- Auth: API key in header `X-API-Key`

Coins whose forced-liquidation flow is one-sided and abnormal *right now*.

A cascade tripwire, not a news feed. Scored catalysts on
``/news/market-moving`` are 15-45 minutes behind a breaking story — RSS is
polled every 5 minutes and desks publish well after the fact — which is no
use to a leveraged position. This reads the liquidation websocket directly:
on 2026-08-19 the BTC tape printed **$322.8M of short liquidations in one
5-minute bucket at a 334x short/long ratio, 23 minutes before** the first
related headline qualified for the tape.

**`direction` names the side being LIQUIDATED, not the price.** A short
liquidation is the exchange closing a short at market — forced buying — so
`short_squeeze` is upward pressure and `long_flush` is downward, and the
label is correct before price confirms it.

**`oi_state` is what separates the two cases that matter.** Open interest
falling into a short squeeze means shorts are being closed out (the move is
consuming its own fuel); OI rising means fresh positioning is being added
into it. It reads `null` until the OI history has two samples, and `unclear`
inside a ±0.5% noise band rather than being forced into a story.

**Severity is built from ratios**, not dollars: `spike_ratio` (this window
against the coin's own trailing-24h mean) and `asymmetry` (the dominant
side's share) carry 80% of the weight. Absolute notionals are the figure
most distorted by the coverage gap below, so they are weighted least.

**Coverage:** the same venue subset as ``/market-intelligence/liquidations``
(OKX + Bybit + Hyperliquid where armed; Hyperliquid is exact per-fill).
Binance geo-blocks its liquidation stream from our infrastructure, so
notionals run below a true all-exchange total.

**Check `baseline_span_h`, not `window_uptime_h`.** `spike_ratio` compares a
window against a trailing-24h mean, and `baseline_span_h` is how many hours
of history are actually behind that mean — it is what triggering is gated on.
`window_uptime_h` is process uptime and resets on every deploy, while the
feed restores up to 24h of events from its snapshot on boot, so the two
routinely disagree by a full day.

**`triggered` requires every gate**: `spike_ratio` ≥ 2, `asymmetry` ≥ 0.70,
`severity` ≥ 0.35, window notional ≥ $100k and ≥ 1h of baseline history.
`suppressed_by` names whichever blocked it. The two absolute floors exist
because notional is only 20% of the severity weight — without them a
perfectly one-sided window scores 0.80 on any size at all, which in
production raised alerts on $760 of liquidations. They gate the alert, not
the scoring, so `include_quiet=true` still returns the row with the reason.

The free tier is scoped to BTC; full-universe coverage is Pro and Pro Plus.

## Query parameters

- `symbol` string: Filter to a single coin (e.g. BTC)
- `window_s` integer: Trailing window in seconds (default 300 = 5 min)
- `min_severity` number: Minimum severity to report
- `include_quiet` boolean: Return every coin with a usable window, not just the ones firing. For calibration
- `limit` integer: Max coins to scan

## Response `200`

Successful Response

- SqueezeAlertsResponse: Coins whose forced-liquidation flow is currently one-sided and abnormal.
  - `as_of` integer, required
  - `window_s` integer, required
  - `min_severity` number, required
  - `count` integer, required
  - `evaluated` integer, required: Coins that had a usable liquidation window. `count` of these cleared the thresholds
  - `coverage` string, nullable
  - `alerts` SqueezeAlert[], required
    - `symbol` string, required
    - `direction` string, required: short_squeeze | long_flush | balanced. Named after the side being LIQUIDATED: a short liquidation is forced buying, so short_squeeze is upward pressure
    - `severity` number, required: 0..1 composite of spike_ratio, asymmetry and notional. Ratios carry 80% of the weight because absolute notionals run low (Binance excluded)
    - `triggered` boolean, required: True when every gate clears: spike_ratio, asymmetry, severity, a minimum absolute notional and a minimum baseline age — i.e. a cascade is firing, not just churn
    - `suppressed_by` string[]: Which gates blocked the alert, empty when triggered. One or more of: no_spike_baseline, spike_ratio, asymmetry, severity, min_notional (window below the absolute floor — the ratios alone must not be able to raise an alert on four-figure flow), baseline_too_young (feed reconnected too recently for spike_ratio to be a fair comparison)
    - `window_s` integer, nullable: Trailing window the figures cover, in seconds
    - `long_liq_usd` number, required
    - `short_liq_usd` number, required
    - `total_liq_usd` number, required
    - `asymmetry` number, required: Dominant side's share of window notional: 0.5 = two-sided churn, 1.0 = entirely one-sided
    - `side_ratio` number, nullable: Dominant side divided by the opposing side (the '334x' figure). null when the opposing side is exactly zero
    - `spike_ratio` number, nullable: Window liquidation total vs this coin's own trailing-24h mean over an equal window. ~1 is normal; >= 2 is required to trigger
    - `liq_24h_usd` number, nullable
    - `oi_change_pct` number, nullable: Open-interest change over the same window. null until the OI history has two samples
    - `oi_state` string, nullable: covering | fresh_longs | capitulating | fresh_shorts | unclear. Reads oi_change_pct against `direction`: OI falling into a short squeeze means shorts are being closed out; OI rising means the move is being fed. null when OI is unavailable
    - `price_change_24h_pct` number, nullable: Context only — 24h mark vs prevDayPx. Direction is derived from liquidation flow, not from this
    - `legs` object: The three severity components before weighting
    - `coverage` string, nullable: Which venue feeds the totals aggregate
    - `window_uptime_h` number, nullable: Hours the liquidation FEED PROCESS has been connected. Not the same as baseline_span_h — the feed restores up to 24h of events from its snapshot on boot, so this resets on every deploy while the history does not
    - `baseline_span_h` number, nullable: Hours of history actually behind spike_ratio. This is the number to check before trusting a spike; triggering is gated on it, not on window_uptime_h

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/cryptodataapi/apis/crypto-data-api.md) · [All operations](https://skmtc.dev/cryptodataapi/apis/crypto-data-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cryptodataapi/apis/crypto-data-api/revisions/8628b754ca81?raw)