Event envelope

Every record Polaris returns — whether from a query method or a snapshot file — uses the same standard event envelope.

Structure

An envelope has two core parts:

type: the event kind, such as trade, intent, bar, orderbook, or datapoint.
data: the typed payload for that kind. Each data schema page describes the fields under data for its event type.

Identifier fields carry source and market, with an optional instrument when a normalized market contains multiple exact contracts. For options, market is the normalized underlying such as BTC, while instrument is the venue-native contract such as BTC-29MAR24-50000-C. Every option_ticker event requires a non-empty instrument. The canonical IDs from Catalog are the values you pass to requests.

Timestamps and sequence numbers

Event time follows one of two models depending on the schema version:

Legacy records use a timestamp field.
Schema v2 records replace timestamp with collector and exchange fields:

Field	Type	Meaning
`collector_timestamp`	integer	Complete-message arrival time at the collector, in Unix milliseconds
`collector_sequence`	integer	Stored collector order within one snapshot; values can have gaps
`exchange_timestamp`	integer or null	Venue-provided event time, in Unix milliseconds
`exchange_sequence`	string or null	Exact venue-provided sequence identifier

Use collector_timestamp for historical filters, buckets, and replay timing. Treat exchange_timestamp as provenance: it can be null or regress relative to collector order. Iterate rows in the order returned by the SDK. Each v2 snapshot starts with a metadata record containing data.schema_version: "v2". SDK readers consume this record; it is not returned from event, replay, trade, or order-book methods.

Match the event version

Check for collector_timestamp to tell v2 from legacy, then read the version-specific fields.

use polaris_data::StandardEvent;

match &event {
    StandardEvent::Legacy(row) => println!("legacy venue time: {}", row.timestamp),
    StandardEvent::V2(row) => {
        println!("collector time: {}", row.collector_timestamp);
        println!("exchange time: {:?}", row.exchange_timestamp);
    }
}

// Shared SDK timing uses collector time for v2.
println!("SDK timestamp: {}", event.timestamp());

if "collector_timestamp" in event:
    sdk_timestamp = event["collector_timestamp"]
    exchange_timestamp = event["exchange_timestamp"]
else:
    sdk_timestamp = event["timestamp"]
    exchange_timestamp = event["timestamp"]

if ("collector_timestamp" in event) {
  const sdkTimestamp = event.collector_timestamp;
  const exchangeTimestamp = event.exchange_timestamp;
} else {
  const sdkTimestamp = event.timestamp;
  const exchangeTimestamp = event.timestamp;
}

Payload shapes

Market data pages (Trades, Intents and RFQs, Option tickers, OHLCV, Events) show the envelope plus their data fields.
Order book pages (L2 snapshots, BBO) show how book state is represented in the envelope.
Derived series (Funding rates, Mark prices, Volume, VWAP, Volatility, Depth metrics) show their point-series payloads.

Getting Started

Core Concepts

Structure

Timestamps and sequence numbers

Match the event version

Payload shapes

​Structure

​Timestamps and sequence numbers

​Match the event version

​Payload shapes

Structure

Timestamps and sequence numbers

Match the event version

Payload shapes