# StreamL4BookUpdates

> HyperCore private-preview documentation.

> For the complete documentation index, see [llms.txt](/docs/llms.txt).

<Callout intent="info">
  This API is in private preview. Target September 2026; timing is subject to change.
</Callout>


# Stream L4 book updates

`StreamL4BookUpdates` delivers every individual order placed, resized, or removed,
including its position in the price-level queue. This is ideal for market making,
queue-position analysis, liquidity attribution, and reconstructing an exact book.

## Overview

* The first message after subscribing is a full snapshot: every resting order is delivered
  as a `NEW` diff with `snapshot` set true
* `UPDATE` means the order's size changed, typically a partial fill
* `REMOVE` is terminal — the order was filled or cancelled
* Aggregating these orders by price yields an exact L2 view, so a single subscription can
  serve both order-level and level-aggregated needs

## Request structure

```proto
message StreamL4BookUpdatesRequest {
  repeated string coins = 1;
  repeated string market_types = 2;
}
```

### Coins

**Field**: `coins`
**Type**: `repeated string`

Markets to subscribe to. Empty means all markets.

### Market types

**Field**: `market_types`
**Type**: `repeated string`

Accepted values are `perp`, `spot`, `outcome`, or `*`. The default is `["perp"]`, so
spot and outcome markets are not delivered unless requested. The default never grows:
add new market types explicitly, or pass `["*"]` to opt in to future types automatically.
This field is rejected when combined with an explicit `coins` list.

## Response structure

```proto
message L4BookUpdatesUpdate {
  uint64 height = 1;
  uint64 time = 2;
  bool snapshot = 3;
  string cursor = 4;
  repeated OrderDiff diffs = 5;
}

message OrderDiff {
  DiffType diff_type = 1;
  string coin = 2;
  uint64 oid = 3;
  string user = 4;
  string side = 5;
  string px = 6;
  string sz = 7;
  optional uint64 insert_before = 8;
  optional string orig_sz = 9;
  optional string new_sz = 10;
}

enum DiffType {
  DIFF_TYPE_NEW = 0;
  DIFF_TYPE_UPDATE = 1;
  DIFF_TYPE_REMOVE = 2;
}
```

### Key fields

**`oid`**: Order ID, unique and stable for the life of the order.

**`user`**: Address that placed the order.

**`side`**: `B` for bid, `A` for ask.

**`px`**: Limit price, as a decimal string.

**`sz`**: Initial order size on `NEW`. Absent on `UPDATE` and `REMOVE`.

**`orig_sz`**: Order size before an `UPDATE`. Absent on `NEW` and `REMOVE`.

**`new_sz`**: Order size after an `UPDATE`. Absent on `NEW` and `REMOVE`.

**`insert_before`**: Queue placement. Insert this order immediately ahead of the resting
order with this ID at the same price level. Absent means append to the tail of the queue.
If the named order is no longer at that level, append to the tail.

### Field presence by operation

| Operation | Operation-specific fields |
| --- | --- |
| `NEW` | `sz`, and `insert_before` when applicable |
| `UPDATE` | `orig_sz`, `new_sz` |
| `REMOVE` | None; the normalized diff carries only its common context. |

## Queue position

`insert_before` reflects HyperCore's priority placement rules. It supplies the queue
position that makes order-level consumption useful beyond aggregated levels.

## Recovery

A message flagged as a snapshot replaces your local state. Anything else is a diff that
must chain onto your previous block.

If continuity is broken, a fresh snapshot is pushed to you. The snapshot flag is the
only continuity signal you need to handle — receiving it means discard local state
and adopt the snapshot.

## Choosing a book stream

| | StreamL2Book | StreamL2BookDiff | StreamL4BookUpdates |
| --- | --- | --- | --- |
| **Payload** | Full snapshot per block | Changed levels only | Per-order changes |
| **Client state** | None required | Maintains a local book | Maintains a local book |
| **Bandwidth** | Highest | Low | Moderate |
| **Detail** | Aggregated levels | Aggregated levels | Individual orders, with queue position |
| **Use case** | Displays, periodic reads | Efficient live book | Market making, queue analysis |