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