Skip to main content

nautilus_kalshi/http/
history.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//! Bounded live/archive market-data collection.
17
18use std::collections::HashMap;
19
20use super::{
21    client::KalshiHttpClient,
22    error::KalshiHttpError,
23    models::{
24        BidAskDistribution, Candlestick, Field, FixedPoint, HistoricalBidAskDistribution,
25        HistoricalCandlestick, Market, PriceDistribution, Trade,
26    },
27    parse::Pagination,
28    query::{CandlesticksQuery, TradesQuery},
29};
30use crate::common::enums::MarketStatus;
31
32impl KalshiHttpClient {
33    /// Collects a bounded trade window, oldest first with trade ID breaking timestamp ties.
34    ///
35    /// The cutoff is read once. A window reaching it reads live pages before a full-window
36    /// archive probe to cover a forward handoff between the reads. The venue does not promise an
37    /// atomic snapshot across pages. `limit` is a page size, not a result limit.
38    ///
39    /// # Errors
40    ///
41    /// Returns an error if:
42    /// - The query is invalid, unbounded, or resumed.
43    /// - Pagination is incomplete, duplicates conflict, or records do not match.
44    /// - Any source fails.
45    pub async fn get_trades_range(
46        &self,
47        query: TradesQuery,
48        max_pages: u32,
49    ) -> Result<Vec<Trade>, KalshiHttpError> {
50        let (Some(start), Some(end), Some(_)) =
51            (query.min_ts, query.max_ts, query.ticker.as_deref())
52        else {
53            return Err(KalshiHttpError::Validation(
54                "trade history requires ticker and both time bounds",
55            ));
56        };
57
58        if start < 0
59            || start > end
60            || query.cursor.is_some()
61            || max_pages == 0
62            || query.limit.is_some_and(|v| v == 0 || v > 1000)
63        {
64            return Err(KalshiHttpError::Validation("invalid bounded trade query"));
65        }
66
67        let cutoff = self.get_historical_cutoff().await?;
68        let mut records = HashMap::new();
69        if end >= cutoff.trades_created_ts.as_second() {
70            self.collect_trade_range(&query, max_pages, false, &mut records)
71                .await?;
72        }
73
74        self.collect_trade_range(&query, max_pages, true, &mut records)
75            .await?;
76        let mut records: Vec<_> = records
77            .into_values()
78            .filter(|t| t.created_time.as_second() >= start && t.created_time.as_second() <= end)
79            .collect();
80        records.sort_by(|a, b| {
81            a.created_time
82                .cmp(&b.created_time)
83                .then_with(|| a.trade_id.cmp(&b.trade_id))
84        });
85
86        Ok(records)
87    }
88
89    async fn collect_trade_range(
90        &self,
91        query: &TradesQuery,
92        max_pages: u32,
93        historical: bool,
94        records: &mut HashMap<String, Trade>,
95    ) -> Result<(), KalshiHttpError> {
96        let mut query = query.clone();
97        let mut pagination = Pagination::new(None);
98
99        for _ in 0..max_pages {
100            let page = if historical {
101                self.get_historical_trades(&query).await?
102            } else {
103                self.get_trades(&query).await?
104            };
105
106            let empty = page.trades.is_empty();
107            for trade in page.trades {
108                merge_trade(records, trade, &query)?;
109            }
110
111            query.cursor = pagination.advance(page.cursor, empty)?;
112            if query.cursor.is_none() {
113                return Ok(());
114            }
115        }
116
117        Err(KalshiHttpError::Pagination(
118            "trade history page budget exhausted",
119        ))
120    }
121
122    /// Fetches native candles using market settlement time to select the archive partition.
123    ///
124    /// The cutoff is read once. A settled market still in the live tier receives an archive
125    /// probe after the live read to cover a forward handoff. Endpoint time bounds apply to candle end timestamps.
126    ///
127    /// # Errors
128    ///
129    /// Returns an error if:
130    /// - Bounds or periods are invalid, or a finalized market has no settlement evidence.
131    /// - Market identity does not match, candles conflict, or a source fails.
132    pub async fn get_candlesticks_range(
133        &self,
134        market: &Market,
135        series: &str,
136        query: &CandlesticksQuery,
137    ) -> Result<Vec<Candlestick>, KalshiHttpError> {
138        if query.start_ts < 0 || query.start_ts > query.end_ts {
139            return Err(KalshiHttpError::Validation(
140                "invalid candle window or period",
141            ));
142        }
143
144        let cutoff = self.get_historical_cutoff().await?;
145
146        let settled = match market.settlement_ts {
147            Field::Value(value) => Some(value),
148            _ if market.status == MarketStatus::Finalized => {
149                return Err(KalshiHttpError::Parse(
150                    "finalized market has no settlement timestamp".into(),
151                ));
152            }
153            _ => None,
154        };
155
156        let archived = settled.is_some_and(|t| t < cutoff.market_settled_ts);
157        let mut records = None;
158
159        if !archived {
160            match self
161                .candlestick_partition(market, series, query, false)
162                .await
163            {
164                Ok(candles) => records = Some(candles),
165                Err(e) if settled.is_some() && missing(&e) => {}
166                Err(e) => return Err(e),
167            }
168        }
169
170        if archived || settled.is_some() {
171            match self
172                .candlestick_partition(market, series, query, true)
173                .await
174            {
175                Ok(candles) => records.get_or_insert_with(Vec::new).extend(candles),
176                Err(e) if records.is_some() && missing(&e) => {}
177                Err(e) => return Err(e),
178            }
179        }
180
181        merge_candles(records.unwrap_or_default(), query)
182    }
183
184    async fn candlestick_partition(
185        &self,
186        market: &Market,
187        series: &str,
188        query: &CandlesticksQuery,
189        historical: bool,
190    ) -> Result<Vec<Candlestick>, KalshiHttpError> {
191        let (ticker, records) = if historical {
192            let response = self
193                .get_historical_candlesticks(&market.ticker, query)
194                .await?;
195
196            (
197                response.ticker,
198                response.candlesticks.into_iter().map(normalize).collect(),
199            )
200        } else {
201            let response = self.get_candlesticks(series, &market.ticker, query).await?;
202            (response.ticker, response.candlesticks)
203        };
204
205        if ticker != market.ticker {
206            return Err(KalshiHttpError::Parse(
207                "candle market identity mismatch".into(),
208            ));
209        }
210
211        Ok(records)
212    }
213}
214
215fn merge_trade(
216    records: &mut HashMap<String, Trade>,
217    trade: Trade,
218    query: &TradesQuery,
219) -> Result<(), KalshiHttpError> {
220    if Some(&trade.ticker) != query.ticker.as_ref()
221        || query
222            .is_block_trade
223            .is_some_and(|v| trade.is_block_trade != v)
224    {
225        return Err(KalshiHttpError::Parse(
226            "trade does not match requested filters".into(),
227        ));
228    }
229
230    if let Some(previous) = records.get(&trade.trade_id) {
231        if previous != &trade {
232            return Err(KalshiHttpError::Parse("conflicting duplicate trade".into()));
233        }
234    } else {
235        records.insert(trade.trade_id.clone(), trade);
236    }
237
238    Ok(())
239}
240
241fn missing(error: &KalshiHttpError) -> bool {
242    matches!(
243        error,
244        KalshiHttpError::Http { status: 404, .. }
245            | KalshiHttpError::Venue { status: 404, .. }
246            | KalshiHttpError::Status(404)
247    )
248}
249
250fn merge_candles(
251    mut records: Vec<Candlestick>,
252    query: &CandlesticksQuery,
253) -> Result<Vec<Candlestick>, KalshiHttpError> {
254    records.sort_by_key(|c| c.end_period_ts);
255    let mut result: Vec<Candlestick> = Vec::new();
256
257    for candle in records {
258        if candle.end_period_ts < query.start_ts || candle.end_period_ts > query.end_ts {
259            continue;
260        }
261
262        if let Some(previous) = result.last()
263            && previous.end_period_ts == candle.end_period_ts
264        {
265            if previous.yes_bid != candle.yes_bid
266                || previous.yes_ask != candle.yes_ask
267                || previous.price.open_dollars != candle.price.open_dollars
268                || previous.price.high_dollars != candle.price.high_dollars
269                || previous.price.low_dollars != candle.price.low_dollars
270                || previous.price.close_dollars != candle.price.close_dollars
271                || previous.volume_fp != candle.volume_fp
272            {
273                return Err(KalshiHttpError::Parse(
274                    "conflicting duplicate candle".into(),
275                ));
276            }
277
278            continue;
279        }
280
281        result.push(candle);
282    }
283
284    Ok(result)
285}
286
287fn normalize(value: HistoricalCandlestick) -> Candlestick {
288    let prices = |value: HistoricalBidAskDistribution| BidAskDistribution {
289        open_dollars: value.open,
290        low_dollars: value.low,
291        high_dollars: value.high,
292        close_dollars: value.close,
293    };
294
295    let field = |value: Option<FixedPoint>| value.map_or(Field::Null, Field::Value);
296
297    Candlestick {
298        end_period_ts: value.end_period_ts,
299        yes_bid: prices(value.yes_bid),
300        yes_ask: prices(value.yes_ask),
301        price: PriceDistribution {
302            open_dollars: field(value.price.open),
303            low_dollars: field(value.price.low),
304            high_dollars: field(value.price.high),
305            close_dollars: field(value.price.close),
306            mean_dollars: field(value.price.mean),
307            previous_dollars: field(value.price.previous),
308            min_dollars: Field::Missing,
309            max_dollars: Field::Missing,
310        },
311        volume_fp: value.volume,
312        open_interest_fp: value.open_interest,
313    }
314}