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 self.send_get_request(ENDPOINT_TRADES, Some(query)).await
323 }
324
325 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 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 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 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 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 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 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 pub async fn get_tx(&self, query: &LighterTxQuery) -> LighterHttpResult<LighterTx> {
421 self.send_get_request(ENDPOINT_TX, Some(query)).await
422 }
423
424 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(¶ms), headers)
447 .await
448 }
449
450 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 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 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 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 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 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 if status >= 500 {
644 return Err(LighterHttpError::Http {
645 status,
646 body,
647 retry_after,
648 });
649 }
650
651 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#[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 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 #[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 #[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 #[must_use]
823 pub fn base_url(&self) -> &str {
824 self.inner.base_url()
825 }
826
827 #[must_use]
829 pub fn environment(&self) -> LighterEnvironment {
830 self.inner.environment()
831 }
832
833 #[must_use]
835 pub fn market_registry(&self) -> Arc<MarketRegistry> {
836 self.market_registry.clone()
837 }
838
839 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 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 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 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 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 pub async fn get_trades(&self, query: &LighterTradesQuery) -> LighterHttpResult<LighterTrades> {
913 self.inner.get_trades(query).await
914 }
915
916 pub async fn get_candles(
922 &self,
923 query: &LighterCandlesQuery,
924 ) -> LighterHttpResult<LighterCandles> {
925 self.inner.get_candles(query).await
926 }
927
928 pub async fn get_fundings(
934 &self,
935 query: &LighterFundingsQuery,
936 ) -> LighterHttpResult<LighterFundings> {
937 self.inner.get_fundings(query).await
938 }
939
940 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 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 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 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 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 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 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 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 pub async fn send_tx(
1075 &self,
1076 request: &LighterSendTxRequest,
1077 ) -> LighterHttpResult<LighterSendTxResponse> {
1078 self.inner.send_tx(request).await
1079 }
1080
1081 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 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 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 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 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 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 pub async fn request_instruments(&self) -> LighterHttpResult<Vec<InstrumentAny>> {
1428 self.request_instruments_for_query(&LighterOrderBookDetailsQuery::default())
1429 .await
1430 }
1431
1432 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 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 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 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 assert_eq!(
1621 LighterRawHttpClient::rate_limit_keys(endpoint),
1622 vec![LIGHTER_REST_BUCKET.to_string(), route.to_string()],
1623 );
1624 }
1625}