Opex Pinning

Family: Flow surveillance

What it computes

Emits OpexPinningTick ticks carrying top_pin_strikes[], dominant_strike off chain + spot.

Available on the live, historical, and replay drives.

Methodology

Gaussian-weighted GEX concentration.

See the methodology overview for the citation index.

Inputs

Chain + spot.

Key outputs

Top_pin_strikes[], dominant_strike. The full field set is in the tick table below.

Output schema (OpexPinningTick)

The field / type / description table below is regenerated from the OpexPinningTick 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
contract	Contract	Resolved underlying contract metadata. Subscribers identify the underlying by (symbol, …) on this field — the wire-level contract id is engine-internal and is not surfaced here.
date	i32	Trading-session date in YYYYMMDD form.
ms_of_day	i32	Milliseconds-of-day at emission time.
expiration	i32	Expiration the projection targets (YYYYMMDD).
dte	i32	Calendar days from date to expiration — gates the emission (only dte ≤ dte_threshold rows surface).
spot	f64	Underlying spot used to compute the Gaussian distance kernel.
sigma	f64	Gaussian distance kernel width, in dollars. Scales with dte and IV per the inline derivation; surfaced so downstream consumers can audit the kernel.
dominant_pin_strike	f64	Strike with the highest pin_score. f64::NAN when no strike carries a finite pin score (no admitted contributions yet).
dominant_pin_strength	f64	dominant_pin_strike's share of the total pin force, in percent: pin_score(dominant) / Σ pin_score × 100. f64::NAN when there are no admitted contributions.
top_pin_strikes	Vec<PinStrikeRow>	Top pin candidates by pin_score, sorted descending. Length is min(top_strikes_emit, number of admitted strikes).

Configuration (OpexPinningParams)

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

Field	Type	Description
contracts	SecurityFilter	Contracts the subscription tracks. Typically a [SecurityFilter::Symbols] entry naming the underlying roots.
rate	Arc<dyn RateService>	Risk-free rate provider, shared with the Greeks / GEX analytics.
calendar	Arc<dyn MarketCalendar>	Market calendar provider, shared with the Greeks / GEX analytics.
annual_dividend	Option<f64>	Annual continuously compounded dividend yield. None (default) treats the underlying as non-dividend-paying.
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.
oi_cache	Arc<OpenInterestCache>	Engine-wide option open-interest cache. Build at Client::connect and clone the resulting Arc into the spec.
spot_cache	SpotPriceCache	Shared underlying-spot cache, populated by the engine from stock NBBO quotes.
contract_multiplier	f64	Contract multiplier. Default 100.0 for US-listed equity options.
dte_threshold	i32	Maximum DTE (calendar days) at which the analytic emits. Default 7 — the canonical OPEX-week window over which dealer-gamma pinning meaningfully dominates spot tape. Set higher to surface pre-OPEX projections.
top_strikes_emit	u32	Number of top-pin candidates to include in [super::tick::OpexPinningTick::top_pin_strikes]. Default 5 — matches the institutional OPEX board's top-of-list shape.
sigma_floor	f64	Floor on the Gaussian distance-kernel width, in dollars. Prevents the kernel collapsing to a delta function on a same-day expiration with a tiny IV reading. Default 0.50.
default_iv	f64	Annualised IV proxy when the analytic cannot solve a live IV for the chain (cold start, sparse mids). Default 0.20 (20% annualised) — institutional roll-up over the S&P realised-vol band.
min_emit_interval_ms	i64	Minimum interval between emissions per (symbol, expiration), in milliseconds. Defaults to 1_000 (one snapshot per second).
conditions	ConditionPolicy	Trade-condition admission policy (gates which quote ticks can feed the IV solve).
venues	ExchangeFilter	Exchange / venue admission policy applied to option quotes.

Example

Python

import kairos_thetadata as kt

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

def on_event(row):
    print(row)

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

Rust

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

use kairos::{Client, OpexPinningRow};

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

let sub = client
    .live()
    .opex_pinning(["SPX"])
    .on_event(|row: &OpexPinningRow| println!("dte={} spot={}", row.dte, row.spot))?;

// ... later, to stop delivery ...
sub.unsubscribe();
# Ok(())
# }