1pub(crate) mod parse;
19
20mod history;
21mod lifecycle;
22
23use std::{
24 cell::RefCell,
25 collections::HashMap,
26 future::Future,
27 rc::Rc,
28 sync::{
29 Arc, Mutex,
30 atomic::{AtomicBool, Ordering},
31 },
32 time::Duration,
33};
34
35use anyhow::Context;
36use async_trait::async_trait;
37use nautilus_common::{
38 cache::{Cache, CacheView},
39 clients::{DataClient, execute_instrument_subscriptions},
40 live::{dst::time, sender::EventSender},
41 messages::{DataEvent, data::*},
42};
43use nautilus_core::{
44 Params, UUID4,
45 time::{AtomicTime, get_atomic_clock_realtime},
46};
47use nautilus_live::task::{TaskGroup, TaskGroupGuard, TaskSpawner};
48use nautilus_model::{
49 data::Data,
50 enums::BookType,
51 identifiers::{ClientId, InstrumentId, Venue},
52 instruments::{BinaryOption, Instrument, InstrumentAny},
53 orderbook::OrderBook,
54};
55use tokio_util::sync::CancellationToken;
56
57use self::lifecycle::LifecycleTracker;
58pub use self::parse::{quote, trade};
59use crate::{
60 book::{BookSyncTracker, Levels},
61 common::{consts::KALSHI_VENUE, parse::parse_ticker},
62 config::KalshiDataClientConfig,
63 http::client::KalshiHttpClient,
64 providers::{KalshiInstrumentProvider, request_bounds},
65 websocket::{
66 client::{KalshiWebSocketClient, KalshiWsEvent},
67 messages::{KalshiChannel, KalshiDataMessage, KalshiSubscription, KalshiWsMessage},
68 },
69};
70
71const TASK_GRACE: Duration = Duration::from_secs(5);
72const TASK_FORCE: Duration = Duration::from_secs(2);
73
74#[derive(Debug)]
83pub struct KalshiDataClient {
84 clock: &'static AtomicTime,
85 cache: CacheView,
86 client_id: ClientId,
87 config: KalshiDataClientConfig,
88 provider: Arc<KalshiInstrumentProvider>,
89 ws_client: Option<KalshiWebSocketClient>,
90 connected: Arc<AtomicBool>,
91 disposed: bool,
92 session_tasks: TaskGroup,
93 command_tasks: TaskGroup,
94 sender: EventSender<DataEvent>,
95 instruments: Vec<InstrumentId>,
96 context: Arc<Mutex<HashMap<InstrumentId, BinaryOption>>>,
97 demand: Arc<Mutex<HashMap<InstrumentId, Demand>>>,
98 lifecycle: Arc<LifecycleTracker>,
99 books: BookSyncTracker,
100}
101
102#[allow(
103 clippy::missing_panics_doc,
104 reason = "client state mutex poisoning is not expected"
105)]
106impl KalshiDataClient {
107 pub fn new(
118 client_id: ClientId,
119 config: KalshiDataClientConfig,
120 instruments: Vec<InstrumentId>,
121 sender: EventSender<DataEvent>,
122 ) -> anyhow::Result<Self> {
123 config.validate()?;
124 anyhow::ensure!(
125 !instruments.is_empty(),
126 "bootstrap markets must not be empty"
127 );
128 let mut selected = std::collections::HashSet::new();
129
130 for id in &instruments {
131 parse_ticker(*id)?;
132 anyhow::ensure!(selected.insert(*id), "duplicate bootstrap market");
133 }
134
135 let http = KalshiHttpClient::new(&config)?;
136 let clock = get_atomic_clock_realtime();
137 let provider = KalshiInstrumentProvider::new(http, clock, sender.clone());
138
139 let books = BookSyncTracker::new(
140 &instruments,
141 Duration::from_secs(config.book_snapshot_timeout_secs),
142 );
143
144 Ok(Self {
145 clock,
146 cache: Rc::new(RefCell::new(Cache::default())).into(),
147 client_id,
148 config,
149 provider: Arc::new(provider),
150 ws_client: None,
151 connected: Arc::new(AtomicBool::new(false)),
152 disposed: false,
153 session_tasks: TaskGroup::new(),
154 command_tasks: TaskGroup::new(),
155 sender,
156 instruments,
157 context: Arc::default(),
158 demand: Arc::default(),
159 lifecycle: Arc::default(),
160 books,
161 })
162 }
163
164 pub(crate) fn with_runtime(
165 client_id: ClientId,
166 config: KalshiDataClientConfig,
167 sender: EventSender<DataEvent>,
168 cache: CacheView,
169 ) -> anyhow::Result<Self> {
170 let instruments = config.instrument_ids.clone();
171 let mut client = Self::new(client_id, config, instruments, sender)?;
172 client.cache = cache;
173 client.require_cached_binary_options()?;
174 Ok(client)
175 }
176
177 fn require_cached_binary_options(&self) -> anyhow::Result<()> {
178 let cache = self.cache.borrow();
179 for id in &self.instruments {
180 if let Some(instrument) = cache.instrument(id) {
181 anyhow::ensure!(
182 matches!(instrument, InstrumentAny::BinaryOption(_)) && instrument.id() == *id,
183 "cached instrument {id} is not a Kalshi binary option"
184 );
185 }
186 }
187
188 Ok(())
189 }
190
191 #[cfg(all(test, not(all(feature = "simulation", madsim))))]
192 pub(crate) fn config(&self) -> &KalshiDataClientConfig {
193 &self.config
194 }
195
196 #[cfg(all(test, not(all(feature = "simulation", madsim))))]
197 pub(crate) fn instruments(&self) -> &[InstrumentId] {
198 &self.instruments
199 }
200
201 #[cfg(all(test, not(all(feature = "simulation", madsim))))]
202 pub(crate) fn cache(&self) -> &CacheView {
203 &self.cache
204 }
205
206 fn subscribe_lifecycle(
207 &self,
208 id: InstrumentId,
209 close: bool,
210 subscribe: bool,
211 ) -> anyhow::Result<()> {
212 anyhow::ensure!(!self.disposed, "Kalshi data client is disposed");
213 anyhow::ensure!(!self.sender.is_closed(), "data event receiver closed");
214 anyhow::ensure!(
215 self.instruments.contains(&id),
216 "instrument is not a selected bootstrap market"
217 );
218 self.lifecycle.subscribe(
219 id,
220 close,
221 subscribe,
222 &self.context,
223 &self.sender,
224 self.clock.get_time_ns(),
225 )
226 }
227
228 fn subscribe_market(&self, id: InstrumentId, quotes: bool) -> anyhow::Result<()> {
229 anyhow::ensure!(!self.disposed, "Kalshi data client is disposed");
230 anyhow::ensure!(
231 self.instruments.contains(&id),
232 "instrument is not a selected bootstrap market"
233 );
234 anyhow::ensure!(!self.sender.is_closed(), "data event receiver closed");
235 let mut demand = self.demand.lock().expect("demand lock is not poisoned");
236 let first = demand.values().all(|entry| entry.count(quotes) == 0);
237 let entry = demand.entry(id).or_default();
238 let count = entry.count_mut(quotes);
239 let next = count
240 .checked_add(1)
241 .context("subscription reference count overflow")?;
242
243 if first && let Some(ws_client) = &self.ws_client {
244 let subscription = subscription(&self.instruments, quotes)?;
245 if let Err(e) = ws_client.subscribe(subscription.clone()) {
246 if let Err(e) = ws_client.unsubscribe(&subscription) {
247 log::warn!("Kalshi subscription rollback notification failed: {e}");
248 }
249
250 return Err(e);
251 }
252 }
253
254 *count = next;
255 Ok(())
256 }
257
258 fn unsubscribe_market(&self, id: InstrumentId, quotes: bool) -> anyhow::Result<()> {
259 let mut demand = self.demand.lock().expect("demand lock is not poisoned");
260
261 let Some(entry) = demand.get_mut(&id) else {
262 return Ok(());
263 };
264
265 let count = entry.count_mut(quotes);
266 if *count == 0 {
267 return Ok(());
268 }
269
270 *count -= 1;
271 let last = demand.values().all(|entry| entry.count(quotes) == 0);
272 if last && let Some(ws_client) = &self.ws_client {
273 let subscription = subscription(&self.instruments, quotes)?;
274 ws_client.unsubscribe(&subscription)?;
275 }
276
277 Ok(())
278 }
279
280 fn spawn_request<F>(&self, future: F) -> anyhow::Result<()>
281 where
282 F: Future<Output = anyhow::Result<()>> + Send + 'static,
283 {
284 anyhow::ensure!(!self.disposed, "Kalshi data client is disposed");
285 anyhow::ensure!(!self.sender.is_closed(), "data event receiver closed");
286 let cancellation = self.command_tasks.cancellation_token();
287
288 self.command_tasks.spawn(async move {
289 tokio::select! {
290 biased;
291 () = cancellation.cancelled() => {},
292 result = future => if let Err(e) = result { log::warn!("Kalshi data request failed: {e}"); },
293 }
294 })?;
295
296 Ok(())
297 }
298
299 fn begin_session_shutdown(&mut self) {
300 self.connected.store(false, Ordering::Release);
301 self.books.stop(false);
302 self.session_tasks.begin_shutdown();
303 self.ws_client = None;
304 }
305
306 async fn finish_shutdown(&self) -> anyhow::Result<()> {
307 let (session, commands) = tokio::join!(
308 self.session_tasks.finish_shutdown(TASK_GRACE, TASK_FORCE),
309 self.command_tasks.finish_shutdown(TASK_GRACE, TASK_FORCE)
310 );
311 session?;
312 commands?;
313 Ok(())
314 }
315}
316
317macro_rules! unsupported {
318 ($($name:ident($command:ty)),* $(,)?) => { $(
319 fn $name(&mut self, _command: $command) -> anyhow::Result<()> {
320 anyhow::bail!(concat!("Kalshi does not support ", stringify!($name)))
321 }
322 )* };
323}
324
325#[async_trait(?Send)]
326impl DataClient for KalshiDataClient {
327 fn client_id(&self) -> ClientId {
328 self.client_id
329 }
330
331 fn venue(&self) -> Option<Venue> {
332 Some(*KALSHI_VENUE)
333 }
334
335 fn start(&mut self) -> anyhow::Result<()> {
336 anyhow::ensure!(!self.disposed, "Kalshi data client is disposed");
337 Ok(())
338 }
339
340 fn stop(&mut self) -> anyhow::Result<()> {
341 self.begin_session_shutdown();
342 self.command_tasks.begin_shutdown();
343 Ok(())
344 }
345
346 fn reset(&mut self) -> anyhow::Result<()> {
347 self.stop()?;
348 self.books.stop(true);
349 self.lifecycle.clear();
350 self.demand
351 .lock()
352 .expect("demand lock is not poisoned")
353 .clear();
354 self.context
355 .lock()
356 .expect("context lock is not poisoned")
357 .clear();
358 Ok(())
359 }
360
361 fn dispose(&mut self) -> anyhow::Result<()> {
362 self.reset()?;
363 self.disposed = true;
364 Ok(())
365 }
366
367 fn is_connected(&self) -> bool {
368 self.connected.load(Ordering::Acquire)
369 && !self.sender.is_closed()
370 && self
371 .ws_client
372 .as_ref()
373 .is_some_and(KalshiWebSocketClient::is_active)
374 }
375
376 fn is_disconnected(&self) -> bool {
377 !self.is_connected()
378 }
379
380 async fn connect(&mut self) -> anyhow::Result<()> {
381 anyhow::ensure!(!self.disposed, "Kalshi data client is disposed");
382
383 if self.is_connected() {
384 return Ok(());
385 }
386
387 self.begin_session_shutdown();
388 self.session_tasks
389 .finish_shutdown(TASK_GRACE, TASK_FORCE)
390 .await?;
391 self.session_tasks.start_generation()?;
392
393 if !self.command_tasks.is_open() {
394 self.command_tasks
395 .finish_shutdown(TASK_GRACE, TASK_FORCE)
396 .await?;
397 self.command_tasks.start_generation()?;
398 }
399
400 let connected = Arc::clone(&self.connected);
401 let guard = TaskGroupGuard::new(&[&self.session_tasks], move || {
402 connected.store(false, Ordering::Release);
403 });
404
405 self.lifecycle.begin_recovery();
406 self.context
407 .lock()
408 .expect("context lock is not poisoned")
409 .clear();
410 refresh(
411 &self.provider,
412 &self.instruments,
413 &self.context,
414 &self.lifecycle,
415 &self.sender,
416 &self.session_tasks.cancellation_token(),
417 )
418 .await?;
419 let (ws_client, receiver) = KalshiWebSocketClient::new(self.config.clone())?;
420 ws_client.subscribe(KalshiSubscription {
421 channel: KalshiChannel::MarketLifecycleV2,
422 market_tickers: Vec::new(),
423 })?;
424
425 self.books.replay(&ws_client)?;
426 {
427 let demand = self.demand.lock().expect("demand lock is not poisoned");
428 for quotes in [true, false] {
429 if demand.values().any(|entry| entry.count(quotes) > 0) {
430 ws_client.subscribe(subscription(&self.instruments, quotes)?)?;
431 }
432 }
433 }
434
435 let session = Session {
436 provider: Arc::clone(&self.provider),
437 instruments: self.instruments.clone(),
438 context: Arc::clone(&self.context),
439 demand: Arc::clone(&self.demand),
440 lifecycle: Arc::clone(&self.lifecycle),
441 books: self.books.clone(),
442 tasks: self.session_tasks.spawner()?,
443 sender: self.sender.clone(),
444 connected: Arc::clone(&self.connected),
445 ws_client: ws_client.clone(),
446 clock: self.clock,
447 refresh_interval: Duration::from_secs(
448 self.config.update_instruments_interval_mins * 60,
449 ),
450 };
451
452 let (startup, initialized) = tokio::sync::oneshot::channel();
453
454 self.session_tasks.spawn(session.run(
455 receiver,
456 self.session_tasks.cancellation_token(),
457 startup,
458 ))?;
459 self.ws_client = Some(ws_client.clone());
460 let result = async {
461 ws_client.connect().await?;
462 time::timeout(
463 Duration::from_secs(self.config.ws_timeout_secs),
464 initialized,
465 )
466 .await
467 .context("initial lifecycle recovery timed out")?
468 .context("initial lifecycle recovery stopped")??;
469 anyhow::ensure!(
470 !self.sender.is_closed(),
471 "data event receiver closed during connect"
472 );
473 Ok(())
474 }
475 .await;
476
477 if let Err(e) = result {
478 drop(guard);
479 self.begin_session_shutdown();
480 self.session_tasks
481 .finish_shutdown(TASK_GRACE, TASK_FORCE)
482 .await
483 .context("failed Kalshi startup cleanup")?;
484 return Err(e);
485 }
486
487 self.connected.store(true, Ordering::Release);
488 guard.disarm();
489 log::info!("Connected {}", self.client_id);
490 Ok(())
491 }
492
493 async fn disconnect(&mut self) -> anyhow::Result<()> {
494 self.stop()?;
495 self.finish_shutdown().await?;
496 log::info!("Disconnected {}", self.client_id);
497 Ok(())
498 }
499
500 fn subscribe_quotes(&mut self, command: SubscribeQuotes) -> anyhow::Result<()> {
501 execute_instrument_subscriptions(&command.instrument_ids, |id| {
502 self.subscribe_market(id, true)
503 })
504 }
505
506 fn subscribe_trades(&mut self, command: SubscribeTrades) -> anyhow::Result<()> {
507 execute_instrument_subscriptions(&command.instrument_ids, |id| {
508 self.subscribe_market(id, false)
509 })
510 }
511
512 fn unsubscribe_quotes(&mut self, command: &UnsubscribeQuotes) -> anyhow::Result<()> {
513 execute_instrument_subscriptions(&command.instrument_ids, |id| {
514 self.unsubscribe_market(id, true)
515 })
516 }
517
518 fn unsubscribe_trades(&mut self, command: &UnsubscribeTrades) -> anyhow::Result<()> {
519 execute_instrument_subscriptions(&command.instrument_ids, |id| {
520 self.unsubscribe_market(id, false)
521 })
522 }
523
524 fn subscribe_book_deltas(&mut self, command: SubscribeBookDeltas) -> anyhow::Result<()> {
525 anyhow::ensure!(!self.disposed, "Kalshi data client is disposed");
526 anyhow::ensure!(!self.sender.is_closed(), "data event receiver closed");
527 anyhow::ensure!(
528 command.book_type == BookType::L2_MBP && command.depth.is_none(),
529 "Kalshi streams full L2 market-by-price books only"
530 );
531 anyhow::ensure!(
532 command
533 .params
534 .as_ref()
535 .is_none_or(|params| params.is_empty()),
536 "Kalshi book subscription parameters are unsupported"
537 );
538 execute_instrument_subscriptions(&command.instrument_ids, |id| {
539 anyhow::ensure!(
540 self.instruments.contains(&id),
541 "instrument is not a selected bootstrap market"
542 );
543 self.books.subscribe(id, self.ws_client.as_ref())
544 })
545 }
546
547 fn unsubscribe_book_deltas(&mut self, command: &UnsubscribeBookDeltas) -> anyhow::Result<()> {
548 execute_instrument_subscriptions(&command.instrument_ids, |id| {
549 self.books.unsubscribe(id, self.ws_client.as_ref())
550 })
551 }
552
553 fn request_book_snapshot(&self, request: RequestBookSnapshot) -> anyhow::Result<()> {
554 let instrument_id = request.single_instrument_id()?;
555 let ticker = parse_ticker(instrument_id)?;
556 let depth = request.depth.map_or(0, |depth| depth.get());
557 anyhow::ensure!(depth <= 100, "Kalshi REST book depth exceeds 100");
558 anyhow::ensure!(
559 request
560 .params
561 .as_ref()
562 .is_none_or(|params| params.is_empty()),
563 "Kalshi book request parameters are unsupported"
564 );
565 let provider = Arc::clone(&self.provider);
566 let sender = self.sender.clone();
567 let client_id = self.client_id;
568 self.spawn_request(async move {
569 let instrument_request = RequestInstrument::new(
570 instrument_id,
571 None,
572 None,
573 None,
574 UUID4::new(),
575 request.ts_init,
576 None,
577 );
578
579 let instrument = provider.load_instrument(&instrument_request).await?;
580 let response = provider.http.get_orderbook(&ticker, depth as u32).await?;
581 let now = provider.clock.get_time_ns();
582 let deltas = Levels::rest(&response.orderbook_fp, &instrument, now)?;
583 let mut book = OrderBook::new(instrument.id, BookType::L2_MBP);
584 book.apply_deltas(&deltas)?;
585
586 let response = BookResponse::new(
587 request.request_id,
588 request.client_id.unwrap_or(client_id),
589 instrument_id,
590 book,
591 None,
592 None,
593 now,
594 request.params,
595 );
596
597 sender
598 .send(DataEvent::Response(DataResponse::Book(response)))
599 .map_err(|_| anyhow::anyhow!("book response receiver closed"))?;
600 Ok(())
601 })
602 }
603
604 fn request_trades(&self, request: RequestTrades) -> anyhow::Result<()> {
605 let instrument_id = request.single_instrument_id()?;
606 let ticker = parse_ticker(instrument_id)?;
607 let now = self.clock.get_time_ns();
608
609 let range = history::HistoryRange::new(
610 request.start,
611 request.end,
612 request.limit,
613 request.params.as_ref(),
614 now,
615 )?;
616
617 let (start, end) = request_bounds(request.start, request.end)?;
618 let provider = Arc::clone(&self.provider);
619 let client_id = request.client_id.unwrap_or(self.client_id);
620 let sender = self.sender.clone();
621 self.spawn_request(async move {
622 let metadata =
623 RequestInstrument::new(instrument_id, None, None, None, UUID4::new(), now, None);
624 let instrument = provider.load_instrument(&metadata).await?;
625 let records = provider
626 .http
627 .get_trades_range(range.trades_query(ticker), range.max_pages)
628 .await?;
629 let mut trades = Vec::new();
630
631 for record in records {
632 let tick = history::trade(record, &instrument)?;
633 if range.contains(tick.ts_event) {
634 trades.push(tick);
635 }
636 }
637
638 range.truncate(&mut trades);
639
640 let response = TradesResponse::new(
641 request.request_id,
642 client_id,
643 instrument_id,
644 trades,
645 start,
646 end,
647 now,
648 request.params,
649 );
650
651 sender
652 .send(DataEvent::Response(DataResponse::Trades(response)))
653 .map_err(|_| anyhow::anyhow!("trade response receiver closed"))?;
654 Ok(())
655 })
656 }
657
658 fn request_bars(&self, request: RequestBars) -> anyhow::Result<()> {
659 let bar_type = request.single_bar_type()?;
660 let id = bar_type.instrument_id();
661 parse_ticker(id)?;
662 let period = history::period(bar_type)?;
663 let now = self.clock.get_time_ns();
664
665 let range = history::HistoryRange::new(
666 request.start,
667 request.end,
668 request.limit,
669 request.params.as_ref(),
670 now,
671 )?;
672
673 let (start, end) = request_bounds(request.start, request.end)?;
674 let provider = Arc::clone(&self.provider);
675 let client_id = request.client_id.unwrap_or(self.client_id);
676 let sender = self.sender.clone();
677 self.spawn_request(async move {
678 let metadata = RequestInstrument::new(id, None, None, None, UUID4::new(), now, None);
679 let instrument = provider.load_instrument(&metadata).await?;
680 let info = instrument
681 .info
682 .as_ref()
683 .context("missing instrument metadata")?;
684 let market = serde_json::from_value(
685 info.get("market")
686 .context("missing market metadata")?
687 .clone(),
688 )?;
689 let series = info
690 .get("event")
691 .and_then(|v| v.get("series_ticker"))
692 .and_then(serde_json::Value::as_str)
693 .context("missing series identity")?;
694 let records = provider
695 .http
696 .get_candlesticks_range(&market, series, &range.candles_query(period))
697 .await?;
698 let mut bars = Vec::new();
699
700 for record in records {
701 let ts_event = history::candle_time(record.end_period_ts)?;
702 if !range.contains(ts_event) || ts_event > now {
703 continue;
704 }
705
706 if let Some(bar) = history::bar(record, bar_type, &instrument)? {
707 bars.push(bar);
708 }
709 }
710
711 range.truncate(&mut bars);
712
713 let response = BarsResponse::new(
714 request.request_id,
715 client_id,
716 bar_type,
717 bars,
718 start,
719 end,
720 now,
721 request.params,
722 );
723
724 sender
725 .send(DataEvent::Response(DataResponse::Bars(response)))
726 .map_err(|_| anyhow::anyhow!("bar response receiver closed"))?;
727 Ok(())
728 })
729 }
730
731 fn request_quotes(&self, _request: RequestQuotes) -> anyhow::Result<()> {
732 anyhow::bail!("Kalshi does not provide historical quotes")
733 }
734
735 fn request_instrument(&self, mut request: RequestInstrument) -> anyhow::Result<()> {
736 let instrument_id = request.single_instrument_id()?;
737 parse_ticker(instrument_id)?;
738 request.client_id.get_or_insert(self.client_id);
739 let provider = Arc::clone(&self.provider);
740 let selected = self.instruments.contains(&instrument_id);
741 let context = Arc::clone(&self.context);
742 let sender = self.sender.clone();
743 let lifecycle = Arc::clone(&self.lifecycle);
744 let stamp = lifecycle.begin_read();
745 self.spawn_request(async move {
746 let instrument = provider.load_instrument(&request).await?;
747 if selected {
748 lifecycle.apply(instrument.clone(), stamp, &context, &sender)?;
749 }
750
751 let guard = if selected {
752 Some(lifecycle.response_guard(&[&instrument])?)
753 } else {
754 None
755 };
756
757 let result = provider.respond_instrument(request, instrument);
758 drop(guard);
759 result
760 })
761 }
762
763 fn request_instruments(&self, mut request: RequestInstruments) -> anyhow::Result<()> {
764 anyhow::ensure!(
765 request.venue.is_none_or(|v| v == *KALSHI_VENUE),
766 "instrument request venue must be KALSHI"
767 );
768 request.client_id.get_or_insert(self.client_id);
769 let provider = Arc::clone(&self.provider);
770 let selected = self.instruments.clone();
771 let context = Arc::clone(&self.context);
772 let sender = self.sender.clone();
773 let lifecycle = Arc::clone(&self.lifecycle);
774 let stamp = lifecycle.begin_read();
775 self.spawn_request(async move {
776 let mut scoped = request.clone();
777
778 if !selected.is_empty()
779 && scoped.params.as_ref().is_none_or(|params| {
780 [
781 "tickers",
782 "event_ticker",
783 "series_ticker",
784 "min_updated_ts",
785 "max_updated_ts",
786 ]
787 .iter()
788 .all(|key| !params.contains_key(*key))
789 })
790 {
791 let tickers = selected
792 .iter()
793 .map(|id| id.symbol.as_str())
794 .collect::<Vec<_>>()
795 .join(",");
796 let mut params = scoped
797 .params
798 .as_ref()
799 .map(Params::to_shared_map)
800 .unwrap_or_default();
801 let tickers = Arc::new(tickers.into());
802 params.insert("tickers".into(), tickers);
803 let params = Params::from_shared(params);
804 scoped.params = Some(params);
805 }
806
807 let instruments = provider.load_instruments(&scoped).await?;
808 for instrument in &instruments {
809 if let InstrumentAny::BinaryOption(instrument) = instrument
810 && selected.contains(&instrument.id)
811 {
812 lifecycle.apply(instrument.clone(), stamp, &context, &sender)?;
813 }
814 }
815
816 let definitions: Vec<_> = instruments
817 .iter()
818 .filter_map(|instrument| match instrument {
819 InstrumentAny::BinaryOption(instrument)
820 if selected.contains(&instrument.id) =>
821 {
822 Some(instrument)
823 }
824 _ => None,
825 })
826 .collect();
827
828 let guard = lifecycle.response_guard(&definitions)?;
829 drop(definitions);
830 let result = provider.respond_instruments(request, instruments);
831 drop(guard);
832 result
833 })
834 }
835
836 fn subscribe_instrument_status(
837 &mut self,
838 command: SubscribeInstrumentStatus,
839 ) -> anyhow::Result<()> {
840 execute_instrument_subscriptions(&command.instrument_ids, |id| {
841 self.subscribe_lifecycle(id, false, true)
842 })
843 }
844
845 fn unsubscribe_instrument_status(
846 &mut self,
847 command: &UnsubscribeInstrumentStatus,
848 ) -> anyhow::Result<()> {
849 execute_instrument_subscriptions(&command.instrument_ids, |id| {
850 self.subscribe_lifecycle(id, false, false)
851 })
852 }
853
854 fn subscribe_instrument_close(
855 &mut self,
856 command: SubscribeInstrumentClose,
857 ) -> anyhow::Result<()> {
858 execute_instrument_subscriptions(&command.instrument_ids, |id| {
859 self.subscribe_lifecycle(id, true, true)
860 })
861 }
862
863 fn unsubscribe_instrument_close(
864 &mut self,
865 command: &UnsubscribeInstrumentClose,
866 ) -> anyhow::Result<()> {
867 execute_instrument_subscriptions(&command.instrument_ids, |id| {
868 self.subscribe_lifecycle(id, true, false)
869 })
870 }
871
872 unsupported! {
873 subscribe(SubscribeCustomData), subscribe_instruments(SubscribeInstruments), subscribe_instrument(SubscribeInstrument),
874 subscribe_book_depth(SubscribeBookDepth),
875 subscribe_mark_prices(SubscribeMarkPrices), subscribe_index_prices(SubscribeIndexPrices), subscribe_funding_rates(SubscribeFundingRates),
876 subscribe_bars(SubscribeBars), subscribe_option_greeks(SubscribeOptionGreeks),
877 unsubscribe(&UnsubscribeCustomData), unsubscribe_instruments(&UnsubscribeInstruments), unsubscribe_instrument(&UnsubscribeInstrument),
878 unsubscribe_book_depth(&UnsubscribeBookDepth),
879 unsubscribe_mark_prices(&UnsubscribeMarkPrices), unsubscribe_index_prices(&UnsubscribeIndexPrices), unsubscribe_funding_rates(&UnsubscribeFundingRates),
880 unsubscribe_bars(&UnsubscribeBars), unsubscribe_option_greeks(&UnsubscribeOptionGreeks),
881 }
882}
883
884#[derive(Debug, Default)]
885struct Demand {
886 quotes: usize,
887 trades: usize,
888}
889
890impl Demand {
891 fn count_mut(&mut self, quotes: bool) -> &mut usize {
892 if quotes {
893 &mut self.quotes
894 } else {
895 &mut self.trades
896 }
897 }
898
899 fn count(&self, quotes: bool) -> usize {
900 if quotes { self.quotes } else { self.trades }
901 }
902}
903
904struct Session {
905 provider: Arc<KalshiInstrumentProvider>,
906 instruments: Vec<InstrumentId>,
907 context: Arc<Mutex<HashMap<InstrumentId, BinaryOption>>>,
908 demand: Arc<Mutex<HashMap<InstrumentId, Demand>>>,
909 lifecycle: Arc<LifecycleTracker>,
910 books: BookSyncTracker,
911 tasks: TaskSpawner,
912 sender: EventSender<DataEvent>,
913 connected: Arc<AtomicBool>,
914 ws_client: KalshiWebSocketClient,
915 clock: &'static AtomicTime,
916 refresh_interval: Duration,
917}
918
919impl Session {
920 async fn run(
921 self,
922 mut receiver: tokio::sync::mpsc::UnboundedReceiver<KalshiWsEvent>,
923 cancellation: CancellationToken,
924 startup: tokio::sync::oneshot::Sender<anyhow::Result<()>>,
925 ) {
926 let mut startup = Some(startup);
927 let result = self
928 .receive(&mut receiver, &cancellation, &mut startup)
929 .await;
930
931 if let Some(startup) = startup {
932 let _ = startup.send(Err(anyhow::anyhow!("initial lifecycle recovery failed")));
933 }
934
935 self.connected.store(false, Ordering::Release);
936 self.books.stop(false);
937
938 if let Err(e) = result {
939 log::warn!("Kalshi data stream stopped: {e}");
940 }
941
942 if let Err(e) = self.ws_client.stop().await {
943 log::warn!("Kalshi WebSocket shutdown failed: {e}");
944 }
945 }
946
947 async fn receive(
948 &self,
949 receiver: &mut tokio::sync::mpsc::UnboundedReceiver<KalshiWsEvent>,
950 cancellation: &CancellationToken,
951 startup: &mut Option<tokio::sync::oneshot::Sender<anyhow::Result<()>>>,
952 ) -> anyhow::Result<()> {
953 let mut refresh_tick = time::interval(self.refresh_interval);
954 refresh_tick.tick().await;
955 let mut health_tick = time::interval(Duration::from_millis(100));
956 health_tick.set_missed_tick_behavior(time::MissedTickBehavior::Skip);
957 let mut generation = None;
958 let mut lifecycle_sequence = None;
959 let mut lifecycle_recovered = false;
960
961 loop {
962 let event = tokio::select! {
963 biased;
964 () = cancellation.cancelled() => return Ok(()),
965 _ = health_tick.tick() => { anyhow::ensure!(!self.sender.is_closed(), "data event receiver closed"); self.books.monitor(&self.ws_client, &self.tasks); self.lifecycle.tick(&self.context, &self.sender, self.clock.get_time_ns())?; continue; },
966 _ = refresh_tick.tick() => { self.refresh(&mut refresh_tick, cancellation).await?; continue; },
967 event = receiver.recv() => event.context("WebSocket event receiver closed")?,
968 };
969
970 let current = event.generation();
971
972 if generation.is_some_and(|generation| current < generation) {
973 continue;
974 }
975
976 let new_generation = generation != Some(current);
977 if new_generation {
978 self.lifecycle.begin_recovery();
979 self.refresh(&mut refresh_tick, cancellation).await?;
980 generation = Some(current);
981 lifecycle_sequence = None;
982 lifecycle_recovered = false;
983 }
984
985 if matches!(&event, KalshiWsEvent::Message { message: KalshiWsMessage::Subscribed { msg, .. }, .. } if msg.channel == KalshiChannel::MarketLifecycleV2)
986 {
987 if !new_generation {
988 self.refresh(&mut refresh_tick, cancellation).await?;
989 }
990
991 lifecycle_recovered = true;
992 }
993
994 if matches!(&event, KalshiWsEvent::Ready { .. }) {
995 if !lifecycle_recovered {
996 self.refresh(&mut refresh_tick, cancellation).await?;
997 }
998
999 lifecycle_recovered = true;
1000
1001 if let Some(startup) = startup.take() {
1002 let _ = startup.send(Ok(()));
1003 }
1004 }
1005
1006 if !self
1007 .sequence(
1008 &event,
1009 &mut lifecycle_sequence,
1010 &mut refresh_tick,
1011 cancellation,
1012 )
1013 .await?
1014 {
1015 continue;
1016 }
1017
1018 self.books.event(
1019 &event,
1020 &self.context.lock().expect("context lock is not poisoned"),
1021 &self.sender,
1022 self.clock.get_time_ns(),
1023 )?;
1024
1025 match event {
1026 KalshiWsEvent::Message {
1027 message: KalshiWsMessage::MarketLifecycleV2(data),
1028 ..
1029 } => {
1030 self.receive_lifecycle(&data, &mut refresh_tick, cancellation)
1031 .await?;
1032 }
1033 KalshiWsEvent::Message { message, .. } => self.dispatch(message)?,
1034 KalshiWsEvent::Error { message, .. } => log::warn!("Kalshi WebSocket: {message}"),
1035 KalshiWsEvent::Ready { .. }
1036 | KalshiWsEvent::BookSequenceGap { .. }
1037 | KalshiWsEvent::BookSnapshotRequested { .. } => {}
1038 }
1039 }
1040 }
1041
1042 async fn receive_lifecycle(
1043 &self,
1044 data: &KalshiDataMessage,
1045 refresh_tick: &mut time::Interval,
1046 cancellation: &CancellationToken,
1047 ) -> anyhow::Result<()> {
1048 if let Some(id) = self
1049 .instruments
1050 .iter()
1051 .find(|id| Some(id.symbol.as_str()) == data.msg["market_ticker"].as_str())
1052 {
1053 self.lifecycle.observe(
1054 *id,
1055 data,
1056 &self.context,
1057 &self.sender,
1058 self.clock.get_time_ns(),
1059 )?;
1060 refresh(
1061 &self.provider,
1062 &[*id],
1063 &self.context,
1064 &self.lifecycle,
1065 &self.sender,
1066 cancellation,
1067 )
1068 .await?;
1069 refresh_tick.reset();
1070
1071 if data.msg["event_type"] == "settled" {
1072 self.recheck_settlement(*id)?;
1073 }
1074 }
1075
1076 Ok(())
1077 }
1078
1079 async fn sequence(
1080 &self,
1081 event: &KalshiWsEvent,
1082 lifecycle_sequence: &mut Option<(u64, u64)>,
1083 refresh_tick: &mut time::Interval,
1084 cancellation: &CancellationToken,
1085 ) -> anyhow::Result<bool> {
1086 if let KalshiWsEvent::Message { message, .. } = event
1087 && let Some((KalshiChannel::MarketLifecycleV2, data)) = message.data()
1088 && let Some(seq) = data.seq
1089 {
1090 if let Some((sid, previous)) = *lifecycle_sequence
1091 && sid == data.sid
1092 {
1093 if seq <= previous {
1094 return Ok(false);
1095 }
1096
1097 if seq != previous + 1 {
1098 self.refresh(refresh_tick, cancellation).await?;
1099 }
1100 }
1101
1102 *lifecycle_sequence = Some((data.sid, seq));
1103 }
1104
1105 Ok(true)
1106 }
1107
1108 async fn refresh(
1109 &self,
1110 refresh_tick: &mut time::Interval,
1111 cancellation: &CancellationToken,
1112 ) -> anyhow::Result<()> {
1113 refresh(
1114 &self.provider,
1115 &self.instruments,
1116 &self.context,
1117 &self.lifecycle,
1118 &self.sender,
1119 cancellation,
1120 )
1121 .await?;
1122 refresh_tick.reset();
1123 Ok(())
1124 }
1125
1126 fn recheck_settlement(&self, id: InstrumentId) -> anyhow::Result<()> {
1127 let provider = Arc::clone(&self.provider);
1128 let context = Arc::clone(&self.context);
1129 let lifecycle = Arc::clone(&self.lifecycle);
1130 let sender = self.sender.clone();
1131 let cancellation = self.tasks.cancellation_token();
1132
1133 self.tasks.spawn(async move {
1134 for millis in [250, 500, 1_000, 2_000] {
1135 let finalized = context
1136 .lock()
1137 .expect("context lock is not poisoned")
1138 .get(&id)
1139 .and_then(|instrument| instrument.info.as_ref())
1140 .is_some_and(|info| info["market"]["status"] == "finalized");
1141
1142 if finalized {
1143 return;
1144 }
1145
1146 tokio::select! {
1147 biased;
1148 () = cancellation.cancelled() => return,
1149 () = time::sleep(Duration::from_millis(millis)) => {}
1150 }
1151
1152 if let Err(e) = refresh(
1153 &provider,
1154 &[id],
1155 &context,
1156 &lifecycle,
1157 &sender,
1158 &cancellation,
1159 )
1160 .await
1161 {
1162 if !cancellation.is_cancelled() {
1163 log::warn!("Kalshi final settlement recheck failed: {e}");
1164 }
1165
1166 return;
1167 }
1168 }
1169 })?;
1170
1171 Ok(())
1172 }
1173
1174 fn dispatch(&self, message: KalshiWsMessage) -> anyhow::Result<()> {
1175 let (data, quotes) = match message {
1176 KalshiWsMessage::Ticker(data) => (data, true),
1177 KalshiWsMessage::Trade(data) => (data, false),
1178 _ => return Ok(()),
1179 };
1180
1181 let Some(ticker) = data
1182 .msg
1183 .get("market_ticker")
1184 .and_then(serde_json::Value::as_str)
1185 else {
1186 log::warn!("Kalshi data frame has no market ticker");
1187 return Ok(());
1188 };
1189
1190 let Some(id) = self
1191 .instruments
1192 .iter()
1193 .find(|id| id.symbol.as_str() == ticker)
1194 .copied()
1195 else {
1196 return Ok(());
1197 };
1198
1199 let demanded = self
1200 .demand
1201 .lock()
1202 .expect("demand lock is not poisoned")
1203 .get(&id)
1204 .is_some_and(|demand| {
1205 if quotes {
1206 demand.quotes > 0
1207 } else {
1208 demand.trades > 0
1209 }
1210 });
1211
1212 if !demanded {
1213 return Ok(());
1214 }
1215
1216 let ts_init = self.clock.get_time_ns();
1217
1218 let result = {
1219 let context = self.context.lock().expect("context lock is not poisoned");
1220
1221 let Some(instrument) = context.get(&id) else {
1222 return Ok(());
1223 };
1224
1225 if quotes {
1226 parse::quote(data.msg, instrument, ts_init).map(|tick| tick.map(Data::Quote))
1227 } else {
1228 parse::trade(data.msg, instrument, ts_init).map(|tick| tick.map(Data::Trade))
1229 }
1230 };
1231
1232 match result {
1233 Ok(Some(data)) => self
1234 .sender
1235 .send(DataEvent::Data(data))
1236 .map_err(|_| anyhow::anyhow!("data event receiver closed"))?,
1237 Ok(None) => {}
1238 Err(e) => log::warn!("Invalid Kalshi market data: {e}"),
1239 }
1240
1241 Ok(())
1242 }
1243}
1244
1245fn subscription(ids: &[InstrumentId], quotes: bool) -> anyhow::Result<KalshiSubscription> {
1246 Ok(KalshiSubscription {
1247 channel: if quotes {
1248 KalshiChannel::Ticker
1249 } else {
1250 KalshiChannel::Trade
1251 },
1252 market_tickers: ids
1253 .iter()
1254 .map(|id| parse_ticker(*id))
1255 .collect::<anyhow::Result<_>>()?,
1256 })
1257}
1258
1259async fn refresh(
1260 provider: &KalshiInstrumentProvider,
1261 ids: &[InstrumentId],
1262 context: &Mutex<HashMap<InstrumentId, BinaryOption>>,
1263 lifecycle: &LifecycleTracker,
1264 sender: &EventSender<DataEvent>,
1265 cancellation: &CancellationToken,
1266) -> anyhow::Result<()> {
1267 let stamp = lifecycle.begin_read();
1268
1269 for id in ids {
1270 let request = RequestInstrument::new(
1271 *id,
1272 None,
1273 None,
1274 None,
1275 UUID4::new(),
1276 provider.clock.get_time_ns(),
1277 None,
1278 );
1279
1280 let instrument = tokio::select! {
1281 biased;
1282 () = cancellation.cancelled() => anyhow::bail!("metadata refresh canceled"),
1283 result = provider.load_instrument(&request) => result?,
1284 };
1285 lifecycle.apply(instrument, stamp, context, sender)?;
1286 }
1287
1288 Ok(())
1289}
1290
1291#[cfg(test)]
1292#[cfg(not(all(feature = "simulation", madsim)))]
1293mod tests {
1294 use std::{
1295 process::Command,
1296 sync::{Barrier, atomic::AtomicUsize},
1297 };
1298
1299 use nautilus_core::UnixNanos;
1300 use rstest::rstest;
1301 use serde_json::Value;
1302
1303 use super::*;
1304 use crate::{
1305 common::{consts::KALSHI_CLIENT_ID, parse::parse_instrument_id},
1306 http::{
1307 models::{Event, Market},
1308 parse::parse_instrument,
1309 },
1310 websocket::messages::KalshiDataMessage,
1311 };
1312
1313 #[allow(
1314 dead_code,
1315 reason = "shared key fixtures serve both session and integration peers"
1316 )]
1317 mod keys {
1318 include!(concat!(
1319 env!("CARGO_MANIFEST_DIR"),
1320 "/tests/integration/keys.rs"
1321 ));
1322 }
1323 mod http_request {
1324 include!(concat!(
1325 env!("CARGO_MANIFEST_DIR"),
1326 "/tests/common/http_request.rs"
1327 ));
1328 }
1329 #[allow(
1330 dead_code,
1331 reason = "shared peer also serves the complete data-client integration suite"
1332 )]
1333 mod peer {
1334 include!(concat!(
1335 env!("CARGO_MANIFEST_DIR"),
1336 "/tests/common/data_peer.rs"
1337 ));
1338 }
1339
1340 #[tokio::test]
1341 async fn slow_periodic_refresh_yields_to_queued_market_data() {
1342 let peer = peer::Peer::new().await;
1343 peer.delay_millis.store(10, Ordering::SeqCst);
1344 let fixtures: Value =
1345 serde_json::from_str(include_str!("../test_data/instruments.json")).unwrap();
1346 let market: Market =
1347 serde_json::from_value(fixtures["definitions"]["live"]["market"].clone()).unwrap();
1348 let event: Event =
1349 serde_json::from_value(fixtures["definitions"]["live"]["event"].clone()).unwrap();
1350 let instrument = parse_instrument(&market, &event, UnixNanos::from(1)).unwrap();
1351 let id = instrument.id;
1352 let (sender, mut output) = tokio::sync::mpsc::unbounded_channel();
1353 let sender: EventSender<DataEvent> = sender.into();
1354 let clock = get_atomic_clock_realtime();
1355
1356 let provider = Arc::new(KalshiInstrumentProvider::new(
1357 KalshiHttpClient::new(&peer.config).unwrap(),
1358 clock,
1359 sender.clone(),
1360 ));
1361
1362 let (ws_client, _events) = KalshiWebSocketClient::new(peer.config.clone()).unwrap();
1363
1364 let tasks = TaskGroup::new();
1365
1366 let session = Session {
1367 provider,
1368 lifecycle: Arc::default(),
1369 books: BookSyncTracker::new(&[id], Duration::from_secs(10)),
1370 tasks: tasks.spawner().unwrap(),
1371 instruments: vec![id],
1372 context: Arc::new(Mutex::new(HashMap::from([(id, instrument)]))),
1373 demand: Arc::new(Mutex::new(HashMap::from([(
1374 id,
1375 Demand {
1376 quotes: 0,
1377 trades: 1,
1378 },
1379 )]))),
1380 sender,
1381 connected: Arc::new(AtomicBool::new(true)),
1382 ws_client,
1383 clock,
1384 refresh_interval: Duration::from_millis(1),
1385 };
1386
1387 let (input, receiver) = tokio::sync::mpsc::unbounded_channel();
1388 let cancellation = CancellationToken::new();
1389
1390 let session = session.run(
1392 receiver,
1393 cancellation.clone(),
1394 tokio::sync::oneshot::channel().0,
1395 );
1396
1397 let run = tokio::spawn(session); let result = time::timeout(Duration::from_secs(1), async {
1400 while peer.requests.load(Ordering::SeqCst) == 0 {
1401 tokio::task::yield_now().await;
1402 }
1403
1404 let payloads: Value =
1405 serde_json::from_str(include_str!("../test_data/market_data.json")).unwrap();
1406 input
1407 .send(KalshiWsEvent::Message {
1408 generation: 0,
1409 message: KalshiWsMessage::Trade(KalshiDataMessage {
1410 id: None,
1411 sid: 1,
1412 seq: Some(1),
1413 sending_ts_ms: None,
1414 msg: payloads["trade"].clone(),
1415 }),
1416 })
1417 .unwrap();
1418
1419 loop {
1420 if let DataEvent::Data(Data::Trade(tick)) = output.recv().await.unwrap() {
1421 return tick;
1422 }
1423 }
1424 })
1425 .await;
1426
1427 cancellation.cancel();
1428 run.await.unwrap();
1429 let tick = result.expect("queued trade must progress after a slow metadata refresh");
1430 assert_eq!(tick.instrument_id, id);
1431 assert_eq!(tick.size.as_decimal(), "7.25".parse().unwrap());
1432 assert_eq!(tick.price.as_decimal(), "0.123456".parse().unwrap());
1433 }
1434
1435 #[rstest]
1436 fn canceled_ready_requests_do_not_poll_their_work() {
1437 let output = Command::new(std::env::current_exe().unwrap())
1438 .args([
1439 "--exact",
1440 "data::tests::canceled_ready_requests_child",
1441 "--test-threads=1",
1442 ])
1443 .env("NAUTILUS_KALSHI_CANCEL_TEST", "1")
1444 .output()
1445 .unwrap();
1446 assert!(
1447 output.status.success(),
1448 "{}",
1449 String::from_utf8_lossy(&output.stdout)
1450 );
1451 assert!(String::from_utf8_lossy(&output.stdout).contains("1 passed; 0 failed;"));
1452 }
1453
1454 #[rstest]
1455 fn canceled_ready_requests_child() {
1456 if std::env::var_os("NAUTILUS_KALSHI_CANCEL_TEST").is_none() {
1457 return;
1458 }
1459
1460 let runtime = tokio::runtime::Builder::new_multi_thread()
1461 .worker_threads(1)
1462 .enable_all()
1463 .build()
1464 .unwrap();
1465 nautilus_common::live::set_runtime(runtime).unwrap();
1466 let (blocked, observed) = std::sync::mpsc::channel();
1467 let gate = Arc::new(Barrier::new(2));
1468 let blocker_gate = Arc::clone(&gate);
1469
1470 let blocker = nautilus_common::live::get_runtime().spawn(async move {
1471 blocked.send(()).unwrap();
1472 blocker_gate.wait();
1473 });
1474
1475 observed.recv_timeout(Duration::from_secs(1)).unwrap();
1476 let (sender, _events) = tokio::sync::mpsc::unbounded_channel();
1477 let id = parse_instrument_id("MARKET-A").unwrap();
1478 let mut client = KalshiDataClient::new(
1479 *KALSHI_CLIENT_ID,
1480 KalshiDataClientConfig::default(),
1481 vec![id],
1482 sender.into(),
1483 )
1484 .unwrap();
1485 let polled = Arc::new(AtomicUsize::new(0));
1486 for _ in 0..64 {
1487 let polled = Arc::clone(&polled);
1488 client
1489 .spawn_request(async move {
1490 polled.fetch_add(1, Ordering::SeqCst);
1491 Ok(())
1492 })
1493 .unwrap();
1494 }
1495
1496 client.stop().unwrap();
1497 gate.wait();
1498 nautilus_common::live::get_runtime().block_on(async {
1499 client.disconnect().await.unwrap();
1500 blocker.await.unwrap();
1501 });
1502
1503 assert_eq!(polled.load(Ordering::SeqCst), 0);
1504 }
1505}