Liquidity

Cohort liquidity

Returns cohort-level liquidity aggregation with execution intelligence. One row per cohort per timestamp. 28 cohorts per coin (7 moneyness x 4 expiry buckets). Contains usable liquidity (within 1 pct of mid, what you can actually execute), liquidity-weighted spreads (real execution cost at size), HHI concentration (fragility indicator), bid-ask imbalance score (directional pressure before price moves), velocity tracking (early warning when market makers leave), momentum classification, warning flags, and an A-through-F liquidity grade. This is the institutional execution intelligence layer.

GET/v1/liquidity/cohortproalpha

Query Parameters

coinstringrequired

Underlying asset. Required.

e.g.BTCETH

moneyness_bucketstringoptional

Filter: FAR_ABOVE, ABOVE, NEAR_ABOVE, ATM, NEAR_BELOW, BELOW, FAR_BELOW.

e.g.ATM

expiration_bucketstringoptional

Filter: DTE_7, DTE_30, DTE_60, DTE_LONG.

e.g.DTE_7

gradestringoptional

Filter by liquidity grade: A, B, C, D, F.

e.g.AB

min_imbalancefloatoptional

Only cohorts with |imbalance_score| >= this value.

e.g.30

fromstringoptional

Start UTC (ISO 8601). Default: latest snapshot.

e.g.2026-03-08T00:00:00Z

tostringoptional

End UTC (ISO 8601). Default: now.

e.g.2026-03-09T00:00:00Z

limitintegeroptional

Max rows returned. Default 500, max 5000.

e.g.200

Response Schema

Fields marked pro require a Pro subscription. Fields marked alpha require Alpha.

Field	Type	Tier	Description
`timestamp`	`datetime`	pro	Snapshot time in UTC. Aligned to 10-minute boundary.
`coin`	`string`	pro	Underlying asset.
`moneyness_bucket`	`string`	pro	Moneyness classification: FAR_ABOVE through FAR_BELOW.
`expiration_bucket`	`string`	pro	Expiry classification: DTE_7, DTE_30, DTE_60, DTE_LONG.
`cohort_name`	`string`	pro	Combined bucket name, e.g. ATM_DTE_7.
`underlying_price`	`float`	pro	Spot price at snapshot time.
`option_count`	`integer`	pro	Total options in cohort.
`call_count`	`integer`	pro	Call options.
`put_count`	`integer`	pro	Put options.
`options_with_bids`	`integer`	pro	Options with at least one bid.
`options_with_asks`	`integer`	pro	Options with at least one ask.
`options_with_two_sided`	`integer`	pro	Options with BOTH bid AND ask. Actually tradeable.
`pct_two_sided`	`float`	pro	Percentage of cohort that is actually tradeable.
`avg_bid_depth`	`float`	pro	Average bid levels per option.
`avg_ask_depth`	`float`	pro	Average ask levels per option.
`total_bid_value_usd`	`float`	pro	Sum of all bid value across cohort in USD.
`total_ask_value_usd`	`float`	pro	Sum of all ask value across cohort in USD.
`total_liquidity_usd`	`float`	pro	Bid + ask combined. Total theoretical liquidity.
`avg_bid_value_usd`	`float`	alpha	Average bid value per option.
`avg_ask_value_usd`	`float`	alpha	Average ask value per option.
`max_single_option_liquidity_usd`	`float`	alpha	Largest liquidity in a single option. Concentration risk indicator.
`median_spread_pct`	`float`	pro	Median spread across cohort. Robust to outliers.
`min_spread_pct`	`float`	pro	Tightest spread in cohort. Best execution available.
`max_spread_pct`	`float`	pro	Widest spread in cohort. Worst case.
`stddev_spread_pct`	`float`	alpha	Spread consistency. Low = uniform market. High = patchy liquidity.
`top_3_options_pct`	`float`	alpha	Pct of liquidity in top 3 options. Above 70 = concentrated = fragile.
`options_above_50k_usd`	`integer`	alpha	Options with meaningful liquidity (>$50K total book value).
`bid_ask_value_ratio`	`float`	alpha	Total bid / total ask value. Above 1 = bid-heavy. Below 1 = ask-heavy.
`avg_liquidity_score`	`float`	pro	Average liquidity score (0-100) across options in cohort.
`min_liquidity_score`	`float`	pro	Worst option liquidity in cohort.
`max_liquidity_score`	`float`	pro	Best option liquidity in cohort.
`pct_highly_liquid`	`float`	pro	Pct of options with score >= 70.
`pct_illiquid`	`float`	pro	Pct of options with score < 40.
`cohort_volume_24h_usd`	`float`	pro	24h volume in this cohort. Liquidity relative to activity.
`liquidity_to_volume_ratio`	`float`	alpha	Liquidity / volume. Low = active market, high = idle book.
`liquidity_change_1h_usd`	`float`	alpha	Absolute liquidity change vs 1h ago in USD.
`liquidity_change_1h_pct`	`float`	alpha	Liquidity change as pct vs 1h ago.
`liquidity_change_24h_pct`	`float`	alpha	Liquidity change as pct vs 24h ago.
`imbalance_change_1h`	`float`	alpha	Imbalance score change vs 1h ago. Rapid shift = directional pressure building.
`imbalance_change_24h`	`float`	alpha	Imbalance score change vs 24h ago.
`spread_change_1h_pct`	`float`	alpha	Spread change vs 1h ago. Positive = widening (market makers pulling back).
`spread_change_24h_pct`	`float`	alpha	Spread change vs 24h ago.
`velocity_1h_available`	`boolean`	alpha	Is 1h lookback data available for velocity fields?
`velocity_24h_available`	`boolean`	alpha	Is 24h lookback data available?
`liquidity_warning_level`	`integer`	alpha	0 = OK, 1 = WATCH, 2 = WARNING, 3 = CRITICAL.
`warning_flags`	`string[]`	alpha	Array of active warnings: LIQUIDITY_DRAINING, LIQUIDITY_SURGING, IMBALANCE_EXTREME, CONCENTRATION_DANGEROUS, SPREAD_BLOWING_OUT, THIN_MARKET.
`options_with_liquidity_data`	`integer`	alpha	How many options had liquidity data. Data coverage quality indicator.
`pct_with_liquidity_data`	`float`	alpha	Percentage of cohort with liquidity data.
`usable_liquidity_usd`	`float`	alpha	Actionable liquidity: what you can actually execute within 1 pct of mid See detail ↓
`pct_liquidity_usable`	`float`	alpha	What fraction of displayed liquidity is actually executable? See detail ↓
`usable_bid_value_usd`	`float`	alpha	Usable bid-side liquidity (buy protection within 1 pct of mid) See detail ↓
`usable_ask_value_usd`	`float`	alpha	Usable ask-side liquidity (sell protection within 1 pct of mid) See detail ↓
`liquidity_weighted_spread_pct`	`float`	alpha	Real execution cost: what spread would you pay trading size? See detail ↓
`imbalance_score`	`float`	alpha	Directional pressure: is the book leaning buy or sell? See detail ↓
`liquidity_hhi`	`float`	alpha	How fragile is this market? Concentration of liquidity across options. See detail ↓
`cohort_liquidity_grade`	`string`	pro	Overall liquidity quality grade: A through F See detail ↓
`liquidity_momentum`	`string`	alpha	Is liquidity improving or deteriorating? See detail ↓

Derived Fields

FieldTypeTiercollapse all

▶usable_liquidity_usdfloatalphacollapse

Actionable liquidity: what you can actually execute within 1 pct of mid

Total liquidity within 1 pct of mid price across the cohort. This is the number that matters for execution. Total liquidity is theoretical (includes stale quotes deep in the book). Usable liquidity is what you can actually hit without moving the market. No competitor tracks this for crypto options.

Range0 to total_liquidity_usd.

▶pct_liquidity_usablefloatalphacollapse

What fraction of displayed liquidity is actually executable?

usable / total. Low percentage = most of the book is decorative (stale quotes, wide levels). High percentage = tight, actionable market. Below 30 pct = the book looks deep but you cannot execute at displayed prices.

Range0 to 100.

▶usable_bid_value_usdfloatalphacollapse

Usable bid-side liquidity (buy protection within 1 pct of mid)

Bid value within 1 pct of mid. What you can sell into without impact.

▶usable_ask_value_usdfloatalphacollapse

Usable ask-side liquidity (sell protection within 1 pct of mid)

Ask value within 1 pct of mid. What you can buy at without impact.

▶liquidity_weighted_spread_pctfloatalphacollapse

Real execution cost: what spread would you pay trading size?

Spread weighted by liquidity at each price level across the cohort. Simple average spread is meaningless for institutions because it treats a 1-lot quote and a 100-lot quote equally. This weights by actual depth. It is the true cost of execution at size.

Range0 to max_spread_pct.

▶imbalance_scorefloatalphacollapse

Directional pressure: is the book leaning buy or sell?

Normalized to -100 (all asks, maximum sell pressure) through +100 (all bids, maximum buy pressure). Computed as (bid_value - ask_value) / (bid_value + ask_value) * 100. Imbalances above +30 or below -30 often precede price moves in that direction. This leads price: it tells you what is about to happen, not what already happened.

Range-100 to +100. |30|+ = significant directional pressure.

▶liquidity_hhifloatalphacollapse

How fragile is this market? Concentration of liquidity across options.

Herfindahl-Hirschman Index for liquidity distribution. Sum of squared liquidity shares * 10000. Below 1500 = diverse, stable. Above 2500 = concentrated, fragile. A high-HHI cohort with one market maker pulling quotes can lose 50 pct of its liquidity in one cycle.

Range0-10000. Below 1500 = diverse. Above 2500 = concentrated.

▶cohort_liquidity_gradestringprocollapse

Overall liquidity quality grade: A through F

Composite letter grade summarizing execution conditions. A = excellent (tight spreads, deep book, balanced). B = good. C = adequate. D = poor (wide spreads, thin). F = untradeable. Use as a quick filter: only trade in A/B cohorts for reliable execution.

RangeA, B, C, D, F.

▶liquidity_momentumstringalphacollapse

Is liquidity improving or deteriorating?

SURGING: > 30 pct increase in 6h (unusual, investigate). IMPROVING: > 10 pct increase. STABLE: -10 to +10 pct. DETERIORATING: -10 to -25 pct decrease. DRAINING: > 25 pct decrease. DRAINING is the critical early warning: market makers pulling quotes often precedes volatility.

RangeSURGING, IMPROVING, STABLE, DETERIORATING, DRAINING

Suggested Calculations

Not included in the API response. Compute these client-side from the fields above. Formulas and context provided.

FieldTypeInputsexpand all

▶liquidity_heatmapstringclient-sideBuild a liquidity heatmap: where can you actually trade?expand

Build a liquidity heatmap: where can you actually trade?

Pivot avg_liquidity_score into a 7x4 grid (moneyness rows x expiry columns). Color by score: green (70+), yellow (40-70), red (< 40). ATM DTE_7 and DTE_30 are almost always green. FAR_ABOVE DTE_LONG is almost always red. This map defines the tradeable surface. Ignore any Greeks or IV data from red zones.

Inputsavg_liquidity_scoremoneyness_bucketexpiration_bucket

▶spread_cost_comparisonstringclient-sideHow much will it cost to trade in each part of the surface?expand

How much will it cost to trade in each part of the surface?

Compare median_spread_pct across cohorts. ATM options typically have 2-5 pct spreads, wings can be 20-50 pct. If you are considering a strategy that requires trading in FAR_BELOW DTE_LONG (e.g. crash protection), look at the spread first: a 30 pct spread means you lose 30 pct of your premium immediately. The spread is your real entry cost, not the commission.

Inputsmedian_spread_pctmoneyness_bucketexpiration_bucket

▶tradeable_surface_pctfloatclient-sideWhat fraction of options are actually quotable?expand

What fraction of options are actually quotable?

pct_two_sided tells you what percentage of options have both a bid and an ask. Below 50 pct = most options in this cohort have no market. Above 80 pct = active market making. A cohort with 20 options but only 3 with two-sided quotes is effectively untradeable no matter what the avg_liquidity_score says.

Inputspct_two_sidedoption_count

▶execution_surface_mapstringclient-sideGrade map: A through F across the surfaceexpand

Grade map: A through F across the surface

Map the letter grade across the moneyness x expiry grid. A = excellent execution (tight spreads, deep book). F = untradeable. The boundaries between A/B and C/D define your strategy limits. Any strategy requiring C or worse cohorts needs Alpha-tier usable_liquidity data to assess real execution costs.

Inputscohort_liquidity_grademoneyness_bucketexpiration_bucket

▶bid_ask_depth_ratiofloatclient-sideIs the book leaning buy or sell at cohort level?expand

Is the book leaning buy or sell at cohort level?

Simple ratio: total_bid_value_usd / total_ask_value_usd. Above 1.5 = strong bid pressure. Below 0.67 = strong ask pressure. At cohort level this is a structural signal: bid-heavy ATM = market makers want to buy = they are short. Ask-heavy = they are long and want to exit.

Inputstotal_bid_value_usdtotal_ask_value_usd

▶liquidity_draining_alertbooleanclient-sideEarly warning: are market makers leaving?expand

Early warning: are market makers leaving?

Screen for cohorts where liquidity_momentum = DRAINING or warning_flags includes LIQUIDITY_DRAINING. When market makers pull quotes from multiple cohorts simultaneously, volatility is about to spike. Combine with GEX gamma regime: draining liquidity in negative gamma territory is the most dangerous market condition.

Inputsliquidity_momentumliquidity_warning_levelwarning_flags

Or use the pre-computed endpointalpha

Gamma regime at /v1/gex/pinning.

▶usable_vs_total_efficiencystringclient-sideHow much of the displayed liquidity is real?expand

How much of the displayed liquidity is real?

pct_liquidity_usable tells you what fraction of the book is within execution tolerance. Below 30 pct = the book looks deep but most of it is stale or decorative. Above 70 pct = tight, actionable market. This is the metric that separates theoretical liquidity (anyone can display it) from actionable liquidity (what you can actually hit). No competitor computes this.

Inputsusable_liquidity_usdtotal_liquidity_usdpct_liquidity_usable