> For the complete documentation index, see [llms.txt](https://docs.hydromancer.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hydromancer.xyz/readme/builder-guides/l4-orderbook-streaming.md).

# L4 orderbook streaming

Maintain a real-time L4 orderbook locally using snapshot + delta sync.

### How it works

1. Subscribe to [l4BookUpdates](/readme/websocket/l4bookupdates.md) and buffer incoming updates
2. Fetch [L4PerpBookSnapshot](/readme/rest-api/market-data/l4book.md) snapshot with block height
3. Apply buffered updates where `height > snapshot_height`
4. Continue applying live updates

This gives you a complete L4 orderbook with user addresses for every resting order.

### Use cases

* **HIP-3 liquidity incentives** - monitor which users qualify for LP rewards based on their orderbook presence
* **BBO tracking** - identify which users are providing best bid/offer
* **Market making** - track your queue position, monitor competitor liquidity
* **Analytics** - real-time orderbook metrics, spread analysis, depth tracking

### SDK

The [Hydromancer Python SDK](https://github.com/hydromancerxyz/hydromancer-sdk) handles sync automatically:

```python
from hydromancer_sdk import L4OrderbookClient

client = L4OrderbookClient(coins=["ETH", "BTC"])
await client.run()

book = client.get_book("ETH")
print(book.best_bid_str(), book.best_ask_str())
```

See [examples](https://github.com/hydromancerxyz/hydromancer-sdk/tree/main/examples) for streaming orderbook and validation usage. Use [meta](/readme/rest-api/metadata/meta.md) to call correct markets.

### Manual implementation

If implementing without the SDK, handle the three diff types from [l4BookUpdates](/readme/websocket/l4bookupdates.md):

* **new** - insert order into book at price level, store `oid`, `user`, `side`, `px`, `sz`
* **update** - find order by `oid`, update `sz` (partial fill occurred)
* **remove** - delete order by `oid` (filled or cancelled)

Maintain orders indexed by `oid` for fast lookups. Use sorted structures (e.g. sorted map) keyed by price for efficient BBO queries.

**Important:** Order matching is mandatory. When inserting new orders, run your matching engine to cross any orders that would trade (bid >= ask). Without matching, your book will become stale and show crossed markets.

### Key details

* Updates arrive per-block (\~70ms block time)
* Perp and spot markets are both included
* Includes all resting limit orders with user addresses
* Does not include untriggered stop/take-profit orders