Order-book reconstruction

Reconstruction is for applications that need a local book over time instead of independent snapshots.

Pattern

Start from a snapshot

Load the initial book state from REST or the first WebSocket snapshot.

Apply diffs in timestamp order

Ignore messages older than the snapshot timestamp and apply updates in order.

Detect gaps

If replay or live streams emit a gap signal, mark the local book as unsafe until it is rebuilt.

Resync when needed

Pull a fresh snapshot and resume from the latest known safe point.

Inputs

Reconstruction needs a trustworthy starting point and ordered changes. The starting point can come from a REST snapshot, a WebSocket snapshot, or a checkpoint route in venue families that expose checkpoints. Changes can come from diffs, replay messages, or a bounded historical stream. Store the source route or channel with every run.

TypeScript Reconstruction Helpers

The TypeScript SDK exposes Lighter tick-history helpers and an OrderBookReconstructor for workflows that need checkpoint plus delta reconstruction.

import { OrderBookReconstructor } from "@0xarchive/sdk";

const tickData = await client.lighter.orderbook.historyTick("BTC", {
  start: Date.now() - 3_600_000,
  end: Date.now()
});

const reconstructor = client.lighter.orderbook.createReconstructor();
const finalBook = reconstructor.reconstructFinal(
  tickData.checkpoint,
  tickData.deltas
);

const gaps = OrderBookReconstructor.detectGaps(tickData.deltas);
if (gaps.length > 0) {
  throw new Error(`Unsafe reconstruction: ${gaps.length} gap(s)`);
}

For larger windows, prefer the SDK’s async iterator helper when the installed package exposes it so pagination and reconstruction state stay together:

for await (const snapshot of client.lighter.orderbook.iterateTickHistory("BTC", {
  start: Date.now() - 86_400_000,
  end: Date.now()
})) {
  console.log(snapshot.timestamp, snapshot.midPrice);
}

Use these helpers only on a venue route that exposes the required depth. Every plan can access the depth exposed by the selected route: L3 is Lighter-only, L4 is Hyperliquid-family-only, and full-depth L2 is available on covered Hyperliquid core and HIP-3 routes. Plans differ in credits, request rate, concurrency, replay speed, query windows, and exports. For other families, keep the same reconstruction discipline but use the documented REST and WebSocket route family for that market.

Python And Rust Helpers

The Python and Rust SDKs also expose reconstruction-oriented types and helpers. Use the package README for exact import paths and method names, then keep the same manifest and gap policy from this page.

Runtime	Package surface	Use it for
Python	`oxarchive`, `OrderBookReconstructor`, WebSocket extra	Notebook or pipeline reconstruction with typed models and optional stream callbacks
Rust	`oxarchive`, `orderbook_reconstructor`, `websocket` feature	Async services and backtest runners that need typed reconstruction behavior
TypeScript	`@0xarchive/sdk`, `OrderBookReconstructor`, WebSocket helpers	App and worker code that needs checkpoint-plus-delta reconstruction

If a runtime helper is missing for the venue family, use the REST/WebSocket route directly and keep the same reconstruction checklist instead of pretending every SDK has the same method.

Gap Policy

A local book is only as trustworthy as its gap handling. If a replay, diff stream, or checkpoint route reports a missing segment, mark the local state unsafe and rebuild. Do not keep applying newer updates to a state that has an unknown hole. That can produce plausible but wrong depth.

Reconstruction Manifest

Store a manifest beside reconstructed output.

Field	Store
Venue family and symbol	Lighter `BTC`, Spot `HYPE-USDC`, HIP-3 `km:US500`, or another explicit family
Baseline source	REST snapshot, WebSocket snapshot, checkpoint route, or replay snapshot
Update source	Diffs, replay stream, tick history, or live channel
Window	start/end timestamps and any cursor or iterator state
Gap state	gap list, rebuild trigger, and whether the output is complete
Output depth	full book or capped depth level
Code surface	SDK package/version, generated client, or direct REST/WebSocket path

Venue Family Notes

Hyperliquid core, Hyperliquid Spot, HIP-3, HIP-4, and Lighter can expose different depth primitives. Keep the reconstruction code aware of venue family rather than trying to normalize every stream into one generic path. Use Venue coverage and Endpoint Reference pages before sharing reconstruction code across families.

Production Rule

Every reconstruction path needs a resync path. If the local book cannot recover from a missing diff, unavailable checkpoint, or replay gap, do not use it as production reconstruction logic. Verify recovery with a forced gap or closed connection, and record the rebuild trigger beside the manifest.

API reference

SDKs & tooling

AI & agents

Order-book reconstruction

Pattern

Inputs

TypeScript Reconstruction Helpers

Python And Rust Helpers

Gap Policy

Reconstruction Manifest

Venue Family Notes

Production Rule

​Pattern

​Inputs

​TypeScript Reconstruction Helpers

​Python And Rust Helpers

​Gap Policy

​Reconstruction Manifest

​Venue Family Notes

​Production Rule

Pattern

Inputs

TypeScript Reconstruction Helpers

Python And Rust Helpers

Gap Policy

Reconstruction Manifest

Venue Family Notes

Production Rule