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

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

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

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