Skip to main content

polaris_data/
models.rs

1use std::{collections::BTreeMap, pin::Pin};
2
3use chrono::{DateTime, Utc};
4use futures_core::Stream;
5use serde::{Deserialize, Serialize};
6use serde_json::Value;
7
8use crate::errors::PolarisError;
9
10#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
11pub struct Diagnostic {
12    pub code: String,
13    pub message: String,
14}
15
16#[derive(Clone, Debug, PartialEq, Eq)]
17pub enum TimeInput {
18    Iso8601(String),
19    DateTime(DateTime<Utc>),
20    EpochMicros(i64),
21}
22
23impl From<&str> for TimeInput {
24    fn from(value: &str) -> Self {
25        Self::Iso8601(value.to_owned())
26    }
27}
28
29impl From<String> for TimeInput {
30    fn from(value: String) -> Self {
31        Self::Iso8601(value)
32    }
33}
34
35impl From<DateTime<Utc>> for TimeInput {
36    fn from(value: DateTime<Utc>) -> Self {
37        Self::DateTime(value)
38    }
39}
40
41impl From<i64> for TimeInput {
42    fn from(value: i64) -> Self {
43        Self::EpochMicros(value)
44    }
45}
46
47impl From<u64> for TimeInput {
48    fn from(value: u64) -> Self {
49        Self::EpochMicros(value as i64)
50    }
51}
52
53#[derive(Clone, Debug, Default, PartialEq, Eq)]
54pub struct CatalogQuery {
55    pub source: Option<String>,
56    pub market: Option<String>,
57    pub q: Option<String>,
58}
59
60/// Public API discovery links returned by `/meta`.
61#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
62pub struct MetaResponse {
63    pub name: String,
64    pub docs: String,
65    pub llms: String,
66    pub openapi: String,
67    pub skill: String,
68    pub health: String,
69    pub stream: String,
70}
71
72/// Filters for option-contract discovery. `market` is the normalized underlying.
73#[derive(Clone, Debug, PartialEq, Eq)]
74pub struct InstrumentsQuery {
75    pub source: String,
76    pub market: String,
77    pub instrument: Option<String>,
78    /// Exact expiry as Unix milliseconds.
79    pub expiry: Option<i64>,
80    pub option_type: Option<String>,
81    pub q: Option<String>,
82}
83
84#[derive(Clone, Debug, Default, PartialEq, Eq)]
85pub struct BboQuery {
86    pub source: String,
87    pub market: String,
88    pub start: i64,
89    pub end: i64,
90    pub interval: Option<OhlcvInterval>,
91}
92
93/// Filters for the direct historical row endpoints. Times are inclusive Unix milliseconds.
94#[derive(Clone, Debug, Default, PartialEq, Eq)]
95pub struct HistoricalRowsQuery {
96    pub source: Option<String>,
97    pub market: Option<String>,
98    pub start: Option<i64>,
99    pub end: Option<i64>,
100}
101
102/// Trade filters. `instrument` selects one exact venue-native instrument.
103#[derive(Clone, Debug, Default, PartialEq, Eq)]
104pub struct TradeRowsQuery {
105    pub source: Option<String>,
106    pub market: Option<String>,
107    pub instrument: Option<String>,
108    pub start: Option<i64>,
109    pub end: Option<i64>,
110}
111
112impl From<HistoricalRowsQuery> for TradeRowsQuery {
113    fn from(query: HistoricalRowsQuery) -> Self {
114        Self {
115            source: query.source,
116            market: query.market,
117            instrument: None,
118            start: query.start,
119            end: query.end,
120        }
121    }
122}
123
124#[derive(Clone, Debug, Default, PartialEq, Eq)]
125pub struct OptionTickerRowsQuery {
126    pub source: Option<String>,
127    pub market: Option<String>,
128    pub instrument: Option<String>,
129    pub start: Option<i64>,
130    pub end: Option<i64>,
131}
132
133#[derive(Clone, Debug, Default, PartialEq, Eq)]
134pub struct OhlcvRowsQuery {
135    pub source: Option<String>,
136    pub market: Option<String>,
137    pub instrument: Option<String>,
138    pub interval: Option<String>,
139    pub start: Option<i64>,
140    pub end: Option<i64>,
141}
142
143/// Required inclusive collector-time window for the authenticated `/events` route.
144#[derive(Clone, Debug, PartialEq, Eq)]
145pub struct EventsQuery {
146    pub start: i64,
147    pub end: i64,
148    pub types: Option<Vec<MixedEventType>>,
149    pub source: Option<String>,
150    pub market: Option<String>,
151    pub instrument: Option<String>,
152}
153
154#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
155#[serde(rename_all = "snake_case")]
156pub enum MixedEventType {
157    Trade,
158    L2Update,
159    FundingRate,
160    Intent,
161    Quote,
162    OptionTicker,
163    Ohlcv,
164}
165
166impl MixedEventType {
167    pub fn as_str(self) -> &'static str {
168        match self {
169            Self::Trade => "trade",
170            Self::L2Update => "l2_update",
171            Self::FundingRate => "funding_rate",
172            Self::Intent => "intent",
173            Self::Quote => "quote",
174            Self::OptionTicker => "option_ticker",
175            Self::Ohlcv => "ohlcv",
176        }
177    }
178}
179
180#[derive(Clone, Debug, Default, PartialEq, Eq)]
181pub struct IntentRowsQuery {
182    pub source: Option<String>,
183    pub market: Option<String>,
184    pub instrument: Option<String>,
185    pub intent_id: Option<String>,
186    pub start: Option<i64>,
187    pub end: Option<i64>,
188}
189
190#[derive(Clone, Debug, Default, PartialEq, Eq)]
191pub struct QuoteRowsQuery {
192    pub source: Option<String>,
193    pub market: Option<String>,
194    pub instrument: Option<String>,
195    pub observation_id: Option<String>,
196    pub start: Option<i64>,
197    pub end: Option<i64>,
198}
199
200/// Filters for flat source snapshots and deltas from `/l2-updates`.
201#[derive(Clone, Debug, Default, PartialEq, Eq)]
202pub struct L2UpdatesQuery {
203    pub source: Option<String>,
204    pub market: Option<String>,
205    pub instrument: Option<String>,
206    pub start: Option<i64>,
207    pub end: Option<i64>,
208}
209
210/// Required inclusive millisecond window for `/l2-orderbooks`.
211#[derive(Clone, Debug, PartialEq, Eq)]
212pub struct L2OrderbooksQuery {
213    pub source: String,
214    pub market: String,
215    pub instrument: Option<String>,
216    pub start: i64,
217    pub end: i64,
218}
219
220/// One flat top-25 L2 row with all nullable fixed level fields from the API.
221#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
222pub struct OrderbookL2Row {
223    pub event_id: String,
224    pub source: String,
225    pub market: String,
226    pub instrument: Option<String>,
227    pub collector_timestamp: i64,
228    pub exchange_timestamp: Option<i64>,
229    pub source_capture_id: String,
230    pub schema_version: u32,
231    pub source_event_is_snapshot: bool,
232    pub bid_px_00: Option<f64>,
233    pub bid_sz_00: Option<f64>,
234    pub ask_px_00: Option<f64>,
235    pub ask_sz_00: Option<f64>,
236    pub bid_px_01: Option<f64>,
237    pub bid_sz_01: Option<f64>,
238    pub ask_px_01: Option<f64>,
239    pub ask_sz_01: Option<f64>,
240    pub bid_px_02: Option<f64>,
241    pub bid_sz_02: Option<f64>,
242    pub ask_px_02: Option<f64>,
243    pub ask_sz_02: Option<f64>,
244    pub bid_px_03: Option<f64>,
245    pub bid_sz_03: Option<f64>,
246    pub ask_px_03: Option<f64>,
247    pub ask_sz_03: Option<f64>,
248    pub bid_px_04: Option<f64>,
249    pub bid_sz_04: Option<f64>,
250    pub ask_px_04: Option<f64>,
251    pub ask_sz_04: Option<f64>,
252    pub bid_px_05: Option<f64>,
253    pub bid_sz_05: Option<f64>,
254    pub ask_px_05: Option<f64>,
255    pub ask_sz_05: Option<f64>,
256    pub bid_px_06: Option<f64>,
257    pub bid_sz_06: Option<f64>,
258    pub ask_px_06: Option<f64>,
259    pub ask_sz_06: Option<f64>,
260    pub bid_px_07: Option<f64>,
261    pub bid_sz_07: Option<f64>,
262    pub ask_px_07: Option<f64>,
263    pub ask_sz_07: Option<f64>,
264    pub bid_px_08: Option<f64>,
265    pub bid_sz_08: Option<f64>,
266    pub ask_px_08: Option<f64>,
267    pub ask_sz_08: Option<f64>,
268    pub bid_px_09: Option<f64>,
269    pub bid_sz_09: Option<f64>,
270    pub ask_px_09: Option<f64>,
271    pub ask_sz_09: Option<f64>,
272    pub bid_px_10: Option<f64>,
273    pub bid_sz_10: Option<f64>,
274    pub ask_px_10: Option<f64>,
275    pub ask_sz_10: Option<f64>,
276    pub bid_px_11: Option<f64>,
277    pub bid_sz_11: Option<f64>,
278    pub ask_px_11: Option<f64>,
279    pub ask_sz_11: Option<f64>,
280    pub bid_px_12: Option<f64>,
281    pub bid_sz_12: Option<f64>,
282    pub ask_px_12: Option<f64>,
283    pub ask_sz_12: Option<f64>,
284    pub bid_px_13: Option<f64>,
285    pub bid_sz_13: Option<f64>,
286    pub ask_px_13: Option<f64>,
287    pub ask_sz_13: Option<f64>,
288    pub bid_px_14: Option<f64>,
289    pub bid_sz_14: Option<f64>,
290    pub ask_px_14: Option<f64>,
291    pub ask_sz_14: Option<f64>,
292    pub bid_px_15: Option<f64>,
293    pub bid_sz_15: Option<f64>,
294    pub ask_px_15: Option<f64>,
295    pub ask_sz_15: Option<f64>,
296    pub bid_px_16: Option<f64>,
297    pub bid_sz_16: Option<f64>,
298    pub ask_px_16: Option<f64>,
299    pub ask_sz_16: Option<f64>,
300    pub bid_px_17: Option<f64>,
301    pub bid_sz_17: Option<f64>,
302    pub ask_px_17: Option<f64>,
303    pub ask_sz_17: Option<f64>,
304    pub bid_px_18: Option<f64>,
305    pub bid_sz_18: Option<f64>,
306    pub ask_px_18: Option<f64>,
307    pub ask_sz_18: Option<f64>,
308    pub bid_px_19: Option<f64>,
309    pub bid_sz_19: Option<f64>,
310    pub ask_px_19: Option<f64>,
311    pub ask_sz_19: Option<f64>,
312    pub bid_px_20: Option<f64>,
313    pub bid_sz_20: Option<f64>,
314    pub ask_px_20: Option<f64>,
315    pub ask_sz_20: Option<f64>,
316    pub bid_px_21: Option<f64>,
317    pub bid_sz_21: Option<f64>,
318    pub ask_px_21: Option<f64>,
319    pub ask_sz_21: Option<f64>,
320    pub bid_px_22: Option<f64>,
321    pub bid_sz_22: Option<f64>,
322    pub ask_px_22: Option<f64>,
323    pub ask_sz_22: Option<f64>,
324    pub bid_px_23: Option<f64>,
325    pub bid_sz_23: Option<f64>,
326    pub ask_px_23: Option<f64>,
327    pub ask_sz_23: Option<f64>,
328    pub bid_px_24: Option<f64>,
329    pub bid_sz_24: Option<f64>,
330    pub ask_px_24: Option<f64>,
331    pub ask_sz_24: Option<f64>,
332}
333
334impl OrderbookL2Row {
335    /// Return the reconstructed top-25 bid levels in API order.
336    pub fn bids(&self) -> impl Iterator<Item = (f64, f64)> + '_ {
337        [
338            (self.bid_px_00, self.bid_sz_00),
339            (self.bid_px_01, self.bid_sz_01),
340            (self.bid_px_02, self.bid_sz_02),
341            (self.bid_px_03, self.bid_sz_03),
342            (self.bid_px_04, self.bid_sz_04),
343            (self.bid_px_05, self.bid_sz_05),
344            (self.bid_px_06, self.bid_sz_06),
345            (self.bid_px_07, self.bid_sz_07),
346            (self.bid_px_08, self.bid_sz_08),
347            (self.bid_px_09, self.bid_sz_09),
348            (self.bid_px_10, self.bid_sz_10),
349            (self.bid_px_11, self.bid_sz_11),
350            (self.bid_px_12, self.bid_sz_12),
351            (self.bid_px_13, self.bid_sz_13),
352            (self.bid_px_14, self.bid_sz_14),
353            (self.bid_px_15, self.bid_sz_15),
354            (self.bid_px_16, self.bid_sz_16),
355            (self.bid_px_17, self.bid_sz_17),
356            (self.bid_px_18, self.bid_sz_18),
357            (self.bid_px_19, self.bid_sz_19),
358            (self.bid_px_20, self.bid_sz_20),
359            (self.bid_px_21, self.bid_sz_21),
360            (self.bid_px_22, self.bid_sz_22),
361            (self.bid_px_23, self.bid_sz_23),
362            (self.bid_px_24, self.bid_sz_24),
363        ]
364        .into_iter()
365        .filter_map(|(price, quantity)| price.zip(quantity))
366        .filter(|(price, quantity)| {
367            price.is_finite() && *price > 0.0 && quantity.is_finite() && *quantity > 0.0
368        })
369    }
370
371    /// Return the reconstructed top-25 ask levels in API order.
372    pub fn asks(&self) -> impl Iterator<Item = (f64, f64)> + '_ {
373        [
374            (self.ask_px_00, self.ask_sz_00),
375            (self.ask_px_01, self.ask_sz_01),
376            (self.ask_px_02, self.ask_sz_02),
377            (self.ask_px_03, self.ask_sz_03),
378            (self.ask_px_04, self.ask_sz_04),
379            (self.ask_px_05, self.ask_sz_05),
380            (self.ask_px_06, self.ask_sz_06),
381            (self.ask_px_07, self.ask_sz_07),
382            (self.ask_px_08, self.ask_sz_08),
383            (self.ask_px_09, self.ask_sz_09),
384            (self.ask_px_10, self.ask_sz_10),
385            (self.ask_px_11, self.ask_sz_11),
386            (self.ask_px_12, self.ask_sz_12),
387            (self.ask_px_13, self.ask_sz_13),
388            (self.ask_px_14, self.ask_sz_14),
389            (self.ask_px_15, self.ask_sz_15),
390            (self.ask_px_16, self.ask_sz_16),
391            (self.ask_px_17, self.ask_sz_17),
392            (self.ask_px_18, self.ask_sz_18),
393            (self.ask_px_19, self.ask_sz_19),
394            (self.ask_px_20, self.ask_sz_20),
395            (self.ask_px_21, self.ask_sz_21),
396            (self.ask_px_22, self.ask_sz_22),
397            (self.ask_px_23, self.ask_sz_23),
398            (self.ask_px_24, self.ask_sz_24),
399        ]
400        .into_iter()
401        .filter_map(|(price, quantity)| price.zip(quantity))
402        .filter(|(price, quantity)| {
403            price.is_finite() && *price > 0.0 && quantity.is_finite() && *quantity > 0.0
404        })
405    }
406}
407
408/// One venue-published candle update from `/ohlcv`.
409#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
410pub struct OhlcvRow {
411    pub event_id: String,
412    pub source: String,
413    pub market: String,
414    pub collector_timestamp: i64,
415    pub source_capture_id: String,
416    pub schema_version: u32,
417    pub interval: String,
418    pub open_timestamp: i64,
419    pub open: f64,
420    pub high: f64,
421    pub low: f64,
422    pub close: f64,
423    #[serde(default)]
424    pub exchange_timestamp: Option<i64>,
425    #[serde(default)]
426    pub instrument: Option<String>,
427    #[serde(default)]
428    pub close_timestamp: Option<i64>,
429    #[serde(default)]
430    pub base_volume: Option<f64>,
431    #[serde(default)]
432    pub quote_volume: Option<f64>,
433    #[serde(default)]
434    pub trade_count: Option<u64>,
435    #[serde(default)]
436    pub is_closed: Option<bool>,
437}
438
439/// One pair-shaped intent observation from `/intents`.
440#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
441pub struct IntentRow {
442    pub event_id: String,
443    pub source: String,
444    pub market: String,
445    pub collector_timestamp: i64,
446    pub source_capture_id: String,
447    pub schema_version: u32,
448    #[serde(default)]
449    pub exchange_timestamp: Option<i64>,
450    #[serde(default)]
451    pub instrument: Option<String>,
452    #[serde(default)]
453    pub amount_kind: Option<String>,
454    #[serde(default)]
455    pub expires_at: Option<i64>,
456    #[serde(default)]
457    pub input_amount: Option<String>,
458    #[serde(default)]
459    pub input_asset_id: Option<String>,
460    #[serde(default)]
461    pub input_chain_id: Option<String>,
462    #[serde(default)]
463    pub intent_id: Option<String>,
464    #[serde(default)]
465    pub output_amount: Option<String>,
466    #[serde(default)]
467    pub output_asset_id: Option<String>,
468    #[serde(default)]
469    pub output_chain_id: Option<String>,
470    #[serde(default)]
471    pub quote_id: Option<String>,
472    #[serde(default)]
473    pub quoted_input_amount: Option<String>,
474    #[serde(default)]
475    pub quoted_output_amount: Option<String>,
476    #[serde(default)]
477    pub rfq_id: Option<String>,
478    #[serde(default)]
479    pub settled_at: Option<i64>,
480    #[serde(default)]
481    pub status: Option<String>,
482}
483
484/// One PropAMM quote point from `/quotes`.
485#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
486pub struct QuoteRow {
487    pub event_id: String,
488    pub source: String,
489    pub market: String,
490    pub instrument: String,
491    pub collector_timestamp: i64,
492    pub source_capture_id: String,
493    pub schema_version: u32,
494    pub observation_id: String,
495    pub input_asset_id: String,
496    pub input_chain_id: String,
497    pub input_amount: String,
498    pub input_decimals: u32,
499    pub output_asset_id: String,
500    pub output_chain_id: String,
501    pub output_amount: String,
502    pub output_decimals: u32,
503    pub amount_kind: String,
504    pub block_number: u64,
505    pub block_hash: String,
506    pub transaction_hash: String,
507    pub transaction_index: u64,
508    pub router: String,
509    #[serde(default)]
510    pub exchange_timestamp: Option<i64>,
511    #[serde(default)]
512    pub oracle: Option<String>,
513    #[serde(default)]
514    pub pool: Option<String>,
515}
516
517/// One flat row from `/trades`.
518#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
519pub struct TradeRow {
520    pub event_id: String,
521    pub source: String,
522    pub market: String,
523    pub collector_timestamp: i64,
524    pub source_capture_id: String,
525    pub schema_version: u32,
526    pub price: f64,
527    pub quantity: f64,
528    #[serde(default)]
529    pub exchange_timestamp: Option<i64>,
530    #[serde(default)]
531    pub instrument: Option<String>,
532    #[serde(default)]
533    pub liquidation: Option<bool>,
534    #[serde(default)]
535    pub maker: Option<String>,
536    #[serde(default)]
537    pub order_id: Option<String>,
538    #[serde(default)]
539    pub side: Option<String>,
540    #[serde(default)]
541    pub taker: Option<String>,
542}
543
544/// One partial flat row from `/options-ticker`.
545#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
546pub struct OptionTickerRow {
547    pub event_id: String,
548    pub source: String,
549    pub market: String,
550    pub instrument: String,
551    pub collector_timestamp: i64,
552    pub source_capture_id: String,
553    pub schema_version: u32,
554    #[serde(default)]
555    pub exchange_timestamp: Option<i64>,
556    #[serde(default)]
557    pub expiry_timestamp: Option<i64>,
558    #[serde(default)]
559    pub ask_iv: Option<String>,
560    #[serde(default)]
561    pub ask_price: Option<String>,
562    #[serde(default)]
563    pub ask_size: Option<String>,
564    #[serde(default)]
565    pub bid_iv: Option<String>,
566    #[serde(default)]
567    pub bid_price: Option<String>,
568    #[serde(default)]
569    pub bid_size: Option<String>,
570    #[serde(default)]
571    pub delta: Option<String>,
572    #[serde(default)]
573    pub forward_price: Option<String>,
574    #[serde(default)]
575    pub gamma: Option<String>,
576    #[serde(default)]
577    pub index_price: Option<String>,
578    #[serde(default)]
579    pub last_price: Option<String>,
580    #[serde(default)]
581    pub mark_iv: Option<String>,
582    #[serde(default)]
583    pub mark_price: Option<String>,
584    #[serde(default)]
585    pub open_interest: Option<String>,
586    #[serde(default)]
587    pub option_type: Option<String>,
588    #[serde(default)]
589    pub premium_currency: Option<String>,
590    #[serde(default)]
591    pub quantity_unit: Option<String>,
592    #[serde(default)]
593    pub rho: Option<String>,
594    #[serde(default)]
595    pub strike: Option<String>,
596    #[serde(default)]
597    pub theta: Option<String>,
598    #[serde(default)]
599    pub turnover_24h: Option<String>,
600    #[serde(default)]
601    pub underlying: Option<String>,
602    #[serde(default)]
603    pub underlying_price: Option<String>,
604    #[serde(default)]
605    pub vega: Option<String>,
606    #[serde(default)]
607    pub volume_24h: Option<String>,
608}
609
610/// One partial flat row from `/funding-rates`.
611#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
612pub struct FundingRateRow {
613    pub event_id: String,
614    pub source: String,
615    pub market: String,
616    pub collector_timestamp: i64,
617    pub source_capture_id: String,
618    pub schema_version: u32,
619    #[serde(default)]
620    pub exchange_timestamp: Option<i64>,
621    #[serde(default)]
622    pub funding_timestamp: Option<i64>,
623    #[serde(default)]
624    pub instrument: Option<String>,
625    #[serde(default)]
626    pub funding_rate: Option<String>,
627    #[serde(default)]
628    pub index_price: Option<String>,
629    #[serde(default)]
630    pub mark_price: Option<String>,
631    #[serde(default)]
632    pub open_interest: Option<String>,
633    #[serde(default)]
634    pub predicted_funding_rate: Option<String>,
635    #[serde(default)]
636    pub premium: Option<String>,
637}
638
639/// A typed flat row from the authenticated mixed `/events` stream.
640// Keep variant payloads public and unboxed so callers can construct and match them directly.
641#[allow(clippy::large_enum_variant)]
642#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
643#[serde(tag = "type", content = "data", rename_all = "snake_case")]
644pub enum MixedEventRow {
645    Trade(TradeRow),
646    L2Update(OrderbookL2Row),
647    FundingRate(FundingRateRow),
648    Intent(IntentRow),
649    Quote(QuoteRow),
650    OptionTicker(OptionTickerRow),
651    Ohlcv(OhlcvRow),
652}
653
654#[derive(Clone, Debug, PartialEq, Eq)]
655pub struct StreamQuery {
656    pub source: String,
657    pub markets: Vec<String>,
658    /// Optional exact venue-native instrument filter applied to each market.
659    /// `None` subscribes to the whole market (for options, the whole chain).
660    pub instrument: Option<String>,
661    pub include_buffer: bool,
662    pub materialize_orderbooks: bool,
663}
664
665impl Default for StreamQuery {
666    fn default() -> Self {
667        Self {
668            source: String::new(),
669            markets: Vec::new(),
670            instrument: None,
671            include_buffer: false,
672            materialize_orderbooks: true,
673        }
674    }
675}
676
677#[derive(Clone, Debug, PartialEq, Eq)]
678pub struct RawQuery {
679    pub source: String,
680    /// Exact recorded routing market. `None` includes every source market.
681    pub market: Option<String>,
682    /// Exact native channel. `None` includes every raw channel.
683    pub channel: Option<String>,
684    /// Inclusive lower bound. Omitted bounds use a seven-day window.
685    pub from: Option<TimeInput>,
686    /// Inclusive upper bound. Omitted bounds use a seven-day window.
687    pub to: Option<TimeInput>,
688    pub limit: usize,
689}
690
691/// Query for exact captures from one venue-native raw channel.
692/// `exchange` and `event` map to the API's `source` and `channel` filters.
693#[derive(Clone, Debug, PartialEq, Eq)]
694pub struct RawChannelQuery {
695    pub exchange: String,
696    pub event: String,
697    /// Optional exact recorded routing market within the channel.
698    pub market: Option<String>,
699    /// Inclusive collector time in Unix milliseconds.
700    pub start: i64,
701    /// Inclusive collector time in Unix milliseconds.
702    pub end: i64,
703}
704
705/// One capture from `GET /raw`.
706#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
707pub struct RawCaptureRow {
708    pub raw_table: String,
709    pub capture_id: String,
710    pub collector_timestamp: i64,
711    pub recorder_version: String,
712    pub ingested_at: i64,
713    pub additional_context: Value,
714    /// Exact upstream JSON text; intentionally left unparsed.
715    pub original_json: String,
716}
717
718#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
719pub enum OhlcvInterval {
720    #[serde(rename = "100ms")]
721    Ms100,
722    #[serde(rename = "1s")]
723    S1,
724    #[serde(rename = "10s")]
725    S10,
726    #[serde(rename = "1m")]
727    M1,
728    #[serde(rename = "5m")]
729    M5,
730    #[serde(rename = "15m")]
731    M15,
732    #[serde(rename = "1h")]
733    H1,
734}
735
736impl OhlcvInterval {
737    pub fn as_str(self) -> &'static str {
738        match self {
739            Self::Ms100 => "100ms",
740            Self::S1 => "1s",
741            Self::S10 => "10s",
742            Self::M1 => "1m",
743            Self::M5 => "5m",
744            Self::M15 => "15m",
745            Self::H1 => "1h",
746        }
747    }
748}
749
750#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
751pub struct CatalogResponse {
752    #[serde(rename = "updatedAt")]
753    pub updated_at: String,
754    pub markets: Vec<CatalogMarket>,
755    #[doc(hidden)]
756    #[serde(skip)]
757    pub legacy_shape: bool,
758}
759
760/// One venue-native option contract in the instrument catalog.
761#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
762pub struct OptionContract {
763    pub source: String,
764    pub market: String,
765    pub instrument: String,
766    pub status: String,
767    pub option_type: String,
768    pub underlying: String,
769    pub strike: String,
770    pub expiry_timestamp: i64,
771    #[serde(default)]
772    pub contract_size: Option<String>,
773    #[serde(default)]
774    pub exercise_style: Option<String>,
775    #[serde(default)]
776    pub premium_currency: Option<String>,
777    #[serde(default)]
778    pub quantity_unit: Option<String>,
779    #[serde(default)]
780    pub settlement_currency: Option<String>,
781    #[serde(default)]
782    pub statistics: Option<OptionContractStatistics>,
783}
784
785#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
786pub struct OptionContractStatistics {
787    pub source: String,
788    pub market: String,
789    #[serde(default)]
790    pub instrument: Option<String>,
791    pub fields: BTreeMap<String, ObservedStatistic>,
792}
793
794#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
795pub struct ObservedStatistic {
796    pub value: String,
797    pub observed_at: i64,
798    #[serde(default)]
799    pub exchange_timestamp: Option<i64>,
800    #[serde(default)]
801    pub unit: Option<String>,
802    #[serde(default)]
803    pub convention: Option<String>,
804}
805
806#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
807pub struct InstrumentsResponse {
808    #[serde(rename = "updatedAt")]
809    pub updated_at: String,
810    pub instruments: Vec<OptionContract>,
811}
812
813#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
814pub struct CatalogCount {
815    #[serde(rename = "updatedAt")]
816    pub updated_at: String,
817    pub sources: u64,
818    pub markets: u64,
819    pub by_source: BTreeMap<String, u64>,
820}
821
822#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
823pub struct CatalogAccess {
824    pub status: String,
825    pub public_cutoff_date: Option<String>,
826}
827
828#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
829pub struct CatalogInstrument {
830    pub base: Option<String>,
831    pub quote: Option<String>,
832    pub tick_size: Option<String>,
833    pub lot_size: Option<String>,
834    pub min_notional: Option<String>,
835}
836
837#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
838pub struct CatalogMarket {
839    pub source: String,
840    pub market: String,
841    pub symbol: String,
842    pub start: Option<String>,
843    pub end: Option<String>,
844    pub source_type: Option<String>,
845    pub categories: Option<Vec<String>>,
846    pub access: Option<CatalogAccess>,
847    pub instrument: CatalogInstrument,
848}
849
850#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
851pub struct LegacyStandardEvent {
852    pub timestamp: i64,
853    #[serde(default)]
854    pub source: String,
855    #[serde(default)]
856    pub market: String,
857    #[serde(default, rename = "type")]
858    pub event_type: String,
859    #[serde(default)]
860    pub data: Value,
861    #[serde(default, flatten)]
862    pub extra: BTreeMap<String, Value>,
863}
864
865#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
866pub struct StandardEventV2 {
867    pub collector_timestamp: i64,
868    pub collector_sequence: u64,
869    pub exchange_timestamp: Option<i64>,
870    pub exchange_sequence: Option<String>,
871    #[serde(default)]
872    pub source: String,
873    #[serde(default)]
874    pub market: String,
875    #[serde(default, rename = "type")]
876    pub event_type: String,
877    #[serde(default)]
878    pub data: Value,
879    #[serde(default, flatten)]
880    pub extra: BTreeMap<String, Value>,
881}
882
883#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
884#[serde(untagged)]
885pub enum StandardEvent {
886    Legacy(LegacyStandardEvent),
887    V2(StandardEventV2),
888}
889
890impl StandardEvent {
891    pub fn timestamp(&self) -> i64 {
892        match self {
893            Self::Legacy(event) => event.timestamp,
894            Self::V2(event) => event.collector_timestamp,
895        }
896    }
897
898    pub fn source(&self) -> &str {
899        match self {
900            Self::Legacy(event) => &event.source,
901            Self::V2(event) => &event.source,
902        }
903    }
904
905    pub fn market(&self) -> &str {
906        match self {
907            Self::Legacy(event) => &event.market,
908            Self::V2(event) => &event.market,
909        }
910    }
911
912    pub fn event_type(&self) -> &str {
913        match self {
914            Self::Legacy(event) => &event.event_type,
915            Self::V2(event) => &event.event_type,
916        }
917    }
918
919    /// Exact venue-native instrument carried by the event envelope, when one
920    /// is present. For options, `market()` is the normalized underlying and
921    /// this value identifies the contract.
922    pub fn instrument(&self) -> Option<&str> {
923        self.extra().get("instrument").and_then(Value::as_str)
924    }
925
926    pub fn data(&self) -> &Value {
927        match self {
928            Self::Legacy(event) => &event.data,
929            Self::V2(event) => &event.data,
930        }
931    }
932
933    pub fn data_mut(&mut self) -> &mut Value {
934        match self {
935            Self::Legacy(event) => &mut event.data,
936            Self::V2(event) => &mut event.data,
937        }
938    }
939
940    pub(crate) fn source_mut(&mut self) -> &mut String {
941        match self {
942            Self::Legacy(event) => &mut event.source,
943            Self::V2(event) => &mut event.source,
944        }
945    }
946
947    pub(crate) fn market_mut(&mut self) -> &mut String {
948        match self {
949            Self::Legacy(event) => &mut event.market,
950            Self::V2(event) => &mut event.market,
951        }
952    }
953
954    pub(crate) fn event_type_mut(&mut self) -> &mut String {
955        match self {
956            Self::Legacy(event) => &mut event.event_type,
957            Self::V2(event) => &mut event.event_type,
958        }
959    }
960
961    #[doc(hidden)]
962    pub fn extra(&self) -> &BTreeMap<String, Value> {
963        match self {
964            Self::Legacy(event) => &event.extra,
965            Self::V2(event) => &event.extra,
966        }
967    }
968
969    pub(crate) fn extra_mut(&mut self) -> &mut BTreeMap<String, Value> {
970        match self {
971            Self::Legacy(event) => &mut event.extra,
972            Self::V2(event) => &mut event.extra,
973        }
974    }
975}
976
977#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
978pub struct LegacyTradeData {
979    pub price: f64,
980    pub quantity: f64,
981    #[serde(default)]
982    pub side: String,
983    #[serde(default, skip_serializing_if = "Option::is_none")]
984    pub maker: Option<String>,
985    #[serde(default, skip_serializing_if = "Option::is_none")]
986    pub taker: Option<String>,
987    #[serde(flatten)]
988    pub extra: BTreeMap<String, Value>,
989}
990
991#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
992pub struct TradeDataV2 {
993    pub order_id: Option<String>,
994    pub price: f64,
995    pub quantity: f64,
996    pub side: Option<String>,
997    #[serde(default, skip_serializing_if = "Option::is_none")]
998    pub maker: Option<String>,
999    #[serde(default, skip_serializing_if = "Option::is_none")]
1000    pub taker: Option<String>,
1001    #[serde(flatten)]
1002    pub extra: BTreeMap<String, Value>,
1003}
1004
1005#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
1006pub struct LegacyTradeEvent {
1007    pub timestamp: i64,
1008    pub source: String,
1009    pub market: String,
1010    #[serde(rename = "type")]
1011    pub event_type: String,
1012    pub data: LegacyTradeData,
1013}
1014
1015#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
1016pub struct TradeEventV2 {
1017    pub collector_timestamp: i64,
1018    pub collector_sequence: u64,
1019    pub exchange_timestamp: Option<i64>,
1020    pub exchange_sequence: Option<String>,
1021    pub source: String,
1022    pub market: String,
1023    #[serde(rename = "type")]
1024    pub event_type: String,
1025    pub data: TradeDataV2,
1026}
1027
1028#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
1029#[serde(untagged)]
1030pub enum TradeEvent {
1031    Legacy(LegacyTradeEvent),
1032    V2(TradeEventV2),
1033}
1034
1035impl TradeEvent {
1036    pub fn is_v2(&self) -> bool {
1037        matches!(self, Self::V2(_))
1038    }
1039
1040    pub fn timestamp(&self) -> i64 {
1041        match self {
1042            Self::Legacy(event) => event.timestamp,
1043            Self::V2(event) => event.collector_timestamp,
1044        }
1045    }
1046
1047    pub fn price(&self) -> f64 {
1048        match self {
1049            Self::Legacy(event) => event.data.price,
1050            Self::V2(event) => event.data.price,
1051        }
1052    }
1053
1054    pub fn quantity(&self) -> f64 {
1055        match self {
1056            Self::Legacy(event) => event.data.quantity,
1057            Self::V2(event) => event.data.quantity,
1058        }
1059    }
1060
1061    pub fn source(&self) -> &str {
1062        match self {
1063            Self::Legacy(event) => &event.source,
1064            Self::V2(event) => &event.source,
1065        }
1066    }
1067
1068    pub fn market(&self) -> &str {
1069        match self {
1070            Self::Legacy(event) => &event.market,
1071            Self::V2(event) => &event.market,
1072        }
1073    }
1074
1075    pub fn side(&self) -> Option<&str> {
1076        match self {
1077            Self::Legacy(event) => {
1078                (!event.data.side.is_empty()).then_some(event.data.side.as_str())
1079            }
1080            Self::V2(event) => event.data.side.as_deref(),
1081        }
1082    }
1083
1084    pub fn order_id(&self) -> Option<&str> {
1085        match self {
1086            Self::Legacy(event) => event.data.extra.get("order_id").and_then(Value::as_str),
1087            Self::V2(event) => event.data.order_id.as_deref(),
1088        }
1089    }
1090
1091    pub fn maker(&self) -> Option<&str> {
1092        match self {
1093            Self::Legacy(event) => event.data.maker.as_deref(),
1094            Self::V2(event) => event.data.maker.as_deref(),
1095        }
1096    }
1097
1098    pub fn taker(&self) -> Option<&str> {
1099        match self {
1100            Self::Legacy(event) => event.data.taker.as_deref(),
1101            Self::V2(event) => event.data.taker.as_deref(),
1102        }
1103    }
1104
1105    pub fn extra(&self) -> &BTreeMap<String, Value> {
1106        match self {
1107            Self::Legacy(event) => &event.data.extra,
1108            Self::V2(event) => &event.data.extra,
1109        }
1110    }
1111}
1112
1113/// Whether an intent fixes its inputs or outputs.
1114#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
1115#[serde(rename_all = "snake_case")]
1116pub enum AmountKind {
1117    ExactInput,
1118    ExactOutput,
1119}
1120
1121/// Canonical execution lifecycle for an intent.
1122#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
1123#[serde(rename_all = "snake_case")]
1124pub enum IntentStatus {
1125    Submitted,
1126    Open,
1127    PartiallyFilled,
1128    Executing,
1129    Filled,
1130    Settled,
1131    Cancelled,
1132    Expired,
1133    Failed,
1134    Unknown,
1135}
1136
1137/// One asset and its economically binding amount.
1138#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1139pub struct AssetAmount {
1140    pub asset_id: String,
1141    #[serde(default, skip_serializing_if = "Option::is_none")]
1142    pub chain_id: Option<String>,
1143    #[serde(default, skip_serializing_if = "Option::is_none")]
1144    pub amount: Option<String>,
1145    #[serde(default, skip_serializing_if = "Option::is_none")]
1146    pub recipient: Option<String>,
1147    #[serde(flatten)]
1148    pub extra: BTreeMap<String, Value>,
1149}
1150
1151/// A solver or venue response to an RFQ.
1152#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1153pub struct IntentQuote {
1154    pub quote_id: String,
1155    #[serde(default)]
1156    pub response: Vec<AssetAmount>,
1157    #[serde(flatten)]
1158    pub extra: BTreeMap<String, Value>,
1159}
1160
1161/// A chain transaction that executes or settles an intent.
1162#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1163pub struct SettlementTransaction {
1164    #[serde(default, skip_serializing_if = "Option::is_none")]
1165    pub chain_id: Option<String>,
1166    pub transaction_hash: String,
1167    #[serde(flatten)]
1168    pub extra: BTreeMap<String, Value>,
1169}
1170
1171/// Venue-independent projection of an RFQ, quote, or executable intent.
1172#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
1173pub struct IntentData {
1174    #[serde(default, skip_serializing_if = "Option::is_none")]
1175    pub rfq_id: Option<String>,
1176    #[serde(default, skip_serializing_if = "Option::is_none")]
1177    pub intent_id: Option<String>,
1178    #[serde(default, skip_serializing_if = "Option::is_none")]
1179    pub requester: Option<String>,
1180    #[serde(default, skip_serializing_if = "Option::is_none")]
1181    pub signer: Option<String>,
1182    #[serde(default)]
1183    pub inputs: Vec<AssetAmount>,
1184    #[serde(default)]
1185    pub outputs: Vec<AssetAmount>,
1186    #[serde(default, skip_serializing_if = "Option::is_none")]
1187    pub amount_kind: Option<AmountKind>,
1188    #[serde(default, skip_serializing_if = "Option::is_none")]
1189    pub expires_at: Option<i64>,
1190    #[serde(default, skip_serializing_if = "Option::is_none")]
1191    pub quote: Option<IntentQuote>,
1192    #[serde(default, skip_serializing_if = "Option::is_none")]
1193    pub status: Option<IntentStatus>,
1194    #[serde(default)]
1195    pub transactions: Vec<SettlementTransaction>,
1196    #[serde(default, skip_serializing_if = "Option::is_none")]
1197    pub settled_at: Option<i64>,
1198    #[serde(flatten)]
1199    pub extra: BTreeMap<String, Value>,
1200}
1201
1202#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1203pub struct LegacyIntentEvent {
1204    pub timestamp: i64,
1205    pub source: String,
1206    pub market: String,
1207    #[serde(rename = "type")]
1208    pub event_type: String,
1209    pub data: IntentData,
1210    #[serde(default, skip_serializing_if = "Option::is_none")]
1211    pub raw: Option<Value>,
1212}
1213
1214#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1215pub struct IntentEventV2 {
1216    pub collector_timestamp: i64,
1217    pub collector_sequence: u64,
1218    pub exchange_timestamp: Option<i64>,
1219    pub exchange_sequence: Option<String>,
1220    pub source: String,
1221    pub market: String,
1222    #[serde(rename = "type")]
1223    pub event_type: String,
1224    pub data: IntentData,
1225    #[serde(default, skip_serializing_if = "Option::is_none")]
1226    pub raw: Option<Value>,
1227}
1228
1229#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1230#[serde(untagged)]
1231pub enum IntentEvent {
1232    Legacy(LegacyIntentEvent),
1233    V2(IntentEventV2),
1234}
1235
1236impl IntentEvent {
1237    pub fn timestamp(&self) -> i64 {
1238        match self {
1239            Self::Legacy(event) => event.timestamp,
1240            Self::V2(event) => event.collector_timestamp,
1241        }
1242    }
1243
1244    pub fn source(&self) -> &str {
1245        match self {
1246            Self::Legacy(event) => &event.source,
1247            Self::V2(event) => &event.source,
1248        }
1249    }
1250
1251    pub fn market(&self) -> &str {
1252        match self {
1253            Self::Legacy(event) => &event.market,
1254            Self::V2(event) => &event.market,
1255        }
1256    }
1257
1258    pub fn data(&self) -> &IntentData {
1259        match self {
1260            Self::Legacy(event) => &event.data,
1261            Self::V2(event) => &event.data,
1262        }
1263    }
1264
1265    /// Exact upstream JSON token associated with this observation, when stored.
1266    pub fn raw(&self) -> Option<&Value> {
1267        match self {
1268            Self::Legacy(event) => event.raw.as_ref(),
1269            Self::V2(event) => event.raw.as_ref(),
1270        }
1271    }
1272}
1273
1274#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
1275pub struct OptionGreeks {
1276    #[serde(default, skip_serializing_if = "Option::is_none")]
1277    pub delta: Option<String>,
1278    #[serde(default, skip_serializing_if = "Option::is_none")]
1279    pub gamma: Option<String>,
1280    #[serde(default, skip_serializing_if = "Option::is_none")]
1281    pub vega: Option<String>,
1282    #[serde(default, skip_serializing_if = "Option::is_none")]
1283    pub theta: Option<String>,
1284    #[serde(default, skip_serializing_if = "Option::is_none")]
1285    pub rho: Option<String>,
1286}
1287
1288#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
1289pub struct OptionTickerData {
1290    #[serde(default, skip_serializing_if = "Option::is_none")]
1291    pub underlying: Option<String>,
1292    #[serde(default, skip_serializing_if = "Option::is_none")]
1293    pub strike: Option<String>,
1294    #[serde(default, skip_serializing_if = "Option::is_none")]
1295    pub expiry_timestamp: Option<i64>,
1296    #[serde(default, skip_serializing_if = "Option::is_none")]
1297    pub option_type: Option<String>,
1298    #[serde(default, skip_serializing_if = "Option::is_none")]
1299    pub mark_price: Option<String>,
1300    #[serde(default, skip_serializing_if = "Option::is_none")]
1301    pub bid_price: Option<String>,
1302    #[serde(default, skip_serializing_if = "Option::is_none")]
1303    pub bid_size: Option<String>,
1304    #[serde(default, skip_serializing_if = "Option::is_none")]
1305    pub ask_price: Option<String>,
1306    #[serde(default, skip_serializing_if = "Option::is_none")]
1307    pub ask_size: Option<String>,
1308    #[serde(default, skip_serializing_if = "Option::is_none")]
1309    pub last_price: Option<String>,
1310    #[serde(default, skip_serializing_if = "Option::is_none")]
1311    pub index_price: Option<String>,
1312    #[serde(default, skip_serializing_if = "Option::is_none")]
1313    pub underlying_price: Option<String>,
1314    #[serde(default, skip_serializing_if = "Option::is_none")]
1315    pub forward_price: Option<String>,
1316    #[serde(default, skip_serializing_if = "Option::is_none")]
1317    pub mark_iv: Option<String>,
1318    #[serde(default, skip_serializing_if = "Option::is_none")]
1319    pub bid_iv: Option<String>,
1320    #[serde(default, skip_serializing_if = "Option::is_none")]
1321    pub ask_iv: Option<String>,
1322    #[serde(default, skip_serializing_if = "Option::is_none")]
1323    pub open_interest: Option<String>,
1324    #[serde(default, skip_serializing_if = "Option::is_none")]
1325    pub volume_24h: Option<String>,
1326    #[serde(default, skip_serializing_if = "Option::is_none")]
1327    pub turnover_24h: Option<String>,
1328    #[serde(default, skip_serializing_if = "Option::is_none")]
1329    pub premium_currency: Option<String>,
1330    #[serde(default, skip_serializing_if = "Option::is_none")]
1331    pub quantity_unit: Option<String>,
1332    #[serde(default, skip_serializing_if = "option_greeks_are_empty")]
1333    pub greeks: OptionGreeks,
1334    #[serde(flatten)]
1335    pub extra: BTreeMap<String, Value>,
1336}
1337
1338fn option_greeks_are_empty(greeks: &OptionGreeks) -> bool {
1339    greeks.delta.is_none()
1340        && greeks.gamma.is_none()
1341        && greeks.vega.is_none()
1342        && greeks.theta.is_none()
1343        && greeks.rho.is_none()
1344}
1345
1346#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1347pub struct LegacyOptionTickerEvent {
1348    pub timestamp: i64,
1349    pub source: String,
1350    pub market: String,
1351    pub instrument: String,
1352    #[serde(rename = "type")]
1353    pub event_type: String,
1354    pub data: OptionTickerData,
1355}
1356
1357#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1358pub struct OptionTickerEventV2 {
1359    pub collector_timestamp: i64,
1360    pub collector_sequence: u64,
1361    pub exchange_timestamp: Option<i64>,
1362    pub exchange_sequence: Option<String>,
1363    pub source: String,
1364    pub market: String,
1365    pub instrument: String,
1366    #[serde(rename = "type")]
1367    pub event_type: String,
1368    pub data: OptionTickerData,
1369}
1370
1371#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1372#[serde(untagged)]
1373pub enum OptionTickerEvent {
1374    Legacy(LegacyOptionTickerEvent),
1375    V2(OptionTickerEventV2),
1376}
1377
1378impl OptionTickerEvent {
1379    pub fn timestamp(&self) -> i64 {
1380        match self {
1381            Self::Legacy(event) => event.timestamp,
1382            Self::V2(event) => event.collector_timestamp,
1383        }
1384    }
1385
1386    pub fn source(&self) -> &str {
1387        match self {
1388            Self::Legacy(event) => &event.source,
1389            Self::V2(event) => &event.source,
1390        }
1391    }
1392
1393    pub fn market(&self) -> &str {
1394        match self {
1395            Self::Legacy(event) => &event.market,
1396            Self::V2(event) => &event.market,
1397        }
1398    }
1399
1400    pub fn instrument(&self) -> &str {
1401        match self {
1402            Self::Legacy(event) => &event.instrument,
1403            Self::V2(event) => &event.instrument,
1404        }
1405    }
1406
1407    pub fn data(&self) -> &OptionTickerData {
1408        match self {
1409            Self::Legacy(event) => &event.data,
1410            Self::V2(event) => &event.data,
1411        }
1412    }
1413}
1414
1415#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
1416pub struct PerpetualTickerData {
1417    #[serde(default, skip_serializing_if = "Option::is_none")]
1418    pub last_price: Option<String>,
1419    #[serde(default, skip_serializing_if = "Option::is_none")]
1420    pub mark_price: Option<String>,
1421    #[serde(default, skip_serializing_if = "Option::is_none")]
1422    pub index_price: Option<String>,
1423    #[serde(default, skip_serializing_if = "Option::is_none")]
1424    pub oracle_price: Option<String>,
1425    #[serde(default, skip_serializing_if = "Option::is_none")]
1426    pub mid_price: Option<String>,
1427    #[serde(default, skip_serializing_if = "Option::is_none")]
1428    pub open_interest: Option<String>,
1429    #[serde(default, skip_serializing_if = "Option::is_none")]
1430    pub funding_rate: Option<String>,
1431    #[serde(default, skip_serializing_if = "Option::is_none")]
1432    pub funding_timestamp: Option<i64>,
1433    #[serde(default, skip_serializing_if = "Option::is_none")]
1434    pub predicted_funding_rate: Option<String>,
1435    #[serde(default, skip_serializing_if = "Option::is_none")]
1436    pub premium: Option<String>,
1437    #[serde(flatten)]
1438    pub extra: BTreeMap<String, Value>,
1439}
1440
1441impl PerpetualTickerData {
1442    pub fn is_empty(&self) -> bool {
1443        self.last_price.is_none()
1444            && self.mark_price.is_none()
1445            && self.index_price.is_none()
1446            && self.oracle_price.is_none()
1447            && self.mid_price.is_none()
1448            && self.open_interest.is_none()
1449            && self.funding_rate.is_none()
1450            && self.funding_timestamp.is_none()
1451            && self.predicted_funding_rate.is_none()
1452            && self.premium.is_none()
1453    }
1454}
1455
1456#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1457pub struct LegacyPerpetualTickerEvent {
1458    pub timestamp: i64,
1459    pub source: String,
1460    pub market: String,
1461    #[serde(rename = "type")]
1462    pub event_type: String,
1463    pub data: PerpetualTickerData,
1464}
1465
1466#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1467pub struct PerpetualTickerEventV2 {
1468    pub collector_timestamp: i64,
1469    pub collector_sequence: u64,
1470    pub exchange_timestamp: Option<i64>,
1471    pub exchange_sequence: Option<String>,
1472    pub source: String,
1473    pub market: String,
1474    #[serde(rename = "type")]
1475    pub event_type: String,
1476    pub data: PerpetualTickerData,
1477}
1478
1479#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1480#[serde(untagged)]
1481pub enum PerpetualTickerEvent {
1482    Legacy(LegacyPerpetualTickerEvent),
1483    V2(PerpetualTickerEventV2),
1484}
1485
1486impl PerpetualTickerEvent {
1487    pub fn timestamp(&self) -> i64 {
1488        match self {
1489            Self::Legacy(event) => event.timestamp,
1490            Self::V2(event) => event.collector_timestamp,
1491        }
1492    }
1493
1494    pub fn source(&self) -> &str {
1495        match self {
1496            Self::Legacy(event) => &event.source,
1497            Self::V2(event) => &event.source,
1498        }
1499    }
1500
1501    pub fn market(&self) -> &str {
1502        match self {
1503            Self::Legacy(event) => &event.market,
1504            Self::V2(event) => &event.market,
1505        }
1506    }
1507
1508    pub fn data(&self) -> &PerpetualTickerData {
1509        match self {
1510            Self::Legacy(event) => &event.data,
1511            Self::V2(event) => &event.data,
1512        }
1513    }
1514}
1515
1516pub type HistoricalStream<T> = Pin<Box<dyn Stream<Item = Result<T, PolarisError>> + Send>>;
1517pub type RealtimeStream = Pin<Box<dyn Stream<Item = Result<StandardEvent, PolarisError>> + Send>>;
1518
1519// PropAMM quote-ladder types
1520#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1521pub struct PropammQuote {
1522    pub amount_in: String,
1523    pub amount_out: String,
1524}
1525
1526#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1527pub struct PropammQuoteLadderValues {
1528    pub event_id: String,
1529    pub chain_id: u64,
1530    pub block_number: u64,
1531    pub block_hash: String,
1532    pub parent_hash: String,
1533    pub transaction_hash: String,
1534    pub transaction_index: u64,
1535    pub router: String,
1536    pub oracle: Option<String>,
1537    #[serde(default, skip_serializing_if = "Option::is_none")]
1538    pub pool: Option<String>,
1539    pub token_in: String,
1540    pub token_out: String,
1541    pub token_in_decimals: u8,
1542    pub token_out_decimals: u8,
1543    pub quotes: Vec<PropammQuote>,
1544}
1545
1546#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1547pub struct PropammQuoteLadderData {
1548    #[serde(rename = "series")]
1549    pub series_name: String,
1550    pub values: PropammQuoteLadderValues,
1551}
1552
1553#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1554pub struct PropammQuoteLadderEvent {
1555    pub collector_timestamp: i64,
1556    pub collector_sequence: u64,
1557    pub exchange_timestamp: Option<i64>,
1558    pub exchange_sequence: Option<String>,
1559    pub source: String,
1560    pub market: String,
1561    #[serde(rename = "type")]
1562    pub event_type: String,
1563    pub data: PropammQuoteLadderData,
1564}
1565
1566impl PropammQuoteLadderEvent {
1567    pub fn timestamp(&self) -> i64 {
1568        self.collector_timestamp
1569    }
1570
1571    pub fn source(&self) -> &str {
1572        &self.source
1573    }
1574
1575    pub fn market(&self) -> &str {
1576        &self.market
1577    }
1578
1579    pub fn data(&self) -> &PropammQuoteLadderData {
1580        &self.data
1581    }
1582}
1583
1584// Orderbook-related types
1585#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
1586pub struct OrderbookLevel {
1587    pub price: f64,
1588    pub quantity: f64,
1589}
1590
1591#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
1592pub struct LegacyOrderbookEvent {
1593    pub timestamp: i64,
1594    pub source: String,
1595    pub market: String,
1596    #[serde(rename = "type")]
1597    pub event_type: String,
1598    pub data: OrderbookData,
1599}
1600
1601#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
1602pub struct OrderbookDataV2 {
1603    pub is_snapshot: bool,
1604    pub bids: Vec<OrderbookLevel>,
1605    pub asks: Vec<OrderbookLevel>,
1606    #[serde(flatten)]
1607    pub extra: BTreeMap<String, Value>,
1608}
1609
1610#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
1611pub struct OrderbookEventV2 {
1612    pub collector_timestamp: i64,
1613    pub collector_sequence: u64,
1614    pub exchange_timestamp: Option<i64>,
1615    pub exchange_sequence: Option<String>,
1616    pub source: String,
1617    pub market: String,
1618    #[serde(rename = "type")]
1619    pub event_type: String,
1620    pub data: OrderbookDataV2,
1621}
1622
1623#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
1624#[serde(untagged)]
1625pub enum OrderbookEvent {
1626    Legacy(LegacyOrderbookEvent),
1627    V2(OrderbookEventV2),
1628}
1629
1630#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
1631pub struct OrderbookData {
1632    pub bids: Vec<OrderbookLevel>,
1633    pub asks: Vec<OrderbookLevel>,
1634    #[serde(flatten)]
1635    pub extra: BTreeMap<String, Value>,
1636}
1637
1638#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
1639pub struct BboQuote {
1640    pub timestamp: i64,
1641    pub bid_price: f64,
1642    pub bid_quantity: f64,
1643    pub ask_price: f64,
1644    pub ask_quantity: f64,
1645}
1646
1647// Point series types
1648#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
1649pub struct LegacyPointSeriesEvent {
1650    pub timestamp: i64,
1651    pub source: String,
1652    pub market: String,
1653    #[serde(rename = "type")]
1654    pub event_type: String,
1655    pub data: PointSeriesData,
1656}
1657
1658#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
1659pub struct PointSeriesEventV2 {
1660    pub collector_timestamp: i64,
1661    pub collector_sequence: u64,
1662    pub exchange_timestamp: Option<i64>,
1663    pub exchange_sequence: Option<String>,
1664    pub source: String,
1665    pub market: String,
1666    #[serde(rename = "type")]
1667    pub event_type: String,
1668    pub data: PointSeriesData,
1669}
1670
1671#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
1672#[serde(untagged)]
1673pub enum PointSeriesEvent {
1674    Legacy(LegacyPointSeriesEvent),
1675    V2(PointSeriesEventV2),
1676}
1677
1678impl PointSeriesEvent {
1679    pub fn timestamp(&self) -> i64 {
1680        match self {
1681            Self::Legacy(event) => event.timestamp,
1682            Self::V2(event) => event.collector_timestamp,
1683        }
1684    }
1685
1686    pub fn source(&self) -> &str {
1687        match self {
1688            Self::Legacy(event) => &event.source,
1689            Self::V2(event) => &event.source,
1690        }
1691    }
1692
1693    pub fn market(&self) -> &str {
1694        match self {
1695            Self::Legacy(event) => &event.market,
1696            Self::V2(event) => &event.market,
1697        }
1698    }
1699
1700    pub fn data(&self) -> &PointSeriesData {
1701        match self {
1702            Self::Legacy(event) => &event.data,
1703            Self::V2(event) => &event.data,
1704        }
1705    }
1706}
1707
1708#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
1709pub struct PointSeriesData {
1710    #[serde(rename = "series")]
1711    pub series_name: String,
1712    #[serde(deserialize_with = "deserialize_f64_from_number_or_string")]
1713    pub value: f64,
1714    #[serde(flatten)]
1715    pub extra: BTreeMap<String, Value>,
1716}
1717
1718fn deserialize_f64_from_number_or_string<'de, D>(deserializer: D) -> Result<f64, D::Error>
1719where
1720    D: serde::Deserializer<'de>,
1721{
1722    let value = Value::deserialize(deserializer)?;
1723    value
1724        .as_f64()
1725        .or_else(|| value.as_str().and_then(|text| text.parse().ok()))
1726        .ok_or_else(|| serde::de::Error::custom("expected a number or numeric string"))
1727}
1728
1729// Depth metrics
1730#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
1731pub struct DepthMetricsRow {
1732    pub timestamp: i64,
1733    pub bid_price: f64,
1734    pub ask_price: f64,
1735    pub mid_price: f64,
1736    pub bid_ask_spread: f64,
1737    pub bid_ask_spread_bps: Option<f64>,
1738    pub depth_pct: f64,
1739    pub bid_depth_notional: f64,
1740    pub ask_depth_notional: f64,
1741    pub depth_imbalance: Option<f64>,
1742    pub slippage_notional: f64,
1743    pub target_base_quantity: Option<f64>,
1744    pub buy_average_price: Option<f64>,
1745    pub sell_average_price: Option<f64>,
1746    pub buy_slippage: Option<f64>,
1747    pub sell_slippage: Option<f64>,
1748    pub buy_slippage_bps: Option<f64>,
1749    pub sell_slippage_bps: Option<f64>,
1750}