Skip to main content

nautilus_lighter/http/
models.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//! Request and response payload definitions for Lighter REST endpoints.
17
18use std::{collections::BTreeMap, str::FromStr};
19
20use nautilus_core::serialization::{
21    deserialize_decimal, deserialize_decimal_from_str, deserialize_decimal_or_zero,
22    deserialize_optional_decimal,
23};
24use rust_decimal::Decimal;
25use serde::{Deserialize, Serialize, de};
26use ustr::Ustr;
27use zeroize::ZeroizeOnDrop;
28
29use crate::common::enums::{
30    LighterCandleResolution, LighterFundingResolution, LighterMarketStatus, LighterOrderKind,
31    LighterOrderSide, LighterOrderStatus, LighterOrderTimeInForce, LighterPositionMarginMode,
32    LighterProductType, LighterTradeType, LighterTriggerStatus, LighterTxStatus,
33};
34
35#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
36pub struct LighterResultCode {
37    pub code: i32,
38    pub message: Option<String>,
39}
40
41/// Response payload of `GET /api/v1/nextNonce`.
42///
43/// The venue reports the next sequence number it expects on `sendTx` for the
44/// `(account_index, api_key_index)` pair. Pass this to
45/// [`crate::signing::nonce::NonceManager::refresh`] before the first signed
46/// transaction.
47#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
48pub struct LighterNextNonce {
49    pub code: i32,
50    pub message: Option<String>,
51    pub nonce: i64,
52}
53
54/// Response payload of `GET /api/v1/tx`.
55#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
56pub struct LighterTx {
57    pub code: i32,
58    pub message: Option<String>,
59    pub hash: String,
60    #[serde(rename = "type")]
61    pub tx_type: u8,
62    pub info: String,
63    pub event_info: String,
64    pub status: LighterTxStatus,
65    pub account_index: i64,
66    pub nonce: i64,
67    pub api_key_index: u8,
68}
69
70/// One account row from `GET /api/v1/account`.
71///
72/// Models only the fields the adapter consumes; the venue response carries
73/// many more, which are ignored on deserialization.
74#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq, ZeroizeOnDrop)]
75pub struct LighterAccountDetail {
76    pub account_index: u64,
77    pub account_type: u8,
78    pub status: i32,
79    pub l1_address: String,
80}
81
82/// Response payload of `GET /api/v1/account`.
83#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
84pub struct LighterAccountsResponse {
85    pub code: i32,
86    pub message: Option<String>,
87    pub total: i64,
88    #[serde(default, deserialize_with = "deserialize_null_vec")]
89    pub accounts: Vec<LighterAccountDetail>,
90}
91
92/// Response payload of `GET /api/v1/getMakerOnlyApiKeys`.
93///
94/// Lighter restricts maker-only keys to the 0ms speed-bump lane (PostOnly
95/// creates, modifies on ALO orders, cancel / cancel-all). Any tx kind outside
96/// that allowlist - for example `ApproveIntegrator` (tx_type 45) - is rejected
97/// with venue code `62007`. The adapter pre-flights this endpoint before
98/// submitting the integrator auto-approval so it can skip the doomed tx with
99/// a clear log line instead of swallowing the misleading 62007.
100#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
101pub struct LighterMakerOnlyApiKeys {
102    pub code: i32,
103    pub message: Option<String>,
104    #[serde(default)]
105    pub api_key_indexes: Vec<i64>,
106}
107
108#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
109pub struct LighterSendTxRequest {
110    pub tx_type: u8,
111    pub tx_info: String,
112    #[serde(skip_serializing_if = "Option::is_none")]
113    pub price_protection: Option<bool>,
114}
115
116impl LighterSendTxRequest {
117    #[must_use]
118    pub fn new(tx_type: u8, tx_info: impl Into<String>) -> Self {
119        Self {
120            tx_type,
121            tx_info: tx_info.into(),
122            price_protection: None,
123        }
124    }
125
126    #[must_use]
127    pub const fn with_price_protection(mut self, price_protection: bool) -> Self {
128        self.price_protection = Some(price_protection);
129        self
130    }
131
132    pub(crate) fn form_fields(&self) -> Vec<(&'static str, String)> {
133        let mut fields = vec![
134            ("tx_type", self.tx_type.to_string()),
135            ("tx_info", self.tx_info.clone()),
136        ];
137
138        if let Some(price_protection) = self.price_protection {
139            fields.push(("price_protection", price_protection.to_string()));
140        }
141        fields
142    }
143}
144
145#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
146pub struct LighterSendTxBatchRequest {
147    pub tx_types: String,
148    pub tx_infos: String,
149}
150
151impl LighterSendTxBatchRequest {
152    #[must_use]
153    pub fn new(tx_types: impl Into<String>, tx_infos: impl Into<String>) -> Self {
154        Self {
155            tx_types: tx_types.into(),
156            tx_infos: tx_infos.into(),
157        }
158    }
159
160    pub(crate) fn form_fields(&self) -> Vec<(&'static str, String)> {
161        vec![
162            ("tx_types", self.tx_types.clone()),
163            ("tx_infos", self.tx_infos.clone()),
164        ]
165    }
166}
167
168#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
169pub struct LighterSendTxResponse {
170    pub code: i32,
171    pub message: Option<String>,
172    pub tx_hash: String,
173    pub predicted_execution_time_ms: i64,
174    pub volume_quota_remaining: Option<i64>,
175    #[serde(skip_serializing_if = "Option::is_none")]
176    pub remaining_send_tx: Option<i64>,
177}
178
179#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
180pub struct LighterSendTxBatchResponse {
181    pub code: i32,
182    pub message: Option<String>,
183    #[serde(default, deserialize_with = "deserialize_null_vec")]
184    pub tx_hash: Vec<String>,
185    pub predicted_execution_time_ms: i64,
186    pub volume_quota_remaining: Option<i64>,
187    #[serde(skip_serializing_if = "Option::is_none")]
188    pub remaining_send_tx: Option<i64>,
189}
190
191#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
192pub struct LighterOrderBooks {
193    pub code: i32,
194    pub message: Option<String>,
195    #[serde(default, deserialize_with = "deserialize_null_vec")]
196    pub order_books: Vec<LighterOrderBook>,
197}
198
199#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
200pub struct LighterOrderBook {
201    pub symbol: Ustr,
202    pub market_id: i64,
203    pub market_type: LighterProductType,
204    pub base_asset_id: i16,
205    pub quote_asset_id: i16,
206    pub status: LighterMarketStatus,
207    #[serde(deserialize_with = "deserialize_decimal_from_str")]
208    pub taker_fee: Decimal,
209    #[serde(deserialize_with = "deserialize_decimal_from_str")]
210    pub maker_fee: Decimal,
211    #[serde(deserialize_with = "deserialize_decimal_from_str")]
212    pub liquidation_fee: Decimal,
213    #[serde(deserialize_with = "deserialize_decimal_from_str")]
214    pub min_base_amount: Decimal,
215    #[serde(deserialize_with = "deserialize_decimal_from_str")]
216    pub min_quote_amount: Decimal,
217    #[serde(deserialize_with = "deserialize_decimal_from_str")]
218    pub order_quote_limit: Decimal,
219    pub supported_size_decimals: u8,
220    pub supported_price_decimals: u8,
221    pub supported_quote_decimals: u8,
222}
223
224#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
225pub struct LighterOrderBookDetails {
226    pub code: i32,
227    pub message: Option<String>,
228    #[serde(default, deserialize_with = "deserialize_null_vec")]
229    pub order_book_details: Vec<LighterPerpOrderBookDetail>,
230    #[serde(default, deserialize_with = "deserialize_null_vec")]
231    pub spot_order_book_details: Vec<LighterSpotOrderBookDetail>,
232}
233
234#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
235pub struct LighterPerpOrderBookDetail {
236    #[serde(flatten)]
237    pub order_book: LighterOrderBook,
238    pub size_decimals: u8,
239    pub price_decimals: u8,
240    pub quote_multiplier: i64,
241    pub default_initial_margin_fraction: u16,
242    pub min_initial_margin_fraction: u16,
243    pub maintenance_margin_fraction: u16,
244    pub closeout_margin_fraction: u16,
245    #[serde(deserialize_with = "deserialize_decimal")]
246    pub last_trade_price: Decimal,
247    pub daily_trades_count: i64,
248    #[serde(deserialize_with = "deserialize_decimal")]
249    pub daily_base_token_volume: Decimal,
250    #[serde(deserialize_with = "deserialize_decimal")]
251    pub daily_quote_token_volume: Decimal,
252    #[serde(deserialize_with = "deserialize_decimal")]
253    pub daily_price_low: Decimal,
254    #[serde(deserialize_with = "deserialize_decimal")]
255    pub daily_price_high: Decimal,
256    #[serde(deserialize_with = "deserialize_decimal")]
257    pub daily_price_change: Decimal,
258    #[serde(deserialize_with = "deserialize_decimal")]
259    pub open_interest: Decimal,
260    #[serde(deserialize_with = "deserialize_decimal_btree_map")]
261    pub daily_chart: BTreeMap<String, Decimal>,
262    pub market_config: LighterMarketConfig,
263    pub strategy_index: u8,
264}
265
266#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
267pub struct LighterSpotOrderBookDetail {
268    #[serde(flatten)]
269    pub order_book: LighterOrderBook,
270    pub size_decimals: u8,
271    pub price_decimals: u8,
272    #[serde(deserialize_with = "deserialize_decimal")]
273    pub last_trade_price: Decimal,
274    pub daily_trades_count: i64,
275    #[serde(deserialize_with = "deserialize_decimal")]
276    pub daily_base_token_volume: Decimal,
277    #[serde(deserialize_with = "deserialize_decimal")]
278    pub daily_quote_token_volume: Decimal,
279    #[serde(deserialize_with = "deserialize_decimal")]
280    pub daily_price_low: Decimal,
281    #[serde(deserialize_with = "deserialize_decimal")]
282    pub daily_price_high: Decimal,
283    #[serde(deserialize_with = "deserialize_decimal")]
284    pub daily_price_change: Decimal,
285    #[serde(deserialize_with = "deserialize_decimal_btree_map")]
286    pub daily_chart: BTreeMap<String, Decimal>,
287}
288
289#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
290pub struct LighterMarketConfig {
291    pub market_margin_mode: LighterPositionMarginMode,
292    pub insurance_fund_account_index: i64,
293    pub liquidation_mode: i32,
294    pub force_reduce_only: bool,
295    pub trading_hours: String,
296    #[serde(default, skip_serializing_if = "Option::is_none")]
297    pub funding_fee_discounts_enabled: Option<bool>,
298    pub hidden: bool,
299    pub rfq_enabled: bool,
300}
301
302#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
303pub struct LighterOrderBookOrders {
304    pub code: i32,
305    pub message: Option<String>,
306    pub total_asks: i64,
307    #[serde(default, deserialize_with = "deserialize_null_vec")]
308    pub asks: Vec<LighterSimpleOrder>,
309    pub total_bids: i64,
310    #[serde(default, deserialize_with = "deserialize_null_vec")]
311    pub bids: Vec<LighterSimpleOrder>,
312}
313
314#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
315pub struct LighterSimpleOrder {
316    pub order_index: i64,
317    pub order_id: String,
318    pub owner_account_index: i64,
319    #[serde(deserialize_with = "deserialize_decimal_from_str")]
320    pub initial_base_amount: Decimal,
321    #[serde(deserialize_with = "deserialize_decimal_from_str")]
322    pub remaining_base_amount: Decimal,
323    #[serde(deserialize_with = "deserialize_decimal_from_str")]
324    pub price: Decimal,
325    pub order_expiry: i64,
326    pub transaction_time: i64,
327}
328
329#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
330pub struct LighterOrderBookDepth {
331    pub code: i32,
332    pub message: Option<String>,
333    #[serde(default, deserialize_with = "deserialize_null_vec")]
334    pub asks: Vec<LighterPriceLevel>,
335    #[serde(default, deserialize_with = "deserialize_null_vec")]
336    pub bids: Vec<LighterPriceLevel>,
337    pub offset: i64,
338    pub nonce: i64,
339}
340
341/// A single book level returned by the order-book REST snapshot and the
342/// WebSocket ticker / order_book / order_book_depth frames.
343///
344/// Lighter sends empty strings on the bid or ask side of a ticker frame when
345/// that side currently has no resting orders; [`deserialize_decimal_or_zero`]
346/// maps those to [`Decimal::ZERO`]. Downstream parsers must treat a
347/// zero-priced (or zero-sized) level as an uninhabited side, not a literal
348/// zero quote.
349#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
350pub struct LighterPriceLevel {
351    #[serde(deserialize_with = "deserialize_decimal_or_zero")]
352    pub price: Decimal,
353    #[serde(deserialize_with = "deserialize_decimal_or_zero")]
354    pub size: Decimal,
355}
356
357#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
358pub struct LighterTrades {
359    pub code: i32,
360    pub message: Option<String>,
361    pub next_cursor: Option<String>,
362    #[serde(default, deserialize_with = "deserialize_null_vec")]
363    pub trades: Vec<LighterTrade>,
364}
365
366#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
367pub struct LighterCandles {
368    pub code: i32,
369    pub message: Option<String>,
370    #[serde(rename = "r")]
371    pub resolution: LighterCandleResolution,
372    #[serde(rename = "c", default, deserialize_with = "deserialize_null_vec")]
373    pub candles: Vec<LighterCandle>,
374}
375
376#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
377pub struct LighterCandle {
378    #[serde(rename = "t")]
379    pub timestamp: i64,
380    #[serde(rename = "o", default, deserialize_with = "deserialize_decimal")]
381    pub open: Decimal,
382    #[serde(rename = "h", default, deserialize_with = "deserialize_decimal")]
383    pub high: Decimal,
384    #[serde(rename = "l", default, deserialize_with = "deserialize_decimal")]
385    pub low: Decimal,
386    #[serde(rename = "c", default, deserialize_with = "deserialize_decimal")]
387    pub close: Decimal,
388    #[serde(rename = "v", default, deserialize_with = "deserialize_decimal")]
389    pub volume_base: Decimal,
390    #[serde(rename = "V", default, deserialize_with = "deserialize_decimal")]
391    pub volume_quote: Decimal,
392    #[serde(rename = "i")]
393    pub last_trade_id: i64,
394}
395
396#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
397pub struct LighterFundings {
398    pub code: i32,
399    pub message: Option<String>,
400    pub resolution: LighterFundingResolution,
401    #[serde(default, deserialize_with = "deserialize_null_vec")]
402    pub fundings: Vec<LighterFunding>,
403}
404
405#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
406pub struct LighterFunding {
407    pub timestamp: i64,
408    #[serde(deserialize_with = "deserialize_decimal")]
409    pub value: Decimal,
410    #[serde(deserialize_with = "deserialize_decimal")]
411    pub rate: Decimal,
412    pub direction: LighterFundingDirection,
413}
414
415#[derive(Copy, Clone, Debug, Deserialize, Serialize, PartialEq, Eq)]
416#[serde(rename_all = "lowercase")]
417pub enum LighterFundingDirection {
418    Long,
419    Short,
420}
421
422#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
423pub struct LighterTrade {
424    pub trade_id: i64,
425    pub trade_id_str: Option<String>,
426    pub tx_hash: String,
427    #[serde(rename = "type")]
428    pub trade_type: LighterTradeType,
429    pub market_id: i64,
430    #[serde(deserialize_with = "deserialize_decimal_from_str")]
431    pub size: Decimal,
432    #[serde(deserialize_with = "deserialize_decimal_from_str")]
433    pub price: Decimal,
434    #[serde(deserialize_with = "deserialize_decimal_from_str")]
435    pub usd_amount: Decimal,
436    pub ask_id: i64,
437    pub ask_id_str: Option<String>,
438    pub bid_id: i64,
439    pub bid_id_str: Option<String>,
440    pub ask_client_id: i64,
441    pub ask_client_id_str: Option<String>,
442    pub bid_client_id: i64,
443    pub bid_client_id_str: Option<String>,
444    pub ask_account_id: i64,
445    pub bid_account_id: i64,
446    pub is_maker_ask: bool,
447    pub block_height: i64,
448    pub timestamp: i64,
449    pub taker_fee: Option<i32>,
450    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
451    pub taker_position_size_before: Option<Decimal>,
452    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
453    pub taker_entry_quote_before: Option<Decimal>,
454    pub taker_initial_margin_fraction_before: Option<u16>,
455    pub taker_position_sign_changed: Option<bool>,
456    pub maker_fee: Option<i32>,
457    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
458    pub maker_position_size_before: Option<Decimal>,
459    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
460    pub maker_entry_quote_before: Option<Decimal>,
461    pub maker_initial_margin_fraction_before: Option<u16>,
462    pub maker_position_sign_changed: Option<bool>,
463    pub transaction_time: i64,
464    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
465    pub ask_account_pnl: Option<Decimal>,
466    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
467    pub bid_account_pnl: Option<Decimal>,
468}
469
470#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
471pub struct LighterOrders {
472    pub code: i32,
473    pub message: Option<String>,
474    pub next_cursor: Option<String>,
475    #[serde(default, deserialize_with = "deserialize_null_vec")]
476    pub orders: Vec<LighterOrder>,
477}
478
479#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
480pub struct LighterOrder {
481    pub order_index: i64,
482    pub client_order_index: i64,
483    pub order_id: String,
484    pub client_order_id: String,
485    pub market_index: i64,
486    pub owner_account_index: i64,
487    #[serde(deserialize_with = "deserialize_decimal_from_str")]
488    pub initial_base_amount: Decimal,
489    #[serde(deserialize_with = "deserialize_decimal_from_str")]
490    pub price: Decimal,
491    pub nonce: i64,
492    #[serde(deserialize_with = "deserialize_decimal_from_str")]
493    pub remaining_base_amount: Decimal,
494    pub is_ask: bool,
495    pub base_size: i64,
496    pub base_price: i32,
497    #[serde(deserialize_with = "deserialize_decimal_from_str")]
498    pub filled_base_amount: Decimal,
499    #[serde(deserialize_with = "deserialize_decimal_from_str")]
500    pub filled_quote_amount: Decimal,
501    #[serde(default, deserialize_with = "deserialize_order_side")]
502    pub side: Option<LighterOrderSide>,
503    #[serde(rename = "type")]
504    pub order_type: LighterOrderKind,
505    pub time_in_force: LighterOrderTimeInForce,
506    pub reduce_only: bool,
507    // Lighter sends an empty string when no trigger price is set.
508    #[serde(deserialize_with = "deserialize_decimal_or_zero")]
509    pub trigger_price: Decimal,
510    pub order_expiry: i64,
511    pub status: LighterOrderStatus,
512    pub trigger_status: LighterTriggerStatus,
513    pub trigger_time: i64,
514    pub parent_order_index: i64,
515    pub parent_order_id: String,
516    pub to_trigger_order_id_0: String,
517    pub to_trigger_order_id_1: String,
518    pub to_cancel_order_id_0: String,
519    pub integrator_fee_collector_index: String,
520    #[serde(deserialize_with = "deserialize_decimal_or_zero")]
521    pub integrator_taker_fee: Decimal,
522    #[serde(deserialize_with = "deserialize_decimal_or_zero")]
523    pub integrator_maker_fee: Decimal,
524    pub block_height: i64,
525    pub timestamp: i64,
526    pub created_at: i64,
527    pub updated_at: i64,
528    pub transaction_time: i64,
529}
530
531#[derive(Deserialize)]
532struct DecimalFromAny(#[serde(deserialize_with = "deserialize_decimal")] Decimal);
533
534fn deserialize_decimal_btree_map<'de, D>(
535    deserializer: D,
536) -> Result<BTreeMap<String, Decimal>, D::Error>
537where
538    D: serde::Deserializer<'de>,
539{
540    BTreeMap::<String, DecimalFromAny>::deserialize(deserializer).map(|values| {
541        values
542            .into_iter()
543            .map(|(key, decimal)| (key, decimal.0))
544            .collect()
545    })
546}
547
548fn deserialize_null_vec<'de, D, T>(deserializer: D) -> Result<Vec<T>, D::Error>
549where
550    D: serde::Deserializer<'de>,
551    T: Deserialize<'de>,
552{
553    Option::<Vec<T>>::deserialize(deserializer).map(Option::unwrap_or_default)
554}
555
556fn deserialize_order_side<'de, D>(deserializer: D) -> Result<Option<LighterOrderSide>, D::Error>
557where
558    D: serde::Deserializer<'de>,
559{
560    let value = Option::<String>::deserialize(deserializer)?;
561    match value.as_deref() {
562        None | Some("") => Ok(None),
563        Some(s) => LighterOrderSide::from_str(s)
564            .map(Some)
565            .map_err(|_| de::Error::unknown_variant(s, &["buy", "sell", ""])),
566    }
567}
568
569#[cfg(test)]
570mod tests {
571    use rstest::rstest;
572
573    use super::*;
574
575    const HTTP_ORDER_BOOK_DETAILS: &str =
576        include_str!("../../test_data/http_order_book_details.json");
577    const HTTP_ORDER_BOOK_DETAILS_WIDENED_IDS: &str =
578        include_str!("../../test_data/http_order_book_details_widened_ids.json");
579    const HTTP_RECENT_TRADES: &str = include_str!("../../test_data/http_recent_trades.json");
580    const HTTP_RECENT_TRADES_MISSING: &str =
581        include_str!("../../test_data/http_recent_trades_missing.json");
582    const HTTP_RECENT_TRADES_NULL: &str =
583        include_str!("../../test_data/http_recent_trades_null.json");
584    const HTTP_ORDER_BOOKS: &str = include_str!("../../test_data/http_order_books.json");
585    const HTTP_ORDER_BOOKS_WIDENED_IDS: &str =
586        include_str!("../../test_data/http_order_books_widened_ids.json");
587    const HTTP_ORDER_BOOK_ORDERS: &str =
588        include_str!("../../test_data/http_order_book_orders.json");
589    const HTTP_ORDER_BOOK_DEPTH: &str = include_str!("../../test_data/http_order_book_depth.json");
590    const HTTP_ORDER_BOOK_DEPTH_NULL: &str =
591        include_str!("../../test_data/http_order_book_depth_null.json");
592    const HTTP_ORDERS: &str = include_str!("../../test_data/http_orders.json");
593    const HTTP_CANDLES: &str = include_str!("../../test_data/http_candles.json");
594    const HTTP_CANDLES_NULL: &str = include_str!("../../test_data/http_candles_null.json");
595    const HTTP_FUNDINGS: &str = include_str!("../../test_data/http_fundings.json");
596    const HTTP_ACCOUNT: &str = include_str!("../../test_data/http_account.json");
597    const HTTP_SEND_TX_WITH_HEADROOM: &str =
598        include_str!("../../test_data/http_send_tx_with_headroom.json");
599    const HTTP_SEND_TX_LEGACY: &str = include_str!("../../test_data/http_send_tx_legacy.json");
600    const HTTP_SEND_TX_BATCH_WITH_HEADROOM: &str =
601        include_str!("../../test_data/http_send_tx_batch_with_headroom.json");
602    const HTTP_SEND_TX_BATCH_LEGACY: &str =
603        include_str!("../../test_data/http_send_tx_batch_legacy.json");
604
605    #[rstest]
606    fn test_account_response_deserializes_live_shape() {
607        let response: LighterAccountsResponse = serde_json::from_str(HTTP_ACCOUNT).unwrap();
608
609        assert_eq!(response.code, 200);
610        assert_eq!(response.total, 1);
611        assert_eq!(response.accounts.len(), 1);
612        let account = &response.accounts[0];
613        assert_eq!(account.account_index, 123_456);
614        assert_eq!(account.account_type, 0);
615        assert_eq!(account.status, 1);
616        assert_eq!(
617            account.l1_address,
618            "0x0000000000000000000000000000000000000000"
619        );
620    }
621
622    #[rstest]
623    fn test_account_response_allows_missing_or_null_accounts() {
624        let missing = serde_json::json!({"code": 200, "total": 0});
625        let null = serde_json::json!({"code": 200, "total": 0, "accounts": null});
626
627        let missing: LighterAccountsResponse = serde_json::from_value(missing).unwrap();
628        let null: LighterAccountsResponse = serde_json::from_value(null).unwrap();
629
630        assert!(missing.accounts.is_empty());
631        assert!(null.accounts.is_empty());
632    }
633
634    #[rstest]
635    fn test_send_tx_batch_response_allows_missing_or_null_tx_hash() {
636        let missing = serde_json::json!({
637            "code": 200,
638            "predicted_execution_time_ms": 1_751_465_475,
639        });
640        let null = serde_json::json!({
641            "code": 200,
642            "tx_hash": null,
643            "predicted_execution_time_ms": 1_751_465_475,
644        });
645
646        let missing: LighterSendTxBatchResponse = serde_json::from_value(missing).unwrap();
647        let null: LighterSendTxBatchResponse = serde_json::from_value(null).unwrap();
648
649        assert!(missing.tx_hash.is_empty());
650        assert!(null.tx_hash.is_empty());
651    }
652
653    #[rstest]
654    #[case::with_headroom(HTTP_SEND_TX_WITH_HEADROOM, Some(17))]
655    #[case::legacy(HTTP_SEND_TX_LEGACY, None)]
656    fn test_send_tx_response_deserializes_optional_remaining_send_tx(
657        #[case] fixture: &str,
658        #[case] expected: Option<i64>,
659    ) {
660        let response: LighterSendTxResponse = serde_json::from_str(fixture).unwrap();
661
662        assert_eq!(response.code, 200);
663        assert_eq!(response.message, None);
664        assert_eq!(response.tx_hash, "0xabc");
665        assert_eq!(response.predicted_execution_time_ms, 1_751_465_474);
666        assert_eq!(response.volume_quota_remaining, Some(123));
667        assert_eq!(response.remaining_send_tx, expected);
668
669        let serialized = serde_json::to_value(&response).unwrap();
670        assert_eq!(
671            serialized.get("remaining_send_tx").is_some(),
672            expected.is_some()
673        );
674
675        if let Some(expected) = expected {
676            assert_eq!(serialized["remaining_send_tx"], expected);
677        }
678    }
679
680    #[rstest]
681    #[case::with_headroom(HTTP_SEND_TX_BATCH_WITH_HEADROOM, Some(18))]
682    #[case::legacy(HTTP_SEND_TX_BATCH_LEGACY, None)]
683    fn test_send_tx_batch_response_deserializes_optional_remaining_send_tx(
684        #[case] fixture: &str,
685        #[case] expected: Option<i64>,
686    ) {
687        let response: LighterSendTxBatchResponse = serde_json::from_str(fixture).unwrap();
688
689        assert_eq!(response.code, 200);
690        assert_eq!(response.message, None);
691        assert_eq!(response.tx_hash, vec!["0xabc", "0xdef"]);
692        assert_eq!(response.predicted_execution_time_ms, 1_751_465_475);
693        assert_eq!(response.volume_quota_remaining, Some(122));
694        assert_eq!(response.remaining_send_tx, expected);
695
696        let serialized = serde_json::to_value(&response).unwrap();
697        assert_eq!(
698            serialized.get("remaining_send_tx").is_some(),
699            expected.is_some()
700        );
701
702        if let Some(expected) = expected {
703            assert_eq!(serialized["remaining_send_tx"], expected);
704        }
705    }
706
707    #[rstest]
708    fn test_order_book_details_deserializes_live_shape() {
709        let details: LighterOrderBookDetails =
710            serde_json::from_str(HTTP_ORDER_BOOK_DETAILS).unwrap();
711
712        assert_eq!(details.code, 200);
713        assert_eq!(details.order_book_details.len(), 1);
714        assert_eq!(
715            details.order_book_details[0].order_book.market_type,
716            LighterProductType::Perp,
717        );
718        assert_eq!(details.order_book_details[0].price_decimals, 2);
719        assert_eq!(
720            details.order_book_details[0].last_trade_price,
721            Decimal::new(236_131, 2),
722        );
723        assert_eq!(
724            details.order_book_details[0].daily_base_token_volume,
725            Decimal::new(1_953_991_521, 4),
726        );
727        assert_eq!(
728            details.order_book_details[0]
729                .market_config
730                .market_margin_mode,
731            LighterPositionMarginMode::Cross,
732        );
733        assert!(details.spot_order_book_details.is_empty());
734    }
735
736    #[rstest]
737    fn test_order_book_details_deserializes_widened_market_ids() {
738        let details: LighterOrderBookDetails =
739            serde_json::from_str(HTTP_ORDER_BOOK_DETAILS_WIDENED_IDS).unwrap();
740
741        assert_eq!(details.code, 200);
742        assert_eq!(details.order_book_details.len(), 2);
743        assert_eq!(details.spot_order_book_details.len(), 2);
744
745        let perp_ids: Vec<i64> = details
746            .order_book_details
747            .iter()
748            .map(|d| d.order_book.market_id)
749            .collect();
750        assert_eq!(perp_ids, vec![4095, 40_000]);
751        assert!(
752            details
753                .order_book_details
754                .iter()
755                .all(|d| d.order_book.market_type == LighterProductType::Perp)
756        );
757
758        let spot_ids: Vec<i64> = details
759            .spot_order_book_details
760            .iter()
761            .map(|d| d.order_book.market_id)
762            .collect();
763        assert_eq!(spot_ids, vec![4098, 50_000]);
764        assert!(
765            details
766                .spot_order_book_details
767                .iter()
768                .all(|d| d.order_book.market_type == LighterProductType::Spot)
769        );
770    }
771
772    #[rstest]
773    fn test_recent_trades_allow_omitted_fee_fields() {
774        let trades: LighterTrades = serde_json::from_str(HTTP_RECENT_TRADES).unwrap();
775
776        assert_eq!(trades.trades.len(), 1);
777        assert_eq!(
778            trades.trades[0].trade_id_str.as_deref(),
779            Some("19211490282")
780        );
781        assert_eq!(trades.trades[0].taker_fee, None);
782        assert_eq!(trades.trades[0].maker_fee, Some(28));
783    }
784
785    #[rstest]
786    fn test_recent_trades_deserializes_null_trades_as_empty() {
787        let trades: LighterTrades = serde_json::from_str(HTTP_RECENT_TRADES_NULL).unwrap();
788
789        assert_eq!(trades.code, 200);
790        assert!(trades.trades.is_empty());
791    }
792
793    #[rstest]
794    fn test_recent_trades_deserializes_missing_trades_as_empty() {
795        let trades: LighterTrades = serde_json::from_str(HTTP_RECENT_TRADES_MISSING).unwrap();
796
797        assert_eq!(trades.code, 200);
798        assert!(trades.trades.is_empty());
799    }
800
801    #[rstest]
802    fn test_candles_deserializes_live_shape_with_omitted_raw_fields() {
803        let candles: LighterCandles = serde_json::from_str(HTTP_CANDLES).unwrap();
804
805        assert_eq!(candles.code, 200);
806        assert_eq!(candles.resolution, LighterCandleResolution::OneMinute);
807        assert_eq!(candles.candles.len(), 2);
808        assert_eq!(candles.candles[0].timestamp, 1_700_000_000_000);
809        assert_eq!(candles.candles[0].open, Decimal::new(236_111, 2));
810        assert_eq!(candles.candles[0].high, Decimal::new(236_222, 2));
811        assert_eq!(candles.candles[0].low, Decimal::new(236_000, 2));
812        assert_eq!(candles.candles[0].close, Decimal::new(236_131, 2));
813        assert_eq!(candles.candles[0].volume_base, Decimal::new(12_345, 4));
814        assert_eq!(candles.candles[0].last_trade_id, 19_211_490_282);
815    }
816
817    #[rstest]
818    fn test_candles_deserializes_null_candles_as_empty() {
819        let candles: LighterCandles = serde_json::from_str(HTTP_CANDLES_NULL).unwrap();
820
821        assert_eq!(candles.code, 200);
822        assert_eq!(candles.resolution, LighterCandleResolution::OneMinute);
823        assert!(candles.candles.is_empty());
824    }
825
826    #[rstest]
827    #[case("o")]
828    #[case("h")]
829    #[case("l")]
830    #[case("c")]
831    fn test_candle_missing_or_null_ohlc_deserializes_as_zero(#[case] field: &str) {
832        let base = serde_json::json!({
833            "t": 1_700_000_000_000_i64,
834            "o": "1",
835            "h": "1",
836            "l": "1",
837            "c": "1",
838            "v": "1",
839            "V": "1",
840            "i": 1,
841        });
842        let mut missing = base.clone();
843        missing.as_object_mut().unwrap().remove(field);
844        let mut null = base;
845        null[field] = serde_json::Value::Null;
846
847        let missing: LighterCandle = serde_json::from_value(missing).unwrap();
848        let null: LighterCandle = serde_json::from_value(null).unwrap();
849        let value_for = |candle: &LighterCandle| match field {
850            "o" => candle.open,
851            "h" => candle.high,
852            "l" => candle.low,
853            "c" => candle.close,
854            _ => unreachable!(),
855        };
856
857        assert_eq!(value_for(&missing), Decimal::ZERO);
858        assert_eq!(value_for(&null), Decimal::ZERO);
859    }
860
861    #[rstest]
862    fn test_fundings_deserializes_live_shape() {
863        let fundings: LighterFundings = serde_json::from_str(HTTP_FUNDINGS).unwrap();
864
865        assert_eq!(fundings.code, 200);
866        assert_eq!(fundings.resolution, LighterFundingResolution::OneHour);
867        assert_eq!(fundings.fundings.len(), 2);
868        assert_eq!(fundings.fundings[0].timestamp, 1_778_702_400);
869        assert_eq!(fundings.fundings[0].rate, Decimal::new(12, 4));
870        assert_eq!(
871            fundings.fundings[0].direction,
872            LighterFundingDirection::Long
873        );
874        assert_eq!(
875            fundings.fundings[1].direction,
876            LighterFundingDirection::Short
877        );
878    }
879
880    #[rstest]
881    fn test_order_books_deserializes_live_shape() {
882        let order_books: LighterOrderBooks = serde_json::from_str(HTTP_ORDER_BOOKS).unwrap();
883
884        assert_eq!(order_books.code, 200);
885        assert_eq!(order_books.order_books.len(), 1);
886        assert_eq!(order_books.order_books[0].symbol, Ustr::from("ETH"));
887        assert_eq!(
888            order_books.order_books[0].market_type,
889            LighterProductType::Perp
890        );
891        assert_eq!(
892            order_books.order_books[0].status,
893            LighterMarketStatus::Active
894        );
895        assert_eq!(order_books.order_books[0].supported_price_decimals, 2);
896    }
897
898    #[rstest]
899    fn test_order_books_deserializes_widened_market_ids() {
900        let order_books: LighterOrderBooks =
901            serde_json::from_str(HTTP_ORDER_BOOKS_WIDENED_IDS).unwrap();
902
903        assert_eq!(order_books.code, 200);
904        assert_eq!(order_books.order_books.len(), 2);
905        assert_eq!(order_books.order_books[0].market_id, 4095);
906        assert_eq!(
907            order_books.order_books[0].market_type,
908            LighterProductType::Perp
909        );
910        assert_eq!(order_books.order_books[1].market_id, 50_000);
911        assert_eq!(
912            order_books.order_books[1].market_type,
913            LighterProductType::Spot
914        );
915    }
916
917    #[rstest]
918    fn test_order_book_orders_deserializes_live_shape() {
919        let book: LighterOrderBookOrders = serde_json::from_str(HTTP_ORDER_BOOK_ORDERS).unwrap();
920
921        assert_eq!(book.total_asks, 1);
922        assert_eq!(book.asks[0].order_id, "281476929689581");
923        assert_eq!(book.asks[0].price, Decimal::from_str("2361.32").unwrap());
924        assert_eq!(book.total_bids, 1);
925        assert_eq!(
926            book.bids[0].remaining_base_amount,
927            Decimal::from_str("3.4125").unwrap(),
928        );
929    }
930
931    #[rstest]
932    fn test_order_book_depth_deserializes_live_shape() {
933        let depth: LighterOrderBookDepth = serde_json::from_str(HTTP_ORDER_BOOK_DEPTH).unwrap();
934
935        assert_eq!(depth.code, 200);
936        assert_eq!(depth.asks[0].price, Decimal::from_str("2352.74").unwrap());
937        assert_eq!(depth.bids[0].size, Decimal::from_str("0.2125").unwrap());
938        assert_eq!(depth.offset, 1_558_300);
939        assert_eq!(depth.nonce, 9_182_390_020);
940    }
941
942    #[rstest]
943    fn test_order_book_depth_deserializes_null_sides_as_empty() {
944        let depth: LighterOrderBookDepth =
945            serde_json::from_str(HTTP_ORDER_BOOK_DEPTH_NULL).unwrap();
946
947        assert_eq!(depth.code, 200);
948        assert!(depth.asks.is_empty());
949        assert!(depth.bids.is_empty());
950        assert_eq!(depth.offset, 1);
951        assert_eq!(depth.nonce, 0);
952    }
953
954    #[rstest]
955    fn test_orders_deserializes_live_shape() {
956        let orders: LighterOrders = serde_json::from_str(HTTP_ORDERS).unwrap();
957
958        assert_eq!(orders.next_cursor.as_deref(), Some("cursor-1"));
959        assert_eq!(orders.orders.len(), 1);
960        assert_eq!(orders.orders[0].order_type, LighterOrderKind::Limit);
961        assert_eq!(
962            orders.orders[0].time_in_force,
963            LighterOrderTimeInForce::GoodTillTime,
964        );
965        assert_eq!(orders.orders[0].status, LighterOrderStatus::Open);
966        assert_eq!(orders.orders[0].trigger_status, LighterTriggerStatus::Na);
967        assert_eq!(orders.orders[0].side, Some(LighterOrderSide::Sell));
968        assert!(orders.orders[0].is_ask);
969    }
970
971    #[rstest]
972    fn test_orders_allows_empty_side_with_is_ask() {
973        let mut value: serde_json::Value = serde_json::from_str(HTTP_ORDERS).unwrap();
974        value["orders"][0]["side"] = serde_json::Value::String(String::new());
975
976        let orders: LighterOrders = serde_json::from_value(value).unwrap();
977
978        assert_eq!(orders.orders[0].side, None);
979        assert!(orders.orders[0].is_ask);
980    }
981
982    #[rstest]
983    #[case::funding_true_rfq_false(Some(true), false)]
984    #[case::funding_false_rfq_true(Some(false), true)]
985    #[case::funding_absent_rfq_true(None, true)]
986    #[case::funding_absent_rfq_false(None, false)]
987    fn test_market_config_optional_funding_flag(
988        #[case] funding_fee_discounts_enabled: Option<bool>,
989        #[case] rfq_enabled: bool,
990    ) {
991        let mut payload: serde_json::Value = serde_json::from_str(HTTP_ORDER_BOOK_DETAILS).unwrap();
992        let config = &mut payload["order_book_details"][0]["market_config"];
993        config["rfq_enabled"] = serde_json::json!(rfq_enabled);
994        match funding_fee_discounts_enabled {
995            Some(enabled) => config["funding_fee_discounts_enabled"] = serde_json::json!(enabled),
996            None => {
997                config
998                    .as_object_mut()
999                    .unwrap()
1000                    .remove("funding_fee_discounts_enabled");
1001            }
1002        }
1003
1004        let expected = LighterMarketConfig {
1005            market_margin_mode: LighterPositionMarginMode::Cross,
1006            insurance_fund_account_index: 281_474_976_710_655,
1007            liquidation_mode: 0,
1008            force_reduce_only: false,
1009            trading_hours: String::new(),
1010            funding_fee_discounts_enabled,
1011            hidden: false,
1012            rfq_enabled,
1013        };
1014
1015        let config: LighterMarketConfig =
1016            serde_json::from_value(payload["order_book_details"][0]["market_config"].clone())
1017                .unwrap();
1018        let details: LighterOrderBookDetails = serde_json::from_value(payload).unwrap();
1019
1020        assert_eq!(config, expected);
1021        assert_eq!(details.order_book_details.len(), 1);
1022        assert_eq!(details.order_book_details[0].market_config, expected);
1023        assert_eq!(
1024            serde_json::to_value(&expected)
1025                .unwrap()
1026                .get("funding_fee_discounts_enabled"),
1027            funding_fee_discounts_enabled
1028                .map(|enabled| serde_json::json!(enabled))
1029                .as_ref(),
1030        );
1031    }
1032
1033    #[rstest]
1034    fn test_market_config_requires_rfq_enabled() {
1035        let mut payload: serde_json::Value = serde_json::from_str(HTTP_ORDER_BOOK_DETAILS).unwrap();
1036        payload["order_book_details"][0]["market_config"]
1037            .as_object_mut()
1038            .unwrap()
1039            .remove("rfq_enabled");
1040
1041        let err = serde_json::from_value::<LighterOrderBookDetails>(payload).unwrap_err();
1042
1043        assert!(err.to_string().contains("missing field `rfq_enabled`"));
1044    }
1045
1046    #[rstest]
1047    #[case::binary_options(
1048        "binary_options",
1049        "waiting-for-settlement",
1050        LighterProductType::BinaryOptions,
1051        LighterMarketStatus::WaitingForSettlement
1052    )]
1053    #[case::in_settlement(
1054        "binary_options",
1055        "in-settlement",
1056        LighterProductType::BinaryOptions,
1057        LighterMarketStatus::InSettlement
1058    )]
1059    #[case::settled(
1060        "binary_options",
1061        "settled",
1062        LighterProductType::BinaryOptions,
1063        LighterMarketStatus::Settled
1064    )]
1065    #[case::unfamiliar(
1066        "future_kind",
1067        "future-status",
1068        LighterProductType::Other,
1069        LighterMarketStatus::Unknown
1070    )]
1071    fn test_order_books_keeps_siblings_of_other_market_classifications(
1072        #[case] market_type: &str,
1073        #[case] status: &str,
1074        #[case] expected_market_type: LighterProductType,
1075        #[case] expected_status: LighterMarketStatus,
1076    ) {
1077        let mut payload: serde_json::Value = serde_json::from_str(HTTP_ORDER_BOOKS).unwrap();
1078        let mut unfamiliar = payload["order_books"][0].clone();
1079        unfamiliar["symbol"] = serde_json::json!("BTC-UPDOWN");
1080        unfamiliar["market_id"] = serde_json::json!(7001);
1081        unfamiliar["market_type"] = serde_json::json!(market_type);
1082        unfamiliar["status"] = serde_json::json!(status);
1083        payload["order_books"]
1084            .as_array_mut()
1085            .unwrap()
1086            .insert(0, unfamiliar);
1087        let healthy: LighterOrderBooks = serde_json::from_str(HTTP_ORDER_BOOKS).unwrap();
1088
1089        let order_books: LighterOrderBooks = serde_json::from_value(payload).unwrap();
1090
1091        assert_eq!(order_books.order_books.len(), 2);
1092        assert_eq!(order_books.order_books[0].symbol, Ustr::from("BTC-UPDOWN"));
1093        assert_eq!(order_books.order_books[0].market_id, 7001);
1094        assert_eq!(order_books.order_books[0].market_type, expected_market_type);
1095        assert_eq!(order_books.order_books[0].status, expected_status);
1096        assert_eq!(order_books.order_books[1], healthy.order_books[0]);
1097    }
1098
1099    #[rstest]
1100    fn test_orders_keeps_siblings_of_unfamiliar_classifications() {
1101        let mut payload: serde_json::Value = serde_json::from_str(HTTP_ORDERS).unwrap();
1102        let mut unfamiliar = payload["orders"][0].clone();
1103        unfamiliar["order_id"] = serde_json::json!("900");
1104        unfamiliar["order_index"] = serde_json::json!(900);
1105        unfamiliar["type"] = serde_json::json!("future-type");
1106        unfamiliar["time_in_force"] = serde_json::json!("future-tif");
1107        unfamiliar["status"] = serde_json::json!("future-status");
1108        unfamiliar["trigger_status"] = serde_json::json!("future-trigger");
1109        payload["orders"]
1110            .as_array_mut()
1111            .unwrap()
1112            .insert(0, unfamiliar);
1113        let healthy: LighterOrders = serde_json::from_str(HTTP_ORDERS).unwrap();
1114
1115        let orders: LighterOrders = serde_json::from_value(payload).unwrap();
1116
1117        assert_eq!(orders.orders.len(), 2);
1118        assert_eq!(orders.orders[0].order_id, "900");
1119        assert_eq!(orders.orders[0].order_type, LighterOrderKind::Other);
1120        assert_eq!(
1121            orders.orders[0].time_in_force,
1122            LighterOrderTimeInForce::Unknown
1123        );
1124        assert_eq!(orders.orders[0].status, LighterOrderStatus::Unknown);
1125        assert_eq!(
1126            orders.orders[0].trigger_status,
1127            LighterTriggerStatus::Unknown
1128        );
1129        assert_eq!(
1130            orders.orders[0].filled_base_amount,
1131            healthy.orders[0].filled_base_amount
1132        );
1133        assert_eq!(orders.orders[1], healthy.orders[0]);
1134    }
1135
1136    #[rstest]
1137    fn test_trades_keeps_fill_data_of_unfamiliar_trade_type() {
1138        let mut payload: serde_json::Value = serde_json::from_str(HTTP_RECENT_TRADES).unwrap();
1139        let mut unfamiliar = payload["trades"][0].clone();
1140        unfamiliar["trade_id"] = serde_json::json!(900);
1141        unfamiliar["trade_id_str"] = serde_json::json!("900");
1142        unfamiliar["type"] = serde_json::json!("future-trade");
1143        payload["trades"]
1144            .as_array_mut()
1145            .unwrap()
1146            .insert(0, unfamiliar);
1147        let healthy: LighterTrades = serde_json::from_str(HTTP_RECENT_TRADES).unwrap();
1148        let mut expected = healthy.trades[0].clone();
1149        expected.trade_id = 900;
1150        expected.trade_id_str = Some("900".to_string());
1151        expected.trade_type = LighterTradeType::Other;
1152
1153        let trades: LighterTrades = serde_json::from_value(payload).unwrap();
1154
1155        assert_eq!(trades.trades.len(), 2);
1156        assert_eq!(trades.trades[0], expected);
1157        assert_eq!(trades.trades[1], healthy.trades[0]);
1158    }
1159}