VWAP TWAP deviation

Family: Microstructure

What it computes

Emits VwapTwapDevTick ticks carrying vwap, twap, dev_pct, dev_zscore off trade tape.

Available on the live, historical, and replay drives.

Methodology

Welford weighted recurrence (West 1979) + NaN warmup.

See the methodology overview for the citation index.

Inputs

Trade tape.

Key outputs

Vwap, twap, dev_pct, dev_zscore. The full field set is in the tick table below.

Output schema (VwapTwapDevTick)

The field / type / description table below is regenerated from the VwapTwapDevTick 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. This is a stock analytic, so expiration, right, and strike will always be None on emitted ticks.
date	i32	Trading-session date of the bar boundary (YYYYMMDD).
ms_of_day	i32	Millisecond-of-day at which the snapshot was emitted — equal to bar_start_ms + bar_size_ms for closed bars.
last_price	f64	Most recent admitted trade price observed as of the bar boundary. Carries forward from the prior bar when the current bar saw no print (standard TWAP carry-forward convention).
cumulative_volume	f64	Cumulative share volume from session open through the bar boundary (sum of admitted size values).
vwap	f64	Volume-weighted average price from session open through the bar boundary — Σ(price_i × size_i) / Σ(size_i).
twap	f64	Time-weighted average price from session open through the bar boundary — the simple mean of the per-bar last_price samples across every closed bar in the session. Empty bars carry the prior last-known price forward, so the TWAP is well-defined from the first post-seed bar onward.
vwap_dev_pct	f64	Signed percentage deviation of last_price from vwap — (last_price − vwap) / vwap × 100. Positive readings indicate the latest print printed above VWAP (paying premium); negative readings indicate it printed below (capturing rebate). Standard TCA metric.
vwap_dev_zscore	f64	Standardised deviation of last_price from vwap, expressed in volume-weighted-standard-deviation units — (last_price − vwap) / σ_vwap, where σ_vwap is the running volume-weighted standard deviation of admitted trade prices (Welford online estimator). NaN while warmup == true.
warmup	bool	true until the cumulative trade count crosses the spec's min_samples_for_zscore threshold. While set, the vwap_dev_zscore field carries NaN; the remaining fields (vwap, twap, vwap_dev_pct) stay well-defined from the first admitted trade onward, so the bar cadence is never broken.
bar_start_ms	i32	Bar boundary in millisecond-of-day form. Always an integer multiple of the spec's bar_size_ms.

Configuration (VwapTwapDevParams)

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

Field	Type	Description
contracts	SecurityFilter	Contracts the subscription tracks. Stock contracts only; option / index / rate ticks are rejected at the dispatch gate.
bar_size_ms	i32	Bar-emission cadence in milliseconds. Snapshots emit at integer multiples of bar_size_ms past midnight. Defaults to 1_000 (one-second bars), the standard sub-second TCA cadence for execution-quality dashboards; production deployments may override (e.g. 60_000 for one-minute rollups, 100 for ultra-fine TCA bench drills). The same cadence drives the TWAP sampling interval — each closed bar contributes one TWAP sample of the prevailing last_trade_price, with empty bars carrying the prior last-known price forward (standard TWAP convention).
min_samples_for_zscore	u32	Minimum trade count before vwap_dev_zscore emits a non-NaN value. Below the threshold the bar's warmup flag is true, vwap_dev_zscore emits NaN, and the well- defined VWAP / TWAP / vwap_dev_pct fields continue to publish at the full bar cadence. Defaults to 10 — the canonical TCA warm-up depth Bloomberg / Refinitiv apply before lifting the z-score gate; production deployments may raise it for noisier names or lower it for sub-minute rebalancing windows.
conditions	ConditionPolicy	Trade-condition admission policy.
venues	ExchangeFilter	Exchange / venue admission policy.

Example

Python

import kairos_thetadata as kt

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

def on_event(row):
    print(row)

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

Rust

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

use kairos::{Client, VwapTwapDevRow};

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

let sub = client
    .live()
    .vwap_twap_dev(["QQQ"])
    .on_event(|row: &VwapTwapDevRow| println!("vwap={} dev_pct={}", row.vwap, row.vwap_dev_pct))?;
// ... later ...
sub.unsubscribe();
# Ok(())
# }