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-100). 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/optionsproalpha

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_scoreintegeroptional

Only options with liquidity_score >= this value.

e.g.5070

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.
`instrument_name`	`string`	pro	Deribit canonical name, e.g. BTC-28MAR26-80000-C.
`instrument_id`	`integer`	pro	Internal instrument PK. Join with /v1/instruments/options.
`option_type`	`string`	pro	Call or put.
`strike`	`float`	pro	Strike price.
`expiration_timestamp`	`datetime`	pro	Expiration time in UTC.
`days_to_expiry`	`integer`	pro	Calendar days to expiration.
`underlying_price`	`float`	pro	Spot price at snapshot time.
`mark_price`	`float`	pro	Deribit mark price (theoretical fair value).
`mark_iv`	`float`	pro	Deribit mark implied volatility.
`bid_price`	`float`	pro	Best bid price.
`ask_price`	`float`	pro	Best ask price.
`spread_percent`	`float`	pro	Bid-ask spread as percentage of mark price. The primary execution cost metric.
`bid_depth`	`integer`	pro	Number of bid levels in the order book.
`ask_depth`	`integer`	pro	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`	pro	Delta from Deribit. For filtering: \|delta\| near 0.5 = ATM.
`gamma`	`float`	pro	Gamma. High gamma + low liquidity = dangerous to trade.
`theta`	`float`	pro	Theta. Time decay context for liquidity analysis.
`vega`	`float`	pro	Vega. Vol-sensitive instruments need deeper liquidity.
`moneyness_percent`	`float`	pro	Moneyness as percentage. 0 = ATM. Positive = OTM call / ITM put.
`atm_distance_percent`	`float`	pro	Distance from ATM as percentage. Used for moneyness bucketing.
`liquidity_score`	`float`	pro	Composite liquidity quality score (0-100) See detail ↓

Derived Fields

FieldTypeTiercollapse all

▶liquidity_scorefloatprocollapse

Composite liquidity quality score (0-100)

Proprietary composite measuring overall liquidity quality for this instrument. Combines spread width, order book depth, bid/ask value, and market data availability. Use as a quick filter: score above 70 = tradeable with reasonable execution. Score below 30 = illiquid, Greeks unreliable, avoid for live trading. This score is also used as a weighting factor in ORIA cohort aggregations.

Range0-100. Above 70 = good liquidity. Below 30 = illiquid.

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 >= 50 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). In crypto options, typically only 20-30 pct of listed instruments pass this filter. 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.