1use 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
104pub const LIGHTER_REST_PAGE_SIZE: u16 = 100;
109pub const LIGHTER_CANDLES_MAX_LIMIT: u16 = 500;
110
111pub 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#[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 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 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 #[must_use]
243 pub fn base_url(&self) -> &str {
244 self.base_url.as_str()
245 }
246
247 #[must_use]
249 pub const fn environment(&self) -> LighterEnvironment {
250 self.environment
251 }
252
253 pub fn set_base_url(&mut self, base_url: &str) {
255 self.base_url = base_url.trim_end_matches('/').to_string();
256 }
257
258 pub fn set_retry_manager(&mut self, retry_manager: RetryManager<LighterHttpError>) {
261 self.retry_manager = retry_manager;
262 }
263
264 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 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 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 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 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 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 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 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 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 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 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 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 pub async fn get_tx(&self, query: &LighterTxQuery) -> LighterHttpResult<LighterTx> {
426 self.send_get_request(ENDPOINT_TX, Some(query)).await
427 }
428
429 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(¶ms), headers)
444 .await
445 }
446
447 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 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 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 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 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 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 if status >= 500 {
641 return Err(LighterHttpError::Http {
642 status,
643 body,
644 retry_after,
645 });
646 }
647
648 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#[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 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 #[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 #[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 #[must_use]
832 pub fn base_url(&self) -> &str {
833 self.inner.base_url()
834 }
835
836 #[must_use]
838 pub fn environment(&self) -> LighterEnvironment {
839 self.inner.environment()
840 }
841
842 #[must_use]
844 pub fn market_registry(&self) -> Arc<MarketRegistry> {
845 self.market_registry.clone()
846 }
847
848 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 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 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 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 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 pub async fn get_trades(&self, query: &LighterTradesQuery) -> LighterHttpResult<LighterTrades> {
922 self.inner.get_trades(query).await
923 }
924
925 pub async fn get_candles(
931 &self,
932 query: &LighterCandlesQuery,
933 ) -> LighterHttpResult<LighterCandles> {
934 self.inner.get_candles(query).await
935 }
936
937 pub async fn get_fundings(
943 &self,
944 query: &LighterFundingsQuery,
945 ) -> LighterHttpResult<LighterFundings> {
946 self.inner.get_fundings(query).await
947 }
948
949 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 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 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 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 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 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 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 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 pub async fn send_tx(
1084 &self,
1085 request: &LighterSendTxRequest,
1086 ) -> LighterHttpResult<LighterSendTxResponse> {
1087 self.inner.send_tx(request).await
1088 }
1089
1090 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 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 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 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 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 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 pub async fn request_instruments(&self) -> LighterHttpResult<Vec<InstrumentAny>> {
1437 self.request_instruments_for_query(&LighterOrderBookDetailsQuery::default())
1438 .await
1439 }
1440
1441 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 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 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 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 assert_eq!(
1630 LighterRawHttpClient::rate_limit_keys(endpoint),
1631 vec![LIGHTER_REST_BUCKET.to_string(), route.to_string()],
1632 );
1633 }
1634}