Skip to main content

nautilus_kalshi/
providers.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//! Instrument provider for the Kalshi adapter.
17
18use std::{collections::HashMap, ops::Bound};
19
20use anyhow::Context;
21use nautilus_common::{
22    live::sender::EventSender,
23    messages::{
24        DataEvent,
25        data::{
26            DataResponse, InstrumentResponse, InstrumentsResponse, RequestInstrument,
27            RequestInstruments,
28        },
29    },
30};
31use nautilus_core::{
32    UnixNanos,
33    datetime::{NANOSECONDS_IN_SECOND, try_datetime_to_unix_nanos},
34    params::Params,
35    time::AtomicTime,
36};
37use nautilus_model::instruments::{BinaryOption, InstrumentAny};
38
39use crate::{
40    common::{
41        consts::{KALSHI_CLIENT_ID, KALSHI_VENUE},
42        enums::{MarketStatus, MarketStatusFilter, MveFilter, MveHistoricalFilter},
43        parse::{parse_instrument_id, parse_ticker},
44    },
45    http::{
46        client::KalshiHttpClient,
47        error::KalshiHttpError,
48        models::{Event, Field, Market, Series},
49        parse::{parse_instrument, supported_market},
50        query::{EventQuery, HistoricalMarketsQuery, MarketsQuery},
51    },
52};
53
54const STATUS_FILTERS: &[(MarketStatusFilter, &[MarketStatus])] = &[
55    (MarketStatusFilter::Unopened, &[MarketStatus::Initialized]),
56    (MarketStatusFilter::Open, &[MarketStatus::Active]),
57    (MarketStatusFilter::Paused, &[MarketStatus::Inactive]),
58    (
59        MarketStatusFilter::Closed,
60        &[
61            MarketStatus::Closed,
62            MarketStatus::Determined,
63            MarketStatus::Disputed,
64            MarketStatus::Amended,
65        ],
66    ),
67    (MarketStatusFilter::Settled, &[MarketStatus::Finalized]),
68];
69
70/// Loads current or archived definitions without serving explicit requests from a private cache.
71///
72/// Request parameters accept the REST market filters, `exchange_index`, `historical`, and
73/// `max_pages` (default 100). An exhausted page budget fails without emitting a partial response.
74/// Time bounds filter `ts_event`, using local initialization time when `updated_time` is absent.
75/// They do not reconstruct historical definitions.
76#[derive(Debug)]
77pub struct KalshiInstrumentProvider {
78    pub(crate) http: KalshiHttpClient,
79    pub(crate) clock: &'static AtomicTime,
80    sender: EventSender<DataEvent>,
81}
82
83impl KalshiInstrumentProvider {
84    /// Creates an instrument request handler using the supplied transport and event sender.
85    pub fn new(
86        http: KalshiHttpClient,
87        clock: &'static AtomicTime,
88        sender: EventSender<DataEvent>,
89    ) -> Self {
90        Self {
91            http,
92            clock,
93            sender,
94        }
95    }
96
97    /// Fetches a fresh definition, falling back to the archive only after a live-market 404.
98    ///
99    /// # Errors
100    ///
101    /// Returns an error if identity, filters, admission, transport, or response dispatch fails.
102    pub async fn request_instrument(&self, request: RequestInstrument) -> anyhow::Result<()> {
103        let instrument = self.load_instrument(&request).await?;
104        self.respond_instrument(request, instrument)
105    }
106
107    pub(crate) fn respond_instrument(
108        &self,
109        request: RequestInstrument,
110        instrument: BinaryOption,
111    ) -> anyhow::Result<()> {
112        let (start, end) = request_bounds(request.start, request.end)?;
113
114        let response = InstrumentResponse::new(
115            request.request_id,
116            request.client_id.unwrap_or(*KALSHI_CLIENT_ID),
117            request.single_instrument_id()?,
118            InstrumentAny::BinaryOption(instrument),
119            start,
120            end,
121            self.clock.get_time_ns(),
122            request.params,
123        );
124
125        self.sender
126            .send(DataEvent::Response(DataResponse::Instrument(Box::new(
127                response,
128            ))))
129            .map_err(|_| anyhow::anyhow!("instrument response receiver closed"))?;
130        Ok(())
131    }
132
133    /// Fetches all selected live or archived markets, retaining only supported definitions.
134    ///
135    /// # Errors
136    ///
137    /// Returns an error if the venue or filters are invalid, pagination is incomplete, metadata is
138    /// malformed, or transport or response dispatch fails.
139    pub async fn request_instruments(&self, request: RequestInstruments) -> anyhow::Result<()> {
140        let instruments = self.load_instruments(&request).await?;
141        self.respond_instruments(request, instruments)
142    }
143
144    pub(crate) fn respond_instruments(
145        &self,
146        request: RequestInstruments,
147        instruments: Vec<InstrumentAny>,
148    ) -> anyhow::Result<()> {
149        let (start, end) = request_bounds(request.start, request.end)?;
150
151        let response = InstrumentsResponse::new(
152            request.request_id,
153            request.client_id.unwrap_or(*KALSHI_CLIENT_ID),
154            *KALSHI_VENUE,
155            instruments,
156            start,
157            end,
158            self.clock.get_time_ns(),
159            request.params,
160        );
161
162        self.sender
163            .send(DataEvent::Response(DataResponse::Instruments(response)))
164            .map_err(|_| anyhow::anyhow!("instruments response receiver closed"))?;
165        Ok(())
166    }
167
168    pub(crate) async fn load_instruments(
169        &self,
170        request: &RequestInstruments,
171    ) -> anyhow::Result<Vec<InstrumentAny>> {
172        anyhow::ensure!(
173            request.venue.is_none_or(|v| v == *KALSHI_VENUE),
174            "instrument request venue must be KALSHI"
175        );
176        let selection = Selection::new(request.params.as_ref())?;
177        let (start, end) = request_bounds(request.start, request.end)?;
178
179        let pages = if selection.historical {
180            let mut query = HistoricalMarketsQuery {
181                limit: selection.query.limit,
182                cursor: selection.query.cursor.clone(),
183                ..Default::default()
184            };
185
186            match (
187                &selection.query.tickers,
188                &selection.query.event_ticker,
189                &selection.query.series_ticker,
190            ) {
191                (Some(tickers), _, _) => query.tickers = Some(tickers.clone()),
192                (_, Some(event), _) => query.event_ticker = Some(event.clone()),
193                (_, _, Some(series)) => query.series_ticker = Some(series.clone()),
194                _ => query.mve_filter = Some(MveHistoricalFilter::Exclude),
195            }
196
197            self.http
198                .get_all_historical_markets(query, selection.max_pages)
199                .await?
200        } else {
201            self.http
202                .get_all_markets(selection.query.clone(), selection.max_pages)
203                .await?
204        };
205
206        anyhow::ensure!(pages.complete, "instrument discovery page budget exhausted");
207        let mut events: HashMap<String, Event> = HashMap::new();
208        let mut series: HashMap<String, Series> = HashMap::new();
209        let mut instruments = Vec::new();
210
211        for market in pages.records {
212            if !events.contains_key(&market.event_ticker) {
213                let event = self
214                    .http
215                    .get_event(
216                        &market.event_ticker,
217                        &EventQuery {
218                            exclude_markets: Some(true),
219                            ..Default::default()
220                        },
221                    )
222                    .await?
223                    .event;
224
225                anyhow::ensure!(
226                    event.event_ticker == market.event_ticker,
227                    "requested event identity mismatch"
228                );
229                events.insert(market.event_ticker.clone(), event);
230            }
231
232            let event = &events[&market.event_ticker];
233            if !selection.matches(&market, event) || !supported_market(&market, event) {
234                continue;
235            }
236
237            if !series.contains_key(&event.series_ticker) {
238                let definition = self.http.get_series(&event.series_ticker).await?.series;
239                series.insert(event.series_ticker.clone(), definition);
240            }
241
242            let instrument = Self::parse(
243                &market,
244                event,
245                &series[&event.series_ticker],
246                self.clock.get_time_ns(),
247            )?;
248
249            if start.is_some_and(|t| instrument.ts_event < t)
250                || end.is_some_and(|t| instrument.ts_event > t)
251            {
252                continue;
253            }
254
255            instruments.push(InstrumentAny::BinaryOption(instrument));
256        }
257
258        Ok(instruments)
259    }
260
261    pub(crate) async fn load_instrument(
262        &self,
263        request: &RequestInstrument,
264    ) -> anyhow::Result<BinaryOption> {
265        let ticker = parse_ticker(request.single_instrument_id()?)?;
266        let selection = Selection::new(request.params.as_ref())?;
267        let (start, end) = request_bounds(request.start, request.end)?;
268
269        let market = if selection.historical {
270            self.http.get_historical_market(&ticker).await?.market
271        } else {
272            Self::load_market(&self.http, &ticker).await?
273        };
274
275        anyhow::ensure!(
276            market.ticker == ticker,
277            "requested market identity mismatch"
278        );
279
280        let event = self
281            .http
282            .get_event(
283                &market.event_ticker,
284                &EventQuery {
285                    exclude_markets: Some(true),
286                    ..Default::default()
287                },
288            )
289            .await?
290            .event;
291
292        let series = self.http.get_series(&event.series_ticker).await?.series;
293        anyhow::ensure!(
294            selection.matches(&market, &event),
295            "definition does not satisfy request filters"
296        );
297        let instrument = Self::parse(&market, &event, &series, self.clock.get_time_ns())?;
298        anyhow::ensure!(
299            start.is_none_or(|t| instrument.ts_event >= t)
300                && end.is_none_or(|t| instrument.ts_event <= t),
301            "definition outside requested update interval"
302        );
303
304        Ok(instrument)
305    }
306
307    pub(crate) async fn load_market(
308        http: &KalshiHttpClient,
309        ticker: &str,
310    ) -> anyhow::Result<Market> {
311        let mut attempt = 0;
312
313        loop {
314            match http.get_market(ticker).await {
315                Ok(response) => return Ok(response.market),
316                Err(e) if not_found(&e) => match http.get_historical_market(ticker).await {
317                    Ok(response) => return Ok(response.market),
318                    Err(e) if not_found(&e) && attempt < 3 => {
319                        nautilus_common::live::dst::time::sleep(std::time::Duration::from_millis(
320                            100 << attempt,
321                        ))
322                        .await;
323                        attempt += 1;
324                    }
325                    Err(e) => return Err(e.into()),
326                },
327                Err(e) => return Err(e.into()),
328            }
329        }
330    }
331
332    pub(crate) fn parse(
333        market: &Market,
334        event: &Event,
335        series: &Series,
336        ts_init: UnixNanos,
337    ) -> anyhow::Result<BinaryOption> {
338        anyhow::ensure!(
339            series.ticker == event.series_ticker,
340            "requested series identity mismatch"
341        );
342        let mut instrument = parse_instrument(market, event, ts_init)?;
343        // Keep exact fee metadata out of serde_json's floating-point number path
344        let serialized = serde_json::to_string(series)?;
345        let fields: HashMap<String, Box<serde_json::value::RawValue>> =
346            serde_json::from_str(&serialized)?;
347
348        let metadata = fields
349            .into_iter()
350            .map(|(key, value)| {
351                let value = if key == "fee_multiplier" {
352                    serde_json::Value::String(series.fee_multiplier.0.to_string())
353                } else {
354                    serde_json::from_str(value.get())?
355                };
356
357                Ok((key, value))
358            })
359            .collect::<Result<serde_json::Map<_, _>, serde_json::Error>>()?;
360
361        let mut info = instrument
362            .info
363            .as_deref()
364            .cloned()
365            .context("missing instrument metadata")?;
366        info.insert("series".into(), metadata.into());
367        instrument.info = Some(Params::new(info));
368        Ok(instrument)
369    }
370}
371
372pub(crate) fn request_bounds(
373    start: Option<jiff::Timestamp>,
374    end: Option<jiff::Timestamp>,
375) -> anyhow::Result<(Option<UnixNanos>, Option<UnixNanos>)> {
376    let start = start
377        .map(try_datetime_to_unix_nanos)
378        .transpose()
379        .context("invalid request start bound")?;
380    let end = end
381        .map(try_datetime_to_unix_nanos)
382        .transpose()
383        .context("invalid request end bound")?;
384    anyhow::ensure!(
385        start.zip(end).is_none_or(|(a, b)| a <= b),
386        "invalid update interval"
387    );
388    Ok((start, end))
389}
390
391fn not_found(error: &KalshiHttpError) -> bool {
392    matches!(
393        error,
394        KalshiHttpError::Http { status: 404, .. }
395            | KalshiHttpError::Venue { status: 404, .. }
396            | KalshiHttpError::Status(404)
397    )
398}
399
400struct Selection {
401    query: MarketsQuery,
402    historical: bool,
403    max_pages: u32,
404    exchange_index: Option<i64>,
405}
406
407impl Selection {
408    fn new(params: Option<&Params>) -> anyhow::Result<Self> {
409        let value = params
410            .map(serde_json::to_value)
411            .transpose()?
412            .unwrap_or_else(|| serde_json::json!({}));
413
414        if let Some(status) = value.get("status").and_then(serde_json::Value::as_str) {
415            anyhow::ensure!(
416                status.parse::<MarketStatusFilter>().is_ok(),
417                "unsupported market status filter"
418            );
419        }
420
421        let mut query: MarketsQuery = serde_json::from_value(value.clone())?;
422        anyhow::ensure!(
423            query
424                .mve_filter
425                .as_ref()
426                .is_none_or(|value| *value == MveFilter::Exclude),
427            "only ordinary market discovery is supported"
428        );
429        query.mve_filter = Some(MveFilter::Exclude);
430        anyhow::ensure!(
431            query.cursor.as_deref().is_none_or(str::is_empty),
432            "instrument discovery must start at the first page"
433        );
434
435        for ticker in query.tickers.iter().flat_map(|v| v.split(',')) {
436            parse_instrument_id(ticker)?;
437        }
438
439        for ticker in [&query.event_ticker, &query.series_ticker]
440            .into_iter()
441            .flatten()
442        {
443            parse_instrument_id(ticker)?;
444        }
445
446        let historical = value
447            .get("historical")
448            .map(|v| v.as_bool().context("historical must be a boolean"))
449            .transpose()?
450            .unwrap_or(false);
451        let max_pages = value
452            .get("max_pages")
453            .map(|v| v.as_u64().context("max_pages must be a positive integer"))
454            .transpose()?
455            .unwrap_or(100);
456        let max_pages = u32::try_from(max_pages)?;
457        anyhow::ensure!(max_pages > 0, "max_pages must be positive");
458
459        let exchange_index = value
460            .get("exchange_index")
461            .map(|v| {
462                v.as_i64()
463                    .filter(|v| *v >= 0 && *v <= i64::from(i32::MAX))
464                    .context("invalid exchange index")
465            })
466            .transpose()?;
467
468        Ok(Self {
469            query,
470            historical,
471            max_pages,
472            exchange_index,
473        })
474    }
475
476    fn matches(&self, market: &Market, event: &Event) -> bool {
477        self.query
478            .tickers
479            .as_ref()
480            .is_none_or(|v| v.split(',').any(|t| t == market.ticker))
481            && self
482                .query
483                .event_ticker
484                .as_ref()
485                .is_none_or(|v| *v == market.event_ticker)
486            && self
487                .query
488                .series_ticker
489                .as_ref()
490                .is_none_or(|v| *v == event.series_ticker)
491            && self
492                .exchange_index
493                .is_none_or(|v| market.exchange_index == Field::Value(v as i32))
494            && timestamp_matches(
495                Some(market.created_time),
496                self.query.min_created_ts,
497                self.query
498                    .max_created_ts
499                    .map_or(Bound::Unbounded, Bound::Excluded),
500            )
501            && timestamp_matches(
502                match market.updated_time {
503                    Field::Value(t) => Some(t),
504                    _ => None,
505                },
506                self.query.min_updated_ts,
507                self.query
508                    .max_updated_ts
509                    .map_or(Bound::Unbounded, Bound::Included),
510            )
511            && timestamp_matches(
512                Some(market.close_time),
513                self.query.min_close_ts,
514                self.query
515                    .max_close_ts
516                    .map_or(Bound::Unbounded, Bound::Excluded),
517            )
518            && timestamp_matches(
519                match market.settlement_ts {
520                    Field::Value(t) => Some(t),
521                    _ => None,
522                },
523                self.query.min_settled_ts,
524                self.query
525                    .max_settled_ts
526                    .map_or(Bound::Unbounded, Bound::Excluded),
527            )
528            && self.query.status.as_ref().is_none_or(|filter| {
529                STATUS_FILTERS
530                    .iter()
531                    .find(|(name, _)| name == filter)
532                    .is_some_and(|(_, statuses)| statuses.contains(&market.status))
533            })
534    }
535}
536
537fn timestamp_matches(
538    value: Option<jiff::Timestamp>,
539    minimum: Option<i64>,
540    maximum: Bound<i64>,
541) -> bool {
542    let value = value.map(jiff::Timestamp::as_nanosecond);
543    let minimum = minimum.map(|seconds| i128::from(seconds) * i128::from(NANOSECONDS_IN_SECOND));
544    let maximum = maximum.map(|seconds| i128::from(seconds) * i128::from(NANOSECONDS_IN_SECOND));
545    minimum.is_none_or(|min| value.is_some_and(|value| value > min))
546        && match maximum {
547            Bound::Unbounded => true,
548            Bound::Included(max) => value.is_some_and(|value| value <= max),
549            Bound::Excluded(max) => value.is_some_and(|value| value < max),
550        }
551}
552
553#[cfg(test)]
554mod tests {
555    use rstest::rstest;
556    use serde_json::Value;
557
558    use super::*;
559    use crate::config::KalshiDataClientConfig;
560
561    #[rstest]
562    #[case("min_created_ts", [false, false, true])]
563    #[case("max_created_ts", [true, false, false])]
564    #[case("min_updated_ts", [false, false, true])]
565    #[case("max_updated_ts", [true, true, false])]
566    #[case("min_close_ts", [false, false, true])]
567    #[case("max_close_ts", [true, false, false])]
568    #[case("min_settled_ts", [false, false, true])]
569    #[case("max_settled_ts", [true, false, false])]
570    fn timestamp_filters_preserve_nanoseconds_and_boundaries(
571        #[case] field: &str,
572        #[case] expected: [bool; 3],
573    ) {
574        let (mut market, event) = definition();
575        let params = Params::new([(field.into(), 100.into())].into());
576        let selection = Selection::new(Some(&params)).unwrap();
577
578        let results = [-1, 0, 1].map(|offset| {
579            let timestamp = jiff::Timestamp::from_nanosecond(100_000_000_000 + offset).unwrap();
580            market.created_time = timestamp;
581            market.updated_time = Field::Value(timestamp);
582            market.close_time = timestamp;
583            market.settlement_ts = Field::Value(timestamp);
584            selection.matches(&market, &event)
585        });
586
587        assert_eq!(results, expected);
588    }
589
590    #[rstest]
591    #[case("unopened", "initialized", true)]
592    #[case("open", "active", true)]
593    #[case("paused", "inactive", true)]
594    #[case("closed", "closed", true)]
595    #[case("closed", "determined", true)]
596    #[case("closed", "disputed", true)]
597    #[case("closed", "amended", true)]
598    #[case("settled", "finalized", true)]
599    #[case("paused", "active", false)]
600    #[case("closed", "finalized", false)]
601    fn status_filters_match_lifecycle(
602        #[case] filter: &str,
603        #[case] status: &str,
604        #[case] expected: bool,
605    ) {
606        let (mut market, event) = definition();
607        market.status = status.parse().unwrap();
608        let params = Params::new([("status".into(), filter.into())].into());
609        let selection = Selection::new(Some(&params)).unwrap();
610        assert_eq!(selection.matches(&market, &event), expected);
611    }
612
613    #[rstest]
614    #[case("finalized")]
615    #[case("open,closed")]
616    #[case("not-a-status")]
617    fn unknown_status_filter_is_rejected(#[case] status: &str) {
618        let params = Params::new([("status".into(), status.into())].into());
619        let result = Selection::new(Some(&params));
620        assert_eq!(
621            result.err().unwrap().to_string(),
622            "unsupported market status filter"
623        );
624    }
625
626    #[rstest]
627    fn multivariate_only_selection_is_rejected() {
628        let params = Params::new([("mve_filter".into(), "only".into())].into());
629        let result = Selection::new(Some(&params));
630        assert_eq!(
631            result.err().unwrap().to_string(),
632            "only ordinary market discovery is supported"
633        );
634    }
635
636    #[rstest]
637    fn series_metadata_retains_exact_fee_multiplier() {
638        let (market, event) = definition();
639        let values: Value =
640            serde_json::from_str(include_str!("../test_data/instruments.json")).unwrap();
641        let mut series: Series =
642            serde_json::from_str(&serde_json::to_string(&values["series"]["series"]).unwrap())
643                .unwrap();
644        let exact = "0.1234567890123456789012345678";
645        series.fee_multiplier.0 = rust_decimal::Decimal::from_str_exact(exact).unwrap();
646        let http = KalshiHttpClient::new(&KalshiDataClientConfig::default()).unwrap();
647        let clock = Box::leak(Box::new(AtomicTime::new(false, UnixNanos::from(31))));
648        let (sender, _) = tokio::sync::mpsc::unbounded_channel();
649        let provider = KalshiInstrumentProvider::new(http, clock, sender.into());
650        let instrument =
651            KalshiInstrumentProvider::parse(&market, &event, &series, provider.clock.get_time_ns())
652                .unwrap();
653        assert_eq!(
654            instrument.info.as_ref().unwrap()["series"]["fee_multiplier"],
655            exact
656        );
657    }
658
659    #[rstest]
660    fn ticker_selection_preserves_case_and_multiple_tickers() {
661        let (market, event) = definition();
662
663        let results = [
664            market.ticker.clone(),
665            format!("OTHER,{}", market.ticker),
666            market.ticker.to_lowercase(),
667            "OTHER".into(),
668        ]
669        .map(|tickers| {
670            let params = Params::new([("tickers".into(), tickers.into())].into());
671            Selection::new(Some(&params))
672                .unwrap()
673                .matches(&market, &event)
674        });
675
676        assert_eq!(results, [true, true, false, false]);
677    }
678
679    fn definition() -> (Market, Event) {
680        let values: Value =
681            serde_json::from_str(include_str!("../test_data/instruments.json")).unwrap();
682        let value = &values["definitions"]["live"];
683
684        (
685            serde_json::from_value(value["market"].clone()).unwrap(),
686            serde_json::from_value(value["event"].clone()).unwrap(),
687        )
688    }
689}