Skip to main content

nautilus_deribit/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//! Deribit HTTP client implementation.
17
18use std::{
19    collections::HashMap,
20    str::FromStr,
21    sync::{
22        Arc,
23        atomic::{AtomicBool, AtomicU64, Ordering},
24    },
25};
26
27use ahash::{AHashMap, AHashSet};
28use anyhow::Context;
29use indexmap::IndexMap;
30use jiff::Timestamp;
31use nautilus_common::cache::InstrumentLookupError;
32use nautilus_core::{
33    AtomicMap, AtomicTime, Params, datetime::nanos_to_millis, nanos::UnixNanos,
34    time::get_atomic_clock_realtime,
35};
36use nautilus_model::{
37    data::{Bar, BarType, TradeTick},
38    enums::{AggregationSource, BarAggregation},
39    events::AccountState,
40    identifiers::{AccountId, InstrumentId, Symbol, VenueOrderId},
41    instruments::{Instrument, InstrumentAny},
42    orderbook::OrderBook,
43    reports::{FillReport, OrderStatusReport, PositionStatusReport},
44};
45use nautilus_network::{
46    http::{HttpClient, HttpRedirectPolicy, Method, create_standard_nautilus_headers},
47    ratelimiter::quota::Quota,
48    retry::{RetryConfig, RetryError, RetryManager},
49};
50use serde::{Serialize, de::DeserializeOwned};
51use serde_json::json;
52use strum::IntoEnumIterator;
53use tokio_util::sync::CancellationToken;
54use ustr::Ustr;
55
56use super::{
57    error::DeribitHttpError,
58    models::{
59        DeribitAccountSummariesResponse, DeribitBookSummaryRaw, DeribitCombo, DeribitCurrency,
60        DeribitExpirationsResponse, DeribitInstrument, DeribitJsonRpcRequest,
61        DeribitJsonRpcResponse, DeribitPosition, DeribitProductType, DeribitTicker,
62        DeribitUserTradesResponse,
63    },
64    query::{
65        DeribitExpirationKind, GetAccountSummariesParams, GetBookSummaryByCurrencyParams,
66        GetCombosParams, GetExpirationsParams, GetInstrumentParams, GetInstrumentsParams,
67        GetOpenOrdersByInstrumentParams, GetOpenOrdersParams, GetOrderHistoryByCurrencyParams,
68        GetOrderHistoryByInstrumentParams, GetOrderStateParams, GetPositionsParams,
69        GetTickerParams, GetUserTradesByCurrencyAndTimeParams,
70        GetUserTradesByInstrumentAndTimeParams,
71    },
72    reconciliation::{
73        ReconciliationScope, ReportRead, instrument_id_from_name, is_historical_order_state,
74        millis_in_window, record_historical_miss, timestamp_in_window,
75    },
76};
77use crate::{
78    common::{
79        capabilities,
80        consts::{
81            DERIBIT_ACCOUNT_RATE_KEY, DERIBIT_API_PATH, DERIBIT_GLOBAL_RATE_KEY,
82            DERIBIT_HTTP_ACCOUNT_QUOTA, DERIBIT_HTTP_ORDER_QUOTA, DERIBIT_HTTP_REST_QUOTA,
83            DERIBIT_ORDER_RATE_KEY, DERIBIT_VENUE, JSONRPC_VERSION,
84        },
85        credential::{Credential, credential_env_vars},
86        enums::DeribitEnvironment,
87        parse::{
88            extract_server_timestamp, parse_account_state, parse_bars,
89            parse_deribit_instrument_any, parse_order_book, parse_trade_tick,
90            use_cost_for_bar_volume,
91        },
92        urls::get_http_base_url,
93    },
94    http::{
95        models::{DeribitOrderBook, DeribitTradesResponse, DeribitTradingViewChartData},
96        query::{
97            GetLastTradesByCurrencyParams, GetLastTradesByInstrumentAndTimeParams,
98            GetOrderBookParams, GetTradingViewChartDataParams,
99        },
100    },
101    websocket::{
102        messages::{DeribitOrderMsg, DeribitUserTradeMsg},
103        parse::{parse_position_status_report, parse_user_order_msg, parse_user_trade_msg},
104    },
105};
106
107/// Maximum number of trades per request for Deribit's historical trades API.
108/// Deribit's default is 10 which is insufficient for most use cases.
109/// The API maximum is 1000.
110pub const DERIBIT_HISTORICAL_TRADES_MAX_COUNT: u32 = 1000;
111
112const ORDER_HISTORY_PAGE_SIZE: u32 = 100;
113
114/// Low-level Deribit HTTP client for raw API operations.
115///
116/// This client handles JSON-RPC 2.0 protocol, request signing, rate limiting,
117/// and retry logic. It returns venue-specific response types.
118#[derive(Debug)]
119pub struct DeribitRawHttpClient {
120    base_url: String,
121    client: HttpClient,
122    credential: Option<Credential>,
123    retry_manager: RetryManager<DeribitHttpError>,
124    cancellation_token: CancellationToken,
125    request_id: AtomicU64,
126}
127
128impl DeribitRawHttpClient {
129    /// Creates a new [`DeribitRawHttpClient`].
130    ///
131    /// # Errors
132    ///
133    /// Returns an error if the HTTP client cannot be created.
134    pub fn new(
135        base_url: Option<String>,
136        environment: DeribitEnvironment,
137        timeout_secs: u64,
138        max_retries: u32,
139        retry_delay_ms: u64,
140        retry_delay_max_ms: u64,
141        proxy_url: Option<String>,
142    ) -> Result<Self, DeribitHttpError> {
143        let base_url = base_url
144            .unwrap_or_else(|| format!("{}{}", get_http_base_url(environment), DERIBIT_API_PATH));
145        let retry_config = RetryConfig {
146            max_retries,
147            initial_delay_ms: retry_delay_ms,
148            max_delay_ms: retry_delay_max_ms,
149            backoff_factor: 2.0,
150            jitter_ms: 1000,
151            operation_timeout_ms: Some(60_000),
152            immediate_first: false,
153            max_elapsed_ms: Some(180_000),
154        };
155
156        let retry_manager = RetryManager::new(retry_config);
157
158        Ok(Self {
159            base_url,
160            client: HttpClient::builder()
161                .headers(create_standard_nautilus_headers().into_iter().collect())
162                .keyed_quotas(Self::rate_limiter_quotas())
163                .default_quota(*DERIBIT_HTTP_REST_QUOTA)
164                .timeout_secs(timeout_secs)
165                .maybe_proxy_url(proxy_url)
166                .build()
167                .map_err(|e| anyhow::anyhow!("Failed to create HTTP client: {e}"))?,
168            credential: None,
169            retry_manager,
170            cancellation_token: CancellationToken::new(),
171            request_id: AtomicU64::new(1),
172        })
173    }
174
175    /// Get the cancellation token for this client.
176    pub fn cancellation_token(&self) -> &CancellationToken {
177        &self.cancellation_token
178    }
179
180    /// Returns whether this client is connected to testnet.
181    #[must_use]
182    pub fn is_testnet(&self) -> bool {
183        self.base_url.contains("test.")
184    }
185
186    /// Returns the rate limiter quotas for the HTTP client.
187    ///
188    /// Quotas are organized by:
189    /// - Global: Overall rate limit for all requests
190    /// - Orders: Matching engine operations (buy, sell, cancel, etc.)
191    /// - Account: Account information endpoints
192    fn rate_limiter_quotas() -> Vec<(String, Quota)> {
193        vec![
194            (
195                DERIBIT_GLOBAL_RATE_KEY.to_string(),
196                *DERIBIT_HTTP_REST_QUOTA,
197            ),
198            (
199                DERIBIT_ORDER_RATE_KEY.to_string(),
200                *DERIBIT_HTTP_ORDER_QUOTA,
201            ),
202            (
203                DERIBIT_ACCOUNT_RATE_KEY.to_string(),
204                *DERIBIT_HTTP_ACCOUNT_QUOTA,
205            ),
206        ]
207    }
208
209    /// Returns rate limit keys for a given RPC method.
210    ///
211    /// Maps Deribit JSON-RPC methods to appropriate rate limit buckets.
212    fn rate_limit_keys(method: &str) -> Vec<String> {
213        let mut keys = vec![DERIBIT_GLOBAL_RATE_KEY.to_string()];
214
215        // Categorize by method type
216        if Self::is_order_method(method) {
217            keys.push(DERIBIT_ORDER_RATE_KEY.to_string());
218        } else if Self::is_account_method(method) {
219            keys.push(DERIBIT_ACCOUNT_RATE_KEY.to_string());
220        }
221
222        // Add method-specific key
223        keys.push(format!("deribit:{method}"));
224
225        keys
226    }
227
228    /// Returns true if the method is an order operation (matching engine).
229    fn is_order_method(method: &str) -> bool {
230        matches!(
231            method,
232            "private/buy"
233                | "private/sell"
234                | "private/edit"
235                | "private/cancel"
236                | "private/cancel_all"
237                | "private/cancel_all_by_currency"
238                | "private/cancel_all_by_instrument"
239                | "private/cancel_by_label"
240                | "private/close_position"
241        )
242    }
243
244    /// Returns true if the method accesses account information.
245    fn is_account_method(method: &str) -> bool {
246        matches!(
247            method,
248            "private/get_account_summaries"
249                | "private/get_account_summary"
250                | "private/get_positions"
251                | "private/get_position"
252                | "private/get_open_orders_by_currency"
253                | "private/get_open_orders_by_instrument"
254                | "private/get_order_state"
255                | "private/get_user_trades_by_currency"
256                | "private/get_user_trades_by_instrument"
257        )
258    }
259
260    /// Creates a new [`DeribitRawHttpClient`] with explicit credentials.
261    ///
262    /// # Errors
263    ///
264    /// Returns an error if the HTTP client cannot be created.
265    #[expect(clippy::too_many_arguments)]
266    pub fn with_credentials(
267        api_key: String,
268        api_secret: String,
269        base_url: Option<String>,
270        environment: DeribitEnvironment,
271        timeout_secs: u64,
272        max_retries: u32,
273        retry_delay_ms: u64,
274        retry_delay_max_ms: u64,
275        proxy_url: Option<String>,
276    ) -> Result<Self, DeribitHttpError> {
277        let base_url = base_url
278            .unwrap_or_else(|| format!("{}{}", get_http_base_url(environment), DERIBIT_API_PATH));
279        let retry_config = RetryConfig {
280            max_retries,
281            initial_delay_ms: retry_delay_ms,
282            max_delay_ms: retry_delay_max_ms,
283            backoff_factor: 2.0,
284            jitter_ms: 1000,
285            operation_timeout_ms: Some(60_000),
286            immediate_first: false,
287            max_elapsed_ms: Some(180_000),
288        };
289
290        let retry_manager = RetryManager::new(retry_config);
291        let credential = Credential::new(api_key, api_secret);
292
293        Ok(Self {
294            base_url,
295            client: HttpClient::builder()
296                .redirect_policy(HttpRedirectPolicy::Reject)
297                .headers(create_standard_nautilus_headers().into_iter().collect())
298                .keyed_quotas(Self::rate_limiter_quotas())
299                .default_quota(*DERIBIT_HTTP_REST_QUOTA)
300                .timeout_secs(timeout_secs)
301                .maybe_proxy_url(proxy_url)
302                .build()
303                .map_err(|e| anyhow::anyhow!("Failed to create HTTP client: {e}"))?,
304            credential: Some(credential),
305            retry_manager,
306            cancellation_token: CancellationToken::new(),
307            request_id: AtomicU64::new(1),
308        })
309    }
310
311    /// Creates a new [`DeribitRawHttpClient`] with credentials from environment variables.
312    ///
313    /// If `api_key` or `api_secret` are not provided, they will be loaded from environment:
314    /// - Mainnet: `DERIBIT_API_KEY`, `DERIBIT_API_SECRET`
315    /// - Testnet: `DERIBIT_TESTNET_API_KEY`, `DERIBIT_TESTNET_API_SECRET`
316    ///
317    /// # Errors
318    ///
319    /// Returns an error if:
320    /// - The HTTP client cannot be created.
321    /// - Credentials are not provided and environment variables are not set.
322    #[expect(clippy::too_many_arguments)]
323    pub fn new_with_env(
324        api_key: Option<String>,
325        api_secret: Option<String>,
326        base_url: Option<String>,
327        environment: DeribitEnvironment,
328        timeout_secs: u64,
329        max_retries: u32,
330        retry_delay_ms: u64,
331        retry_delay_max_ms: u64,
332        proxy_url: Option<String>,
333    ) -> Result<Self, DeribitHttpError> {
334        // Determine environment variable names based on environment
335        let (key_env, secret_env) = credential_env_vars(environment);
336
337        // Resolve credentials from explicit params or environment
338        let api_key = nautilus_core::env::get_or_env_var_opt(api_key, key_env);
339        let api_secret = nautilus_core::env::get_or_env_var_opt(api_secret, secret_env);
340
341        // If credentials were resolved, create authenticated client
342        if let (Some(key), Some(secret)) = (api_key, api_secret) {
343            Self::with_credentials(
344                key,
345                secret,
346                base_url,
347                environment,
348                timeout_secs,
349                max_retries,
350                retry_delay_ms,
351                retry_delay_max_ms,
352                proxy_url,
353            )
354        } else {
355            // No credentials - create unauthenticated client
356            Self::new(
357                base_url,
358                environment,
359                timeout_secs,
360                max_retries,
361                retry_delay_ms,
362                retry_delay_max_ms,
363                proxy_url,
364            )
365        }
366    }
367
368    /// Sends a JSON-RPC 2.0 request to the Deribit API.
369    async fn send_request<T, P>(
370        &self,
371        method: &str,
372        params: P,
373        authenticate: bool,
374    ) -> Result<DeribitJsonRpcResponse<T>, DeribitHttpError>
375    where
376        T: DeserializeOwned,
377        P: Serialize,
378    {
379        // Create operation identifier combining URL and RPC method
380        let operation_id = format!("{}#{}", self.base_url, method);
381        let params_clone = serde_json::to_value(&params)?;
382
383        let operation = || {
384            let method = method.to_string();
385            let params_clone = params_clone.clone();
386
387            async move {
388                // Build JSON-RPC request
389                let id = self.request_id.fetch_add(1, Ordering::SeqCst);
390                let request = DeribitJsonRpcRequest {
391                    jsonrpc: JSONRPC_VERSION,
392                    id,
393                    method: method.clone(),
394                    params: params_clone.clone(),
395                };
396
397                let body = serde_json::to_vec(&request)?;
398
399                // Build headers
400                let mut headers = HashMap::new();
401                headers.insert("Content-Type".to_string(), "application/json".to_string());
402
403                // Add authentication headers if required
404                if authenticate {
405                    let credentials = self
406                        .credential
407                        .as_ref()
408                        .ok_or(DeribitHttpError::MissingCredentials)?;
409                    let auth_headers = credentials.sign_auth_headers("POST", "/api/v2", &body)?;
410                    headers.extend(auth_headers);
411                }
412
413                let rate_limit_keys = Self::rate_limit_keys(&method);
414                let resp = self
415                    .client
416                    .request(
417                        Method::POST,
418                        self.base_url.clone(),
419                        None,
420                        Some(headers),
421                        Some(body),
422                        None,
423                        Some(rate_limit_keys),
424                    )
425                    .await
426                    .map_err(|e| DeribitHttpError::NetworkError(e.to_string()))?;
427
428                // Parse JSON-RPC response
429                // Note: Deribit may return JSON-RPC errors with non-2xx HTTP status (e.g., 400)
430                // Always try to parse as JSON-RPC first, then fall back to HTTP error handling
431
432                // Decode the body directly so exact decimal fields read the raw numeric tokens
433                let json_rpc_response: DeribitJsonRpcResponse<T> = match serde_json::from_slice(
434                    &resp.body,
435                ) {
436                    Ok(response) => response,
437                    Err(e) if e.is_data() => {
438                        log::warn!(
439                            "Failed to deserialize Deribit JSON-RPC response: method={method}, status={}, error={e}",
440                            resp.status.as_u16()
441                        );
442                        log::debug!(
443                            "Response JSON (first 2000 chars): {}",
444                            String::from_utf8_lossy(&resp.body)
445                                .chars()
446                                .take(2000)
447                                .collect::<String>()
448                        );
449                        return Err(DeribitHttpError::JsonError(e.to_string()));
450                    }
451                    Err(_) => {
452                        // Not valid JSON - treat as HTTP error
453                        let error_body = String::from_utf8_lossy(&resp.body);
454                        log::warn!(
455                            "Non-JSON response: method={method}, status={}, body={error_body}",
456                            resp.status.as_u16()
457                        );
458                        return Err(DeribitHttpError::UnexpectedStatus {
459                            status: resp.status.as_u16(),
460                            body: error_body.to_string(),
461                        });
462                    }
463                };
464
465                // Check if it's a success or error result
466                if json_rpc_response.result.is_some() {
467                    Ok(json_rpc_response)
468                } else if let Some(error) = &json_rpc_response.error {
469                    // JSON-RPC error (may come with any HTTP status)
470                    log::warn!(
471                        "Deribit RPC error response: method={method}, http_status={}, error_code={}, error_message={}, error_data={:?}",
472                        resp.status.as_u16(),
473                        error.code,
474                        error.message,
475                        error.data
476                    );
477
478                    // Map JSON-RPC error to appropriate error variant
479                    Err(DeribitHttpError::from_jsonrpc_error(
480                        error.code,
481                        error.message.clone(),
482                        error.data.as_ref(),
483                    ))
484                } else {
485                    log::warn!(
486                        "Response contains neither result nor error field: method={method}, status={}, request_id={:?}",
487                        resp.status.as_u16(),
488                        json_rpc_response.id
489                    );
490                    Err(DeribitHttpError::JsonError(
491                        "Response contains neither result nor error".to_string(),
492                    ))
493                }
494            }
495        };
496
497        // Retry strategy based on Deribit error responses and HTTP status codes:
498        //
499        // 1. Network errors: always retry (transient connection issues)
500        // 2. HTTP 5xx/429: server errors and rate limiting should be retried
501        // 3. Deribit-specific retryable error codes (defined in common::consts)
502        //
503        // Note: Deribit returns many permanent errors which should NOT be retried
504        // (e.g., "invalid_credentials", "not_enough_funds", "order_not_found")
505        let should_retry = |error: &DeribitHttpError| -> bool { error.is_retryable() };
506
507        let create_error = |error: RetryError| -> DeribitHttpError {
508            match error {
509                RetryError::Canceled => {
510                    DeribitHttpError::Canceled("Adapter disconnecting or shutting down".to_string())
511                }
512                error => DeribitHttpError::NetworkError(error.to_string()),
513            }
514        };
515
516        let result = self
517            .retry_manager
518            .invocation(&operation_id, operation, should_retry, create_error)
519            .cancellation_token(&self.cancellation_token)
520            .execute()
521            .await;
522
523        if let Err(ref e) = result
524            && e.is_retryable()
525        {
526            log::warn!("Request exhausted retries: method={method}, error={e}");
527        }
528
529        result
530    }
531
532    /// Gets available trading instruments.
533    ///
534    /// # Errors
535    ///
536    /// Returns an error if the request fails or the response cannot be parsed.
537    pub async fn get_instruments(
538        &self,
539        params: GetInstrumentsParams,
540    ) -> Result<DeribitJsonRpcResponse<Vec<DeribitInstrument>>, DeribitHttpError> {
541        self.send_request("public/get_instruments", params, false)
542            .await
543    }
544
545    /// Gets details for a specific trading instrument.
546    ///
547    /// # Errors
548    ///
549    /// Returns an error if the request fails or the response cannot be parsed.
550    pub async fn get_instrument(
551        &self,
552        params: GetInstrumentParams,
553    ) -> Result<DeribitJsonRpcResponse<DeribitInstrument>, DeribitHttpError> {
554        self.send_request("public/get_instrument", params, false)
555            .await
556    }
557
558    /// Gets combo definitions for a currency.
559    ///
560    /// # Errors
561    ///
562    /// Returns an error if the request fails or the response cannot be parsed.
563    pub async fn get_combos(
564        &self,
565        params: GetCombosParams,
566    ) -> Result<DeribitJsonRpcResponse<Vec<DeribitCombo>>, DeribitHttpError> {
567        self.send_request("public/get_combos", params, false).await
568    }
569
570    /// Gets recent trades for an instrument within a time range.
571    ///
572    /// # Errors
573    ///
574    /// Returns an error if the request fails or the response cannot be parsed.
575    pub async fn get_last_trades_by_instrument_and_time(
576        &self,
577        params: GetLastTradesByInstrumentAndTimeParams,
578    ) -> Result<DeribitJsonRpcResponse<DeribitTradesResponse>, DeribitHttpError> {
579        self.send_request(
580            "public/get_last_trades_by_instrument_and_time",
581            params,
582            false,
583        )
584        .await
585    }
586
587    /// Gets recent trades for a currency, optionally filtered by product kind.
588    ///
589    /// The instrument-and-time variant accepts combo instrument names, but
590    /// this currency-scoped endpoint is the only way to sweep trades across
591    /// all combos of a given kind (e.g., every BTC future combo) in one call.
592    ///
593    /// # Errors
594    ///
595    /// Returns an error if the request fails or the response cannot be parsed.
596    pub async fn get_last_trades_by_currency(
597        &self,
598        params: GetLastTradesByCurrencyParams,
599    ) -> Result<DeribitJsonRpcResponse<DeribitTradesResponse>, DeribitHttpError> {
600        self.send_request("public/get_last_trades_by_currency", params, false)
601            .await
602    }
603
604    /// Gets traded expirations by currency and instrument kind.
605    ///
606    /// # Errors
607    ///
608    /// Returns an error if the request fails or the response cannot be parsed.
609    pub async fn get_expirations(
610        &self,
611        params: GetExpirationsParams,
612    ) -> Result<DeribitJsonRpcResponse<DeribitExpirationsResponse>, DeribitHttpError> {
613        self.send_request("public/get_expirations", params, false)
614            .await
615    }
616
617    /// Gets TradingView chart data (OHLCV) for an instrument.
618    ///
619    /// # Errors
620    ///
621    /// Returns an error if the request fails or the response cannot be parsed.
622    pub async fn get_tradingview_chart_data(
623        &self,
624        params: GetTradingViewChartDataParams,
625    ) -> Result<DeribitJsonRpcResponse<DeribitTradingViewChartData>, DeribitHttpError> {
626        self.send_request("public/get_tradingview_chart_data", params, false)
627            .await
628    }
629
630    /// Gets account summaries for all currencies.
631    ///
632    /// # Errors
633    ///
634    /// Returns an error if:
635    /// - Credentials are missing.
636    /// - Authentication fails (invalid signature, expired timestamp).
637    /// - The request fails or the response cannot be parsed.
638    pub async fn get_account_summaries(
639        &self,
640        params: GetAccountSummariesParams,
641    ) -> Result<DeribitJsonRpcResponse<DeribitAccountSummariesResponse>, DeribitHttpError> {
642        self.send_request("private/get_account_summaries", params, true)
643            .await
644    }
645
646    /// Gets order book for an instrument.
647    ///
648    /// # Errors
649    ///
650    /// Returns an error if the request fails or the response cannot be parsed.
651    pub async fn get_order_book(
652        &self,
653        params: GetOrderBookParams,
654    ) -> Result<DeribitJsonRpcResponse<DeribitOrderBook>, DeribitHttpError> {
655        self.send_request("public/get_order_book", params, false)
656            .await
657    }
658
659    /// Gets a single order by its ID.
660    ///
661    /// # Errors
662    ///
663    /// Returns an error if:
664    /// - Credentials are missing.
665    /// - Authentication fails (invalid signature, expired timestamp).
666    /// - The request fails or the response cannot be parsed.
667    pub async fn get_order_state(
668        &self,
669        params: GetOrderStateParams,
670    ) -> Result<DeribitJsonRpcResponse<DeribitOrderMsg>, DeribitHttpError> {
671        self.send_request("private/get_order_state", params, true)
672            .await
673    }
674
675    /// Gets all open orders across all currencies and instruments.
676    ///
677    /// # Errors
678    ///
679    /// Returns an error if:
680    /// - Credentials are missing.
681    /// - Authentication fails (invalid signature, expired timestamp).
682    /// - The request fails or the response cannot be parsed.
683    pub async fn get_open_orders(
684        &self,
685        params: GetOpenOrdersParams,
686    ) -> Result<DeribitJsonRpcResponse<Vec<DeribitOrderMsg>>, DeribitHttpError> {
687        self.send_request("private/get_open_orders", params, true)
688            .await
689    }
690
691    /// Gets open orders for a specific instrument.
692    ///
693    /// # Errors
694    ///
695    /// Returns an error if:
696    /// - Credentials are missing.
697    /// - Authentication fails (invalid signature, expired timestamp).
698    /// - The request fails or the response cannot be parsed.
699    pub async fn get_open_orders_by_instrument(
700        &self,
701        params: GetOpenOrdersByInstrumentParams,
702    ) -> Result<DeribitJsonRpcResponse<Vec<DeribitOrderMsg>>, DeribitHttpError> {
703        self.send_request("private/get_open_orders_by_instrument", params, true)
704            .await
705    }
706
707    /// Gets historical orders for a specific instrument.
708    ///
709    /// # Errors
710    ///
711    /// Returns an error if:
712    /// - Credentials are missing.
713    /// - Authentication fails (invalid signature, expired timestamp).
714    /// - The request fails or the response cannot be parsed.
715    pub async fn get_order_history_by_instrument(
716        &self,
717        params: GetOrderHistoryByInstrumentParams,
718    ) -> Result<DeribitJsonRpcResponse<Vec<DeribitOrderMsg>>, DeribitHttpError> {
719        self.send_request("private/get_order_history_by_instrument", params, true)
720            .await
721    }
722
723    /// Gets historical orders for a specific currency.
724    ///
725    /// # Errors
726    ///
727    /// Returns an error if:
728    /// - Credentials are missing.
729    /// - Authentication fails (invalid signature, expired timestamp).
730    /// - The request fails or the response cannot be parsed.
731    pub async fn get_order_history_by_currency(
732        &self,
733        params: GetOrderHistoryByCurrencyParams,
734    ) -> Result<DeribitJsonRpcResponse<Vec<DeribitOrderMsg>>, DeribitHttpError> {
735        self.send_request("private/get_order_history_by_currency", params, true)
736            .await
737    }
738
739    /// Gets user trades for a specific instrument within a time range.
740    ///
741    /// # Errors
742    ///
743    /// Returns an error if:
744    /// - Credentials are missing.
745    /// - Authentication fails (invalid signature, expired timestamp).
746    /// - The request fails or the response cannot be parsed.
747    pub async fn get_user_trades_by_instrument_and_time(
748        &self,
749        params: GetUserTradesByInstrumentAndTimeParams,
750    ) -> Result<DeribitJsonRpcResponse<DeribitUserTradesResponse>, DeribitHttpError> {
751        self.send_request(
752            "private/get_user_trades_by_instrument_and_time",
753            params,
754            true,
755        )
756        .await
757    }
758
759    /// Gets user trades for a specific currency within a time range.
760    ///
761    /// # Errors
762    ///
763    /// Returns an error if:
764    /// - Credentials are missing.
765    /// - Authentication fails (invalid signature, expired timestamp).
766    /// - The request fails or the response cannot be parsed.
767    pub async fn get_user_trades_by_currency_and_time(
768        &self,
769        params: GetUserTradesByCurrencyAndTimeParams,
770    ) -> Result<DeribitJsonRpcResponse<DeribitUserTradesResponse>, DeribitHttpError> {
771        self.send_request("private/get_user_trades_by_currency_and_time", params, true)
772            .await
773    }
774
775    /// Gets book summaries for all instruments of a given currency.
776    ///
777    /// # Errors
778    ///
779    /// Returns an error if the request fails or the response cannot be parsed.
780    pub async fn get_book_summary_by_currency(
781        &self,
782        params: GetBookSummaryByCurrencyParams,
783    ) -> Result<DeribitJsonRpcResponse<Vec<DeribitBookSummaryRaw>>, DeribitHttpError> {
784        self.send_request("public/get_book_summary_by_currency", params, false)
785            .await
786    }
787
788    /// Gets ticker data for a single instrument.
789    ///
790    /// # Errors
791    ///
792    /// Returns an error if the request fails or the response cannot be parsed.
793    pub async fn get_ticker(
794        &self,
795        params: GetTickerParams,
796    ) -> Result<DeribitJsonRpcResponse<DeribitTicker>, DeribitHttpError> {
797        self.send_request("public/ticker", params, false).await
798    }
799
800    /// Gets positions for a specific currency.
801    ///
802    /// # Errors
803    ///
804    /// Returns an error if:
805    /// - Credentials are missing.
806    /// - Authentication fails (invalid signature, expired timestamp).
807    /// - The request fails or the response cannot be parsed.
808    pub async fn get_positions(
809        &self,
810        params: GetPositionsParams,
811    ) -> Result<DeribitJsonRpcResponse<Vec<DeribitPosition>>, DeribitHttpError> {
812        self.send_request("private/get_positions", params, true)
813            .await
814    }
815}
816
817/// High-level Deribit HTTP client with domain-level abstractions.
818///
819/// This client wraps the raw HTTP client and provides methods that use Nautilus
820/// domain types. It maintains an instrument cache for efficient lookups.
821#[derive(Debug)]
822#[cfg_attr(
823    feature = "python",
824    pyo3::pyclass(module = "nautilus_trader.adapters.deribit", from_py_object)
825)]
826#[cfg_attr(
827    feature = "python",
828    pyo3_stub_gen::derive::gen_stub_pyclass(module = "nautilus_trader.adapters.deribit")
829)]
830pub struct DeribitHttpClient {
831    pub(crate) inner: Arc<DeribitRawHttpClient>,
832    pub(crate) instruments_cache: Arc<AtomicMap<Ustr, InstrumentAny>>,
833    clock: &'static AtomicTime,
834    cache_initialized: AtomicBool,
835}
836
837impl Clone for DeribitHttpClient {
838    fn clone(&self) -> Self {
839        let cache_initialized = AtomicBool::new(false);
840
841        let is_initialized = self.cache_initialized.load(Ordering::Acquire);
842        if is_initialized {
843            cache_initialized.store(true, Ordering::Release);
844        }
845
846        Self {
847            inner: self.inner.clone(),
848            instruments_cache: self.instruments_cache.clone(),
849            cache_initialized,
850            clock: self.clock,
851        }
852    }
853}
854
855impl DeribitHttpClient {
856    /// Returns a reference to the underlying raw HTTP client.
857    ///
858    /// Exposes low-level endpoint methods (e.g., `get_last_trades_by_currency`)
859    /// that this wrapper does not yet adapt.
860    #[must_use]
861    pub fn inner(&self) -> &DeribitRawHttpClient {
862        &self.inner
863    }
864
865    /// Creates a new [`DeribitHttpClient`] with default configuration.
866    ///
867    /// # Parameters
868    /// - `base_url`: Optional custom base URL (for testing)
869    /// - `environment`: The Deribit environment to connect to
870    ///
871    /// # Errors
872    ///
873    /// Returns an error if the HTTP client cannot be created.
874    pub fn new(
875        base_url: Option<String>,
876        environment: DeribitEnvironment,
877        timeout_secs: u64,
878        max_retries: u32,
879        retry_delay_ms: u64,
880        retry_delay_max_ms: u64,
881        proxy_url: Option<String>,
882    ) -> anyhow::Result<Self> {
883        let raw_client = Arc::new(DeribitRawHttpClient::new(
884            base_url,
885            environment,
886            timeout_secs,
887            max_retries,
888            retry_delay_ms,
889            retry_delay_max_ms,
890            proxy_url,
891        )?);
892
893        Ok(Self {
894            inner: raw_client,
895            instruments_cache: Arc::new(AtomicMap::new()),
896            cache_initialized: AtomicBool::new(false),
897            clock: get_atomic_clock_realtime(),
898        })
899    }
900
901    /// Creates a new [`DeribitHttpClient`] with credentials from environment variables.
902    ///
903    /// If `api_key` or `api_secret` are not provided, they will be loaded from environment:
904    /// - Mainnet: `DERIBIT_API_KEY`, `DERIBIT_API_SECRET`
905    /// - Testnet: `DERIBIT_TESTNET_API_KEY`, `DERIBIT_TESTNET_API_SECRET`
906    ///
907    /// # Errors
908    ///
909    /// Returns an error if:
910    /// - The HTTP client cannot be created.
911    /// - Credentials are not provided and environment variables are not set.
912    #[expect(clippy::too_many_arguments)]
913    pub fn new_with_env(
914        api_key: Option<String>,
915        api_secret: Option<String>,
916        base_url: Option<String>,
917        environment: DeribitEnvironment,
918        timeout_secs: u64,
919        max_retries: u32,
920        retry_delay_ms: u64,
921        retry_delay_max_ms: u64,
922        proxy_url: Option<String>,
923    ) -> anyhow::Result<Self> {
924        let raw_client = Arc::new(DeribitRawHttpClient::new_with_env(
925            api_key,
926            api_secret,
927            base_url,
928            environment,
929            timeout_secs,
930            max_retries,
931            retry_delay_ms,
932            retry_delay_max_ms,
933            proxy_url,
934        )?);
935
936        Ok(Self {
937            inner: raw_client,
938            instruments_cache: Arc::new(AtomicMap::new()),
939            cache_initialized: AtomicBool::new(false),
940            clock: get_atomic_clock_realtime(),
941        })
942    }
943
944    /// Requests instruments for a specific currency.
945    ///
946    /// # Errors
947    ///
948    /// Returns an error if the request fails or instruments cannot be parsed.
949    pub async fn request_instruments(
950        &self,
951        currency: DeribitCurrency,
952        product_type: Option<DeribitProductType>,
953    ) -> anyhow::Result<Vec<InstrumentAny>> {
954        // Build parameters
955        let params = if let Some(pt) = product_type {
956            GetInstrumentsParams::with_kind(currency, pt)
957        } else {
958            GetInstrumentsParams::new(currency)
959        };
960
961        // Call raw client
962        let full_response = self.inner.get_instruments(params).await?;
963        let result = full_response
964            .result
965            .ok_or_else(|| anyhow::anyhow!("No result in response"))?;
966        let ts_event = extract_server_timestamp(full_response.us_out)?;
967        let ts_init = self.generate_ts_init();
968        let combo_by_id = self.combo_map_for_instruments(currency, &result).await;
969
970        // Parse each instrument
971        let mut instruments = Vec::new();
972        let mut skipped_count = 0;
973        let mut error_count = 0;
974
975        for raw_instrument in result {
976            match parse_deribit_instrument_any(&raw_instrument, ts_init, ts_event) {
977                Ok(Some(mut instrument)) => {
978                    if let Some(combo) = combo_by_id.get(&raw_instrument.instrument_name) {
979                        Self::attach_combo_leg_info(&mut instrument, combo);
980                    }
981                    instruments.push(instrument);
982                }
983                Ok(None) => {
984                    // Unsupported instrument type (e.g., combos)
985                    skipped_count += 1;
986                    log::debug!(
987                        "Skipped unsupported instrument type: {} (kind: {:?})",
988                        raw_instrument.instrument_name,
989                        raw_instrument.kind
990                    );
991                }
992                Err(e) => {
993                    error_count += 1;
994                    log::warn!(
995                        "Failed to parse instrument {}: {}",
996                        raw_instrument.instrument_name,
997                        e
998                    );
999                }
1000            }
1001        }
1002
1003        log::debug!(
1004            "Parsed {} instruments ({} skipped, {} errors)",
1005            instruments.len(),
1006            skipped_count,
1007            error_count
1008        );
1009
1010        Ok(instruments)
1011    }
1012
1013    /// Requests a specific instrument by its Nautilus instrument ID.
1014    ///
1015    /// This is a high-level method that fetches the raw instrument data from Deribit
1016    /// and converts it to a Nautilus `InstrumentAny` type.
1017    ///
1018    /// # Errors
1019    ///
1020    /// Returns an error if:
1021    /// - The instrument name format is invalid (error code `-32602`).
1022    /// - The instrument doesn't exist (error code `13020`).
1023    /// - Network or API errors occur.
1024    pub async fn request_instrument(
1025        &self,
1026        instrument_id: InstrumentId,
1027    ) -> anyhow::Result<InstrumentAny> {
1028        let params = GetInstrumentParams {
1029            instrument_name: instrument_id.symbol.to_string(),
1030        };
1031
1032        let full_response = self.inner.get_instrument(params).await?;
1033        let response = full_response
1034            .result
1035            .ok_or_else(|| anyhow::anyhow!("No result in response"))?;
1036        let ts_event = extract_server_timestamp(full_response.us_out)?;
1037        let ts_init = self.generate_ts_init();
1038
1039        match parse_deribit_instrument_any(&response, ts_init, ts_event)? {
1040            Some(mut instrument) => {
1041                if Self::is_combo_kind(response.kind) {
1042                    let currency = DeribitCurrency::from_str(response.base_currency.as_str())
1043                        .unwrap_or(DeribitCurrency::ANY);
1044                    let combo_by_id = self
1045                        .combo_map_for_instruments(currency, std::slice::from_ref(&response))
1046                        .await;
1047
1048                    if let Some(combo) = combo_by_id.get(&response.instrument_name) {
1049                        Self::attach_combo_leg_info(&mut instrument, combo);
1050                    }
1051                }
1052
1053                Ok(instrument)
1054            }
1055            None => anyhow::bail!(
1056                "Unsupported instrument type: {} (kind: {:?})",
1057                response.instrument_name,
1058                response.kind
1059            ),
1060        }
1061    }
1062
1063    async fn combo_map_for_instruments(
1064        &self,
1065        requested_currency: DeribitCurrency,
1066        raw_instruments: &[DeribitInstrument],
1067    ) -> AHashMap<Ustr, DeribitCombo> {
1068        if !raw_instruments
1069            .iter()
1070            .any(|instrument| Self::is_combo_kind(instrument.kind))
1071        {
1072            return AHashMap::new();
1073        }
1074
1075        let currencies = if requested_currency == DeribitCurrency::ANY {
1076            raw_instruments
1077                .iter()
1078                .filter(|instrument| Self::is_combo_kind(instrument.kind))
1079                .filter_map(|instrument| {
1080                    DeribitCurrency::from_str(instrument.base_currency.as_str()).ok()
1081                })
1082                .collect()
1083        } else {
1084            AHashSet::from([requested_currency])
1085        };
1086
1087        let mut combo_by_id = AHashMap::new();
1088
1089        for currency in currencies {
1090            let response = match self.inner.get_combos(GetCombosParams::new(currency)).await {
1091                Ok(response) => response,
1092                Err(e) => {
1093                    log::warn!("Failed to load Deribit combo definitions for {currency}: {e}");
1094                    continue;
1095                }
1096            };
1097
1098            let Some(combos) = response.result else {
1099                continue;
1100            };
1101
1102            for combo in combos {
1103                combo_by_id.insert(combo.id, combo);
1104            }
1105        }
1106
1107        combo_by_id
1108    }
1109
1110    fn is_combo_kind(kind: DeribitProductType) -> bool {
1111        matches!(
1112            kind,
1113            DeribitProductType::FutureCombo | DeribitProductType::OptionCombo
1114        )
1115    }
1116
1117    fn attach_combo_leg_info(instrument: &mut InstrumentAny, combo: &DeribitCombo) {
1118        let info = match instrument {
1119            InstrumentAny::CryptoOptionSpread(spread) => &mut spread.info,
1120            InstrumentAny::CryptoFuturesSpread(spread) => &mut spread.info,
1121            _ => return,
1122        };
1123
1124        let mut merged = info.as_ref().map_or_default(|info| IndexMap::clone(info));
1125
1126        let legs = combo
1127            .legs
1128            .iter()
1129            .map(|leg| {
1130                let instrument_id =
1131                    InstrumentId::new(Symbol::new(leg.instrument_name), *DERIBIT_VENUE);
1132
1133                json!({
1134                    "amount": leg.amount,
1135                    "instrument_id": instrument_id.to_string(),
1136                    "instrument_name": leg.instrument_name,
1137                })
1138            })
1139            .collect::<Vec<_>>();
1140
1141        merged.insert("deribit_combo_id".to_string(), json!(combo.id));
1142        merged.insert(
1143            "deribit_combo_state".to_string(),
1144            json!(combo.state.as_str()),
1145        );
1146        merged.insert("deribit_combo_legs".to_string(), json!(legs));
1147        *info = Some(Params::new(merged));
1148    }
1149
1150    /// Requests historical trades for an instrument within a time range.
1151    ///
1152    /// Fetches trade ticks from Deribit and converts them to Nautilus [`TradeTick`] objects.
1153    ///
1154    /// # Arguments
1155    ///
1156    /// * `instrument_id` - The instrument to fetch trades for
1157    /// * `start` - Optional start time filter
1158    /// * `end` - Optional end time filter
1159    /// * `limit` - Optional limit on number of trades (max 1000)
1160    ///
1161    /// # Errors
1162    ///
1163    /// Returns an error if:
1164    /// - The instrument is not found in cache.
1165    /// - The request fails.
1166    /// - Trade parsing fails.
1167    ///
1168    /// # Pagination
1169    ///
1170    /// When `limit` is `None`, this function automatically paginates through all available
1171    /// trades in the time range using the `has_more` field from the API response.
1172    /// When `limit` is specified, pagination stops once that many trades are collected.
1173    pub async fn request_trades(
1174        &self,
1175        instrument_id: InstrumentId,
1176        start: Option<Timestamp>,
1177        end: Option<Timestamp>,
1178        limit: Option<u32>,
1179    ) -> anyhow::Result<Vec<TradeTick>> {
1180        // Get instrument from cache to determine precisions
1181        let (price_precision, size_precision) =
1182            if let Some(instrument) = self.get_instrument(&instrument_id.symbol.inner()) {
1183                capabilities::validate_public_trades(&instrument)?;
1184                (instrument.price_precision(), instrument.size_precision())
1185            } else {
1186                log::warn!("Instrument {instrument_id} not in cache, skipping trades request");
1187                return Err(InstrumentLookupError::not_found(instrument_id).into());
1188            };
1189
1190        // Convert timestamps to milliseconds
1191        let now = Timestamp::now();
1192        let end_dt = end.unwrap_or(now);
1193        let start_dt = start.unwrap_or(end_dt - jiff::SignedDuration::from_hours(1));
1194
1195        if let (Some(s), Some(e)) = (start, end) {
1196            anyhow::ensure!(s < e, "Invalid time range: start={s:?} end={e:?}");
1197        }
1198
1199        let start_ms = start_dt.as_millisecond();
1200        let end_ms = end_dt.as_millisecond();
1201        let ts_init = self.generate_ts_init();
1202        let mut all_trades = Vec::new();
1203        let mut paginator = TradePaginator::new(start_ms, end_ms);
1204
1205        loop {
1206            let params = GetLastTradesByInstrumentAndTimeParams::new(
1207                instrument_id.symbol.to_string(),
1208                paginator.cursor,
1209                end_ms,
1210                Some(DERIBIT_HISTORICAL_TRADES_MAX_COUNT),
1211                Some("asc".to_string()),
1212            );
1213
1214            let full_response = self
1215                .inner
1216                .get_last_trades_by_instrument_and_time(params)
1217                .await
1218                .map_err(|e| anyhow::anyhow!(e))?;
1219
1220            let response_data = full_response
1221                .result
1222                .ok_or_else(|| anyhow::anyhow!("No result in response"))?;
1223
1224            let ids: Vec<String> = response_data
1225                .trades
1226                .iter()
1227                .map(|t| t.trade_id.clone())
1228                .collect();
1229            let timestamps: Vec<i64> = response_data.trades.iter().map(|t| t.timestamp).collect();
1230
1231            let Some(new_indices) = paginator.advance(&ids, &timestamps, response_data.has_more)
1232            else {
1233                break;
1234            };
1235
1236            for i in &new_indices {
1237                let raw_trade = &response_data.trades[*i];
1238
1239                match parse_trade_tick(
1240                    raw_trade,
1241                    instrument_id,
1242                    price_precision,
1243                    size_precision,
1244                    ts_init,
1245                ) {
1246                    Ok(trade) => {
1247                        all_trades.push(trade);
1248
1249                        if let Some(max) = limit
1250                            && all_trades.len() >= max as usize
1251                        {
1252                            return Ok(all_trades);
1253                        }
1254                    }
1255                    Err(e) => {
1256                        log::warn!(
1257                            "Failed to parse trade {} for {}: {}",
1258                            raw_trade.trade_id,
1259                            instrument_id,
1260                            e
1261                        );
1262                    }
1263                }
1264            }
1265
1266            if !response_data.has_more || paginator.is_exhausted() {
1267                break;
1268            }
1269        }
1270
1271        log::debug!(
1272            "Fetched {} historical trades for {} from {} to {}",
1273            all_trades.len(),
1274            instrument_id,
1275            start_dt,
1276            end_dt
1277        );
1278
1279        Ok(all_trades)
1280    }
1281
1282    /// Requests historical bars (OHLCV) for an instrument.
1283    ///
1284    /// Uses the `public/get_tradingview_chart_data` endpoint to fetch candlestick data.
1285    ///
1286    /// # Errors
1287    ///
1288    /// Returns an error if:
1289    /// - Aggregation source is not EXTERNAL.
1290    /// - Bar aggregation type is not supported by Deribit.
1291    /// - The instrument is not found in cache.
1292    /// - The request fails or response cannot be parsed.
1293    ///
1294    /// # Supported Resolutions
1295    ///
1296    /// Deribit supports: 1, 3, 5, 10, 15, 30, 60, 120, 180, 360, 720 minutes, and 1D (daily)
1297    pub async fn request_bars(
1298        &self,
1299        bar_type: BarType,
1300        start: Option<Timestamp>,
1301        end: Option<Timestamp>,
1302        limit: Option<u32>,
1303    ) -> anyhow::Result<Vec<Bar>> {
1304        anyhow::ensure!(
1305            bar_type.aggregation_source() == AggregationSource::External,
1306            "Only EXTERNAL aggregation is supported"
1307        );
1308
1309        let now = Timestamp::now();
1310
1311        // Default to last hour if no start/end provided
1312        let end_dt = end.unwrap_or(now);
1313        let start_dt = start.unwrap_or(end_dt - jiff::SignedDuration::from_hours(1));
1314
1315        if let (Some(s), Some(e)) = (start, end) {
1316            anyhow::ensure!(s < e, "Invalid time range: start={s:?} end={e:?}");
1317        }
1318
1319        // Convert BarType to Deribit resolution
1320        let spec = bar_type.spec();
1321        let step = spec.step.get();
1322        let resolution = match spec.aggregation {
1323            BarAggregation::Minute => format!("{step}"),
1324            BarAggregation::Hour => format!("{}", step * 60),
1325            BarAggregation::Day => "1D".to_string(),
1326            a => anyhow::bail!("Deribit does not support {a:?} aggregation"),
1327        };
1328
1329        // Validate resolution is supported by Deribit
1330        let supported_resolutions = [
1331            "1", "3", "5", "10", "15", "30", "60", "120", "180", "360", "720", "1D",
1332        ];
1333
1334        if !supported_resolutions.contains(&resolution.as_str()) {
1335            anyhow::bail!(
1336                "Deribit does not support resolution '{resolution}'. Supported: {supported_resolutions:?}"
1337            );
1338        }
1339
1340        let instrument_id = bar_type.instrument_id();
1341
1342        let (price_precision, size_precision, use_cost_for_volume) =
1343            if let Some(instrument) = self.get_instrument(&instrument_id.symbol.inner()) {
1344                capabilities::validate_public_trades(&instrument)?;
1345                (
1346                    instrument.price_precision(),
1347                    instrument.size_precision(),
1348                    use_cost_for_bar_volume(&instrument),
1349                )
1350            } else {
1351                log::warn!("Instrument {instrument_id} not in cache, skipping bars request");
1352                return Err(InstrumentLookupError::not_found(instrument_id).into());
1353            };
1354
1355        let instrument_name = instrument_id.symbol.to_string();
1356        let start_timestamp = start_dt.as_millisecond();
1357        let end_timestamp = end_dt.as_millisecond();
1358
1359        let params = GetTradingViewChartDataParams::new(
1360            instrument_name,
1361            start_timestamp,
1362            end_timestamp,
1363            resolution,
1364        );
1365
1366        let full_response = self.inner.get_tradingview_chart_data(params).await?;
1367        let chart_data = full_response
1368            .result
1369            .ok_or_else(|| anyhow::anyhow!("No result in response"))?;
1370
1371        if chart_data.status == "no_data" {
1372            log::debug!("No bar data returned for {bar_type}");
1373            return Ok(Vec::new());
1374        }
1375
1376        let ts_init = self.generate_ts_init();
1377        let mut bars = parse_bars(
1378            &chart_data,
1379            bar_type,
1380            price_precision,
1381            size_precision,
1382            use_cost_for_volume,
1383            ts_init,
1384        )?;
1385
1386        if let Some(max) = limit {
1387            let max = max as usize;
1388            if bars.len() > max {
1389                bars.drain(..bars.len() - max);
1390            }
1391        }
1392
1393        log::debug!("Parsed {} bars for {}", bars.len(), bar_type);
1394
1395        Ok(bars)
1396    }
1397
1398    /// Requests a snapshot of the order book for an instrument.
1399    ///
1400    /// Fetches the order book from Deribit and converts it to a Nautilus [`OrderBook`].
1401    ///
1402    /// # Arguments
1403    ///
1404    /// * `instrument_id` - The instrument to fetch the order book for
1405    /// * `depth` - Optional depth limit (valid values: 1, 5, 10, 20, 50, 100, 1000, 10000)
1406    ///
1407    /// # Errors
1408    ///
1409    /// Returns an error if:
1410    /// - The instrument is not found in cache.
1411    /// - The request fails.
1412    /// - Order book parsing fails.
1413    pub async fn request_book_snapshot(
1414        &self,
1415        instrument_id: InstrumentId,
1416        depth: Option<u32>,
1417    ) -> anyhow::Result<OrderBook> {
1418        let (price_precision, size_precision) =
1419            if let Some(instrument) = self.get_instrument(&instrument_id.symbol.inner()) {
1420                (instrument.price_precision(), instrument.size_precision())
1421            } else {
1422                return Err(InstrumentLookupError::not_found(instrument_id).into());
1423            };
1424
1425        let params = GetOrderBookParams::new(instrument_id.symbol.to_string(), depth);
1426        let full_response = self
1427            .inner
1428            .get_order_book(params)
1429            .await
1430            .map_err(|e| anyhow::anyhow!(e))?;
1431
1432        let order_book_data = full_response
1433            .result
1434            .ok_or_else(|| anyhow::anyhow!("No result in response"))?;
1435
1436        let ts_init = self.generate_ts_init();
1437        let book = parse_order_book(
1438            &order_book_data,
1439            instrument_id,
1440            price_precision,
1441            size_precision,
1442            ts_init,
1443        )?;
1444
1445        log::debug!(
1446            "Fetched order book for {} with {} bids and {} asks",
1447            instrument_id,
1448            order_book_data.bids.len(),
1449            order_book_data.asks.len()
1450        );
1451
1452        Ok(book)
1453    }
1454
1455    /// Requests account state for all currencies.
1456    ///
1457    /// Fetches account balance and margin information for all currencies from Deribit
1458    /// and converts it to Nautilus [`AccountState`] event.
1459    ///
1460    /// # Errors
1461    ///
1462    /// Returns an error if:
1463    /// - The request fails.
1464    /// - Currency conversion fails.
1465    pub async fn request_account_state(
1466        &self,
1467        account_id: AccountId,
1468    ) -> anyhow::Result<AccountState> {
1469        let params = GetAccountSummariesParams::default();
1470        let full_response = self
1471            .inner
1472            .get_account_summaries(params)
1473            .await
1474            .map_err(|e| anyhow::anyhow!(e))?;
1475        let response_data = full_response
1476            .result
1477            .ok_or_else(|| anyhow::anyhow!("No result in response"))?;
1478        let ts_init = self.generate_ts_init();
1479        let ts_event = extract_server_timestamp(full_response.us_out)?;
1480
1481        parse_account_state(&response_data.summaries, account_id, ts_init, ts_event)
1482    }
1483
1484    /// Generates a timestamp for initialization.
1485    fn generate_ts_init(&self) -> UnixNanos {
1486        self.clock.get_time_ns()
1487    }
1488
1489    /// Caches instruments for later retrieval.
1490    pub fn cache_instruments(&self, instruments: &[InstrumentAny]) {
1491        self.instruments_cache.rcu(|m| {
1492            for inst in instruments {
1493                m.insert(inst.raw_symbol().inner(), inst.clone());
1494            }
1495        });
1496        self.cache_initialized.store(true, Ordering::Release);
1497    }
1498
1499    /// Retrieves a cached instrument by symbol.
1500    #[must_use]
1501    pub fn get_instrument(&self, symbol: &Ustr) -> Option<InstrumentAny> {
1502        self.instruments_cache.get_cloned(symbol)
1503    }
1504
1505    /// Checks if the instrument cache has been initialized.
1506    #[must_use]
1507    pub fn is_cache_initialized(&self) -> bool {
1508        self.cache_initialized.load(Ordering::Acquire)
1509    }
1510
1511    /// Returns whether this client is connected to testnet.
1512    #[must_use]
1513    pub fn is_testnet(&self) -> bool {
1514        self.inner.is_testnet()
1515    }
1516
1517    /// Requests order status reports for reconciliation.
1518    ///
1519    /// Fetches order statuses from Deribit and converts them to Nautilus [`OrderStatusReport`].
1520    /// Every instrument is in scope. An unresolved open order fails the request. An unresolved
1521    /// closed order inside the request window also fails the request.
1522    ///
1523    /// # Strategy
1524    /// - Uses `/private/get_open_orders` for all open orders (single efficient API call)
1525    /// - Uses `/private/get_open_orders_by_instrument` when specific instrument is provided
1526    /// - For historical orders (when `open_only=false`), iterates over currencies
1527    ///
1528    /// # Errors
1529    ///
1530    /// Returns an error if:
1531    /// - The request fails.
1532    /// - An in-scope open order cannot be resolved.
1533    /// - An in-scope closed order inside the request window cannot be resolved.
1534    pub async fn request_order_status_reports(
1535        &self,
1536        account_id: AccountId,
1537        instrument_id: Option<InstrumentId>,
1538        start: Option<UnixNanos>,
1539        end: Option<UnixNanos>,
1540        open_only: bool,
1541    ) -> anyhow::Result<Vec<OrderStatusReport>> {
1542        let read = self
1543            .request_order_status_reports_in_scope(
1544                account_id,
1545                instrument_id,
1546                start,
1547                end,
1548                open_only,
1549                ReconciliationScope::unrestricted(),
1550            )
1551            .await?;
1552
1553        read.into_reports()
1554    }
1555
1556    /// Requests order status reports and reports in-window historical instrument misses.
1557    ///
1558    /// Records outside `scope` are omitted. An in-scope open order whose instrument is not cached
1559    /// fails the read. An in-scope closed order inside the request window whose instrument is not
1560    /// cached is omitted and recorded on [`ReportRead::historical_misses`]. This method does not
1561    /// request the missing instrument from the venue.
1562    ///
1563    /// # Errors
1564    ///
1565    /// Returns an error if the request fails or an in-scope open order cannot be resolved. No
1566    /// reports are returned in that case. A cached order that cannot be parsed is omitted.
1567    pub(crate) async fn request_order_status_reports_in_scope(
1568        &self,
1569        account_id: AccountId,
1570        instrument_id: Option<InstrumentId>,
1571        start: Option<UnixNanos>,
1572        end: Option<UnixNanos>,
1573        open_only: bool,
1574        scope: ReconciliationScope,
1575    ) -> anyhow::Result<ReportRead<OrderStatusReport>> {
1576        let ts_init = self.generate_ts_init();
1577        let mut reports = Vec::new();
1578        let mut seen_order_ids = AHashSet::new();
1579        let mut historical_misses = Vec::new();
1580
1581        let mut parse_and_add = |order: &DeribitOrderMsg| -> anyhow::Result<()> {
1582            self.accept_order_report(
1583                order,
1584                account_id,
1585                instrument_id,
1586                start,
1587                end,
1588                ts_init,
1589                &scope,
1590                &mut seen_order_ids,
1591                &mut reports,
1592                &mut historical_misses,
1593            )
1594        };
1595
1596        if let Some(instrument_id) = instrument_id {
1597            self.collect_instrument_order_reports(instrument_id, open_only, &mut parse_and_add)
1598                .await?;
1599        } else {
1600            self.collect_account_order_reports(open_only, &mut parse_and_add)
1601                .await?;
1602        }
1603
1604        log::debug!("Generated {} order status reports", reports.len());
1605        Ok(ReportRead {
1606            reports,
1607            historical_misses,
1608        })
1609    }
1610
1611    #[expect(clippy::too_many_arguments)]
1612    fn accept_order_report(
1613        &self,
1614        order: &DeribitOrderMsg,
1615        account_id: AccountId,
1616        instrument_id: Option<InstrumentId>,
1617        start: Option<UnixNanos>,
1618        end: Option<UnixNanos>,
1619        ts_init: UnixNanos,
1620        scope: &ReconciliationScope,
1621        seen_order_ids: &mut AHashSet<String>,
1622        reports: &mut Vec<OrderStatusReport>,
1623        historical_misses: &mut Vec<InstrumentId>,
1624    ) -> anyhow::Result<()> {
1625        let record_id = instrument_id_from_name(order.instrument_name);
1626
1627        if instrument_id.is_some_and(|id| id != record_id) {
1628            return Ok(());
1629        }
1630
1631        if !scope.includes(record_id) {
1632            log::debug!("Skipping report for out-of-scope instrument {record_id}");
1633            return Ok(());
1634        }
1635
1636        let Some(instrument) = self.get_instrument(&order.instrument_name) else {
1637            if !is_historical_order_state(order.order_state.as_str()) {
1638                anyhow::bail!(
1639                    "Open order {} has unresolved instrument {record_id}",
1640                    order.order_id
1641                );
1642            }
1643
1644            if millis_in_window(order.last_update_timestamp, start, end) {
1645                record_historical_miss(historical_misses, record_id);
1646            }
1647
1648            return Ok(());
1649        };
1650
1651        match parse_user_order_msg(order, &instrument, account_id, ts_init) {
1652            Ok(report) if timestamp_in_window(report.ts_last, start, end) => {
1653                if seen_order_ids.insert(order.order_id.clone()) {
1654                    reports.push(report);
1655                }
1656            }
1657            Ok(_) => {}
1658            Err(e) => {
1659                log::warn!(
1660                    "Failed to parse order {} for {}: {}",
1661                    order.order_id,
1662                    order.instrument_name,
1663                    e
1664                );
1665            }
1666        }
1667
1668        Ok(())
1669    }
1670
1671    async fn collect_instrument_order_reports(
1672        &self,
1673        instrument_id: InstrumentId,
1674        open_only: bool,
1675        parse_and_add: &mut impl FnMut(&DeribitOrderMsg) -> anyhow::Result<()>,
1676    ) -> anyhow::Result<()> {
1677        let instrument_name = instrument_id.symbol.to_string();
1678
1679        let open_params = GetOpenOrdersByInstrumentParams {
1680            instrument_name: instrument_name.clone(),
1681            r#type: None,
1682        };
1683
1684        if let Some(orders) = self
1685            .inner
1686            .get_open_orders_by_instrument(open_params)
1687            .await?
1688            .result
1689        {
1690            for order in &orders {
1691                parse_and_add(order)?;
1692            }
1693        }
1694
1695        if open_only {
1696            return Ok(());
1697        }
1698
1699        let mut offset = 0;
1700
1701        loop {
1702            let history_params = GetOrderHistoryByInstrumentParams {
1703                instrument_name: instrument_name.clone(),
1704                count: Some(ORDER_HISTORY_PAGE_SIZE),
1705                offset: Some(offset),
1706                include_old: Some(true),
1707                include_unfilled: Some(true),
1708            };
1709
1710            let orders = self
1711                .inner
1712                .get_order_history_by_instrument(history_params)
1713                .await?
1714                .result
1715                .unwrap_or_default();
1716            let count = orders.len() as u32;
1717            for order in &orders {
1718                parse_and_add(order)?;
1719            }
1720
1721            if count < ORDER_HISTORY_PAGE_SIZE {
1722                break;
1723            }
1724
1725            offset += count;
1726        }
1727
1728        Ok(())
1729    }
1730
1731    async fn collect_account_order_reports(
1732        &self,
1733        open_only: bool,
1734        parse_and_add: &mut impl FnMut(&DeribitOrderMsg) -> anyhow::Result<()>,
1735    ) -> anyhow::Result<()> {
1736        if let Some(orders) = self
1737            .inner
1738            .get_open_orders(GetOpenOrdersParams::default())
1739            .await?
1740            .result
1741        {
1742            for order in &orders {
1743                parse_and_add(order)?;
1744            }
1745        }
1746
1747        if open_only {
1748            return Ok(());
1749        }
1750
1751        for currency in DeribitCurrency::iter().filter(|currency| *currency != DeribitCurrency::ANY)
1752        {
1753            let mut offset = 0;
1754
1755            loop {
1756                let history_params = GetOrderHistoryByCurrencyParams {
1757                    currency,
1758                    kind: None,
1759                    count: Some(ORDER_HISTORY_PAGE_SIZE),
1760                    offset: Some(offset),
1761                    include_old: Some(true),
1762                    include_unfilled: Some(true),
1763                };
1764
1765                let orders = self
1766                    .inner
1767                    .get_order_history_by_currency(history_params)
1768                    .await?
1769                    .result
1770                    .unwrap_or_default();
1771                let count = orders.len() as u32;
1772                for order in &orders {
1773                    parse_and_add(order)?;
1774                }
1775
1776                if count < ORDER_HISTORY_PAGE_SIZE {
1777                    break;
1778                }
1779
1780                offset += count;
1781            }
1782        }
1783
1784        Ok(())
1785    }
1786
1787    /// Requests fill reports for reconciliation.
1788    ///
1789    /// Fetches user trades from Deribit and converts them to Nautilus [`FillReport`].
1790    /// Automatically paginates through all results using time-cursor advancement.
1791    ///
1792    /// Every instrument is in scope. A trade whose instrument is not cached is an unresolved
1793    /// historical record and fails this request. A trade for a cached instrument that cannot be
1794    /// parsed, including a commission outside the representable money range, also fails the
1795    /// request. No fill reports are returned.
1796    ///
1797    /// # Strategy
1798    /// - Uses `/private/get_user_trades_by_instrument_and_time` when instrument is provided
1799    /// - Otherwise iterates over currencies using `/private/get_user_trades_by_currency_and_time`
1800    ///
1801    /// # Errors
1802    ///
1803    /// Returns an error if:
1804    /// - The request fails.
1805    /// - A trade for a cached instrument cannot be parsed.
1806    /// - An in-scope trade inside the request window cannot be resolved.
1807    pub async fn request_fill_reports(
1808        &self,
1809        account_id: AccountId,
1810        instrument_id: Option<InstrumentId>,
1811        start: Option<UnixNanos>,
1812        end: Option<UnixNanos>,
1813    ) -> anyhow::Result<Vec<FillReport>> {
1814        let read = self
1815            .request_fill_reports_scoped(
1816                account_id,
1817                instrument_id,
1818                start,
1819                end,
1820                None,
1821                ReconciliationScope::unrestricted(),
1822            )
1823            .await?;
1824
1825        read.into_reports()
1826    }
1827
1828    /// Requests fill reports, optionally limited to one venue order.
1829    ///
1830    /// When `venue_order_id` is set, trades for other orders are omitted before trade parsing.
1831    /// A trade-parse failure for an omitted order does not fail the request. A response that
1832    /// cannot be decoded still fails the request.
1833    ///
1834    /// Records outside `scope` are omitted. An in-scope trade inside the request window whose
1835    /// instrument is not cached is omitted and recorded on [`ReportRead::historical_misses`]. A
1836    /// commission conversion failure for a cached trade still fails the request and is not recorded
1837    /// as incomplete history. This method does not request the missing instrument from the venue.
1838    ///
1839    /// # Errors
1840    ///
1841    /// Returns an error if:
1842    /// - The request fails.
1843    /// - A requested cached trade cannot be parsed.
1844    pub(crate) async fn request_fill_reports_scoped(
1845        &self,
1846        account_id: AccountId,
1847        instrument_id: Option<InstrumentId>,
1848        start: Option<UnixNanos>,
1849        end: Option<UnixNanos>,
1850        venue_order_id: Option<&VenueOrderId>,
1851        scope: ReconciliationScope,
1852    ) -> anyhow::Result<ReportRead<FillReport>> {
1853        let ts_init = self.generate_ts_init();
1854        let now_ms = Timestamp::now().as_millisecond();
1855
1856        // Convert UnixNanos to milliseconds for Deribit API
1857        let start_ms = start.map_or(0, |ns| nanos_to_millis(ns.as_u64()) as i64);
1858        let end_ms = end.map_or(now_ms, |ns| nanos_to_millis(ns.as_u64()) as i64);
1859        let mut reports = Vec::new();
1860        let mut historical_misses = Vec::new();
1861
1862        let mut parse_and_add = |trade: &DeribitUserTradeMsg| -> anyhow::Result<()> {
1863            self.accept_fill_report(
1864                trade,
1865                account_id,
1866                instrument_id,
1867                start,
1868                end,
1869                ts_init,
1870                venue_order_id,
1871                &scope,
1872                &mut reports,
1873                &mut historical_misses,
1874            )
1875        };
1876
1877        let mut paginator = TradePaginator::new(start_ms, end_ms);
1878
1879        if let Some(instrument_id) = instrument_id {
1880            self.collect_instrument_fill_reports(
1881                instrument_id,
1882                end_ms,
1883                &mut paginator,
1884                &mut parse_and_add,
1885            )
1886            .await?;
1887        } else {
1888            self.collect_account_fill_reports(start_ms, end_ms, &mut paginator, &mut parse_and_add)
1889                .await?;
1890        }
1891
1892        log::debug!("Generated {} fill reports", reports.len());
1893        Ok(ReportRead {
1894            reports,
1895            historical_misses,
1896        })
1897    }
1898
1899    #[expect(clippy::too_many_arguments)]
1900    fn accept_fill_report(
1901        &self,
1902        trade: &DeribitUserTradeMsg,
1903        account_id: AccountId,
1904        instrument_id: Option<InstrumentId>,
1905        start: Option<UnixNanos>,
1906        end: Option<UnixNanos>,
1907        ts_init: UnixNanos,
1908        venue_order_id: Option<&VenueOrderId>,
1909        scope: &ReconciliationScope,
1910        reports: &mut Vec<FillReport>,
1911        historical_misses: &mut Vec<InstrumentId>,
1912    ) -> anyhow::Result<()> {
1913        if venue_order_id.is_some_and(|order_id| trade.order_id != order_id.as_str()) {
1914            return Ok(());
1915        }
1916
1917        let record_id = instrument_id_from_name(trade.instrument_name);
1918
1919        if instrument_id.is_some_and(|id| id != record_id) {
1920            return Ok(());
1921        }
1922
1923        if !scope.includes(record_id) {
1924            log::debug!("Skipping report for out-of-scope instrument {record_id}");
1925            return Ok(());
1926        }
1927
1928        let Some(instrument) = self.get_instrument(&trade.instrument_name) else {
1929            if millis_in_window(trade.timestamp, start, end) {
1930                record_historical_miss(historical_misses, record_id);
1931            }
1932
1933            return Ok(());
1934        };
1935
1936        let report =
1937            parse_user_trade_msg(trade, &instrument, account_id, ts_init).with_context(|| {
1938                format!(
1939                    "failed to parse trade {} for {}",
1940                    trade.trade_id, trade.instrument_name
1941                )
1942            })?;
1943
1944        reports.push(report);
1945        Ok(())
1946    }
1947
1948    async fn collect_instrument_fill_reports(
1949        &self,
1950        instrument_id: InstrumentId,
1951        end_ms: i64,
1952        paginator: &mut TradePaginator,
1953        parse_and_add: &mut impl FnMut(&DeribitUserTradeMsg) -> anyhow::Result<()>,
1954    ) -> anyhow::Result<()> {
1955        loop {
1956            let params = GetUserTradesByInstrumentAndTimeParams {
1957                instrument_name: instrument_id.symbol.to_string(),
1958                start_timestamp: paginator.cursor,
1959                end_timestamp: end_ms,
1960                count: Some(DERIBIT_HISTORICAL_TRADES_MAX_COUNT),
1961                sorting: Some("asc".to_string()),
1962            };
1963
1964            let Some(data) = self
1965                .inner
1966                .get_user_trades_by_instrument_and_time(params)
1967                .await?
1968                .result
1969            else {
1970                break;
1971            };
1972
1973            if !Self::consume_trade_page(&data, paginator, parse_and_add)? {
1974                break;
1975            }
1976        }
1977
1978        Ok(())
1979    }
1980
1981    async fn collect_account_fill_reports(
1982        &self,
1983        start_ms: i64,
1984        end_ms: i64,
1985        paginator: &mut TradePaginator,
1986        parse_and_add: &mut impl FnMut(&DeribitUserTradeMsg) -> anyhow::Result<()>,
1987    ) -> anyhow::Result<()> {
1988        for currency in DeribitCurrency::iter().filter(|currency| *currency != DeribitCurrency::ANY)
1989        {
1990            paginator.reset(start_ms);
1991
1992            loop {
1993                let params = GetUserTradesByCurrencyAndTimeParams {
1994                    currency,
1995                    start_timestamp: paginator.cursor,
1996                    end_timestamp: end_ms,
1997                    kind: None,
1998                    count: Some(DERIBIT_HISTORICAL_TRADES_MAX_COUNT),
1999                    sorting: Some("asc".to_string()),
2000                };
2001
2002                let Some(data) = self
2003                    .inner
2004                    .get_user_trades_by_currency_and_time(params)
2005                    .await?
2006                    .result
2007                else {
2008                    break;
2009                };
2010
2011                if !Self::consume_trade_page(&data, paginator, parse_and_add)? {
2012                    break;
2013                }
2014            }
2015        }
2016
2017        Ok(())
2018    }
2019
2020    fn consume_trade_page(
2021        data: &DeribitUserTradesResponse,
2022        paginator: &mut TradePaginator,
2023        parse_and_add: &mut impl FnMut(&DeribitUserTradeMsg) -> anyhow::Result<()>,
2024    ) -> anyhow::Result<bool> {
2025        let ids: Vec<String> = data
2026            .trades
2027            .iter()
2028            .map(|trade| trade.trade_id.clone())
2029            .collect();
2030        let timestamps: Vec<i64> = data
2031            .trades
2032            .iter()
2033            .map(|trade| trade.timestamp as i64)
2034            .collect();
2035
2036        let Some(new_indices) = paginator.advance(&ids, &timestamps, data.has_more) else {
2037            return Ok(false);
2038        };
2039
2040        for index in new_indices {
2041            parse_and_add(&data.trades[index])?;
2042        }
2043
2044        Ok(data.has_more && !paginator.is_exhausted())
2045    }
2046
2047    /// Requests ticker data for a single instrument.
2048    ///
2049    /// Returns the `DeribitTicker` including its option-chain reference price.
2050    ///
2051    /// # Errors
2052    ///
2053    /// Returns an error if the request fails.
2054    pub async fn request_ticker(&self, instrument_name: &str) -> anyhow::Result<DeribitTicker> {
2055        let params = GetTickerParams {
2056            instrument_name: instrument_name.to_string(),
2057        };
2058        let response = self
2059            .inner
2060            .get_ticker(params)
2061            .await
2062            .map_err(|e| anyhow::anyhow!(e))?;
2063        response
2064            .result
2065            .ok_or_else(|| anyhow::anyhow!("No result in ticker response"))
2066    }
2067
2068    /// Requests book summaries for a currency via `public/get_book_summary_by_currency`.
2069    ///
2070    /// Defaults to product kind `option`.
2071    /// Entries include mark/IV, bid-ask, volumes, and `underlying_price` (forward) when present.
2072    ///
2073    /// # Errors
2074    ///
2075    /// Returns an error if the request fails.
2076    pub async fn request_book_summaries(
2077        &self,
2078        currency: &str,
2079    ) -> anyhow::Result<Vec<DeribitBookSummaryRaw>> {
2080        self.request_book_summaries_kind(currency, Some("option"))
2081            .await
2082    }
2083
2084    /// Requests book summaries for a currency with an optional product `kind` filter.
2085    ///
2086    /// When `kind` is `None`, Deribit returns summaries for all product kinds.
2087    ///
2088    /// # Errors
2089    ///
2090    /// Returns an error if the request fails.
2091    pub async fn request_book_summaries_kind(
2092        &self,
2093        currency: &str,
2094        kind: Option<&str>,
2095    ) -> anyhow::Result<Vec<DeribitBookSummaryRaw>> {
2096        let params = GetBookSummaryByCurrencyParams {
2097            currency: currency.to_string(),
2098            kind: kind.map(str::to_string),
2099        };
2100        let full_response = self
2101            .inner
2102            .get_book_summary_by_currency(params)
2103            .await
2104            .map_err(|e| anyhow::anyhow!(e))?;
2105        full_response
2106            .result
2107            .ok_or_else(|| anyhow::anyhow!("No result in book summary response"))
2108    }
2109
2110    /// Requests traded option expirations for a settlement currency.
2111    ///
2112    /// # Errors
2113    ///
2114    /// Returns an error if the request fails.
2115    pub async fn request_option_expirations(
2116        &self,
2117        currency: DeribitCurrency,
2118    ) -> anyhow::Result<Vec<String>> {
2119        let params = GetExpirationsParams::new(currency.as_str(), DeribitExpirationKind::Option);
2120        let full_response = self
2121            .inner
2122            .get_expirations(params)
2123            .await
2124            .map_err(|e| anyhow::anyhow!(e))?;
2125        let response = full_response
2126            .result
2127            .ok_or_else(|| anyhow::anyhow!("No result in expirations response"))?;
2128        let expirations = response
2129            .expirations_for_currency(currency.as_str())
2130            .ok_or_else(|| anyhow::anyhow!("No option expirations for {currency}"))?;
2131
2132        Ok(expirations.option.clone())
2133    }
2134
2135    /// Requests position status reports for reconciliation.
2136    ///
2137    /// Fetches positions from Deribit and converts them to Nautilus [`PositionStatusReport`].
2138    /// Every instrument is in scope. A non-flat position whose instrument is not cached fails the
2139    /// request, and no reports are returned.
2140    ///
2141    /// # Strategy
2142    /// - Uses `currency=any` to fetch all positions in one call
2143    /// - Filters by instrument_id if provided
2144    ///
2145    /// # Errors
2146    ///
2147    /// Returns an error if the request fails or an in-scope non-flat position cannot be resolved.
2148    pub async fn request_position_status_reports(
2149        &self,
2150        account_id: AccountId,
2151        instrument_id: Option<InstrumentId>,
2152    ) -> anyhow::Result<Vec<PositionStatusReport>> {
2153        Ok(self
2154            .request_position_status_reports_in_scope(
2155                account_id,
2156                instrument_id,
2157                ReconciliationScope::unrestricted(),
2158            )
2159            .await?
2160            .reports)
2161    }
2162
2163    /// Requests position status reports and classifies instrument misses by `scope`.
2164    ///
2165    /// A position outside `scope`, or outside `instrument_id` when that filter is set, is omitted.
2166    /// An in-scope non-flat position whose instrument is not cached fails the read. Flat positions
2167    /// are omitted before scope classification. This method does not request the missing instrument
2168    /// from the venue.
2169    ///
2170    /// # Errors
2171    ///
2172    /// Returns an error if the request fails or an in-scope non-flat position cannot be resolved.
2173    /// No reports are returned in that case.
2174    pub(crate) async fn request_position_status_reports_in_scope(
2175        &self,
2176        account_id: AccountId,
2177        instrument_id: Option<InstrumentId>,
2178        scope: ReconciliationScope,
2179    ) -> anyhow::Result<ReportRead<PositionStatusReport>> {
2180        let ts_init = self.generate_ts_init();
2181        let mut reports = Vec::new();
2182
2183        // Use ANY to get all positions across all currencies in one call
2184        let params = GetPositionsParams {
2185            currency: DeribitCurrency::ANY,
2186            kind: None,
2187        };
2188
2189        if let Some(positions) = self.inner.get_positions(params).await?.result {
2190            for position in &positions {
2191                // Skip flat positions (size == 0)
2192                if position.size.is_zero() {
2193                    continue;
2194                }
2195
2196                let record_id = instrument_id_from_name(position.instrument_name);
2197
2198                if instrument_id.is_some_and(|id| id != record_id) {
2199                    continue;
2200                }
2201
2202                if !scope.includes(record_id) {
2203                    log::debug!("Skipping report for out-of-scope instrument {record_id}");
2204                    continue;
2205                }
2206
2207                let symbol = position.instrument_name;
2208
2209                let Some(instrument) = self.get_instrument(&symbol) else {
2210                    anyhow::bail!("Position has unresolved instrument {record_id}");
2211                };
2212
2213                let report =
2214                    parse_position_status_report(position, &instrument, account_id, ts_init);
2215                reports.push(report);
2216            }
2217        }
2218
2219        log::debug!("Generated {} position status reports", reports.len());
2220        Ok(ReportRead {
2221            reports,
2222            historical_misses: Vec::new(),
2223        })
2224    }
2225
2226    /// Loads configured instruments that are not already cached.
2227    ///
2228    /// Each returned instrument id matches the requested id. The caller caches the result. Report
2229    /// generation does not call this method.
2230    ///
2231    /// # Errors
2232    ///
2233    /// Returns an error if a request fails or the venue returns a different instrument.
2234    pub(crate) async fn request_uncached_instruments(
2235        &self,
2236        instrument_ids: &[InstrumentId],
2237    ) -> anyhow::Result<Vec<InstrumentAny>> {
2238        let mut loaded = Vec::new();
2239
2240        for instrument_id in instrument_ids {
2241            if self.get_instrument(&instrument_id.symbol.inner()).is_some() {
2242                continue;
2243            }
2244
2245            let instrument = self
2246                .request_instrument(*instrument_id)
2247                .await
2248                .with_context(|| {
2249                    format!("failed to load reconciliation instrument {instrument_id}")
2250                })?;
2251
2252            anyhow::ensure!(
2253                instrument.id() == *instrument_id,
2254                "loaded instrument {} does not match required {instrument_id}",
2255                instrument.id(),
2256            );
2257            loaded.push(instrument);
2258        }
2259
2260        Ok(loaded)
2261    }
2262}
2263
2264// Dedup and cursor state for timestamp-based trade pagination.
2265// Deribit provides no offset cursor, so when multiple trades share
2266// one millisecond we use trade-ID dedup to avoid reprocessing.
2267// If an entire page contains only seen IDs we advance past that
2268// millisecond, which can skip trades when >1000 share one timestamp.
2269struct TradePaginator {
2270    seen_ids: AHashSet<String>,
2271    cursor: i64,
2272    end: i64,
2273}
2274
2275impl TradePaginator {
2276    fn new(start: i64, end: i64) -> Self {
2277        Self {
2278            seen_ids: AHashSet::new(),
2279            cursor: start,
2280            end,
2281        }
2282    }
2283
2284    // Returns indices of new (unseen) items and advances the cursor.
2285    // Returns None when the page is empty (pagination should stop).
2286    fn advance(
2287        &mut self,
2288        ids: &[String],
2289        timestamps: &[i64],
2290        has_more: bool,
2291    ) -> Option<Vec<usize>> {
2292        if ids.is_empty() {
2293            return None;
2294        }
2295
2296        let mut new_indices = Vec::new();
2297        let mut last_ts = self.cursor;
2298        for (i, id) in ids.iter().enumerate() {
2299            last_ts = timestamps[i];
2300            if self.seen_ids.insert(id.clone()) {
2301                new_indices.push(i);
2302            }
2303        }
2304
2305        if !has_more {
2306            return Some(new_indices);
2307        }
2308
2309        if new_indices.is_empty() {
2310            self.cursor = last_ts + 1;
2311        } else {
2312            self.cursor = last_ts;
2313        }
2314
2315        Some(new_indices)
2316    }
2317
2318    // Strict greater-than so pages at exactly end_ms are still
2319    // fetched (Deribit treats start_timestamp as inclusive).
2320    fn is_exhausted(&self) -> bool {
2321        self.cursor > self.end
2322    }
2323
2324    fn reset(&mut self, start: i64) {
2325        self.seen_ids.clear();
2326        self.cursor = start;
2327    }
2328}
2329
2330#[cfg(test)]
2331mod tests {
2332    use nautilus_testkit::http::assert_http_redirect_rejected;
2333    use rstest::rstest;
2334
2335    use super::*;
2336    use crate::common::{
2337        consts::{DERIBIT_ACCOUNT_RATE_KEY, DERIBIT_GLOBAL_RATE_KEY, DERIBIT_ORDER_RATE_KEY},
2338        testing::routed_spot_instrument,
2339    };
2340
2341    #[tokio::test]
2342    async fn routed_spot_rejects_trade_and_bar_history_before_http() {
2343        let client = DeribitHttpClient::new(
2344            Some("http://127.0.0.1:1".into()),
2345            DeribitEnvironment::Testnet,
2346            1,
2347            0,
2348            1,
2349            1,
2350            None,
2351        )
2352        .unwrap();
2353        let instrument = routed_spot_instrument();
2354        let instrument_id = instrument.id();
2355        client.cache_instruments(&[instrument]);
2356
2357        let trades_error = client
2358            .request_trades(instrument_id, None, None, None)
2359            .await
2360            .unwrap_err();
2361        let bars_error = client
2362            .request_bars(
2363                "BTC_USDC.DERIBIT-1-MINUTE-LAST-EXTERNAL".parse().unwrap(),
2364                None,
2365                None,
2366                None,
2367            )
2368            .await
2369            .unwrap_err();
2370
2371        assert_eq!(
2372            trades_error.to_string(),
2373            "Deribit routed spot does not support public trades or charts for BTC_USDC.DERIBIT"
2374        );
2375        assert_eq!(bars_error.to_string(), trades_error.to_string());
2376    }
2377
2378    #[tokio::test]
2379    async fn test_authenticated_client_rejects_redirects() {
2380        let client = DeribitRawHttpClient::with_credentials(
2381            "key".into(),
2382            "secret".into(),
2383            None,
2384            DeribitEnvironment::Testnet,
2385            3,
2386            0,
2387            1,
2388            1,
2389            None,
2390        )
2391        .unwrap()
2392        .client;
2393        assert_http_redirect_rejected(|url| async move {
2394            client
2395                .get(url, None, None, Some(3), None)
2396                .await
2397                .unwrap()
2398                .status
2399                .as_u16()
2400        })
2401        .await;
2402    }
2403
2404    #[rstest]
2405    #[case("private/buy", true, false)]
2406    #[case("private/cancel", true, false)]
2407    #[case("private/get_account_summaries", false, true)]
2408    #[case("private/get_positions", false, true)]
2409    #[case("public/get_instruments", false, false)]
2410    fn test_method_classification(
2411        #[case] method: &str,
2412        #[case] is_order: bool,
2413        #[case] is_account: bool,
2414    ) {
2415        assert_eq!(DeribitRawHttpClient::is_order_method(method), is_order);
2416        assert_eq!(DeribitRawHttpClient::is_account_method(method), is_account);
2417    }
2418
2419    #[rstest]
2420    #[case("private/buy", vec![DERIBIT_GLOBAL_RATE_KEY, DERIBIT_ORDER_RATE_KEY])]
2421    #[case("private/get_account_summaries", vec![DERIBIT_GLOBAL_RATE_KEY, DERIBIT_ACCOUNT_RATE_KEY])]
2422    #[case("public/get_instruments", vec![DERIBIT_GLOBAL_RATE_KEY])]
2423    fn test_rate_limit_keys(#[case] method: &str, #[case] expected_keys: Vec<&str>) {
2424        let keys = DeribitRawHttpClient::rate_limit_keys(method);
2425
2426        for key in &expected_keys {
2427            assert!(keys.contains(&key.to_string()));
2428        }
2429        assert!(keys.contains(&format!("deribit:{method}")));
2430    }
2431
2432    #[rstest]
2433    fn test_paginator_empty_page_returns_none() {
2434        let mut p = TradePaginator::new(100, 200);
2435        assert!(p.advance(&[], &[], true).is_none());
2436    }
2437
2438    #[rstest]
2439    fn test_paginator_single_page_no_more() {
2440        let mut p = TradePaginator::new(100, 200);
2441        let ids = vec!["t1".into(), "t2".into()];
2442        let ts = vec![150, 160];
2443
2444        let result = p.advance(&ids, &ts, false);
2445        assert_eq!(result, Some(vec![0, 1]));
2446    }
2447
2448    #[rstest]
2449    fn test_paginator_dedup_across_pages() {
2450        let mut p = TradePaginator::new(100, 200);
2451
2452        // First page: two new trades
2453        let ids1 = vec!["t1".into(), "t2".into()];
2454        let ts1 = vec![150, 150];
2455        let r1 = p.advance(&ids1, &ts1, true);
2456        assert_eq!(r1, Some(vec![0, 1]));
2457        assert_eq!(p.cursor, 150);
2458
2459        // Second page: t2 repeated, t3 new
2460        let ids2 = vec!["t2".into(), "t3".into()];
2461        let ts2 = vec![150, 150];
2462        let r2 = p.advance(&ids2, &ts2, false);
2463        assert_eq!(r2, Some(vec![1])); // Only t3 is new
2464    }
2465
2466    #[rstest]
2467    fn test_paginator_all_duplicates_advances_past_timestamp() {
2468        let mut p = TradePaginator::new(100, 200);
2469
2470        // First page
2471        let ids = vec!["t1".into(), "t2".into()];
2472        let ts = vec![150, 150];
2473        p.advance(&ids, &ts, true);
2474        assert_eq!(p.cursor, 150);
2475
2476        // Second page: same trades again (all duplicates)
2477        let r2 = p.advance(&ids, &ts, true);
2478        assert_eq!(r2, Some(vec![])); // No new items
2479        assert_eq!(p.cursor, 151); // Advanced past 150
2480    }
2481
2482    #[rstest]
2483    fn test_paginator_is_exhausted_strict_greater_than() {
2484        let mut p = TradePaginator::new(100, 150);
2485
2486        let ids = vec!["t1".into()];
2487        let ts = vec![150];
2488        p.advance(&ids, &ts, true);
2489
2490        // Cursor at end (150) should NOT be exhausted
2491        assert_eq!(p.cursor, 150);
2492        assert!(!p.is_exhausted());
2493
2494        // All duplicates: cursor advances to 151
2495        p.advance(&ids, &ts, true);
2496        assert_eq!(p.cursor, 151);
2497        assert!(p.is_exhausted());
2498    }
2499
2500    #[rstest]
2501    fn test_paginator_reset_clears_state() {
2502        let mut p = TradePaginator::new(100, 200);
2503
2504        let ids = vec!["t1".into()];
2505        let ts = vec![150];
2506        p.advance(&ids, &ts, true);
2507        assert_eq!(p.seen_ids.len(), 1);
2508
2509        p.reset(100);
2510        assert_eq!(p.cursor, 100);
2511        assert!(p.seen_ids.is_empty());
2512
2513        // Same ID is now treated as new
2514        let r = p.advance(&ids, &ts, false);
2515        assert_eq!(r, Some(vec![0]));
2516    }
2517}