Skip to main content

nautilus_kalshi/http/
client.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Typed Kalshi REST reads and V2 order transport.
17
18use 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/// REST transport for public discovery, account reports, and V2 order requests.
55///
56/// Public construction does not resolve credentials. Authenticated construction validates them
57/// before traffic. Safe reads retry transient failures twice at the adapter, acquiring quota before
58/// each fresh timestamp and signature. Redirects are never followed.
59/// Typed mutations use one adapter-owned attempt. Lower-level transport retries can replay the
60/// original signed request without entering adapter quota or signing. Callers reconcile uncertain
61/// or mismatched acknowledgements.
62#[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    /// Validates the data-client settings and creates the public transport.
75    ///
76    /// Explicit proxies override direct routing. Ambient proxy variables are ignored.
77    ///
78    /// # Errors
79    ///
80    /// Returns an error if config validation or transport construction fails.
81    pub fn new(config: &KalshiDataClientConfig) -> anyhow::Result<Self> {
82        Self::build(config)
83    }
84
85    /// Creates an authenticated transport from explicit or selected-environment credentials.
86    ///
87    /// # Errors
88    ///
89    /// Returns an error if config, credentials, key encoding, or transport construction is invalid.
90    pub fn new_authenticated(config: &KalshiDataClientConfig) -> anyhow::Result<Self> {
91        Self::authenticated(config, None)
92    }
93
94    /// Creates an authenticated transport using the supplied account quota owner.
95    ///
96    /// Share one owner across data and execution clients, including distinct keys for the same
97    /// account. A key already bound to another owner is rejected before traffic.
98    ///
99    /// # Errors
100    ///
101    /// Returns an error if settings or credentials are invalid, or quota ownership conflicts.
102    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    /// Creates a public data transport sharing an authenticated account's quota.
110    ///
111    /// # Errors
112    ///
113    /// Returns an error if settings or transport construction is invalid.
114    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    /// Refreshes authenticated limits and endpoint costs for the shared account owner.
124    ///
125    /// Transports with credentials refresh lazily before ordinary traffic, including public reads.
126    /// Fresh discovery or an active five-second fallback window returns without traffic.
127    /// Failed discovery uses Basic read limits, one balance read per second, and a conservative
128    /// 50-token read cost during the fallback window. Expiry uses those read budgets until refresh;
129    /// writes wait for discovery and remain disabled if it fails. A subaccount-restricted key uses
130    /// conservative Basic limits when the limits endpoint denies its scope; endpoint cost discovery
131    /// remains required.
132    ///
133    /// # Errors
134    ///
135    /// Returns an error if endpoint costs are unavailable or invalid, or limit discovery fails
136    /// without a recognized subaccount-restriction denial.
137    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    /// Fetches the public exchange status without authentication.
192    ///
193    /// Non-success HTTP statuses remain responses for the caller to inspect.
194    ///
195    /// # Errors
196    ///
197    /// Returns an error if the request fails or exceeds the configured timeout.
198    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    /// Fetches the authenticated balance on an explicit exchange shard.
215    ///
216    /// # Errors
217    ///
218    /// Returns an error if authentication, quota admission, retries, or transport fails.
219    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    /// Cancels typed REST requests on this client and its clones.
239    ///
240    /// Cancellation after dispatch does not establish whether a mutation reached the venue.
241    pub fn cancel(&self) {
242        self.cancellation.cancel();
243    }
244
245    /// Fetches typed public exchange availability.
246    ///
247    /// Documented maintenance responses (HTTP 500, 503, and 504) return their typed status body.
248    /// Use [`Self::get_exchange_status`] when the HTTP status and response headers are required.
249    ///
250    /// # Errors
251    ///
252    /// Returns an error if transport, cancellation, status, or response decoding fails.
253    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    /// Fetches one live market discovery page.
273    ///
274    /// # Errors
275    ///
276    /// Returns an error if encoding, transport, cancellation, status, or decoding fails.
277    pub async fn get_markets(
278        &self,
279        query: &MarketsQuery,
280    ) -> Result<MarketsResponse, KalshiHttpError> {
281        self.get(&["markets"], query, false).await
282    }
283
284    /// Fetches one market by ticker.
285    ///
286    /// # Errors
287    ///
288    /// Returns an error if the ticker, transport, status, cancellation, or decoding is invalid.
289    pub async fn get_market(&self, ticker: &str) -> Result<MarketResponse, KalshiHttpError> {
290        self.get(&["markets", ticker], &(), false).await
291    }
292
293    /// Fetches one archived market discovery page.
294    ///
295    /// # Errors
296    ///
297    /// Returns an error if encoding, transport, cancellation, status, or decoding fails.
298    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    /// Fetches one archived market by ticker.
306    ///
307    /// # Errors
308    ///
309    /// Returns an error if the ticker, transport, status, cancellation, or decoding is invalid.
310    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    /// Fetches one event discovery page.
319    ///
320    /// # Errors
321    ///
322    /// Returns an error if encoding, transport, cancellation, status, or decoding fails.
323    pub async fn get_events(&self, query: &EventsQuery) -> Result<EventsResponse, KalshiHttpError> {
324        self.get(&["events"], query, false).await
325    }
326
327    /// Fetches one event and its markets.
328    ///
329    /// # Errors
330    ///
331    /// Returns an error if the ticker, encoding, transport, cancellation, status, or decoding fails.
332    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    /// Fetches series definitions.
341    ///
342    /// # Errors
343    ///
344    /// Returns an error if encoding, transport, cancellation, status, or decoding fails.
345    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    /// Fetches one series definition.
353    ///
354    /// # Errors
355    ///
356    /// Returns an error if the ticker, transport, cancellation, status, or decoding is invalid.
357    pub async fn get_series(&self, ticker: &str) -> Result<SeriesResponse, KalshiHttpError> {
358        self.get(&["series", ticker], &(), false).await
359    }
360
361    /// Fetches exact YES and NO bid levels; zero depth requests all levels.
362    ///
363    /// # Errors
364    ///
365    /// Returns an error if depth exceeds 100, or transport, cancellation, status, or decoding fails.
366    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    /// Fetches one public trade page from the live tier.
384    ///
385    /// # Errors
386    ///
387    /// Returns an error if encoding, transport, cancellation, status, or decoding fails.
388    pub async fn get_trades(&self, query: &TradesQuery) -> Result<TradesResponse, KalshiHttpError> {
389        self.get(&["markets", "trades"], query, false).await
390    }
391
392    /// Fetches one public trade page from the archive.
393    ///
394    /// # Errors
395    ///
396    /// Returns an error if encoding, transport, cancellation, status, or decoding fails.
397    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    /// Fetches live market candles for a supported interval.
405    ///
406    /// # Errors
407    ///
408    /// Returns an error if the window, interval, transport, status, cancellation, or decoding fails.
409    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    /// Fetches archived market candles.
425    ///
426    /// # Errors
427    ///
428    /// Returns an error if the window, interval, transport, status, cancellation, or decoding fails.
429    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    /// Fetches each archive partition's authoritative cutoff.
444    ///
445    /// # Errors
446    ///
447    /// Returns an error if transport, cancellation, status, or decoding fails.
448    pub async fn get_historical_cutoff(&self) -> Result<HistoricalCutoff, KalshiHttpError> {
449        self.get(&["historical", "cutoff"], &(), false).await
450    }
451
452    /// Fetches typed collateral for an explicit subaccount and exchange shard.
453    ///
454    /// # Errors
455    ///
456    /// Returns an error if scope, authentication, transport, cancellation, status, or decoding fails.
457    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    /// Fetches one live market/event position page.
466    ///
467    /// # Errors
468    ///
469    /// Returns an error if scope, authentication, encoding, transport, cancellation, status, or decoding fails.
470    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    /// Fetches one archived market/event position page.
479    ///
480    /// # Errors
481    ///
482    /// Returns an error if scope, authentication, encoding, transport, cancellation, status, or decoding fails.
483    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    /// Fetches one live fills page.
492    ///
493    /// # Errors
494    ///
495    /// Returns an error if scope, authentication, encoding, transport, cancellation, status, or decoding fails.
496    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    /// Fetches one archived fills page.
502    ///
503    /// # Errors
504    ///
505    /// Returns an error if scope, authentication, encoding, transport, cancellation, status, or decoding fails.
506    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    /// Fetches one live orders page.
515    ///
516    /// # Errors
517    ///
518    /// Returns an error if scope, authentication, encoding, transport, cancellation, status, or decoding fails.
519    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    /// Fetches one order by its venue identity.
525    ///
526    /// # Errors
527    ///
528    /// Returns an error if identity, authentication, transport, cancellation, status, or decoding fails.
529    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    /// Fetches one archived orders page.
535    ///
536    /// # Errors
537    ///
538    /// Returns an error if scope, authentication, encoding, transport, cancellation, status, or decoding fails.
539    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    /// Fetches one page of settlements still held in the live tier.
548    ///
549    /// # Errors
550    ///
551    /// Returns an error if scope, authentication, encoding, transport, cancellation, status, or decoding fails.
552    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    /// Fetches token limits and updates the shared account quota owner.
561    ///
562    /// # Errors
563    ///
564    /// Returns an error if authentication, transport, cancellation, status, decoding, or quota validation fails.
565    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    /// Fetches endpoint token costs and updates the shared account quota owner.
574    ///
575    /// # Errors
576    ///
577    /// Returns an error if transport, cancellation, status, decoding, or quota validation fails.
578    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    /// Sends one V2 limit-order request without replay.
587    ///
588    /// # Errors
589    ///
590    /// Returns an error if validation, authentication, encoding, transport, cancellation, status, or decoding fails.
591    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    /// Sends independent V2 order requests once in one batch.
607    ///
608    /// Each child requires a unique, non-empty client order identity. Reply identities must match.
609    ///
610    /// # Errors
611    ///
612    /// Returns an error if validation, authentication, encoding, transport, cancellation, status, or decoding fails.
613    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    /// Sends a V2 amendment once. Expiration remains a raw protocol field.
684    ///
685    /// Callers verify returned order and client identities, then obtain authoritative order reports.
686    ///
687    /// # Errors
688    ///
689    /// Returns an error if scope, values, authentication, encoding, transport, cancellation, status, or decoding fails.
690    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    /// Sends a V2 decrease once, using exactly one selector.
709    ///
710    /// Callers verify returned order and client identities, then obtain authoritative order reports.
711    ///
712    /// # Errors
713    ///
714    /// Returns an error if scope, selectors, values, authentication, encoding, transport, cancellation, status, or decoding fails.
715    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    /// Cancels one selected V2 order once on an explicit shard.
746    ///
747    /// Callers verify returned order and client identities, then obtain authoritative order reports.
748    ///
749    /// # Errors
750    ///
751    /// Returns an error if scope, authentication, encoding, transport, cancellation, status, or decoding fails.
752    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    /// Cancels only the explicitly selected V2 orders, without replay.
781    ///
782    /// Selected order identities must be unique. Reply identities must match the selected set.
783    ///
784    /// # Errors
785    ///
786    /// Returns an error if scope, identities, authentication, encoding, transport, cancellation, status, or decoding fails.
787    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    /// Collects live market pages with stable-ticker deduplication and a page budget.
848    ///
849    /// # Errors
850    ///
851    /// Returns an error if any source fails, the budget is zero, or pagination makes no progress.
852    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    /// Collects archived market pages with stable-ticker deduplication.
867    ///
868    /// # Errors
869    ///
870    /// Returns an error if any source fails, the budget is zero, or pagination makes no progress.
871    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    /// Collects event pages with stable-event-identity deduplication.
886    ///
887    /// # Errors
888    ///
889    /// Returns an error if any source fails, the budget is zero, or pagination makes no progress.
890    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    /// Collects live trades, deduplicating inclusive boundaries by trade identity.
905    ///
906    /// # Errors
907    ///
908    /// Returns an error if any source fails, the budget is zero, or pagination makes no progress.
909    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    /// Collects archived trades with stable-trade-identity deduplication.
924    ///
925    /// # Errors
926    ///
927    /// Returns an error if any source fails, the budget is zero, or pagination makes no progress.
928    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    /// Collects live fills, deduplicating by shard and fill identity.
943    ///
944    /// # Errors
945    ///
946    /// Returns an error if any source fails, the budget is zero, or pagination makes no progress.
947    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    /// Collects archived fills, deduplicating by shard and fill identity.
962    ///
963    /// # Errors
964    ///
965    /// Returns an error if any source fails, the budget is zero, or pagination makes no progress.
966    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    /// Collects live order reports with stable-order-identity deduplication.
981    ///
982    /// # Errors
983    ///
984    /// Returns an error if any source fails, the budget is zero, or pagination makes no progress.
985    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    /// Collects archived order reports with stable-order-identity deduplication.
1000    ///
1001    /// # Errors
1002    ///
1003    /// Returns an error if any source fails, the budget is zero, or pagination makes no progress.
1004    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    /// Collects live settlement records with shard/ticker deduplication.
1019    ///
1020    /// # Errors
1021    ///
1022    /// Returns an error if any source fails, the budget is zero, or pagination makes no progress.
1023    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    /// Collects live market and event positions without discarding either list.
1038    ///
1039    /// # Errors
1040    ///
1041    /// Returns an error if any source fails, the budget is zero, or pagination makes no progress.
1042    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    /// Collects archived market and event positions; shard identity stays record-level.
1056    ///
1057    /// # Errors
1058    ///
1059    /// Returns an error if any source fails, the budget is zero, or pagination makes no progress.
1060    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
1553// Workspace builds enable serde_json/preserve_order through another crate, so
1554// object key order would otherwise follow that feature.
1555/// Encodes one JSON value with object keys sorted at every level.
1556///
1557/// Workspace builds can enable `serde_json/preserve_order`. Sorted keys keep the encoded body
1558/// independent of map insertion order. The signer does not include the body.
1559///
1560/// # Errors
1561///
1562/// Returns an error if JSON encoding fails.
1563pub 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
1643/// Validates one V2 create request before it is encoded.
1644///
1645/// # Errors
1646///
1647/// Returns an error if the account, ticker, price, count, reduce-only flag, or expiration is
1648/// unsupported.
1649pub 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}