Skip to main content
These conventions apply everywhere; each endpoint and schema page covers only its exceptions. REST rows and SDK events follow the same standardization pipeline described in the primer.

​
Identifiers

Never guess a source or market. Resolve both from Catalog before querying, and note the exceptions: options use the underlying as market and the contract as instrument; intent sources use market="intents"; PropAMM sources use market="ethereum".

​
Timestamps

SDK envelopes also carry collector_sequence for stored-order tie-breaks, and v2 batches add replay_ordinal, source_file_ordinal, and source_row_ordinal for provenance. Boundary rules differ by surface:
  • REST start and end are inclusive collector times (OHLCV uses inclusive candle-open times; Raw uses inclusive RFC 3339).
  • SDK from_ is inclusive and to is exclusive.
  • Several venues publish events out of order; prioritize SDK stored order over re-sorting by timestamp.

​
Numeric precision

  • REST trade, L2, and OHLCV prices and sizes are JSON numbers.
  • Venue ticker observations (funding, options, perpetuals) and intent amounts keep nullable decimal strings to preserve venue precision. Convert with a decimal type (Decimal, decimal.js, rust_decimal) before arithmetic.
  • Onchain uint256 quote amounts, such as PropAMM amount_in/amount_out, are decimal strings; binary floating point loses precision at that range.
Null means the venue did not publish the value in that observation. It does not mean zero.

​
Sides

Trade rows carry the aggressor side: buy or sell, or null when the venue does not publish one. The optional maker and taker fields are opaque venue-published account identifiers for the passive and aggressing participants; their format and casing depend on the source.

​
The standard envelope

SDK events share one envelope with the typed payload under data: Legacy envelopes use timestamp; v2 envelopes use collector_timestamp (+ nullable exchange_timestamp). In duck-typed languages, check for collector_timestamp on the event to detect v2. REST rows are flat and always use the v2 column names. The fields shared by every standardized REST row:

​
Partial payloads

Venue tickers and funding observations are partial updates: each row contains only the fields that venue published in that message. An omitted field keeps its earlier value in your derived state; it does not clear it, and it does not mean zero. Event and point series (datapoint) observations are the same model.

​
Order book reconstruction

A snapshot replaces both sides of the book; a delta replaces the listed prices, and zero quantity deletes that price. Reconstructed books clear after a coverage gap or reconnect, and deltas at the start of a range are suppressed until a snapshot initializes state. Use l2_snapshots/OrderbookBuilder for complete books and l2_updates for raw snapshots and deltas. See L2 snapshots and updates.

​
Venue-specific fields

Fields the standardization layer does not normalize are retained under extra.<name> in SDK columnar output. Do not depend on them across sources. When a venue-specific field decides the analysis, inspect the original payload with Raw data.

​
Coverage and gaps

Catalog start and end bound the available standardized event range, not a promise that every event type exists at every instant. Real-time collection can also miss intervals:
  • Historical methods (SDK) support allow_gaps=True to return covered rows with a warning instead of failing when coverage is incomplete.
  • Reconstructed book state resets across gaps; never carry a book across one.
Access windows, rate limits, and error handling are shared across surfaces: see Access and rate limits.