OptionTrades

Preview on the public Rust client. The analytic ships in the engine and is reachable today through the Python wheel and the TypeScript / Node addon; a per-analytic builder on the public Rust thin client (kairos::Client) is tracked on the roadmap. The output tick schema below is stable.

What it computes

Per-trade decoration of every admitted option print into a 32-column derived tick covering notional, premium, delta / vega / gamma / theta dollar impact, hedge quantity, edge, market-side classification (bid / ask / mid), price-against-NBBO flags (spread, tied, late, iso, auction, cross, floor, cob, legged, compress, extend, complex), moneyness (itm / otm / atm), the GTH extended-hours flag, and ISO day-of-week.

The analytic does not re-solve Black–Scholes. It composes existing Greeks output via a user-supplied GreekProvider trait, the shared engine spot-price cache, and the per-contract NBBO snapshot.

Methodology

Trade-condition flags map to the OPRA Pillar Options Trade Conditions and UTP §3.14 condition tables. The Lee–Ready side classifier is documented at /methodology/lee-ready.

The standard 100-contract multiplier is the US-listed equity option convention; SPXW / SPX-mini per-symbol overrides are applied by downstream post-processing.

Inputs

• Option TradeTick + the latest QuoteTick (cached in the state cell).
• The underlying UnderlyingSnapshot from the shared engine spot-price cache.
• The latest GreekSnapshot for this contract_id from the GreekProvider.

Production wiring drains the Greeks output stream into InMemoryGreekProvider (bundled). Database-backed or vendor-archive Greek sources implement GreekProvider directly.

Output schema (OptionTradesTick)

OptionTradesTick is a wide per-print struct. Fields group as follows:

Field group	Fields	Notes
Identity	contract_id, contract, date, ms_of_day, exchange, condition	Verbatim from the source TradeTick.
Raw print + NBBO	price, size, bid, ask, spot	NBBO snapshotted at trade time; spot from the shared cache.
Notional / premium	notional, premium	USD; notional = size × spot × multiplier, premium = size × price × multiplier.
Greek-driven derivations	delta_impact, vega_dollar, gamma_shares, gamma_dollar, theta_dollar, dollar_impact, hedge_quantity, edge	NaN when OptionTradesFlags::MISSING_GREEKS is set; dollar_impact additionally NaN on MISSING_SPOT.
Side classification	mktside (MarketSide), bidside, askside, midmkt, buyer, seller	Aggressor inference against pre-trade NBBO.
Condition flags	normal, spread, tied, late, iso, auction, cross, floor, cob, legged, compress, extend, complex, intermarket_sweep, deriv_priced, tied_to_options, burst, qualified_contingent_trade	OPRA Category-a / extension condition booleans.
Moneyness	itm, otm, atm	Resolved against spot and spec.atm_band_pct.
Session metadata	gth, dow	gth true outside SIP RTH; dow is ISO 1-7.
Annotations	flags (OptionTradesFlags)	MISSING_SPOT, MISSING_GREEKS, MISSING_NBBO.

MarketSide is a four-variant enum: AskSide, BidSide, MidMkt, NoQuote. The per-field table below is regenerated from the OptionTradesTick 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 contract metadata. Subscribers identify the security by (symbol, expiration, right, strike) 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 since midnight.
exchange	i32	Exchange code that printed the trade.
condition	i32	Primary OPRA trade-condition code.
price	f64	Trade price.
size	i32	Trade size (contracts).
bid	f64	NBBO bid at trade time. NaN if no NBBO has been seen.
ask	f64	NBBO ask at trade time. NaN if no NBBO has been seen.
spot	f64	Per-symbol spot at trade time. Provider-dependent: defined only when the spot provider is wired; NaN with [OptionTradesFlags::MISSING_SPOT] set otherwise.
notional	f64	size × spot × shares_per_contract. USD. Provider-dependent: defined only when the spot provider is wired.
premium	f64	size × price × shares_per_contract. USD. Print-derived; defined on every emission.
delta_impact	f64	size × delta × shares_per_contract. Per-trade delta exposure in underlying shares. Provider-dependent: defined only when the Greek provider is wired.
vega_dollar	f64	size × vega × shares_per_contract. USD per 1.00 vol unit. Provider-dependent: defined only when the Greek provider is wired.
gamma_shares	f64	size × gamma × shares_per_contract. Per-trade gamma exposure in second-order shares-per-spot-unit terms. Provider-dependent: defined only when the Greek provider is wired.
gamma_dollar	f64	size × gamma × spot × shares_per_contract. USD per 1.00 spot unit (delta change for a $1 move). Provider-dependent: defined only when both the spot and Greek providers are wired.
theta_dollar	f64	size × theta × shares_per_contract. USD/year decay. Provider-dependent: defined only when the Greek provider is wired.
dollar_impact	f64	`size ×
hedge_quantity	f64	size × delta × shares_per_contract. Delta-hedge in underlying shares (signed; same sign convention as delta_impact). Provider-dependent: defined only when the Greek provider is wired.
edge	f64	`
mktside	MarketSide	Aggressor-side classification.
bidside	bool	Convenience: mktside == BidSide.
askside	bool	Convenience: mktside == AskSide.
midmkt	bool	Convenience: mktside == MidMkt.
buyer	bool	true iff the trade was buyer-initiated.
seller	bool	true iff the trade was seller-initiated.
normal	bool	true iff the primary condition is REGULAR (code 0) AND no modifier flag below fires on either the primary or any ext condition. A print with condition = 0 and ext_conditions[0] = 36 (SPREAD) reports normal = false && spread = true so the field stays internally consistent.
spread	bool	true iff the primary or any ext condition is SPREAD / STRADDLE (code 36).
tied	bool	true iff the primary or any ext condition is STPD (code 39).
late	bool	true iff the trade is flagged late (any condition with late_report).
iso	bool	true iff the primary or any ext condition is INTERMARKETSWEEP (code 95).
auction	bool	true iff the print is one of the auction-mechanism OPRA Category-a codes: SLAN (125), SLAI (126), MLAT (131), TLAT (135), MASL (136), TASL (142).
cross	bool	true iff the print is one of the cross-mechanism OPRA Category-a codes: SLCN (127), SCLI (128), MLCT (132), TLCT (139).
floor	bool	true iff the print is one of the floor-mechanism OPRA Category-a codes: SLFT (129), MLFT (133), MFSL (137), TLFT (140), TFSL (143), CBMO (144).
cob	bool	true iff the print is QUALIFIEDCONTINGENTTRADE (code 124).
legged	bool	true iff the print is any of the multi-leg / stock-options OPRA Category-a codes: 130 (MLET), 131 (MLAT), 132 (MLCT), 133 (MLFT), 134 (MESL), 136 (MASL), 137 (MFSL), 138 (TLET), 139 (TLCT), 140 (TLFT), 141 (TESL), 142 (TASL), 143 (TFSL), 144 (CBMO). Overlaps with auction / cross / floor — e.g. an MLAT print has both auction = true and legged = true.
compress	bool	true iff the print is MULTILATERALCOMPRESSIONTRADEOFPROPRIETARYDATAPRODUCTS (code 147).
extend	bool	true iff the print is POSTFULL (code 90) or EXTENDEDHOURSTRADE (code 148).
complex	bool	true iff the print is multi-leg / spread / tied / cob / legged — composite "complex order" indicator.
intermarket_sweep	bool	true iff the print is INTERMARKETSWEEP (95) — alias for iso, kept for stock-tape glossary parity.
deriv_priced	bool	true iff the print is DERIVATIVE (96).
tied_to_options	bool	true iff the print is CONTINGENTTRADEFORMERLYSTOCKOPTION (code 105).
burst	bool	true iff the print is BURSTBASKET (code 25).
qualified_contingent_trade	bool	true iff the print is QUALIFIEDCONTINGENTTRADE (code 124) — alias for cob, kept for stock-tape glossary parity.
itm	bool	true iff this option is in the money at trade-time spot.
otm	bool	true iff this option is out of the money at trade-time spot.
atm	bool	true iff this option is at the money at trade-time spot (within a default 1 % band of spot).
gth	bool	true iff the trade printed outside the SIP RTH window ([34_200_000, 57_600_000) ms).
dow	i32	Day of week in ISO form (1 = Monday … 7 = Sunday).
flags	OptionTradesFlags	Engine-side annotations on this emission.

Configuration (OptionTradesRequest)

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

Field	Type	Description
contracts	SecurityFilter	Contracts the subscription tracks. Typically a [SecurityFilter::Symbols] entry naming the underlying roots — the engine expands the symbol set into the per-contract option universe via the chain-enumeration path.
conditions	ConditionPolicy	Trade-condition admission policy. Defaults to [ConditionPolicy::OpraRegular].
venues	ExchangeFilter	Exchange / venue admission policy. Defaults to [ExchangeFilter::Any] — the SIP-consolidated tape.
reference_quote_label	QuoteLabel	Quote-cycle position cached as the pre-trade NBBO reference. Defaults to [QuoteLabel::PreTrade] per Lee & Ready (1991) §II.B.
spot_cache	SpotPriceCache	Shared per-symbol underlying-spot cache. Seeded by this analytic from the underlying NBBO it consumes; also shareable with a co-resident Greeks subscription (same cache, same writer).
greeks	Arc<InMemoryGreekProvider>	Per-contract Greek snapshot source. When [Self::auto_greeks] is true the analytic feeds this provider internally from the option NBBO; a client publish lands in the same provider and wins by last-write in tick order. Held as the concrete [InMemoryGreekProvider] — not Arc<dyn GreekProvider> — so the analytic can reach the inherent consumer-thread write method for the internal auto-feed. The write method stays off the public sealed [GreekProvider] trait, so SDK consumers holding the read-only trait handle still cannot reach the write path; all external mutation routes through Client. Production wiring registers this same Arc via Client so the auto-feed, the client publish, and every read share one instance.
auto_greeks	bool	Compute the per-contract Greeks internally from the option NBBO mid + the seeded spot so the risk-impact columns populate out of the box. true by default. Set to false for a pure bring-your-own-model deployment that feeds [Self::greeks] exclusively through Client.
rate	Arc<dyn RateService>	Risk-free rate provider used by the internal Greek solve. Defaults to [FixedRateService] at 5.33 %.
calendar	Arc<dyn MarketCalendar>	Market calendar provider used by the internal Greek solve to resolve the per-symbol, per-expiration option cutoff that bounds the Black-Scholes time-to-expiration. Defaults to [RegularSessionCalendar].
annual_dividend	Option<f64>	Annual continuously compounded dividend yield. None (default) resolves the per-symbol carry yield q = D / S from [Self::dividend_cache] against the live spot; an explicit value always wins.
dividend_cache	Arc<DividendYieldCache>	Engine-wired per-symbol dividend-yield cache. Seated at subscribe time by DefaultSpec via wire_dividend_yield. Consulted by the internal Greek solve only when [Self::annual_dividend] is None.
atm_band_pct	f64	Half-width of the at-the-money band as a fraction of spot. 0.01 = ±1 % (institutional default); 0.005 = ±0.5 % (tight); 0.02 = ±2 % (loose). A trade prints atm = true when `

Operational characteristics

• Per-tick latency. O(1) — every input is a state-cell read; the output is a single struct emission.
• Allocation discipline. State cell caches Arc<str> for the underlying symbol; emissions clone the Arc, no hot-path heap allocations.
• Replay parity. Deterministic given identical input tick order and identical GreekProvider contents.

Example

Preview. This analytic ships in the engine and is reachable today through the Python wheel and the TypeScript / Node addon. A per-analytic builder on the public Rust thin client (kairos::Client) is tracked on the roadmap — bare-string symbol filters passed to the analytic accessor will match the other analytics already exposed there. The output tick rows are stable and documented above.