Order-Book Depth & Liquidity API: Spread, Imbalance & Slippage Data

Why Your Backtest Lies About Fills

A backtest fills you at the mid price. The live market fills you against whatever liquidity is actually resting in the book. On a thin perp, a market order that looks tiny can walk three levels and cost you 40 bps of slippage — a cost your strategy never modeled.

The fix is to read the order-book depth before you size the order. The liquidity / market-depth API exposes live Hyperliquid order books as structured numbers: how much USD liquidity sits within ±10, 25, 50 and 100 bps of mid, the current spread, and the bid/ask imbalance — per perp, refreshed continuously.

It powers the live order-book depth page and answers one question your agent should ask before every entry: can this book absorb my order without moving against me?

Depth Within ±Bps: The Number That Predicts Slippage

Raw level-by-level books are noisy. The useful abstraction is banded depth — cumulative resting liquidity within a price band of mid. The API gives you four bands per side:

• depth_usd.bid.25bps / depth_usd.ask.25bps — USD you can fill within a quarter-percent of mid. This is your realistic no-slippage size.
• spread_bps — the live bid/ask spread; your minimum round-trip cost.
• total_depth_25bps_usd — combined two-sided liquidity, a clean single-number liquidity score per coin.
• imbalance_10bps — signed bid-vs-ask skew right at the touch (positive = bid-heavy, negative = ask-heavy).
• open_interest_usd — context for how crowded the perp is relative to its book.

A coin with $12M of 25 bps depth absorbs a $50k order invisibly. A meme with $80k absorbs the same order with a visible dent — same notional, opposite execution risk.

How Do I Read the Live Order Book via API?

One call returns the whole liquid universe. /api/v1/liquidity/depth lists each perp with its mid, spread, banded depth and imbalance.

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

{
  "as_of": 1781696830,
  "coins": [
    {
      "coin": "BTC",
      "mid_price": 64825.5,
      "spread_bps": 0.154,
      "depth_usd": { "bid": {"25bps": 4886157.0}, "ask": {"25bps": 6855423.08} },
      "total_depth_25bps_usd": 11741580.08,
      "imbalance_10bps": -0.1677,
      "open_interest_usd": 2078032611.15
    }
  ]
}

Here BTC shows a razor-thin 0.15 bps spread, ~$11.7M of 25 bps depth, and a slightly ask-heavy book (imbalance_10bps −0.17). Deep, liquid, mildly offered.

Per-Coin Depth, History and the Liquidity Heatmap

For one coin, /api/v1/liquidity/depth/{coin} returns its depth history — how liquidity built or evaporated over time, the input to a liquidity heatmap showing where resting depth has persisted. Sticky liquidity at a level is where the market keeps defending or capping.

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

The same data renders visually on the order-book depth page: cumulative bid/ask depth curves, depth-within-bps bars, spread, imbalance and a price×time liquidity heatmap for every perp — with a quant-regime corroboration line that reads book imbalance against the HMM's directional call.

Imbalance as a Directional Tell

imbalance_10bps is the single number that captures "which way is the book leaning right now." It's the ratio of bid to ask depth within ±10 bps of mid:

• Strongly positive (bid-heavy): a wall of resting bids below price — support. Sellers must eat through it to push lower.
• Near zero (balanced): symmetric book; no microstructure edge, price is free to drift on flow.
• Strongly negative (ask-heavy): thin bids, stacked asks — little stands in the way of a drop, and rallies face overhead supply.

Imbalance is a fast, mean-reverting signal — best read as confirmation alongside the regime and funding, not as a standalone trigger.

Raw Depth vs the Liquidity Regime

Two related products, different jobs — know which to call:

• This depth feed (/liquidity/depth): raw, per-coin, real-time book numbers. Use it for order sizing and slippage modeling at execution time.
• The liquidity regime (/liquidity/regime): an aggregated, classified fragility score — is market-wide liquidity thinning toward a flash-crash setup? Use it for risk posture, not order sizing.

And the new quant engine closes the loop: thin books and wide spreads feed its liquidation_risk read, so depth informs not just your fills but the probability of a forced-selling cascade.

How AI Agents Use Order-Book Depth

Wire depth into execution with a few concrete patterns:

• Slippage-aware sizing. Cap order notional at a fraction of depth_usd within your tolerance band so you never sweep the book.
• Liquidity screening. Skip coins below a total_depth_25bps_usd floor — untradeable size is worse than no signal.
• Spread gating. Pause entries when spread_bps blows out; a widening spread is the first sign of a stressed book.

import httpx
book = {c["coin"]: c for c in httpx.get(
    "https://cryptodataapi.com/api/v1/liquidity/depth",
    headers={"X-API-Key": "cdk_live_your_key"}).json()["coins"]}

def max_order_usd(coin, frac=0.1):
    d = book[coin]["depth_usd"]
    return frac * min(d["bid"]["25bps"], d["ask"]["25bps"])

print(max_order_usd("BTC"))  # size the book can absorb quietly

Start on the visual depth page, then wire the endpoint into your execution layer.