Skip to main content

nautilus_kalshi/http/
query.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//! Kalshi REST request and query builders.
17
18use serde::{Deserialize, Serialize, Serializer};
19
20use super::models::{BookSide, FixedPoint, SelfTradePrevention, TimeInForce};
21use crate::common::enums::{
22    CandlestickInterval, EventStatusFilter, MarketStatusFilter, MveFilter, MveHistoricalFilter,
23    OrderStatusFilter, PositionCountFilter, PositionSettlementStatus,
24};
25
26/// Live market discovery filters; unset values are omitted.
27#[derive(Debug, Clone, Default, Serialize, Deserialize)]
28pub struct MarketsQuery {
29    #[serde(skip_serializing_if = "Option::is_none")]
30    pub limit: Option<u32>,
31    #[serde(skip_serializing_if = "Option::is_none")]
32    pub cursor: Option<String>,
33    #[serde(skip_serializing_if = "Option::is_none")]
34    pub event_ticker: Option<String>,
35    #[serde(skip_serializing_if = "Option::is_none")]
36    pub series_ticker: Option<String>,
37    #[serde(skip_serializing_if = "Option::is_none")]
38    pub min_created_ts: Option<i64>,
39    #[serde(skip_serializing_if = "Option::is_none")]
40    pub max_created_ts: Option<i64>,
41    #[serde(skip_serializing_if = "Option::is_none")]
42    pub min_updated_ts: Option<i64>,
43    #[serde(skip_serializing_if = "Option::is_none")]
44    pub max_updated_ts: Option<i64>,
45    #[serde(skip_serializing_if = "Option::is_none")]
46    pub min_close_ts: Option<i64>,
47    #[serde(skip_serializing_if = "Option::is_none")]
48    pub max_close_ts: Option<i64>,
49    #[serde(skip_serializing_if = "Option::is_none")]
50    pub min_settled_ts: Option<i64>,
51    #[serde(skip_serializing_if = "Option::is_none")]
52    pub max_settled_ts: Option<i64>,
53    #[serde(skip_serializing_if = "Option::is_none")]
54    pub status: Option<MarketStatusFilter>,
55    #[serde(skip_serializing_if = "Option::is_none")]
56    pub tickers: Option<String>,
57    #[serde(skip_serializing_if = "Option::is_none")]
58    pub mve_filter: Option<MveFilter>,
59}
60
61/// Archived market discovery filters.
62#[derive(Debug, Clone, Default, Serialize)]
63pub struct HistoricalMarketsQuery {
64    #[serde(skip_serializing_if = "Option::is_none")]
65    pub limit: Option<u32>,
66    #[serde(skip_serializing_if = "Option::is_none")]
67    pub cursor: Option<String>,
68    #[serde(skip_serializing_if = "Option::is_none")]
69    pub tickers: Option<String>,
70    #[serde(skip_serializing_if = "Option::is_none")]
71    pub event_ticker: Option<String>,
72    #[serde(skip_serializing_if = "Option::is_none")]
73    pub series_ticker: Option<String>,
74    #[serde(skip_serializing_if = "Option::is_none")]
75    pub mve_filter: Option<MveHistoricalFilter>,
76}
77
78/// Event discovery filters.
79#[derive(Debug, Clone, Default, Serialize)]
80pub struct EventsQuery {
81    #[serde(skip_serializing_if = "Option::is_none")]
82    pub limit: Option<u32>,
83    #[serde(skip_serializing_if = "Option::is_none")]
84    pub cursor: Option<String>,
85    #[serde(skip_serializing_if = "Option::is_none")]
86    pub with_nested_markets: Option<bool>,
87    #[serde(skip_serializing_if = "Option::is_none")]
88    pub status: Option<EventStatusFilter>,
89    #[serde(skip_serializing_if = "Option::is_none")]
90    pub series_ticker: Option<String>,
91    #[serde(skip_serializing_if = "Option::is_none")]
92    pub tickers: Option<String>,
93    #[serde(skip_serializing_if = "Option::is_none")]
94    pub min_close_ts: Option<i64>,
95    #[serde(skip_serializing_if = "Option::is_none")]
96    pub min_updated_ts: Option<i64>,
97}
98
99/// Optional market inclusion for one event.
100#[derive(Debug, Clone, Default, Serialize)]
101pub struct EventQuery {
102    #[serde(skip_serializing_if = "Option::is_none")]
103    pub exclude_markets: Option<bool>,
104    #[serde(skip_serializing_if = "Option::is_none")]
105    pub with_nested_markets: Option<bool>,
106}
107
108/// Series discovery filters.
109#[derive(Debug, Clone, Default, Serialize)]
110pub struct SeriesQuery {
111    #[serde(skip_serializing_if = "Option::is_none")]
112    pub category: Option<String>,
113    #[serde(skip_serializing_if = "Option::is_none")]
114    pub tags: Option<String>,
115    #[serde(skip_serializing_if = "Option::is_none")]
116    pub include_volume: Option<bool>,
117    #[serde(skip_serializing_if = "Option::is_none")]
118    pub min_updated_ts: Option<i64>,
119}
120
121/// Shared live/archive public-trade filters.
122#[derive(Debug, Clone, Default, Serialize)]
123pub struct TradesQuery {
124    #[serde(skip_serializing_if = "Option::is_none")]
125    pub limit: Option<u32>,
126    #[serde(skip_serializing_if = "Option::is_none")]
127    pub cursor: Option<String>,
128    #[serde(skip_serializing_if = "Option::is_none")]
129    pub ticker: Option<String>,
130    #[serde(skip_serializing_if = "Option::is_none")]
131    pub min_ts: Option<i64>,
132    #[serde(skip_serializing_if = "Option::is_none")]
133    pub max_ts: Option<i64>,
134    #[serde(skip_serializing_if = "Option::is_none")]
135    pub is_block_trade: Option<bool>,
136}
137
138/// Candle window in Unix seconds and interval in minutes (1, 60, or 1440).
139#[derive(Debug, Clone, Serialize)]
140pub struct CandlesticksQuery {
141    pub start_ts: i64,
142    pub end_ts: i64,
143    pub period_interval: CandlestickInterval,
144}
145
146/// Explicit primary-account shard selection.
147#[derive(Debug, Clone, Copy, Serialize)]
148pub struct AccountQuery {
149    pub subaccount: u32,
150    pub exchange_index: u32,
151}
152
153/// Live order report filters.
154#[derive(Debug, Clone, Default, Serialize)]
155pub struct OrdersQuery {
156    #[serde(skip_serializing_if = "Option::is_none")]
157    pub ticker: Option<String>,
158    #[serde(skip_serializing_if = "Option::is_none")]
159    pub event_ticker: Option<String>,
160    #[serde(skip_serializing_if = "Option::is_none")]
161    pub min_ts: Option<i64>,
162    #[serde(skip_serializing_if = "Option::is_none")]
163    pub max_ts: Option<i64>,
164    #[serde(skip_serializing_if = "Option::is_none")]
165    pub status: Option<OrderStatusFilter>,
166    #[serde(skip_serializing_if = "Option::is_none")]
167    pub limit: Option<u32>,
168    #[serde(skip_serializing_if = "Option::is_none")]
169    pub cursor: Option<String>,
170    pub subaccount: u32,
171    pub exchange_index: u32,
172}
173
174/// Private fill report filters.
175#[derive(Debug, Clone, Default, Serialize)]
176pub struct FillsQuery {
177    #[serde(skip_serializing_if = "Option::is_none")]
178    pub ticker: Option<String>,
179    #[serde(skip_serializing_if = "Option::is_none")]
180    pub order_id: Option<String>,
181    #[serde(skip_serializing_if = "Option::is_none")]
182    pub min_ts: Option<i64>,
183    #[serde(skip_serializing_if = "Option::is_none")]
184    pub max_ts: Option<i64>,
185    #[serde(skip_serializing_if = "Option::is_none")]
186    pub limit: Option<u32>,
187    #[serde(skip_serializing_if = "Option::is_none")]
188    pub cursor: Option<String>,
189    pub subaccount: u32,
190    pub exchange_index: u32,
191}
192
193/// Live position report filters.
194#[derive(Debug, Clone, Default, Serialize)]
195pub struct PositionsQuery {
196    #[serde(skip_serializing_if = "Option::is_none")]
197    pub cursor: Option<String>,
198    #[serde(skip_serializing_if = "Option::is_none")]
199    pub limit: Option<u32>,
200    #[serde(skip_serializing_if = "Option::is_none")]
201    #[serde(serialize_with = "serialize_count_filter")]
202    pub count_filter: Option<Vec<PositionCountFilter>>,
203    #[serde(skip_serializing_if = "Option::is_none")]
204    pub settlement_status: Option<PositionSettlementStatus>,
205    #[serde(skip_serializing_if = "Option::is_none")]
206    pub ticker: Option<String>,
207    #[serde(skip_serializing_if = "Option::is_none")]
208    pub event_ticker: Option<String>,
209    pub subaccount: u32,
210    pub exchange_index: u32,
211}
212
213/// Archived order/fill filters; archive endpoints do not accept a shard selector.
214#[derive(Debug, Clone, Default, Serialize)]
215pub struct HistoryQuery {
216    #[serde(skip_serializing_if = "Option::is_none")]
217    pub ticker: Option<String>,
218    #[serde(skip_serializing_if = "Option::is_none")]
219    pub min_ts: Option<i64>,
220    #[serde(skip_serializing_if = "Option::is_none")]
221    pub max_ts: Option<i64>,
222    #[serde(skip_serializing_if = "Option::is_none")]
223    pub limit: Option<u32>,
224    #[serde(skip_serializing_if = "Option::is_none")]
225    pub cursor: Option<String>,
226    pub subaccount: u32,
227}
228
229/// Archived positions; the caller filters record-level shard identity.
230#[derive(Debug, Clone, Default, Serialize)]
231pub struct HistoricalPositionsQuery {
232    #[serde(skip_serializing_if = "Option::is_none")]
233    pub ticker: Option<String>,
234    #[serde(skip_serializing_if = "Option::is_none")]
235    pub event_ticker: Option<String>,
236    #[serde(skip_serializing_if = "Option::is_none")]
237    pub limit: Option<u32>,
238    #[serde(skip_serializing_if = "Option::is_none")]
239    pub cursor: Option<String>,
240    pub subaccount: u32,
241}
242
243/// Settlements still in the live tier.
244#[derive(Debug, Clone, Default, Serialize)]
245pub struct SettlementsQuery {
246    #[serde(skip_serializing_if = "Option::is_none")]
247    pub ticker: Option<String>,
248    #[serde(skip_serializing_if = "Option::is_none")]
249    pub event_ticker: Option<String>,
250    #[serde(skip_serializing_if = "Option::is_none")]
251    pub min_ts: Option<i64>,
252    #[serde(skip_serializing_if = "Option::is_none")]
253    pub max_ts: Option<i64>,
254    #[serde(skip_serializing_if = "Option::is_none")]
255    pub limit: Option<u32>,
256    #[serde(skip_serializing_if = "Option::is_none")]
257    pub cursor: Option<String>,
258    pub subaccount: u32,
259}
260
261/// A V2 limit order using YES-price book-side semantics.
262///
263/// Prices serialize with four decimal places without rounding.
264#[derive(Debug, Clone, Serialize)]
265pub struct CreateOrderRequest {
266    pub ticker: String,
267    pub side: BookSide,
268    pub count: FixedPoint,
269    #[serde(serialize_with = "serialize_price")]
270    pub price: FixedPoint,
271    pub time_in_force: TimeInForce,
272    pub self_trade_prevention_type: SelfTradePrevention,
273    pub subaccount: u32,
274    pub exchange_index: u32,
275    #[serde(skip_serializing_if = "Option::is_none")]
276    pub client_order_id: Option<String>,
277    #[serde(skip_serializing_if = "Option::is_none")]
278    pub expiration_time: Option<i64>,
279    #[serde(skip_serializing_if = "Option::is_none")]
280    pub post_only: Option<bool>,
281    #[serde(skip_serializing_if = "Option::is_none")]
282    pub cancel_order_on_pause: Option<bool>,
283    #[serde(skip_serializing_if = "Option::is_none")]
284    pub reduce_only: Option<bool>,
285}
286
287/// V2 amendment; count is total filled plus desired remaining contracts.
288///
289/// Prices serialize with four decimal places without rounding.
290#[derive(Debug, Clone, Serialize)]
291pub struct AmendOrderRequest {
292    pub ticker: String,
293    pub side: BookSide,
294    #[serde(serialize_with = "serialize_price")]
295    pub price: FixedPoint,
296    pub count: FixedPoint,
297    pub exchange_index: u32,
298    #[serde(skip_serializing_if = "Option::is_none")]
299    pub client_order_id: Option<String>,
300    #[serde(skip_serializing_if = "Option::is_none")]
301    pub updated_client_order_id: Option<String>,
302    #[serde(skip_serializing_if = "Option::is_none")]
303    pub expiration_time: Option<i64>,
304}
305
306/// V2 decrease with exactly one reduction selector.
307#[derive(Debug, Clone, Serialize)]
308pub struct DecreaseOrderRequest {
309    pub exchange_index: u32,
310    #[serde(skip_serializing_if = "Option::is_none")]
311    pub reduce_by: Option<FixedPoint>,
312    #[serde(skip_serializing_if = "Option::is_none")]
313    pub reduce_to: Option<FixedPoint>,
314    #[serde(skip_serializing_if = "Option::is_none")]
315    pub market_ticker: Option<String>,
316}
317
318/// One explicitly selected order for batch cancellation.
319#[derive(Debug, Clone, Serialize)]
320pub struct CancelOrderRequest {
321    pub order_id: String,
322    pub subaccount: u32,
323    pub exchange_index: u32,
324    #[serde(skip_serializing_if = "Option::is_none")]
325    pub market_ticker: Option<String>,
326}
327
328/// Independent V2 limit-order requests.
329#[derive(Debug, Clone, Serialize)]
330pub struct BatchCreateRequest {
331    pub orders: Vec<CreateOrderRequest>,
332}
333
334/// Explicitly selected V2 order cancellations.
335#[derive(Debug, Clone, Serialize)]
336pub struct BatchCancelRequest {
337    pub orders: Vec<CancelOrderRequest>,
338}
339
340fn serialize_count_filter<S: Serializer>(
341    filters: &Option<Vec<PositionCountFilter>>,
342    serializer: S,
343) -> Result<S::Ok, S::Error> {
344    match filters {
345        Some(filters) => {
346            let value = filters
347                .iter()
348                .map(AsRef::<str>::as_ref)
349                .collect::<Vec<_>>()
350                .join(",");
351            serializer.serialize_str(&value)
352        }
353        None => serializer.serialize_none(),
354    }
355}
356
357fn serialize_price<S: Serializer>(price: &FixedPoint, serializer: S) -> Result<S::Ok, S::Error> {
358    let mut value = price.0;
359    if value.scale() > 4 {
360        return Err(serde::ser::Error::custom(
361            "order price exceeds four decimal places",
362        ));
363    }
364
365    value.rescale(4);
366    serializer.serialize_str(&value.to_string())
367}
368
369pub(super) trait CursorQuery: Clone {
370    fn cursor(&self) -> Option<&str>;
371
372    fn set_cursor(&mut self, cursor: Option<String>);
373}
374
375macro_rules! cursor_query {
376    ($($query:ty),+ $(,)?) => { $(
377        impl CursorQuery for $query {
378            fn cursor(&self) -> Option<&str> { self.cursor.as_deref() }
379            fn set_cursor(&mut self, cursor: Option<String>) { self.cursor = cursor; }
380        }
381    )+ };
382}
383
384cursor_query!(
385    MarketsQuery,
386    HistoricalMarketsQuery,
387    EventsQuery,
388    TradesQuery,
389    OrdersQuery,
390    FillsQuery,
391    PositionsQuery,
392    HistoryQuery,
393    HistoricalPositionsQuery,
394    SettlementsQuery
395);