Volatility

Vol term structure

Returns cohort-level implied volatility options-volatility-landscape across the moneyness x expiry grid. One row per cohort per timestamp (28 cohorts per coin). Contains liquidity-weighted IV (the executable IV, not the simple average), cross-cohort skew metrics (put premium vs ATM, risk reversal, smile curvature), IV momentum with acceleration, percentile context across 4 horizons (7d through 52w), regime classification (LOW/NORMAL/HIGH/EXTREME), skew regime (SMIRK/SYMMETRIC/CALL_HEAVY/FLAT), and data quality indicators. The ATM row across expiration buckets IS the term structure. The cross-moneyness rows at the same expiry IS the smile.

GET/v1/vol/term-structureproalpha

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_7DTE_30

iv_regimestringoptional

Filter: LOW, NORMAL, HIGH, EXTREME.

e.g.HIGHEXTREME

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: FAR_ABOVE through FAR_BELOW. ATM rows across expiry buckets = the term structure.
`expiration_bucket`	`string`	pro	Expiry: DTE_7 (0-7d), DTE_30 (7-30d), DTE_60 (30-60d), DTE_LONG (60d+).
`cohort_name`	`string`	pro	Combined name, e.g. ATM_DTE_7.
`option_count`	`integer`	pro	Total options in cohort.
`options_with_valid_iv`	`integer`	pro	Options with calculable IV (reliability >= 70).
`call_count`	`integer`	pro	Call options.
`put_count`	`integer`	pro	Put options.
`avg_reliability_score`	`float`	pro	Mean reliability from our BS engine (0-100).
`avg_dte`	`float`	pro	Average days to expiry in cohort.
`avg_liquidity_score`	`float`	pro	Average liquidity score (0-100). Filter below 50 for reliable IV.
`total_liquidity_weight`	`float`	alpha	Sum of liquidity weights. Higher = more reliable weighted averages.
`avg_bid_ask_spread_pct`	`float`	pro	Average spread as pct. Execution cost context.
`pct_options_liquid`	`float`	alpha	Pct of options with liquidity_score >= 30.
`avg_iv_pct`	`float`	pro	Simple average IV across cohort.
`median_iv_pct`	`float`	pro	Median IV. Robust to outliers from illiquid options.
`min_iv_pct`	`float`	pro	Lowest IV in cohort.
`max_iv_pct`	`float`	pro	Highest IV in cohort.
`iv_spread_pct`	`float`	alpha	How wide is the IV range within this cohort? See detail ↓
`stddev_iv_pct`	`float`	alpha	Standard deviation of IV within cohort.
`avg_mark_iv_pct`	`float`	pro	Average Deribit mark IV.
`liq_weighted_mark_iv_pct`	`float`	alpha	Liquidity-weighted Deribit mark IV.
`atm_reference_iv_pct`	`float`	pro	ATM cohort IV for the same expiry bucket. Baseline for all skew calculations. NULL if ATM has no data.
`atm_reference_available`	`boolean`	pro	TRUE if ATM reference is populated.
`put_skew_vs_atm_pct`	`float`	pro	How expensive are puts relative to ATM at this cohort? See detail ↓
`call_skew_vs_atm_pct`	`float`	pro	How expensive are calls relative to ATM at this cohort? See detail ↓
`far_put_skew_pct`	`float`	alpha	How much steeper is the deep OTM put wing beyond the near wing? See detail ↓
`far_call_skew_pct`	`float`	alpha	How much steeper is the deep OTM call wing? See detail ↓
`term_skew_pct`	`float`	alpha	Is IV for this cohort higher or lower than the shorter-dated equivalent? See detail ↓
`term_skew_reference_bucket`	`string`	alpha	Which expiry bucket was used for term skew comparison.
`iv_change_1h_pct`	`float`	alpha	IV change vs 1 hour ago (vol points).
`iv_change_6h_pct`	`float`	alpha	IV change vs 6 hours ago.
`iv_change_24h_pct`	`float`	pro	IV change vs 24 hours ago.
`iv_acceleration`	`float`	alpha	Is IV momentum speeding up or slowing down? See detail ↓
`liq_weighted_iv_change_1h_pct`	`float`	alpha	Weighted 1h IV change. More reliable than unweighted.
`liq_weighted_iv_change_24h_pct`	`float`	alpha	Weighted 24h IV change.
`iv_percentile_7d`	`float`	alpha	Where current IV sits vs last 7 days (0-100). 90+ = elevated short-term.
`iv_percentile_30d`	`float`	pro	IV percentile vs last 30 days. 0-100: where current IV sits relative to the last month.
`iv_percentile_90d`	`float`	alpha	IV percentile vs last 90 days. Quarterly context.
`iv_percentile_52w`	`float`	alpha	IV percentile vs last year. This is IV Rank, the industry standard.
`liq_weighted_iv_pct`	`float`	pro	The executable IV: what you actually trade at See detail ↓
`risk_reversal_25d_pct`	`float`	alpha	Directional sentiment: calls vs puts premium See detail ↓
`smile_curvature_pct`	`float`	alpha	Tail risk premium: how expensive are the wings vs ATM? See detail ↓
`iv_momentum_direction`	`string`	pro	Is vol rising, falling, or stable? See detail ↓
`iv_regime`	`string`	pro	Where does current IV sit historically? See detail ↓
`put_skew_regime`	`string`	alpha	How steep is the put wing? See detail ↓
`rr_regime`	`string`	alpha	Risk reversal regime: market directional bias See detail ↓
`smile_shape`	`string`	pro	Overall shape of the volatility smile See detail ↓

Derived Fields

FieldTypeTiercollapse all

▶iv_spread_pctfloatalphacollapse

How wide is the IV range within this cohort?

Max IV minus min IV across all options in the cohort. Wide spread = inconsistent pricing, possibly stale quotes or mixed liquidity. Narrow spread = uniform pricing, reliable IV signal.

Intra-cohort IV range

\text{iv\_spread} = \sigma_{\max} - \sigma_{\min}

RangeTypically 1-15. Above 20 = investigate data quality.

▶put_skew_vs_atm_pctfloatprocollapse

How expensive are puts relative to ATM at this cohort?

This cohort IV minus ATM IV. Only meaningful for BELOW and FAR_BELOW moneyness buckets (NULL for ATM/ABOVE). Positive = puts trade at a premium to ATM. The per-cohort building block of the skew surface.

Put skew vs ATM

\text{put\_skew\_vs\_atm} = \sigma_{\text{this\_cohort}} - \sigma_{\text{ATM}}

RangeTypically 2-20 for NEAR_BELOW. 5-40 for FAR_BELOW.

▶call_skew_vs_atm_pctfloatprocollapse

How expensive are calls relative to ATM at this cohort?

This cohort IV minus ATM IV. Only for ABOVE and FAR_ABOVE (NULL for ATM/BELOW). Positive = calls expensive.

Call skew vs ATM

\text{call\_skew\_vs\_atm} = \sigma_{\text{this\_cohort}} - \sigma_{\text{ATM}}

▶far_put_skew_pctfloatalphacollapse

How much steeper is the deep OTM put wing beyond the near wing?

FAR_BELOW IV minus BELOW IV. Measures the acceleration of skew into the deep tail. High values = crash protection getting disproportionately expensive in the far wing.

Far put wing steepness

\text{far\_put\_skew} = \sigma_{\text{FAR\_BELOW}} - \sigma_{\text{BELOW}}

▶far_call_skew_pctfloatalphacollapse

How much steeper is the deep OTM call wing?

FAR_ABOVE IV minus ABOVE IV. Call-side tail steepness.

Far call wing steepness

\text{far\_call\_skew} = \sigma_{\text{FAR\_ABOVE}} - \sigma_{\text{ABOVE}}

▶term_skew_pctfloatalphacollapse

Is IV for this cohort higher or lower than the shorter-dated equivalent?

This cohort IV minus the shorter-dated same-moneyness cohort IV. Positive = IV backwardation at this moneyness (front-end fear). Negative = contango (normal term premium). Measures per-moneyness term structure, not just ATM.

Term skew (same moneyness, different expiry)

\text{term\_skew} = \sigma_{\text{this\_cohort}} - \sigma_{\text{shorter\_dated\_same\_moneyness}}

▶iv_accelerationfloatalphacollapse

Is IV momentum speeding up or slowing down?

Second derivative of IV: the rate of change of IV momentum. Positive = IV change is accelerating (vol spike building). Negative = IV change is decelerating (spike fading). Zero = steady state. Key for timing: RISING IV + positive acceleration = early in the move. RISING IV + negative acceleration = near the peak.

IV acceleration (2nd derivative)

\text{accel} = \Delta\text{IV}_{t} - \Delta\text{IV}_{t-1}

RangeTypically -5 to +5 vol points. Beyond +/-3 = rapid acceleration/deceleration.

▶liq_weighted_iv_pctfloatprocollapse

The executable IV: what you actually trade at

IV weighted by liquidity at each option. Simple average IV treats a 1-lot option and a 100-lot option equally. Liquidity-weighted IV reflects what you can actually execute. This is the number to use for pricing, not avg_iv_pct.

Liquidity-weighted implied volatility

\sigma_{\text{liq}} = \frac{\sum_i w_i \cdot \sigma_i}{\sum_i w_i}

RangeTypically 30 to 150 for crypto. BTC ATM: 40-80 in normal conditions.

▶risk_reversal_25d_pctfloatalphacollapse

Directional sentiment: calls vs puts premium

ABOVE cohort IV minus BELOW cohort IV. Computed for ATM cohorts as a summary. Negative = bearish (put premium dominates, typical for BTC/ETH). Positive = bullish (call premium, unusual, signals FOMO). The single most watched skew metric in options markets.

Risk reversal (25-delta equivalent)

\text{RR}_{25\delta} = \sigma_{\text{ABOVE}} - \sigma_{\text{BELOW}}

RangeTypically -20 to +10. Below -15 = EXTREME_FEAR.

▶smile_curvature_pctfloatalphacollapse

Tail risk premium: how expensive are the wings vs ATM?

Average of ABOVE and BELOW IV minus ATM IV. Measures how much the market charges for tail protection. High curvature = expensive wings = fear of large moves in either direction. Computed for ATM cohorts.

Smile curvature (butterfly)

\text{curvature} = \frac{\sigma_{\text{ABOVE}} + \sigma_{\text{BELOW}}}{2} - \sigma_{\text{ATM}}

Range0 to 30+. Above 10 = elevated tail hedging.

▶iv_momentum_directionstringprocollapse

Is vol rising, falling, or stable?

Classification based on IV changes. RISING: IV increasing. FALLING: IV decreasing. STABLE: minimal change. Combine with iv_acceleration to distinguish: RISING + positive acceleration = vol spike building. RISING + negative acceleration = spike fading.

RangeRISING, FALLING, STABLE.

▶iv_regimestringprocollapse

Where does current IV sit historically?

Classification based on IV percentile context. LOW (percentile < 20): compressed vol, mean reversion opportunity. NORMAL (20-80): typical conditions. HIGH (80-95): elevated. EXTREME (> 95): crisis-level vol. Strategy implications: sell vol in EXTREME (mean reversion), buy vol in LOW (expansion ahead).

RangeLOW, NORMAL, HIGH, EXTREME.

▶put_skew_regimestringalphacollapse

How steep is the put wing?

STEEP (> 15 pct over ATM): elevated crash fear. NORMAL (5-15 pct): typical skew. FLAT (< 5 pct): complacent market. INVERTED (< 0): puts cheaper than ATM, extremely unusual and signals structural dislocation.

RangeSTEEP, NORMAL, FLAT, INVERTED.

▶rr_regimestringalphacollapse

Risk reversal regime: market directional bias

BULLISH (RR > 5 pct): call premium exceeds put premium. NEUTRAL (-5 to +5 pct): balanced. BEARISH (< -5 pct): put premium dominates. EXTREME_FEAR (< -15 pct): panic-level put demand. EXTREME_FEAR is a contrarian signal after the initial shock.

RangeBULLISH, NEUTRAL, BEARISH, EXTREME_FEAR.

▶smile_shapestringprocollapse

Overall shape of the volatility smile

SMIRK: put-heavy (typical for crypto, crash fear). SYMMETRIC: balanced wings. CALL_HEAVY: unusual bullishness (FOMO). FLAT: low tail premium, complacent.

RangeSMIRK, SYMMETRIC, CALL_HEAVY, FLAT.

Suggested Calculations

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

FieldTypeInputsexpand all

▶term_structure_slopefloatclient-sideIs the market pricing near-term fear or long-term uncertainty?expand

Is the market pricing near-term fear or long-term uncertainty?

Filter to moneyness_bucket = ATM. Subtract DTE_7 avg_iv from DTE_30 avg_iv. Positive = contango (longer-dated IV higher, normal market). Negative = backwardation (short-dated IV higher, the market expects something soon). Crypto spends most of its time in contango. When it flips to backwardation, pay attention.

Inputsavg_iv_pctmoneyness_bucketexpiration_bucket

Term structure slope (vol points)

\text{slope} = \text{avg\_iv}(\text{DTE\_30}) - \text{avg\_iv}(\text{DTE\_7})

RangeTypically -5 to +15. Negative = backwardation (fear).

▶iv_percentile_contextstringclient-sideIs vol cheap or expensive right now? One number tells you.expand

Is vol cheap or expensive right now? One number tells you.

iv_percentile_30d tells you where current IV sits vs the last 30 days. Below 20 = vol is compressed, historically cheap. Above 80 = vol is elevated, historically expensive. This single number is what institutional desks use to decide "buy vol or sell vol." Combined with the term structure slope: compressed vol + contango = classic short vol setup. Elevated vol + backwardation = crisis mode.

Inputsiv_percentile_30d

Range0-100. Below 20 = cheap vol. Above 80 = expensive vol.

▶put_call_count_ratiofloatclient-sideAre there more puts or calls at each part of the surface?expand

Are there more puts or calls at each part of the surface?

call_count / put_count per cohort. In crypto, ATM cohorts typically have roughly equal counts. FAR_BELOW cohorts with many puts = crash protection demand. FAR_ABOVE with many calls = upside speculation. Track this ratio over time: a sudden spike in put count at BELOW/FAR_BELOW without an IV move is smart money hedging quietly.

Inputscall_countput_count

Call/put count ratio

\text{ratio} = \frac{\text{call\_count}}{\text{put\_count}}

Range0 to unbounded. 1.0 = balanced.

▶mark_vs_model_divergencefloatclient-sideDoes our IV agree with Deribit? When it does not, something is mispriced.expand

Does our IV agree with Deribit? When it does not, something is mispriced.

Compare avg_iv_pct (our Black-Scholes engine) with avg_mark_iv_pct (Deribit mark). Small difference = market is efficiently priced. Large divergence = either our model or the exchange model is wrong, which means an opportunity exists. Persistent divergence > 3 vol points in liquid cohorts is worth investigating.

Inputsavg_iv_pctavg_mark_iv_pct

Model vs exchange divergence (vol points)

\text{divergence} = \text{avg\_iv\_pct} - \text{avg\_mark\_iv\_pct}

RangeTypically -2 to +2. Beyond +/-3 = investigate.

Or use the pre-computed endpointalpha

Pre-computed divergence significance classification (ALIGNED through EXTREME_DIVERGENCE) available at Pro tier.

▶expiry_options_densityfloatclient-sideWhere is the options market deepest?expand

Where is the options market deepest?

Compare option_count across the 4 expiry buckets. In crypto, DTE_7 and DTE_30 carry the bulk of activity. DTE_LONG with high option counts = institutional calendar trades. DTE_7 with collapsing option count as expiry approaches = liquidity draining. A beginner tip: always check which tenor has enough options to produce reliable IV before using the number.

Inputsoption_countavg_dteexpiration_bucket

▶atm_term_structure_curvestringclient-sideBuild the ATM term structure curveexpand

Build the ATM term structure curve

Filter to moneyness_bucket = ATM, then plot liq_weighted_iv_pct (Pro) across DTE_7, DTE_30, DTE_60, DTE_LONG. This uses the liquidity-weighted IV rather than the simple average, so it reflects executable levels. Upward slope = contango. Inverted = backwardation. The shape of this curve is the foundation of all term structure trading strategies.

Inputsliq_weighted_iv_pctmoneyness_bucketexpiration_bucket

▶smile_surface_gridstringclient-sideBuild the full vol surface heatmapexpand

Build the full vol surface heatmap

Pivot all cohorts into a 7x4 grid (moneyness rows x expiry columns), fill cells with liq_weighted_iv_pct. This IS the volatility surface. Color-code by IV level. The edges of the grid (FAR_ABOVE/FAR_BELOW x DTE_LONG) will have sparse data. Check option_count before trusting wing IV.

Inputsliq_weighted_iv_pctmoneyness_bucketexpiration_bucket

▶vrp_opportunityfloatclient-sideVariance Risk Premium: is vol overpriced or underpriced?expand

Variance Risk Premium: is vol overpriced or underpriced?

Compare implied IV from this endpoint with realized vol computed from spot returns (/v1/spot/rates). IV > RV = rich (sell vol). IV < RV = cheap (buy vol). The VRP is the structural edge that vol sellers exploit. Requires computing realized vol from spot data separately.

Or use the pre-computed endpointalpha

Pre-computed VRP with regime classification (RICH, FAIR, CHEAP) at /v1/vol/surface (coming soon).

▶cross_coin_iv_spreadfloatclient-sideIV spread between coins: relative valueexpand

IV spread between coins: relative value

Compare ATM liq_weighted_iv_pct for BTC vs ETH at the same expiry bucket. ETH typically trades 5-15 vol points above BTC. Compression = convergence trade. Expansion = divergence. Requires two API calls (one per coin).

Inputsliq_weighted_iv_pct

Or use the pre-computed endpointalpha

Pre-computed cross-asset IV spreads with z-scores and regime at /v1/vol/surface (coming soon).