quantpylib.standards.models
Repo standards for native market-data models and schema helpers.
Fixed-point scale
BookUpdate, BBAUpdate, and TradeUpdate store prices and sizes as
fixed-point int64 values. PRICE_SCALE and SIZE_SCALE are both
1_000_000_000, so decoded values are stored_int / 1_000_000_000.
Inputs normalized through parse_scaled_int() support up to 9 fractional
decimal places.
Flag semantics
Native market-data objects carry a flags bitmask. Decode each bit
independently with bitwise checks, for example update.flags & PROV_EXCH_TS.
Timestamp provenance bits can appear on BookUpdate, BBAUpdate, and
TradeUpdate. Book-state bits are specific to BookUpdate; top-of-book side
availability bits are specific to BBAUpdate.
| Constant | Bit | Applies to | Meaning |
|---|---|---|---|
IS_SNAPSHOT |
1 << 0 |
BookUpdate |
Event represents a book snapshot instead of an incremental update. |
PROV_EXCH_TS |
1 << 1 |
BookUpdate, BBAUpdate, TradeUpdate |
ts_exch_ns came from a provider exchange-event timestamp. If absent, ts_exch_ns falls back to provider dispatch time or local receive time. |
PROV_DISP_TS |
1 << 2 |
BookUpdate, BBAUpdate, TradeUpdate |
ts_disp_ns came from a provider dispatch timestamp. If absent, ts_disp_ns falls back to ts_exch_ns. |
HAS_BID |
1 << 3 |
BBAUpdate |
Bid price is present. |
HAS_ASK |
1 << 4 |
BBAUpdate |
Ask price is present. |
HAS_BID_SZ |
1 << 5 |
BBAUpdate |
Bid size is present. HAS_BID must also be present. |
HAS_ASK_SZ |
1 << 6 |
BBAUpdate |
Ask size is present. HAS_ASK must also be present. |
BIDS_SORTED |
1 << 7 |
BookUpdate |
Bid levels are sorted. |
BIDS_ASCENDING |
1 << 8 |
BookUpdate |
Bid levels are sorted ascending when BIDS_SORTED is present; otherwise sorted bids are descending. |
ASKS_SORTED |
1 << 9 |
BookUpdate |
Ask levels are sorted. |
ASKS_DESCENDING |
1 << 10 |
BookUpdate |
Ask levels are sorted descending when ASKS_SORTED is present; otherwise sorted asks are ascending. |
The helper constructors set provenance flags through timestamp normalization.
When provider_exch_ns is supplied, ts_exch_ns is set from it and
PROV_EXCH_TS is set. Without provider_exch_ns, ts_exch_ns falls back to
provider_disp_ns when available, otherwise to ts_recv_ns, and
PROV_EXCH_TS remains unset. When provider_disp_ns is supplied,
ts_disp_ns is set from it and PROV_DISP_TS is set. Without
provider_disp_ns, ts_disp_ns equals ts_exch_ns, and PROV_DISP_TS
remains unset.
For BBAUpdate, side flags and size flags are separate. A price-only bid sets
HAS_BID without HAS_BID_SZ; a price-only ask sets HAS_ASK without
HAS_ASK_SZ. Supplying a size without the corresponding price is invalid in
the helper constructor. Missing sides are encoded as zero price and zero size
with the side flag unset.
Native market-data model standards.
BookUpdate, BBAUpdate, and TradeUpdate store prices and sizes as
fixed-point int64 values. PRICE_SCALE and SIZE_SCALE are both
1,000,000,000, so decoded values are stored_int / 1_000_000_000.
Inputs normalized through parse_scaled_int() support up to 9 fractional
decimal places.
BookUpdate
Native L2 order-book update emitted by schema-2 capture paths.
BookUpdate stores bid and ask levels as fixed-point int64 values in a
contiguous NumPy data buffer. The first nbids * 2 entries are bid
price/size pairs and the next nasks * 2 entries are ask price/size
pairs. Prices and sizes use PRICE_SCALE and SIZE_SCALE.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ts_exch_ns
|
int
|
Exchange event timestamp in nanoseconds. |
required |
ts_disp_ns
|
int
|
Provider dispatch timestamp in nanoseconds. |
required |
ts_recv_ns
|
int
|
Local receive timestamp in nanoseconds. |
required |
ticker
|
str
|
Ticker symbol. |
required |
flags
|
int
|
Native event bitmask for timestamp provenance, snapshot state, and book sort state. See the page-level flag semantics table. |
required |
nbids
|
int
|
Number of bid levels encoded in |
required |
nasks
|
int
|
Number of ask levels encoded in |
required |
seq_type
|
int
|
Sequence mode, such as |
required |
seq0
|
int
|
First sequence slot. |
required |
seq1
|
int
|
Second sequence slot. |
required |
seq2
|
int
|
Third sequence slot. |
required |
data
|
ndarray
|
One-dimensional, C-contiguous int64 price/size buffer. |
required |
data_bytes()
Return the raw encoded book-level buffer bytes.
qbn_header_bytes(local_id)
Return the QBN header bytes for local_id.
qbn_record_bytes(local_id)
Return the complete QBN record bytes for local_id.
runtime_bytes()
Return the complete runtime-format record bytes.
runtime_header_bytes()
Return the runtime-format fixed header bytes.
BBAUpdate
Native best bid/ask update emitted by schema-2 capture paths.
Prices and sizes are stored as fixed-point int64 values using
PRICE_SCALE and SIZE_SCALE. Missing sides are represented with zero
price/size fields and side-availability bits in flags.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ts_exch_ns
|
int
|
Exchange event timestamp in nanoseconds. |
required |
ts_disp_ns
|
int
|
Provider dispatch timestamp in nanoseconds. |
required |
ts_recv_ns
|
int
|
Local receive timestamp in nanoseconds. |
required |
ticker
|
str
|
Ticker symbol. |
required |
flags
|
int
|
Native event bitmask for timestamp provenance, side availability, and size availability. See the page-level flag semantics table. |
required |
seq_type
|
int
|
Sequence mode. |
required |
seq0
|
int
|
First sequence slot. |
required |
seq1
|
int
|
Second sequence slot. |
required |
seq2
|
int
|
Third sequence slot. |
required |
bid_price
|
int
|
Fixed-point bid price. |
required |
bid_size
|
int
|
Fixed-point bid size. |
required |
ask_price
|
int
|
Fixed-point ask price. |
required |
ask_size
|
int
|
Fixed-point ask size. |
required |
qbn_record_bytes(local_id)
Return the complete QBN record bytes for local_id.
runtime_bytes()
Return the complete runtime-format record bytes.
runtime_fixed_bytes()
Return the runtime-format fixed record bytes.
TradeUpdate
Native public trade update emitted by schema-2 capture paths.
Price and size are stored as fixed-point int64 values using
PRICE_SCALE and SIZE_SCALE; side uses the standard BUY_SIDE,
SELL_SIDE, and UNKNOWN_SIDE constants.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ts_exch_ns
|
int
|
Exchange event timestamp in nanoseconds. |
required |
ts_disp_ns
|
int
|
Provider dispatch timestamp in nanoseconds. |
required |
ts_recv_ns
|
int
|
Local receive timestamp in nanoseconds. |
required |
ticker
|
str
|
Ticker symbol. |
required |
flags
|
int
|
Native event bitmask for timestamp provenance. See the page-level flag semantics table. |
required |
seq_type
|
int
|
Sequence mode. |
required |
seq0
|
int
|
First sequence slot. |
required |
seq1
|
int
|
Second sequence slot. |
required |
seq2
|
int
|
Third sequence slot. |
required |
price
|
int
|
Fixed-point trade price. |
required |
size
|
int
|
Fixed-point trade size. |
required |
side
|
int
|
Trade side. |
required |
qbn_record_bytes(local_id)
Return the complete QBN record bytes for local_id.
runtime_bytes()
Return the complete runtime-format record bytes.
runtime_fixed_bytes()
Return the runtime-format fixed record bytes.