1use std::{
19 collections::{HashMap, HashSet},
20 fmt::Debug,
21 sync::{
22 Arc, LazyLock, Mutex,
23 atomic::{AtomicBool, Ordering},
24 },
25};
26
27use nautilus_common::config::ConfigError;
28use nautilus_core::{string::secret::SecretString, time::get_atomic_clock_realtime};
29use nautilus_network::{
30 http::{HttpClient, HttpClientError, HttpRedirectPolicy, HttpResponse, Method},
31 retry::{RetryConfig, RetryError, RetryManager},
32};
33use serde::{Serialize, de::DeserializeOwned};
34use tokio_util::sync::CancellationToken;
35use url::Url;
36
37use super::{
38 error::KalshiHttpError,
39 models::*,
40 parse::{Pages, Pagination, decode_body, decode_response, unexpected_response},
41 query::*,
42 quota::{Bucket, Charge, KalshiQuota},
43};
44use crate::{
45 common::{
46 consts::MAX_SUBACCOUNT,
47 credential::{KalshiCredential, credential_env_vars},
48 },
49 config::KalshiDataClientConfig,
50};
51
52static QUOTAS: LazyLock<Mutex<QuotaOwners>> = LazyLock::new(|| Mutex::new(HashMap::new()));
53
54#[derive(Clone)]
63pub struct KalshiHttpClient {
64 client: HttpClient,
65 base_url: SecretString,
66 credential: Option<Arc<KalshiCredential>>,
67 cancellation: CancellationToken,
68 dispatch_check: Option<Arc<dyn Fn() -> bool + Send + Sync>>,
69 quota: Arc<KalshiQuota>,
70 timeout_ms: u64,
71}
72
73impl KalshiHttpClient {
74 pub fn new(config: &KalshiDataClientConfig) -> anyhow::Result<Self> {
82 Self::build(config)
83 }
84
85 pub fn new_authenticated(config: &KalshiDataClientConfig) -> anyhow::Result<Self> {
91 Self::authenticated(config, None)
92 }
93
94 pub fn new_authenticated_with_quota(
103 config: &KalshiDataClientConfig,
104 quota: Arc<KalshiQuota>,
105 ) -> anyhow::Result<Self> {
106 Self::authenticated(config, Some(quota))
107 }
108
109 pub fn new_with_quota(
115 config: &KalshiDataClientConfig,
116 quota: Arc<KalshiQuota>,
117 ) -> anyhow::Result<Self> {
118 let mut client = Self::build(config)?;
119 client.quota = quota;
120 Ok(client)
121 }
122
123 pub async fn refresh_quota(&self) -> Result<(), KalshiHttpError> {
138 let _guard = tokio::select! {
139 biased;
140 () = self.cancellation.cancelled() => return Err(KalshiHttpError::Canceled { dispatched: false }),
141 guard = self.quota.refresh.lock() => guard,
142 };
143
144 if !self.quota.needs_refresh() {
145 return Ok(());
146 }
147
148 let limits = match self.get_account_limits().await {
149 Ok(_) => Ok(()),
150 Err(e) if e.is_subaccount_restricted() => {
151 log::debug!("Kalshi restricted API key uses conservative Basic quota limits");
152 self.quota.set_basic_limits()
153 }
154 Err(e) => Err(e),
155 };
156
157 let costs = self.get_endpoint_costs().await;
158 if let Err(e) = limits.and(costs.map(|_| ())) {
159 if !self.cancellation.is_cancelled() {
160 self.quota.discovery_failed();
161 }
162
163 return Err(e);
164 }
165
166 Ok(())
167 }
168
169 pub(crate) async fn batch_size(&self, method: Method) -> Result<usize, KalshiHttpError> {
170 self.refresh_quota().await?;
171 let charge = request_charge(
172 &method,
173 &["portfolio", "events", "orders", "batched"],
174 "",
175 None,
176 Operation::Write,
177 )?;
178 self.quota.batch_size(&charge)
179 }
180
181 pub(crate) fn with_dispatch_check(
182 mut self,
183 cancellation: CancellationToken,
184 check: impl Fn() -> bool + Send + Sync + 'static,
185 ) -> Self {
186 self.cancellation = cancellation;
187 self.dispatch_check = Some(Arc::new(check));
188 self
189 }
190
191 pub async fn get_exchange_status(&self) -> Result<HttpResponse, HttpClientError> {
199 self.send_raw(
200 Method::GET,
201 &["exchange", "status"],
202 &(),
203 Option::<&()>::None,
204 false,
205 Operation::Read,
206 )
207 .await
208 .map_err(|e| match e {
209 KalshiHttpError::Transport(e) => e,
210 e => HttpClientError::Error(e.to_string()),
211 })
212 }
213
214 pub async fn get_balance(&self, exchange_index: u32) -> Result<HttpResponse, KalshiHttpError> {
220 let response = self
221 .send_raw(
222 Method::GET,
223 &["portfolio", "balance"],
224 &[("exchange_index", exchange_index)],
225 Option::<&()>::None,
226 true,
227 Operation::Read,
228 )
229 .await?;
230
231 if !response.status.is_success() {
232 return Err(KalshiHttpError::Status(response.status.as_u16()));
233 }
234
235 Ok(response)
236 }
237
238 pub fn cancel(&self) {
242 self.cancellation.cancel();
243 }
244
245 pub async fn get_status(&self) -> Result<ExchangeStatus, KalshiHttpError> {
254 let response = self
255 .send_raw(
256 Method::GET,
257 &["exchange", "status"],
258 &(),
259 Option::<&()>::None,
260 false,
261 Operation::Read,
262 )
263 .await?;
264
265 if matches!(response.status.as_u16(), 500 | 503 | 504) {
266 return decode_body(response.clone()).or_else(|_| decode_response(response));
267 }
268
269 decode_response(response)
270 }
271
272 pub async fn get_markets(
278 &self,
279 query: &MarketsQuery,
280 ) -> Result<MarketsResponse, KalshiHttpError> {
281 self.get(&["markets"], query, false).await
282 }
283
284 pub async fn get_market(&self, ticker: &str) -> Result<MarketResponse, KalshiHttpError> {
290 self.get(&["markets", ticker], &(), false).await
291 }
292
293 pub async fn get_historical_markets(
299 &self,
300 query: &HistoricalMarketsQuery,
301 ) -> Result<MarketsResponse, KalshiHttpError> {
302 self.get(&["historical", "markets"], query, false).await
303 }
304
305 pub async fn get_historical_market(
311 &self,
312 ticker: &str,
313 ) -> Result<MarketResponse, KalshiHttpError> {
314 self.get(&["historical", "markets", ticker], &(), false)
315 .await
316 }
317
318 pub async fn get_events(&self, query: &EventsQuery) -> Result<EventsResponse, KalshiHttpError> {
324 self.get(&["events"], query, false).await
325 }
326
327 pub async fn get_event(
333 &self,
334 ticker: &str,
335 query: &EventQuery,
336 ) -> Result<EventResponse, KalshiHttpError> {
337 self.get(&["events", ticker], query, false).await
338 }
339
340 pub async fn get_series_list(
346 &self,
347 query: &SeriesQuery,
348 ) -> Result<SeriesListResponse, KalshiHttpError> {
349 self.get(&["series"], query, false).await
350 }
351
352 pub async fn get_series(&self, ticker: &str) -> Result<SeriesResponse, KalshiHttpError> {
358 self.get(&["series", ticker], &(), false).await
359 }
360
361 pub async fn get_orderbook(
367 &self,
368 ticker: &str,
369 depth: u32,
370 ) -> Result<OrderbookResponse, KalshiHttpError> {
371 if depth > 100 {
372 return Err(KalshiHttpError::Validation("depth exceeds 100"));
373 }
374
375 self.get(
376 &["markets", ticker, "orderbook"],
377 &[("depth", depth)],
378 false,
379 )
380 .await
381 }
382
383 pub async fn get_trades(&self, query: &TradesQuery) -> Result<TradesResponse, KalshiHttpError> {
389 self.get(&["markets", "trades"], query, false).await
390 }
391
392 pub async fn get_historical_trades(
398 &self,
399 query: &TradesQuery,
400 ) -> Result<TradesResponse, KalshiHttpError> {
401 self.get(&["historical", "trades"], query, false).await
402 }
403
404 pub async fn get_candlesticks(
410 &self,
411 series: &str,
412 ticker: &str,
413 query: &CandlesticksQuery,
414 ) -> Result<CandlesticksResponse, KalshiHttpError> {
415 validate_candlesticks(query)?;
416 self.get(
417 &["series", series, "markets", ticker, "candlesticks"],
418 query,
419 false,
420 )
421 .await
422 }
423
424 pub async fn get_historical_candlesticks(
430 &self,
431 ticker: &str,
432 query: &CandlesticksQuery,
433 ) -> Result<HistoricalCandlesticksResponse, KalshiHttpError> {
434 validate_candlesticks(query)?;
435 self.get(
436 &["historical", "markets", ticker, "candlesticks"],
437 query,
438 false,
439 )
440 .await
441 }
442
443 pub async fn get_historical_cutoff(&self) -> Result<HistoricalCutoff, KalshiHttpError> {
449 self.get(&["historical", "cutoff"], &(), false).await
450 }
451
452 pub async fn get_account_balance(
458 &self,
459 query: &AccountQuery,
460 ) -> Result<Balance, KalshiHttpError> {
461 validate_subaccount(query.subaccount)?;
462 self.get(&["portfolio", "balance"], query, true).await
463 }
464
465 pub async fn get_positions(
471 &self,
472 query: &PositionsQuery,
473 ) -> Result<PositionsResponse, KalshiHttpError> {
474 validate_subaccount(query.subaccount)?;
475 self.get(&["portfolio", "positions"], query, true).await
476 }
477
478 pub async fn get_historical_positions(
484 &self,
485 query: &HistoricalPositionsQuery,
486 ) -> Result<PositionsResponse, KalshiHttpError> {
487 validate_subaccount(query.subaccount)?;
488 self.get(&["historical", "positions"], query, true).await
489 }
490
491 pub async fn get_fills(&self, query: &FillsQuery) -> Result<FillsResponse, KalshiHttpError> {
497 validate_subaccount(query.subaccount)?;
498 self.get(&["portfolio", "fills"], query, true).await
499 }
500
501 pub async fn get_historical_fills(
507 &self,
508 query: &HistoryQuery,
509 ) -> Result<FillsResponse, KalshiHttpError> {
510 validate_subaccount(query.subaccount)?;
511 self.get(&["historical", "fills"], query, true).await
512 }
513
514 pub async fn get_orders(&self, query: &OrdersQuery) -> Result<OrdersResponse, KalshiHttpError> {
520 validate_subaccount(query.subaccount)?;
521 self.get(&["portfolio", "orders"], query, true).await
522 }
523
524 pub async fn get_order(&self, order_id: &str) -> Result<OrderResponse, KalshiHttpError> {
530 self.get(&["portfolio", "orders", order_id], &(), true)
531 .await
532 }
533
534 pub async fn get_historical_orders(
540 &self,
541 query: &HistoryQuery,
542 ) -> Result<OrdersResponse, KalshiHttpError> {
543 validate_subaccount(query.subaccount)?;
544 self.get(&["historical", "orders"], query, true).await
545 }
546
547 pub async fn get_settlements(
553 &self,
554 query: &SettlementsQuery,
555 ) -> Result<SettlementsResponse, KalshiHttpError> {
556 validate_subaccount(query.subaccount)?;
557 self.get(&["portfolio", "settlements"], query, true).await
558 }
559
560 pub async fn get_account_limits(&self) -> Result<AccountLimits, KalshiHttpError> {
566 let limits: AccountLimits = self.get(&["account", "limits"], &(), true).await?;
567 self.quota
568 .set_limits(&limits, get_atomic_clock_realtime().get_time_ms() as i64)
569 .map_err(|e| KalshiHttpError::AfterSend(Box::new(e)))?;
570 Ok(limits)
571 }
572
573 pub async fn get_endpoint_costs(&self) -> Result<EndpointCosts, KalshiHttpError> {
579 let costs: EndpointCosts = self.get(&["account", "endpoint_costs"], &(), false).await?;
580 self.quota
581 .set_costs(costs.clone())
582 .map_err(|e| KalshiHttpError::AfterSend(Box::new(e)))?;
583 Ok(costs)
584 }
585
586 pub async fn create_order(
592 &self,
593 request: &CreateOrderRequest,
594 ) -> Result<CreateOrderResponse, KalshiHttpError> {
595 validate_create(request)?;
596 self.send(
597 Method::POST,
598 &["portfolio", "events", "orders"],
599 &(),
600 Some(request),
601 true,
602 )
603 .await
604 }
605
606 pub async fn batch_create_orders(
614 &self,
615 request: &BatchCreateRequest,
616 ) -> Result<BatchCreateResponse, KalshiHttpError> {
617 self.create_batch(request, true).await
618 }
619
620 pub(crate) async fn create_batch(
621 &self,
622 request: &BatchCreateRequest,
623 complete: bool,
624 ) -> Result<BatchCreateResponse, KalshiHttpError> {
625 if request.orders.is_empty() {
626 return Err(KalshiHttpError::Validation("empty order batch"));
627 }
628
629 let mut identities = HashSet::new();
630
631 for order in &request.orders {
632 validate_create(order)?;
633 let identity = order
634 .client_order_id
635 .as_deref()
636 .filter(|id| !id.is_empty())
637 .ok_or(KalshiHttpError::Validation(
638 "batch children require client order identities",
639 ))?;
640
641 if !identities.insert(identity) {
642 return Err(KalshiHttpError::Validation(
643 "duplicate batch client order identity",
644 ));
645 }
646 }
647
648 let raw = self
649 .send_raw(
650 Method::POST,
651 &["portfolio", "events", "orders", "batched"],
652 &(),
653 Some(request),
654 true,
655 Operation::Write,
656 )
657 .await?;
658 let response: BatchCreateResponse = decode_response(raw.clone())?;
659 let mut returned = HashSet::new();
660
661 if complete
662 && (response.orders.len() != identities.len()
663 || response
664 .orders
665 .iter()
666 .any(|order| match &order.client_order_id {
667 Field::Value(identity) => {
668 !identities.contains(identity.as_str())
669 || !returned.insert(identity.as_str())
670 }
671 _ => true,
672 }))
673 {
674 return Err(unexpected_response(
675 raw,
676 "batch create result identities do not match requests",
677 ));
678 }
679
680 Ok(response)
681 }
682
683 pub async fn amend_order(
691 &self,
692 order_id: &str,
693 subaccount: u32,
694 request: &AmendOrderRequest,
695 ) -> Result<AmendOrderResponse, KalshiHttpError> {
696 validate_subaccount(subaccount)?;
697 validate_order_values(&request.ticker, request.price, request.count)?;
698 self.send(
699 Method::POST,
700 &["portfolio", "events", "orders", order_id, "amend"],
701 &[("subaccount", subaccount)],
702 Some(request),
703 true,
704 )
705 .await
706 }
707
708 pub async fn decrease_order(
716 &self,
717 order_id: &str,
718 subaccount: u32,
719 request: &DecreaseOrderRequest,
720 ) -> Result<DecreaseOrderResponse, KalshiHttpError> {
721 validate_subaccount(subaccount)?;
722
723 match (request.reduce_by, request.reduce_to) {
724 (Some(value), None)
725 if value.0 > rust_decimal::Decimal::ZERO && value.0.scale() <= 2 => {}
726 (None, Some(value))
727 if value.0 >= rust_decimal::Decimal::ZERO && value.0.scale() <= 2 => {}
728 _ => {
729 return Err(KalshiHttpError::Validation(
730 "exactly one valid decrease selector is required",
731 ));
732 }
733 }
734
735 self.send(
736 Method::POST,
737 &["portfolio", "events", "orders", order_id, "decrease"],
738 &[("subaccount", subaccount)],
739 Some(request),
740 true,
741 )
742 .await
743 }
744
745 pub async fn cancel_order(
753 &self,
754 order_id: &str,
755 query: &AccountQuery,
756 ) -> Result<CancelOrderResponse, KalshiHttpError> {
757 self.cancel_order_for_market(order_id, query, None).await
758 }
759
760 pub(crate) async fn cancel_order_for_market(
761 &self,
762 order_id: &str,
763 query: &AccountQuery,
764 ticker: Option<&str>,
765 ) -> Result<CancelOrderResponse, KalshiHttpError> {
766 validate_subaccount(query.subaccount)?;
767 self.send(
768 Method::DELETE,
769 &["portfolio", "events", "orders", order_id],
770 &CancelQuery {
771 account: query,
772 market_ticker: ticker,
773 },
774 Option::<&()>::None,
775 true,
776 )
777 .await
778 }
779
780 pub async fn batch_cancel_orders(
788 &self,
789 request: &BatchCancelRequest,
790 ) -> Result<BatchCancelResponse, KalshiHttpError> {
791 self.cancel_batch(request, true).await
792 }
793
794 pub(crate) async fn cancel_batch(
795 &self,
796 request: &BatchCancelRequest,
797 complete: bool,
798 ) -> Result<BatchCancelResponse, KalshiHttpError> {
799 if request.orders.is_empty() {
800 return Err(KalshiHttpError::Validation("empty cancel batch"));
801 }
802
803 let mut identities = HashSet::new();
804
805 for order in &request.orders {
806 validate_subaccount(order.subaccount)?;
807 if order.order_id.is_empty() {
808 return Err(KalshiHttpError::Validation("empty order identity"));
809 }
810
811 if !identities.insert(order.order_id.as_str()) {
812 return Err(KalshiHttpError::Validation(
813 "duplicate batch cancel order identity",
814 ));
815 }
816 }
817
818 let raw = self
819 .send_raw(
820 Method::DELETE,
821 &["portfolio", "events", "orders", "batched"],
822 &(),
823 Some(request),
824 true,
825 Operation::Write,
826 )
827 .await?;
828 let response: BatchCancelResponse = decode_response(raw.clone())?;
829 let mut returned = HashSet::new();
830
831 if complete
832 && (response.orders.len() != identities.len()
833 || response.orders.iter().any(|order| {
834 !identities.contains(order.order_id.as_str())
835 || !returned.insert(order.order_id.as_str())
836 }))
837 {
838 return Err(unexpected_response(
839 raw,
840 "batch cancel result identities do not match requests",
841 ));
842 }
843
844 Ok(response)
845 }
846
847 pub async fn get_all_markets(
853 &self,
854 query: MarketsQuery,
855 max_pages: u32,
856 ) -> Result<Pages<Market>, KalshiHttpError> {
857 self.collect_pages(
858 query,
859 max_pages,
860 |q| async move { self.get_markets(&q).await },
861 |m| m.ticker.clone(),
862 )
863 .await
864 }
865
866 pub async fn get_all_historical_markets(
872 &self,
873 query: HistoricalMarketsQuery,
874 max_pages: u32,
875 ) -> Result<Pages<Market>, KalshiHttpError> {
876 self.collect_pages(
877 query,
878 max_pages,
879 |q| async move { self.get_historical_markets(&q).await },
880 |m| m.ticker.clone(),
881 )
882 .await
883 }
884
885 pub async fn get_all_events(
891 &self,
892 query: EventsQuery,
893 max_pages: u32,
894 ) -> Result<Pages<Event>, KalshiHttpError> {
895 self.collect_pages(
896 query,
897 max_pages,
898 |q| async move { self.get_events(&q).await },
899 |e| e.event_ticker.clone(),
900 )
901 .await
902 }
903
904 pub async fn get_all_trades(
910 &self,
911 query: TradesQuery,
912 max_pages: u32,
913 ) -> Result<Pages<Trade>, KalshiHttpError> {
914 self.collect_pages(
915 query,
916 max_pages,
917 |q| async move { self.get_trades(&q).await },
918 |t| t.trade_id.clone(),
919 )
920 .await
921 }
922
923 pub async fn get_all_historical_trades(
929 &self,
930 query: TradesQuery,
931 max_pages: u32,
932 ) -> Result<Pages<Trade>, KalshiHttpError> {
933 self.collect_pages(
934 query,
935 max_pages,
936 |q| async move { self.get_historical_trades(&q).await },
937 |t| t.trade_id.clone(),
938 )
939 .await
940 }
941
942 pub async fn get_all_fills(
948 &self,
949 query: FillsQuery,
950 max_pages: u32,
951 ) -> Result<Pages<Fill>, KalshiHttpError> {
952 self.collect_pages(
953 query,
954 max_pages,
955 |q| async move { self.get_fills(&q).await },
956 |f| format!("{}:{}", f.exchange_index, f.fill_id),
957 )
958 .await
959 }
960
961 pub async fn get_all_historical_fills(
967 &self,
968 query: HistoryQuery,
969 max_pages: u32,
970 ) -> Result<Pages<Fill>, KalshiHttpError> {
971 self.collect_pages(
972 query,
973 max_pages,
974 |q| async move { self.get_historical_fills(&q).await },
975 |f| format!("{}:{}", f.exchange_index, f.fill_id),
976 )
977 .await
978 }
979
980 pub async fn get_all_orders(
986 &self,
987 query: OrdersQuery,
988 max_pages: u32,
989 ) -> Result<Pages<Order>, KalshiHttpError> {
990 self.collect_pages(
991 query,
992 max_pages,
993 |q| async move { self.get_orders(&q).await },
994 |o| o.order_id.clone(),
995 )
996 .await
997 }
998
999 pub async fn get_all_historical_orders(
1005 &self,
1006 query: HistoryQuery,
1007 max_pages: u32,
1008 ) -> Result<Pages<Order>, KalshiHttpError> {
1009 self.collect_pages(
1010 query,
1011 max_pages,
1012 |q| async move { self.get_historical_orders(&q).await },
1013 |o| o.order_id.clone(),
1014 )
1015 .await
1016 }
1017
1018 pub async fn get_all_settlements(
1024 &self,
1025 query: SettlementsQuery,
1026 max_pages: u32,
1027 ) -> Result<Pages<Settlement>, KalshiHttpError> {
1028 self.collect_pages(
1029 query,
1030 max_pages,
1031 |q| async move { self.get_settlements(&q).await },
1032 |s| format!("{}:{}", s.exchange_index, s.ticker),
1033 )
1034 .await
1035 }
1036
1037 pub async fn get_all_positions(
1043 &self,
1044 query: PositionsQuery,
1045 max_pages: u32,
1046 ) -> Result<PositionPages, KalshiHttpError> {
1047 self.collect_positions(
1048 query,
1049 max_pages,
1050 |q| async move { self.get_positions(&q).await },
1051 )
1052 .await
1053 }
1054
1055 pub async fn get_all_historical_positions(
1061 &self,
1062 query: HistoricalPositionsQuery,
1063 max_pages: u32,
1064 ) -> Result<PositionPages, KalshiHttpError> {
1065 self.collect_positions(query, max_pages, |q| async move {
1066 self.get_historical_positions(&q).await
1067 })
1068 .await
1069 }
1070
1071 async fn collect_positions<Q, F, Fut>(
1072 &self,
1073 mut query: Q,
1074 max_pages: u32,
1075 fetch: F,
1076 ) -> Result<PositionPages, KalshiHttpError>
1077 where
1078 Q: CursorQuery,
1079 F: Fn(Q) -> Fut,
1080 Fut: std::future::Future<Output = Result<PositionsResponse, KalshiHttpError>>,
1081 {
1082 if max_pages == 0 {
1083 return Err(KalshiHttpError::Validation("page budget must be positive"));
1084 }
1085
1086 let mut pagination = Pagination::new(query.cursor());
1087
1088 let mut result = PositionPages {
1089 market_positions: Vec::new(),
1090 event_positions: Vec::new(),
1091 complete: false,
1092 next_cursor: query.cursor().map(str::to_owned),
1093 };
1094
1095 for _ in 0..max_pages {
1096 let page = fetch(query.clone()).await?;
1097 let empty = page.market_positions.is_empty() && page.event_positions.is_empty();
1098 let previous = result.market_positions.len() + result.event_positions.len();
1099 result
1100 .market_positions
1101 .extend(page.market_positions.into_iter().filter(|p| {
1102 pagination.retain(format!("market:{}:{}", p.exchange_index, p.ticker))
1103 }));
1104
1105 result.event_positions.extend(
1106 page.event_positions
1107 .into_iter()
1108 .filter(|p| pagination.retain(format!("event:{}", p.event_ticker))),
1109 );
1110 result.next_cursor = pagination.advance(page.cursor, empty)?;
1111 if result.next_cursor.is_none() {
1112 result.complete = true;
1113 break;
1114 }
1115
1116 if result.market_positions.len() + result.event_positions.len() == previous {
1117 return Err(KalshiHttpError::Pagination(
1118 "page contains no new identities",
1119 ));
1120 }
1121
1122 query.set_cursor(result.next_cursor.clone());
1123 }
1124
1125 Ok(result)
1126 }
1127
1128 async fn collect_pages<Q, P, F, Fut>(
1129 &self,
1130 mut query: Q,
1131 max_pages: u32,
1132 fetch: F,
1133 identity: fn(&P::Item) -> String,
1134 ) -> Result<Pages<P::Item>, KalshiHttpError>
1135 where
1136 Q: CursorQuery,
1137 P: CursorPage,
1138 F: Fn(Q) -> Fut,
1139 Fut: std::future::Future<Output = Result<P, KalshiHttpError>>,
1140 {
1141 if max_pages == 0 {
1142 return Err(KalshiHttpError::Validation("page budget must be positive"));
1143 }
1144
1145 let mut pagination = Pagination::new(query.cursor());
1146
1147 let mut result = Pages {
1148 records: Vec::new(),
1149 complete: false,
1150 next_cursor: query.cursor().map(str::to_owned),
1151 };
1152
1153 for _ in 0..max_pages {
1154 let (records, cursor) = fetch(query.clone()).await?.into_parts();
1155 let empty = records.is_empty();
1156 let previous = result.records.len();
1157 result.records.extend(
1158 records
1159 .into_iter()
1160 .filter(|r| pagination.retain(identity(r))),
1161 );
1162 result.next_cursor = pagination.advance(cursor, empty)?;
1163 if result.next_cursor.is_none() {
1164 result.complete = true;
1165 break;
1166 }
1167
1168 if result.records.len() == previous {
1169 return Err(KalshiHttpError::Pagination(
1170 "page contains no new identities",
1171 ));
1172 }
1173
1174 query.set_cursor(result.next_cursor.clone());
1175 }
1176
1177 Ok(result)
1178 }
1179
1180 async fn get<Q: Serialize, R: DeserializeOwned>(
1181 &self,
1182 path: &[&str],
1183 query: &Q,
1184 authenticated: bool,
1185 ) -> Result<R, KalshiHttpError> {
1186 let response = Box::pin(self.send_raw(
1187 Method::GET,
1188 path,
1189 query,
1190 Option::<&()>::None,
1191 authenticated,
1192 Operation::Read,
1193 ))
1194 .await?;
1195 decode_response(response)
1196 }
1197
1198 async fn send<Q: Serialize, B: Serialize, R: DeserializeOwned>(
1199 &self,
1200 method: Method,
1201 path: &[&str],
1202 query: &Q,
1203 body: Option<&B>,
1204 authenticated: bool,
1205 ) -> Result<R, KalshiHttpError> {
1206 let response = self
1207 .send_raw(method, path, query, body, authenticated, Operation::Write)
1208 .await?;
1209 decode_response(response)
1210 }
1211
1212 async fn send_raw<Q: Serialize, B: Serialize>(
1213 &self,
1214 method: Method,
1215 path: &[&str],
1216 query: &Q,
1217 body: Option<&B>,
1218 authenticated: bool,
1219 operation: Operation,
1220 ) -> Result<HttpResponse, KalshiHttpError> {
1221 if self.cancellation.is_cancelled() {
1222 return Err(KalshiHttpError::Canceled { dispatched: false });
1223 }
1224
1225 if authenticated && self.credential.is_none() {
1226 return Err(
1227 ConfigError::invalid_value("credentials", "authenticated client required").into(),
1228 );
1229 }
1230
1231 if path.iter().any(|p| p.is_empty() || *p == "." || *p == "..") {
1232 return Err(KalshiHttpError::Validation(
1233 "empty or relative path component",
1234 ));
1235 }
1236
1237 let mut url = Url::parse(self.base_url.expose_secret())
1238 .map_err(|_| KalshiHttpError::Validation("invalid base URL"))?;
1239 url.path_segments_mut()
1240 .map_err(|()| KalshiHttpError::Validation("invalid base URL"))?
1241 .pop_if_empty()
1242 .extend(path);
1243 let query = serde_urlencoded::to_string(query).map_err(|_| KalshiHttpError::Encoding)?;
1244 if !query.is_empty() {
1245 url.set_query(Some(&query));
1246 }
1247
1248 let value = body
1249 .map(serde_json::to_value)
1250 .transpose()
1251 .map_err(|_| KalshiHttpError::Encoding)?;
1252 let charge = request_charge(&method, path, &query, value.as_ref(), operation)?;
1253 let body = value
1254 .map(stable_object_key_bytes)
1255 .transpose()
1256 .map_err(|_| KalshiHttpError::Encoding)?;
1257 let discovery = matches!(path, ["account", "limits" | "endpoint_costs"]);
1258 self.request(PreparedRequest {
1259 method,
1260 url,
1261 body,
1262 authenticated,
1263 operation,
1264 charge,
1265 discovery,
1266 })
1267 .await
1268 }
1269
1270 async fn request(&self, request: PreparedRequest) -> Result<HttpResponse, KalshiHttpError> {
1271 let dispatched = AtomicBool::new(false);
1272 let last_response = Mutex::new(None);
1273
1274 let retries = RetryManager::new(RetryConfig {
1275 max_retries: 2,
1276 initial_delay_ms: 250,
1277 max_delay_ms: 1_000,
1278 jitter_ms: 0,
1279 operation_timeout_ms: None,
1280 max_elapsed_ms: Some(self.timeout_ms.saturating_mul(3).saturating_add(2_000)),
1281 ..Default::default()
1282 });
1283
1284 let result = retries
1285 .invocation(
1286 "Kalshi HTTP request",
1287 || async {
1288 *last_response.lock().expect("response lock is not poisoned") = None;
1289 let response = self.send_attempt(&request, &dispatched).await?;
1290 if !response.status.is_success() {
1291 let e = decode_response::<serde_json::Value>(response.clone())
1292 .expect_err("non-success response is an error");
1293
1294 if e.is_retryable() && request.operation == Operation::Read {
1295 *last_response.lock().expect("response lock is not poisoned") =
1296 Some(response);
1297 return Err(e);
1298 }
1299 }
1300
1301 Ok(response)
1302 },
1303 |e| request.operation == Operation::Read && e.is_retryable(),
1304 |reason| match reason {
1305 RetryError::Canceled => KalshiHttpError::Canceled {
1306 dispatched: dispatched.load(Ordering::Acquire),
1307 },
1308 reason => KalshiHttpError::Retry {
1309 reason,
1310 dispatched: dispatched.load(Ordering::Acquire),
1311 },
1312 },
1313 )
1314 .cancellation_token(&self.cancellation)
1315 .execute()
1316 .await;
1317
1318 let result = match result {
1319 Err(KalshiHttpError::Http { .. } | KalshiHttpError::Venue { .. }) => Ok(last_response
1320 .into_inner()
1321 .expect("response lock is not poisoned")
1322 .expect("classified response retained")),
1323 result => result,
1324 };
1325
1326 result.map_err(|e| {
1327 if dispatched.load(Ordering::Acquire) && e.is_definitely_not_sent() {
1328 KalshiHttpError::AfterSend(Box::new(e))
1329 } else {
1330 e
1331 }
1332 })
1333 }
1334
1335 async fn send_attempt(
1336 &self,
1337 request: &PreparedRequest,
1338 dispatched: &AtomicBool,
1339 ) -> Result<HttpResponse, KalshiHttpError> {
1340 loop {
1341 if !request.discovery && self.credential.is_some() && self.quota.needs_refresh() {
1342 Box::pin(self.refresh_quota())
1343 .await
1344 .map_err(|e| KalshiHttpError::Discovery(Box::new(e)))?;
1345 }
1346
1347 match self.quota.acquire(&request.charge).await {
1348 Err(_)
1349 if !request.discovery
1350 && self.credential.is_some()
1351 && self.quota.needs_refresh() => {}
1352 result => {
1353 result?;
1354 break;
1355 }
1356 }
1357 }
1358
1359 let mut headers = HashMap::from([("Accept".into(), "application/json".into())]);
1360 if request.body.is_some() {
1361 headers.insert("Content-Type".into(), "application/json".into());
1362 }
1363
1364 if request.authenticated {
1365 let credential = self
1366 .credential
1367 .as_ref()
1368 .expect("authentication checked before quota wait");
1369 headers.extend(
1370 credential
1371 .headers(
1372 get_atomic_clock_realtime().get_time_ms(),
1373 request.method.as_str(),
1374 request.url.path(),
1375 )?
1376 .into_iter()
1377 .map(|(name, value)| (name, value.into_inner())),
1378 );
1379 }
1380
1381 if self.cancellation.is_cancelled()
1382 || request.operation == Operation::Write
1383 && self.dispatch_check.as_ref().is_some_and(|check| !check())
1384 {
1385 return Err(KalshiHttpError::Canceled {
1386 dispatched: dispatched.load(Ordering::Acquire),
1387 });
1388 }
1389
1390 dispatched.store(true, Ordering::Release);
1391 self.client
1392 .request(
1393 request.method.clone(),
1394 request.url.as_str().to_owned(),
1395 None,
1396 Some(headers),
1397 request.body.clone(),
1398 None,
1399 None,
1400 )
1401 .await
1402 .map_err(KalshiHttpError::Transport)
1403 }
1404
1405 fn authenticated(
1406 config: &KalshiDataClientConfig,
1407 quota: Option<Arc<KalshiQuota>>,
1408 ) -> anyhow::Result<Self> {
1409 config.validate()?;
1410 let credential = KalshiCredential::resolve(
1411 config.api_key_id.clone(),
1412 config.private_key.clone(),
1413 config.environment,
1414 )?;
1415
1416 let identity = config
1417 .api_key_id
1418 .clone()
1419 .or_else(|| {
1420 std::env::var(credential_env_vars(config.environment).0)
1421 .ok()
1422 .map(SecretString::from)
1423 })
1424 .ok_or_else(|| anyhow::anyhow!("missing quota credential identity"))?;
1425
1426 let fingerprint = aws_lc_rs::digest::digest(
1427 &aws_lc_rs::digest::SHA256,
1428 identity.expose_secret().as_bytes(),
1429 )
1430 .as_ref()
1431 .to_vec();
1432 let origin = Url::parse(config.http_url())?
1433 .origin()
1434 .ascii_serialization();
1435 let key = (origin, fingerprint);
1436 let mut owners = QUOTAS.lock().expect("quota registry lock is not poisoned");
1437 if let (Some(existing), Some(requested)) = (owners.get(&key), quota.as_ref()) {
1438 anyhow::ensure!(
1439 Arc::ptr_eq(existing, requested),
1440 "credential already has a different quota owner"
1441 );
1442 }
1443
1444 let quota = owners
1445 .entry(key)
1446 .or_insert_with(|| quota.unwrap_or_else(|| Arc::new(KalshiQuota::new())))
1447 .clone();
1448 drop(owners);
1449 let mut client = Self::build(config)?;
1450 client.credential = Some(Arc::new(credential));
1451 client.quota = quota;
1452 Ok(client)
1453 }
1454
1455 fn build(config: &KalshiDataClientConfig) -> anyhow::Result<Self> {
1456 config.validate()?;
1457 let base_url = SecretString::from(config.http_url().trim_end_matches('/'));
1458 let client = HttpClient::builder()
1459 .timeout_secs(config.http_timeout_secs)
1460 .header_keys(vec!["retry-after".into(), "x-request-id".into()])
1461 .maybe_proxy_url(
1462 config
1463 .proxy_url
1464 .as_ref()
1465 .map(|s| s.expose_secret().to_owned()),
1466 )
1467 .redirect_policy(HttpRedirectPolicy::Reject)
1468 .use_system_proxy(false)
1469 .redact_url(true)
1470 .build()
1471 .map_err(|_| anyhow::anyhow!("failed to build Kalshi HTTP transport"))?;
1472 Ok(Self {
1473 client,
1474 base_url,
1475 credential: None,
1476 cancellation: CancellationToken::new(),
1477 dispatch_check: None,
1478 quota: Arc::new(KalshiQuota::new()),
1479 timeout_ms: config.http_timeout_secs.saturating_mul(1_000),
1480 })
1481 }
1482}
1483
1484type QuotaOwners = HashMap<(String, Vec<u8>), Arc<KalshiQuota>>;
1485
1486#[derive(Clone, Copy, PartialEq, Eq)]
1487enum Operation {
1488 Read,
1489 Write,
1490}
1491
1492struct PreparedRequest {
1493 method: Method,
1494 url: Url,
1495 body: Option<Vec<u8>>,
1496 authenticated: bool,
1497 operation: Operation,
1498 charge: Charge,
1499 discovery: bool,
1500}
1501
1502fn request_charge(
1503 method: &Method,
1504 path: &[&str],
1505 query: &str,
1506 body: Option<&serde_json::Value>,
1507 operation: Operation,
1508) -> Result<Charge, KalshiHttpError> {
1509 let batch =
1510 operation == Operation::Write && path == ["portfolio", "events", "orders", "batched"];
1511
1512 let items = if batch {
1513 u32::try_from(
1514 body.and_then(|value| value.get("orders"))
1515 .and_then(serde_json::Value::as_array)
1516 .map_or(0, Vec::len),
1517 )
1518 .map_err(|_| KalshiHttpError::Quota("batch item count overflow"))?
1519 } else {
1520 1
1521 };
1522
1523 let shard = body
1524 .and_then(|value| value.get("exchange_index"))
1525 .and_then(serde_json::Value::as_u64)
1526 .or_else(|| {
1527 url::form_urlencoded::parse(query.as_bytes())
1528 .find(|(name, _)| name == "exchange_index")
1529 .and_then(|(_, value)| value.parse().ok())
1530 });
1531
1532 let bucket = match operation {
1533 Operation::Read if path == ["portfolio", "balance"] => Bucket::Balance,
1534 Operation::Read => Bucket::Read,
1535 Operation::Write if batch => Bucket::Write(0),
1536 Operation::Write => match shard {
1537 Some(shard) => Bucket::Write(
1538 u32::try_from(shard)
1539 .map_err(|_| KalshiHttpError::Quota("invalid exchange shard"))?,
1540 ),
1541 None => Bucket::Auto,
1542 },
1543 };
1544
1545 Ok(Charge {
1546 method: method.as_str().into(),
1547 path: format!("/trade-api/v2/{}", path.join("/")),
1548 bucket,
1549 items,
1550 })
1551}
1552
1553pub fn stable_object_key_bytes(value: serde_json::Value) -> Result<Vec<u8>, serde_json::Error> {
1564 serde_json::to_vec(&sorted_object_keys(value))
1565}
1566
1567fn sorted_object_keys(value: serde_json::Value) -> serde_json::Value {
1568 match value {
1569 serde_json::Value::Object(map) => {
1570 let mut entries: Vec<_> = map.into_iter().collect();
1571 entries.sort_by(|left, right| left.0.cmp(&right.0));
1572 serde_json::Value::Object(
1573 entries
1574 .into_iter()
1575 .map(|(key, child)| (key, sorted_object_keys(child)))
1576 .collect(),
1577 )
1578 }
1579 serde_json::Value::Array(values) => {
1580 serde_json::Value::Array(values.into_iter().map(sorted_object_keys).collect())
1581 }
1582 value => value,
1583 }
1584}
1585
1586trait CursorPage {
1587 type Item;
1588
1589 fn into_parts(self) -> (Vec<Self::Item>, Field<String>);
1590}
1591
1592macro_rules! cursor_page {
1593 ($($response:ty => $field:ident : $record:ty),+ $(,)?) => { $(
1594 impl CursorPage for $response {
1595 type Item = $record;
1596 fn into_parts(self) -> (Vec<Self::Item>, Field<String>) { (self.$field, self.cursor) }
1597 }
1598 )+ };
1599}
1600
1601cursor_page!(MarketsResponse => markets: Market, EventsResponse => events: Event, TradesResponse => trades: Trade, FillsResponse => fills: Fill, OrdersResponse => orders: Order, SettlementsResponse => settlements: Settlement);
1602
1603fn validate_subaccount(subaccount: u32) -> Result<(), KalshiHttpError> {
1604 if subaccount > MAX_SUBACCOUNT {
1605 return Err(KalshiHttpError::Validation("subaccount must be in [0, 63]"));
1606 }
1607
1608 Ok(())
1609}
1610
1611fn validate_candlesticks(query: &CandlesticksQuery) -> Result<(), KalshiHttpError> {
1612 if query.start_ts > query.end_ts {
1613 return Err(KalshiHttpError::Validation(
1614 "invalid candle window or period",
1615 ));
1616 }
1617
1618 Ok(())
1619}
1620
1621fn validate_order_values(
1622 ticker: &str,
1623 price: FixedPoint,
1624 count: FixedPoint,
1625) -> Result<(), KalshiHttpError> {
1626 use rust_decimal::Decimal;
1627
1628 if ticker.is_empty()
1629 || price.0 < Decimal::ZERO
1630 || price.0 > Decimal::ONE
1631 || price.0.scale() > 4
1632 || count.0 <= Decimal::ZERO
1633 || count.0.scale() > 2
1634 {
1635 return Err(KalshiHttpError::Validation(
1636 "invalid ticker, price, or count",
1637 ));
1638 }
1639
1640 Ok(())
1641}
1642
1643pub fn validate_create(request: &CreateOrderRequest) -> Result<(), KalshiHttpError> {
1650 validate_subaccount(request.subaccount)?;
1651 validate_order_values(&request.ticker, request.price, request.count)?;
1652 if request.reduce_only == Some(true) && request.time_in_force != TimeInForce::ImmediateOrCancel
1653 {
1654 return Err(KalshiHttpError::Validation(
1655 "reduce-only requires immediate-or-cancel",
1656 ));
1657 }
1658
1659 if request.expiration_time.is_some() && request.time_in_force != TimeInForce::GoodTillCanceled {
1660 return Err(KalshiHttpError::Validation(
1661 "expiration requires good-till-canceled",
1662 ));
1663 }
1664
1665 Ok(())
1666}
1667
1668impl Debug for KalshiHttpClient {
1669 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1670 f.debug_struct(stringify!(KalshiHttpClient))
1671 .field("base_url", &self.base_url)
1672 .finish_non_exhaustive()
1673 }
1674}
1675
1676#[derive(serde::Serialize)]
1677struct CancelQuery<'a> {
1678 #[serde(flatten)]
1679 account: &'a AccountQuery,
1680 #[serde(skip_serializing_if = "Option::is_none")]
1681 market_ticker: Option<&'a str>,
1682}
1683
1684#[cfg(test)]
1685mod tests {
1686 use rstest::rstest;
1687 #[cfg(not(all(feature = "simulation", madsim)))]
1688 use tokio::io::{AsyncReadExt, AsyncWriteExt};
1689
1690 use super::*;
1691
1692 #[rstest]
1693 fn operation_routes_and_batch_counts_follow_wire_scope() {
1694 let requests: serde_json::Value =
1695 serde_json::from_str(include_str!("../../test_data/rest_requests.json")).unwrap();
1696 let single = request_charge(
1697 &Method::POST,
1698 &["portfolio", "events", "orders"],
1699 "",
1700 Some(&requests["create"]),
1701 Operation::Write,
1702 )
1703 .unwrap();
1704 assert_eq!(single.bucket, Bucket::Write(3));
1705 assert_eq!(single.items, 1);
1706 let batch = request_charge(
1707 &Method::POST,
1708 &["portfolio", "events", "orders", "batched"],
1709 "",
1710 Some(&requests["batch_create"]),
1711 Operation::Write,
1712 )
1713 .unwrap();
1714 assert_eq!(batch.bucket, Bucket::Write(0));
1715 assert_eq!(batch.items, 2);
1716 let cancel = request_charge(
1717 &Method::DELETE,
1718 &["portfolio", "events", "orders", "id"],
1719 "exchange_index=2",
1720 None,
1721 Operation::Write,
1722 )
1723 .unwrap();
1724 assert_eq!(cancel.bucket, Bucket::Write(2));
1725 assert_eq!(cancel.method, "DELETE");
1726 assert_eq!(cancel.path, "/trade-api/v2/portfolio/events/orders/id");
1727 let auto = request_charge(
1728 &Method::POST,
1729 &["portfolio", "events", "orders"],
1730 "",
1731 None,
1732 Operation::Write,
1733 )
1734 .unwrap();
1735 assert_eq!(auto.bucket, Bucket::Auto);
1736 let balance = request_charge(
1737 &Method::GET,
1738 &["portfolio", "balance"],
1739 "exchange_index=3",
1740 None,
1741 Operation::Read,
1742 )
1743 .unwrap();
1744 assert_eq!(balance.bucket, Bucket::Balance);
1745 let market = request_charge(
1746 &Method::GET,
1747 &["markets", "batched"],
1748 "",
1749 None,
1750 Operation::Read,
1751 )
1752 .unwrap();
1753 assert_eq!(market.method, "GET");
1754 assert_eq!(market.path, "/trade-api/v2/markets/batched");
1755 assert_eq!(market.bucket, Bucket::Read);
1756 assert_eq!(market.items, 1);
1757 }
1758
1759 #[cfg(not(all(feature = "simulation", madsim)))]
1760 #[tokio::test]
1761 async fn write_dispatch_check_runs_after_quota_admission() {
1762 let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
1763 let permitted = Arc::new(AtomicBool::new(true));
1764 let check = Arc::clone(&permitted);
1765
1766 let config = KalshiDataClientConfig {
1767 base_url_http: Some(format!("http://{}", listener.local_addr().unwrap()).into()),
1768 ..Default::default()
1769 };
1770
1771 let client = KalshiHttpClient::new(&config)
1772 .unwrap()
1773 .with_dispatch_check(CancellationToken::new(), move || {
1774 check.load(Ordering::Acquire)
1775 });
1776
1777 let mut fixtures: serde_json::Value =
1778 serde_json::from_str(include_str!("../../test_data/rest_responses.json")).unwrap();
1779 fixtures["limits"]["write"]["refill_rate"] = 1.into();
1780 fixtures["limits"]["write"]["bucket_capacity"] = 1.into();
1781 fixtures["costs"]["default_cost"] = 1.into();
1782 let limits = serde_json::from_value(fixtures["limits"].clone()).unwrap();
1783 let costs = serde_json::from_value(fixtures["costs"].clone()).unwrap();
1784 let unix_ms = i64::try_from(get_atomic_clock_realtime().get_time_ms()).unwrap();
1785 client.quota.set_limits(&limits, unix_ms).unwrap();
1786 client.quota.set_costs(costs).unwrap();
1787 let body = serde_json::from_str::<serde_json::Value>(include_str!(
1788 "../../test_data/rest_requests.json"
1789 ))
1790 .unwrap()["quota_batch"]
1791 .clone();
1792 let path = ["portfolio", "events", "orders", "batched"];
1793 let charge =
1794 request_charge(&Method::POST, &path, "", Some(&body), Operation::Write).unwrap();
1795 client.quota.acquire(&charge).await.unwrap();
1796 let request = client.send_raw(
1797 Method::POST,
1798 &path,
1799 &(),
1800 Some(&body),
1801 false,
1802 Operation::Write,
1803 );
1804 tokio::pin!(request);
1805 assert!(futures_util::poll!(request.as_mut()).is_pending());
1806 permitted.store(false, Ordering::Release);
1807 let result = tokio::select! {
1808 result = &mut request => result,
1809 _ = listener.accept() => panic!("Invalidated write reached the HTTP transport"),
1810 };
1811 assert!(matches!(
1812 result,
1813 Err(KalshiHttpError::Canceled { dispatched: false })
1814 ));
1815 permitted.store(true, Ordering::Release);
1816
1817 let peer = tokio::spawn(async move {
1818 let (mut stream, _) = listener.accept().await.unwrap();
1819 let mut data = [0_u8; 1024];
1820 let read = stream.read(&mut data).await.unwrap();
1821 assert!(
1822 std::str::from_utf8(&data[..read])
1823 .unwrap()
1824 .starts_with("POST /portfolio/events/orders/batched ")
1825 );
1826 stream
1827 .write_all(b"HTTP/1.1 200 OK\r\nContent-Length: 0\r\nConnection: close\r\n\r\n")
1828 .await
1829 .unwrap();
1830 });
1831
1832 let response = client
1833 .send_raw(
1834 Method::POST,
1835 &path,
1836 &(),
1837 Some(&body),
1838 false,
1839 Operation::Write,
1840 )
1841 .await
1842 .unwrap();
1843 assert_eq!(response.status.as_u16(), 200);
1844 peer.await.unwrap();
1845 }
1846}