Implement Deribit rate limiting for HTTP and WebSocket clients (#3424)

Author: filipmacek

crates/adapters/deribit/src/common/consts.rs

@@ -15,10 +15,11 @@
 
 //! Core constants for the Deribit adapter.
 
-use std::sync::LazyLock;
+use std::{num::NonZeroU32, sync::LazyLock};
 
 use ahash::AHashSet;
 use nautilus_model::identifiers::Venue;
+use nautilus_network::ratelimiter::quota::Quota;
 use ustr::Ustr;
 
 /// Venue identifier string.
@@ -111,3 +112,74 @@ pub static DERIBIT_RETRY_ERROR_CODES: LazyLock<AHashSet<i64>> = LazyLock::new(||
 pub fn should_retry_error_code(error_code: i64) -> bool {
     DERIBIT_RETRY_ERROR_CODES.contains(&error_code)
 }
+
+/// Default Deribit REST API rate limit: 20 requests per second sustained.
+///
+/// Deribit uses a credit-based system for non-matching engine requests:
+/// - Each request costs 500 credits
+/// - Maximum credits: 50,000
+/// - Refill rate: 10,000 credits/second (~20 sustained req/s)
+/// - Burst capacity: up to 100 requests (50,000 / 500)
+///
+/// # References
+///
+/// <https://docs.deribit.com/#rate-limits>
+pub static DERIBIT_HTTP_REST_QUOTA: LazyLock<Quota> = LazyLock::new(|| {
+    Quota::per_second(NonZeroU32::new(20).expect("20 is non-zero"))
+        .allow_burst(NonZeroU32::new(100).expect("100 is non-zero"))
+});
+
+/// Deribit matching engine (order operations) rate limit.
+///
+/// Matching engine requests (buy, sell, edit, cancel) have separate limits:
+/// - Default burst: 20
+/// - Default rate: 5 requests/second
+///
+/// Note: Actual limits vary by account tier based on 7-day trading volume.
+pub static DERIBIT_HTTP_ORDER_QUOTA: LazyLock<Quota> = LazyLock::new(|| {
+    Quota::per_second(NonZeroU32::new(5).expect("5 is non-zero"))
+        .allow_burst(NonZeroU32::new(20).expect("20 is non-zero"))
+});
+
+/// Conservative rate limit for account information endpoints.
+pub static DERIBIT_HTTP_ACCOUNT_QUOTA: LazyLock<Quota> =
+    LazyLock::new(|| Quota::per_second(NonZeroU32::new(5).expect("5 is non-zero")));
+
+/// Global rate limit key for Deribit HTTP requests.
+pub const DERIBIT_GLOBAL_RATE_KEY: &str = "deribit:global";
+
+/// Rate limit key for Deribit order operations (matching engine).
+pub const DERIBIT_ORDER_RATE_KEY: &str = "deribit:orders";
+
+/// Rate limit key for account information endpoints.
+pub const DERIBIT_ACCOUNT_RATE_KEY: &str = "deribit:account";
+
+/// Deribit WebSocket subscription rate limit.
+///
+/// Subscribe methods have custom rate limits:
+/// - Cost per request: 3,000 credits
+/// - Maximum credits: 30,000
+/// - Sustained rate: ~3.3 requests/second
+/// - Burst capacity: 10 requests
+///
+/// # References
+///
+/// <https://support.deribit.com/hc/en-us/articles/25944617523357-Rate-Limits>
+pub static DERIBIT_WS_SUBSCRIPTION_QUOTA: LazyLock<Quota> = LazyLock::new(|| {
+    Quota::per_second(NonZeroU32::new(3).expect("3 is non-zero"))
+        .allow_burst(NonZeroU32::new(10).expect("10 is non-zero"))
+});
+
+/// Deribit WebSocket order rate limit: 5 requests per second with 20 burst.
+///
+/// Matching engine operations (buy, sell, edit, cancel) have stricter limits.
+pub static DERIBIT_WS_ORDER_QUOTA: LazyLock<Quota> = LazyLock::new(|| {
+    Quota::per_second(NonZeroU32::new(5).expect("5 is non-zero"))
+        .allow_burst(NonZeroU32::new(20).expect("20 is non-zero"))
+});
+
+/// Rate limit key for WebSocket subscriptions.
+pub const DERIBIT_WS_SUBSCRIPTION_KEY: &str = "subscription";
+
+/// Rate limit key for WebSocket order operations.
+pub const DERIBIT_WS_ORDER_KEY: &str = "order";

crates/adapters/deribit/src/http/client.rs

@@ -37,6 +37,7 @@ use nautilus_model::{
 };
 use nautilus_network::{
     http::{HttpClient, Method},
+    ratelimiter::quota::Quota,
     retry::{RetryConfig, RetryManager},
 };
 use serde::{Serialize, de::DeserializeOwned};
@@ -59,7 +60,11 @@ use super::{
 };
 use crate::{
     common::{
-        consts::{DERIBIT_API_PATH, JSONRPC_VERSION, should_retry_error_code},
+        consts::{
+            DERIBIT_ACCOUNT_RATE_KEY, DERIBIT_API_PATH, DERIBIT_GLOBAL_RATE_KEY,
+            DERIBIT_HTTP_ACCOUNT_QUOTA, DERIBIT_HTTP_ORDER_QUOTA, DERIBIT_HTTP_REST_QUOTA,
+            DERIBIT_ORDER_RATE_KEY, JSONRPC_VERSION, should_retry_error_code,
+        },
         credential::Credential,
         parse::{
             extract_server_timestamp, parse_account_state, parse_bars,
@@ -128,10 +133,10 @@ impl DeribitRawHttpClient {
         Ok(Self {
             base_url,
             client: HttpClient::new(
-                HashMap::new(), // headers
-                Vec::new(),     // header_keys
-                Vec::new(),     // keyed_quotas
-                None,           // default_quota
+                HashMap::new(),
+                Vec::new(),
+                Self::rate_limiter_quotas(),
+                Some(*DERIBIT_HTTP_REST_QUOTA),
                 timeout_secs,
                 proxy_url,
             )
@@ -154,6 +159,80 @@ impl DeribitRawHttpClient {
         self.base_url.contains("test")
     }
 
+    /// Returns the rate limiter quotas for the HTTP client.
+    ///
+    /// Quotas are organized by:
+    /// - Global: Overall rate limit for all requests
+    /// - Orders: Matching engine operations (buy, sell, cancel, etc.)
+    /// - Account: Account information endpoints
+    fn rate_limiter_quotas() -> Vec<(String, Quota)> {
+        vec![
+            (
+                DERIBIT_GLOBAL_RATE_KEY.to_string(),
+                *DERIBIT_HTTP_REST_QUOTA,
+            ),
+            (
+                DERIBIT_ORDER_RATE_KEY.to_string(),
+                *DERIBIT_HTTP_ORDER_QUOTA,
+            ),
+            (
+                DERIBIT_ACCOUNT_RATE_KEY.to_string(),
+                *DERIBIT_HTTP_ACCOUNT_QUOTA,
+            ),
+        ]
+    }
+
+    /// Returns rate limit keys for a given RPC method.
+    ///
+    /// Maps Deribit JSON-RPC methods to appropriate rate limit buckets.
+    fn rate_limit_keys(method: &str) -> Vec<String> {
+        let mut keys = vec![DERIBIT_GLOBAL_RATE_KEY.to_string()];
+
+        // Categorize by method type
+        if Self::is_order_method(method) {
+            keys.push(DERIBIT_ORDER_RATE_KEY.to_string());
+        } else if Self::is_account_method(method) {
+            keys.push(DERIBIT_ACCOUNT_RATE_KEY.to_string());
+        }
+
+        // Add method-specific key
+        keys.push(format!("deribit:{method}"));
+
+        keys
+    }
+
+    /// Returns true if the method is an order operation (matching engine).
+    fn is_order_method(method: &str) -> bool {
+        matches!(
+            method,
+            "private/buy"
+                | "private/sell"
+                | "private/edit"
+                | "private/cancel"
+                | "private/cancel_all"
+                | "private/cancel_all_by_currency"
+                | "private/cancel_all_by_instrument"
+                | "private/cancel_by_label"
+                | "private/close_position"
+        )
+    }
+
+    /// Returns true if the method accesses account information.
+    fn is_account_method(method: &str) -> bool {
+        matches!(
+            method,
+            "private/get_account_summaries"
+                | "private/get_account_summary"
+                | "private/get_positions"
+                | "private/get_position"
+                | "private/get_open_orders_by_currency"
+                | "private/get_open_orders_by_instrument"
+                | "private/get_order_state"
+                | "private/get_user_trades_by_currency"
+                | "private/get_user_trades_by_instrument"
+        )
+    }
+
     /// Creates a new [`DeribitRawHttpClient`] with explicit credentials.
     ///
     /// # Errors
@@ -192,8 +271,8 @@ impl DeribitRawHttpClient {
             client: HttpClient::new(
                 HashMap::new(),
                 Vec::new(),
-                Vec::new(),
-                None,
+                Self::rate_limiter_quotas(),
+                Some(*DERIBIT_HTTP_REST_QUOTA),
                 timeout_secs,
                 proxy_url,
             )
@@ -308,6 +387,7 @@ impl DeribitRawHttpClient {
                     headers.extend(auth_headers);
                 }
 
+                let rate_limit_keys = Self::rate_limit_keys(&method);
                 let resp = self
                     .client
                     .request(
@@ -317,7 +397,7 @@ impl DeribitRawHttpClient {
                         Some(headers),
                         Some(body),
                         None,
-                        None,
+                        Some(rate_limit_keys),
                     )
                     .await
                     .map_err(|e| DeribitHttpError::NetworkError(e.to_string()))?;
@@ -1456,3 +1536,41 @@ impl DeribitHttpClient {
         Ok(reports)
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use rstest::rstest;
+
+    use super::*;
+    use crate::common::consts::{
+        DERIBIT_ACCOUNT_RATE_KEY, DERIBIT_GLOBAL_RATE_KEY, DERIBIT_ORDER_RATE_KEY,
+    };
+
+    #[rstest]
+    #[case("private/buy", true, false)]
+    #[case("private/cancel", true, false)]
+    #[case("private/get_account_summaries", false, true)]
+    #[case("private/get_positions", false, true)]
+    #[case("public/get_instruments", false, false)]
+    fn test_method_classification(
+        #[case] method: &str,
+        #[case] is_order: bool,
+        #[case] is_account: bool,
+    ) {
+        assert_eq!(DeribitRawHttpClient::is_order_method(method), is_order);
+        assert_eq!(DeribitRawHttpClient::is_account_method(method), is_account);
+    }
+
+    #[rstest]
+    #[case("private/buy", vec![DERIBIT_GLOBAL_RATE_KEY, DERIBIT_ORDER_RATE_KEY])]
+    #[case("private/get_account_summaries", vec![DERIBIT_GLOBAL_RATE_KEY, DERIBIT_ACCOUNT_RATE_KEY])]
+    #[case("public/get_instruments", vec![DERIBIT_GLOBAL_RATE_KEY])]
+    fn test_rate_limit_keys(#[case] method: &str, #[case] expected_keys: Vec<&str>) {
+        let keys = DeribitRawHttpClient::rate_limit_keys(method);
+
+        for key in &expected_keys {
+            assert!(keys.contains(&key.to_string()));
+        }
+        assert!(keys.contains(&format!("deribit:{method}")));
+    }
+}

crates/adapters/deribit/src/websocket/client.rs

@@ -21,9 +21,8 @@
 
 use std::{
     fmt::Debug,
-    num::NonZeroU32,
     sync::{
-        Arc, LazyLock,
+        Arc,
         atomic::{AtomicBool, AtomicU8, Ordering},
     },
     time::Duration,
@@ -45,7 +44,6 @@ use nautilus_model::{
 use nautilus_network::{
     http::USER_AGENT,
     mode::ConnectionMode,
-    ratelimiter::quota::Quota,
     websocket::{
         AuthTracker, PingHandler, SubscriptionState, WebSocketClient, WebSocketConfig,
         channel_message_handler,
@@ -65,14 +63,13 @@ use super::{
     },
 };
 use crate::common::{
-    consts::{DERIBIT_TESTNET_WS_URL, DERIBIT_WS_URL},
+    consts::{
+        DERIBIT_TESTNET_WS_URL, DERIBIT_WS_ORDER_KEY, DERIBIT_WS_ORDER_QUOTA,
+        DERIBIT_WS_SUBSCRIPTION_KEY, DERIBIT_WS_SUBSCRIPTION_QUOTA, DERIBIT_WS_URL,
+    },
     credential::Credential,
 };
 
-/// Default Deribit WebSocket subscription rate limit: 20 requests per second.
-pub static DERIBIT_WS_SUBSCRIPTION_QUOTA: LazyLock<Quota> =
-    LazyLock::new(|| Quota::per_second(NonZeroU32::new(20).unwrap()));
-
 /// Authentication timeout in seconds.
 const AUTHENTICATION_TIMEOUT_SECS: u64 = 30;
 
@@ -392,7 +389,13 @@ impl DeribitWebSocketClient {
         };
 
         // Configure rate limits
-        let keyed_quotas = vec![("subscription".to_string(), *DERIBIT_WS_SUBSCRIPTION_QUOTA)];
+        let keyed_quotas = vec![
+            (
+                DERIBIT_WS_SUBSCRIPTION_KEY.to_string(),
+                *DERIBIT_WS_SUBSCRIPTION_QUOTA,
+            ),
+            (DERIBIT_WS_ORDER_KEY.to_string(), *DERIBIT_WS_ORDER_QUOTA),
+        ];
 
         // Connect the WebSocket
         let ws_client = WebSocketClient::connect(
@@ -401,7 +404,7 @@ impl DeribitWebSocketClient {
             Some(ping_handler),
             None, // post_reconnection
             keyed_quotas,
-            Some(*DERIBIT_WS_SUBSCRIPTION_QUOTA), // Default quota
+            Some(*DERIBIT_WS_SUBSCRIPTION_QUOTA), // Default quota for non-order operations
         )
         .await?;