IV Cone

Family: Volatility

What it computes

Emits IvConeTick ticks carrying iv_pct_rank per lookback off IV-history cache.

Available on the live and replay drives. The historical drive fails closed with KAIROS_ERR_HISTORICAL_UNWIRED until the relevant cache is hydrated externally.

Methodology

Percentile rank per lookback {252,60,20,5}.

See the methodology overview for the citation index.

Inputs

IV-history cache.

Key outputs

Iv_pct_rank per lookback. The full field set is in the tick table below.

Output schema (IvConeTick)

The field / type / description table below is regenerated from the IvConeTick 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
symbol	Arc<str>	Underlying symbol (interned).
tenor_days	u16	Canonical tenor (calendar days) — 30 / 60 / 90 / 120 / 180 / 360 / 720 per the CANONICAL_TENOR_LADDER.
date	i32	Session date the emission anchors at (YYYYMMDD).
ms_of_day	i64	Milliseconds since midnight ET at emission time. 0 for watermark-driven boot snapshots before any live tick.
iv_current	f64	Current ATM IV observation — the most recent admitted sample for (symbol, tenor) (per-unit decimal, matching [IvHistorySample::atm_iv] convention). NaN when no row has been observed yet.
iv_pct_rank_252	f64	Percentile rank of iv_current within the trailing 252-session ATM-IV distribution, 0.0..=100.0. NaN when fewer than 1 row is observed at the trailing 252-session horizon.
iv_pct_rank_60	f64	Percentile rank within the trailing 60-session distribution.
iv_pct_rank_20	f64	Percentile rank within the trailing 20-session distribution.
iv_pct_rank_5	f64	Percentile rank within the trailing 5-session distribution.
sessions_observed	i32	Count of admitted ATM-IV rows in the LONGEST lookback today (≤ 252). Values strictly less than 252 mean the cone is still warming up — consumers that require a full year of history mask warm-up emissions on this field.

Configuration (IvConeParams)

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

Field	Type	Description
contracts	SecurityFilter	Contracts the subscription tracks. The analytic keys its per-lookback distribution off (symbol, tenor_days); the filter selects the symbols.
iv_history	Arc<IvHistoryCache>	Boot-time hydrated per-(symbol, tenor) IV history. Sealed for the lifetime of the subscription. Must contain at least one row per tracked symbol at the configured tenor for the cone to emit a finite percentile — symbols with no rows surface NaN on every lookback and sessions_observed = 0 (cold-start data-quality signal).
tenor_days	u16	Canonical tenor (calendar days) the cone tracks. Default [DEFAULT_TENOR_DAYS] (30). Bloomberg / Refinitiv / trade-alert.com publish the cone at every tenor on CANONICAL_TENOR_LADDER; each subscription tracks ONE tenor (instantiate multiple subscriptions for the full ladder).

Example

Python

import kairos_thetadata as kt

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

def on_event(row):
    print(row)

sub = client.live().iv_cone(["QQQ"]).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()
  .ivCone(["QQQ"])
  .onEvent((tick) => {
    console.log(tick);
  });

Rust

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

use kairos::{Client, IvConeRow};

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

let sub = client
    .live()
    .iv_cone(["QQQ"])
    .on_event(|row: &IvConeRow| println!("iv_current={} iv_pct_rank_252={}", row.iv_current, row.iv_pct_rank_252))?;
// ... later ...
sub.unsubscribe();
# Ok(())
# }