SDKs

# pip install oxarchive
from oxarchive import Client

client = Client(api_key="0xa_your_api_key")

# Hyperliquid data
hl_orderbook = client.hyperliquid.orderbook.get("BTC")
print(f"Hyperliquid BTC mid price: {hl_orderbook.mid_price}")

# Lighter.xyz data
lighter_orderbook = client.lighter.orderbook.get("BTC")
print(f"Lighter BTC mid price: {lighter_orderbook.mid_price}")

# HIP-3 builder perps
hip3_ob = client.hyperliquid.hip3.orderbook.get("xyz:XYZ100")
print(f"HIP-3 XYZ100 mid price: {hip3_ob.mid_price}")

hip3_trades = client.hyperliquid.hip3.trades.recent("xyz:XYZ100", limit=10)
print(f"Recent HIP-3 trades: {len(hip3_trades)}")

# Get trades with cursor pagination
result = client.hyperliquid.trades.list("ETH", start="2026-01-01", end="2026-01-02", limit=1000)
trades = result.data

# Continue fetching all pages
while result.next_cursor:
    result = client.hyperliquid.trades.list(
        "ETH", start="2026-01-01", end="2026-01-02",
        cursor=result.next_cursor, limit=1000
    )
    trades.extend(result.data)

import asyncio
from oxarchive import OxArchiveWs, WsOptions

async def main():
    ws = OxArchiveWs(WsOptions(api_key="0xa_your_api_key"))

    # Subscribe to real-time data
    ws.on_orderbook(lambda coin, data: print(f"{coin}: {data.mid_price}"))

    await ws.connect()
    ws.subscribe_orderbook("BTC")

    # Or replay historical data
    await ws.replay("orderbook", "BTC", start=1704067200000, speed=10)

asyncio.run(main())

# Server-side L4 reconstruction (Pro+ tier)
# The server handles the matching engine — just pass a timestamp.
from oxarchive import Client

client = Client(api_key="0xa_your_api_key")

# Hyperliquid: get L4 orderbook at a specific point in time
l4 = client.hyperliquid.l4_orderbook.get("BTC", timestamp=1711900800000)
print(f"BTC L4: {l4['bid_count']} bids, {l4['ask_count']} asks")
print(f"Best bid: {l4['bids'][0]['price']}, Best ask: {l4['asks'][0]['price']}")

# HIP-3: same method, same response format
hip3_l4 = client.hyperliquid.hip3.l4_orderbook.get("xyz:CL", timestamp=1711900800000)
print(f"Crude Oil L4: {hip3_l4['bid_count']} bids, {hip3_l4['ask_count']} asks")

# Omit timestamp for current live state (from Redis, sub-second)
live = client.hyperliquid.l4_orderbook.get("BTC")

# L2 full-depth (aggregated from L4, Build+ tier)
l2 = client.hyperliquid.l2_orderbook.get("BTC", timestamp=1711900800000)
print(f"BTC L2: {l2['bid_levels']} bid levels, {l2['ask_levels']} ask levels")
print(f"Best bid: {l2['bids'][0]['px']} ({l2['bids'][0]['n']} orders)")

# Client-side L4 reconstruction with matching engine (Pro+ tier)
# Same approach for Hyperliquid and HIP-3 — identical diff format.
from oxarchive import Client, L4OrderBookReconstructor
from collections import defaultdict

client = Client(api_key="0xa_your_api_key")
start, end = 1711900800000, 1711901100000  # 5-minute window

# 1. Fetch nearest L4 checkpoint
checkpoints = client.hyperliquid.l4_orderbook.history("BTC", start=start-1800000, end=start)
checkpoint = checkpoints.data[-1]  # nearest before target

# 2. Fetch L4 diffs from checkpoint to target
diffs = client.hyperliquid.l4_orderbook.diffs("BTC", start=start, end=end)

# 3. Fetch order statuses for non-resting filter (optional, improves accuracy)
statuses = client.hyperliquid.orders.history("BTC", start=start, end=end)
non_resting = defaultdict(set)
for s in statuses.data:
    if s["status"] != "open":
        non_resting[s["block_number"]].add(s["oid"])

# 4. Reconstruct with matching engine
book = L4OrderBookReconstructor()
book.load_checkpoint(checkpoint)

# Group diffs by block, apply in order
blocks = defaultdict(list)
for d in diffs.data:
    blocks[d["block_number"]].append(d)

for bn in sorted(blocks):
    nr = non_resting.get(bn)
    for diff in blocks[bn]:
        book.apply_diff(diff, nr)

# 5. Result: non-crossed L4 orderbook
assert not book.is_crossed(), "Book should not be crossed"
print(f"Best bid: {book.best_bid()}, Best ask: {book.best_ask()}")
print(f"Orders: {len(book.bids())} bids, {len(book.asks())} asks")

# 6. Derive L2 from L4 (aggregate by price level)
l2_bids, l2_asks = book.derive_l2()
print(f"L2 levels: {len(l2_bids)} bid, {len(l2_asks)} ask")

# Orderbook Reconstruction (Enterprise tier only)
from oxarchive import Client, OrderBookReconstructor

client = Client(api_key="0xa_your_api_key")

# Option 1: Auto-paginating iterator (recommended for large time ranges)
# Automatically handles pagination, fetching up to 1,000 deltas per request
for snapshot in client.lighter.orderbook.iterate_tick_history(
    "BTC",
    start="2026-01-01T00:00:00Z",
    end="2026-01-01T12:00:00Z"  # 12 hours of data
):
    print(f"{snapshot.timestamp}: mid={snapshot.mid_price}")
    if some_condition:
        break  # Early exit supported

# Option 2: Get fully reconstructed snapshots (single page)
snapshots = client.lighter.orderbook.history_reconstructed(
    "BTC",
    start="2026-01-01T00:00:00Z",
    end="2026-01-01T01:00:00Z"
)
for ob in snapshots:
    print(f"{ob.timestamp}: bid={ob.bids[0].px} ask={ob.asks[0].px}")

# Option 3: Get raw tick data for custom reconstruction
tick_data = client.lighter.orderbook.history_tick("BTC", start=start, end=end)
print(f"Checkpoint: {len(tick_data.checkpoint.bids)} bids")
print(f"Deltas: {len(tick_data.deltas)} updates")

# Check for sequence gaps
gaps = OrderBookReconstructor.detect_gaps(tick_data.deltas)
if gaps:
    print("Gaps detected:", gaps)