> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polaris.supply/llms.txt
> Use this file to discover all available pages before exploring further.

# Event envelope

> Understand the standard event envelope shared by every Polaris record.

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](/reference/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.

<CodeGroup>
  ```rust Rust theme={null}
  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());
  ```

  ```python Python theme={null}
  if "collector_timestamp" in event:
      sdk_timestamp = event["collector_timestamp"]
      exchange_timestamp = event["exchange_timestamp"]
  else:
      sdk_timestamp = event["timestamp"]
      exchange_timestamp = event["timestamp"]
  ```

  ```typescript TypeScript theme={null}
  if ("collector_timestamp" in event) {
    const sdkTimestamp = event.collector_timestamp;
    const exchangeTimestamp = event.exchange_timestamp;
  } else {
    const sdkTimestamp = event.timestamp;
    const exchangeTimestamp = event.timestamp;
  }
  ```
</CodeGroup>

## Payload shapes

* Market data pages ([Trades](/schemas/trades), [Intents and RFQs](/schemas/intents-and-rfqs), [Option tickers](/schemas/option-tickers), [OHLCV](/schemas/ohlcv), [Events](/schemas/events)) show the envelope plus their `data` fields.
* Order book pages ([L2 snapshots](/schemas/l2-snapshots), [BBO](/schemas/bbo)) show how book state is represented in the envelope.
* Derived series ([Funding rates](/schemas/funding-rates), [Mark prices](/schemas/mark-prices), [Volume](/schemas/volume), [VWAP](/schemas/vwap), [Volatility](/schemas/volatility), [Depth metrics](/schemas/depth-metrics)) show their point-series payloads.