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