Liquidity

Option liquidity

Returns per-option liquidity metrics from the live order book. Each row is one option instrument at one timestamp, with bid/ask prices, spread percentage, order book depth and aggregate value, weighted average prices, book imbalance ratio, Greeks context, moneyness classification, and a composite liquidity score (0-1). Use to assess execution costs, identify liquid vs illiquid instruments, find order book imbalances that precede price moves, and filter Greeks data for reliable instruments only.

GET/v1/liquidity/optionscoreproalpha

Query Parameters

coinstringrequired

Underlying asset. Required.

e.g.BTCETHSOL

instrument_idintegeroptional

Filter by instrument_id (integer PK).

e.g.4812

option_typestringoptional

Filter: call or put.

e.g.callput

max_spreadfloatoptional

Only options with spread_percent <= this value.

e.g.5.010.0

min_scorefloatoptional

Only options with liquidity_score >= this value. The score is on a 0-1 scale, so thresholds are fractional: 0.5 keeps roughly the most liquid quarter of the BTC book, 0.55 the most liquid tenth. Typed as an integer until 2026-08-10, which made it inoperable (the only expressible values were 0 and 1).

e.g.0.50.55

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. The effective ceiling is your tier row limit, see Tiers and Limits.

e.g.200

Response Schema

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

Field	Type	Tier	Description
`timestamp`	`datetime`	core	Snapshot time in UTC. Aligned to 10-minute boundary.
`coin`	`string`	core	Underlying asset.
`instrument_name`	`string`	core	Deribit canonical name, e.g. BTC-28MAR26-80000-C.
`instrument_id`	`integer`	core	Internal instrument PK. Join with /v1/instruments/options.
`option_type`	`string`	core	Call or put.
`strike`	`float`	core	Strike price.
`expiration_timestamp`	`datetime`	core	Expiration time in UTC.
`days_to_expiry`	`integer`	core	Calendar days to expiration.
`underlying_price`	`float`	core	Spot price at snapshot time.
`mark_price`	`float`	core	Deribit mark price (theoretical fair value).
`mark_iv`	`float`	core	Deribit mark implied volatility.
`bid_price`	`float`	core	Best bid price.
`ask_price`	`float`	core	Best ask price.
`spread_percent`	`float`	core	Bid-ask spread as percentage of mark price. The primary execution cost metric.
`bid_depth`	`integer`	core	Number of bid levels in the order book.
`ask_depth`	`integer`	core	Number of ask levels in the order book.
`total_bid_value`	`float`	alpha	Aggregate value of all bid orders.
`total_ask_value`	`float`	alpha	Aggregate value of all ask orders.
`weighted_avg_bid`	`float`	alpha	Volume-weighted average bid price across all levels.
`weighted_avg_ask`	`float`	alpha	Volume-weighted average ask price across all levels.
`max_bid_size`	`float`	alpha	Largest single bid order size. Potential support level.
`max_ask_size`	`float`	alpha	Largest single ask order size. Potential resistance.
`bid_ask_ratio`	`float`	alpha	Total bid value / total ask value. Above 1 = bid-heavy (buying pressure). Below 1 = ask-heavy (selling pressure).
`delta`	`float`	core	Delta from Deribit. For filtering: \|delta\| near 0.5 = ATM.
`gamma`	`float`	core	Gamma. High gamma + low liquidity = dangerous to trade.
`theta`	`float`	core	Theta. Time decay context for liquidity analysis.
`vega`	`float`	core	Vega. Vol-sensitive instruments need deeper liquidity.
`moneyness_percent`	`float`	core	Moneyness as percentage. 0 = ATM. Positive = OTM call / ITM put.
`atm_distance_percent`	`float`	core	Distance from ATM as percentage. Used for moneyness bucketing.
`liquidity_score`	`float`	pro	Composite liquidity quality score (0-1) See detail ↓

Derived Fields

FieldTypeTiercollapse all

▶liquidity_scorefloatprocollapse

Composite liquidity quality score (0-1)

Proprietary composite measuring overall liquidity quality for this instrument. Combines spread width, order book depth, bid/ask value, and market data availability. CORRECTED 2026-08-10: this documentation previously described a 0-100 scale with thresholds at 70 and 30. The field has been on a 0-1 scale since it began recording in February 2026, so those thresholds excluded the entire book and the published examples returned no rows. Measured on BTC, one cycle: p10 0.25, p25 0.32, median 0.42, p75 0.50, p90 0.56, p99 0.64, and the all-coin maximum since February is 0.84. COMPARE WITHIN A COIN, not across: the ceiling differs by book, with SOL topping out near 0.53 where BTC reaches 0.73 on the same cycle, so an absolute cutoff silently biases toward the liquid majors. This score is also used as a weighting factor in ORIA cohort aggregations, where only the relative values matter, so those aggregations are unaffected by the scale.

Range

0-1. Empirically 0.04 to 0.84. Above the coin's own p90 (BTC ~0.56) = the liquid tail; below its p10 (BTC ~0.25) = thin, treat Greeks with care.

Suggested Calculations

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

FieldTypeInputsexpand all

▶tradeable_filterstringclient-sideWhich options are actually tradeable? Build a quality filter.expand

Which options are actually tradeable? Build a quality filter.

The simplest useful filter: liquidity_score >= 0.45 AND spread_percent < 10 AND bid_depth >= 2 AND ask_depth >= 2. This eliminates illiquid garbage (dead options with no bids, stale quotes, 50 pct spreads). Corrected 2026-08-10: this read liquidity_score >= 50, on a field that runs 0 to 1, so the filter returned nothing at all. At 0.45 roughly 30 pct of the BTC book passes, which matches what this note always claimed. Everything else is noise. Start here before any analysis.

Inputsliquidity_scorespread_percentbid_depthask_depth

▶spread_distributionstringclient-sideHow wide are spreads across the options chain?expand

How wide are spreads across the options chain?

Sort by spread_percent ascending. ATM options typically have 2-5 pct spreads. OTM options can have 20-50 pct spreads. If even ATM options have > 10 pct spreads, the market is thin. Avoid trading or use limit orders only. Compare spread distributions across coins: BTC and ETH are tightest, altcoins are much wider.

Inputsspread_percentinstrument_name

▶depth_asymmetrystringclient-sideIs the order book balanced or one-sided?expand

Is the order book balanced or one-sided?

Compare bid_depth vs ask_depth per instrument. If ask_depth >> bid_depth, market makers are offering to sell but not to buy (they are long and want out). If bid_depth >> ask_depth, they are willing to buy but not sell (they are short and want to cover). Depth asymmetry at an aggregate level hints at dealer positioning before it shows up in price.

Inputsbid_depthask_depth

▶mid_pricefloatclient-sideMidpoint between bid and askexpand

Midpoint between bid and ask

Simple midpoint: (bid + ask) / 2. More reliable than last trade price for illiquid options. Use as the fair value reference when mark price is unavailable or suspect. Compare mid vs mark_price: divergence > 2 pct = stale or mispriced.

Inputsbid_priceask_price

Mid price

\text{mid} = \frac{\text{bid\_price} + \text{ask\_price}}{2}

▶spread_vs_gamma_riskfloatclient-sideIs the spread wide enough to compensate for gamma risk?expand

Is the spread wide enough to compensate for gamma risk?

For market makers: compare spread earned per trade vs gamma risk per dollar move. High gamma + tight spread = dangerous for short gamma positions. High gamma + wide spread = compensated risk. Useful for identifying options where the market-making math does not work.

Inputsspread_percentgamma

▶book_imbalancefloatclient-sideNormalized order book imbalance: directional pressure before priceexpand

Normalized order book imbalance: directional pressure before price

Normalized to -100 (all asks) through +100 (all bids). Imbalances above +30 or below -30 often precede price moves in that direction. This leads price: it tells you what is about to happen.

Inputstotal_bid_valuetotal_ask_value

Normalized imbalance score

\text{imbalance} = \frac{\text{bid\_value} - \text{ask\_value}}{\text{bid\_value} + \text{ask\_value}} \times 100

Range-100 to +100.

Or use the pre-computed endpointalpha

Pre-computed at cohort level at /v1/liquidity/cohort as imbalance_score.

▶cost_to_movefloatclient-sideHow much capital to move the price by 1 tick?expand

How much capital to move the price by 1 tick?

Requires the full order book (bids/asks JSONB arrays, available at Alpha tier). Walk the book to compute how much USD is needed to exhaust levels up to a 1-tick move. Thin cost-to-move = fragile price, easy to manipulate.

Or use the pre-computed endpointalpha

Pre-computed with execution tolerance bands at /v1/liquidity/cohort as usable_liquidity_usd.