Guides / API Guide

Reconstructing an Order Book From Snapshots

ProbSights records the book as periodic snapshots, not as an event stream of individual order placements and cancels. That distinction defines what you can rebuild: how depth looked at each sampled instant, and therefore what a trade would have cost — but not the sequence of individual orders between two samples.

What one snapshot holds

Polymarket snapshots carry bids and asks; Kalshi's carry yes_bids and no_bids, because a No bid is the mirror of the Yes book. Both are arrays of { price, size }, alongside derived best_bid/best_ask (or best_yes_bid/best_yes_ask), mid, and spread.

Replaying a range

Pull the range with granularity=1m, following pagination_key to the end.
Sort by timestamp — do not assume page order is time order.
Step forward one snapshot at a time, treating each as the book state until the next.
Join the trade tape on timestamp to see which resting size actually got taken.

Walking the book for a fill price

This is the whole point of keeping depth rather than just mid-price. To buy n contracts, consume ask levels in price order until filled:

def fill_cost(levels, qty):
    cost = filled = 0
    for level in levels:                      # already price-ordered
        take = min(qty - filled, level["size"])
        cost += take * float(level["price"])
        filled += take
        if filled >= qty:
            return cost / filled              # average fill price
    return None                               # book too thin for this size

Returning None matters as much as the price: a size the book cannot absorb is a trade that would not have happened, and a backtest that fills it anyway is inventing liquidity. See why mid-price backtests lie.

The limits of snapshots

Between samples is invisible. At 1m, a spread that blew out for ten seconds may never appear. Latency-sensitive strategies cannot be validated this way.
No queue position. Snapshots show size at a price, not order order, so passive-fill assumptions stay assumptions.
Gaps are real. Missing minutes happen; detect them by diffing consecutive timestamps rather than assuming a fixed cadence.

Related guides

Data from Kalshi and Polymarket. Search live API docs Pricing