Skip to main content

nautilus_lighter/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//! Query parameter builders for Lighter REST endpoints.
17
18use derive_builder::Builder;
19use nautilus_core::string::secret::SecretString;
20use serde::{Deserialize, Serialize};
21use zeroize::Zeroize;
22
23use crate::common::enums::{
24    LighterCandleResolution, LighterFundingResolution, LighterOrderBookFilter, LighterTradeType,
25};
26
27#[derive(Copy, Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
28#[serde(rename_all = "snake_case")]
29pub enum LighterTxLookup {
30    Hash,
31    SequenceIndex,
32}
33
34#[derive(Clone, Debug, Deserialize, Serialize, Builder, PartialEq, Eq)]
35pub struct LighterTxQuery {
36    pub by: LighterTxLookup,
37    pub value: String,
38}
39
40#[derive(Clone, Debug, Default, Deserialize, Serialize, Builder, PartialEq, Eq)]
41#[builder(setter(strip_option), default)]
42pub struct LighterOrderBooksQuery {
43    #[serde(skip_serializing_if = "Option::is_none")]
44    pub market_id: Option<i64>,
45    #[serde(skip_serializing_if = "Option::is_none")]
46    pub filter: Option<LighterOrderBookFilter>,
47}
48
49#[derive(Clone, Debug, Default, Deserialize, Serialize, Builder, PartialEq, Eq)]
50#[builder(setter(strip_option), default)]
51pub struct LighterOrderBookDetailsQuery {
52    #[serde(skip_serializing_if = "Option::is_none")]
53    pub market_id: Option<i64>,
54    #[serde(skip_serializing_if = "Option::is_none")]
55    pub filter: Option<LighterOrderBookFilter>,
56}
57
58#[derive(Clone, Debug, Deserialize, Serialize, Builder, PartialEq, Eq)]
59pub struct LighterOrderBookOrdersQuery {
60    pub market_id: i64,
61    pub limit: u16,
62}
63
64#[derive(Clone, Debug, Deserialize, Serialize, Builder, PartialEq, Eq)]
65pub struct LighterRecentTradesQuery {
66    pub market_id: i64,
67    pub limit: u16,
68}
69
70#[derive(Clone, Debug, Deserialize, Serialize, Builder, PartialEq, Eq)]
71#[builder(setter(strip_option))]
72pub struct LighterCandlesQuery {
73    pub market_id: i64,
74    pub resolution: LighterCandleResolution,
75    pub start_timestamp: i64,
76    pub end_timestamp: i64,
77    pub count_back: i64,
78    #[builder(default)]
79    #[serde(skip_serializing_if = "Option::is_none")]
80    pub set_timestamp_to_end: Option<bool>,
81}
82
83#[derive(Clone, Debug, Deserialize, Serialize, Builder, PartialEq, Eq)]
84#[builder(setter(strip_option))]
85pub struct LighterFundingsQuery {
86    pub market_id: i64,
87    pub resolution: LighterFundingResolution,
88    pub start_timestamp: i64,
89    pub end_timestamp: i64,
90    pub count_back: i64,
91}
92
93#[derive(Clone, Debug, Deserialize, Serialize, Builder, PartialEq, Eq)]
94#[builder(setter(strip_option))]
95pub struct LighterTradesQuery {
96    #[builder(default)]
97    #[builder(setter(into, strip_option))]
98    #[serde(skip_serializing_if = "Option::is_none")]
99    pub authorization: Option<SecretString>,
100    #[builder(default)]
101    #[builder(setter(into, strip_option))]
102    #[serde(skip_serializing_if = "Option::is_none")]
103    pub auth: Option<SecretString>,
104    #[builder(default)]
105    #[serde(skip_serializing_if = "Option::is_none")]
106    pub market_id: Option<i64>,
107    #[builder(default)]
108    #[serde(skip_serializing_if = "Option::is_none")]
109    pub account_index: Option<i64>,
110    #[builder(default)]
111    #[serde(skip_serializing_if = "Option::is_none")]
112    pub order_index: Option<i64>,
113    /// Venue gives this precedence over [`Self::order_index`]; use for indexes above `i64::MAX`.
114    #[builder(default)]
115    #[builder(setter(into, strip_option))]
116    #[serde(skip_serializing_if = "Option::is_none")]
117    pub order_index_str: Option<String>,
118    #[builder(default)]
119    #[serde(skip_serializing_if = "Option::is_none")]
120    pub integrator_account_index: Option<i64>,
121    #[builder(default)]
122    pub sort_by: LighterTradeSortBy,
123    #[builder(default)]
124    #[serde(skip_serializing_if = "Option::is_none")]
125    pub sort_dir: Option<LighterSortDirection>,
126    #[builder(default)]
127    #[builder(setter(into, strip_option))]
128    #[serde(skip_serializing_if = "Option::is_none")]
129    pub cursor: Option<String>,
130    #[builder(default)]
131    #[serde(rename = "from")]
132    #[serde(skip_serializing_if = "Option::is_none")]
133    pub from_timestamp: Option<i64>,
134    #[builder(default)]
135    #[serde(skip_serializing_if = "Option::is_none")]
136    pub ask_filter: Option<i8>,
137    #[builder(default)]
138    #[serde(skip_serializing_if = "Option::is_none")]
139    pub role: Option<LighterTradeRole>,
140    #[builder(default)]
141    #[serde(rename = "type")]
142    #[serde(skip_serializing_if = "Option::is_none")]
143    pub trade_type: Option<LighterTradeQueryType>,
144    #[builder(default = "100")]
145    pub limit: u16,
146    #[builder(default)]
147    #[serde(skip_serializing_if = "Option::is_none")]
148    pub aggregate: Option<bool>,
149}
150
151#[derive(Clone, Debug, Deserialize, Serialize, Builder, PartialEq, Eq)]
152#[builder(setter(strip_option))]
153pub struct LighterAccountOrdersQuery {
154    #[builder(default)]
155    #[builder(setter(into, strip_option))]
156    #[serde(skip_serializing_if = "Option::is_none")]
157    pub authorization: Option<SecretString>,
158    #[builder(default)]
159    #[builder(setter(into, strip_option))]
160    #[serde(skip_serializing_if = "Option::is_none")]
161    pub auth: Option<SecretString>,
162    pub account_index: i64,
163    /// Client order indexes encoded as one to 20 comma-separated values.
164    #[serde(
165        serialize_with = "serialize_client_order_indexes",
166        deserialize_with = "deserialize_client_order_indexes"
167    )]
168    pub client_order_indexes: Vec<i64>,
169}
170
171#[derive(Clone, Debug, Default, Deserialize, Serialize, Builder, PartialEq, Eq)]
172pub struct LighterNextNonceQuery {
173    pub account_index: i64,
174    pub api_key_index: u8,
175}
176
177#[derive(Clone, Debug, Deserialize, Serialize, Builder, PartialEq, Eq)]
178#[builder(setter(strip_option))]
179pub struct LighterMakerOnlyApiKeysQuery {
180    #[builder(default)]
181    #[builder(setter(into, strip_option))]
182    #[serde(skip_serializing_if = "Option::is_none")]
183    pub authorization: Option<SecretString>,
184    #[builder(default)]
185    #[builder(setter(into, strip_option))]
186    #[serde(skip_serializing_if = "Option::is_none")]
187    pub auth: Option<SecretString>,
188    pub account_index: i64,
189}
190
191#[derive(Copy, Clone, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
192#[serde(rename_all = "snake_case")]
193pub enum LighterAccountLookup {
194    #[default]
195    Index,
196    L1Address,
197}
198
199#[derive(Clone, Debug, Deserialize, Serialize, Builder, PartialEq, Eq)]
200pub struct LighterAccountQuery {
201    pub by: LighterAccountLookup,
202    pub value: String,
203}
204
205#[derive(Clone, Debug, Deserialize, Serialize, Builder, PartialEq, Eq)]
206#[builder(setter(strip_option))]
207pub struct LighterAccountActiveOrdersQuery {
208    #[builder(default)]
209    #[builder(setter(into, strip_option))]
210    #[serde(skip_serializing_if = "Option::is_none")]
211    pub authorization: Option<SecretString>,
212    #[builder(default)]
213    #[builder(setter(into, strip_option))]
214    #[serde(skip_serializing_if = "Option::is_none")]
215    pub auth: Option<SecretString>,
216    pub account_index: i64,
217    pub market_id: i64,
218}
219
220#[derive(Clone, Debug, Deserialize, Serialize, Builder, PartialEq, Eq)]
221#[builder(setter(strip_option))]
222pub struct LighterAccountInactiveOrdersQuery {
223    #[builder(default)]
224    #[builder(setter(into, strip_option))]
225    #[serde(skip_serializing_if = "Option::is_none")]
226    pub authorization: Option<SecretString>,
227    #[builder(default)]
228    #[builder(setter(into, strip_option))]
229    #[serde(skip_serializing_if = "Option::is_none")]
230    pub auth: Option<SecretString>,
231    pub account_index: i64,
232    #[builder(default)]
233    #[serde(skip_serializing_if = "Option::is_none")]
234    pub market_id: Option<i64>,
235    #[builder(default)]
236    #[serde(skip_serializing_if = "Option::is_none")]
237    pub ask_filter: Option<i8>,
238    #[builder(default)]
239    #[builder(setter(into, strip_option))]
240    #[serde(skip_serializing_if = "Option::is_none")]
241    pub between_timestamps: Option<String>,
242    #[builder(default)]
243    #[builder(setter(into, strip_option))]
244    #[serde(skip_serializing_if = "Option::is_none")]
245    pub cursor: Option<String>,
246    pub limit: u16,
247}
248
249macro_rules! impl_auth_query_zeroize {
250    ($type:ident) => {
251        impl Zeroize for $type {
252            fn zeroize(&mut self) {
253                self.authorization.zeroize();
254                self.auth.zeroize();
255            }
256        }
257    };
258}
259
260impl_auth_query_zeroize!(LighterTradesQuery);
261impl_auth_query_zeroize!(LighterMakerOnlyApiKeysQuery);
262impl_auth_query_zeroize!(LighterAccountActiveOrdersQuery);
263impl_auth_query_zeroize!(LighterAccountInactiveOrdersQuery);
264impl_auth_query_zeroize!(LighterAccountOrdersQuery);
265
266#[derive(Copy, Clone, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
267#[serde(rename_all = "snake_case")]
268pub enum LighterTradeSortBy {
269    BlockHeight,
270    Timestamp,
271    #[default]
272    TradeId,
273}
274
275#[derive(Copy, Clone, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
276#[serde(rename_all = "lowercase")]
277pub enum LighterSortDirection {
278    #[default]
279    Desc,
280    Asc,
281}
282
283#[derive(Copy, Clone, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
284#[serde(rename_all = "lowercase")]
285pub enum LighterTradeRole {
286    #[default]
287    All,
288    Maker,
289    Taker,
290}
291
292#[derive(Copy, Clone, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
293#[serde(rename_all = "kebab-case")]
294pub enum LighterTradeQueryType {
295    #[default]
296    All,
297    Trade,
298    Liquidation,
299    Deleverage,
300    MarketSettlement,
301}
302
303impl From<LighterTradeType> for LighterTradeQueryType {
304    fn from(value: LighterTradeType) -> Self {
305        match value {
306            LighterTradeType::Trade => Self::Trade,
307            LighterTradeType::Liquidation => Self::Liquidation,
308            LighterTradeType::Deleverage => Self::Deleverage,
309            LighterTradeType::MarketSettlement => Self::MarketSettlement,
310        }
311    }
312}
313
314impl Default for LighterTradesQuery {
315    fn default() -> Self {
316        Self {
317            authorization: None,
318            auth: None,
319            market_id: None,
320            account_index: None,
321            order_index: None,
322            order_index_str: None,
323            integrator_account_index: None,
324            sort_by: LighterTradeSortBy::default(),
325            sort_dir: None,
326            cursor: None,
327            from_timestamp: None,
328            ask_filter: None,
329            role: None,
330            trade_type: None,
331            limit: 100,
332            aggregate: None,
333        }
334    }
335}
336
337fn serialize_client_order_indexes<S>(values: &[i64], serializer: S) -> Result<S::Ok, S::Error>
338where
339    S: serde::Serializer,
340{
341    validate_client_order_indexes(values).map_err(serde::ser::Error::custom)?;
342    let joined = values
343        .iter()
344        .map(i64::to_string)
345        .collect::<Vec<_>>()
346        .join(",");
347    serializer.serialize_str(&joined)
348}
349
350fn deserialize_client_order_indexes<'de, D>(deserializer: D) -> Result<Vec<i64>, D::Error>
351where
352    D: serde::Deserializer<'de>,
353{
354    let value = String::deserialize(deserializer)?;
355    let values = value
356        .split(',')
357        .map(str::parse::<i64>)
358        .collect::<Result<Vec<_>, _>>()
359        .map_err(serde::de::Error::custom)?;
360    validate_client_order_indexes(&values).map_err(serde::de::Error::custom)?;
361    Ok(values)
362}
363
364pub(crate) fn validate_client_order_indexes(values: &[i64]) -> Result<(), String> {
365    if (1..=20).contains(&values.len()) {
366        Ok(())
367    } else {
368        Err(format!(
369            "client_order_indexes must contain between 1 and 20 values, was {}",
370            values.len()
371        ))
372    }
373}
374
375#[cfg(test)]
376mod tests {
377    use rstest::rstest;
378
379    use super::*;
380
381    #[rstest]
382    fn test_order_books_query_serializes_filter() {
383        let query = LighterOrderBooksQuery {
384            market_id: Some(0),
385            filter: Some(LighterOrderBookFilter::Perp),
386        };
387
388        let value = serde_json::to_value(query).unwrap();
389
390        assert_eq!(value["market_id"], 0);
391        assert_eq!(value["filter"], "perp");
392    }
393
394    #[rstest]
395    fn test_order_book_orders_query_serializes_widened_market_id() {
396        let query = LighterOrderBookOrdersQueryBuilder::default()
397            .market_id(40_000)
398            .limit(10)
399            .build()
400            .unwrap();
401
402        let value = serde_json::to_value(query).unwrap();
403
404        assert_eq!(value["market_id"], 40_000);
405        assert_eq!(value["limit"], 10);
406    }
407
408    #[rstest]
409    fn test_order_book_details_query_serializes_filter() {
410        let query = LighterOrderBookDetailsQueryBuilder::default()
411            .market_id(1)
412            .filter(LighterOrderBookFilter::Spot)
413            .build()
414            .unwrap();
415
416        let value = serde_json::to_value(query).unwrap();
417
418        assert_eq!(value["market_id"], 1);
419        assert_eq!(value["filter"], "spot");
420    }
421
422    #[rstest]
423    fn test_trades_query_renames_type_and_from() {
424        let query = LighterTradesQueryBuilder::default()
425            .market_id(0)
426            .from_timestamp(1_700_000_000_000)
427            .trade_type(LighterTradeQueryType::MarketSettlement)
428            .limit(50)
429            .build()
430            .unwrap();
431
432        let value = serde_json::to_value(query).unwrap();
433
434        assert_eq!(value["sort_by"], "trade_id");
435        assert_eq!(value["from"], 1_700_000_000_000_i64);
436        assert_eq!(value["type"], "market-settlement");
437        assert_eq!(value["limit"], 50);
438    }
439
440    #[rstest]
441    fn test_candles_query_serializes_resolution_and_timestamp_mode() {
442        let query = LighterCandlesQueryBuilder::default()
443            .market_id(0)
444            .resolution(LighterCandleResolution::OneMinute)
445            .start_timestamp(1_700_000_000_000)
446            .end_timestamp(1_700_000_060_000)
447            .count_back(500)
448            .set_timestamp_to_end(false)
449            .build()
450            .unwrap();
451
452        let value = serde_json::to_value(query).unwrap();
453
454        assert_eq!(value["market_id"], 0);
455        assert_eq!(value["resolution"], "1m");
456        assert_eq!(value["start_timestamp"], 1_700_000_000_000_i64);
457        assert_eq!(value["end_timestamp"], 1_700_000_060_000_i64);
458        assert_eq!(value["count_back"], 500);
459        assert_eq!(value["set_timestamp_to_end"], false);
460    }
461
462    #[rstest]
463    fn test_fundings_query_serializes_resolution() {
464        let query = LighterFundingsQueryBuilder::default()
465            .market_id(0)
466            .resolution(LighterFundingResolution::OneHour)
467            .start_timestamp(1_700_000_000_000)
468            .end_timestamp(1_700_003_600_000)
469            .count_back(100)
470            .build()
471            .unwrap();
472
473        let value = serde_json::to_value(query).unwrap();
474
475        assert_eq!(value["market_id"], 0);
476        assert_eq!(value["resolution"], "1h");
477        assert_eq!(value["start_timestamp"], 1_700_000_000_000_i64);
478        assert_eq!(value["end_timestamp"], 1_700_003_600_000_i64);
479        assert_eq!(value["count_back"], 100);
480    }
481
482    #[rstest]
483    fn test_order_book_orders_query_serializes_required_fields() {
484        let query = LighterOrderBookOrdersQuery {
485            market_id: 0,
486            limit: 25,
487        };
488
489        let value = serde_json::to_value(query).unwrap();
490
491        assert_eq!(value["market_id"], 0);
492        assert_eq!(value["limit"], 25);
493    }
494
495    #[rstest]
496    fn test_recent_trades_query_serializes_required_fields() {
497        let query = LighterRecentTradesQueryBuilder::default()
498            .market_id(1)
499            .limit(10)
500            .build()
501            .unwrap();
502
503        let value = serde_json::to_value(query).unwrap();
504
505        assert_eq!(value["market_id"], 1);
506        assert_eq!(value["limit"], 10);
507    }
508
509    #[rstest]
510    fn test_trades_query_serializes_optional_filters() {
511        let mut query = LighterTradesQuery {
512            authorization: Some(SecretString::from("bearer-token")),
513            auth: Some(SecretString::from("auth-token")),
514            market_id: Some(0),
515            account_index: Some(1234),
516            order_index: Some(5678),
517            order_index_str: Some("18446744073709551615".to_string()),
518            integrator_account_index: Some(723_813),
519            sort_by: LighterTradeSortBy::Timestamp,
520            sort_dir: Some(LighterSortDirection::Desc),
521            cursor: Some("cursor-1".to_string()),
522            from_timestamp: Some(1_700_000_000_000),
523            ask_filter: Some(1),
524            role: Some(LighterTradeRole::Maker),
525            trade_type: Some(LighterTradeQueryType::from(LighterTradeType::Liquidation)),
526            limit: 75,
527            aggregate: Some(true),
528        };
529
530        let value = serde_json::to_value(&query).unwrap();
531        let debug = format!("{query:?}");
532
533        assert_eq!(value["authorization"], "bearer-token");
534        assert_eq!(value["auth"], "auth-token");
535        assert_eq!(value["market_id"], 0);
536        assert_eq!(value["account_index"], 1234);
537        assert_eq!(value["order_index"], 5678);
538        assert_eq!(value["order_index_str"], "18446744073709551615");
539        assert_eq!(value["integrator_account_index"], 723_813);
540        assert_eq!(value["sort_by"], "timestamp");
541        assert_eq!(value["sort_dir"], "desc");
542        assert_eq!(
543            serde_json::to_value(LighterSortDirection::Asc).unwrap(),
544            "asc",
545        );
546        assert_eq!(value["cursor"], "cursor-1");
547        assert_eq!(value["from"], 1_700_000_000_000_i64);
548        assert_eq!(value["ask_filter"], 1);
549        assert_eq!(value["role"], "maker");
550        assert_eq!(value["type"], "liquidation");
551        assert_eq!(value["limit"], 75);
552        assert_eq!(value["aggregate"], true);
553        assert!(!debug.contains("bearer-token"));
554        assert!(!debug.contains("auth-token"));
555
556        query.zeroize();
557        assert!(query.authorization.is_none());
558        assert!(query.auth.is_none());
559    }
560
561    #[rstest]
562    fn test_trades_query_omits_announced_filters_when_unset() {
563        let query = LighterTradesQuery::default();
564
565        let value = serde_json::to_value(query).unwrap();
566
567        assert!(value.get("integrator_account_index").is_none());
568        assert!(value.get("order_index_str").is_none());
569    }
570
571    #[rstest]
572    #[case::single(vec![42], "42")]
573    #[case::multiple(vec![42, 43, 44], "42,43,44")]
574    fn test_account_orders_query_serializes_client_order_indexes(
575        #[case] indexes: Vec<i64>,
576        #[case] expected: &str,
577    ) {
578        let query = LighterAccountOrdersQueryBuilder::default()
579            .authorization("bearer-token")
580            .account_index(123)
581            .client_order_indexes(indexes.clone())
582            .build()
583            .unwrap();
584
585        let value = serde_json::to_value(&query).unwrap();
586        let decoded: LighterAccountOrdersQuery = serde_json::from_value(value.clone()).unwrap();
587
588        assert_eq!(value["authorization"], "bearer-token");
589        assert_eq!(value["account_index"], 123);
590        assert_eq!(value["client_order_indexes"], expected);
591        assert!(value.get("auth").is_none());
592        assert_eq!(decoded.client_order_indexes, indexes);
593    }
594
595    #[rstest]
596    #[case::empty(vec![])]
597    #[case::too_many((1..=21).collect::<Vec<i64>>())]
598    fn test_account_orders_query_rejects_invalid_index_counts(#[case] indexes: Vec<i64>) {
599        let query = LighterAccountOrdersQueryBuilder::default()
600            .account_index(123)
601            .client_order_indexes(indexes)
602            .build()
603            .unwrap();
604
605        assert!(serde_json::to_value(query).is_err());
606    }
607
608    #[rstest]
609    #[case::empty("")]
610    #[case::too_many((1..=21).map(|index| index.to_string()).collect::<Vec<_>>().join(","))]
611    fn test_account_orders_query_rejects_invalid_index_count_deserialization(
612        #[case] indexes: String,
613    ) {
614        let value = serde_json::json!({
615            "account_index": 123,
616            "client_order_indexes": indexes,
617        });
618
619        assert!(serde_json::from_value::<LighterAccountOrdersQuery>(value).is_err());
620    }
621
622    #[rstest]
623    fn test_account_active_orders_query_serializes_required_fields() {
624        let query = LighterAccountActiveOrdersQueryBuilder::default()
625            .auth("auth-token")
626            .account_index(123)
627            .market_id(0)
628            .build()
629            .unwrap();
630
631        let value = serde_json::to_value(query).unwrap();
632
633        assert_eq!(value["auth"], "auth-token");
634        assert_eq!(value["account_index"], 123);
635        assert_eq!(value["market_id"], 0);
636        assert!(value.get("authorization").is_none());
637    }
638
639    #[rstest]
640    fn test_account_inactive_orders_query_serializes_optional_filters() {
641        let query = LighterAccountInactiveOrdersQueryBuilder::default()
642            .authorization("bearer-token")
643            .account_index(123)
644            .market_id(0)
645            .ask_filter(1)
646            .between_timestamps("1700000000-1700003600")
647            .cursor("cursor-1")
648            .limit(50)
649            .build()
650            .unwrap();
651
652        let value = serde_json::to_value(query).unwrap();
653
654        assert_eq!(value["authorization"], "bearer-token");
655        assert_eq!(value["account_index"], 123);
656        assert_eq!(value["market_id"], 0);
657        assert_eq!(value["ask_filter"], 1);
658        assert_eq!(value["between_timestamps"], "1700000000-1700003600",);
659        assert_eq!(value["cursor"], "cursor-1");
660        assert_eq!(value["limit"], 50);
661        assert!(value.get("auth").is_none());
662    }
663}