1pub(crate) mod settlement;
19
20mod account;
21mod batch;
22mod context;
23mod mutation;
24mod reports;
25mod snapshot;
26mod stream;
27mod submit;
28
29use std::{
30 cell::RefCell,
31 collections::{HashMap, HashSet},
32 num::NonZeroU64,
33 rc::Rc,
34 sync::{
35 Arc, Mutex,
36 atomic::{AtomicBool, Ordering},
37 },
38 time::Duration,
39};
40
41use anyhow::Context;
42use async_trait::async_trait;
43use nautilus_common::{
44 cache::Cache,
45 clients::ExecutionClient,
46 live::{
47 runner::{try_get_data_event_sender, try_get_exec_event_sender},
48 timer::LiveTimer,
49 },
50 messages::{DataEvent, execution::*},
51 runner::try_get_time_event_sender,
52 timer::TimeEventCallback,
53};
54use nautilus_core::{
55 DurationNanos, Params, UUID4, UnixNanos,
56 time::{AtomicTime, get_atomic_clock_realtime},
57};
58use nautilus_live::{
59 ExecutionClientCore, ExecutionEventEmitter,
60 task::{TaskGroup, TaskGroupGuard},
61};
62use nautilus_model::{
63 accounts::AccountAny,
64 enums::{AccountType, LiquiditySide, OmsType, OrderStatus},
65 events::{OrderDeniedReason, OrderInitialized},
66 identifiers::{
67 AccountId, ClientId, ClientOrderId, InstrumentId, PositionId, Venue, VenueOrderId,
68 },
69 instruments::{BinaryOption, Instrument, InstrumentAny},
70 orders::{Order, OrderAny},
71 reports::{ExecutionMassStatus, FillReport, OrderStatusReport, PositionStatusReport},
72 types::{AccountBalance, Currency, MarginBalance, Money, Price, Quantity},
73};
74use nautilus_network::dst::time::Instant;
75use rust_decimal::Decimal;
76
77use self::{
78 context::RecoveryContextError,
79 mutation::{ADMISSION_TIMEOUT, Command, Mutation, PendingMutation},
80 settlement::Registration,
81 snapshot::{
82 collect_fills, collect_orders, collect_positions_current, collect_recovery_snapshot,
83 collect_snapshot_at, load_definition, timestamp, validate_definition, validate_order_scope,
84 },
85 stream::PrivateStream,
86};
87pub use self::{
88 context::{OrderPlan, PrivateState},
89 reports::{fill as fill_report, order as order_report},
90 snapshot::{KalshiExecutionSnapshot, collect_snapshot},
91 submit::request,
92};
93use crate::{
94 common::{
95 consts::KALSHI_VENUE,
96 parse::{parse_instrument_id, parse_ticker},
97 },
98 config::{KalshiDataClientConfig, KalshiExecutionClientConfig},
99 http::{
100 client::KalshiHttpClient,
101 models::{Fill, HistoricalCutoff, Order as VenueOrder, OrderStatus as VenueOrderStatus},
102 query::FillsQuery,
103 },
104 websocket::{
105 client::KalshiWebSocketClient,
106 messages::{KalshiChannel, KalshiSubscription},
107 },
108};
109
110#[derive(Debug)]
117pub struct KalshiExecutionClient {
118 core: ExecutionClientCore,
119 clock: &'static AtomicTime,
120 config: KalshiExecutionClientConfig,
121 http: KalshiHttpClient,
122 emitter: ExecutionEventEmitter,
123 definitions: RefCell<HashMap<InstrumentId, BinaryOption>>,
124 transport: KalshiDataClientConfig,
125 disposed: bool,
126 private: Arc<Mutex<PrivateState>>,
127 ready: Arc<AtomicBool>,
128 session_tasks: TaskGroup,
129 command_tasks: TaskGroup,
130 ws_client: Option<KalshiWebSocketClient>,
131 refresh: Option<tokio::sync::mpsc::UnboundedSender<()>>,
132 settlement_registration: Option<Registration>,
133 settlement_timer: Option<LiveTimer>,
134}
135
136impl KalshiExecutionClient {
137 pub fn new(
144 core: ExecutionClientCore,
145 config: KalshiExecutionClientConfig,
146 ) -> anyhow::Result<Self> {
147 config.validate()?;
148 anyhow::ensure!(
149 core.venue == *KALSHI_VENUE && core.account_id == config.account_id,
150 "Kalshi execution identity mismatch"
151 );
152 anyhow::ensure!(
153 core.account_type == AccountType::Cash
154 && core.oms_type == OmsType::Netting
155 && core.base_currency == Some(Currency::USD()),
156 "Kalshi requires a USD Cash account with netting OMS"
157 );
158
159 let transport = KalshiDataClientConfig {
160 api_key_id: config.api_key_id.clone(),
161 private_key: config.private_key.clone(),
162 environment: config.environment,
163 base_url_http: config.base_url_http.clone(),
164 base_url_ws: config.base_url_ws.clone(),
165 proxy_url: config.proxy_url.clone(),
166 http_timeout_secs: config.http_timeout_secs,
167 ws_timeout_secs: config.ws_timeout_secs,
168 transport_backend: config.transport_backend,
169 ..Default::default()
170 };
171
172 let http = KalshiHttpClient::new_authenticated(&transport)?;
173 let clock = get_atomic_clock_realtime();
174
175 let mut emitter = ExecutionEventEmitter::new(
176 clock,
177 core.trader_id,
178 core.account_id,
179 core.account_type,
180 core.base_currency,
181 );
182
183 if let Some(sender) = try_get_exec_event_sender() {
184 emitter.set_sender(sender);
185 }
186
187 core.set_disconnected();
188 Ok(Self {
189 core,
190 clock,
191 config,
192 http,
193 emitter,
194 definitions: RefCell::new(HashMap::new()),
195 transport,
196 disposed: false,
197 private: Arc::new(Mutex::new(PrivateState::new())),
198 ready: Arc::new(AtomicBool::new(false)),
199 session_tasks: TaskGroup::new(),
200 command_tasks: TaskGroup::new(),
201 ws_client: None,
202 refresh: None,
203 settlement_registration: None,
204 settlement_timer: None,
205 })
206 }
207
208 #[cfg(all(test, not(all(feature = "simulation", madsim))))]
209 pub(crate) fn config(&self) -> &KalshiExecutionClientConfig {
210 &self.config
211 }
212
213 #[cfg(all(test, not(all(feature = "simulation", madsim))))]
214 pub(crate) fn core(&self) -> &ExecutionClientCore {
215 &self.core
216 }
217
218 async fn finish_shutdown(&self) -> anyhow::Result<()> {
219 let (session, commands) = tokio::join!(
220 self.session_tasks
221 .finish_shutdown(Duration::from_millis(100), Duration::from_secs(1)),
222 self.command_tasks
223 .finish_shutdown(Duration::from_millis(100), Duration::from_secs(1)),
224 );
225 session?;
226 commands?;
227 Ok(())
228 }
229
230 async fn definition(&self, ticker: &str, ts_init: UnixNanos) -> anyhow::Result<BinaryOption> {
231 let id = parse_instrument_id(ticker)?;
232 let known = self.definitions.borrow().get(&id).cloned();
233 if let Some(instrument) = known {
234 return Ok(instrument);
235 }
236
237 let cached = self.core.cache().instrument(&id).cloned();
238 let unloaded = cached.is_none();
239
240 let instrument = if let Some(instrument) = cached {
241 let InstrumentAny::BinaryOption(instrument) = instrument else {
242 anyhow::bail!("Kalshi report requires a binary instrument");
243 };
244
245 instrument
246 } else {
247 load_definition(&self.http, ticker, ts_init).await?
248 };
249
250 validate_definition(&instrument, self.config.exchange_index)?;
251 if unloaded && let Some(sender) = try_get_data_event_sender() {
252 let data = InstrumentAny::BinaryOption(instrument.clone()).into();
253 sender
254 .send(DataEvent::Data(data))
255 .map_err(|_| anyhow::anyhow!("instrument receiver closed"))?;
256 }
257
258 self.definitions.borrow_mut().insert(id, instrument.clone());
259 Ok(instrument)
260 }
261
262 fn client_order_id(&self, value: &VenueOrder) -> anyhow::Result<Option<ClientOrderId>> {
263 let venue_order_id = VenueOrderId::new_checked(&value.order_id)?;
264
265 let wire_id = if value.client_order_id.is_empty() {
266 None
267 } else {
268 Some(ClientOrderId::new_checked(&value.client_order_id)?)
269 };
270
271 let mapped_id = self.core.cache().client_order_id(&venue_order_id).copied();
272 anyhow::ensure!(
273 wire_id
274 .zip(mapped_id)
275 .is_none_or(|(wire, mapped)| wire == mapped),
276 "cached client order identity mismatch"
277 );
278 Ok(wire_id.or(mapped_id))
279 }
280
281 fn cached_order(&self, value: &VenueOrder) -> anyhow::Result<Option<OrderAny>> {
282 let client_order_id = self.client_order_id(value)?;
283 let cache = self.core.cache();
284 let cached =
285 client_order_id.and_then(|id| cache.order_ref(&id).map(|order| order.cloned()));
286
287 if let Some(order) = &cached {
288 let venue_order_id = VenueOrderId::new_checked(&value.order_id)?;
289 anyhow::ensure!(
290 order.venue_order_id().is_none_or(|id| id == venue_order_id)
291 && cache
292 .venue_order_id(&order.client_order_id())
293 .is_none_or(|id| *id == venue_order_id),
294 "cached venue order identity mismatch"
295 );
296 }
297
298 Ok(cached)
299 }
300
301 async fn order_report(
302 &self,
303 value: &VenueOrder,
304 ts_init: UnixNanos,
305 ) -> anyhow::Result<Option<OrderStatusReport>> {
306 let definition = self.definition(&value.ticker, ts_init).await?;
307 let cached = self.cached_order(value)?;
308 let report = reports::order(
309 value,
310 &definition,
311 self.core.account_id,
312 cached.as_ref(),
313 ts_init,
314 )?;
315 Ok(report.filter(|_| cached.is_some()))
317 }
318
319 async fn order_report_aggregate(
320 &self,
321 value: &VenueOrder,
322 ts_init: UnixNanos,
323 max_pages: u32,
324 cutoff: Option<&HistoricalCutoff>,
325 ) -> anyhow::Result<Option<OrderStatusReport>> {
326 let recovered = self
327 .private
328 .lock()
329 .expect("private state lock is not poisoned")
330 .source_order(value)?;
331 let report = self.order_report(value, ts_init).await?;
332 if report.is_some() {
333 return Ok(report);
334 }
335
336 if let Some(cached) = recovered
337 .as_ref()
338 .filter(|order| order.status() == OrderStatus::Rejected)
339 {
340 let definition = self.definition(&value.ticker, ts_init).await?;
341 let report = reports::order_aggregate(
342 value,
343 &definition,
344 self.core.account_id,
345 cached,
346 ts_init,
347 )?;
348
349 if report.is_some() {
350 return Ok(report);
351 }
352 }
353
354 let venue_order_id = VenueOrderId::new_checked(&value.order_id)?;
355 let missing_context = self.cached_order(value)?.is_none()
356 && self.core.cache().client_order_id(&venue_order_id).is_none();
357
358 if missing_context && !value.fill_count_fp.0.is_zero() {
359 let e = RecoveryContextError::Order;
360 log::error!("Kalshi order recovery failed: {e}");
361 return Err(e.into());
362 }
363
364 let unfilled_external = recovered
365 .as_ref()
366 .is_some_and(|order| order.strategy_id().is_external());
367 anyhow::ensure!(
368 missing_context && (unfilled_external || recovered.is_none()),
369 "order command metadata or canceled total is not authoritative"
370 );
371
372 let cutoff = match cutoff {
373 Some(cutoff) => cutoff.clone(),
374 None => self.http.get_historical_cutoff().await?,
375 };
376
377 let query = FillsQuery {
378 ticker: Some(value.ticker.clone()),
379 order_id: Some(value.order_id.clone()),
380 exchange_index: self.config.exchange_index,
381 subaccount: self.config.subaccount,
382 ..Default::default()
383 };
384
385 let fills = collect_fills(&self.http, &query, None, ts_init, &cutoff, max_pages).await?;
386 anyhow::ensure!(
387 fills.iter().all(|fill| fill.order_id != value.order_id),
388 "external order recovery lacks command metadata for collected fills"
389 );
390 Ok(None)
391 }
392
393 async fn fill_report(
394 &self,
395 value: &Fill,
396 source: &VenueOrder,
397 ts_init: UnixNanos,
398 ) -> anyhow::Result<FillReport> {
399 let definition = self.definition(&value.ticker, ts_init).await?;
400 let mut report = reports::fill(value, &definition, self.core.account_id, source, ts_init)?;
401 let cached = self.cached_order(source)?;
402 if let Some(cached) = cached {
403 anyhow::ensure!(
404 cached.instrument_id() == report.instrument_id
405 && cached.order_side() == report.order_side
406 && cached
407 .account_id()
408 .is_none_or(|account| account == self.core.account_id),
409 "cached fill identity mismatch"
410 );
411 report.client_order_id = Some(cached.client_order_id());
412 }
413
414 Ok(report)
415 }
416
417 fn admit_reports(
418 &self,
419 orders: &[OrderStatusReport],
420 fills: &[FillReport],
421 ) -> anyhow::Result<()> {
422 let result = self
423 .private
424 .lock()
425 .expect("private state lock is not poisoned")
426 .admit_reports(&self.core.cache(), orders, fills);
427
428 if result.is_err() {
429 self.ready.store(false, Ordering::Release);
430 }
431
432 result
433 }
434
435 fn observe_settlement(&self) {
436 let private = self
437 .private
438 .lock()
439 .expect("private state lock is not poisoned");
440 private
441 .barrier
442 .lock()
443 .expect("settlement barrier lock")
444 .observe(&self.core.cache(), self.core.account_id);
445 }
446
447 fn start_settlement_timer(&mut self) {
448 if self.settlement_timer.is_some() {
449 return;
450 }
451
452 let Some(sender) = try_get_time_event_sender() else {
453 return;
454 };
455
456 let core = self.core.clone();
457 let private = Arc::downgrade(&self.private);
458 let callback = TimeEventCallback::RustLocal(Rc::new(move |_| {
459 if let Some(private) = private.upgrade() {
460 let private = private.lock().expect("private state lock is not poisoned");
461 private
462 .barrier
463 .lock()
464 .expect("settlement barrier lock")
465 .observe(&core.cache(), core.account_id);
466 }
467 }));
468
469 let mut timer = LiveTimer::new(
470 ustr::Ustr::from(format!("kalshi-settlement-{}", self.core.client_id).as_str()),
471 NonZeroU64::new(100_000_000).expect("nonzero interval"),
472 self.clock.get_time_ns(),
473 None,
474 callback,
475 false,
476 Some(sender),
477 );
478
479 timer.start();
480 self.settlement_timer = Some(timer);
481 }
482
483 fn restore_cache(&self) -> anyhow::Result<()> {
484 let cache = self.core.cache();
485 if let Some(account) = cache.account_owned(&self.core.account_id) {
486 anyhow::ensure!(
487 matches!(account, AccountAny::Cash(ref account) if !account.base.calculate_account_state && !account.allow_borrowing),
488 "Kalshi bootstrap requires reported Cash without borrowing"
489 );
490 }
491
492 let mut private = self
493 .private
494 .lock()
495 .expect("private state lock is not poisoned");
496 private.invalidate();
497
498 let orders: Vec<_> = cache
499 .orders(Some(&KALSHI_VENUE), None, None, None, None)
500 .into_iter()
501 .filter(|order| {
502 cache.client_id(&order.client_order_id()) == Some(&self.core.client_id)
503 && order
504 .account_id()
505 .is_none_or(|id| id == self.core.account_id)
506 })
507 .collect();
508
509 if orders
510 .iter()
511 .any(|order| private.requires_rebase(&order.cloned()))
512 {
513 private.rebase();
514 }
515
516 for order in orders {
517 if let Some(InstrumentAny::BinaryOption(definition)) =
518 cache.instrument(&order.instrument_id())
519 {
520 self.definitions
521 .borrow_mut()
522 .insert(definition.id, definition.clone());
523 }
524
525 private.restore(order.cloned());
526 }
527
528 private.seed_positions(
529 cache
530 .positions_open(
531 Some(&KALSHI_VENUE),
532 None,
533 None,
534 Some(&self.core.account_id),
535 None,
536 )
537 .into_iter()
538 .map(|position| {
539 (
540 position.instrument_id,
541 position.signed_decimal_qty(),
542 position.ts_last,
543 )
544 }),
545 )?;
546
547 private
548 .barrier
549 .lock()
550 .expect("settlement barrier lock")
551 .observe(&cache, self.core.account_id);
552
553 Ok(())
554 }
555}
556
557#[async_trait(?Send)]
558impl ExecutionClient for KalshiExecutionClient {
559 fn is_connected(&self) -> bool {
560 self.observe_settlement();
561
562 if self
563 .private
564 .lock()
565 .expect("private state lock is not poisoned")
566 .barrier
567 .lock()
568 .expect("settlement barrier lock")
569 .is_blocked()
570 {
571 return false;
572 }
573
574 if !self.core.is_connected()
575 || !self.ready.load(Ordering::Acquire)
576 || !self
577 .ws_client
578 .as_ref()
579 .is_some_and(KalshiWebSocketClient::is_active)
580 {
581 return false;
582 }
583
584 let private = self
585 .private
586 .lock()
587 .expect("private state lock is not poisoned");
588
589 if private.epoch.is_none()
590 || private.epoch
591 != self
592 .ws_client
593 .as_ref()
594 .and_then(KalshiWebSocketClient::connection_epoch)
595 {
596 return false;
597 }
598
599 let session = private.session.clone();
600 drop(private);
601 self.core
602 .cache()
603 .account(&self.core.account_id)
604 .and_then(|account| account.last_event())
605 .and_then(|event| event.info)
606 .and_then(|info| {
607 info.get("kalshi_session")
608 .and_then(serde_json::Value::as_str)
609 .map(String::from)
610 })
611 .is_some_and(|value| value == session)
612 }
613
614 fn client_id(&self) -> ClientId {
615 self.core.client_id
616 }
617
618 fn account_id(&self) -> AccountId {
619 self.core.account_id
620 }
621
622 fn venue(&self) -> Venue {
623 *KALSHI_VENUE
624 }
625
626 fn oms_type(&self) -> OmsType {
627 OmsType::Netting
628 }
629
630 fn get_account(&self) -> Option<AccountAny> {
631 self.core.cache().account_owned(&self.core.account_id)
632 }
633
634 fn retain_unresolved_submissions(&self) -> bool {
635 true
636 }
637
638 fn provides_bulk_position_coverage(&self, _instrument_id: InstrumentId) -> bool {
639 false
640 }
641
642 fn calculate_commission(
643 &self,
644 _instrument: &InstrumentAny,
645 _last_qty: Quantity,
646 _last_px: Price,
647 _liquidity_side: LiquiditySide,
648 ) -> anyhow::Result<Option<Money>> {
649 anyhow::bail!("Kalshi reconciliation requires an authoritative fill fee")
650 }
651
652 fn generate_account_state(
653 &self,
654 balances: Vec<AccountBalance>,
655 margins: Vec<MarginBalance>,
656 reported: bool,
657 ts_event: UnixNanos,
658 info: Option<Params>,
659 ) -> anyhow::Result<()> {
660 self.emitter
661 .try_emit_account_state(balances, margins, reported, ts_event, info)
662 }
663
664 fn start(&mut self) -> anyhow::Result<()> {
665 anyhow::ensure!(!self.disposed, "Kalshi execution client is disposed");
666 let sender = try_get_exec_event_sender().context("execution sender is not installed")?;
667 self.emitter.set_sender(sender);
668
669 if self.settlement_registration.is_none()
670 && let Some(sender) = try_get_data_event_sender()
671 {
672 let private = self
673 .private
674 .lock()
675 .expect("private state lock is not poisoned");
676 self.settlement_registration = Some(Registration::new(sender, &private.barrier));
677 }
678
679 self.start_settlement_timer();
680 self.core.set_started();
681 Ok(())
682 }
683
684 fn stop(&mut self) -> anyhow::Result<()> {
685 self.core.set_stopped();
686 self.core.set_disconnected();
687 self.ready.store(false, Ordering::Release);
688 self.private
689 .lock()
690 .expect("private state lock is not poisoned")
691 .invalidate();
692
693 if let Some(mut timer) = self.settlement_timer.take() {
694 timer.cancel();
695 }
696
697 self.session_tasks.begin_shutdown();
698 self.command_tasks.begin_shutdown();
699 self.refresh = None;
700 self.ws_client = None;
701 Ok(())
702 }
703
704 fn reset(&mut self) -> anyhow::Result<()> {
705 self.stop()?;
706 self.definitions.borrow_mut().clear();
707 Ok(())
708 }
709
710 fn dispose(&mut self) -> anyhow::Result<()> {
711 self.reset()?;
712 self.settlement_registration = None;
713 self.disposed = true;
714 Ok(())
715 }
716
717 async fn connect(&mut self) -> anyhow::Result<()> {
718 anyhow::ensure!(!self.disposed, "Kalshi execution client is disposed");
719 anyhow::ensure!(
720 self.emitter.is_initialized(),
721 "Kalshi bootstrap requires an execution sender"
722 );
723
724 if self.core.is_connected()
725 && self
726 .ws_client
727 .as_ref()
728 .is_some_and(KalshiWebSocketClient::is_active)
729 {
730 return Ok(());
731 }
732
733 self.stop()?;
734 self.finish_shutdown().await?;
735 self.session_tasks.start_generation()?;
736 self.command_tasks.start_generation()?;
737 self.restore_cache()?;
738 self.start_settlement_timer();
739
740 let (ws_client, receiver) = KalshiWebSocketClient::new(self.transport.clone())?;
741 for channel in [
742 KalshiChannel::UserOrders,
743 KalshiChannel::Fill,
744 KalshiChannel::MarketPositions,
745 ] {
746 ws_client.subscribe(KalshiSubscription {
747 channel,
748 market_tickers: Vec::new(),
749 })?;
750 }
751
752 let (requests, pending) = tokio::sync::mpsc::unbounded_channel();
753 let (startup, initialized) = tokio::sync::oneshot::channel();
754 let ready = Arc::clone(&self.ready);
755 let guard = TaskGroupGuard::new(&[&self.session_tasks, &self.command_tasks], move || {
756 ready.store(false, Ordering::Release);
757 });
758
759 let stream = PrivateStream {
760 config: self.config.clone(),
761 http: self.http.clone(),
762 emitter: self.emitter.clone(),
763 data_sender: try_get_data_event_sender(),
764 state: Arc::clone(&self.private),
765 definitions: self.definitions.borrow().clone(),
766 instruments: self
767 .core
768 .cache()
769 .instruments(&KALSHI_VENUE, None)
770 .iter()
771 .map(|instrument| instrument.id())
772 .collect(),
773 ready: Arc::clone(&self.ready),
774 ws_client: ws_client.clone(),
775 };
776
777 self.session_tasks.spawn(stream.run(
778 receiver,
779 pending,
780 self.session_tasks.cancellation_token(),
781 startup,
782 ))?;
783 self.refresh = Some(requests);
784 self.ws_client = Some(ws_client.clone());
785 let result = async {
786 ws_client.connect().await?;
787 nautilus_common::live::dst::time::timeout(
788 Duration::from_secs(self.config.ws_timeout_secs),
789 initialized,
790 )
791 .await
792 .context("Kalshi bootstrap timed out")?
793 .context("Kalshi bootstrap stopped")??;
794 nautilus_common::live::dst::time::timeout(
795 Duration::from_secs(self.config.ws_timeout_secs),
796 async {
797 loop {
798 let session = self
799 .private
800 .lock()
801 .expect("private state lock is not poisoned")
802 .session
803 .clone();
804
805 if let Some(AccountAny::Cash(account)) = self.get_account() {
806 anyhow::ensure!(
807 !account.base.calculate_account_state && !account.allow_borrowing,
808 "Kalshi bootstrap account policy mismatch"
809 );
810
811 if account
812 .base
813 .base_last_event()
814 .and_then(|event| event.info)
815 .is_some_and(|info| {
816 info.get("kalshi_session")
817 .and_then(serde_json::Value::as_str)
818 == Some(session.as_str())
819 })
820 {
821 break;
822 }
823 }
824
825 nautilus_common::live::dst::time::sleep(Duration::from_millis(10)).await;
826 }
827
828 Ok::<_, anyhow::Error>(())
829 },
830 )
831 .await
832 .context("Kalshi bootstrap account observation timed out")??;
833
834 Ok::<_, anyhow::Error>(())
835 }
836 .await;
837
838 if let Err(e) = result {
839 drop(guard);
840 self.stop()?;
841 self.finish_shutdown().await?;
842 return Err(e);
843 }
844
845 self.core.set_started();
846 self.core.set_connected();
847 guard.disarm();
848 Ok(())
849 }
850
851 async fn disconnect(&mut self) -> anyhow::Result<()> {
852 self.stop()?;
853 self.finish_shutdown().await?;
854 Ok(())
855 }
856
857 fn submit_order(&self, cmd: SubmitOrder) -> anyhow::Result<()> {
858 let mut order = self.submission_order(&cmd)?;
859 if order.order_list_id().is_some() {
860 self.private
861 .lock()
862 .expect("private state lock is not poisoned")
863 .deny_submission(
864 &mut order,
865 "VALIDATION_FAILED: unsupported Kalshi limit instruction combination",
866 &self.emitter,
867 )?;
868 return Ok(());
869 }
870
871 if let Some(submission) = self.submission(order, &cmd)?
872 && let Err(e) = self.command_tasks.spawn(submission.run())
873 {
874 log::warn!("Kalshi submission task was not registered: {e}");
875 }
876
877 Ok(())
878 }
879
880 fn submit_order_list(&self, cmd: SubmitOrderList) -> anyhow::Result<()> {
881 cmd.order_list.validate()?;
882 anyhow::ensure!(
883 cmd.order_list.strategy_id == cmd.strategy_id
884 && cmd.instrument_id == cmd.order_list.instrument_id
885 && cmd.exec_algorithm_id.is_none()
886 && cmd.order_inits.len() == cmd.order_list.client_order_ids.len(),
887 "Kalshi order-list identity mismatch"
888 );
889
890 if !self
891 .private
892 .lock()
893 .expect("private state lock is not poisoned")
894 .batches
895 .insert(cmd.command_id)
896 {
897 return Ok(());
898 }
899
900 let mut children = Vec::new();
901
902 for (id, init) in cmd.order_list.client_order_ids.iter().zip(&cmd.order_inits) {
903 anyhow::ensure!(
904 *id == init.client_order_id,
905 "Kalshi order-list child identity mismatch"
906 );
907
908 let child = SubmitOrder::new(
909 cmd.trader_id,
910 cmd.client_id,
911 cmd.strategy_id,
912 init.instrument_id,
913 *id,
914 init.clone(),
915 None,
916 cmd.position_id,
917 cmd.params.clone(),
918 cmd.command_id,
919 cmd.ts_init,
920 cmd.correlation_id,
921 );
922
923 let order = self.submission_order(&child)?;
924 children.push((order, child));
925 }
926
927 let mut submissions = Vec::new();
928
929 let prepared = (|| -> anyhow::Result<()> {
930 for (order, child) in &children {
931 submissions.push(
932 self.submission(order.clone(), child)?
933 .context("Kalshi order-list child failed validation")?,
934 );
935 }
936
937 Ok(())
938 })();
939
940 if let Err(e) = prepared {
941 let reason = format!("VALIDATION_FAILED: {e}");
942 for child in &mut submissions {
943 child.deny(&reason);
944 }
945
946 drop(submissions);
947 let mut state = self
948 .private
949 .lock()
950 .expect("private state lock is not poisoned");
951
952 for (mut order, _) in children {
953 if !state.orders.contains_key(&order.client_order_id()) {
954 state.deny_submission(&mut order, &reason, &self.emitter)?;
955 }
956 }
957
958 return Ok(());
959 }
960
961 if let Err(e) = self
962 .command_tasks
963 .spawn(batch::SubmissionBatch { submissions }.run())
964 {
965 log::warn!("Kalshi order-list task was not registered: {e}");
966 }
967
968 Ok(())
969 }
970
971 fn modify_order(&self, cmd: ModifyOrder) -> anyhow::Result<()> {
972 self.mutate(&Command::Modify(cmd))
973 }
974
975 fn batch_modify_orders(&self, _cmd: BatchModifyOrders) -> anyhow::Result<()> {
976 anyhow::bail!("Kalshi batch modification is not available")
977 }
978
979 fn cancel_order(&self, cmd: CancelOrder) -> anyhow::Result<()> {
980 self.mutate(&Command::Cancel(cmd))
981 }
982
983 fn cancel_all_orders(&self, cmd: CancelAllOrders) -> anyhow::Result<()> {
984 let command_id = cmd.causation_id.unwrap_or(cmd.command_id);
985 anyhow::ensure!(
986 cmd.trader_id == self.core.trader_id
987 && cmd.client_id.is_none_or(|id| id == self.core.client_id)
988 && cmd.params.as_ref().is_none_or(|params| params.is_empty()),
989 "Kalshi cancel-all identity or parameters mismatch"
990 );
991 let cache = self.core.cache();
992 let state = self
993 .private
994 .lock()
995 .expect("private state lock is not poisoned");
996
997 if state.batches.contains(&command_id) {
998 return Ok(());
999 }
1000
1001 let mut cancels = Vec::new();
1002
1003 for cached in cache.orders(
1004 Some(&KALSHI_VENUE),
1005 Some(&cmd.instrument_id),
1006 Some(&cmd.strategy_id),
1007 None,
1008 cmd.order_side,
1009 ) {
1010 let id = cached.client_order_id();
1011 let cached = cached.cloned();
1012 let order = Self::claimed_order(&state, &cached);
1013
1014 if order.is_closed()
1015 || order.is_emulated()
1016 || order.exec_algorithm_id().is_some()
1017 || cache.client_id(&id) != Some(&self.core.client_id)
1018 || order
1019 .account_id()
1020 .is_some_and(|id| id != self.core.account_id)
1021 || order.trader_id() != cmd.trader_id
1022 || order.strategy_id() != cmd.strategy_id
1023 || order.instrument_id() != cmd.instrument_id
1024 || cmd
1025 .order_side
1026 .is_some_and(|side| side != order.order_side())
1027 || !state.orders.contains_key(&id) && !state.submissions.contains(&id)
1028 {
1029 continue;
1030 }
1031
1032 let cancel = CancelOrder::new(
1033 cmd.trader_id,
1034 Some(self.core.client_id),
1035 cmd.strategy_id,
1036 order.instrument_id(),
1037 id,
1038 order.venue_order_id(),
1039 UUID4::new(),
1040 cmd.ts_init,
1041 cmd.params.clone(),
1042 cmd.correlation_id.or(Some(cmd.command_id)),
1043 );
1044
1045 cancels.push(cancel);
1046 }
1047
1048 drop(state);
1049 drop(cache);
1050 cancels.sort_by_key(|child| child.client_order_id);
1051 self.cancel_batch(cancels, command_id)
1052 }
1053
1054 fn batch_cancel_orders(&self, cmd: BatchCancelOrders) -> anyhow::Result<()> {
1055 anyhow::ensure!(
1056 cmd.trader_id == self.core.trader_id
1057 && cmd.client_id.is_none_or(|id| id == self.core.client_id)
1058 && cmd.params.as_ref().is_none_or(|params| params.is_empty())
1059 && cmd
1060 .cancels
1061 .iter()
1062 .all(|child| child.trader_id == cmd.trader_id
1063 && child.strategy_id == cmd.strategy_id
1064 && child.instrument_id == cmd.instrument_id),
1065 "Kalshi batch cancellation identity or parameters mismatch"
1066 );
1067 self.cancel_batch(cmd.cancels, cmd.command_id)
1068 }
1069
1070 fn query_account(&self, cmd: QueryAccount) -> anyhow::Result<()> {
1071 anyhow::ensure!(
1072 cmd.account_id == self.core.account_id
1073 && cmd.trader_id == self.core.trader_id
1074 && cmd.client_id.is_none_or(|id| id == self.core.client_id)
1075 && cmd.params.is_none(),
1076 "Kalshi account query identity or parameters mismatch"
1077 );
1078 self.refresh
1079 .as_ref()
1080 .context("Kalshi account bootstrap is not active")?
1081 .send(())
1082 .map_err(|_| anyhow::anyhow!("Kalshi account refresh stopped"))
1083 }
1084
1085 fn query_order(&self, cmd: QueryOrder) -> anyhow::Result<()> {
1086 let order = self.core.get_order(&cmd.client_order_id)?;
1087 anyhow::ensure!(
1088 cmd.trader_id == self.core.trader_id
1089 && cmd.strategy_id == order.strategy_id()
1090 && cmd.instrument_id == order.instrument_id()
1091 && cmd.client_id.is_none_or(|id| id == self.core.client_id)
1092 && cmd
1093 .venue_order_id
1094 .zip(order.venue_order_id())
1095 .is_none_or(|(requested, actual)| requested == actual)
1096 && order
1097 .account_id()
1098 .is_none_or(|id| id == self.core.account_id)
1099 && cmd.params.is_none()
1100 && self.core.cache().client_id(&cmd.client_order_id) == Some(&self.core.client_id),
1101 "Kalshi order query identity or parameters mismatch"
1102 );
1103 let pending = !self
1104 .private
1105 .lock()
1106 .expect("private state lock is not poisoned")
1107 .mutations
1108 .is_empty();
1109
1110 if !pending {
1111 self.ready.store(false, Ordering::Release);
1112 self.restore_cache()?;
1113 }
1114
1115 self.refresh
1116 .as_ref()
1117 .context("Kalshi account bootstrap is not active")?
1118 .send(())
1119 .map_err(|_| anyhow::anyhow!("Kalshi private recovery stopped"))
1120 }
1121
1122 async fn generate_order_status_report(
1123 &self,
1124 cmd: &GenerateOrderStatusReport,
1125 ) -> anyhow::Result<Option<OrderStatusReport>> {
1126 let max_pages = validate_request(cmd.params.as_ref(), None, None)?;
1127 anyhow::ensure!(
1128 cmd.client_order_id.is_some() || cmd.venue_order_id.is_some(),
1129 "targeted order report requires an order identity"
1130 );
1131
1132 if let Some(id) = cmd.instrument_id {
1133 parse_ticker(id)?;
1134 }
1135
1136 let ts_init = self.clock.get_time_ns();
1137 let records =
1138 collect_orders(&self.http, &self.config.account_query(), None, max_pages).await?;
1139
1140 let mut matches = Vec::new();
1141
1142 for value in records.values() {
1143 let client_order_id = self.client_order_id(value)?;
1144 if cmd
1145 .venue_order_id
1146 .is_some_and(|id| id.as_str() == value.order_id)
1147 || cmd
1148 .client_order_id
1149 .is_some_and(|id| Some(id) == client_order_id)
1150 {
1151 matches.push((value, client_order_id));
1152 }
1153 }
1154
1155 if matches.is_empty() {
1156 return Ok(None);
1157 }
1158
1159 anyhow::ensure!(
1160 matches.len() == 1,
1161 "targeted order identities are ambiguous"
1162 );
1163 let (value, client_order_id) = matches[0];
1164 anyhow::ensure!(
1165 cmd.venue_order_id
1166 .is_none_or(|id| id.as_str() == value.order_id)
1167 && cmd
1168 .client_order_id
1169 .is_none_or(|id| Some(id) == client_order_id)
1170 && cmd.instrument_id.is_none_or(
1171 |id| parse_instrument_id(&value.ticker).is_ok_and(|actual| actual == id)
1172 ),
1173 "targeted order identity mismatch"
1174 );
1175 let report = self
1176 .order_report(value, ts_init)
1177 .await?
1178 .context("order command metadata or canceled total is not authoritative")?;
1179 self.admit_reports(std::slice::from_ref(&report), &[])?;
1180 Ok(Some(report))
1181 }
1182
1183 async fn generate_order_status_reports(
1184 &self,
1185 cmd: &GenerateOrderStatusReports,
1186 ) -> anyhow::Result<Vec<OrderStatusReport>> {
1187 let max_pages = validate_request(cmd.params.as_ref(), cmd.start, cmd.end)?;
1188 if let Some(id) = cmd.instrument_id {
1189 parse_ticker(id)?;
1190 }
1191
1192 let ts_init = self.clock.get_time_ns();
1193 let records = collect_orders(
1194 &self.http,
1195 &self.config.account_query(),
1196 cmd.instrument_id.as_ref().map(|id| id.symbol.as_str()),
1197 max_pages,
1198 )
1199 .await?;
1200 let mut reports = Vec::new();
1201 let mut omitted = 0;
1202
1203 for value in records.values() {
1204 if cmd
1205 .instrument_id
1206 .is_some_and(|id| id.symbol.as_str() != value.ticker)
1207 || cmd.open_only && value.status != VenueOrderStatus::Resting
1208 {
1209 continue;
1210 }
1211
1212 if value.status != VenueOrderStatus::Resting
1213 && !order_in_window(value, cmd.start, cmd.end)?
1214 {
1215 continue;
1216 }
1217
1218 match self
1219 .order_report_aggregate(value, ts_init, max_pages, None)
1220 .await?
1221 {
1222 Some(report) => reports.push(report),
1223 None => omitted += 1,
1224 }
1225 }
1226
1227 if omitted > 0 {
1228 log::warn!(
1229 "Kalshi bulk order reports omit {omitted} unfilled external order(s), command metadata unavailable"
1230 );
1231 }
1232
1233 reports.sort_by_key(|report| report.venue_order_id);
1234 self.admit_reports(&reports, &[])?;
1235 Ok(reports)
1236 }
1237
1238 async fn generate_fill_reports(
1239 &self,
1240 cmd: GenerateFillReports,
1241 ) -> anyhow::Result<Vec<FillReport>> {
1242 let max_pages = validate_request(cmd.params.as_ref(), cmd.start, cmd.end)?;
1243 if let Some(id) = cmd.instrument_id {
1244 parse_ticker(id)?;
1245 }
1246
1247 let ts_init = self.clock.get_time_ns();
1248 let cutoff = self.http.get_historical_cutoff().await?;
1249 let ticker = cmd.instrument_id.as_ref().map(|id| id.symbol.as_str());
1250 let orders =
1251 collect_orders(&self.http, &self.config.account_query(), ticker, max_pages).await?;
1252
1253 let query = FillsQuery {
1254 ticker: ticker.map(String::from),
1255 order_id: cmd.venue_order_id.map(|id| id.to_string()),
1256 exchange_index: self.config.exchange_index,
1257 subaccount: self.config.subaccount,
1258 ..Default::default()
1259 };
1260
1261 let fills =
1262 collect_fills(&self.http, &query, cmd.start, ts_init, &cutoff, max_pages).await?;
1263 let mut reports = Vec::new();
1264
1265 for value in &fills {
1266 if cmd
1267 .instrument_id
1268 .is_some_and(|id| id.symbol.as_str() != value.ticker)
1269 || cmd
1270 .venue_order_id
1271 .is_some_and(|id| id.as_str() != value.order_id)
1272 {
1273 continue;
1274 }
1275
1276 let ts_event = timestamp(&value.created_time)?;
1277
1278 if cmd.end.is_some_and(|end| ts_event > end) {
1279 continue;
1280 }
1281
1282 let order = orders
1283 .get(value.order_id.as_str())
1284 .context("fill lacks order evidence")?;
1285 reports.push(self.fill_report(value, order, ts_init).await?);
1286 }
1287
1288 let selected_orders = orders.values().filter(|order| {
1289 cmd.instrument_id
1290 .is_none_or(|id| id.symbol.as_str() == order.ticker)
1291 && cmd
1292 .venue_order_id
1293 .is_none_or(|id| id.as_str() == order.order_id)
1294 });
1295
1296 validate_fill_coverage(selected_orders, &reports, cmd.start, cmd.end)?;
1297 self.admit_reports(&[], &reports)?;
1298 Ok(reports)
1299 }
1300
1301 async fn generate_position_status_reports(
1302 &self,
1303 cmd: &GeneratePositionStatusReports,
1304 ) -> anyhow::Result<Vec<PositionStatusReport>> {
1305 let max_pages = validate_request(cmd.params.as_ref(), cmd.start, cmd.end)?;
1306 if let Some(id) = cmd.instrument_id {
1307 parse_ticker(id)?;
1308 }
1309
1310 let ts_init = self.clock.get_time_ns();
1311 let positions = collect_positions_current(
1312 &self.http,
1313 &self.config.account_query(),
1314 cmd.instrument_id.as_ref().map(|id| id.symbol.as_str()),
1315 max_pages,
1316 )
1317 .await?;
1318 let mut reports = Vec::new();
1319
1320 for value in &positions {
1321 if cmd
1322 .instrument_id
1323 .is_some_and(|id| id.symbol.as_str() != value.ticker)
1324 {
1325 continue;
1326 }
1327
1328 let definition = self.definition(&value.ticker, ts_init).await?;
1329 let report = reports::position(value, &definition, self.core.account_id, ts_init)?;
1330 if cmd.start.is_none_or(|start| report.ts_last >= start)
1331 && cmd.end.is_none_or(|end| report.ts_last <= end)
1332 {
1333 reports.push(report);
1334 }
1335 }
1336
1337 Ok(reports)
1338 }
1339
1340 async fn generate_mass_status(
1341 &self,
1342 lookback_mins: Option<u64>,
1343 ) -> anyhow::Result<Option<ExecutionMassStatus>> {
1344 let requested_at = self.clock.get_time_ns();
1345 let start = lookback_mins
1346 .map(DurationNanos::try_from_mins)
1347 .transpose()?
1348 .map(|duration| requested_at.saturating_sub(duration));
1349 let max_pages = 100;
1350 let snapshot = collect_snapshot_at(
1351 &self.http,
1352 &self.config.account_query(),
1353 start,
1354 max_pages,
1355 requested_at,
1356 )
1357 .await?;
1358 let mut orders = Vec::new();
1359 let mut omitted = 0;
1360
1361 for value in &snapshot.orders {
1362 anyhow::ensure!(
1363 timestamp(&value.last_update_time)? <= snapshot.ts_init,
1364 "order changed after mass collection began"
1365 );
1366
1367 match self
1368 .order_report_aggregate(value, snapshot.ts_init, max_pages, Some(&snapshot.cutoff))
1369 .await?
1370 {
1371 Some(report) => orders.push(report),
1372 None => omitted += 1,
1373 }
1374 }
1375
1376 let source_orders: HashMap<_, _> = snapshot
1377 .orders
1378 .iter()
1379 .map(|order| (order.order_id.as_str(), order))
1380 .collect();
1381 let mut fills = Vec::new();
1382
1383 for value in &snapshot.fills {
1384 let source = source_orders
1385 .get(value.order_id.as_str())
1386 .context("fill lacks order evidence")?;
1387 let report = self.fill_report(value, source, snapshot.ts_init).await?;
1388 fills.push(report);
1389 }
1390
1391 validate_fill_coverage(
1392 snapshot.orders.iter(),
1393 &fills,
1394 start,
1395 Some(snapshot.ts_init),
1396 )?;
1397
1398 let mut positions = Vec::new();
1399
1400 for value in &snapshot.positions {
1401 let definition = self.definition(&value.ticker, snapshot.ts_init).await?;
1402 let report =
1403 reports::position(value, &definition, self.core.account_id, snapshot.ts_init)?;
1404 anyhow::ensure!(
1405 report.ts_last <= snapshot.ts_init,
1406 "position changed after mass collection began"
1407 );
1408 positions.push(report);
1409 }
1410
1411 let mut mass = ExecutionMassStatus::new(
1412 self.core.client_id,
1413 self.core.account_id,
1414 *KALSHI_VENUE,
1415 snapshot.ts_init,
1416 None,
1417 );
1418
1419 self.admit_reports(&orders, &fills)?;
1420
1421 if omitted > 0 {
1422 log::warn!(
1423 "Kalshi mass status omits {omitted} unfilled external order(s), reports are incomplete"
1424 );
1425 }
1426
1427 mass.set_report_window(start, omitted == 0);
1428 mass.add_order_reports(orders);
1429 mass.add_fill_reports(fills);
1430 mass.add_position_reports(positions);
1431 Ok(Some(mass))
1432 }
1433}
1434
1435fn position_qty(
1436 cache: &Cache,
1437 order: &OrderAny,
1438 requested: Option<PositionId>,
1439 account_id: AccountId,
1440) -> Result<Option<Decimal>, OrderDeniedReason> {
1441 let expected = PositionId::new(format!("{}-{}", order.instrument_id(), order.strategy_id()));
1442
1443 let validated = (|| -> anyhow::Result<_> {
1444 anyhow::ensure!(
1445 requested.is_none_or(|id| id == expected)
1446 && order.position_id().is_none_or(|id| id == expected)
1447 && cache
1448 .position_id(&order.client_order_id())
1449 .is_none_or(|id| *id == expected),
1450 "Kalshi NETTING position binding must match the submitting strategy"
1451 );
1452
1453 if !order.is_reduce_only() {
1454 return Ok(None);
1455 }
1456
1457 let position = cache
1458 .position_ref(&expected)
1459 .filter(|position| position.is_open());
1460
1461 let Some(position) = position else {
1462 return Ok(None);
1463 };
1464
1465 anyhow::ensure!(
1466 position.instrument_id == order.instrument_id()
1467 && position.account_id == account_id
1468 && position.strategy_id == order.strategy_id()
1469 && cache.oms_type(&expected) == Some(OmsType::Netting),
1470 "Kalshi canonical position scope mismatch"
1471 );
1472 Ok(Some(position.signed_decimal_qty()))
1473 })();
1474
1475 validated.map_err(|e| OrderDeniedReason::ValidationFailed {
1476 detail: e.to_string(),
1477 })
1478}
1479
1480fn validate_request(
1481 params: Option<&Params>,
1482 start: Option<UnixNanos>,
1483 end: Option<UnixNanos>,
1484) -> anyhow::Result<u32> {
1485 anyhow::ensure!(
1486 start.zip(end).is_none_or(|(start, end)| start <= end),
1487 "invalid report time window"
1488 );
1489
1490 let Some(params) = params else {
1491 return Ok(100);
1492 };
1493
1494 anyhow::ensure!(
1495 params.keys().all(|key| key == "max_pages"),
1496 "unsupported Kalshi report parameter"
1497 );
1498 let pages = params
1499 .get("max_pages")
1500 .map(|value| value.as_u64().context("invalid report page budget"))
1501 .transpose()?
1502 .unwrap_or(100);
1503 let pages = u32::try_from(pages).context("invalid report page budget")?;
1504 anyhow::ensure!(pages > 0, "invalid report page budget");
1505 Ok(pages)
1506}
1507
1508fn order_in_window(
1509 value: &VenueOrder,
1510 start: Option<UnixNanos>,
1511 end: Option<UnixNanos>,
1512) -> anyhow::Result<bool> {
1513 let last = timestamp(&value.last_update_time)?;
1514 Ok(start.is_none_or(|start| last >= start) && end.is_none_or(|end| last <= end))
1515}
1516
1517fn validate_fill_coverage<'a>(
1518 orders: impl Iterator<Item = &'a VenueOrder>,
1519 fills: &[FillReport],
1520 start: Option<UnixNanos>,
1521 end: Option<UnixNanos>,
1522) -> anyhow::Result<()> {
1523 let mut fill_counts = HashMap::new();
1524 for report in fills {
1525 let count = fill_counts
1526 .entry(report.venue_order_id)
1527 .or_insert(Decimal::ZERO);
1528 *count = count
1529 .checked_add(report.last_qty.as_decimal())
1530 .context("fill count overflow")?;
1531 }
1532
1533 for order in orders {
1534 let id = VenueOrderId::new_checked(&order.order_id)?;
1535 let count = fill_counts.get(&id).copied().unwrap_or(Decimal::ZERO);
1536 anyhow::ensure!(
1537 count <= order.fill_count_fp.0,
1538 "collected fills exceed order filled count"
1539 );
1540 let created = timestamp(&order.created_time)?;
1541 let updated = timestamp(&order.last_update_time)?;
1542 anyhow::ensure!(created <= updated, "order timestamps out of sequence");
1543
1544 if start.is_none_or(|start| created >= start) && end.is_none_or(|end| updated <= end) {
1545 anyhow::ensure!(
1546 count == order.fill_count_fp.0,
1547 "order fills are not yet completely visible"
1548 );
1549 }
1550 }
1551
1552 Ok(())
1553}
1554
1555impl KalshiExecutionClient {
1556 fn submission_order(&self, cmd: &SubmitOrder) -> anyhow::Result<OrderAny> {
1557 let order = self.core.get_order(&cmd.client_order_id)?;
1558 anyhow::ensure!(
1559 cmd.trader_id == self.core.trader_id
1560 && cmd.trader_id == order.trader_id()
1561 && cmd.strategy_id == order.strategy_id()
1562 && cmd.instrument_id == order.instrument_id()
1563 && cmd.client_id.is_none_or(|id| id == self.core.client_id)
1564 && cmd.order_init == OrderInitialized::from(&order)
1565 && cmd.exec_algorithm_id == order.exec_algorithm_id()
1566 && order
1567 .account_id()
1568 .is_none_or(|id| id == self.core.account_id)
1569 && self.core.cache().client_id(&cmd.client_order_id) == Some(&self.core.client_id)
1570 && order.status() == OrderStatus::Initialized,
1571 "Kalshi submission command or cached identity mismatch"
1572 );
1573
1574 Ok(order)
1575 }
1576
1577 fn submission(
1578 &self,
1579 mut order: OrderAny,
1580 cmd: &SubmitOrder,
1581 ) -> anyhow::Result<Option<submit::Submission>> {
1582 let session = {
1583 let mut state = self
1584 .private
1585 .lock()
1586 .expect("private state lock is not poisoned");
1587 anyhow::ensure!(
1588 !state.orders.contains_key(&cmd.client_order_id)
1589 && state.submissions.insert(cmd.client_order_id),
1590 "Kalshi submission already claimed"
1591 );
1592 state.session.clone()
1593 };
1594
1595 let request = match submit::request(
1596 &order,
1597 cmd.params.as_ref(),
1598 self.config.exchange_index,
1599 self.config.subaccount,
1600 ) {
1601 Ok(request) => request,
1602 Err(reason) => {
1603 self.private
1604 .lock()
1605 .expect("private state lock is not poisoned")
1606 .deny_submission(&mut order, &reason.to_string(), &self.emitter)?;
1607 return Ok(None);
1608 }
1609 };
1610
1611 let position_qty = match position_qty(
1613 &self.core.cache(),
1614 &order,
1615 cmd.position_id,
1616 self.core.account_id,
1617 ) {
1618 Ok(qty) => qty,
1619 Err(reason) => {
1620 self.private
1621 .lock()
1622 .expect("private state lock is not poisoned")
1623 .deny_submission(&mut order, &reason.to_string(), &self.emitter)?;
1624 return Ok(None);
1625 }
1626 };
1627
1628 anyhow::ensure!(
1629 self.is_connected(),
1630 "Kalshi submission requires current-session readiness"
1631 );
1632
1633 let definition = match self
1634 .core
1635 .cache()
1636 .instrument(&order.instrument_id())
1637 .cloned()
1638 {
1639 Some(InstrumentAny::BinaryOption(definition)) => definition,
1640 _ => anyhow::bail!("Kalshi submission requires a cached binary instrument"),
1641 };
1642
1643 validate_definition(&definition, self.config.exchange_index)?;
1644 let ws_client = self
1645 .ws_client
1646 .clone()
1647 .context("Kalshi private transport missing")?;
1648 let refresh = self
1649 .refresh
1650 .clone()
1651 .context("Kalshi private recovery missing")?;
1652
1653 Ok(Some(submit::Submission {
1654 order,
1655 position_qty,
1656 definition,
1657 request,
1658 http: self.http.clone(),
1659 state: Arc::clone(&self.private),
1660 emitter: self.emitter.clone(),
1661 ready: Arc::clone(&self.ready),
1662 ws_client,
1663 refresh,
1664 session,
1665 cancellation: self.command_tasks.cancellation_token(),
1666 }))
1667 }
1668
1669 fn cancel_batch(&self, cancels: Vec<CancelOrder>, command_id: UUID4) -> anyhow::Result<()> {
1670 if self
1671 .private
1672 .lock()
1673 .expect("private state lock is not poisoned")
1674 .batches
1675 .contains(&command_id)
1676 {
1677 return Ok(());
1678 }
1679
1680 let mut selected = Vec::new();
1681 let mut identities = HashSet::new();
1682
1683 for cmd in cancels {
1684 anyhow::ensure!(
1685 identities.insert(cmd.client_order_id),
1686 "duplicate Kalshi cancellation identity"
1687 );
1688 let cached = self.core.get_order(&cmd.client_order_id)?;
1689 anyhow::ensure!(
1690 cmd.trader_id == self.core.trader_id
1691 && cmd.trader_id == cached.trader_id()
1692 && cmd.strategy_id == cached.strategy_id()
1693 && cmd.instrument_id == cached.instrument_id()
1694 && cmd.client_id.is_none_or(|id| id == self.core.client_id)
1695 && cached
1696 .account_id()
1697 .is_none_or(|id| id == self.core.account_id)
1698 && self.core.cache().client_id(&cmd.client_order_id)
1699 == Some(&self.core.client_id)
1700 && cmd.params.as_ref().is_none_or(|params| params.is_empty())
1701 && cmd
1702 .venue_order_id
1703 .zip(cached.venue_order_id())
1704 .is_none_or(|(requested, actual)| requested == actual)
1705 && !cached.is_emulated()
1706 && cached.exec_algorithm_id().is_none(),
1707 "Kalshi batch cancellation command or cached identity mismatch"
1708 );
1709 selected.push((Command::Cancel(cmd), cached));
1710 }
1711
1712 self.private
1713 .lock()
1714 .expect("private state lock is not poisoned")
1715 .batches
1716 .insert(command_id);
1717 let mut mutations = Vec::new();
1718
1719 for (command, cached) in selected {
1720 {
1721 let state = self
1722 .private
1723 .lock()
1724 .expect("private state lock is not poisoned");
1725
1726 if state.mutations_dispatched.contains(&command.id()) {
1727 continue;
1728 }
1729
1730 if let Some(pending) = state.mutations.get(&command.client_order_id()) {
1731 if pending.command_id == command.id() {
1732 continue;
1733 }
1734
1735 let event = command.outcome(
1736 &cached,
1737 "VALIDATION_FAILED: Kalshi order change is already in flight",
1738 true,
1739 &self.emitter,
1740 );
1741 self.emitter.try_send_order_event(event)?;
1742 continue;
1743 }
1744 }
1745
1746 mutations.push(self.prepare_change(&command, &cached)?);
1747 }
1748
1749 if !mutations.is_empty() {
1750 let epoch = Some(mutations[0].epoch);
1751
1752 if let Err(e) = self
1753 .command_tasks
1754 .spawn(batch::CancellationBatch { mutations, epoch }.run())
1755 {
1756 log::warn!("Kalshi batch cancellation task was not registered: {e}");
1757 }
1758 }
1759
1760 Ok(())
1761 }
1762
1763 fn mutate(&self, command: &Command) -> anyhow::Result<()> {
1764 let id = command.client_order_id();
1765 let cached = self.core.get_order(&id)?;
1766
1767 let (trader_id, client_id, strategy_id, instrument_id, venue_order_id) = match &command {
1768 Command::Modify(cmd) => (
1769 cmd.trader_id,
1770 cmd.client_id,
1771 cmd.strategy_id,
1772 cmd.instrument_id,
1773 cmd.venue_order_id,
1774 ),
1775 Command::Cancel(cmd) => (
1776 cmd.trader_id,
1777 cmd.client_id,
1778 cmd.strategy_id,
1779 cmd.instrument_id,
1780 cmd.venue_order_id,
1781 ),
1782 };
1783
1784 anyhow::ensure!(
1785 trader_id == cached.trader_id()
1786 && strategy_id == cached.strategy_id()
1787 && instrument_id == cached.instrument_id()
1788 && client_id.is_none_or(|id| id == self.core.client_id)
1789 && cached.trader_id() == self.core.trader_id
1790 && cached.account_id() == Some(self.core.account_id)
1791 && self.core.cache().client_id(&id) == Some(&self.core.client_id),
1792 "Kalshi change command or cached identity mismatch"
1793 );
1794
1795 let pending = {
1796 let state = self
1797 .private
1798 .lock()
1799 .expect("private state lock is not poisoned");
1800
1801 if state.mutations_dispatched.contains(&command.id()) {
1802 return Ok(());
1803 }
1804
1805 state.mutations.get(&id).map(|pending| pending.command_id)
1806 };
1807
1808 if pending == Some(command.id()) {
1809 return Ok(());
1810 }
1811
1812 let prepared = if pending.is_some() {
1813 Err(anyhow::anyhow!("Kalshi order change is already in flight"))
1814 } else if venue_order_id.is_some_and(|id| Some(id) != cached.venue_order_id()) {
1815 Err(anyhow::anyhow!("Kalshi change venue identity mismatch"))
1816 } else if cached.is_closed() {
1817 Err(anyhow::anyhow!("Kalshi order is already closed"))
1818 } else {
1819 self.prepare_change(command, &cached)
1820 };
1821
1822 let mutation = match prepared {
1823 Ok(mutation) => mutation,
1824 Err(e) => {
1825 let event = command.outcome(
1826 &cached,
1827 &format!("VALIDATION_FAILED: {e}"),
1828 true,
1829 &self.emitter,
1830 );
1831 self.emitter.try_send_order_event(event)?;
1832 return Ok(());
1833 }
1834 };
1835
1836 if let Err(e) = self.command_tasks.spawn(mutation.run()) {
1837 log::warn!("Kalshi change task was not registered: {e}");
1838 }
1839
1840 Ok(())
1841 }
1842
1843 fn prepare_change(&self, command: &Command, cached: &OrderAny) -> anyhow::Result<Mutation> {
1844 let deadline = Instant::now() + ADMISSION_TIMEOUT;
1845 self.observe_settlement();
1846 let id = command.client_order_id();
1847
1848 let definition = match self
1849 .core
1850 .cache()
1851 .instrument(&cached.instrument_id())
1852 .cloned()
1853 {
1854 Some(InstrumentAny::BinaryOption(definition)) => definition,
1855 _ => anyhow::bail!("Kalshi change requires a cached binary instrument"),
1856 };
1857
1858 validate_definition(&definition, self.config.exchange_index)?;
1859 let ws_client = self
1860 .ws_client
1861 .clone()
1862 .context("Kalshi private transport missing")?;
1863 let refresh = self
1864 .refresh
1865 .clone()
1866 .context("Kalshi private recovery missing")?;
1867 let epoch = ws_client
1868 .connection_epoch()
1869 .context("Kalshi private transport is not active")?;
1870
1871 anyhow::ensure!(
1872 self.core.is_connected() && ws_client.is_active(),
1873 "Kalshi change requires an active execution connection"
1874 );
1875
1876 let (order, session) = {
1877 let mut state = self
1878 .private
1879 .lock()
1880 .expect("private state lock is not poisoned");
1881
1882 let order = if !state.orders.contains_key(&id) && state.submissions.contains(&id) {
1883 cached.clone()
1884 } else {
1885 anyhow::ensure!(
1886 state.orders.contains_key(&id),
1887 "Kalshi change requires recovered order context"
1888 );
1889 Self::claimed_order(&state, cached)
1890 };
1891
1892 anyhow::ensure!(
1893 order.strategy_id() == cached.strategy_id()
1894 && order.instrument_id() == cached.instrument_id()
1895 && (order.venue_order_id() == cached.venue_order_id()
1896 || cached.venue_order_id().is_none()),
1897 "Kalshi change private identity mismatch"
1898 );
1899 state.mutations.insert(
1900 id,
1901 PendingMutation {
1902 command_id: command.id(),
1903 started: self.clock.get_time_ns(),
1904 dispatched: false,
1905 acknowledgement: None,
1906 terms: None,
1907 },
1908 );
1909
1910 (order, state.session.clone())
1911 };
1912
1913 let mutation = Mutation {
1914 command: command.clone(),
1915 order,
1916 definition,
1917 shard: self.config.exchange_index,
1918 subaccount: self.config.subaccount,
1919 http: self.http.clone(),
1920 state: Arc::clone(&self.private),
1921 emitter: self.emitter.clone(),
1922 ready: Arc::clone(&self.ready),
1923 ws_client,
1924 epoch,
1925 deadline,
1926 refresh,
1927 session,
1928 cancellation: self.command_tasks.cancellation_token(),
1929 };
1930
1931 Ok(mutation)
1932 }
1933
1934 fn claimed_order(state: &PrivateState, cached: &OrderAny) -> OrderAny {
1935 let order = state
1936 .orders
1937 .get(&cached.client_order_id())
1938 .map_or_else(|| cached.clone(), |context| context.order.clone());
1939 if order.strategy_id().is_external() && order.strategy_id() != cached.strategy_id() {
1940 return cached.clone();
1941 }
1942
1943 order
1944 }
1945}
1946
1947#[cfg(test)]
1948mod tests {
1949 #[cfg(not(all(feature = "simulation", madsim)))]
1950 use futures_util::StreamExt;
1951 use nautilus_common::{cache::Cache, messages::ExecutionEvent};
1952 #[cfg(not(all(feature = "simulation", madsim)))]
1953 use nautilus_model::events::AccountState;
1954 use nautilus_model::{
1955 enums::{OrderType, TimeInForce},
1956 events::OrderEventAny,
1957 orders::builder::OrderTestBuilder,
1958 };
1959
1960 use super::*;
1961
1962 #[allow(dead_code, reason = "shared key fixtures serve multiple suites")]
1963 mod keys {
1964 include!(concat!(
1965 env!("CARGO_MANIFEST_DIR"),
1966 "/tests/integration/keys.rs"
1967 ));
1968 }
1969
1970 #[rstest::rstest]
1971 fn reset_preserves_unconsumed_submission_identity_and_funds() {
1972 let (sender, mut output) = tokio::sync::mpsc::unbounded_channel();
1973 nautilus_common::live::runner::set_exec_event_sender(sender);
1974 let cache = Rc::new(RefCell::new(Cache::default()));
1975
1976 let config = KalshiExecutionClientConfig {
1977 api_key_id: Some("reset-test".into()),
1978 private_key: Some(keys::rsa_pkcs8().into()),
1979 ..Default::default()
1980 };
1981
1982 let core = ExecutionClientCore::new(
1983 "TRADER-001".into(),
1984 "KALSHI".into(),
1985 *KALSHI_VENUE,
1986 OmsType::Netting,
1987 config.account_id,
1988 AccountType::Cash,
1989 Some(Currency::USD()),
1990 Rc::clone(&cache),
1991 );
1992
1993 let mut client = KalshiExecutionClient::new(core, config).unwrap();
1994 let mut order = OrderTestBuilder::new(OrderType::Limit)
1995 .instrument_id("RESET.KALSHI".into())
1996 .client_order_id("reset-order".into())
1997 .quantity(Quantity::from("1.25"))
1998 .price(Price::from("0.600000"))
1999 .time_in_force(TimeInForce::Gtc)
2000 .build();
2001 let id = order.client_order_id();
2002 cache
2003 .borrow_mut()
2004 .add_order(order.clone(), None, Some(client.client_id()), false)
2005 .unwrap();
2006 {
2007 let mut state = client.private.lock().unwrap();
2008 let ticket = state.ledger.begin_refresh();
2009 state
2010 .ledger
2011 .apply_refresh(ticket, Decimal::from(3), HashMap::new())
2012 .unwrap();
2013 state
2014 .submit(&mut order, Decimal::new(7845, 4), None, &client.emitter)
2015 .unwrap();
2016 }
2017
2018 let balance = client.private.lock().unwrap().ledger.balance().unwrap();
2019 client.reset().unwrap();
2020 assert_eq!(
2021 cache.borrow().order(&id).unwrap().status(),
2022 OrderStatus::Initialized
2023 );
2024 let mut state = client.private.lock().unwrap();
2025 assert_eq!(state.orders[&id].order.status(), OrderStatus::Submitted);
2026 assert_eq!(state.orders[&id].order.client_order_id(), id);
2027 assert_eq!(state.ledger.balance().unwrap(), balance);
2028 assert_eq!(
2029 state
2030 .ledger
2031 .reserve(id, Decimal::new(7845, 4))
2032 .unwrap_err()
2033 .to_string(),
2034 "Kalshi command already owns funds"
2035 );
2036 assert!(matches!(
2037 output.try_recv().unwrap(),
2038 ExecutionEvent::Account(_)
2039 ));
2040 assert!(matches!(
2041 output.try_recv().unwrap(),
2042 ExecutionEvent::Order(OrderEventAny::Submitted(_))
2043 ));
2044 assert!(output.try_recv().is_err());
2045 }
2046
2047 #[rstest::rstest]
2048 #[case::ordinary(None, false)]
2049 #[case::unsent(Some(false), false)]
2050 #[case::unsent_other_order(Some(false), true)]
2051 #[case::dispatched(Some(true), false)]
2052 fn order_query_preserves_recovery_for_pending_native_changes(
2053 #[case] dispatched: Option<bool>,
2054 #[case] other_order: bool,
2055 ) {
2056 let cache = Rc::new(RefCell::new(Cache::default()));
2057
2058 let config = KalshiExecutionClientConfig {
2059 api_key_id: Some("query-test".into()),
2060 private_key: Some(keys::rsa_pkcs8().into()),
2061 ..Default::default()
2062 };
2063
2064 let core = ExecutionClientCore::new(
2065 "TRADER-001".into(),
2066 "KALSHI".into(),
2067 *KALSHI_VENUE,
2068 OmsType::Netting,
2069 config.account_id,
2070 AccountType::Cash,
2071 Some(Currency::USD()),
2072 Rc::clone(&cache),
2073 );
2074
2075 let mut client = KalshiExecutionClient::new(core, config).unwrap();
2076 let order = OrderTestBuilder::new(OrderType::Limit)
2077 .instrument_id("QUERY.KALSHI".into())
2078 .client_order_id("query-order".into())
2079 .quantity(Quantity::from("1.25"))
2080 .price(Price::from("0.600000"))
2081 .time_in_force(TimeInForce::Gtc)
2082 .build();
2083 let other = OrderTestBuilder::new(OrderType::Limit)
2084 .instrument_id("QUERY.KALSHI".into())
2085 .client_order_id("other-order".into())
2086 .quantity(Quantity::from("2.50"))
2087 .price(Price::from("0.700000"))
2088 .time_in_force(TimeInForce::Gtc)
2089 .build();
2090 let id = order.client_order_id();
2091 cache
2092 .borrow_mut()
2093 .add_order(order.clone(), None, Some(client.client_id()), false)
2094 .unwrap();
2095 cache
2096 .borrow_mut()
2097 .add_order(other.clone(), None, Some(client.client_id()), false)
2098 .unwrap();
2099 let (refresh, mut requests) = tokio::sync::mpsc::unbounded_channel();
2100 client.refresh = Some(refresh);
2101 client
2102 .ready
2103 .store(dispatched != Some(true), Ordering::Release);
2104
2105 let (ticket, session) = {
2106 let mut state = client.private.lock().unwrap();
2107 state.restore(order.clone());
2108 let other_id = other.client_order_id();
2109 state.restore(other);
2110 state.epoch = Some((3, 4));
2111 if let Some(dispatched) = dispatched {
2112 state.mutations.insert(
2113 if other_order { other_id } else { id },
2114 PendingMutation {
2115 command_id: UUID4::new(),
2116 terms: None,
2117 acknowledgement: None,
2118 started: order.ts_last(),
2119 dispatched,
2120 },
2121 );
2122 }
2123
2124 (state.ledger.begin_refresh(), state.session.clone())
2125 };
2126
2127 client
2128 .query_order(QueryOrder::new(
2129 client.core.trader_id,
2130 Some(client.client_id()),
2131 order.strategy_id(),
2132 order.instrument_id(),
2133 id,
2134 None,
2135 UUID4::new(),
2136 UnixNanos::default(),
2137 None,
2138 None,
2139 ))
2140 .unwrap();
2141
2142 let state = client.private.lock().unwrap();
2143 let pending = dispatched.is_some();
2144 assert_eq!(state.ledger.check_refresh(ticket).is_ok(), pending);
2145 assert_eq!(state.session == session, pending);
2146 assert_eq!(state.epoch, pending.then_some((3, 4)));
2147 assert_eq!(
2148 client.ready.load(Ordering::Acquire),
2149 dispatched == Some(false)
2150 );
2151 assert_eq!(requests.try_recv(), Ok(()));
2152 assert!(requests.try_recv().is_err());
2153 assert_eq!(state.orders[&id].order.quantity(), Quantity::from("1.25"));
2154 assert_eq!(
2155 state.orders[&id].order.price(),
2156 Some(Price::from("0.600000"))
2157 );
2158 }
2159
2160 #[cfg(not(all(feature = "simulation", madsim)))]
2161 #[tokio::test]
2162 async fn connected_requires_the_transport_epoch_covered_by_account_recovery() {
2163 tokio::time::timeout(Duration::from_secs(10), async {
2164 let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
2165 let address = listener.local_addr().unwrap();
2166 let peer = tokio::spawn(async move {
2167 let (stream, _) = listener.accept().await.unwrap();
2168 let mut ws_client = tokio_tungstenite::accept_async(stream).await.unwrap();
2169 while ws_client.next().await.is_some() {}
2170 });
2171
2172 let config = KalshiExecutionClientConfig {
2173 api_key_id: Some("epoch-test".into()),
2174 private_key: Some(keys::rsa_pkcs8().into()),
2175 base_url_ws: Some(format!("ws://{address}/ws").into()),
2176 ..Default::default()
2177 };
2178
2179 let cache = Rc::new(RefCell::new(Cache::default()));
2180
2181 let core = ExecutionClientCore::new(
2182 "TRADER-001".into(),
2183 "KALSHI".into(),
2184 *KALSHI_VENUE,
2185 OmsType::Netting,
2186 config.account_id,
2187 AccountType::Cash,
2188 Some(Currency::USD()),
2189 Rc::clone(&cache),
2190 );
2191
2192 let mut client = KalshiExecutionClient::new(core, config).unwrap();
2193 let (ws_client, _events) =
2194 KalshiWebSocketClient::new(client.transport.clone()).unwrap();
2195 ws_client.connect().await.unwrap();
2196 let epoch = ws_client.connection_epoch().unwrap();
2197 client.ws_client = Some(ws_client.clone());
2198 client.ready.store(true, Ordering::Release);
2199 client.core.set_connected();
2200
2201 let session = {
2202 let mut state = client.private.lock().unwrap();
2203 state.epoch = Some(epoch);
2204 state.session.clone()
2205 };
2206
2207 let info =
2208 Params::new([("kalshi_session".into(), serde_json::Value::String(session))].into());
2209 let zero = Money::zero(Currency::USD());
2210 let balance = AccountBalance::new(zero, zero, zero);
2211 let event = AccountState::new(
2212 client.account_id(),
2213 AccountType::Cash,
2214 vec![balance],
2215 Vec::new(),
2216 true,
2217 UUID4::new(),
2218 UnixNanos::from(1),
2219 UnixNanos::from(2),
2220 Some(Currency::USD()),
2221 )
2222 .with_info(Some(info));
2223 cache
2224 .borrow_mut()
2225 .add_account(AccountAny::from(event.clone()))
2226 .unwrap();
2227 assert!(client.is_connected());
2228 client.private.lock().unwrap().epoch = Some((epoch.0.wrapping_add(1), epoch.1));
2229 assert!(!client.is_connected());
2230 client.private.lock().unwrap().epoch = Some((epoch.0, epoch.1.wrapping_add(1)));
2231 assert!(!client.is_connected());
2232 client.private.lock().unwrap().epoch = None;
2233 assert!(!client.is_connected());
2234 client.private.lock().unwrap().epoch = Some(epoch);
2235 assert!(client.is_connected());
2236 let mut stale = event.clone();
2237 stale.info = Some(Params::new(
2238 [(
2239 "kalshi_session".into(),
2240 serde_json::Value::String("stale-session".into()),
2241 )]
2242 .into(),
2243 ));
2244 cache
2245 .borrow_mut()
2246 .add_account(AccountAny::from(stale))
2247 .unwrap();
2248 assert!(!client.is_connected());
2249 cache
2250 .borrow_mut()
2251 .add_account(AccountAny::from(event))
2252 .unwrap();
2253 assert!(client.is_connected());
2254 ws_client.stop().await.unwrap();
2255 assert!(!client.is_connected());
2256 peer.await.unwrap();
2257 })
2258 .await
2259 .unwrap();
2260 }
2261}