Institutional Flow Score

Family: Flow surveillance

What it computes

Emits InstitutionalFlowScoreTick ticks carrying score 0-100, classification off trade + NBBO + OI.

Available on the live, historical, and replay drives.

Methodology

6-component composite (premium / spread / aggressor / OI / venue / DTE).

See the methodology overview for the citation index.

Inputs

Trade + NBBO + OI.

Key outputs

Score 0-100, classification. The full field set is in the tick table below.

Output schema (InstitutionalFlowScoreTick)

The field / type / description table below is regenerated from the InstitutionalFlowScoreTick 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 of the print.
trade_size	i32	Trade size (contracts).
trade_price	f64	Trade price.
premium_usd	f64	Premium in USD — trade_size × trade_price × 100. Surfaced on the tick so downstream subscribers can audit the premium-tier bucket without re-deriving the multiplier convention.
score	i32	Composite score in [0, 100].
classification	SmartMoneyClassification	Classification band the score lands in.
premium_tier_pts	i32	Premium-tier contribution to the score (0, 10, 20, 30, or 40).
spread_pts	i32	Spread-tightness contribution (0 or 15).
aggressor_pts	i32	Aggressor-side contribution (0, 8, or 15).
oi_pts	i32	Size-vs-OI contribution (0, 3, 6, or 10).
venue_pts	i32	Multi-venue route contribution (0 or 10).
dte_pts	i32	DTE-bucket contribution (0 or 10).

Configuration (InstitutionalFlowScoreParams)

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

Field	Type	Description
contracts	SecurityFilter	Contracts the subscription tracks. Options-only — stock / index / rate ticks are rejected at the dispatch gate.
conditions	ConditionPolicy	Trade-condition admission policy. Defaults to [ConditionPolicy::OpraRegular].
venues	ExchangeFilter	Exchange / venue admission policy. Defaults to [ExchangeFilter::Any] — the SIP-consolidated tape.
multi_venue_window_ms	i32	Rolling window in milliseconds the multi-venue route detector reads when scoring the venue component. Same shape and default as the sweep_detector convention — 100 ms per the SEC Reg NMS / Rule 611 intermarket-sweep horizon.
max_window_trades	usize	Maximum entries kept in the per-contract rolling multi-venue window. Bounds memory on illiquid contracts that trade in bursts. Default 256.

Example

Python

import kairos_thetadata as kt

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

def on_event(row):
    print(row)

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

Rust

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

use kairos::{Client, InstitutionalFlowScoreRow};

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

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