IBKR Spread Quote Schema v2 Draft¶
Status: DRAFT Updated: 2026-04-13 Scope: Phase 6.1 planned spread-quote JSONL contract
Purpose¶
- Freeze the Python-side draft contract before the Rust spread collector grows more fields.
- Keep downstream parity scripts aligned on one top-level schema string and field set.
Proposed Record¶
Each JSONL row should represent one spread quote snapshot.
| Field | Type | Unit | Notes |
|---|---|---|---|
schema |
string | n/a | Fixed value: ibkr_spread_quote_v1 |
ts_utc |
string | ISO-8601 UTC | Collector write timestamp |
ts_ms |
integer | epoch milliseconds | Same timestamp in integer form |
underlying_symbol |
string | ticker | Example: SPY |
underlying_conid |
integer | IBKR contract id | Underlying contract id |
short_leg_conid |
integer | IBKR contract id | Short put conid |
short_strike |
number | USD | Short leg strike |
short_expiry |
string | YYYY-MM-DD |
Short leg expiry |
long_leg_conid |
integer | IBKR contract id | Long put conid |
long_strike |
number | USD | Long leg strike |
long_expiry |
string | YYYY-MM-DD |
Long leg expiry |
short_bid |
number or null | USD/contract | Short leg bid |
short_ask |
number or null | USD/contract | Short leg ask |
long_bid |
number or null | USD/contract | Long leg bid |
long_ask |
number or null | USD/contract | Long leg ask |
net_bid |
number or null | USD/spread | short_bid - long_ask |
net_ask |
number or null | USD/spread | short_ask - long_bid |
net_mid |
number or null | USD/spread | Midpoint of net_bid and net_ask |
spread_width |
number | USD | Absolute strike width |
delayed |
boolean | n/a | true when IBKR marks the quote delayed |
authenticated |
boolean | n/a | Collector auth state at write time |
source |
string | n/a | Writer id such as lt-ibkr-spread-collector |
Example Record¶
{
"schema": "ibkr_spread_quote_v1",
"ts_utc": "2026-04-13T13:35:12.456Z",
"ts_ms": 1776087312456,
"underlying_symbol": "SPY",
"underlying_conid": 756733,
"short_leg_conid": 912345678,
"short_strike": 550.0,
"short_expiry": "2026-04-17",
"long_leg_conid": 912345679,
"long_strike": 545.0,
"long_expiry": "2026-04-17",
"short_bid": 1.82,
"short_ask": 1.88,
"long_bid": 0.94,
"long_ask": 0.98,
"net_bid": 0.84,
"net_ask": 0.94,
"net_mid": 0.89,
"spread_width": 5.0,
"delayed": false,
"authenticated": true,
"source": "lt-ibkr-spread-collector"
}
Notes¶
- This file is intentionally named
v2_schemabecause it supersedes the earlier spread-shape notes while the emitted schema string still starts atibkr_spread_quote_v1. - If Phase 6.1 changes field names, units, or nesting, the next draft must update both this document and the emitting collector in the same change set.