CayøLargo
← Back to siteAPI ReferencePricingChangelog
v1.0Swagger ↗

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.

GET/v1/vol/surfaceproalpha

Query Parameters

coinstringrequired

Underlying asset. Required.

e.g.BTCETHSOL
fromstringoptional

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

e.g.2026-03-01T00: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.5004320

Response Schema

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

FieldTypeTierDescription
timestampdatetimeproSnapshot time in UTC. Aligned to 10-minute boundary.
coinstringproUnderlying asset (BTC, ETH, SOL, XRP, AVAX, TRX).
atm_iv_dte_7floatproATM implied volatility (pct) for 0-7 DTE bucket. Weekly expiry reference.
atm_iv_dte_30floatproATM IV for 8-30 DTE. The most-watched tenor.
atm_iv_dte_60floatproATM IV for 31-60 DTE. Quarterly reference.
atm_iv_dte_longfloatproATM IV for 60+ DTE. Structural vol level.
term_structure_slopefloatproIs vol in contango or backwardation? The term structure slope.
See detail ↓
term_structure_spreadfloatproAbsolute spread: dte_long IV minus dte_7 IV in vol points.
term_structure_shapestringproCONTANGO (normal upward), BACKWARDATION (inverted, fear), FLAT, HUMPED.
term_slope_change_1hfloatproTerm slope change vs 1 hour ago.
term_slope_change_24hfloatproTerm slope change vs 24 hours ago.
term_slope_percentile_30dfloatproWhere the current slope sits in 30-day history. Below 10 = unusually flat/inverted.
put_skew_dte30floatproPut skew at 30d: FAR_BELOW IV minus ATM IV. The industry standard fear gauge.
put_skew_dte7floatproPut skew at 7d. Front-end fear. Spikes into events.
put_skew_dte60floatproPut skew at 60d. Structural downside pricing.
call_skew_dte30floatproCall skew at 30d: FAR_ABOVE IV minus ATM IV. Upside demand.
call_skew_dte7floatproCall skew at 7d.
call_skew_dte60floatproCall skew at 60d.
skew_ratio_dte30floatproPut/call skew ratio at 30d. Above 1 = fear dominant. Below 1 = greed dominant.
smile_width_dte30floatproSmile convexity at 30d: (FAR_BELOW + FAR_ABOVE) - 2*ATM. Higher = more tail premium.
put_skew_change_24hfloatproPut skew change vs 24 hours ago.
skew_percentile_30dfloatproWhere put skew sits in 30-day history.
skew_momentum_directionstringproSTEEPENING (fear increasing), FLATTENING (fear decreasing), STABLE.
surface_avg_ivfloatproLiquidity-weighted average IV across the entire surface.
surface_median_ivfloatproMedian IV across all cohorts. Robust to outliers.
surface_iv_dispersionfloatproStandard deviation of IV across cohorts. High dispersion = fragmented surface.
surface_iv_rangefloatproMax minus min IV on the surface.
surface_liquidity_scorefloatproAverage liquidity score across the surface (0-100).
active_cohort_countintegerproNumber of cohorts (out of 28) with valid data.
surface_avg_divergence_pctfloatproMean divergence between market and theoretical prices across all cohorts.
surface_max_divergence_pctfloatalphaWorst divergence on the surface. Red flag if high.
surface_median_divergence_pctfloatalphaMedian divergence. Robust quality measure.
high_stress_cohort_countintegeralphaCohorts with HIGH_STRESS conditions. Above 5 = surface-wide execution concerns.
moderate_stress_cohort_countintegeralphaCohorts with MODERATE_STRESS.
normal_conditions_cohort_countintegeralphaCohorts with NORMAL_CONDITIONS.
institutional_grade_cohort_countintegeralphaCohorts at INSTITUTIONAL_GRADE quality.
professional_grade_cohort_countintegeralphaCohorts at PROFESSIONAL_GRADE.
research_grade_cohort_countintegeralphaCohorts at RESEARCH_GRADE.
monitor_only_cohort_countintegeralphaCohorts at MONITOR_ONLY (untradeable).
extreme_divergence_cohort_countintegeralphaCohorts with EXTREME_DIVERGENCE.
high_divergence_cohort_countintegeralphaCohorts with HIGH_DIVERGENCE.
aligned_cohort_countintegeralphaCohorts with ALIGNED (divergence < 2 pct).
surface_quality_tierstringproINSTITUTIONAL_GRADE, PROFESSIONAL_GRADE, RESEARCH_GRADE, or MONITOR_ONLY.
surface_execution_recommendationstringproAGGRESSIVE (tight surface, low stress), STANDARD, CAUTIOUS, AVOID.
surface_avg_execution_difficultyfloatalphaMean execution difficulty score (0-100) across the surface.
surface_max_execution_difficultyfloatalphaWorst execution difficulty on the surface.
realized_vol_7dfloatpro7-day annualized realized volatility from spot returns.
realized_vol_30dfloatpro30-day annualized RV. The standard benchmark for VRP calculation.
realized_vol_90dfloatpro90-day annualized RV. Long-term reference.
rv_change_7dfloatproRV change vs 7 days ago. Rising RV = vol expanding.
rv_percentile_30dfloatproWhere RV sits in 30-day history.
vrp_atm_vs_rv7dfloatproVRP: ATM IV (30d) minus RV (7d). Shortest RV window, most reactive.
vrp_atm_vs_rv30dfloatproThe Variance Risk Premium: should you sell vol or buy vol?
See detail ↓
vrp_atm_vs_rv90dfloatproVRP: ATM IV (30d) minus RV (90d). Most stable reference.
vrp_percentile_30dfloatproWhere VRP sits vs 30-day history.
vrp_percentile_90dfloatproWhere VRP sits vs 90-day history.
vrp_regimestringproRICH (positive VRP, sell vol), FAIR (near zero), CHEAP (negative VRP, buy vol).
vrp_zscorefloatproVRP in standard deviations from mean. Beyond +/-2 = extreme.
iv_correlation_btc_7dfloatproIV correlation with BTC (7-day rolling). High = coin IV moves with BTC.
iv_correlation_btc_30dfloatproIV correlation with BTC (30-day rolling).
iv_beta_to_btcfloatproIV beta: regression slope vs BTC IV. Above 1 = amplifies BTC vol moves.
iv_spread_vs_btcfloatproThis coin ATM IV minus BTC ATM IV. The vol premium over BTC.
coin_iv_percentile_7dfloatproSurface avg IV vs 7-day history.
coin_iv_percentile_30dfloatproSurface avg IV vs 30-day history.
coin_iv_percentile_52wfloatproIV Rank (annual). Below 20 = historically low IV.
coin_iv_regimestringproLOW, NORMAL, HIGH, EXTREME based on percentile position.
rv_stress_regimestringproNORMAL, MODERATE_STRESS, HIGH_STRESS, EXTREME_STRESS based on RV change magnitude.
breach_rate_7dfloatproFraction of cycles IV breached RV bands (7d). High breach rate = vol is breaking its range.
breach_rate_30dfloatproBreach rate over 30 days.
upside_breach_rate_7dfloatalphaFraction of upside breaches (7d). IV expanding above RV.
downside_breach_rate_7dfloatalphaFraction of downside breaches (7d). IV collapsing below RV.
breach_direction_biasfloatalphaUpside minus downside breach rate. Positive = IV expanding, negative = compressing.
breach_regimestringproCONTAINED (few breaches), MIXED, PERSISTENT, EXTREME.
vov_7dfloatproAnnualized vol of ATM IV changes (7d). How unstable is IV itself.
vov_30dfloatproVoV over 30 days.
vov_regimestringproSTABLE, ELEVATED, ERRATIC, EXTREME. ERRATIC = vega risk is high.
gamma_carry_pnl_1dfloatpro1-day gamma vs theta carry. Positive = gamma winning (realized moves exceed IV). Negative = theta winning (quiet market).
gamma_carry_pnl_7dfloatpro7-day rolling gamma carry.
gamma_carry_regimestringproGAMMA_WINNING, BALANCED, THETA_WINNING.
iv_responsiveness_7dfloatalphaRatio of IV change to spot change. High = IV reacts quickly (efficient pricing). Low = lagging (mispriced).
iv_responsiveness_regimestringalphaRESPONSIVE, NEUTRAL, LAGGING.
regime_multiplierfloatalphaComposite confidence multiplier for signal weighting. Higher = stronger signal confidence.
percentile_confidencestringalphaRELIABLE, UNCERTAIN, UNRELIABLE. Based on data depth for percentile calculations.
skew_level_divergencestringalphaALIGNED (skew and IV level agree), DIVERGENT, CONTRADICTORY.
skew_level_divergence_scorefloatalphaNumeric divergence score (0-100).
rv_concentration_ratiofloatalphaLargest daily return squared / sum of all returns squared (7d). Above 0.4 = one event dominates RV. The VRP calculation is contaminated.
days_until_shock_rolloutintegeralphaDays until the dominant shock exits the 7d RV window. Countdown to RV normalization.
rv_ex_shockfloatalpha7d RV recalculated excluding the largest return. The clean VRP denominator.
skew_term_slopefloatproIs fear concentrated in the front end or the back end?
See detail ↓
skew_term_shapestringproFRONT_LOADED_FEAR (DTE_7 skew >> DTE_60), NORMAL, BACK_LOADED_FEAR.
skew_elasticity_24hfloatalphaSkew mean-reversion speed (24h). Higher = skew snaps back quickly (elastic). Lower = skew changes persist (sticky).
skew_max_excursion_24hfloatalphaMaximum skew swing over 24 hours. The realized range of skew.
skew_elasticity_regimestringalphaELASTIC (skew mean-reverts fast), MODERATE, STICKY (skew changes persist), QUIET (small moves).
skew_contagion_scorefloatalphaCross-tenor alignment: 0 (no contagion), 60 (partial), 100 (full). When all tenors steepen simultaneously, fear is systemic.
skew_contagion_regimestringalphaNO_CONTAGION, PARTIAL_CONTAGION, FULL_CONTAGION.
front_end_skew_velocitystringalphaDTE_7 velocity regime from cohort_iv_skew. The fastest-moving skew signal.
inversion_duration_cyclesintegeralphaConsecutive 10-min cycles in BACKWARDATION. Longer = more entrenched fear.
inversion_depth_percentilefloatalphaCurrent inversion depth vs 90-day inversion history.
inversion_regimestringalphaNORMAL, SHALLOW_INVERSION, DEEP_INVERSION, EXTREME_INVERSION.
iv_spread_vs_btc_dte7floatalphaIV spread vs BTC at DTE_7. NULL for BTC (benchmark).
iv_spread_vs_btc_dte60floatalphaIV spread vs BTC at DTE_60.
iv_spread_vs_btc_longfloatalphaIV spread vs BTC at DTE_LONG.
vol_spread_term_slopefloatalphaSlope of the IV spread across tenors. How the premium vs BTC changes with maturity.
vol_spread_term_shapestringalphaFRONT_HEAVY (wider at front), BACK_HEAVY, UNIFORM, INVERTED.
iv_spread_vs_btc_percentile_30dfloatalphaSpread percentile vs 30-day history. At extremes = mean-reversion trade.
iv_spread_vs_btc_zscorefloatalphaSpread z-score (90d). Beyond +/-2 = statistically extreme.
iv_spread_regimestringalphaWIDE, NORMAL, TIGHT, COMPRESSED. COMPRESSED = vol convergence trade.
rr_spread_vs_btc_dte7floatalphaRisk reversal spread vs BTC at DTE_7.
rr_spread_vs_btc_dte30floatalphaRisk reversal spread vs BTC at DTE_30.
rr_spread_vs_btc_dte60floatalphaRisk reversal spread vs BTC at DTE_60.
relative_skew_term_slopefloatalphaSlope of skew spread vs BTC across tenors.
relative_skew_regimestringalphaCOIN_BULLISH_VS_BTC (coin skew less fearful), COIN_BEARISH_VS_BTC, NEUTRAL, CONFLICTED.
eth_skew_leading_signalstringalphaETH only: BULLISH_DIVERGENCE, BEARISH_DIVERGENCE, ALIGNED. ETH skew leads BTC by hours.
gamma_efficiencyfloatalphaHow much gamma do you get per unit of theta paid?
See detail ↓
relative_gamma_valuefloatalphaGamma efficiency vs BTC - 1. Positive = cheaper gamma than BTC.
rv_iv_ratio_spreadfloatalphaRV/IV ratio for this coin minus BTC. Positive = coin RV outpaces IV more than BTC.
orderliness_ratiofloatalphaIs the market repricing smoothly or in jumps?
See detail ↓
return_kurtosis_24hfloatalphaExcess kurtosis of 10-min returns (24h). Above 10 = extreme fat tails. Below 3 = thin tails.
repricing_orderliness_regimestringalphaORDERLY (smooth repricing), CHOPPY, EXTREME_JUMPS (gap risk).
spot_vol_beta_downfloatalphaIV change per 1 pct spot selloff. Positive = normal crypto (IV rises on selloff).
spot_vol_beta_upfloatalphaIV change per 1 pct spot rally. Negative = normal (IV drops on rally).
spot_vol_asymmetry_ratiofloatalphaHow much worse is a selloff than a rally for your short vol position?
See detail ↓
breach_sustainability_avg_7dfloatalphaAverage cycles an IV breach persists before mean-reversion (7d). High = trending vol. Low = mean-reverting.
breach_sustainability_regimestringalphaMEAN_REVERTING (sell vol after breach), MODERATE_PERSISTENCE, TRENDING (do not fade breaches).
flow_spot_correlation_downfloatalphaCorrelation of spot return and net call/put flow during selloffs (7d, sign-flipped). Positive = dip buying.
behavioral_regimestringalphaDIP_BUYING (flow buys on drops), CAPITAL_PRESERVING (flow sells on drops), NEUTRAL.
vol_lifecycle_phasestringproCOMPRESSION (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_cyclesintegeralphaHow many 10-min cycles the current phase has persisted. Long COMPRESSION (200+ cycles, ~33h) = coiled spring ready to break.
phase_confidencefloatalphaLifecycle classifier confidence (0-100). Below 50 = phase is ambiguous, do not trade on it.
compression_duration_daysfloatalphaDays in current COMPRESSION phase (NULL if not in COMPRESSION). Above 20 days = historically extended, breakout imminent.

Derived Fields

FieldTypeTiercollapse all
term_structure_slopefloatprocollapse

Is 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

slope=σATMDTE_LONGσATMDTE_7σATMDTE_7\text{slope} = \frac{\sigma_{\text{ATM}}^{\text{DTE\_LONG}} - \sigma_{\text{ATM}}^{\text{DTE\_7}}}{\sigma_{\text{ATM}}^{\text{DTE\_7}}}
RangeTypically -0.3 to +0.5. Negative = backwardation. Above +0.3 = steep contango.
vrp_atm_vs_rv30dfloatprocollapse

The 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)

VRP=σATM30dRV30d\text{VRP} = \sigma_{\text{ATM}}^{\text{30d}} - \text{RV}_{\text{30d}}
RangeTypically -10 to +20 vol points. Positive is normal in crypto (IV overprices). Negative = buy vol.
skew_term_slopefloatprocollapse

Is 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

skew_term_slope=put_skewDTE_60put_skewDTE_7put_skewDTE_30\text{skew\_term\_slope} = \frac{\text{put\_skew}_{\text{DTE\_60}} - \text{put\_skew}_{\text{DTE\_7}}}{\text{put\_skew}_{\text{DTE\_30}}}
RangeTypically -2 to +2. Positive = BACK_LOADED_FEAR. Negative = FRONT_LOADED_FEAR.
gamma_efficiencyfloatalphacollapse

How 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)

gamma_eff=RV7d/σATM30dαdollar-gamma\text{gamma\_eff} = \frac{\text{RV}_{\text{7d}} / \sigma_{\text{ATM}}^{\text{30d}}}{\alpha_{\text{dollar-gamma}}}
orderliness_ratiofloatalphacollapse

Is 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

orderliness=RV1hRV10min\text{orderliness} = \frac{\text{RV}_{\text{1h}}}{\text{RV}_{\text{10min}}}
Range0 to 1. Above 0.8 = ORDERLY. Below 0.3 = EXTREME_JUMPS.
spot_vol_asymmetry_ratiofloatalphacollapse

How 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

asymmetry=βdownβup\text{asymmetry} = \frac{|\beta_{\text{down}}|}{|\beta_{\text{up}}|}
RangeTypically 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.

FieldTypeInputsexpand all
vrp_trade_signalstringclient-sideShould you sell vol or buy vol right now?expand

Should 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.

Inputsvrp_regimevrp_atm_vs_rv30dcoin_iv_regime
term_structure_regime_readstringclient-sideWhat is the term structure telling you about fear vs complacency?expand

What 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.

Inputsterm_structure_shapeterm_structure_slopevol_lifecycle_phase
lifecycle_compression_alertstringclient-sideIs vol about to explode? The compression breakout screen.expand

Is 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.

Inputsvol_lifecycle_phasesurface_avg_ivskew_momentum_direction
carry_regime_assessmentstringclient-sideIs it a good environment for selling premium?expand

Is 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.

Inputsgamma_carry_regimevrp_regimevov_regime
skew_term_divergencestringclient-sideWhere on the curve is the fear concentrated?expand

Where 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.

Inputsput_skew_dte7put_skew_dte30put_skew_dte60skew_term_shape
rv_contamination_screenstringclient-sideIs the VRP signal contaminated by a single event?expand

Is 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.

Inputsrv_concentration_ratiodays_until_shock_rolloutrv_ex_shockvrp_atm_vs_rv30d
cross_asset_vol_tradestringclient-sideRelative value vol trade: this coin vs BTCexpand

Relative 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.

Inputsiv_spread_regimeiv_spread_vs_btc_zscorerelative_skew_regime
asymmetry_premium_seller_checkstringclient-sideWhat is your real P&L skew as a premium seller?expand

What 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.

Inputsspot_vol_asymmetry_ratiobreach_sustainability_regimebehavioral_regime