Trades

Use client.trades() when you want execution-level records only. Trade events represent executed transactions only. They are normalized so you can compare fills across venues without translating symbol formats or side conventions.

Method signature

trades(source, market, from_=None, to=None, allow_gaps=False, 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
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 normalized trade event dictionaries by default. With output="batches", returns flat PyArrow record batches; with output="dataframe", returns an eager Pandas DataFrame. Python columnar output always includes nullable maker and taker string columns, even when the source rows omit those identifiers.

Example response

[
    {
        'collector_timestamp': 1704067200000,
        'collector_sequence': 1,
        'exchange_timestamp': 1704067199000,
        'exchange_sequence': 'trade-1',
        'source': 'hyperliquid',
        'market': 'BTC',
        'type': 'trade',
        'data': {
            'order_id': 'trade-1',
            'price': 43250.50,
            'quantity': 0.5,
            'side': 'buy',
            'maker': '0xmaker',
            'taker': '0xtaker'
        }
    }
]

Fields

Trade events use the standard event envelope with type: "trade" and the following trade-specific fields under data:

data.price: matched execution price
data.quantity: executed size in base units
data.order_id: v2 venue order or execution ID, as a string or null
data.side: aggressor side; v2 uses buy, sell, or null
data.maker: optional venue-published account or address for the passive participant
data.taker: optional venue-published account or address for the aggressing participant

Older rows without maker or taker continue to decode normally. Treat the values as opaque venue identifiers; their format and casing depend on the source. Legacy iterator rows use timestamp; v2 rows use collector_timestamp for SDK timing and retain nullable exchange_timestamp as venue provenance. Columnar trade output uses the SDK timestamp as timestamp[ms, tz=UTC]; query boundary integers remain epoch milliseconds. See the event envelope for matching examples.

SDK types

Python exports LegacyTradeData, TradeDataV2, LegacyTradeEvent, TradeEventV2, and the TradeEvent union. TypeScript exposes optional maker and taker fields on both legacy and v2 trade data interfaces. Rust exposes typed optional fields on both event versions plus TradeEvent::maker() and TradeEvent::taker() accessors.

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:
    trades = client.trades(
        source="hyperliquid",
        market="SPX",
        from_=start,
        to=end,
    )
    print(list(islice(trades, 2)))

How it works

client.trades() filters trade rows from the standardized stream using snapshot-first replay. See Snapshots for the full flow.

Events if you need more than just executions
OHLCV if you want interval-based aggregations derived from trade flow
Snapshots for venue-native raw snapshot files
Quickstart

Foundation

Trade & Price Data

Orderbook & Liquidity

Derivatives Data

Method signature

Parameters

Return value

Example response

Fields

SDK types

Example

How it works

​Method signature

​Parameters

​Return value

​Example response

​Fields

​SDK types

​Example

​How it works

​Related documentation

Method signature

Parameters

Return value

Example response

Fields

SDK types

Example

How it works

Related documentation