Risk Reversal Velocity

Family: Volatility

What it computes

Emits RiskReversalVelocityTick ticks carrying rr25_velocity, direction off chain.

Available on the live, historical, and replay drives.

Methodology

D(RR25)/dt annualized (5.9M sec/yr).

See the methodology overview for the citation index.

Inputs

Chain.

Key outputs

Rr25_velocity, direction. The full field set is in the tick table below.

Output schema (RiskReversalVelocityTick)

The field / type / description table below is regenerated from the RiskReversalVelocityTick Rust source by docs-site/scripts/inject-doc-tables.ts on every npm run docs:build. Do not hand-edit between the sentinels.

Field	Type	Description
root	Arc<str>	Underlying symbol (interned).
expiration	i32	Expiration date (YYYYMMDD).
date	i32	Trading-session date (YYYYMMDD).
ms_of_day	i32	Milliseconds since midnight at emission.
rr25_current	f64	Current 25-delta risk-reversal under the OTC / Derman-Kani sign convention (call_25d_iv - put_25d_iv). Mirrors IvSkewLeg.
rr25_window_start	f64	25-delta risk-reversal at the oldest sample inside the rolling window — the velocity baseline.
velocity_per_minute	f64	Velocity in IV-per-minute: Δrr25 / Δseconds × 60. Sign follows the rr25 convention (positive = call-side skew dominant moving farther from put-skew baseline).
velocity_annualized	f64	Velocity annualized to a 252-day / 6.5-hour calendar year: Δrr25 / Δseconds × 5_896_800. The same trading-session-second convention the volatility / historical_vol analytics use.
direction	&'static str	Direction label ("Steepening" / "Flattening" / "Stable") per the velocity sign + the configurable per-minute threshold.

Configuration (RiskReversalVelocityParams)

Regenerated from the RiskReversalVelocityParams Rust source — see the note above.

Field	Type	Description
contracts	SecurityFilter	Contracts the subscription tracks.
rate	Arc<dyn RateService>	Risk-free rate provider — same Black-Scholes solver wiring as IvSkewParams.
annual_dividend	Option<f64>	Optional continuous dividend yield. None falls back to zero.
dividend_cache	`std::sync::Arc<crate::reference_data::dividend_yield::
DividendYieldCache>`	Engine-wired per-symbol dividend-yield cache. Seated at subscribe time by DefaultSpec via wire_dividend_yield. Consulted on the dispatch path only when annual_dividend is None — the per-tick lookup resolves the continuous-dividend carry yield q = D / S from the live underlying spot the analytic already holds (O(1), lock-light, non-blocking). An explicit annual_dividend override always wins.
venues	ExchangeFilter	Exchange / venue admission policy.
emit	EmitPolicy	Emission policy. Defaults to [EmitPolicy::OnExchangeInterval] at one chain sweep per second per symbol: the per-expiration velocity ladder is a property of the whole chain snapshot, so the per-second event-time cadence carries the full signal without paying a chain sweep per inbound quote. OnEveryTick sweeps per admitted Quote (the per-leg [Self::emit_interval_ms] gate still caps the downstream per-expiration rate). OnClose stays silent: the velocity is the time-derivative of the rolling window, which a watermark does not advance.
target_delta	f64	Wing-delta magnitude the picker targets. Default [DEFAULT_TARGET_DELTA] (0.25).
delta_tolerance	f64	Acceptance band around target_delta. Default [DEFAULT_DELTA_TOLERANCE] (0.05).
window_ms	i32	Rolling window length in milliseconds. Default [DEFAULT_WINDOW_MS] (60_000 ms / 1 minute).
emit_interval_ms	i32	Minimum interval between consecutive emissions per (symbol, expiration), in milliseconds. Default [DEFAULT_EMIT_INTERVAL_MS] (1_000 ms).
direction_threshold	f64	Per-minute velocity threshold separating "Steepening" / "Flattening" from "Stable". Default [DEFAULT_DIRECTION_THRESHOLD] (0.001 IV / minute).
spot_cache	SpotPriceCache	Shared spot price cache.
calendar	Arc<dyn MarketCalendar>	Market calendar provider.

Example

Python

import kairos_thetadata as kt

client = kt.Client.connect(kt.Credentials.from_env())

def on_event(row):
    print(row)

sub = client.live().risk_reversal_velocity(["SPX"]).on_event(on_event)
sub.wait(timeout_seconds=60.0)

TypeScript

import { Client, Credentials } from "kairos-thetadata";

const client = await Client.connect(Credentials.fromEnv());

await client
  .live()
  .riskReversalVelocity(["SPX"])
  .onEvent((tick) => {
    console.log(tick);
  });

Rust

// Cargo.toml:
//   kairos = "0.1"

use kairos::{Client, RiskReversalVelocityRow};

# fn run() -> Result<(), Box<dyn std::error::Error>> {
let client = Client::connect(("me@example.com", "secret"))?;

let sub = client
    .live()
    .risk_reversal_velocity(["SPX"])
    .on_event(|row: &RiskReversalVelocityRow| println!("rr25_current={}", row.rr25_current))?;
// ... later ...
sub.unsubscribe();
# Ok(())
# }