Skip to main content

nautilus_lighter/http/
client.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//! Raw and domain HTTP clients for Lighter REST endpoints.
17
18use std::{collections::HashMap, sync::Arc, time::Duration};
19
20use jiff::Timestamp;
21use nautilus_core::{
22    AtomicTime, UnixNanos, string::secret::SecretString, time::get_atomic_clock_realtime,
23};
24use nautilus_model::{
25    data::{Bar, BarType, FundingRateUpdate, OrderBookDeltas, TradeTick},
26    identifiers::InstrumentId,
27    instruments::{Instrument, InstrumentAny},
28};
29use nautilus_network::{
30    http::{
31        HttpClient, HttpRedirectPolicy, HttpResponse, Method, create_standard_nautilus_headers,
32        parse_retry_after,
33    },
34    ratelimiter::quota::Quota,
35    retry::{RetryManager, create_http_retry_manager},
36};
37use rust_decimal::Decimal;
38use serde::{Serialize, de::DeserializeOwned};
39use url::form_urlencoded;
40use zeroize::Zeroizing;
41
42use crate::{
43    common::{
44        enums::{
45            LighterCandleResolution, LighterEnvironment, LighterFundingResolution,
46            LighterMarketStatus,
47        },
48        rate_limit::{
49            LIGHTER_REST_BUCKET, LIGHTER_REST_QUOTA, LighterTxRateLimiter, await_tx_quota,
50        },
51        symbol::MarketRegistry,
52        urls::lighter_http_base_url,
53    },
54    http::{
55        error::{
56            LighterHttpError, LighterHttpResult, create_lighter_http_timeout_error,
57            should_retry_lighter_http_error,
58        },
59        models::{
60            LighterAccountDetail, LighterAccountsResponse, LighterCandle, LighterCandles,
61            LighterFundings, LighterMakerOnlyApiKeys, LighterNextNonce, LighterOrderBookDetails,
62            LighterOrderBookOrders, LighterOrderBooks, LighterOrders, LighterResultCode,
63            LighterSendTxBatchRequest, LighterSendTxBatchResponse, LighterSendTxRequest,
64            LighterSendTxResponse, LighterTrade, LighterTrades, LighterTx,
65        },
66        parse::{
67            parse_candle_bar, parse_funding_rate_update,
68            parse_order_book_details_instruments_with_status, parse_order_book_snapshot,
69            parse_trade_tick, register_order_books,
70        },
71        query::{
72            LighterAccountActiveOrdersQuery, LighterAccountInactiveOrdersQuery,
73            LighterAccountLookup, LighterAccountOrdersQuery, LighterAccountQuery,
74            LighterCandlesQuery, LighterFundingsQuery, LighterMakerOnlyApiKeysQuery,
75            LighterNextNonceQuery, LighterOrderBookDetailsQuery, LighterOrderBookOrdersQuery,
76            LighterOrderBooksQuery, LighterRecentTradesQuery, LighterTradesQuery, LighterTxLookup,
77            LighterTxQuery, validate_client_order_indexes,
78        },
79    },
80};
81
82const API_V1: &str = "/api/v1";
83const ENDPOINT_ACCOUNT: &str = "/api/v1/account";
84const ENDPOINT_ACCOUNT_ACTIVE_ORDERS: &str = "/api/v1/accountActiveOrders";
85const ENDPOINT_ACCOUNT_INACTIVE_ORDERS: &str = "/api/v1/accountInactiveOrders";
86const ENDPOINT_ACCOUNT_ORDERS: &str = "/api/v1/accountOrders";
87const ENDPOINT_CANDLES: &str = "/api/v1/candles";
88const ENDPOINT_FUNDINGS: &str = "/api/v1/fundings";
89const ENDPOINT_MAKER_ONLY_API_KEYS: &str = "/api/v1/getMakerOnlyApiKeys";
90const ENDPOINT_NEXT_NONCE: &str = "/api/v1/nextNonce";
91const ENDPOINT_ORDER_BOOK_DETAILS: &str = "/api/v1/orderBookDetails";
92const ENDPOINT_ORDER_BOOK_ORDERS: &str = "/api/v1/orderBookOrders";
93const ENDPOINT_ORDER_BOOKS: &str = "/api/v1/orderBooks";
94const ENDPOINT_RECENT_TRADES: &str = "/api/v1/recentTrades";
95const ENDPOINT_REFERRAL_USE: &str = "/api/v1/referral/use";
96const ENDPOINT_SEND_TX: &str = "/api/v1/sendTx";
97const ENDPOINT_SEND_TX_BATCH: &str = "/api/v1/sendTxBatch";
98const ENDPOINT_TRADES: &str = "/api/v1/trades";
99const ENDPOINT_TX: &str = "/api/v1/tx";
100const HEADER_AUTHORIZATION: &str = "authorization";
101const HEADER_RETRY_AFTER: &str = "retry-after";
102const MULTIPART_BOUNDARY: &str = "nautilus-lighter-form-boundary";
103
104/// Maximum page size accepted by Lighter REST list endpoints (`/api/v1/trades`,
105/// `/api/v1/accountInactiveOrders`). Values above this trigger `20001 invalid
106/// param` from the venue, so reconciliation paginates at this cap and follows
107/// `next_cursor` until the response is empty.
108pub const LIGHTER_REST_PAGE_SIZE: u16 = 100;
109pub const LIGHTER_CANDLES_MAX_LIMIT: u16 = 500;
110
111/// Maximum rows returned per `/api/v1/fundings` call (the venue per-call cap).
112pub const LIGHTER_FUNDINGS_MAX_LIMIT: u16 = 100;
113
114const DEFAULT_BARS_LIMIT: usize = LIGHTER_CANDLES_MAX_LIMIT as usize;
115const DEFAULT_FUNDING_RATES_LIMIT: usize = 100;
116const MAX_BAR_REQUEST_PAGES: usize = 500;
117const MAX_FUNDING_REQUEST_PAGES: usize = 500;
118
119trait LighterResponseCheck {
120    fn response_code(&self) -> i32;
121    fn response_message(&self) -> Option<&str>;
122}
123
124macro_rules! impl_lighter_response_check {
125    ($($ty:ty),+ $(,)?) => {
126        $(
127            impl LighterResponseCheck for $ty {
128                fn response_code(&self) -> i32 {
129                    self.code
130                }
131
132                fn response_message(&self) -> Option<&str> {
133                    self.message.as_deref()
134                }
135            }
136        )+
137    };
138}
139
140impl_lighter_response_check!(
141    LighterAccountsResponse,
142    LighterCandles,
143    LighterFundings,
144    LighterMakerOnlyApiKeys,
145    LighterNextNonce,
146    LighterOrderBookDetails,
147    LighterOrderBookOrders,
148    LighterOrderBooks,
149    LighterOrders,
150    LighterResultCode,
151    LighterSendTxBatchResponse,
152    LighterSendTxResponse,
153    LighterTrades,
154    LighterTx,
155);
156
157/// Raw HTTP client for Lighter REST API operations.
158///
159/// This client owns the transport, base URL, default headers, and rate limit. Methods map directly
160/// to venue endpoints and return venue response models without converting to Nautilus domain types.
161#[derive(Clone, Debug)]
162pub struct LighterRawHttpClient {
163    base_url: String,
164    environment: LighterEnvironment,
165    client: HttpClient,
166    retry_manager: RetryManager<LighterHttpError>,
167    tx_rate_limiter: Option<Arc<LighterTxRateLimiter>>,
168}
169
170impl Default for LighterRawHttpClient {
171    fn default() -> Self {
172        Self::new(LighterEnvironment::Mainnet, None, 60, None)
173            .expect("failed to create default Lighter raw HTTP client")
174    }
175}
176
177impl LighterRawHttpClient {
178    /// Creates a new [`LighterRawHttpClient`].
179    ///
180    /// # Errors
181    ///
182    /// Returns an error if the underlying HTTP client cannot be created.
183    pub fn new(
184        environment: LighterEnvironment,
185        base_url: Option<String>,
186        timeout_secs: u64,
187        proxy_url: Option<String>,
188    ) -> LighterHttpResult<Self> {
189        Self::new_with_quotas(
190            environment,
191            base_url,
192            timeout_secs,
193            proxy_url,
194            *LIGHTER_REST_QUOTA,
195            None,
196        )
197    }
198
199    /// Creates a new [`LighterRawHttpClient`] with an explicit read quota and an
200    /// optional shared transaction limiter.
201    ///
202    /// `default_quota` governs the REST read bucket ([`LIGHTER_REST_BUCKET`]),
203    /// resolved from the client's configured `rest_quota_per_min` (detected tier
204    /// only logs hints). `tx_rate_limiter` paces `sendTx` / `sendTxBatch`; the
205    /// execution client shares one limiter across this and the WebSocket
206    /// `sendTx` path so their combined rate honors the single venue tx bucket.
207    /// The data client passes `None` (it sends no transactions).
208    ///
209    /// # Errors
210    ///
211    /// Returns an error if the underlying HTTP client cannot be created.
212    pub fn new_with_quotas(
213        environment: LighterEnvironment,
214        base_url: Option<String>,
215        timeout_secs: u64,
216        proxy_url: Option<String>,
217        default_quota: Quota,
218        tx_rate_limiter: Option<Arc<LighterTxRateLimiter>>,
219    ) -> LighterHttpResult<Self> {
220        let base_url = base_url
221            .unwrap_or_else(|| lighter_http_base_url(environment).to_string())
222            .trim_end_matches('/')
223            .to_string();
224
225        Ok(Self {
226            base_url,
227            environment,
228            client: HttpClient::builder()
229                .redirect_policy(HttpRedirectPolicy::Reject)
230                .header_keys(vec![HEADER_RETRY_AFTER.to_string()])
231                .headers(Self::default_headers())
232                .default_quota(default_quota)
233                .timeout_secs(timeout_secs)
234                .maybe_proxy_url(proxy_url)
235                .build()?,
236            retry_manager: create_http_retry_manager(),
237            tx_rate_limiter,
238        })
239    }
240
241    /// Returns the configured REST base URL.
242    #[must_use]
243    pub fn base_url(&self) -> &str {
244        self.base_url.as_str()
245    }
246
247    /// Returns the configured Lighter environment.
248    #[must_use]
249    pub const fn environment(&self) -> LighterEnvironment {
250        self.environment
251    }
252
253    /// Overrides the REST base URL. Intended for mock-server tests.
254    pub fn set_base_url(&mut self, base_url: &str) {
255        self.base_url = base_url.trim_end_matches('/').to_string();
256    }
257
258    /// Overrides the retry manager. Intended for mock-server tests that need
259    /// shorter backoff than [`create_http_retry_manager`] produces.
260    pub fn set_retry_manager(&mut self, retry_manager: RetryManager<LighterHttpError>) {
261        self.retry_manager = retry_manager;
262    }
263
264    /// Calls `GET /api/v1/orderBooks`.
265    ///
266    /// # Errors
267    ///
268    /// Returns an error if the request fails or the response is invalid.
269    pub async fn get_order_books(
270        &self,
271        query: &LighterOrderBooksQuery,
272    ) -> LighterHttpResult<LighterOrderBooks> {
273        self.send_get_request(ENDPOINT_ORDER_BOOKS, Some(query))
274            .await
275    }
276
277    /// Calls `GET /api/v1/orderBookDetails`.
278    ///
279    /// # Errors
280    ///
281    /// Returns an error if the request fails or the response is invalid.
282    pub async fn get_order_book_details(
283        &self,
284        query: &LighterOrderBookDetailsQuery,
285    ) -> LighterHttpResult<LighterOrderBookDetails> {
286        self.send_get_request(ENDPOINT_ORDER_BOOK_DETAILS, Some(query))
287            .await
288    }
289
290    /// Calls `GET /api/v1/orderBookOrders`.
291    ///
292    /// # Errors
293    ///
294    /// Returns an error if the request fails or the response is invalid.
295    pub async fn get_order_book_orders(
296        &self,
297        query: &LighterOrderBookOrdersQuery,
298    ) -> LighterHttpResult<LighterOrderBookOrders> {
299        self.send_get_request(ENDPOINT_ORDER_BOOK_ORDERS, Some(query))
300            .await
301    }
302
303    /// Calls `GET /api/v1/recentTrades`.
304    ///
305    /// # Errors
306    ///
307    /// Returns an error if the request fails or the response is invalid.
308    pub async fn get_recent_trades(
309        &self,
310        query: &LighterRecentTradesQuery,
311    ) -> LighterHttpResult<LighterTrades> {
312        self.send_get_request(ENDPOINT_RECENT_TRADES, Some(query))
313            .await
314    }
315
316    /// Calls `GET /api/v1/trades`.
317    ///
318    /// # Errors
319    ///
320    /// Returns an error if the request fails or the response is invalid.
321    pub async fn get_trades(&self, query: &LighterTradesQuery) -> LighterHttpResult<LighterTrades> {
322        let headers = authorization_headers(query.authorization.as_ref(), query.auth.as_ref());
323        self.send_get_request_with_headers(ENDPOINT_TRADES, Some(query), headers)
324            .await
325    }
326
327    /// Calls `GET /api/v1/candles`.
328    ///
329    /// # Errors
330    ///
331    /// Returns an error if the request fails or the response is invalid.
332    pub async fn get_candles(
333        &self,
334        query: &LighterCandlesQuery,
335    ) -> LighterHttpResult<LighterCandles> {
336        self.send_get_request(ENDPOINT_CANDLES, Some(query)).await
337    }
338
339    /// Calls `GET /api/v1/fundings`.
340    ///
341    /// # Errors
342    ///
343    /// Returns an error if the request fails or the response is invalid.
344    pub async fn get_fundings(
345        &self,
346        query: &LighterFundingsQuery,
347    ) -> LighterHttpResult<LighterFundings> {
348        self.send_get_request(ENDPOINT_FUNDINGS, Some(query)).await
349    }
350
351    /// Calls `GET /api/v1/account`.
352    ///
353    /// # Errors
354    ///
355    /// Returns an error if the request fails or the response is invalid.
356    pub async fn get_account(
357        &self,
358        query: &LighterAccountQuery,
359    ) -> LighterHttpResult<LighterAccountsResponse> {
360        self.send_get_request(ENDPOINT_ACCOUNT, Some(query)).await
361    }
362
363    /// Calls `GET /api/v1/accountActiveOrders`.
364    ///
365    /// # Errors
366    ///
367    /// Returns an error if the request fails or the response is invalid.
368    pub async fn get_account_active_orders(
369        &self,
370        query: &LighterAccountActiveOrdersQuery,
371    ) -> LighterHttpResult<LighterOrders> {
372        let headers = authorization_headers(query.authorization.as_ref(), query.auth.as_ref());
373        self.send_get_request_with_headers(ENDPOINT_ACCOUNT_ACTIVE_ORDERS, Some(query), headers)
374            .await
375    }
376
377    /// Calls `GET /api/v1/accountInactiveOrders`.
378    ///
379    /// # Errors
380    ///
381    /// Returns an error if the request fails or the response is invalid.
382    pub async fn get_account_inactive_orders(
383        &self,
384        query: &LighterAccountInactiveOrdersQuery,
385    ) -> LighterHttpResult<LighterOrders> {
386        let headers = authorization_headers(query.authorization.as_ref(), query.auth.as_ref());
387        self.send_get_request_with_headers(ENDPOINT_ACCOUNT_INACTIVE_ORDERS, Some(query), headers)
388            .await
389    }
390
391    /// Calls `GET /api/v1/accountOrders`.
392    ///
393    /// # Errors
394    ///
395    /// Returns an error if the request fails or the response is invalid.
396    pub async fn get_account_orders(
397        &self,
398        query: &LighterAccountOrdersQuery,
399    ) -> LighterHttpResult<LighterOrders> {
400        validate_client_order_indexes(&query.client_order_indexes)
401            .map_err(LighterHttpError::Parse)?;
402        let headers = authorization_headers(query.authorization.as_ref(), query.auth.as_ref());
403        self.send_get_request_with_headers(ENDPOINT_ACCOUNT_ORDERS, Some(query), headers)
404            .await
405    }
406
407    /// Calls `GET /api/v1/nextNonce`.
408    ///
409    /// # Errors
410    ///
411    /// Returns an error if the request fails or the response is invalid.
412    pub async fn get_next_nonce(
413        &self,
414        query: &LighterNextNonceQuery,
415    ) -> LighterHttpResult<LighterNextNonce> {
416        self.send_get_request(ENDPOINT_NEXT_NONCE, Some(query))
417            .await
418    }
419
420    /// Calls `GET /api/v1/tx`.
421    ///
422    /// # Errors
423    ///
424    /// Returns an error if the request fails or the response is invalid.
425    pub async fn get_tx(&self, query: &LighterTxQuery) -> LighterHttpResult<LighterTx> {
426        self.send_get_request(ENDPOINT_TX, Some(query)).await
427    }
428
429    /// Calls `GET /api/v1/getMakerOnlyApiKeys`.
430    ///
431    /// # Errors
432    ///
433    /// Returns an error if the request fails or the response is invalid.
434    pub async fn get_maker_only_api_keys(
435        &self,
436        query: &LighterMakerOnlyApiKeysQuery,
437    ) -> LighterHttpResult<LighterMakerOnlyApiKeys> {
438        let params = LighterMakerOnlyApiKeysParams {
439            account_index: query.account_index,
440        };
441
442        let headers = authorization_headers(query.authorization.as_ref(), query.auth.as_ref());
443        self.send_get_request_with_headers(ENDPOINT_MAKER_ONLY_API_KEYS, Some(&params), headers)
444            .await
445    }
446
447    /// Calls `POST /api/v1/referral/use`.
448    ///
449    /// # Errors
450    ///
451    /// Returns an error if the request fails or the response is invalid.
452    pub async fn use_referral(
453        &self,
454        l1_address: &str,
455        referral_code: &str,
456        auth_token: &str,
457    ) -> LighterHttpResult<LighterResultCode> {
458        let fields = [("l1_address", l1_address), ("referral_code", referral_code)];
459        self.send_post_urlencoded(ENDPOINT_REFERRAL_USE, &fields, auth_token)
460            .await
461    }
462
463    /// Calls `POST /api/v1/sendTx`.
464    ///
465    /// # Errors
466    ///
467    /// Returns an error if the request fails or the response is invalid.
468    pub async fn send_tx(
469        &self,
470        request: &LighterSendTxRequest,
471    ) -> LighterHttpResult<LighterSendTxResponse> {
472        let fields = request.form_fields();
473        self.send_post_form(ENDPOINT_SEND_TX, &fields).await
474    }
475
476    /// Calls `POST /api/v1/sendTxBatch`.
477    ///
478    /// # Errors
479    ///
480    /// Returns an error if the request fails or the response is invalid.
481    pub async fn send_tx_batch(
482        &self,
483        request: &LighterSendTxBatchRequest,
484    ) -> LighterHttpResult<LighterSendTxBatchResponse> {
485        let fields = request.form_fields();
486        self.send_post_form(ENDPOINT_SEND_TX_BATCH, &fields).await
487    }
488
489    async fn send_get_request<T, P>(
490        &self,
491        endpoint: &str,
492        params: Option<&P>,
493    ) -> LighterHttpResult<T>
494    where
495        T: DeserializeOwned + LighterResponseCheck,
496        P: Serialize,
497    {
498        self.send_get_request_with_headers(endpoint, params, None)
499            .await
500    }
501
502    async fn send_get_request_with_headers<T, P>(
503        &self,
504        endpoint: &str,
505        params: Option<&P>,
506        headers: Option<HashMap<String, String>>,
507    ) -> LighterHttpResult<T>
508    where
509        T: DeserializeOwned + LighterResponseCheck,
510        P: Serialize,
511    {
512        let url = self.url(endpoint);
513        let rate_limit_keys = Self::rate_limit_keys(endpoint);
514        self.retry_manager
515            .invocation(
516                endpoint,
517                || {
518                    let url = url.clone();
519                    let rate_limit_keys = rate_limit_keys.clone();
520                    let headers = headers.clone();
521
522                    async move {
523                        let response = self
524                            .client
525                            .request_with_params(
526                                Method::GET,
527                                url,
528                                params,
529                                headers,
530                                None,
531                                None,
532                                Some(rate_limit_keys),
533                            )
534                            .await?;
535                        Self::parse_response(&response)
536                    }
537                },
538                should_retry_lighter_http_error,
539                |e| create_lighter_http_timeout_error(e.to_string()),
540            )
541            .retry_delay(&LighterHttpError::retry_after)
542            .execute()
543            .await
544    }
545
546    // Single-shot: sendTx / sendTxBatch carry a signed nonce; transport-layer
547    // retry could double-submit if the original landed and only the ack was lost.
548    async fn send_post_form<T>(
549        &self,
550        endpoint: &str,
551        fields: &[(&str, String)],
552    ) -> LighterHttpResult<T>
553    where
554        T: DeserializeOwned + LighterResponseCheck,
555    {
556        // send_post_form only carries sendTx / sendTxBatch. With a shared tx
557        // limiter (execution client) pace on it and pass no REST keys, so the
558        // read quota does not also cap transactions. Without one (e.g. the
559        // integrator-revoke utility) fall back to the internal REST limiter so
560        // the request is still bounded rather than unthrottled.
561        let rate_keys = match &self.tx_rate_limiter {
562            Some(limiter) => {
563                await_tx_quota(limiter).await;
564                None
565            }
566            None => Some(Self::rate_limit_keys(endpoint)),
567        };
568
569        let response = self
570            .client
571            .request(
572                Method::POST,
573                self.url(endpoint),
574                None,
575                Some(multipart_headers()),
576                Some(multipart_form_bytes(fields)),
577                None,
578                rate_keys,
579            )
580            .await?;
581
582        Self::parse_response(&response)
583    }
584
585    // Single-shot because referral use changes account-level state and the API
586    // does not document idempotency for a response lost after submission.
587    async fn send_post_urlencoded<T>(
588        &self,
589        endpoint: &str,
590        fields: &[(&str, &str)],
591        auth_token: &str,
592    ) -> LighterHttpResult<T>
593    where
594        T: DeserializeOwned + LighterResponseCheck,
595    {
596        let mut serializer = form_urlencoded::Serializer::new(String::new());
597        serializer.extend_pairs(fields.iter().copied());
598        let body = serializer.finish().into_bytes();
599
600        let headers = HashMap::from([
601            ("Accept".to_string(), "application/json".to_string()),
602            (
603                "Content-Type".to_string(),
604                "application/x-www-form-urlencoded".to_string(),
605            ),
606            (HEADER_AUTHORIZATION.to_string(), auth_token.to_string()),
607        ]);
608
609        let response = self
610            .client
611            .request(
612                Method::POST,
613                self.url(endpoint),
614                None,
615                Some(headers),
616                Some(body),
617                None,
618                Some(Self::rate_limit_keys(endpoint)),
619            )
620            .await?;
621
622        Self::parse_response(&response)
623    }
624
625    fn parse_response<T>(response: &HttpResponse) -> LighterHttpResult<T>
626    where
627        T: DeserializeOwned + LighterResponseCheck,
628    {
629        let retry_after = response.headers.get(HEADER_RETRY_AFTER).and_then(|value| {
630            let now = get_atomic_clock_realtime().get_time_ns().to_datetime_utc();
631            parse_retry_after(value, now)
632        });
633
634        if !response.status.is_success() {
635            let status = response.status.as_u16();
636            let body = String::from_utf8_lossy(&response.body).to_string();
637
638            // Status-first: a `{code,message}` body must not override the
639            // retry decision for 5xx / 429.
640            if status >= 500 {
641                return Err(LighterHttpError::Http {
642                    status,
643                    body,
644                    retry_after,
645                });
646            }
647
648            // HTTP 405 is a Lighter rate-limit status like 429 per the docs, not a method error
649            if status == 429 || status == 405 {
650                return Err(LighterHttpError::RateLimit {
651                    message: body,
652                    retry_after,
653                });
654            }
655
656            if let Ok(result) = serde_json::from_slice::<LighterResultCode>(&response.body)
657                && result.code != 200
658            {
659                Self::result_code_error(
660                    result.code,
661                    result.message.as_deref(),
662                    "HTTP error",
663                    retry_after,
664                )?;
665            }
666
667            return Err(LighterHttpError::Http {
668                status,
669                body,
670                retry_after,
671            });
672        }
673
674        let payload: T = match serde_json::from_slice(&response.body) {
675            Ok(payload) => payload,
676            Err(payload_error) => {
677                if let Ok(result) = serde_json::from_slice::<LighterResultCode>(&response.body) {
678                    Self::check_response(&result, retry_after)?;
679                }
680                return Err(payload_error.into());
681            }
682        };
683
684        Self::check_response(&payload, retry_after)?;
685        Ok(payload)
686    }
687
688    fn check_response<T: LighterResponseCheck>(
689        payload: &T,
690        retry_after: Option<Duration>,
691    ) -> LighterHttpResult<()> {
692        Self::result_code_error(
693            payload.response_code(),
694            payload.response_message(),
695            "Lighter request failed",
696            retry_after,
697        )
698    }
699
700    fn result_code_error(
701        code: i32,
702        message: Option<&str>,
703        default_message: &str,
704        retry_after: Option<Duration>,
705    ) -> LighterHttpResult<()> {
706        match code {
707            200 => Ok(()),
708            405 | 429 => Err(LighterHttpError::RateLimit {
709                message: message.unwrap_or("Lighter rate limit exceeded").to_string(),
710                retry_after,
711            }),
712            code => Err(venue_error(code, message, default_message)),
713        }
714    }
715
716    fn url(&self, endpoint: &str) -> String {
717        format!("{}{}", self.base_url, endpoint)
718    }
719
720    fn rate_limit_keys(endpoint: &str) -> Vec<String> {
721        let route = endpoint.strip_prefix(API_V1).unwrap_or(endpoint);
722        vec![
723            LIGHTER_REST_BUCKET.to_string(),
724            format!("lighter:{}", route.trim_start_matches('/')),
725        ]
726    }
727
728    fn default_headers() -> HashMap<String, String> {
729        create_standard_nautilus_headers().into_iter().collect()
730    }
731}
732
733#[derive(Serialize)]
734struct LighterMakerOnlyApiKeysParams {
735    account_index: i64,
736}
737
738fn authorization_headers(
739    authorization: Option<&SecretString>,
740    auth: Option<&SecretString>,
741) -> Option<HashMap<String, String>> {
742    authorization.or(auth).map(|token| {
743        HashMap::from([(
744            HEADER_AUTHORIZATION.to_string(),
745            token.expose_secret().to_owned(),
746        )])
747    })
748}
749
750fn multipart_headers() -> HashMap<String, String> {
751    HashMap::from([
752        ("Accept".to_string(), "application/json".to_string()),
753        (
754            "Content-Type".to_string(),
755            format!("multipart/form-data; boundary={MULTIPART_BOUNDARY}"),
756        ),
757    ])
758}
759
760fn multipart_form_bytes(fields: &[(&str, String)]) -> Vec<u8> {
761    let mut body = String::new();
762    for (name, value) in fields {
763        body.push_str("--");
764        body.push_str(MULTIPART_BOUNDARY);
765        body.push_str("\r\nContent-Disposition: form-data; name=\"");
766        body.push_str(name);
767        body.push_str("\"\r\n\r\n");
768        body.push_str(value);
769        body.push_str("\r\n");
770    }
771    body.push_str("--");
772    body.push_str(MULTIPART_BOUNDARY);
773    body.push_str("--\r\n");
774    body.into_bytes()
775}
776
777/// Domain HTTP client for Lighter REST operations.
778///
779/// This client wraps [`LighterRawHttpClient`] and converts selected endpoint responses into
780/// Nautilus domain data. Market metadata calls also populate the shared [`MarketRegistry`].
781#[derive(Clone, Debug)]
782pub struct LighterHttpClient {
783    pub(crate) inner: Arc<LighterRawHttpClient>,
784    market_registry: Arc<MarketRegistry>,
785    clock: &'static AtomicTime,
786}
787
788impl Default for LighterHttpClient {
789    fn default() -> Self {
790        Self::new(LighterEnvironment::Mainnet, None, 60, None)
791            .expect("failed to create default Lighter HTTP client")
792    }
793}
794
795impl LighterHttpClient {
796    /// Creates a new [`LighterHttpClient`].
797    ///
798    /// # Errors
799    ///
800    /// Returns an error if the underlying raw HTTP client cannot be created.
801    pub fn new(
802        environment: LighterEnvironment,
803        base_url: Option<String>,
804        timeout_secs: u64,
805        proxy_url: Option<String>,
806    ) -> LighterHttpResult<Self> {
807        let raw_client = LighterRawHttpClient::new(environment, base_url, timeout_secs, proxy_url)?;
808        Ok(Self::from_raw(raw_client))
809    }
810
811    /// Wraps an existing raw HTTP client.
812    #[must_use]
813    pub fn from_raw(raw_client: LighterRawHttpClient) -> Self {
814        Self::from_raw_with_registry(raw_client, Arc::new(MarketRegistry::new()))
815    }
816
817    /// Wraps an existing raw HTTP client and shared market registry.
818    #[must_use]
819    pub fn from_raw_with_registry(
820        raw_client: LighterRawHttpClient,
821        market_registry: Arc<MarketRegistry>,
822    ) -> Self {
823        Self {
824            inner: Arc::new(raw_client),
825            market_registry,
826            clock: get_atomic_clock_realtime(),
827        }
828    }
829
830    /// Returns the configured REST base URL.
831    #[must_use]
832    pub fn base_url(&self) -> &str {
833        self.inner.base_url()
834    }
835
836    /// Returns the configured Lighter environment.
837    #[must_use]
838    pub fn environment(&self) -> LighterEnvironment {
839        self.inner.environment()
840    }
841
842    /// Returns the shared market registry used by this client.
843    #[must_use]
844    pub fn market_registry(&self) -> Arc<MarketRegistry> {
845        self.market_registry.clone()
846    }
847
848    /// Overrides the REST base URL. Intended for mock-server tests.
849    ///
850    /// # Panics
851    ///
852    /// Panics if the raw client is shared by another [`Arc`].
853    pub fn set_base_url(&mut self, base_url: &str) {
854        Arc::get_mut(&mut self.inner)
855            .expect("cannot override URL: raw client is shared")
856            .set_base_url(base_url);
857    }
858
859    /// Calls `GET /api/v1/orderBooks` and registers returned markets.
860    ///
861    /// # Errors
862    ///
863    /// Returns an error if the request fails or the response is invalid.
864    pub async fn get_order_books(
865        &self,
866        query: &LighterOrderBooksQuery,
867    ) -> LighterHttpResult<LighterOrderBooks> {
868        let response = self.inner.get_order_books(query).await?;
869        register_order_books(&self.market_registry, &response.order_books);
870        Ok(response)
871    }
872
873    /// Calls `GET /api/v1/orderBookDetails` and registers returned markets.
874    ///
875    /// # Errors
876    ///
877    /// Returns an error if the request fails or the response is invalid.
878    pub async fn get_order_book_details(
879        &self,
880        query: &LighterOrderBookDetailsQuery,
881    ) -> LighterHttpResult<LighterOrderBookDetails> {
882        let response = self.inner.get_order_book_details(query).await?;
883        parse_order_book_details_instruments_with_status(
884            &self.market_registry,
885            &response.order_book_details,
886            &response.spot_order_book_details,
887            self.generate_ts_init(),
888        )?;
889        Ok(response)
890    }
891
892    /// Calls `GET /api/v1/orderBookOrders`.
893    ///
894    /// # Errors
895    ///
896    /// Returns an error if the request fails or the response is invalid.
897    pub async fn get_order_book_orders(
898        &self,
899        query: &LighterOrderBookOrdersQuery,
900    ) -> LighterHttpResult<LighterOrderBookOrders> {
901        self.inner.get_order_book_orders(query).await
902    }
903
904    /// Calls `GET /api/v1/recentTrades`.
905    ///
906    /// # Errors
907    ///
908    /// Returns an error if the request fails or the response is invalid.
909    pub async fn get_recent_trades(
910        &self,
911        query: &LighterRecentTradesQuery,
912    ) -> LighterHttpResult<LighterTrades> {
913        self.inner.get_recent_trades(query).await
914    }
915
916    /// Calls `GET /api/v1/trades`.
917    ///
918    /// # Errors
919    ///
920    /// Returns an error if the request fails or the response is invalid.
921    pub async fn get_trades(&self, query: &LighterTradesQuery) -> LighterHttpResult<LighterTrades> {
922        self.inner.get_trades(query).await
923    }
924
925    /// Calls `GET /api/v1/candles`.
926    ///
927    /// # Errors
928    ///
929    /// Returns an error if the request fails or the response is invalid.
930    pub async fn get_candles(
931        &self,
932        query: &LighterCandlesQuery,
933    ) -> LighterHttpResult<LighterCandles> {
934        self.inner.get_candles(query).await
935    }
936
937    /// Calls `GET /api/v1/fundings`.
938    ///
939    /// # Errors
940    ///
941    /// Returns an error if the request fails or the response is invalid.
942    pub async fn get_fundings(
943        &self,
944        query: &LighterFundingsQuery,
945    ) -> LighterHttpResult<LighterFundings> {
946        self.inner.get_fundings(query).await
947    }
948
949    /// Fetches the account row for `account_index` via `GET /api/v1/account`.
950    ///
951    /// # Errors
952    ///
953    /// Returns an error if the request fails, the response is invalid, or the
954    /// venue returns no account for the index.
955    pub async fn get_account_detail(
956        &self,
957        account_index: i64,
958    ) -> LighterHttpResult<LighterAccountDetail> {
959        let query = LighterAccountQuery {
960            by: LighterAccountLookup::Index,
961            value: account_index.to_string(),
962        };
963        self.inner
964            .get_account(&query)
965            .await?
966            .accounts
967            .into_iter()
968            .next()
969            .ok_or_else(|| {
970                LighterHttpError::Parse(format!("no account returned for index {account_index}"))
971            })
972    }
973
974    /// Calls `GET /api/v1/accountActiveOrders`.
975    ///
976    /// # Errors
977    ///
978    /// Returns an error if the request fails or the response is invalid.
979    pub async fn get_account_active_orders(
980        &self,
981        query: &LighterAccountActiveOrdersQuery,
982    ) -> LighterHttpResult<LighterOrders> {
983        self.inner.get_account_active_orders(query).await
984    }
985
986    /// Calls `GET /api/v1/accountInactiveOrders`.
987    ///
988    /// # Errors
989    ///
990    /// Returns an error if the request fails or the response is invalid.
991    pub async fn get_account_inactive_orders(
992        &self,
993        query: &LighterAccountInactiveOrdersQuery,
994    ) -> LighterHttpResult<LighterOrders> {
995        self.inner.get_account_inactive_orders(query).await
996    }
997
998    /// Calls `GET /api/v1/accountOrders`.
999    ///
1000    /// # Errors
1001    ///
1002    /// Returns an error if the request fails or the response is invalid.
1003    pub async fn get_account_orders(
1004        &self,
1005        query: &LighterAccountOrdersQuery,
1006    ) -> LighterHttpResult<LighterOrders> {
1007        self.inner.get_account_orders(query).await
1008    }
1009
1010    /// Calls `GET /api/v1/nextNonce` for `(account_index, api_key_index)`.
1011    ///
1012    /// # Errors
1013    ///
1014    /// Returns an error if the request fails or the response is invalid.
1015    pub async fn get_next_nonce(
1016        &self,
1017        account_index: i64,
1018        api_key_index: u8,
1019    ) -> LighterHttpResult<LighterNextNonce> {
1020        let query = LighterNextNonceQuery {
1021            account_index,
1022            api_key_index,
1023        };
1024        self.inner.get_next_nonce(&query).await
1025    }
1026
1027    /// Calls `GET /api/v1/tx` for `tx_hash`.
1028    ///
1029    /// # Errors
1030    ///
1031    /// Returns an error if the request fails or the response is invalid.
1032    pub async fn get_tx(&self, tx_hash: impl Into<String>) -> LighterHttpResult<LighterTx> {
1033        self.inner
1034            .get_tx(&LighterTxQuery {
1035                by: LighterTxLookup::Hash,
1036                value: tx_hash.into(),
1037            })
1038            .await
1039    }
1040
1041    /// Calls `GET /api/v1/getMakerOnlyApiKeys` for `account_index`.
1042    ///
1043    /// `auth_token` is the canonical Lighter auth string minted from the
1044    /// caller's credential.
1045    ///
1046    /// # Errors
1047    ///
1048    /// Returns an error if the request fails or the response is invalid.
1049    pub async fn get_maker_only_api_keys(
1050        &self,
1051        account_index: i64,
1052        auth_token: impl Into<SecretString>,
1053    ) -> LighterHttpResult<LighterMakerOnlyApiKeys> {
1054        let query = Zeroizing::new(LighterMakerOnlyApiKeysQuery {
1055            authorization: Some(auth_token.into()),
1056            auth: None,
1057            account_index,
1058        });
1059        self.inner.get_maker_only_api_keys(&query).await
1060    }
1061
1062    /// Applies `referral_code` to the L1 address.
1063    ///
1064    /// # Errors
1065    ///
1066    /// Returns an error if the request fails or the response is invalid.
1067    pub async fn use_referral(
1068        &self,
1069        l1_address: &str,
1070        referral_code: &str,
1071        auth_token: &SecretString,
1072    ) -> LighterHttpResult<LighterResultCode> {
1073        self.inner
1074            .use_referral(l1_address, referral_code, auth_token.expose_secret())
1075            .await
1076    }
1077
1078    /// Calls `POST /api/v1/sendTx`.
1079    ///
1080    /// # Errors
1081    ///
1082    /// Returns an error if the request fails or the response is invalid.
1083    pub async fn send_tx(
1084        &self,
1085        request: &LighterSendTxRequest,
1086    ) -> LighterHttpResult<LighterSendTxResponse> {
1087        self.inner.send_tx(request).await
1088    }
1089
1090    /// Calls `POST /api/v1/sendTxBatch`.
1091    ///
1092    /// # Errors
1093    ///
1094    /// Returns an error if the request fails or the response is invalid.
1095    pub async fn send_tx_batch(
1096        &self,
1097        request: &LighterSendTxBatchRequest,
1098    ) -> LighterHttpResult<LighterSendTxBatchResponse> {
1099        self.inner.send_tx_batch(request).await
1100    }
1101
1102    /// Requests recent trades for an instrument and parses them into [`TradeTick`]s.
1103    ///
1104    /// # Errors
1105    ///
1106    /// Returns an error if the instrument has not been registered, the request fails, or a trade
1107    /// cannot be parsed.
1108    pub async fn request_recent_trades(
1109        &self,
1110        instrument: &InstrumentAny,
1111        limit: u16,
1112    ) -> LighterHttpResult<Vec<TradeTick>> {
1113        let market_id = self.market_index(instrument)?;
1114        let query = LighterRecentTradesQuery { market_id, limit };
1115        let response = self.inner.get_recent_trades(&query).await?;
1116        self.parse_trade_ticks(&response.trades, instrument)
1117    }
1118
1119    /// Requests historical trades and parses them into [`TradeTick`]s.
1120    ///
1121    /// If `query.market_id` is `None`, the value is resolved from the shared market registry.
1122    ///
1123    /// # Errors
1124    ///
1125    /// Returns an error if the instrument has not been registered, the request fails, or a trade
1126    /// cannot be parsed.
1127    pub async fn request_trades(
1128        &self,
1129        instrument: &InstrumentAny,
1130        query: LighterTradesQuery,
1131    ) -> LighterHttpResult<Vec<TradeTick>> {
1132        let mut query = Zeroizing::new(query);
1133        if query.market_id.is_none() {
1134            query.market_id = Some(self.market_index(instrument)?);
1135        }
1136        let response = self.inner.get_trades(&query).await?;
1137        self.parse_trade_ticks(&response.trades, instrument)
1138    }
1139
1140    /// Requests historical candles and parses them into Nautilus [`Bar`]s.
1141    ///
1142    /// # Errors
1143    ///
1144    /// Returns an error if the instrument has not been registered, the bar
1145    /// type is unsupported, the request fails, the page cap leaves part of the
1146    /// requested range uncovered, or a candle cannot be parsed.
1147    pub async fn request_bars(
1148        &self,
1149        instrument: &InstrumentAny,
1150        bar_type: BarType,
1151        start: Option<Timestamp>,
1152        end: Option<Timestamp>,
1153        limit: Option<u32>,
1154    ) -> LighterHttpResult<Vec<Bar>> {
1155        let market_id = self.market_index(instrument)?;
1156        let resolution = LighterCandleResolution::try_from(&bar_type)?;
1157        let interval_ms = resolution.interval_millis();
1158        let now = Timestamp::now();
1159
1160        if let (Some(start), Some(end)) = (start, end)
1161            && start >= end
1162        {
1163            return Err(LighterHttpError::Parse(format!(
1164                "invalid bar request range: start={start}, end={end}",
1165            )));
1166        }
1167
1168        let end = end.unwrap_or(now).min(now);
1169
1170        if let Some(start) = start
1171            && start >= end
1172        {
1173            return Ok(Vec::new());
1174        }
1175
1176        let requested_limit = limit.filter(|n| *n > 0).map(|n| n as usize);
1177        let target_limit = requested_limit.unwrap_or(DEFAULT_BARS_LIMIT);
1178        let start_was_unspecified = start.is_none();
1179        let end_ms = end.as_millisecond().max(0);
1180        let now_ms = now.as_millisecond();
1181
1182        if end_ms == 0 {
1183            return Ok(Vec::new());
1184        }
1185
1186        let start_ms = start.map_or_else(
1187            || {
1188                let lookback_bars = target_limit.saturating_add(1);
1189                let lookback_bars = i64::try_from(lookback_bars).unwrap_or(i64::MAX);
1190                let lookback_ms = interval_ms.saturating_mul(lookback_bars);
1191                end_ms.saturating_sub(lookback_ms)
1192            },
1193            |dt| dt.as_millisecond().max(0),
1194        );
1195
1196        if start_ms >= end_ms {
1197            return Ok(Vec::new());
1198        }
1199
1200        let mut bars = Vec::new();
1201        let mut cursor_ms = start_ms;
1202        let mut pages = 0_usize;
1203        let page_span_ms = interval_ms.saturating_mul(i64::from(LIGHTER_CANDLES_MAX_LIMIT));
1204
1205        while cursor_ms < end_ms && pages < MAX_BAR_REQUEST_PAGES {
1206            if !start_was_unspecified
1207                && let Some(limit) = requested_limit
1208                && bars.len() >= limit
1209            {
1210                break;
1211            }
1212
1213            let window_end_ms = cursor_ms.saturating_add(page_span_ms).min(end_ms);
1214            if window_end_ms <= cursor_ms {
1215                break;
1216            }
1217
1218            let query = LighterCandlesQuery {
1219                market_id,
1220                resolution,
1221                start_timestamp: cursor_ms,
1222                end_timestamp: window_end_ms,
1223                count_back: i64::from(LIGHTER_CANDLES_MAX_LIMIT),
1224                set_timestamp_to_end: Some(false),
1225            };
1226            let response = self.get_candles(&query).await?;
1227            let mut page = self.parse_bars(&response.candles, instrument, bar_type)?;
1228
1229            page.sort_by_key(|bar| bar.ts_event);
1230            for bar in page {
1231                let bar_start_ms = i64::try_from(bar.ts_event.as_u64() / 1_000_000)
1232                    .map_err(|e| LighterHttpError::Parse(e.to_string()))?;
1233
1234                if bar_start_ms < cursor_ms
1235                    || bar_start_ms >= end_ms
1236                    || bar_start_ms.saturating_add(interval_ms) > now_ms
1237                {
1238                    continue;
1239                }
1240
1241                if bars
1242                    .last()
1243                    .is_some_and(|last: &Bar| last.ts_event == bar.ts_event)
1244                {
1245                    continue;
1246                }
1247                bars.push(bar);
1248
1249                if !start_was_unspecified
1250                    && let Some(limit) = requested_limit
1251                    && bars.len() >= limit
1252                {
1253                    break;
1254                }
1255            }
1256
1257            cursor_ms = window_end_ms;
1258            pages += 1;
1259        }
1260
1261        let limit_satisfied =
1262            !start_was_unspecified && requested_limit.is_some_and(|limit| bars.len() >= limit);
1263        if pages >= MAX_BAR_REQUEST_PAGES && cursor_ms < end_ms && !limit_satisfied {
1264            return Err(LighterHttpError::HistoryIncomplete {
1265                data_type: "bar",
1266                pages,
1267            });
1268        }
1269
1270        if start_was_unspecified && bars.len() > target_limit {
1271            bars = bars.split_off(bars.len() - target_limit);
1272        }
1273
1274        Ok(bars)
1275    }
1276
1277    /// Requests historical funding rates and parses them into Nautilus updates.
1278    ///
1279    /// Lighter's public `/api/v1/fundings` endpoint returns settled funding
1280    /// rows at hourly or daily resolution. The adapter requests hourly rows and
1281    /// returns them in chronological order.
1282    ///
1283    /// # Errors
1284    ///
1285    /// Returns an error if the instrument is not a perpetual, the instrument
1286    /// has not been registered, the request range is invalid, the page cap
1287    /// leaves part of the requested range uncovered, or a row cannot be parsed.
1288    pub async fn request_funding_rates(
1289        &self,
1290        instrument: &InstrumentAny,
1291        start: Option<Timestamp>,
1292        end: Option<Timestamp>,
1293        limit: Option<usize>,
1294    ) -> LighterHttpResult<Vec<FundingRateUpdate>> {
1295        if !matches!(instrument, InstrumentAny::CryptoPerpetual(_)) {
1296            return Err(LighterHttpError::Parse(format!(
1297                "funding rates are only available for perpetual instruments: {}",
1298                instrument.id()
1299            )));
1300        }
1301
1302        let market_id = self.market_index(instrument)?;
1303        let resolution = LighterFundingResolution::OneHour;
1304        let interval_ms = resolution.interval_millis();
1305        let now = Timestamp::now();
1306
1307        if let (Some(start), Some(end)) = (start, end)
1308            && start >= end
1309        {
1310            return Err(LighterHttpError::Parse(format!(
1311                "invalid funding request range: start={start}, end={end}",
1312            )));
1313        }
1314
1315        let end = end.unwrap_or(now).min(now);
1316
1317        if let Some(start) = start
1318            && start >= end
1319        {
1320            return Ok(Vec::new());
1321        }
1322
1323        let requested_limit = limit.filter(|n| *n > 0);
1324        let target_limit = requested_limit.unwrap_or(DEFAULT_FUNDING_RATES_LIMIT);
1325        let start_was_unspecified = start.is_none();
1326        let end_ms = end.as_millisecond().max(0);
1327
1328        if end_ms == 0 {
1329            return Ok(Vec::new());
1330        }
1331
1332        let start_ms = start.map_or_else(
1333            || {
1334                let lookback_rows = target_limit.saturating_add(1);
1335                let lookback_rows = i64::try_from(lookback_rows).unwrap_or(i64::MAX);
1336                let lookback_ms = interval_ms.saturating_mul(lookback_rows);
1337                end_ms.saturating_sub(lookback_ms)
1338            },
1339            |dt| dt.as_millisecond().max(0),
1340        );
1341
1342        if start_ms >= end_ms {
1343            return Ok(Vec::new());
1344        }
1345
1346        let ts_init = self.generate_ts_init();
1347        let interval = Some(resolution.interval_minutes());
1348        let mut funding_rates = Vec::new();
1349        let mut cursor_ms = start_ms;
1350        let mut pages = 0_usize;
1351        // `cap - 1`, not `cap`: the endpoint excludes `end_timestamp`, so a
1352        // full-cap span with `count_back = cap` would drop the row at the cursor.
1353        let page_span_ms =
1354            interval_ms.saturating_mul(i64::from(LIGHTER_FUNDINGS_MAX_LIMIT.saturating_sub(1)));
1355
1356        while cursor_ms < end_ms && pages < MAX_FUNDING_REQUEST_PAGES {
1357            if !start_was_unspecified
1358                && let Some(limit) = requested_limit
1359                && funding_rates.len() >= limit
1360            {
1361                break;
1362            }
1363
1364            let window_end_ms = cursor_ms.saturating_add(page_span_ms).min(end_ms);
1365            if window_end_ms <= cursor_ms {
1366                break;
1367            }
1368
1369            let query = LighterFundingsQuery {
1370                market_id,
1371                resolution,
1372                start_timestamp: cursor_ms,
1373                end_timestamp: window_end_ms,
1374                count_back: i64::from(LIGHTER_FUNDINGS_MAX_LIMIT),
1375            };
1376            let response = self.get_fundings(&query).await?;
1377
1378            let mut page = Vec::with_capacity(response.fundings.len());
1379            for funding in &response.fundings {
1380                let update = parse_funding_rate_update(funding, instrument.id(), interval, ts_init)
1381                    .map_err(LighterHttpError::from)?;
1382                let timestamp_ms = i64::try_from(update.ts_event.as_u64() / 1_000_000)
1383                    .map_err(|e| LighterHttpError::Parse(e.to_string()))?;
1384
1385                if timestamp_ms < cursor_ms || timestamp_ms > end_ms {
1386                    continue;
1387                }
1388                page.push(update);
1389            }
1390
1391            page.sort_by_key(|rate| rate.ts_event);
1392            for update in page {
1393                if funding_rates
1394                    .last()
1395                    .is_some_and(|last: &FundingRateUpdate| last.ts_event == update.ts_event)
1396                {
1397                    continue;
1398                }
1399                funding_rates.push(update);
1400
1401                if !start_was_unspecified
1402                    && let Some(limit) = requested_limit
1403                    && funding_rates.len() >= limit
1404                {
1405                    break;
1406                }
1407            }
1408
1409            cursor_ms = window_end_ms;
1410            pages += 1;
1411        }
1412
1413        let limit_satisfied = !start_was_unspecified
1414            && requested_limit.is_some_and(|limit| funding_rates.len() >= limit);
1415        if pages >= MAX_FUNDING_REQUEST_PAGES && cursor_ms < end_ms && !limit_satisfied {
1416            return Err(LighterHttpError::HistoryIncomplete {
1417                data_type: "funding rate",
1418                pages,
1419            });
1420        }
1421
1422        if start_was_unspecified && funding_rates.len() > target_limit {
1423            funding_rates = funding_rates.split_off(funding_rates.len() - target_limit);
1424        }
1425
1426        Ok(funding_rates)
1427    }
1428
1429    /// Requests all instruments from Lighter order book metadata.
1430    ///
1431    /// Lighter exposes market definitions through `GET /api/v1/orderBookDetails`.
1432    ///
1433    /// # Errors
1434    ///
1435    /// Returns an error if the request fails or supported markets contain no valid instruments.
1436    pub async fn request_instruments(&self) -> LighterHttpResult<Vec<InstrumentAny>> {
1437        self.request_instruments_for_query(&LighterOrderBookDetailsQuery::default())
1438            .await
1439    }
1440
1441    /// Requests all instruments and their market statuses from Lighter order book metadata.
1442    ///
1443    /// # Errors
1444    ///
1445    /// Returns an error if the request fails or supported markets contain no valid instruments.
1446    pub async fn request_instruments_with_status(
1447        &self,
1448    ) -> LighterHttpResult<Vec<(InstrumentAny, LighterMarketStatus)>> {
1449        self.request_instruments_with_status_for_query(&LighterOrderBookDetailsQuery::default())
1450            .await
1451    }
1452
1453    /// Requests a single instrument from Lighter order book metadata.
1454    ///
1455    /// # Errors
1456    ///
1457    /// Returns an error if the request fails, the instrument is not found, or the instrument
1458    /// cannot be parsed.
1459    pub async fn request_instrument(
1460        &self,
1461        instrument_id: InstrumentId,
1462    ) -> LighterHttpResult<InstrumentAny> {
1463        self.request_instrument_with_status(instrument_id)
1464            .await
1465            .map(|(instrument, _)| instrument)
1466    }
1467
1468    /// Requests a single instrument and its market status from Lighter order book metadata.
1469    ///
1470    /// # Errors
1471    ///
1472    /// Returns an error if the request fails, the instrument is not found, or the instrument
1473    /// cannot be parsed.
1474    pub async fn request_instrument_with_status(
1475        &self,
1476        instrument_id: InstrumentId,
1477    ) -> LighterHttpResult<(InstrumentAny, LighterMarketStatus)> {
1478        let query = LighterOrderBookDetailsQuery {
1479            market_id: self.market_registry.market_index(&instrument_id),
1480            filter: None,
1481        };
1482        let instruments = self
1483            .request_instruments_with_status_for_query(&query)
1484            .await?;
1485
1486        instruments
1487            .into_iter()
1488            .find(|(instrument, _)| instrument.id() == instrument_id)
1489            .ok_or_else(|| LighterHttpError::Parse(format!("instrument {instrument_id} not found")))
1490    }
1491
1492    /// Requests an HTTP order book snapshot and parses it into Nautilus order book deltas.
1493    ///
1494    /// # Errors
1495    ///
1496    /// Returns an error if the instrument has not been registered, the request fails, or any level
1497    /// cannot be parsed.
1498    pub async fn request_order_book_snapshot(
1499        &self,
1500        instrument: &InstrumentAny,
1501        limit: u16,
1502    ) -> LighterHttpResult<OrderBookDeltas> {
1503        let query = LighterOrderBookOrdersQuery {
1504            market_id: self.market_index(instrument)?,
1505            limit,
1506        };
1507        let snapshot = self.inner.get_order_book_orders(&query).await?;
1508        let ts_init = self.generate_ts_init();
1509
1510        parse_order_book_snapshot(
1511            &snapshot,
1512            instrument.id(),
1513            instrument.price_precision(),
1514            instrument.size_precision(),
1515            ts_init,
1516            ts_init,
1517        )
1518        .map_err(LighterHttpError::from)
1519    }
1520
1521    async fn request_instruments_for_query(
1522        &self,
1523        query: &LighterOrderBookDetailsQuery,
1524    ) -> LighterHttpResult<Vec<InstrumentAny>> {
1525        self.request_instruments_with_status_for_query(query)
1526            .await
1527            .map(|instruments| {
1528                instruments
1529                    .into_iter()
1530                    .map(|(instrument, _)| instrument)
1531                    .collect()
1532            })
1533    }
1534
1535    async fn request_instruments_with_status_for_query(
1536        &self,
1537        query: &LighterOrderBookDetailsQuery,
1538    ) -> LighterHttpResult<Vec<(InstrumentAny, LighterMarketStatus)>> {
1539        let response = self.inner.get_order_book_details(query).await?;
1540        let ts_init = self.generate_ts_init();
1541        parse_order_book_details_instruments_with_status(
1542            &self.market_registry,
1543            &response.order_book_details,
1544            &response.spot_order_book_details,
1545            ts_init,
1546        )
1547        .map_err(LighterHttpError::from)
1548    }
1549
1550    fn parse_trade_ticks(
1551        &self,
1552        trades: &[LighterTrade],
1553        instrument: &InstrumentAny,
1554    ) -> LighterHttpResult<Vec<TradeTick>> {
1555        let ts_init = self.generate_ts_init();
1556        trades
1557            .iter()
1558            .map(|trade| parse_trade_tick(trade, instrument, ts_init).map_err(Into::into))
1559            .collect()
1560    }
1561
1562    fn parse_bars(
1563        &self,
1564        candles: &[LighterCandle],
1565        instrument: &InstrumentAny,
1566        bar_type: BarType,
1567    ) -> LighterHttpResult<Vec<Bar>> {
1568        let ts_init = self.generate_ts_init();
1569        candles
1570            .iter()
1571            .filter_map(|candle| {
1572                let has_positive_ohlc = candle.open > Decimal::ZERO
1573                    && candle.high > Decimal::ZERO
1574                    && candle.low > Decimal::ZERO
1575                    && candle.close > Decimal::ZERO;
1576
1577                if !has_positive_ohlc {
1578                    log::warn!(
1579                        "Skipping Lighter candle at timestamp {} with non-positive OHLC values",
1580                        candle.timestamp,
1581                    );
1582                    return None;
1583                }
1584
1585                Some(parse_candle_bar(candle, bar_type, instrument, ts_init).map_err(Into::into))
1586            })
1587            .collect()
1588    }
1589
1590    fn market_index(&self, instrument: &InstrumentAny) -> LighterHttpResult<i64> {
1591        self.market_registry
1592            .market_index(&instrument.id())
1593            .ok_or_else(|| {
1594                LighterHttpError::Parse(format!(
1595                    "market index not registered for instrument {}",
1596                    instrument.id()
1597                ))
1598            })
1599    }
1600
1601    fn generate_ts_init(&self) -> UnixNanos {
1602        self.clock.get_time_ns()
1603    }
1604}
1605
1606fn venue_error(code: i32, message: Option<&str>, default_message: &str) -> LighterHttpError {
1607    LighterHttpError::Venue {
1608        code: i64::from(code),
1609        message: message.unwrap_or(default_message).to_string(),
1610    }
1611}
1612
1613#[cfg(test)]
1614mod tests {
1615    use rstest::rstest;
1616
1617    use super::*;
1618
1619    #[rstest]
1620    #[case(ENDPOINT_TRADES, "lighter:trades")]
1621    #[case(ENDPOINT_SEND_TX, "lighter:sendTx")]
1622    #[case(ENDPOINT_SEND_TX_BATCH, "lighter:sendTxBatch")]
1623    fn test_rate_limit_keys_uses_rest_bucket_and_route(
1624        #[case] endpoint: &str,
1625        #[case] route: &str,
1626    ) {
1627        // Transactions are paced by the shared tx limiter, not a separate HTTP
1628        // key, so every endpoint (reads and tx) keys uniformly on the rest bucket.
1629        assert_eq!(
1630            LighterRawHttpClient::rate_limit_keys(endpoint),
1631            vec![LIGHTER_REST_BUCKET.to_string(), route.to_string()],
1632        );
1633    }
1634}