1use std::{collections::HashMap, ops::Bound};
19
20use anyhow::Context;
21use nautilus_common::{
22 live::sender::EventSender,
23 messages::{
24 DataEvent,
25 data::{
26 DataResponse, InstrumentResponse, InstrumentsResponse, RequestInstrument,
27 RequestInstruments,
28 },
29 },
30};
31use nautilus_core::{
32 UnixNanos,
33 datetime::{NANOSECONDS_IN_SECOND, try_datetime_to_unix_nanos},
34 params::Params,
35 time::AtomicTime,
36};
37use nautilus_model::instruments::{BinaryOption, InstrumentAny};
38
39use crate::{
40 common::{
41 consts::{KALSHI_CLIENT_ID, KALSHI_VENUE},
42 enums::{MarketStatus, MarketStatusFilter, MveFilter, MveHistoricalFilter},
43 parse::{parse_instrument_id, parse_ticker},
44 },
45 http::{
46 client::KalshiHttpClient,
47 error::KalshiHttpError,
48 models::{Event, Field, Market, Series},
49 parse::{parse_instrument, supported_market},
50 query::{EventQuery, HistoricalMarketsQuery, MarketsQuery},
51 },
52};
53
54const STATUS_FILTERS: &[(MarketStatusFilter, &[MarketStatus])] = &[
55 (MarketStatusFilter::Unopened, &[MarketStatus::Initialized]),
56 (MarketStatusFilter::Open, &[MarketStatus::Active]),
57 (MarketStatusFilter::Paused, &[MarketStatus::Inactive]),
58 (
59 MarketStatusFilter::Closed,
60 &[
61 MarketStatus::Closed,
62 MarketStatus::Determined,
63 MarketStatus::Disputed,
64 MarketStatus::Amended,
65 ],
66 ),
67 (MarketStatusFilter::Settled, &[MarketStatus::Finalized]),
68];
69
70#[derive(Debug)]
77pub struct KalshiInstrumentProvider {
78 pub(crate) http: KalshiHttpClient,
79 pub(crate) clock: &'static AtomicTime,
80 sender: EventSender<DataEvent>,
81}
82
83impl KalshiInstrumentProvider {
84 pub fn new(
86 http: KalshiHttpClient,
87 clock: &'static AtomicTime,
88 sender: EventSender<DataEvent>,
89 ) -> Self {
90 Self {
91 http,
92 clock,
93 sender,
94 }
95 }
96
97 pub async fn request_instrument(&self, request: RequestInstrument) -> anyhow::Result<()> {
103 let instrument = self.load_instrument(&request).await?;
104 self.respond_instrument(request, instrument)
105 }
106
107 pub(crate) fn respond_instrument(
108 &self,
109 request: RequestInstrument,
110 instrument: BinaryOption,
111 ) -> anyhow::Result<()> {
112 let (start, end) = request_bounds(request.start, request.end)?;
113
114 let response = InstrumentResponse::new(
115 request.request_id,
116 request.client_id.unwrap_or(*KALSHI_CLIENT_ID),
117 request.single_instrument_id()?,
118 InstrumentAny::BinaryOption(instrument),
119 start,
120 end,
121 self.clock.get_time_ns(),
122 request.params,
123 );
124
125 self.sender
126 .send(DataEvent::Response(DataResponse::Instrument(Box::new(
127 response,
128 ))))
129 .map_err(|_| anyhow::anyhow!("instrument response receiver closed"))?;
130 Ok(())
131 }
132
133 pub async fn request_instruments(&self, request: RequestInstruments) -> anyhow::Result<()> {
140 let instruments = self.load_instruments(&request).await?;
141 self.respond_instruments(request, instruments)
142 }
143
144 pub(crate) fn respond_instruments(
145 &self,
146 request: RequestInstruments,
147 instruments: Vec<InstrumentAny>,
148 ) -> anyhow::Result<()> {
149 let (start, end) = request_bounds(request.start, request.end)?;
150
151 let response = InstrumentsResponse::new(
152 request.request_id,
153 request.client_id.unwrap_or(*KALSHI_CLIENT_ID),
154 *KALSHI_VENUE,
155 instruments,
156 start,
157 end,
158 self.clock.get_time_ns(),
159 request.params,
160 );
161
162 self.sender
163 .send(DataEvent::Response(DataResponse::Instruments(response)))
164 .map_err(|_| anyhow::anyhow!("instruments response receiver closed"))?;
165 Ok(())
166 }
167
168 pub(crate) async fn load_instruments(
169 &self,
170 request: &RequestInstruments,
171 ) -> anyhow::Result<Vec<InstrumentAny>> {
172 anyhow::ensure!(
173 request.venue.is_none_or(|v| v == *KALSHI_VENUE),
174 "instrument request venue must be KALSHI"
175 );
176 let selection = Selection::new(request.params.as_ref())?;
177 let (start, end) = request_bounds(request.start, request.end)?;
178
179 let pages = if selection.historical {
180 let mut query = HistoricalMarketsQuery {
181 limit: selection.query.limit,
182 cursor: selection.query.cursor.clone(),
183 ..Default::default()
184 };
185
186 match (
187 &selection.query.tickers,
188 &selection.query.event_ticker,
189 &selection.query.series_ticker,
190 ) {
191 (Some(tickers), _, _) => query.tickers = Some(tickers.clone()),
192 (_, Some(event), _) => query.event_ticker = Some(event.clone()),
193 (_, _, Some(series)) => query.series_ticker = Some(series.clone()),
194 _ => query.mve_filter = Some(MveHistoricalFilter::Exclude),
195 }
196
197 self.http
198 .get_all_historical_markets(query, selection.max_pages)
199 .await?
200 } else {
201 self.http
202 .get_all_markets(selection.query.clone(), selection.max_pages)
203 .await?
204 };
205
206 anyhow::ensure!(pages.complete, "instrument discovery page budget exhausted");
207 let mut events: HashMap<String, Event> = HashMap::new();
208 let mut series: HashMap<String, Series> = HashMap::new();
209 let mut instruments = Vec::new();
210
211 for market in pages.records {
212 if !events.contains_key(&market.event_ticker) {
213 let event = self
214 .http
215 .get_event(
216 &market.event_ticker,
217 &EventQuery {
218 exclude_markets: Some(true),
219 ..Default::default()
220 },
221 )
222 .await?
223 .event;
224
225 anyhow::ensure!(
226 event.event_ticker == market.event_ticker,
227 "requested event identity mismatch"
228 );
229 events.insert(market.event_ticker.clone(), event);
230 }
231
232 let event = &events[&market.event_ticker];
233 if !selection.matches(&market, event) || !supported_market(&market, event) {
234 continue;
235 }
236
237 if !series.contains_key(&event.series_ticker) {
238 let definition = self.http.get_series(&event.series_ticker).await?.series;
239 series.insert(event.series_ticker.clone(), definition);
240 }
241
242 let instrument = Self::parse(
243 &market,
244 event,
245 &series[&event.series_ticker],
246 self.clock.get_time_ns(),
247 )?;
248
249 if start.is_some_and(|t| instrument.ts_event < t)
250 || end.is_some_and(|t| instrument.ts_event > t)
251 {
252 continue;
253 }
254
255 instruments.push(InstrumentAny::BinaryOption(instrument));
256 }
257
258 Ok(instruments)
259 }
260
261 pub(crate) async fn load_instrument(
262 &self,
263 request: &RequestInstrument,
264 ) -> anyhow::Result<BinaryOption> {
265 let ticker = parse_ticker(request.single_instrument_id()?)?;
266 let selection = Selection::new(request.params.as_ref())?;
267 let (start, end) = request_bounds(request.start, request.end)?;
268
269 let market = if selection.historical {
270 self.http.get_historical_market(&ticker).await?.market
271 } else {
272 Self::load_market(&self.http, &ticker).await?
273 };
274
275 anyhow::ensure!(
276 market.ticker == ticker,
277 "requested market identity mismatch"
278 );
279
280 let event = self
281 .http
282 .get_event(
283 &market.event_ticker,
284 &EventQuery {
285 exclude_markets: Some(true),
286 ..Default::default()
287 },
288 )
289 .await?
290 .event;
291
292 let series = self.http.get_series(&event.series_ticker).await?.series;
293 anyhow::ensure!(
294 selection.matches(&market, &event),
295 "definition does not satisfy request filters"
296 );
297 let instrument = Self::parse(&market, &event, &series, self.clock.get_time_ns())?;
298 anyhow::ensure!(
299 start.is_none_or(|t| instrument.ts_event >= t)
300 && end.is_none_or(|t| instrument.ts_event <= t),
301 "definition outside requested update interval"
302 );
303
304 Ok(instrument)
305 }
306
307 pub(crate) async fn load_market(
308 http: &KalshiHttpClient,
309 ticker: &str,
310 ) -> anyhow::Result<Market> {
311 let mut attempt = 0;
312
313 loop {
314 match http.get_market(ticker).await {
315 Ok(response) => return Ok(response.market),
316 Err(e) if not_found(&e) => match http.get_historical_market(ticker).await {
317 Ok(response) => return Ok(response.market),
318 Err(e) if not_found(&e) && attempt < 3 => {
319 nautilus_common::live::dst::time::sleep(std::time::Duration::from_millis(
320 100 << attempt,
321 ))
322 .await;
323 attempt += 1;
324 }
325 Err(e) => return Err(e.into()),
326 },
327 Err(e) => return Err(e.into()),
328 }
329 }
330 }
331
332 pub(crate) fn parse(
333 market: &Market,
334 event: &Event,
335 series: &Series,
336 ts_init: UnixNanos,
337 ) -> anyhow::Result<BinaryOption> {
338 anyhow::ensure!(
339 series.ticker == event.series_ticker,
340 "requested series identity mismatch"
341 );
342 let mut instrument = parse_instrument(market, event, ts_init)?;
343 let serialized = serde_json::to_string(series)?;
345 let fields: HashMap<String, Box<serde_json::value::RawValue>> =
346 serde_json::from_str(&serialized)?;
347
348 let metadata = fields
349 .into_iter()
350 .map(|(key, value)| {
351 let value = if key == "fee_multiplier" {
352 serde_json::Value::String(series.fee_multiplier.0.to_string())
353 } else {
354 serde_json::from_str(value.get())?
355 };
356
357 Ok((key, value))
358 })
359 .collect::<Result<serde_json::Map<_, _>, serde_json::Error>>()?;
360
361 let mut info = instrument
362 .info
363 .as_deref()
364 .cloned()
365 .context("missing instrument metadata")?;
366 info.insert("series".into(), metadata.into());
367 instrument.info = Some(Params::new(info));
368 Ok(instrument)
369 }
370}
371
372pub(crate) fn request_bounds(
373 start: Option<jiff::Timestamp>,
374 end: Option<jiff::Timestamp>,
375) -> anyhow::Result<(Option<UnixNanos>, Option<UnixNanos>)> {
376 let start = start
377 .map(try_datetime_to_unix_nanos)
378 .transpose()
379 .context("invalid request start bound")?;
380 let end = end
381 .map(try_datetime_to_unix_nanos)
382 .transpose()
383 .context("invalid request end bound")?;
384 anyhow::ensure!(
385 start.zip(end).is_none_or(|(a, b)| a <= b),
386 "invalid update interval"
387 );
388 Ok((start, end))
389}
390
391fn not_found(error: &KalshiHttpError) -> bool {
392 matches!(
393 error,
394 KalshiHttpError::Http { status: 404, .. }
395 | KalshiHttpError::Venue { status: 404, .. }
396 | KalshiHttpError::Status(404)
397 )
398}
399
400struct Selection {
401 query: MarketsQuery,
402 historical: bool,
403 max_pages: u32,
404 exchange_index: Option<i64>,
405}
406
407impl Selection {
408 fn new(params: Option<&Params>) -> anyhow::Result<Self> {
409 let value = params
410 .map(serde_json::to_value)
411 .transpose()?
412 .unwrap_or_else(|| serde_json::json!({}));
413
414 if let Some(status) = value.get("status").and_then(serde_json::Value::as_str) {
415 anyhow::ensure!(
416 status.parse::<MarketStatusFilter>().is_ok(),
417 "unsupported market status filter"
418 );
419 }
420
421 let mut query: MarketsQuery = serde_json::from_value(value.clone())?;
422 anyhow::ensure!(
423 query
424 .mve_filter
425 .as_ref()
426 .is_none_or(|value| *value == MveFilter::Exclude),
427 "only ordinary market discovery is supported"
428 );
429 query.mve_filter = Some(MveFilter::Exclude);
430 anyhow::ensure!(
431 query.cursor.as_deref().is_none_or(str::is_empty),
432 "instrument discovery must start at the first page"
433 );
434
435 for ticker in query.tickers.iter().flat_map(|v| v.split(',')) {
436 parse_instrument_id(ticker)?;
437 }
438
439 for ticker in [&query.event_ticker, &query.series_ticker]
440 .into_iter()
441 .flatten()
442 {
443 parse_instrument_id(ticker)?;
444 }
445
446 let historical = value
447 .get("historical")
448 .map(|v| v.as_bool().context("historical must be a boolean"))
449 .transpose()?
450 .unwrap_or(false);
451 let max_pages = value
452 .get("max_pages")
453 .map(|v| v.as_u64().context("max_pages must be a positive integer"))
454 .transpose()?
455 .unwrap_or(100);
456 let max_pages = u32::try_from(max_pages)?;
457 anyhow::ensure!(max_pages > 0, "max_pages must be positive");
458
459 let exchange_index = value
460 .get("exchange_index")
461 .map(|v| {
462 v.as_i64()
463 .filter(|v| *v >= 0 && *v <= i64::from(i32::MAX))
464 .context("invalid exchange index")
465 })
466 .transpose()?;
467
468 Ok(Self {
469 query,
470 historical,
471 max_pages,
472 exchange_index,
473 })
474 }
475
476 fn matches(&self, market: &Market, event: &Event) -> bool {
477 self.query
478 .tickers
479 .as_ref()
480 .is_none_or(|v| v.split(',').any(|t| t == market.ticker))
481 && self
482 .query
483 .event_ticker
484 .as_ref()
485 .is_none_or(|v| *v == market.event_ticker)
486 && self
487 .query
488 .series_ticker
489 .as_ref()
490 .is_none_or(|v| *v == event.series_ticker)
491 && self
492 .exchange_index
493 .is_none_or(|v| market.exchange_index == Field::Value(v as i32))
494 && timestamp_matches(
495 Some(market.created_time),
496 self.query.min_created_ts,
497 self.query
498 .max_created_ts
499 .map_or(Bound::Unbounded, Bound::Excluded),
500 )
501 && timestamp_matches(
502 match market.updated_time {
503 Field::Value(t) => Some(t),
504 _ => None,
505 },
506 self.query.min_updated_ts,
507 self.query
508 .max_updated_ts
509 .map_or(Bound::Unbounded, Bound::Included),
510 )
511 && timestamp_matches(
512 Some(market.close_time),
513 self.query.min_close_ts,
514 self.query
515 .max_close_ts
516 .map_or(Bound::Unbounded, Bound::Excluded),
517 )
518 && timestamp_matches(
519 match market.settlement_ts {
520 Field::Value(t) => Some(t),
521 _ => None,
522 },
523 self.query.min_settled_ts,
524 self.query
525 .max_settled_ts
526 .map_or(Bound::Unbounded, Bound::Excluded),
527 )
528 && self.query.status.as_ref().is_none_or(|filter| {
529 STATUS_FILTERS
530 .iter()
531 .find(|(name, _)| name == filter)
532 .is_some_and(|(_, statuses)| statuses.contains(&market.status))
533 })
534 }
535}
536
537fn timestamp_matches(
538 value: Option<jiff::Timestamp>,
539 minimum: Option<i64>,
540 maximum: Bound<i64>,
541) -> bool {
542 let value = value.map(jiff::Timestamp::as_nanosecond);
543 let minimum = minimum.map(|seconds| i128::from(seconds) * i128::from(NANOSECONDS_IN_SECOND));
544 let maximum = maximum.map(|seconds| i128::from(seconds) * i128::from(NANOSECONDS_IN_SECOND));
545 minimum.is_none_or(|min| value.is_some_and(|value| value > min))
546 && match maximum {
547 Bound::Unbounded => true,
548 Bound::Included(max) => value.is_some_and(|value| value <= max),
549 Bound::Excluded(max) => value.is_some_and(|value| value < max),
550 }
551}
552
553#[cfg(test)]
554mod tests {
555 use rstest::rstest;
556 use serde_json::Value;
557
558 use super::*;
559 use crate::config::KalshiDataClientConfig;
560
561 #[rstest]
562 #[case("min_created_ts", [false, false, true])]
563 #[case("max_created_ts", [true, false, false])]
564 #[case("min_updated_ts", [false, false, true])]
565 #[case("max_updated_ts", [true, true, false])]
566 #[case("min_close_ts", [false, false, true])]
567 #[case("max_close_ts", [true, false, false])]
568 #[case("min_settled_ts", [false, false, true])]
569 #[case("max_settled_ts", [true, false, false])]
570 fn timestamp_filters_preserve_nanoseconds_and_boundaries(
571 #[case] field: &str,
572 #[case] expected: [bool; 3],
573 ) {
574 let (mut market, event) = definition();
575 let params = Params::new([(field.into(), 100.into())].into());
576 let selection = Selection::new(Some(¶ms)).unwrap();
577
578 let results = [-1, 0, 1].map(|offset| {
579 let timestamp = jiff::Timestamp::from_nanosecond(100_000_000_000 + offset).unwrap();
580 market.created_time = timestamp;
581 market.updated_time = Field::Value(timestamp);
582 market.close_time = timestamp;
583 market.settlement_ts = Field::Value(timestamp);
584 selection.matches(&market, &event)
585 });
586
587 assert_eq!(results, expected);
588 }
589
590 #[rstest]
591 #[case("unopened", "initialized", true)]
592 #[case("open", "active", true)]
593 #[case("paused", "inactive", true)]
594 #[case("closed", "closed", true)]
595 #[case("closed", "determined", true)]
596 #[case("closed", "disputed", true)]
597 #[case("closed", "amended", true)]
598 #[case("settled", "finalized", true)]
599 #[case("paused", "active", false)]
600 #[case("closed", "finalized", false)]
601 fn status_filters_match_lifecycle(
602 #[case] filter: &str,
603 #[case] status: &str,
604 #[case] expected: bool,
605 ) {
606 let (mut market, event) = definition();
607 market.status = status.parse().unwrap();
608 let params = Params::new([("status".into(), filter.into())].into());
609 let selection = Selection::new(Some(¶ms)).unwrap();
610 assert_eq!(selection.matches(&market, &event), expected);
611 }
612
613 #[rstest]
614 #[case("finalized")]
615 #[case("open,closed")]
616 #[case("not-a-status")]
617 fn unknown_status_filter_is_rejected(#[case] status: &str) {
618 let params = Params::new([("status".into(), status.into())].into());
619 let result = Selection::new(Some(¶ms));
620 assert_eq!(
621 result.err().unwrap().to_string(),
622 "unsupported market status filter"
623 );
624 }
625
626 #[rstest]
627 fn multivariate_only_selection_is_rejected() {
628 let params = Params::new([("mve_filter".into(), "only".into())].into());
629 let result = Selection::new(Some(¶ms));
630 assert_eq!(
631 result.err().unwrap().to_string(),
632 "only ordinary market discovery is supported"
633 );
634 }
635
636 #[rstest]
637 fn series_metadata_retains_exact_fee_multiplier() {
638 let (market, event) = definition();
639 let values: Value =
640 serde_json::from_str(include_str!("../test_data/instruments.json")).unwrap();
641 let mut series: Series =
642 serde_json::from_str(&serde_json::to_string(&values["series"]["series"]).unwrap())
643 .unwrap();
644 let exact = "0.1234567890123456789012345678";
645 series.fee_multiplier.0 = rust_decimal::Decimal::from_str_exact(exact).unwrap();
646 let http = KalshiHttpClient::new(&KalshiDataClientConfig::default()).unwrap();
647 let clock = Box::leak(Box::new(AtomicTime::new(false, UnixNanos::from(31))));
648 let (sender, _) = tokio::sync::mpsc::unbounded_channel();
649 let provider = KalshiInstrumentProvider::new(http, clock, sender.into());
650 let instrument =
651 KalshiInstrumentProvider::parse(&market, &event, &series, provider.clock.get_time_ns())
652 .unwrap();
653 assert_eq!(
654 instrument.info.as_ref().unwrap()["series"]["fee_multiplier"],
655 exact
656 );
657 }
658
659 #[rstest]
660 fn ticker_selection_preserves_case_and_multiple_tickers() {
661 let (market, event) = definition();
662
663 let results = [
664 market.ticker.clone(),
665 format!("OTHER,{}", market.ticker),
666 market.ticker.to_lowercase(),
667 "OTHER".into(),
668 ]
669 .map(|tickers| {
670 let params = Params::new([("tickers".into(), tickers.into())].into());
671 Selection::new(Some(¶ms))
672 .unwrap()
673 .matches(&market, &event)
674 });
675
676 assert_eq!(results, [true, true, false, false]);
677 }
678
679 fn definition() -> (Market, Event) {
680 let values: Value =
681 serde_json::from_str(include_str!("../test_data/instruments.json")).unwrap();
682 let value = &values["definitions"]["live"];
683
684 (
685 serde_json::from_value(value["market"].clone()).unwrap(),
686 serde_json::from_value(value["event"].clone()).unwrap(),
687 )
688 }
689}