Sequence Gap
A sequence gap is a missing number or range in an ordered market data stream, indicating that one or more events were not received and the local state may be incomplete.
A sequence gap occurs when a data consumer expects the next message in a sequence but receives a later one instead.
For example, if an order book feed delivers updates with sequence numbers 1001, 1002, and then 1005, the missing sequence numbers 1003 and 1004 represent a sequence gap. This means the local consumer cannot know whether any order book changes, trades, quotes, or other events occurred in the missing range.
Sequence gaps are especially important in order book processing because incremental order book updates depend on every prior update being applied in order. If even one update is missing, the reconstructed local book may no longer match the exchange's true state.
Why Do Sequence Gaps Matter?
Sequence gaps matter because they signal that a locally reconstructed market data state may be invalid.
For order book data, a gap can cause incorrect bid or ask levels, stale liquidity, wrong spreads, locked quotes, crossed quotes, or inaccurate backtesting results. For trade and quote streams, a sequence gap can indicate missing events that affect volume calculations, tick-level analysis, or event replay.
Detecting sequence gaps allows systems to stop applying unreliable incremental updates and request a fresh current order book snapshot, seed snapshot, or replayable data segment. Without this check, applications may continue operating on corrupted state without realizing it.
How Is a Sequence Gap Detected?
A sequence gap is usually detected by comparing the expected next sequence number with the sequence number of the next received event.
If the feed is expected to increment by one and the consumer has processed sequence number 2500, the next valid update should be 2501. If the next received update is 2504, the consumer has detected a gap covering 2501 through 2503.
Some exchanges use native sequence numbers, while normalized data products may expose exchange-native sequence IDs or canonical replay order fields. The exact detection logic depends on the venue and feed type, but the principle is the same: every ordered event must connect cleanly to the next event.
What Should You Do After a Sequence Gap?
After detecting a sequence gap, a system should generally treat the current local state as unreliable until it can be repaired.
For an order book, the typical recovery process is to discard or pause the local book, fetch a current order book snapshot or seed snapshot, and then resume applying incremental updates from a sequence point that is known to be continuous. In historical workflows, a replay sequence or canonical replay order may be used to rebuild the book deterministically.
The correct recovery process depends on the exchange feed, the data product, and whether the gap occurred in real-time streaming, historical flat files, or a replay pipeline.
Real-World Example
A trading system subscribes to an exchange order book feed and receives incremental updates for BTC/USD.
The system processes update sequence 880010, then 880011, then receives 880015. Because updates 880012, 880013, and 880014 are missing, the system detects a sequence gap. It stops using the local book for trading decisions, requests a new order book snapshot, and waits until the snapshot and following incremental updates can be aligned.
By doing this, the system avoids making decisions based on an order book that may be missing important liquidity changes.
Sequence Gap and CoinAPI Market Data API
CoinAPI Market Data API helps developers work with exchange market data across trades, quotes, order books, and historical datasets. When consuming order book or replay-style market data, sequence continuity is a key part of verifying that local state can be trusted.
Sequence gap handling is especially relevant when working with incremental order book updates, exchange-native sequence numbers, LIMITBOOK_FULL data, quote streams, and historical replay workflows. By monitoring sequence continuity and resetting state when needed, developers can build more reliable market data pipelines, backtests, and trading applications.