Volatility
Volatility surface
Returns coin-level volatility surface options-volatility-landscape. One row per (coin, timestamp). The single most comprehensive endpoint in the API: 127 columns covering ATM IV across 4 tenors, term structure dynamics, put/call skew per tenor, smile metrics, surface quality assessment, realized volatility (3 windows), variance risk premium (3 windows + regime + percentiles), cross-asset IV correlation, IV regime classification, and 6 layers of proprietary ORIA intelligence: from RV stress and breach detection through skew contagion, cross-asset relative value, dynamic signal processing, to the vol lifecycle state machine that no competitor offers.
/v1/vol/surfaceproalphaQuery Parameters
coinstringrequiredUnderlying asset. Required.
BTCETHSOLfromstringoptionalStart UTC (ISO 8601). Default: latest snapshot.
2026-03-01T00:00:00ZtostringoptionalEnd UTC (ISO 8601). Default: now.
2026-03-09T00:00:00ZlimitintegeroptionalMax rows returned. Default 500, max 5000.
5004320Response 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 (BTC, ETH, SOL, XRP, AVAX, TRX). |
atm_iv_dte_7 | float | pro | ATM implied volatility (pct) for 0-7 DTE bucket. Weekly expiry reference. |
atm_iv_dte_30 | float | pro | ATM IV for 8-30 DTE. The most-watched tenor. |
atm_iv_dte_60 | float | pro | ATM IV for 31-60 DTE. Quarterly reference. |
atm_iv_dte_long | float | pro | ATM IV for 60+ DTE. Structural vol level. |
term_structure_slope | float | pro | Is vol in contango or backwardation? The term structure slope. See detail ↓ |
term_structure_spread | float | pro | Absolute spread: dte_long IV minus dte_7 IV in vol points. |
term_structure_shape | string | pro | CONTANGO (normal upward), BACKWARDATION (inverted, fear), FLAT, HUMPED. |
term_slope_change_1h | float | pro | Term slope change vs 1 hour ago. |
term_slope_change_24h | float | pro | Term slope change vs 24 hours ago. |
term_slope_percentile_30d | float | pro | Where the current slope sits in 30-day history. Below 10 = unusually flat/inverted. |
put_skew_dte30 | float | pro | Put skew at 30d: FAR_BELOW IV minus ATM IV. The industry standard fear gauge. |
put_skew_dte7 | float | pro | Put skew at 7d. Front-end fear. Spikes into events. |
put_skew_dte60 | float | pro | Put skew at 60d. Structural downside pricing. |
call_skew_dte30 | float | pro | Call skew at 30d: FAR_ABOVE IV minus ATM IV. Upside demand. |
call_skew_dte7 | float | pro | Call skew at 7d. |
call_skew_dte60 | float | pro | Call skew at 60d. |
skew_ratio_dte30 | float | pro | Put/call skew ratio at 30d. Above 1 = fear dominant. Below 1 = greed dominant. |
smile_width_dte30 | float | pro | Smile convexity at 30d: (FAR_BELOW + FAR_ABOVE) - 2*ATM. Higher = more tail premium. |
put_skew_change_24h | float | pro | Put skew change vs 24 hours ago. |
skew_percentile_30d | float | pro | Where put skew sits in 30-day history. |
skew_momentum_direction | string | pro | STEEPENING (fear increasing), FLATTENING (fear decreasing), STABLE. |
surface_avg_iv | float | pro | Liquidity-weighted average IV across the entire surface. |
surface_median_iv | float | pro | Median IV across all cohorts. Robust to outliers. |
surface_iv_dispersion | float | pro | Standard deviation of IV across cohorts. High dispersion = fragmented surface. |
surface_iv_range | float | pro | Max minus min IV on the surface. |
surface_liquidity_score | float | pro | Average liquidity score across the surface (0-100). |
active_cohort_count | integer | pro | Number of cohorts (out of 28) with valid data. |
surface_avg_divergence_pct | float | pro | Mean divergence between market and theoretical prices across all cohorts. |
surface_max_divergence_pct | float | alpha | Worst divergence on the surface. Red flag if high. |
surface_median_divergence_pct | float | alpha | Median divergence. Robust quality measure. |
high_stress_cohort_count | integer | alpha | Cohorts with HIGH_STRESS conditions. Above 5 = surface-wide execution concerns. |
moderate_stress_cohort_count | integer | alpha | Cohorts with MODERATE_STRESS. |
normal_conditions_cohort_count | integer | alpha | Cohorts with NORMAL_CONDITIONS. |
institutional_grade_cohort_count | integer | alpha | Cohorts at INSTITUTIONAL_GRADE quality. |
professional_grade_cohort_count | integer | alpha | Cohorts at PROFESSIONAL_GRADE. |
research_grade_cohort_count | integer | alpha | Cohorts at RESEARCH_GRADE. |
monitor_only_cohort_count | integer | alpha | Cohorts at MONITOR_ONLY (untradeable). |
extreme_divergence_cohort_count | integer | alpha | Cohorts with EXTREME_DIVERGENCE. |
high_divergence_cohort_count | integer | alpha | Cohorts with HIGH_DIVERGENCE. |
aligned_cohort_count | integer | alpha | Cohorts with ALIGNED (divergence < 2 pct). |
surface_quality_tier | string | pro | INSTITUTIONAL_GRADE, PROFESSIONAL_GRADE, RESEARCH_GRADE, or MONITOR_ONLY. |
surface_execution_recommendation | string | pro | AGGRESSIVE (tight surface, low stress), STANDARD, CAUTIOUS, AVOID. |
surface_avg_execution_difficulty | float | alpha | Mean execution difficulty score (0-100) across the surface. |
surface_max_execution_difficulty | float | alpha | Worst execution difficulty on the surface. |
realized_vol_7d | float | pro | 7-day annualized realized volatility from spot returns. |
realized_vol_30d | float | pro | 30-day annualized RV. The standard benchmark for VRP calculation. |
realized_vol_90d | float | pro | 90-day annualized RV. Long-term reference. |
rv_change_7d | float | pro | RV change vs 7 days ago. Rising RV = vol expanding. |
rv_percentile_30d | float | pro | Where RV sits in 30-day history. |
vrp_atm_vs_rv7d | float | pro | VRP: ATM IV (30d) minus RV (7d). Shortest RV window, most reactive. |
vrp_atm_vs_rv30d | float | pro | The Variance Risk Premium: should you sell vol or buy vol? See detail ↓ |
vrp_atm_vs_rv90d | float | pro | VRP: ATM IV (30d) minus RV (90d). Most stable reference. |
vrp_percentile_30d | float | pro | Where VRP sits vs 30-day history. |
vrp_percentile_90d | float | pro | Where VRP sits vs 90-day history. |
vrp_regime | string | pro | RICH (positive VRP, sell vol), FAIR (near zero), CHEAP (negative VRP, buy vol). |
vrp_zscore | float | pro | VRP in standard deviations from mean. Beyond +/-2 = extreme. |
iv_correlation_btc_7d | float | pro | IV correlation with BTC (7-day rolling). High = coin IV moves with BTC. |
iv_correlation_btc_30d | float | pro | IV correlation with BTC (30-day rolling). |
iv_beta_to_btc | float | pro | IV beta: regression slope vs BTC IV. Above 1 = amplifies BTC vol moves. |
iv_spread_vs_btc | float | pro | This coin ATM IV minus BTC ATM IV. The vol premium over BTC. |
coin_iv_percentile_7d | float | pro | Surface avg IV vs 7-day history. |
coin_iv_percentile_30d | float | pro | Surface avg IV vs 30-day history. |
coin_iv_percentile_52w | float | pro | IV Rank (annual). Below 20 = historically low IV. |
coin_iv_regime | string | pro | LOW, NORMAL, HIGH, EXTREME based on percentile position. |
rv_stress_regime | string | pro | NORMAL, MODERATE_STRESS, HIGH_STRESS, EXTREME_STRESS based on RV change magnitude. |
breach_rate_7d | float | pro | Fraction of cycles IV breached RV bands (7d). High breach rate = vol is breaking its range. |
breach_rate_30d | float | pro | Breach rate over 30 days. |
upside_breach_rate_7d | float | alpha | Fraction of upside breaches (7d). IV expanding above RV. |
downside_breach_rate_7d | float | alpha | Fraction of downside breaches (7d). IV collapsing below RV. |
breach_direction_bias | float | alpha | Upside minus downside breach rate. Positive = IV expanding, negative = compressing. |
breach_regime | string | pro | CONTAINED (few breaches), MIXED, PERSISTENT, EXTREME. |
vov_7d | float | pro | Annualized vol of ATM IV changes (7d). How unstable is IV itself. |
vov_30d | float | pro | VoV over 30 days. |
vov_regime | string | pro | STABLE, ELEVATED, ERRATIC, EXTREME. ERRATIC = vega risk is high. |
gamma_carry_pnl_1d | float | pro | 1-day gamma vs theta carry. Positive = gamma winning (realized moves exceed IV). Negative = theta winning (quiet market). |
gamma_carry_pnl_7d | float | pro | 7-day rolling gamma carry. |
gamma_carry_regime | string | pro | GAMMA_WINNING, BALANCED, THETA_WINNING. |
iv_responsiveness_7d | float | alpha | Ratio of IV change to spot change. High = IV reacts quickly (efficient pricing). Low = lagging (mispriced). |
iv_responsiveness_regime | string | alpha | RESPONSIVE, NEUTRAL, LAGGING. |
regime_multiplier | float | alpha | Composite confidence multiplier for signal weighting. Higher = stronger signal confidence. |
percentile_confidence | string | alpha | RELIABLE, UNCERTAIN, UNRELIABLE. Based on data depth for percentile calculations. |
skew_level_divergence | string | alpha | ALIGNED (skew and IV level agree), DIVERGENT, CONTRADICTORY. |
skew_level_divergence_score | float | alpha | Numeric divergence score (0-100). |
rv_concentration_ratio | float | alpha | Largest daily return squared / sum of all returns squared (7d). Above 0.4 = one event dominates RV. The VRP calculation is contaminated. |
days_until_shock_rollout | integer | alpha | Days until the dominant shock exits the 7d RV window. Countdown to RV normalization. |
rv_ex_shock | float | alpha | 7d RV recalculated excluding the largest return. The clean VRP denominator. |
skew_term_slope | float | pro | Is fear concentrated in the front end or the back end? See detail ↓ |
skew_term_shape | string | pro | FRONT_LOADED_FEAR (DTE_7 skew >> DTE_60), NORMAL, BACK_LOADED_FEAR. |
skew_elasticity_24h | float | alpha | Skew mean-reversion speed (24h). Higher = skew snaps back quickly (elastic). Lower = skew changes persist (sticky). |
skew_max_excursion_24h | float | alpha | Maximum skew swing over 24 hours. The realized range of skew. |
skew_elasticity_regime | string | alpha | ELASTIC (skew mean-reverts fast), MODERATE, STICKY (skew changes persist), QUIET (small moves). |
skew_contagion_score | float | alpha | Cross-tenor alignment: 0 (no contagion), 60 (partial), 100 (full). When all tenors steepen simultaneously, fear is systemic. |
skew_contagion_regime | string | alpha | NO_CONTAGION, PARTIAL_CONTAGION, FULL_CONTAGION. |
front_end_skew_velocity | string | alpha | DTE_7 velocity regime from cohort_iv_skew. The fastest-moving skew signal. |
inversion_duration_cycles | integer | alpha | Consecutive 10-min cycles in BACKWARDATION. Longer = more entrenched fear. |
inversion_depth_percentile | float | alpha | Current inversion depth vs 90-day inversion history. |
inversion_regime | string | alpha | NORMAL, SHALLOW_INVERSION, DEEP_INVERSION, EXTREME_INVERSION. |
iv_spread_vs_btc_dte7 | float | alpha | IV spread vs BTC at DTE_7. NULL for BTC (benchmark). |
iv_spread_vs_btc_dte60 | float | alpha | IV spread vs BTC at DTE_60. |
iv_spread_vs_btc_long | float | alpha | IV spread vs BTC at DTE_LONG. |
vol_spread_term_slope | float | alpha | Slope of the IV spread across tenors. How the premium vs BTC changes with maturity. |
vol_spread_term_shape | string | alpha | FRONT_HEAVY (wider at front), BACK_HEAVY, UNIFORM, INVERTED. |
iv_spread_vs_btc_percentile_30d | float | alpha | Spread percentile vs 30-day history. At extremes = mean-reversion trade. |
iv_spread_vs_btc_zscore | float | alpha | Spread z-score (90d). Beyond +/-2 = statistically extreme. |
iv_spread_regime | string | alpha | WIDE, NORMAL, TIGHT, COMPRESSED. COMPRESSED = vol convergence trade. |
rr_spread_vs_btc_dte7 | float | alpha | Risk reversal spread vs BTC at DTE_7. |
rr_spread_vs_btc_dte30 | float | alpha | Risk reversal spread vs BTC at DTE_30. |
rr_spread_vs_btc_dte60 | float | alpha | Risk reversal spread vs BTC at DTE_60. |
relative_skew_term_slope | float | alpha | Slope of skew spread vs BTC across tenors. |
relative_skew_regime | string | alpha | COIN_BULLISH_VS_BTC (coin skew less fearful), COIN_BEARISH_VS_BTC, NEUTRAL, CONFLICTED. |
eth_skew_leading_signal | string | alpha | ETH only: BULLISH_DIVERGENCE, BEARISH_DIVERGENCE, ALIGNED. ETH skew leads BTC by hours. |
gamma_efficiency | float | alpha | How much gamma do you get per unit of theta paid? See detail ↓ |
relative_gamma_value | float | alpha | Gamma efficiency vs BTC - 1. Positive = cheaper gamma than BTC. |
rv_iv_ratio_spread | float | alpha | RV/IV ratio for this coin minus BTC. Positive = coin RV outpaces IV more than BTC. |
orderliness_ratio | float | alpha | Is the market repricing smoothly or in jumps? See detail ↓ |
return_kurtosis_24h | float | alpha | Excess kurtosis of 10-min returns (24h). Above 10 = extreme fat tails. Below 3 = thin tails. |
repricing_orderliness_regime | string | alpha | ORDERLY (smooth repricing), CHOPPY, EXTREME_JUMPS (gap risk). |
spot_vol_beta_down | float | alpha | IV change per 1 pct spot selloff. Positive = normal crypto (IV rises on selloff). |
spot_vol_beta_up | float | alpha | IV change per 1 pct spot rally. Negative = normal (IV drops on rally). |
spot_vol_asymmetry_ratio | float | alpha | How much worse is a selloff than a rally for your short vol position? See detail ↓ |
breach_sustainability_avg_7d | float | alpha | Average cycles an IV breach persists before mean-reversion (7d). High = trending vol. Low = mean-reverting. |
breach_sustainability_regime | string | alpha | MEAN_REVERTING (sell vol after breach), MODERATE_PERSISTENCE, TRENDING (do not fade breaches). |
flow_spot_correlation_down | float | alpha | Correlation of spot return and net call/put flow during selloffs (7d, sign-flipped). Positive = dip buying. |
behavioral_regime | string | alpha | DIP_BUYING (flow buys on drops), CAPITAL_PRESERVING (flow sells on drops), NEUTRAL. |
vol_lifecycle_phase | string | pro | COMPRESSION (coiled spring, vol low and falling), EARLY_EXPANSION (first signs of breakout), EXPANSION (vol rising), PEAK (vol extreme), STRESS (crash conditions), NORMALIZATION (returning to base). The single most valuable field in the API. No competitor computes this for crypto. |
phase_duration_cycles | integer | alpha | How many 10-min cycles the current phase has persisted. Long COMPRESSION (200+ cycles, ~33h) = coiled spring ready to break. |
phase_confidence | float | alpha | Lifecycle classifier confidence (0-100). Below 50 = phase is ambiguous, do not trade on it. |
compression_duration_days | float | alpha | Days in current COMPRESSION phase (NULL if not in COMPRESSION). Above 20 days = historically extended, breakout imminent. |
Derived Fields
term_structure_slopefloatprocollapseIs vol in contango or backwardation? The term structure slope.
Ratio of long-dated to short-dated ATM IV minus 1. Positive = contango (normal, long-dated vol higher than short-dated). Negative = backwardation (front-end fear, event pricing). Zero = flat term structure.
Term structure slope
Typically -0.3 to +0.5. Negative = backwardation. Above +0.3 = steep contango.vrp_atm_vs_rv30dfloatprocollapseThe Variance Risk Premium: should you sell vol or buy vol?
ATM implied volatility (30-day tenor) minus 30-day realized volatility. THE number for vol trading. Positive = IV premium exists, vol selling is profitable on average. Negative = IV is cheap relative to realized, consider buying vol. The single most researched signal in volatility literature.
Variance risk premium (ATM vs RV30d)
Typically -10 to +20 vol points. Positive is normal in crypto (IV overprices). Negative = buy vol.skew_term_slopefloatprocollapseIs fear concentrated in the front end or the back end?
Slope of put skew across DTE buckets, normalized by the 30d midpoint. Positive = back-loaded fear (longer-dated skew steeper, structural concern). Negative = front-loaded fear (near-term event hedging, resolves at expiry).
Skew term structure slope
Typically -2 to +2. Positive = BACK_LOADED_FEAR. Negative = FRONT_LOADED_FEAR.gamma_efficiencyfloatalphacollapseHow much gamma do you get per unit of theta paid?
Dollar-gamma normalized efficiency: (RV/IV) scaled by the dollar-gamma alpha from cohort Greeks. Measures how efficiently priced the gamma is. Higher = you are getting more realized movement per dollar of theta paid. Compare across coins: the coin with highest gamma_efficiency offers the best gamma-buying opportunity.
Gamma efficiency (dollar-gamma normalized)
orderliness_ratiofloatalphacollapseIs the market repricing smoothly or in jumps?
Ratio of 1-hour RV to 10-minute RV. Above 0.8 = smooth, orderly repricing (IV adjustments are gradual). Below 0.3 = jump-dominated, gap risk (IV adjustments happen in sudden bursts). This directly affects your hedging P&L: smooth repricing = delta hedging works. Jumps = you get gapped.
Repricing orderliness ratio
0 to 1. Above 0.8 = ORDERLY. Below 0.3 = EXTREME_JUMPS.spot_vol_asymmetry_ratiofloatalphacollapseHow much worse is a selloff than a rally for your short vol position?
Absolute downside beta divided by absolute upside beta. Above 1.5 = IV rises much faster on selloffs than it falls on rallies. This is the P&L asymmetry for premium sellers: your losses on down moves are 1.5-3x larger than your gains on up moves of equal magnitude. The number that separates profitable from unprofitable short vol.
Spot-vol asymmetry ratio
Typically 1.0-4.0 in crypto. Above 2.0 = strongly asymmetric (short vol is dangerous).Suggested Calculations
Not included in the API response. Compute these client-side from the fields above. Formulas and context provided.
vrp_trade_signalstringclient-sideShould you sell vol or buy vol right now?expandShould you sell vol or buy vol right now?
The fundamental vol trade: RICH VRP + HIGH/EXTREME IV regime = sell premium (straddles, iron condors). CHEAP VRP + LOW IV regime = buy vol (strangles, calendars). The combination matters: RICH VRP in LOW IV might just mean RV collapsed, not that IV is actually rich. Cross-reference both.
vrp_regimevrp_atm_vs_rv30dcoin_iv_regimeterm_structure_regime_readstringclient-sideWhat is the term structure telling you about fear vs complacency?expandWhat is the term structure telling you about fear vs complacency?
CONTANGO (positive slope) = normal, market pricing term premium. BACKWARDATION = front-end fear exceeds structural vol, a specific event is causing panic. When term_structure_shape = BACKWARDATION AND vol_lifecycle_phase = COMPRESSION, the market is pricing event risk into the front end while structural vol remains suppressed. This is the setup for the biggest moves.
term_structure_shapeterm_structure_slopevol_lifecycle_phaselifecycle_compression_alertstringclient-sideIs vol about to explode? The compression breakout screen.expandIs vol about to explode? The compression breakout screen.
Filter for vol_lifecycle_phase = COMPRESSION. This is the coiled spring state: vol is low and getting lower, the market is quiet, premiums are cheap. When skew starts STEEPENING during COMPRESSION, someone is buying crash protection before the breakout. This is the highest-conviction pre-positioning signal in vol trading.
vol_lifecycle_phasesurface_avg_ivskew_momentum_directioncarry_regime_assessmentstringclient-sideIs it a good environment for selling premium?expandIs it a good environment for selling premium?
THETA_WINNING + RICH VRP + STABLE VoV = ideal carry environment. GAMMA_WINNING = realized moves are beating theta, do not sell premium. ERRATIC VoV = vega risk is high, spread positions to reduce vega. This triple check prevents the common mistake of selling vol based on VRP alone without checking if the carry is actually working.
gamma_carry_regimevrp_regimevov_regimeskew_term_divergencestringclient-sideWhere on the curve is the fear concentrated?expandWhere on the curve is the fear concentrated?
FRONT_LOADED_FEAR = DTE_7 skew much steeper than DTE_60. Likely event-driven, resolves at expiry. BACK_LOADED_FEAR = longer-dated skew is steeper. Structural concern. Calendar skew trades profit from FRONT_LOADED_FEAR normalization: sell front-end puts, buy back-end puts.
put_skew_dte7put_skew_dte30put_skew_dte60skew_term_shaperv_contamination_screenstringclient-sideIs the VRP signal contaminated by a single event?expandIs the VRP signal contaminated by a single event?
If rv_concentration_ratio > 0.4, one event dominates the RV calculation. The VRP you see is an artifact, not a signal. Use rv_ex_shock as the clean denominator: vrp_clean = atm_iv - rv_ex_shock. Also: days_until_shock_rollout tells you when the contaminated return exits the window and VRP normalizes. Time your entry after rollout.
rv_concentration_ratiodays_until_shock_rolloutrv_ex_shockvrp_atm_vs_rv30dcross_asset_vol_tradestringclient-sideRelative value vol trade: this coin vs BTCexpandRelative value vol trade: this coin vs BTC
COMPRESSED spread + z-score below -2 = coin vol is historically cheap vs BTC. Buy coin vol, sell BTC vol (calendar or straddle spread). WIDE spread + z-score above +2 = coin vol is historically rich. Sell coin vol, buy BTC vol. The relative_skew_regime adds directional tilt: COIN_BULLISH_VS_BTC suggests upside vol is cheap on the coin.
iv_spread_regimeiv_spread_vs_btc_zscorerelative_skew_regimeasymmetry_premium_seller_checkstringclient-sideWhat is your real P&L skew as a premium seller?expandWhat is your real P&L skew as a premium seller?
spot_vol_asymmetry_ratio > 2.0 means IV rises 2x faster on selloffs than it drops on rallies. Your short vol position has negatively skewed P&L. Combine with breach_sustainability_regime: if TRENDING, breaches persist and your short vol bleed extends. If MEAN_REVERTING, pain is temporary. DIP_BUYING behavioral_regime means flow supports recovery, a better environment for short vol.
spot_vol_asymmetry_ratiobreach_sustainability_regimebehavioral_regime