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
1125            .as_ref()
1126            .map(|info| IndexMap::clone(info))
1127            .unwrap_or_default();
1128
1129        let legs = combo
1130            .legs
1131            .iter()
1132            .map(|leg| {
1133                let instrument_id =
1134                    InstrumentId::new(Symbol::new(leg.instrument_name), *DERIBIT_VENUE);
1135
1136                json!({
1137                    "amount": leg.amount,
1138                    "instrument_id": instrument_id.to_string(),
1139                    "instrument_name": leg.instrument_name,
1140                })
1141            })
1142            .collect::<Vec<_>>();
1143
1144        merged.insert("deribit_combo_id".to_string(), json!(combo.id));
1145        merged.insert(
1146            "deribit_combo_state".to_string(),
1147            json!(combo.state.as_str()),
1148        );
1149        merged.insert("deribit_combo_legs".to_string(), json!(legs));
1150        *info = Some(Params::new(merged));
1151    }
1152
1153    /// Requests historical trades for an instrument within a time range.
1154    ///
1155    /// Fetches trade ticks from Deribit and converts them to Nautilus [`TradeTick`] objects.
1156    ///
1157    /// # Arguments
1158    ///
1159    /// * `instrument_id` - The instrument to fetch trades for
1160    /// * `start` - Optional start time filter
1161    /// * `end` - Optional end time filter
1162    /// * `limit` - Optional limit on number of trades (max 1000)
1163    ///
1164    /// # Errors
1165    ///
1166    /// Returns an error if:
1167    /// - The instrument is not found in cache.
1168    /// - The request fails.
1169    /// - Trade parsing fails.
1170    ///
1171    /// # Pagination
1172    ///
1173    /// When `limit` is `None`, this function automatically paginates through all available
1174    /// trades in the time range using the `has_more` field from the API response.
1175    /// When `limit` is specified, pagination stops once that many trades are collected.
1176    pub async fn request_trades(
1177        &self,
1178        instrument_id: InstrumentId,
1179        start: Option<Timestamp>,
1180        end: Option<Timestamp>,
1181        limit: Option<u32>,
1182    ) -> anyhow::Result<Vec<TradeTick>> {
1183        // Get instrument from cache to determine precisions
1184        let (price_precision, size_precision) =
1185            if let Some(instrument) = self.get_instrument(&instrument_id.symbol.inner()) {
1186                capabilities::validate_public_trades(&instrument)?;
1187                (instrument.price_precision(), instrument.size_precision())
1188            } else {
1189                log::warn!("Instrument {instrument_id} not in cache, skipping trades request");
1190                return Err(InstrumentLookupError::not_found(instrument_id).into());
1191            };
1192
1193        // Convert timestamps to milliseconds
1194        let now = Timestamp::now();
1195        let end_dt = end.unwrap_or(now);
1196        let start_dt = start.unwrap_or(end_dt - jiff::SignedDuration::from_hours(1));
1197
1198        if let (Some(s), Some(e)) = (start, end) {
1199            anyhow::ensure!(s < e, "Invalid time range: start={s:?} end={e:?}");
1200        }
1201
1202        let start_ms = start_dt.as_millisecond();
1203        let end_ms = end_dt.as_millisecond();
1204        let ts_init = self.generate_ts_init();
1205        let mut all_trades = Vec::new();
1206        let mut paginator = TradePaginator::new(start_ms, end_ms);
1207
1208        loop {
1209            let params = GetLastTradesByInstrumentAndTimeParams::new(
1210                instrument_id.symbol.to_string(),
1211                paginator.cursor,
1212                end_ms,
1213                Some(DERIBIT_HISTORICAL_TRADES_MAX_COUNT),
1214                Some("asc".to_string()),
1215            );
1216
1217            let full_response = self
1218                .inner
1219                .get_last_trades_by_instrument_and_time(params)
1220                .await
1221                .map_err(|e| anyhow::anyhow!(e))?;
1222
1223            let response_data = full_response
1224                .result
1225                .ok_or_else(|| anyhow::anyhow!("No result in response"))?;
1226
1227            let ids: Vec<String> = response_data
1228                .trades
1229                .iter()
1230                .map(|t| t.trade_id.clone())
1231                .collect();
1232            let timestamps: Vec<i64> = response_data.trades.iter().map(|t| t.timestamp).collect();
1233
1234            let Some(new_indices) = paginator.advance(&ids, &timestamps, response_data.has_more)
1235            else {
1236                break;
1237            };
1238
1239            for i in &new_indices {
1240                let raw_trade = &response_data.trades[*i];
1241
1242                match parse_trade_tick(
1243                    raw_trade,
1244                    instrument_id,
1245                    price_precision,
1246                    size_precision,
1247                    ts_init,
1248                ) {
1249                    Ok(trade) => {
1250                        all_trades.push(trade);
1251
1252                        if let Some(max) = limit
1253                            && all_trades.len() >= max as usize
1254                        {
1255                            return Ok(all_trades);
1256                        }
1257                    }
1258                    Err(e) => {
1259                        log::warn!(
1260                            "Failed to parse trade {} for {}: {}",
1261                            raw_trade.trade_id,
1262                            instrument_id,
1263                            e
1264                        );
1265                    }
1266                }
1267            }
1268
1269            if !response_data.has_more || paginator.is_exhausted() {
1270                break;
1271            }
1272        }
1273
1274        log::debug!(
1275            "Fetched {} historical trades for {} from {} to {}",
1276            all_trades.len(),
1277            instrument_id,
1278            start_dt,
1279            end_dt
1280        );
1281
1282        Ok(all_trades)
1283    }
1284
1285    /// Requests historical bars (OHLCV) for an instrument.
1286    ///
1287    /// Uses the `public/get_tradingview_chart_data` endpoint to fetch candlestick data.
1288    ///
1289    /// # Errors
1290    ///
1291    /// Returns an error if:
1292    /// - Aggregation source is not EXTERNAL.
1293    /// - Bar aggregation type is not supported by Deribit.
1294    /// - The instrument is not found in cache.
1295    /// - The request fails or response cannot be parsed.
1296    ///
1297    /// # Supported Resolutions
1298    ///
1299    /// Deribit supports: 1, 3, 5, 10, 15, 30, 60, 120, 180, 360, 720 minutes, and 1D (daily)
1300    pub async fn request_bars(
1301        &self,
1302        bar_type: BarType,
1303        start: Option<Timestamp>,
1304        end: Option<Timestamp>,
1305        limit: Option<u32>,
1306    ) -> anyhow::Result<Vec<Bar>> {
1307        anyhow::ensure!(
1308            bar_type.aggregation_source() == AggregationSource::External,
1309            "Only EXTERNAL aggregation is supported"
1310        );
1311
1312        let now = Timestamp::now();
1313
1314        // Default to last hour if no start/end provided
1315        let end_dt = end.unwrap_or(now);
1316        let start_dt = start.unwrap_or(end_dt - jiff::SignedDuration::from_hours(1));
1317
1318        if let (Some(s), Some(e)) = (start, end) {
1319            anyhow::ensure!(s < e, "Invalid time range: start={s:?} end={e:?}");
1320        }
1321
1322        // Convert BarType to Deribit resolution
1323        let spec = bar_type.spec();
1324        let step = spec.step.get();
1325        let resolution = match spec.aggregation {
1326            BarAggregation::Minute => format!("{step}"),
1327            BarAggregation::Hour => format!("{}", step * 60),
1328            BarAggregation::Day => "1D".to_string(),
1329            a => anyhow::bail!("Deribit does not support {a:?} aggregation"),
1330        };
1331
1332        // Validate resolution is supported by Deribit
1333        let supported_resolutions = [
1334            "1", "3", "5", "10", "15", "30", "60", "120", "180", "360", "720", "1D",
1335        ];
1336
1337        if !supported_resolutions.contains(&resolution.as_str()) {
1338            anyhow::bail!(
1339                "Deribit does not support resolution '{resolution}'. Supported: {supported_resolutions:?}"
1340            );
1341        }
1342
1343        let instrument_id = bar_type.instrument_id();
1344
1345        let (price_precision, size_precision, use_cost_for_volume) =
1346            if let Some(instrument) = self.get_instrument(&instrument_id.symbol.inner()) {
1347                capabilities::validate_public_trades(&instrument)?;
1348                (
1349                    instrument.price_precision(),
1350                    instrument.size_precision(),
1351                    use_cost_for_bar_volume(&instrument),
1352                )
1353            } else {
1354                log::warn!("Instrument {instrument_id} not in cache, skipping bars request");
1355                return Err(InstrumentLookupError::not_found(instrument_id).into());
1356            };
1357
1358        let instrument_name = instrument_id.symbol.to_string();
1359        let start_timestamp = start_dt.as_millisecond();
1360        let end_timestamp = end_dt.as_millisecond();
1361
1362        let params = GetTradingViewChartDataParams::new(
1363            instrument_name,
1364            start_timestamp,
1365            end_timestamp,
1366            resolution,
1367        );
1368
1369        let full_response = self.inner.get_tradingview_chart_data(params).await?;
1370        let chart_data = full_response
1371            .result
1372            .ok_or_else(|| anyhow::anyhow!("No result in response"))?;
1373
1374        if chart_data.status == "no_data" {
1375            log::debug!("No bar data returned for {bar_type}");
1376            return Ok(Vec::new());
1377        }
1378
1379        let ts_init = self.generate_ts_init();
1380        let mut bars = parse_bars(
1381            &chart_data,
1382            bar_type,
1383            price_precision,
1384            size_precision,
1385            use_cost_for_volume,
1386            ts_init,
1387        )?;
1388
1389        if let Some(max) = limit {
1390            let max = max as usize;
1391            if bars.len() > max {
1392                bars.drain(..bars.len() - max);
1393            }
1394        }
1395
1396        log::debug!("Parsed {} bars for {}", bars.len(), bar_type);
1397
1398        Ok(bars)
1399    }
1400
1401    /// Requests a snapshot of the order book for an instrument.
1402    ///
1403    /// Fetches the order book from Deribit and converts it to a Nautilus [`OrderBook`].
1404    ///
1405    /// # Arguments
1406    ///
1407    /// * `instrument_id` - The instrument to fetch the order book for
1408    /// * `depth` - Optional depth limit (valid values: 1, 5, 10, 20, 50, 100, 1000, 10000)
1409    ///
1410    /// # Errors
1411    ///
1412    /// Returns an error if:
1413    /// - The instrument is not found in cache.
1414    /// - The request fails.
1415    /// - Order book parsing fails.
1416    pub async fn request_book_snapshot(
1417        &self,
1418        instrument_id: InstrumentId,
1419        depth: Option<u32>,
1420    ) -> anyhow::Result<OrderBook> {
1421        let (price_precision, size_precision) =
1422            if let Some(instrument) = self.get_instrument(&instrument_id.symbol.inner()) {
1423                (instrument.price_precision(), instrument.size_precision())
1424            } else {
1425                return Err(InstrumentLookupError::not_found(instrument_id).into());
1426            };
1427
1428        let params = GetOrderBookParams::new(instrument_id.symbol.to_string(), depth);
1429        let full_response = self
1430            .inner
1431            .get_order_book(params)
1432            .await
1433            .map_err(|e| anyhow::anyhow!(e))?;
1434
1435        let order_book_data = full_response
1436            .result
1437            .ok_or_else(|| anyhow::anyhow!("No result in response"))?;
1438
1439        let ts_init = self.generate_ts_init();
1440        let book = parse_order_book(
1441            &order_book_data,
1442            instrument_id,
1443            price_precision,
1444            size_precision,
1445            ts_init,
1446        )?;
1447
1448        log::debug!(
1449            "Fetched order book for {} with {} bids and {} asks",
1450            instrument_id,
1451            order_book_data.bids.len(),
1452            order_book_data.asks.len()
1453        );
1454
1455        Ok(book)
1456    }
1457
1458    /// Requests account state for all currencies.
1459    ///
1460    /// Fetches account balance and margin information for all currencies from Deribit
1461    /// and converts it to Nautilus [`AccountState`] event.
1462    ///
1463    /// # Errors
1464    ///
1465    /// Returns an error if:
1466    /// - The request fails.
1467    /// - Currency conversion fails.
1468    pub async fn request_account_state(
1469        &self,
1470        account_id: AccountId,
1471    ) -> anyhow::Result<AccountState> {
1472        let params = GetAccountSummariesParams::default();
1473        let full_response = self
1474            .inner
1475            .get_account_summaries(params)
1476            .await
1477            .map_err(|e| anyhow::anyhow!(e))?;
1478        let response_data = full_response
1479            .result
1480            .ok_or_else(|| anyhow::anyhow!("No result in response"))?;
1481        let ts_init = self.generate_ts_init();
1482        let ts_event = extract_server_timestamp(full_response.us_out)?;
1483
1484        parse_account_state(&response_data.summaries, account_id, ts_init, ts_event)
1485    }
1486
1487    /// Generates a timestamp for initialization.
1488    fn generate_ts_init(&self) -> UnixNanos {
1489        self.clock.get_time_ns()
1490    }
1491
1492    /// Caches instruments for later retrieval.
1493    pub fn cache_instruments(&self, instruments: &[InstrumentAny]) {
1494        self.instruments_cache.rcu(|m| {
1495            for inst in instruments {
1496                m.insert(inst.raw_symbol().inner(), inst.clone());
1497            }
1498        });
1499        self.cache_initialized.store(true, Ordering::Release);
1500    }
1501
1502    /// Retrieves a cached instrument by symbol.
1503    #[must_use]
1504    pub fn get_instrument(&self, symbol: &Ustr) -> Option<InstrumentAny> {
1505        self.instruments_cache.get_cloned(symbol)
1506    }
1507
1508    /// Checks if the instrument cache has been initialized.
1509    #[must_use]
1510    pub fn is_cache_initialized(&self) -> bool {
1511        self.cache_initialized.load(Ordering::Acquire)
1512    }
1513
1514    /// Returns whether this client is connected to testnet.
1515    #[must_use]
1516    pub fn is_testnet(&self) -> bool {
1517        self.inner.is_testnet()
1518    }
1519
1520    /// Requests order status reports for reconciliation.
1521    ///
1522    /// Fetches order statuses from Deribit and converts them to Nautilus [`OrderStatusReport`].
1523    /// Every instrument is in scope. An unresolved open order fails the request. An unresolved
1524    /// closed order inside the request window also fails the request.
1525    ///
1526    /// # Strategy
1527    /// - Uses `/private/get_open_orders` for all open orders (single efficient API call)
1528    /// - Uses `/private/get_open_orders_by_instrument` when specific instrument is provided
1529    /// - For historical orders (when `open_only=false`), iterates over currencies
1530    ///
1531    /// # Errors
1532    ///
1533    /// Returns an error if:
1534    /// - The request fails.
1535    /// - An in-scope open order cannot be resolved.
1536    /// - An in-scope closed order inside the request window cannot be resolved.
1537    pub async fn request_order_status_reports(
1538        &self,
1539        account_id: AccountId,
1540        instrument_id: Option<InstrumentId>,
1541        start: Option<UnixNanos>,
1542        end: Option<UnixNanos>,
1543        open_only: bool,
1544    ) -> anyhow::Result<Vec<OrderStatusReport>> {
1545        let read = self
1546            .request_order_status_reports_in_scope(
1547                account_id,
1548                instrument_id,
1549                start,
1550                end,
1551                open_only,
1552                ReconciliationScope::unrestricted(),
1553            )
1554            .await?;
1555
1556        read.into_reports()
1557    }
1558
1559    /// Requests order status reports and reports in-window historical instrument misses.
1560    ///
1561    /// Records outside `scope` are omitted. An in-scope open order whose instrument is not cached
1562    /// fails the read. An in-scope closed order inside the request window whose instrument is not
1563    /// cached is omitted and recorded on [`ReportRead::historical_misses`]. This method does not
1564    /// request the missing instrument from the venue.
1565    ///
1566    /// # Errors
1567    ///
1568    /// Returns an error if the request fails or an in-scope open order cannot be resolved. No
1569    /// reports are returned in that case. A cached order that cannot be parsed is omitted.
1570    pub(crate) async fn request_order_status_reports_in_scope(
1571        &self,
1572        account_id: AccountId,
1573        instrument_id: Option<InstrumentId>,
1574        start: Option<UnixNanos>,
1575        end: Option<UnixNanos>,
1576        open_only: bool,
1577        scope: ReconciliationScope,
1578    ) -> anyhow::Result<ReportRead<OrderStatusReport>> {
1579        let ts_init = self.generate_ts_init();
1580        let mut reports = Vec::new();
1581        let mut seen_order_ids = AHashSet::new();
1582        let mut historical_misses = Vec::new();
1583
1584        let mut parse_and_add = |order: &DeribitOrderMsg| -> anyhow::Result<()> {
1585            self.accept_order_report(
1586                order,
1587                account_id,
1588                instrument_id,
1589                start,
1590                end,
1591                ts_init,
1592                &scope,
1593                &mut seen_order_ids,
1594                &mut reports,
1595                &mut historical_misses,
1596            )
1597        };
1598
1599        if let Some(instrument_id) = instrument_id {
1600            self.collect_instrument_order_reports(instrument_id, open_only, &mut parse_and_add)
1601                .await?;
1602        } else {
1603            self.collect_account_order_reports(open_only, &mut parse_and_add)
1604                .await?;
1605        }
1606
1607        log::debug!("Generated {} order status reports", reports.len());
1608        Ok(ReportRead {
1609            reports,
1610            historical_misses,
1611        })
1612    }
1613
1614    #[expect(clippy::too_many_arguments)]
1615    fn accept_order_report(
1616        &self,
1617        order: &DeribitOrderMsg,
1618        account_id: AccountId,
1619        instrument_id: Option<InstrumentId>,
1620        start: Option<UnixNanos>,
1621        end: Option<UnixNanos>,
1622        ts_init: UnixNanos,
1623        scope: &ReconciliationScope,
1624        seen_order_ids: &mut AHashSet<String>,
1625        reports: &mut Vec<OrderStatusReport>,
1626        historical_misses: &mut Vec<InstrumentId>,
1627    ) -> anyhow::Result<()> {
1628        let record_id = instrument_id_from_name(order.instrument_name);
1629
1630        if instrument_id.is_some_and(|id| id != record_id) {
1631            return Ok(());
1632        }
1633
1634        if !scope.includes(record_id) {
1635            log::debug!("Skipping report for out-of-scope instrument {record_id}");
1636            return Ok(());
1637        }
1638
1639        let Some(instrument) = self.get_instrument(&order.instrument_name) else {
1640            if !is_historical_order_state(order.order_state.as_str()) {
1641                anyhow::bail!(
1642                    "Open order {} has unresolved instrument {record_id}",
1643                    order.order_id
1644                );
1645            }
1646
1647            if millis_in_window(order.last_update_timestamp, start, end) {
1648                record_historical_miss(historical_misses, record_id);
1649            }
1650
1651            return Ok(());
1652        };
1653
1654        match parse_user_order_msg(order, &instrument, account_id, ts_init) {
1655            Ok(report) if timestamp_in_window(report.ts_last, start, end) => {
1656                if seen_order_ids.insert(order.order_id.clone()) {
1657                    reports.push(report);
1658                }
1659            }
1660            Ok(_) => {}
1661            Err(e) => {
1662                log::warn!(
1663                    "Failed to parse order {} for {}: {}",
1664                    order.order_id,
1665                    order.instrument_name,
1666                    e
1667                );
1668            }
1669        }
1670
1671        Ok(())
1672    }
1673
1674    async fn collect_instrument_order_reports(
1675        &self,
1676        instrument_id: InstrumentId,
1677        open_only: bool,
1678        parse_and_add: &mut impl FnMut(&DeribitOrderMsg) -> anyhow::Result<()>,
1679    ) -> anyhow::Result<()> {
1680        let instrument_name = instrument_id.symbol.to_string();
1681
1682        let open_params = GetOpenOrdersByInstrumentParams {
1683            instrument_name: instrument_name.clone(),
1684            r#type: None,
1685        };
1686
1687        if let Some(orders) = self
1688            .inner
1689            .get_open_orders_by_instrument(open_params)
1690            .await?
1691            .result
1692        {
1693            for order in &orders {
1694                parse_and_add(order)?;
1695            }
1696        }
1697
1698        if open_only {
1699            return Ok(());
1700        }
1701
1702        let mut offset = 0;
1703
1704        loop {
1705            let history_params = GetOrderHistoryByInstrumentParams {
1706                instrument_name: instrument_name.clone(),
1707                count: Some(ORDER_HISTORY_PAGE_SIZE),
1708                offset: Some(offset),
1709                include_old: Some(true),
1710                include_unfilled: Some(true),
1711            };
1712
1713            let orders = self
1714                .inner
1715                .get_order_history_by_instrument(history_params)
1716                .await?
1717                .result
1718                .unwrap_or_default();
1719            let count = orders.len() as u32;
1720            for order in &orders {
1721                parse_and_add(order)?;
1722            }
1723
1724            if count < ORDER_HISTORY_PAGE_SIZE {
1725                break;
1726            }
1727
1728            offset += count;
1729        }
1730
1731        Ok(())
1732    }
1733
1734    async fn collect_account_order_reports(
1735        &self,
1736        open_only: bool,
1737        parse_and_add: &mut impl FnMut(&DeribitOrderMsg) -> anyhow::Result<()>,
1738    ) -> anyhow::Result<()> {
1739        if let Some(orders) = self
1740            .inner
1741            .get_open_orders(GetOpenOrdersParams::default())
1742            .await?
1743            .result
1744        {
1745            for order in &orders {
1746                parse_and_add(order)?;
1747            }
1748        }
1749
1750        if open_only {
1751            return Ok(());
1752        }
1753
1754        for currency in DeribitCurrency::iter().filter(|currency| *currency != DeribitCurrency::ANY)
1755        {
1756            let mut offset = 0;
1757
1758            loop {
1759                let history_params = GetOrderHistoryByCurrencyParams {
1760                    currency,
1761                    kind: None,
1762                    count: Some(ORDER_HISTORY_PAGE_SIZE),
1763                    offset: Some(offset),
1764                    include_old: Some(true),
1765                    include_unfilled: Some(true),
1766                };
1767
1768                let orders = self
1769                    .inner
1770                    .get_order_history_by_currency(history_params)
1771                    .await?
1772                    .result
1773                    .unwrap_or_default();
1774                let count = orders.len() as u32;
1775                for order in &orders {
1776                    parse_and_add(order)?;
1777                }
1778
1779                if count < ORDER_HISTORY_PAGE_SIZE {
1780                    break;
1781                }
1782
1783                offset += count;
1784            }
1785        }
1786
1787        Ok(())
1788    }
1789
1790    /// Requests fill reports for reconciliation.
1791    ///
1792    /// Fetches user trades from Deribit and converts them to Nautilus [`FillReport`].
1793    /// Automatically paginates through all results using time-cursor advancement.
1794    ///
1795    /// Every instrument is in scope. A trade whose instrument is not cached is an unresolved
1796    /// historical record and fails this request. A trade for a cached instrument that cannot be
1797    /// parsed, including a commission outside the representable money range, also fails the
1798    /// request. No fill reports are returned.
1799    ///
1800    /// # Strategy
1801    /// - Uses `/private/get_user_trades_by_instrument_and_time` when instrument is provided
1802    /// - Otherwise iterates over currencies using `/private/get_user_trades_by_currency_and_time`
1803    ///
1804    /// # Errors
1805    ///
1806    /// Returns an error if:
1807    /// - The request fails.
1808    /// - A trade for a cached instrument cannot be parsed.
1809    /// - An in-scope trade inside the request window cannot be resolved.
1810    pub async fn request_fill_reports(
1811        &self,
1812        account_id: AccountId,
1813        instrument_id: Option<InstrumentId>,
1814        start: Option<UnixNanos>,
1815        end: Option<UnixNanos>,
1816    ) -> anyhow::Result<Vec<FillReport>> {
1817        let read = self
1818            .request_fill_reports_scoped(
1819                account_id,
1820                instrument_id,
1821                start,
1822                end,
1823                None,
1824                ReconciliationScope::unrestricted(),
1825            )
1826            .await?;
1827
1828        read.into_reports()
1829    }
1830
1831    /// Requests fill reports, optionally limited to one venue order.
1832    ///
1833    /// When `venue_order_id` is set, trades for other orders are omitted before trade parsing.
1834    /// A trade-parse failure for an omitted order does not fail the request. A response that
1835    /// cannot be decoded still fails the request.
1836    ///
1837    /// Records outside `scope` are omitted. An in-scope trade inside the request window whose
1838    /// instrument is not cached is omitted and recorded on [`ReportRead::historical_misses`]. A
1839    /// commission conversion failure for a cached trade still fails the request and is not recorded
1840    /// as incomplete history. This method does not request the missing instrument from the venue.
1841    ///
1842    /// # Errors
1843    ///
1844    /// Returns an error if:
1845    /// - The request fails.
1846    /// - A requested cached trade cannot be parsed.
1847    pub(crate) async fn request_fill_reports_scoped(
1848        &self,
1849        account_id: AccountId,
1850        instrument_id: Option<InstrumentId>,
1851        start: Option<UnixNanos>,
1852        end: Option<UnixNanos>,
1853        venue_order_id: Option<&VenueOrderId>,
1854        scope: ReconciliationScope,
1855    ) -> anyhow::Result<ReportRead<FillReport>> {
1856        let ts_init = self.generate_ts_init();
1857        let now_ms = Timestamp::now().as_millisecond();
1858
1859        // Convert UnixNanos to milliseconds for Deribit API
1860        let start_ms = start.map_or(0, |ns| nanos_to_millis(ns.as_u64()) as i64);
1861        let end_ms = end.map_or(now_ms, |ns| nanos_to_millis(ns.as_u64()) as i64);
1862        let mut reports = Vec::new();
1863        let mut historical_misses = Vec::new();
1864
1865        let mut parse_and_add = |trade: &DeribitUserTradeMsg| -> anyhow::Result<()> {
1866            self.accept_fill_report(
1867                trade,
1868                account_id,
1869                instrument_id,
1870                start,
1871                end,
1872                ts_init,
1873                venue_order_id,
1874                &scope,
1875                &mut reports,
1876                &mut historical_misses,
1877            )
1878        };
1879
1880        let mut paginator = TradePaginator::new(start_ms, end_ms);
1881
1882        if let Some(instrument_id) = instrument_id {
1883            self.collect_instrument_fill_reports(
1884                instrument_id,
1885                end_ms,
1886                &mut paginator,
1887                &mut parse_and_add,
1888            )
1889            .await?;
1890        } else {
1891            self.collect_account_fill_reports(start_ms, end_ms, &mut paginator, &mut parse_and_add)
1892                .await?;
1893        }
1894
1895        log::debug!("Generated {} fill reports", reports.len());
1896        Ok(ReportRead {
1897            reports,
1898            historical_misses,
1899        })
1900    }
1901
1902    #[expect(clippy::too_many_arguments)]
1903    fn accept_fill_report(
1904        &self,
1905        trade: &DeribitUserTradeMsg,
1906        account_id: AccountId,
1907        instrument_id: Option<InstrumentId>,
1908        start: Option<UnixNanos>,
1909        end: Option<UnixNanos>,
1910        ts_init: UnixNanos,
1911        venue_order_id: Option<&VenueOrderId>,
1912        scope: &ReconciliationScope,
1913        reports: &mut Vec<FillReport>,
1914        historical_misses: &mut Vec<InstrumentId>,
1915    ) -> anyhow::Result<()> {
1916        if venue_order_id.is_some_and(|order_id| trade.order_id != order_id.as_str()) {
1917            return Ok(());
1918        }
1919
1920        let record_id = instrument_id_from_name(trade.instrument_name);
1921
1922        if instrument_id.is_some_and(|id| id != record_id) {
1923            return Ok(());
1924        }
1925
1926        if !scope.includes(record_id) {
1927            log::debug!("Skipping report for out-of-scope instrument {record_id}");
1928            return Ok(());
1929        }
1930
1931        let Some(instrument) = self.get_instrument(&trade.instrument_name) else {
1932            if millis_in_window(trade.timestamp, start, end) {
1933                record_historical_miss(historical_misses, record_id);
1934            }
1935
1936            return Ok(());
1937        };
1938
1939        let report =
1940            parse_user_trade_msg(trade, &instrument, account_id, ts_init).with_context(|| {
1941                format!(
1942                    "failed to parse trade {} for {}",
1943                    trade.trade_id, trade.instrument_name
1944                )
1945            })?;
1946
1947        reports.push(report);
1948        Ok(())
1949    }
1950
1951    async fn collect_instrument_fill_reports(
1952        &self,
1953        instrument_id: InstrumentId,
1954        end_ms: i64,
1955        paginator: &mut TradePaginator,
1956        parse_and_add: &mut impl FnMut(&DeribitUserTradeMsg) -> anyhow::Result<()>,
1957    ) -> anyhow::Result<()> {
1958        loop {
1959            let params = GetUserTradesByInstrumentAndTimeParams {
1960                instrument_name: instrument_id.symbol.to_string(),
1961                start_timestamp: paginator.cursor,
1962                end_timestamp: end_ms,
1963                count: Some(DERIBIT_HISTORICAL_TRADES_MAX_COUNT),
1964                sorting: Some("asc".to_string()),
1965            };
1966
1967            let Some(data) = self
1968                .inner
1969                .get_user_trades_by_instrument_and_time(params)
1970                .await?
1971                .result
1972            else {
1973                break;
1974            };
1975
1976            if !Self::consume_trade_page(&data, paginator, parse_and_add)? {
1977                break;
1978            }
1979        }
1980
1981        Ok(())
1982    }
1983
1984    async fn collect_account_fill_reports(
1985        &self,
1986        start_ms: i64,
1987        end_ms: i64,
1988        paginator: &mut TradePaginator,
1989        parse_and_add: &mut impl FnMut(&DeribitUserTradeMsg) -> anyhow::Result<()>,
1990    ) -> anyhow::Result<()> {
1991        for currency in DeribitCurrency::iter().filter(|currency| *currency != DeribitCurrency::ANY)
1992        {
1993            paginator.reset(start_ms);
1994
1995            loop {
1996                let params = GetUserTradesByCurrencyAndTimeParams {
1997                    currency,
1998                    start_timestamp: paginator.cursor,
1999                    end_timestamp: end_ms,
2000                    kind: None,
2001                    count: Some(DERIBIT_HISTORICAL_TRADES_MAX_COUNT),
2002                    sorting: Some("asc".to_string()),
2003                };
2004
2005                let Some(data) = self
2006                    .inner
2007                    .get_user_trades_by_currency_and_time(params)
2008                    .await?
2009                    .result
2010                else {
2011                    break;
2012                };
2013
2014                if !Self::consume_trade_page(&data, paginator, parse_and_add)? {
2015                    break;
2016                }
2017            }
2018        }
2019
2020        Ok(())
2021    }
2022
2023    fn consume_trade_page(
2024        data: &DeribitUserTradesResponse,
2025        paginator: &mut TradePaginator,
2026        parse_and_add: &mut impl FnMut(&DeribitUserTradeMsg) -> anyhow::Result<()>,
2027    ) -> anyhow::Result<bool> {
2028        let ids: Vec<String> = data
2029            .trades
2030            .iter()
2031            .map(|trade| trade.trade_id.clone())
2032            .collect();
2033        let timestamps: Vec<i64> = data
2034            .trades
2035            .iter()
2036            .map(|trade| trade.timestamp as i64)
2037            .collect();
2038
2039        let Some(new_indices) = paginator.advance(&ids, &timestamps, data.has_more) else {
2040            return Ok(false);
2041        };
2042
2043        for index in new_indices {
2044            parse_and_add(&data.trades[index])?;
2045        }
2046
2047        Ok(data.has_more && !paginator.is_exhausted())
2048    }
2049
2050    /// Requests ticker data for a single instrument.
2051    ///
2052    /// Returns the `DeribitTicker` including its option-chain reference price.
2053    ///
2054    /// # Errors
2055    ///
2056    /// Returns an error if the request fails.
2057    pub async fn request_ticker(&self, instrument_name: &str) -> anyhow::Result<DeribitTicker> {
2058        let params = GetTickerParams {
2059            instrument_name: instrument_name.to_string(),
2060        };
2061        let response = self
2062            .inner
2063            .get_ticker(params)
2064            .await
2065            .map_err(|e| anyhow::anyhow!(e))?;
2066        response
2067            .result
2068            .ok_or_else(|| anyhow::anyhow!("No result in ticker response"))
2069    }
2070
2071    /// Requests book summaries for a currency via `public/get_book_summary_by_currency`.
2072    ///
2073    /// Defaults to product kind `option`.
2074    /// Entries include mark/IV, bid-ask, volumes, and `underlying_price` (forward) when present.
2075    ///
2076    /// # Errors
2077    ///
2078    /// Returns an error if the request fails.
2079    pub async fn request_book_summaries(
2080        &self,
2081        currency: &str,
2082    ) -> anyhow::Result<Vec<DeribitBookSummaryRaw>> {
2083        self.request_book_summaries_kind(currency, Some("option"))
2084            .await
2085    }
2086
2087    /// Requests book summaries for a currency with an optional product `kind` filter.
2088    ///
2089    /// When `kind` is `None`, Deribit returns summaries for all product kinds.
2090    ///
2091    /// # Errors
2092    ///
2093    /// Returns an error if the request fails.
2094    pub async fn request_book_summaries_kind(
2095        &self,
2096        currency: &str,
2097        kind: Option<&str>,
2098    ) -> anyhow::Result<Vec<DeribitBookSummaryRaw>> {
2099        let params = GetBookSummaryByCurrencyParams {
2100            currency: currency.to_string(),
2101            kind: kind.map(str::to_string),
2102        };
2103        let full_response = self
2104            .inner
2105            .get_book_summary_by_currency(params)
2106            .await
2107            .map_err(|e| anyhow::anyhow!(e))?;
2108        full_response
2109            .result
2110            .ok_or_else(|| anyhow::anyhow!("No result in book summary response"))
2111    }
2112
2113    /// Requests traded option expirations for a settlement currency.
2114    ///
2115    /// # Errors
2116    ///
2117    /// Returns an error if the request fails.
2118    pub async fn request_option_expirations(
2119        &self,
2120        currency: DeribitCurrency,
2121    ) -> anyhow::Result<Vec<String>> {
2122        let params = GetExpirationsParams::new(currency.as_str(), DeribitExpirationKind::Option);
2123        let full_response = self
2124            .inner
2125            .get_expirations(params)
2126            .await
2127            .map_err(|e| anyhow::anyhow!(e))?;
2128        let response = full_response
2129            .result
2130            .ok_or_else(|| anyhow::anyhow!("No result in expirations response"))?;
2131        let expirations = response
2132            .expirations_for_currency(currency.as_str())
2133            .ok_or_else(|| anyhow::anyhow!("No option expirations for {currency}"))?;
2134
2135        Ok(expirations.option.clone())
2136    }
2137
2138    /// Requests position status reports for reconciliation.
2139    ///
2140    /// Fetches positions from Deribit and converts them to Nautilus [`PositionStatusReport`].
2141    /// Every instrument is in scope. A non-flat position whose instrument is not cached fails the
2142    /// request, and no reports are returned.
2143    ///
2144    /// # Strategy
2145    /// - Uses `currency=any` to fetch all positions in one call
2146    /// - Filters by instrument_id if provided
2147    ///
2148    /// # Errors
2149    ///
2150    /// Returns an error if the request fails or an in-scope non-flat position cannot be resolved.
2151    pub async fn request_position_status_reports(
2152        &self,
2153        account_id: AccountId,
2154        instrument_id: Option<InstrumentId>,
2155    ) -> anyhow::Result<Vec<PositionStatusReport>> {
2156        Ok(self
2157            .request_position_status_reports_in_scope(
2158                account_id,
2159                instrument_id,
2160                ReconciliationScope::unrestricted(),
2161            )
2162            .await?
2163            .reports)
2164    }
2165
2166    /// Requests position status reports and classifies instrument misses by `scope`.
2167    ///
2168    /// A position outside `scope`, or outside `instrument_id` when that filter is set, is omitted.
2169    /// An in-scope non-flat position whose instrument is not cached fails the read. Flat positions
2170    /// are omitted before scope classification. This method does not request the missing instrument
2171    /// from the venue.
2172    ///
2173    /// # Errors
2174    ///
2175    /// Returns an error if the request fails or an in-scope non-flat position cannot be resolved.
2176    /// No reports are returned in that case.
2177    pub(crate) async fn request_position_status_reports_in_scope(
2178        &self,
2179        account_id: AccountId,
2180        instrument_id: Option<InstrumentId>,
2181        scope: ReconciliationScope,
2182    ) -> anyhow::Result<ReportRead<PositionStatusReport>> {
2183        let ts_init = self.generate_ts_init();
2184        let mut reports = Vec::new();
2185
2186        // Use ANY to get all positions across all currencies in one call
2187        let params = GetPositionsParams {
2188            currency: DeribitCurrency::ANY,
2189            kind: None,
2190        };
2191
2192        if let Some(positions) = self.inner.get_positions(params).await?.result {
2193            for position in &positions {
2194                // Skip flat positions (size == 0)
2195                if position.size.is_zero() {
2196                    continue;
2197                }
2198
2199                let record_id = instrument_id_from_name(position.instrument_name);
2200
2201                if instrument_id.is_some_and(|id| id != record_id) {
2202                    continue;
2203                }
2204
2205                if !scope.includes(record_id) {
2206                    log::debug!("Skipping report for out-of-scope instrument {record_id}");
2207                    continue;
2208                }
2209
2210                let symbol = position.instrument_name;
2211
2212                let Some(instrument) = self.get_instrument(&symbol) else {
2213                    anyhow::bail!("Position has unresolved instrument {record_id}");
2214                };
2215
2216                let report =
2217                    parse_position_status_report(position, &instrument, account_id, ts_init);
2218                reports.push(report);
2219            }
2220        }
2221
2222        log::debug!("Generated {} position status reports", reports.len());
2223        Ok(ReportRead {
2224            reports,
2225            historical_misses: Vec::new(),
2226        })
2227    }
2228
2229    /// Loads configured instruments that are not already cached.
2230    ///
2231    /// Each returned instrument id matches the requested id. The caller caches the result. Report
2232    /// generation does not call this method.
2233    ///
2234    /// # Errors
2235    ///
2236    /// Returns an error if a request fails or the venue returns a different instrument.
2237    pub(crate) async fn request_uncached_instruments(
2238        &self,
2239        instrument_ids: &[InstrumentId],
2240    ) -> anyhow::Result<Vec<InstrumentAny>> {
2241        let mut loaded = Vec::new();
2242
2243        for instrument_id in instrument_ids {
2244            if self.get_instrument(&instrument_id.symbol.inner()).is_some() {
2245                continue;
2246            }
2247
2248            let instrument = self
2249                .request_instrument(*instrument_id)
2250                .await
2251                .with_context(|| {
2252                    format!("failed to load reconciliation instrument {instrument_id}")
2253                })?;
2254
2255            anyhow::ensure!(
2256                instrument.id() == *instrument_id,
2257                "loaded instrument {} does not match required {instrument_id}",
2258                instrument.id(),
2259            );
2260            loaded.push(instrument);
2261        }
2262
2263        Ok(loaded)
2264    }
2265}
2266
2267// Dedup and cursor state for timestamp-based trade pagination.
2268// Deribit provides no offset cursor, so when multiple trades share
2269// one millisecond we use trade-ID dedup to avoid reprocessing.
2270// If an entire page contains only seen IDs we advance past that
2271// millisecond, which can skip trades when >1000 share one timestamp.
2272struct TradePaginator {
2273    seen_ids: AHashSet<String>,
2274    cursor: i64,
2275    end: i64,
2276}
2277
2278impl TradePaginator {
2279    fn new(start: i64, end: i64) -> Self {
2280        Self {
2281            seen_ids: AHashSet::new(),
2282            cursor: start,
2283            end,
2284        }
2285    }
2286
2287    // Returns indices of new (unseen) items and advances the cursor.
2288    // Returns None when the page is empty (pagination should stop).
2289    fn advance(
2290        &mut self,
2291        ids: &[String],
2292        timestamps: &[i64],
2293        has_more: bool,
2294    ) -> Option<Vec<usize>> {
2295        if ids.is_empty() {
2296            return None;
2297        }
2298
2299        let mut new_indices = Vec::new();
2300        let mut last_ts = self.cursor;
2301        for (i, id) in ids.iter().enumerate() {
2302            last_ts = timestamps[i];
2303            if self.seen_ids.insert(id.clone()) {
2304                new_indices.push(i);
2305            }
2306        }
2307
2308        if !has_more {
2309            return Some(new_indices);
2310        }
2311
2312        if new_indices.is_empty() {
2313            self.cursor = last_ts + 1;
2314        } else {
2315            self.cursor = last_ts;
2316        }
2317
2318        Some(new_indices)
2319    }
2320
2321    // Strict greater-than so pages at exactly end_ms are still
2322    // fetched (Deribit treats start_timestamp as inclusive).
2323    fn is_exhausted(&self) -> bool {
2324        self.cursor > self.end
2325    }
2326
2327    fn reset(&mut self, start: i64) {
2328        self.seen_ids.clear();
2329        self.cursor = start;
2330    }
2331}
2332
2333#[cfg(test)]
2334mod tests {
2335    use nautilus_testkit::http::assert_http_redirect_rejected;
2336    use rstest::rstest;
2337
2338    use super::*;
2339    use crate::common::{
2340        consts::{DERIBIT_ACCOUNT_RATE_KEY, DERIBIT_GLOBAL_RATE_KEY, DERIBIT_ORDER_RATE_KEY},
2341        testing::routed_spot_instrument,
2342    };
2343
2344    #[tokio::test]
2345    async fn routed_spot_rejects_trade_and_bar_history_before_http() {
2346        let client = DeribitHttpClient::new(
2347            Some("http://127.0.0.1:1".into()),
2348            DeribitEnvironment::Testnet,
2349            1,
2350            0,
2351            1,
2352            1,
2353            None,
2354        )
2355        .unwrap();
2356        let instrument = routed_spot_instrument();
2357        let instrument_id = instrument.id();
2358        client.cache_instruments(&[instrument]);
2359
2360        let trades_error = client
2361            .request_trades(instrument_id, None, None, None)
2362            .await
2363            .unwrap_err();
2364        let bars_error = client
2365            .request_bars(
2366                "BTC_USDC.DERIBIT-1-MINUTE-LAST-EXTERNAL".parse().unwrap(),
2367                None,
2368                None,
2369                None,
2370            )
2371            .await
2372            .unwrap_err();
2373
2374        assert_eq!(
2375            trades_error.to_string(),
2376            "Deribit routed spot does not support public trades or charts for BTC_USDC.DERIBIT"
2377        );
2378        assert_eq!(bars_error.to_string(), trades_error.to_string());
2379    }
2380
2381    #[tokio::test]
2382    async fn test_authenticated_client_rejects_redirects() {
2383        let client = DeribitRawHttpClient::with_credentials(
2384            "key".into(),
2385            "secret".into(),
2386            None,
2387            DeribitEnvironment::Testnet,
2388            3,
2389            0,
2390            1,
2391            1,
2392            None,
2393        )
2394        .unwrap()
2395        .client;
2396        assert_http_redirect_rejected(|url| async move {
2397            client
2398                .get(url, None, None, Some(3), None)
2399                .await
2400                .unwrap()
2401                .status
2402                .as_u16()
2403        })
2404        .await;
2405    }
2406
2407    #[rstest]
2408    #[case("private/buy", true, false)]
2409    #[case("private/cancel", true, false)]
2410    #[case("private/get_account_summaries", false, true)]
2411    #[case("private/get_positions", false, true)]
2412    #[case("public/get_instruments", false, false)]
2413    fn test_method_classification(
2414        #[case] method: &str,
2415        #[case] is_order: bool,
2416        #[case] is_account: bool,
2417    ) {
2418        assert_eq!(DeribitRawHttpClient::is_order_method(method), is_order);
2419        assert_eq!(DeribitRawHttpClient::is_account_method(method), is_account);
2420    }
2421
2422    #[rstest]
2423    #[case("private/buy", vec![DERIBIT_GLOBAL_RATE_KEY, DERIBIT_ORDER_RATE_KEY])]
2424    #[case("private/get_account_summaries", vec![DERIBIT_GLOBAL_RATE_KEY, DERIBIT_ACCOUNT_RATE_KEY])]
2425    #[case("public/get_instruments", vec![DERIBIT_GLOBAL_RATE_KEY])]
2426    fn test_rate_limit_keys(#[case] method: &str, #[case] expected_keys: Vec<&str>) {
2427        let keys = DeribitRawHttpClient::rate_limit_keys(method);
2428
2429        for key in &expected_keys {
2430            assert!(keys.contains(&key.to_string()));
2431        }
2432        assert!(keys.contains(&format!("deribit:{method}")));
2433    }
2434
2435    #[rstest]
2436    fn test_paginator_empty_page_returns_none() {
2437        let mut p = TradePaginator::new(100, 200);
2438        assert!(p.advance(&[], &[], true).is_none());
2439    }
2440
2441    #[rstest]
2442    fn test_paginator_single_page_no_more() {
2443        let mut p = TradePaginator::new(100, 200);
2444        let ids = vec!["t1".into(), "t2".into()];
2445        let ts = vec![150, 160];
2446
2447        let result = p.advance(&ids, &ts, false);
2448        assert_eq!(result, Some(vec![0, 1]));
2449    }
2450
2451    #[rstest]
2452    fn test_paginator_dedup_across_pages() {
2453        let mut p = TradePaginator::new(100, 200);
2454
2455        // First page: two new trades
2456        let ids1 = vec!["t1".into(), "t2".into()];
2457        let ts1 = vec![150, 150];
2458        let r1 = p.advance(&ids1, &ts1, true);
2459        assert_eq!(r1, Some(vec![0, 1]));
2460        assert_eq!(p.cursor, 150);
2461
2462        // Second page: t2 repeated, t3 new
2463        let ids2 = vec!["t2".into(), "t3".into()];
2464        let ts2 = vec![150, 150];
2465        let r2 = p.advance(&ids2, &ts2, false);
2466        assert_eq!(r2, Some(vec![1])); // Only t3 is new
2467    }
2468
2469    #[rstest]
2470    fn test_paginator_all_duplicates_advances_past_timestamp() {
2471        let mut p = TradePaginator::new(100, 200);
2472
2473        // First page
2474        let ids = vec!["t1".into(), "t2".into()];
2475        let ts = vec![150, 150];
2476        p.advance(&ids, &ts, true);
2477        assert_eq!(p.cursor, 150);
2478
2479        // Second page: same trades again (all duplicates)
2480        let r2 = p.advance(&ids, &ts, true);
2481        assert_eq!(r2, Some(vec![])); // No new items
2482        assert_eq!(p.cursor, 151); // Advanced past 150
2483    }
2484
2485    #[rstest]
2486    fn test_paginator_is_exhausted_strict_greater_than() {
2487        let mut p = TradePaginator::new(100, 150);
2488
2489        let ids = vec!["t1".into()];
2490        let ts = vec![150];
2491        p.advance(&ids, &ts, true);
2492
2493        // Cursor at end (150) should NOT be exhausted
2494        assert_eq!(p.cursor, 150);
2495        assert!(!p.is_exhausted());
2496
2497        // All duplicates: cursor advances to 151
2498        p.advance(&ids, &ts, true);
2499        assert_eq!(p.cursor, 151);
2500        assert!(p.is_exhausted());
2501    }
2502
2503    #[rstest]
2504    fn test_paginator_reset_clears_state() {
2505        let mut p = TradePaginator::new(100, 200);
2506
2507        let ids = vec!["t1".into()];
2508        let ts = vec![150];
2509        p.advance(&ids, &ts, true);
2510        assert_eq!(p.seen_ids.len(), 1);
2511
2512        p.reset(100);
2513        assert_eq!(p.cursor, 100);
2514        assert!(p.seen_ids.is_empty());
2515
2516        // Same ID is now treated as new
2517        let r = p.advance(&ids, &ts, false);
2518        assert_eq!(r, Some(vec![0]));
2519    }
2520}