Crypto Liquidity Regime API: Order-Book Depth, Spreads & Fragility

Why Does Price Move Violently Even When Nothing Changed?

You've seen it: a coin gaps 4% on a single market order, no news, no obvious catalyst. The catalyst was the order book. The bids that should have absorbed the flow weren't there. The book was thin, and one aggressive seller walked it down.

Thin books precede violent moves. Market makers pull depth ahead of vol events, spreads widen, and the same dollar of flow that barely registered yesterday becomes a 4% slide today. Price tells you what already happened; depth tells you what the next move will cost.

The Liquidity / Market Depth regime measures that fragility before it bites. It's Regime #9 of 14 in our regime taxonomy — a real-time read on how deep, how tight, and how stable the book is across the most-traded Hyperliquid perps.

What the Depth Snapshot Endpoint Returns

GET /api/v1/liquidity/depth returns one record per coin for the top-25 Hyperliquid perps by 24h volume. Each record measures cumulative bid/ask notional inside {10, 25, 50, 100} bps of mid, the spread in bps, book imbalance within 10bps, and joined open interest.

curl -H "X-API-Key: cdk_live_yourkey" \
  "https://cryptodataapi.com/api/v1/liquidity/depth"

One coin in the coins array:

{
  "coin": "BTC",
  "ts": 1749600000,
  "mid_price": 67250.5,
  "spread_bps": 0.74,
  "bid_levels": 142,
  "ask_levels": 138,
  "depth_usd": {
    "bid": {"10bps": 412000.0, "25bps": 980000.0,
             "50bps": 2150000.0, "100bps": 4870000.0},
    "ask": {"10bps": 388000.0, "25bps": 940000.0,
             "50bps": 2080000.0, "100bps": 4710000.0}
  },
  "total_depth_25bps_usd": 1920000.0,
  "imbalance_10bps": 0.03,
  "open_interest_usd": 1843000000.0
}

The headline number is total_depth_25bps_usd — combined bid+ask notional you can trade through inside a quarter-percent of mid. A positive imbalance_10bps means more bid than ask at the top of book; negative means sellers are stacked.

The Five Liquidity Regime Classes, Decoded

GET /api/v1/liquidity/regime classifies every tracked coin into exactly one of five regimes. Rules apply in priority order — first match wins — so a coin in cascade aftermath is never mislabelled as merely divergent.

Each coins[] entry carries confidence, a low_confidence flag (set until a coin has 60+ minutes of buffered samples), baseline_minutes, and a signals dict exposing the exact numbers that fired the rule — e.g. depth_drop_10min_pct or oi_change_4h_pct.

Reading OI vs Price Divergence

GET /api/v1/liquidity/oi-divergence ranks the universe by how much open interest is rising relative to price. When traders pile into positions while price stalls, you have crowded, fragile positioning — the fuel for a liquidation cascade.

Each rows[] entry reports price_change_1h_pct, price_change_4h_pct, price_change_24h_pct alongside oi_change_1h_pct, oi_change_4h_pct, and oi_change_24h_pct. The ranking key is divergence_4h — literally oi_change_4h_pct - price_change_4h_pct.

• High positive divergence — OI surging while price is flat or down. Longs (or shorts) trapped and adding. Squeeze risk.
• Near zero — OI tracking price. Healthy trend participation, nothing to flag.
• Negative divergence — OI falling while price holds. Positions unwinding into strength; de-risking, not building.

Coins without enough buffered history for a given window report null for that window rather than a fabricated zero — check before you sort.

How Do I Get a Single Market-Wide Fragility Read?

Per-coin detail is great for a screener; for a dashboard gauge you want one number. GET /api/v1/liquidity/regime/score is the trimmed companion to /regime — same composite, no per-coin list.

import httpx

HDR = {"X-API-Key": "cdk_live_yourkey"}
BASE = "https://cryptodataapi.com/api/v1/liquidity"

score = httpx.get(f"{BASE}/regime/score", headers=HDR).json()
print(score["composite_score"], score["sentiment"])
# e.g. 41.5 leaning_fragile

agg = score["aggregate"]
print("withdrawing:", agg["pct_withdrawing"], "%")
print("deep books:", agg["pct_deep_book"], "%")

The composite_score runs 0-100 — higher is healthier. It starts from a baseline of 50 and shifts with the regime mix: the share of deep_book coins adds up to +30, while depth_withdrawal subtracts up to -30, oi_price_divergence up to -25, and post_cascade_impaired up to -20.

The sentiment field bands that score into five labels: healthy (≥70), leaning_healthy (≥55), neutral (≥45), leaning_fragile (≥30), and fragile below 30. The aggregate block carries both raw counts and percentages per regime, so you can drill in without a second call.

Why This Regime Is Forward-Only (and What That Means for Backtests)

One caveat that matters before you wire this into a backtest: the liquidity regime is forward-only — it is not historically backfillable. This is a deliberate limitation, not an oversight.

Unlike technical_regime, which we can replay from archived daily klines, the liquidity rules depend on intraday L2 depth deltas: a 10-minute withdrawal window, a 12-hour depth baseline, and depth/spread percentiles computed over the live per-minute sample buffer. None of that exists in any historical data source. There is simply no record of what the Hyperliquid book looked like minute by minute last March.

So the signal accumulates forward from collector start. We archive the per-coin snapshot daily, which means a backtestable history builds going forward — but any period before the collector was deployed is permanently unavailable. Plan windows accordingly: treat this as a live risk overlay first, a backtest input only once you've accrued enough forward history.

Wiring Liquidity Depth Into a Trading Bot

Two reads cover most use cases: pull the market-wide score to gate risk, then pull per-coin regime to size individual positions.

import httpx

HDR = {"X-API-Key": "cdk_live_yourkey"}
BASE = "https://cryptodataapi.com/api/v1/liquidity"

# 1. Gate overall risk on the composite
reg = httpx.get(f"{BASE}/regime", headers=HDR).json()
if reg["sentiment"] in ("leaning_fragile", "fragile"):
    print("Book is thin market-wide — cut size.")

# 2. Avoid coins whose makers are pulling depth right now
for c in reg["coins"]:
    if c["regime"] == "depth_withdrawal" and not c["low_confidence"]:
        print(c["coin"], "withdrawing:",
              c["signals"].get("depth_drop_10min_pct"), "%")

For per-coin depth history, GET /api/v1/liquidity/depth/{coin} returns the rolling buffer (up to 24h, via ?minutes=) so you can chart how a book thinned out ahead of a move. That endpoint is Pro+ only — it returns a 403 with pro_required on free and starter tiers.

This pairs naturally with neighbouring regimes. Cross-reference the Hyperliquid perps data API for the underlying funding and OI, and the liquidation heatmap endpoint to see where a thin book and clustered liq levels overlap — the exact setup that produces post_cascade_impaired reads.

When to Reach for the Liquidity Regime

This regime earns its keep in three concrete situations:

• Pre-trade slippage estimation. Before sending size, read total_depth_25bps_usd for the coin. If your order is a meaningful fraction of it, split the fill or widen your limit. A deep_book classification is your green light to size up.
• Cascade pre-positioning. Combine oi_price_divergence with the liquidation heatmap. Crowded positioning over a thin book over clustered liq levels is the highest-probability cascade setup there is.
• Market-wide risk gating. When sentiment flips to leaning_fragile or fragile, your whole book is exposed to violent moves. Cut leverage across the portfolio, not just one name.

What this regime isn't: a directional signal. A thin book amplifies moves; it doesn't pick which way. Pair it with trend and positioning context — that's why it's one layer in the 14-regime framework. Liquidity tells you how hard the next move will hit; the other regimes tell you which direction to brace for.

Go deeper on the book: this regime is the aggregated fragility score; for the raw per-coin numbers behind it — depth within ±bps, spread and imbalance for order sizing — see the order-book depth API. The same thinness feeds the quant engine's liquidation_risk read.