sequence_numberPer snapshot- Event-drivenCapture
- Gap detectionUse
- Replay fidelityGoal
A backtest is only as trustworthy as the series underneath it. If events went missing and you never noticed, your replay is fiction dressed as history. Every snapshot carries a sequence_number for exactly this reason: it lets you prove the series is complete and ordered before you build anything on top of it.
Capture here is event-driven, a snapshot is produced when Polymarket emits a change to the book, not on a fixed polling clock. That makes the series efficient, but it raises an obvious question: how do you know you received every event? The answer is the sequence number that rides on each snapshot.
What the sequence number is for
Ordering
The sequence number gives every snapshot a definite position in the stream, independent of any clock skew.
- Definite order
- Clock-independent
- No tie-break guessing
Completeness
A run of consecutive sequence numbers is your proof that nothing fell out between two snapshots.
- Consecutive = whole
- Provable, not assumed
- Integrity check
Gap flags
A break in the sequence is a signal, an event was dropped, so you can quarantine that window instead of trusting it.
- Jump = missing event
- Quarantine the window
- Fail loud, not silent
How to verify a series
- 1Pull the snapshots for your market and window, ordered ascending so the sequence numbers run in capture order.
- 2Walk the series and check that each sequence_number follows the previous one, a clean run is a complete window.
- 3Where the sequence jumps, mark a gap: there was a book change you did not receive between those two snapshots.
- 4Decide the policy for each gap before you backtest, drop the affected window, or hold the last known book across it, but never silently interpolate.
Why a quiet market is not a gap
This is the distinction that makes the sequence number worth having. With event-driven capture, a long stretch with no new snapshot can mean two very different things: the book genuinely did not change, or you missed the events that changed it. The wall-clock gap between two snapshots cannot tell those apart, but the sequence number can. Consecutive numbers across a quiet stretch mean nothing was missed; a jump means it was.
Silence is a feature, not a hole
Because capture fires on book changes rather than a fixed interval, a gap in time is normal and expected when the market is calm. The sequence number is what separates that benign silence from a real dropped event, without it, you would be forced to treat every quiet patch as suspect.
The fields integrity rests on
sequence_numberPosition in the stream, the integrity keyevent_timestampWhen Polymarket emitted the changecapture_timestampWhen we processed it- order asc /
descPull in capture order to walk the sequence
The sequence number orders and verifies; the two timestamps tell you when each event happened and when it was processed. Read together, they let you reconstruct not just what the book looked like but whether your view of it is whole.
Being honest about what a gap means
- A gap means an event was not captured, it does not tell you what that event was or how far the book moved.
- Most gaps are small and local; the right response is to flag the window, not to throw away the dataset.
- Interpolating across a gap manufactures data that never existed, for replay fidelity, hold the last known state or skip the window instead.
- Gap detection is a property of the series you pull, so re-running the check after every pull is cheap insurance against a silent hole.
A missing event you never noticed is worse than one you did, the first corrupts your backtest quietly, the second you can quarantine.
Verify before you backtest
The quant research page covers gap-detection workflows; the backtesting tools let you replay a verified window tick by tick.
Frequently asked questions
What is the sequence_number on a snapshot?
It is a counter that gives every snapshot a definite position in the order-book stream. A consecutive run proves you have a complete, ordered series; a jump in the sequence flags that an event was dropped between two snapshots, so you can handle that window deliberately rather than trust it blindly.
How do I know my order-book series is complete?
Pull the snapshots in ascending order and walk the sequence numbers. If each follows the previous without a jump, the window is complete. Where the sequence skips, you missed a book change there and should quarantine or otherwise handle that window before backtesting.
Capture is event-driven, does a long gap in time mean missing data?
Not on its own. With event-driven capture, a stretch with no new snapshot often just means the book did not change. The sequence number is what distinguishes that benign silence from a real dropped event: consecutive numbers across a quiet stretch mean nothing was missed, while a jump means it was.
What should I do when I find a gap?
Be honest about what it is, an event you did not capture, with no way to know exactly what it was. Flag the window and either skip it or hold the last known book across it. Do not interpolate, because that invents data that never existed and quietly undermines replay fidelity.