A point-in-time normalized order book snapshot.

A MarketSnapshot is the input an execution model uses to simulate a fill: it carries the resting bids and asks for one PaperEx.Instrument, in normalized form (price descending for bids, price ascending for asks).

Adapters produce snapshots from exchange-specific payloads via the PaperEx.Adapter.normalize_snapshot/2 callback. The engine never fetches a snapshot itself — this package does no IO. Callers either pass a snapshot in directly or build one from data their adapter normalized.

Fields

• :instrument_id (required) — matches a PaperEx.Instrument.id. The engine uses this to associate the snapshot with the right position bucket.
• :bids — list of {price, size} tuples, sorted descending by price (best bid first). Defaults to [].
• :asks — list of {price, size} tuples, sorted ascending by price (best ask first). Defaults to [].
• :as_of — DateTime.t() when the snapshot was observed. Defaults to DateTime.utc_now/0.
• :metadata — free-form map. Adapters can stash raw payloads here.

Convenience accessors

• best_bid/1, best_ask/1 — {price, size} of the top level on each side, or nil if that side is empty.
• midpoint/1 — (best_bid_price + best_ask_price) / 2, or nil if either side is empty.
• spread/1 — best_ask_price - best_bid_price, or nil if either side is empty.

The engine and the default execution model use these accessors rather than indexing the lists directly, so adapters do not need to expose extra helpers.

Sorting invariant

new/1 does not sort the lists for you; it only validates the shape. Adapters are responsible for producing already-sorted lists. That keeps new/1 cheap and the data contract explicit: a snapshot that comes off an exchange WebSocket usually arrives sorted.