Events

Use client.events() when you want more than just trade executions. This method returns mixed event types in a single normalized stream, including trades, intents, option tickers, bars, datapoints, and order book events.

Method signature

events(source, market, from_=None, to=None, allow_gaps=False, materialize_orderbooks=True, output="iterator", batch_size=65536)

Parameters

Parameter	Type	Required	Notes
source	str	Yes	Source ID
market	str	Yes	Normalized market or instrument ID
from_	str/datetime/date/int	No	Inclusive start time (ISO 8601, datetime, date, or epoch milliseconds)
to	str/datetime/date/int	No	Exclusive end time (same formats as from_)
allow_gaps	bool	No	Return covered rows and warn instead of failing on coverage gaps
materialize_orderbooks	bool	No	Reconstruct complete books from deltas (default: true)
output	str	No	`iterator`, `batches`, or `dataframe`
batch_size	int	No	Maximum rows per Arrow batch; must be positive

Return value

A single-pass iterator of mixed normalized event records, bounded exact pyarrow.RecordBatch objects, or an eager Pandas DataFrame. Use list(...) only when you intentionally need an eager result. Exact batches preserve source-file order. They expose nullable legacy timestamp plus nullable v2 collector_timestamp, collector_sequence, exchange_timestamp, and exchange_sequence columns. Timestamp columns use timestamp[ms, tz=UTC]. replay_ordinal is the stable position in the decoded replay; source_file_ordinal and source_row_ordinal identify its stored origin. Typed columns include order_id, side, is_snapshot, trade, order-book, and point fields. With materialize_orderbooks=False, event_json retains the complete source event and every unknown payload; with materialization enabled, it contains the resulting complete-book event. Metadata is omitted, but counts as source row 0, so the first v2 event has source_row_ordinal == 1. Neither collector nor exchange timestamps are used to reorder stored events. Batch size never changes ordering or resets order-book state.

Event versions and time

Headerless snapshots use the legacy envelope with timestamp; v2 snapshots use collector_timestamp for SDK time and nullable exchange_timestamp for venue provenance. Prefer collector_timestamp for range filters, replay, bucketing, and derived calculations, and preserve the order returned by the SDK. See Event envelope for the full field set and version-matching examples.

Common event types

The events() method returns mixed event types:

trade: executed transactions
intent: RFQ, quote, executable-intent, or settlement observation
option_ticker: partial venue-published state for one exact option contract; market identifies the underlying and instrument identifies the contract
bar: OHLCV candles
datapoint: market state updates such as funding rates or liquidations
orderbook: a legacy snapshot, or any v2 book event distinguished by data.is_snapshot
orderbook_delta: a legacy changed-level event; zero quantity removes a level

The SDKs materialize orderbooks by default: updates become complete orderbook events after a snapshot has initialized the book. Deltas at the beginning of a range, after a coverage gap, or after a reconnect are suppressed until the next snapshot. Disable materialize_orderbooks/materializeOrderbooks to receive the stored update unchanged. Materialized v2 deltas retain data.is_snapshot: false.

Common datapoint labels

datapoint events carry a market state update under data with a label and value:

funding_rate: perpetual funding rate
open_interest: open contracts or positions
liquidation: liquidation event
index_price: mark or index price update

Example:

{
  "timestamp": 1767225600456,
  "source": "hyperliquid",
  "market": "BTC",
  "symbol": "BTCUSD",
  "type": "datapoint",
  "data": {
    "label": "funding_rate",
    "value": 0.00017
  }
}

Example response

[
    {
        'timestamp': 1704067200000,
        'source': 'hyperliquid',
        'market': 'BTC',
        'symbol': 'BTCUSD',
        'type': 'trade',
        'data': {
            'price': 43250.50,
            'quantity': 0.5,
            'side': 'buy'
        }
    },
    {
        'timestamp': 1704067260000,
        'source': 'hyperliquid',
        'market': 'BTC',
        'symbol': 'BTCUSD',
        'type': 'bar',
        'data': {
            'interval': '1m',
            'open': 43250.00,
            'high': 43260.00,
            'low': 43245.00,
            'close': 43255.00,
            'volume': 12.5
        }
    }
]

Events use the standard event envelope, with each event’s typed payload under data.

Example

from datetime import datetime, timedelta, timezone
from itertools import islice
from polaris_data import PolarisClient

end = datetime.now(timezone.utc)
start = end - timedelta(hours=1)

with PolarisClient() as client:
    events = client.events(
        source="hyperliquid",
        market="SPX",
        from_=start,
        to=end,
    )
    print(list(islice(events, 2)))

How it works

client.events() uses snapshot-first replay: it queries /snapshots for historical data, caches files locally, and derives the mixed event stream. See Snapshots for the full flow.

Trades if you only need executions
Intents and RFQs if you need canonical RFQ, quote, and executable-intent observations
Option tickers if you need option prices, implied volatility, open interest, or Greeks
OHLCV if you only need candles
Quickstart

Foundation

Trade & Price Data

Orderbook & Liquidity

Derivatives Data

Method signature

Parameters

Return value

Event versions and time

Common event types

Common datapoint labels

Example response

Example

How it works

​Method signature

​Parameters

​Return value

​Event versions and time

​Common event types

​Common datapoint labels

​Example response

​Example

​How it works

​Related documentation

Method signature

Parameters

Return value

Event versions and time

Common event types

Common datapoint labels

Example response

Example

How it works

Related documentation