Canonical Replay Order
Canonical replay order is the standardized sequence used to apply historical market data messages so reconstructed state is deterministic and reproducible.
A canonical replay order defines exactly how historical messages should be sorted and applied during replay. This may include ordering by exchange timestamp, receive timestamp, sequence number, message type, or a provider-defined tie-break rule.
In market data systems, multiple messages can share the same timestamp or arrive out of order. Without a canonical replay order, two systems could replay the same data and produce different final states. A canonical order removes ambiguity by specifying a stable sequence for applying snapshots, resets, incremental updates, trades, or quote messages.
For order book data, canonical replay order is especially important because applying updates in the wrong order can create incorrect depth, stale levels, locked quotes, crossed quotes, or unreconstructable book states.
Why It Matters
Canonical replay order matters because it makes historical market data replay reproducible. Traders, researchers, auditors, and infrastructure teams need confidence that replaying the same dataset produces the same result every time.
A clear replay order helps users:
- Reconstruct order books consistently
- Audit market data pipelines
- Compare results across systems
- Detect missing or out-of-order messages
- Support backtesting and compliance workflows
How does canonical replay order affect market data replay?
Canonical replay order determines the exact sequence in which historical messages are applied. If messages are applied in a different order, the reconstructed state may differ even when the underlying data is the same.
For example, an order book replay may need to apply a seed snapshot first, then incremental updates sorted by exchange-native sequence number, and then resets or full-book messages according to provider rules.
Why is canonical replay order important for order books?
Order books are stateful. Each update depends on the previous state. If updates are replayed out of order, a local order book can become inaccurate or impossible to validate.
A canonical replay order helps ensure that book reconstruction follows a deterministic process and that any sequence gap, reset, or snapshot boundary can be handled consistently.
What can go wrong without a canonical replay order?
Without a canonical replay order, replay results can vary between systems. One system may apply messages by timestamp, another by sequence number, and another by file position.
This can lead to mismatched best bid and ask values, inconsistent depth, incorrect backtest results, and difficulty debugging historical market data behavior.
Real-World Example
A trading firm replays historical LIMITBOOK_FULL data to reconstruct a market’s order book at every point in time. Some messages have identical timestamps, while others include exchange-native sequence numbers.
By using a canonical replay order, the firm applies the seed snapshot, subsequent full-book messages, resets, and updates in a stable order. This ensures that every replay run produces the same reconstructed order book state.
Canonical Replay Order and CoinAPI Market Data API
CoinAPI provides market data products that support historical analysis, order book workflows, and deterministic data processing. When users replay market data from CoinAPI, understanding the canonical replay order helps them apply messages consistently and identify when snapshots, sequence numbers, or resets should be used.
This is especially relevant for users working with full limit order book data, replay sequences, exchange-native sequence identifiers, and historical flat files.