Skip to main content

nautilus_derive/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//! REST client for the Derive API using the shared HTTP transport.
17//!
18//! [`DeriveHttpClient`] exposes typed `send_public` / `send_private`
19//! dispatchers plus thin wrappers for the two endpoints that establish the
20//! plumbing this crate needs to grow against: `public/get_all_instruments` and
21//! `private/order`. Authenticated requests inject the EIP-191 session-key
22//! headers built by [`crate::signing::auth`].
23
24use std::{
25    collections::HashSet,
26    fmt::Debug,
27    sync::{
28        Arc,
29        atomic::{AtomicU64, Ordering},
30    },
31};
32
33use ahash::AHashMap;
34use alloy::signers::local::PrivateKeySigner;
35use nautilus_core::string::secret::{REDACTED, SecretString, zeroize_json_value};
36use nautilus_network::{
37    ConnectionUrl,
38    http::{
39        HttpClient, HttpClientError, HttpRedirectPolicy, HttpResponse, Method, RETRY_AFTER,
40        create_standard_nautilus_headers, parse_retry_after,
41    },
42    retry::{RetryConfig, RetryManager},
43};
44use serde::{Serialize, de::DeserializeOwned};
45use serde_json::Value;
46use ustr::Ustr;
47
48use crate::{
49    common::{
50        consts::{
51            HEADER_DERIVE_SIGNATURE, HEADER_DERIVE_TIMESTAMP, HEADER_DERIVE_WALLET,
52            HTTP_MAX_RETRIES, HTTP_RETRY_DELAY_INITIAL_MS, HTTP_RETRY_DELAY_MAX_MS, HTTP_TIMEOUT,
53        },
54        enums::DeriveInstrumentType,
55        rate_limit::{self, DeriveRateLimiter},
56        retry::{http_retry_config, should_retry_http_error},
57    },
58    http::{
59        error::{DeriveHttpError, Result},
60        models::{
61            DeriveCancelByLabelResult, DeriveEmptyResult, DeriveInstrument,
62            DeriveInstrumentsResult, DeriveOpenOrdersResult, DeriveOrder, DeriveOrderResult,
63            DeriveOrdersResult, DerivePositionsResult, DerivePublicCandle,
64            DerivePublicFundingRateHistoryResult, DerivePublicTradesResult, DeriveReplaceOutcome,
65            DeriveReplaceResult, DeriveSubaccount, DeriveTickerSnapshot, DeriveTickersResult,
66            DeriveTradesResult, JsonRpcResponse,
67        },
68        query::{
69            DeriveCancelAllParams, DeriveCancelByLabelParams, DeriveCancelParams,
70            DeriveGetOpenOrdersParams, DeriveGetOrderHistoryParams, DeriveGetOrderParams,
71            DeriveGetPositionsParams, DeriveGetSubaccountParams, DeriveGetTradeHistoryParams,
72            DeriveGetTriggerOrdersParams, DeriveOrderParams, DeriveReplaceParams, PaginationCursor,
73        },
74    },
75    signing::auth::{AuthHeaders, build_rest_auth_headers},
76};
77
78/// Credentials used to sign authenticated REST requests.
79///
80/// `Debug` is implemented manually so the session key never escapes through
81/// loggers or Python `__repr__`.
82#[derive(Clone)]
83pub struct DeriveCredentials {
84    /// Owner's EOA or multisig address (`0x`-prefixed hex, 42 chars).
85    pub wallet_address: String,
86    /// secp256k1 session-key signer.
87    pub signer: PrivateKeySigner,
88}
89
90impl DeriveCredentials {
91    /// Constructs credentials by parsing `session_key_hex` into a signer.
92    ///
93    /// # Errors
94    ///
95    /// Returns an error if the session-key hex cannot be parsed.
96    pub fn new(wallet_address: impl Into<String>, session_key_hex: &str) -> Result<Self> {
97        let signer: PrivateKeySigner = session_key_hex
98            .parse()
99            .map_err(|e| DeriveHttpError::decode(format!("invalid session key: {e}")))?;
100        Ok(Self {
101            wallet_address: wallet_address.into(),
102            signer,
103        })
104    }
105}
106
107impl Debug for DeriveCredentials {
108    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
109        f.debug_struct(stringify!(DeriveCredentials))
110            .field("wallet_address", &self.wallet_address)
111            .field("signer", &REDACTED)
112            .finish()
113    }
114}
115
116/// HTTP client for the Derive REST API.
117///
118/// The client carries an atomic `id` counter so every request frame has a
119/// unique correlator; the REST transport ships only `params` on the wire but
120/// the id is preserved for logs and reused by the upcoming WebSocket client.
121/// Each call routes through a [`RetryManager`] that re-signs auth headers on
122/// every attempt, so retries never replay a stale `X-DeriveTimestamp`.
123#[derive(Debug, Clone)]
124pub struct DeriveHttpClient {
125    client: HttpClient,
126    base_url: ConnectionUrl,
127    credentials: Option<DeriveCredentials>,
128    next_id: Arc<AtomicU64>,
129    timeout_secs: u64,
130    retry_manager: Arc<RetryManager<DeriveHttpError>>,
131    rate_limiter: Arc<DeriveRateLimiter>,
132}
133
134impl DeriveHttpClient {
135    /// Creates a public-only client.
136    ///
137    /// When `retry_config` is `None`, uses [`HTTP_MAX_RETRIES`],
138    /// [`HTTP_RETRY_DELAY_INITIAL_MS`], and [`HTTP_RETRY_DELAY_MAX_MS`].
139    ///
140    /// # Errors
141    ///
142    /// Returns an error if the underlying HTTP client (proxy URL, TLS init) cannot be constructed.
143    pub fn new(
144        base_url: impl Into<String>,
145        timeout_secs: Option<u64>,
146        proxy_url: Option<String>,
147        retry_config: Option<RetryConfig>,
148    ) -> Result<Self> {
149        let timeout_secs = timeout_secs.unwrap_or_else(|| HTTP_TIMEOUT.as_secs());
150        let client = build_client(timeout_secs, proxy_url)?;
151        let base_url = trim_trailing_slash(base_url.into());
152        let rate_limiter = Arc::new(DeriveRateLimiter::shared(&base_url, None, None, None));
153
154        let retry_config = retry_config.unwrap_or_else(|| {
155            http_retry_config(
156                HTTP_MAX_RETRIES,
157                HTTP_RETRY_DELAY_INITIAL_MS,
158                HTTP_RETRY_DELAY_MAX_MS,
159            )
160        });
161
162        Ok(Self {
163            client,
164            base_url: base_url.into(),
165            credentials: None,
166            next_id: Arc::new(AtomicU64::new(1)),
167            timeout_secs,
168            retry_manager: Arc::new(RetryManager::new(retry_config)),
169            rate_limiter,
170        })
171    }
172
173    /// Creates a client with credentials installed for `send_private` calls.
174    ///
175    /// # Errors
176    ///
177    /// Returns an error if the underlying HTTP client cannot be constructed.
178    pub fn with_credentials(
179        base_url: impl Into<String>,
180        credentials: DeriveCredentials,
181        timeout_secs: Option<u64>,
182        proxy_url: Option<String>,
183        retry_config: Option<RetryConfig>,
184    ) -> Result<Self> {
185        let mut client = Self::new(base_url, timeout_secs, proxy_url, retry_config)?;
186
187        client.rate_limiter = Arc::new(DeriveRateLimiter::shared(
188            client.base_url.expose(),
189            Some(&credentials.wallet_address),
190            None,
191            None,
192        ));
193        client.credentials = Some(credentials);
194        Ok(client)
195    }
196
197    /// Returns the configured base URL (no trailing slash).
198    #[must_use]
199    pub fn base_url(&self) -> &str {
200        self.base_url.expose()
201    }
202
203    /// Returns `true` when credentials are installed.
204    #[must_use]
205    pub fn has_credentials(&self) -> bool {
206        self.credentials.is_some()
207    }
208
209    /// Allocates the next correlator id.
210    fn next_id(&self) -> u64 {
211        self.next_id.fetch_add(1, Ordering::Relaxed)
212    }
213
214    /// Sends an unauthenticated request and decodes the JSON-RPC envelope.
215    ///
216    /// Public endpoints are idempotent reads; this path retries transient
217    /// failures via the configured [`RetryManager`].
218    ///
219    /// # Errors
220    ///
221    /// Returns an error if transport, HTTP, or JSON-RPC processing fails.
222    pub async fn send_public<P, R>(&self, method: &str, params: &P) -> Result<R>
223    where
224        P: Serialize + ?Sized,
225        R: DeserializeOwned,
226    {
227        let id = self.next_id();
228        self.dispatch(method, params, id, false, true, None).await
229    }
230
231    /// Sends an authenticated idempotent request (private reads).
232    ///
233    /// Used for `private/get_*` endpoints whose responses are pure reads of
234    /// venue state. Transient failures retry via the configured
235    /// [`RetryManager`].
236    ///
237    /// # Errors
238    ///
239    /// Returns an error if the client was built without credentials. Other variants propagate from
240    /// the transport or the venue.
241    pub async fn send_private<P, R>(&self, method: &str, params: &P) -> Result<R>
242    where
243        P: Serialize + ?Sized,
244        R: DeserializeOwned,
245    {
246        if self.credentials.is_none() {
247            return Err(DeriveHttpError::MissingCredentials {
248                method: method.to_owned(),
249            });
250        }
251
252        let id = self.next_id();
253        self.dispatch(method, params, id, true, true, None).await
254    }
255
256    /// Sends an authenticated request exactly once (no retry).
257    ///
258    /// Used for state-changing endpoints (`private/order`, `private/cancel`,
259    /// `private/cancel_all`, `private/cancel_by_label`, `private/replace`)
260    /// where a transport-level failure leaves the venue's view of the
261    /// signed action ambiguous: the request may have been accepted before
262    /// the network broke. Automatic replay would either double-submit (when
263    /// the venue accepted) or trigger a duplicate-nonce rejection (which
264    /// the caller would surface as `OrderRejected` even though the original
265    /// is live). Callers are expected to resolve ambiguous outcomes via
266    /// reconciliation rather than retry here.
267    ///
268    /// Instrument pacing uses the typed wrapper's instrument or the body's
269    /// `instrument_name` field. Requests without an instrument consume only
270    /// their wallet request budgets.
271    ///
272    /// # Errors
273    ///
274    /// Returns an error if the client was built without credentials. Other variants propagate from
275    /// the transport or the venue.
276    pub async fn send_private_once<P, R>(&self, method: &str, params: &P) -> Result<R>
277    where
278        P: Serialize + ?Sized,
279        R: DeserializeOwned,
280    {
281        if self.credentials.is_none() {
282            return Err(DeriveHttpError::MissingCredentials {
283                method: method.to_owned(),
284            });
285        }
286
287        let id = self.next_id();
288        self.dispatch(method, params, id, true, false, None).await
289    }
290
291    /// Sends an authenticated matching-engine write exactly once, pacing it
292    /// against both the wallet and per-instrument allowances.
293    async fn send_private_write<P, R>(
294        &self,
295        method: &str,
296        params: &P,
297        instrument_name: Ustr,
298    ) -> Result<R>
299    where
300        P: Serialize + ?Sized,
301        R: DeserializeOwned,
302    {
303        if self.credentials.is_none() {
304            return Err(DeriveHttpError::MissingCredentials {
305                method: method.to_owned(),
306            });
307        }
308
309        let id = self.next_id();
310        self.dispatch(method, params, id, true, false, Some(instrument_name))
311            .await
312    }
313
314    /// Fetches the venue's listed instruments.
315    ///
316    /// Fetches every page for `currency` and `instrument_type`. For options,
317    /// `expired` selects either live (`false`) or expired (`true`) listings.
318    /// Perpetuals and spot ignore `expired`.
319    ///
320    /// # Errors
321    ///
322    /// Returns an error if transport, HTTP, or JSON-RPC processing fails. Returns a decode error
323    /// for invalid pagination counts or a page count that exceeds the collection limit.
324    pub async fn get_instruments(
325        &self,
326        currency: &str,
327        instrument_type: DeriveInstrumentType,
328        expired: bool,
329    ) -> Result<Vec<DeriveInstrument>> {
330        let mut instruments = Vec::new();
331        let mut names = HashSet::new();
332        let mut pages = PaginationCursor::new_public();
333
334        loop {
335            let params = serde_json::json!({
336                "currency": currency,
337                "instrument_type": instrument_type,
338                "expired": expired,
339                "page": pages.page(),
340                "page_size": 1000,
341            });
342            let result: DeriveInstrumentsResult = self
343                .send_public("public/get_all_instruments", &params)
344                .await?;
345            let more = pages.advance(
346                &result.pagination,
347                result
348                    .instruments
349                    .iter()
350                    .map(|row| row.instrument_name.as_str()),
351            )?;
352            instruments.extend(
353                result
354                    .instruments
355                    .into_iter()
356                    .filter(|row| names.insert(row.instrument_name)),
357            );
358
359            if !more {
360                return Ok(instruments);
361            }
362        }
363    }
364
365    /// Fetches a single instrument definition by name.
366    ///
367    /// Expired options remain queryable by name. Settlement prices appear
368    /// here before they appear in the bulk listing.
369    ///
370    /// # Errors
371    ///
372    /// Returns an error if transport, HTTP, or JSON-RPC processing fails. Returns a decode error
373    /// when the response names a different instrument.
374    pub async fn get_instrument(&self, instrument_name: &str) -> Result<DeriveInstrument> {
375        let params = serde_json::json!({
376            "instrument_name": instrument_name,
377        });
378        let instrument: DeriveInstrument =
379            self.send_public("public/get_instrument", &params).await?;
380
381        if instrument.instrument_name.as_str() != instrument_name {
382            return Err(DeriveHttpError::decode(format!(
383                "instrument response identity mismatch: requested {instrument_name}, received {}",
384                instrument.instrument_name,
385            )));
386        }
387
388        Ok(instrument)
389    }
390
391    /// Fetches a page of public trade history for the instrument.
392    ///
393    /// `from_timestamp` / `to_timestamp` are UNIX milliseconds and bound the
394    /// returned window. `page` is 1-indexed; `page_size` is capped by the venue
395    /// at 1000.
396    ///
397    /// # Errors
398    ///
399    /// Returns an error if transport, HTTP, or JSON-RPC processing fails.
400    /// Returns a decode error if any trade names a different instrument.
401    pub async fn get_trade_history(
402        &self,
403        instrument_name: &str,
404        from_timestamp: Option<i64>,
405        to_timestamp: Option<i64>,
406        page: u32,
407        page_size: u32,
408    ) -> Result<DerivePublicTradesResult> {
409        let mut params = serde_json::Map::new();
410        params.insert("instrument_name".to_string(), instrument_name.into());
411        params.insert("page".to_string(), page.into());
412        params.insert("page_size".to_string(), page_size.into());
413        if let Some(from) = from_timestamp {
414            params.insert("from_timestamp".to_string(), from.into());
415        }
416
417        if let Some(to) = to_timestamp {
418            params.insert("to_timestamp".to_string(), to.into());
419        }
420
421        let result: DerivePublicTradesResult = self
422            .send_public("public/get_trade_history", &Value::Object(params))
423            .await?;
424
425        for trade in &result.trades {
426            if trade.instrument_name.as_str() != instrument_name {
427                return Err(DeriveHttpError::decode(format!(
428                    "trade history response identity mismatch: requested {instrument_name}, received {}",
429                    trade.instrument_name,
430                )));
431            }
432        }
433
434        Ok(result)
435    }
436
437    /// Fetches the public funding rate history for the instrument.
438    ///
439    /// `start_timestamp` / `end_timestamp` are UNIX milliseconds. `period`, if
440    /// provided, selects the sample interval in seconds.
441    ///
442    /// # Errors
443    ///
444    /// Returns an error if transport, HTTP, or JSON-RPC processing fails.
445    pub async fn get_funding_rate_history(
446        &self,
447        instrument_name: &str,
448        start_timestamp: Option<i64>,
449        end_timestamp: Option<i64>,
450        period: Option<u32>,
451    ) -> Result<DerivePublicFundingRateHistoryResult> {
452        let mut params = serde_json::Map::new();
453        params.insert("instrument_name".to_string(), instrument_name.into());
454        if let Some(start) = start_timestamp {
455            params.insert("start_timestamp".to_string(), start.into());
456        }
457
458        if let Some(end) = end_timestamp {
459            params.insert("end_timestamp".to_string(), end.into());
460        }
461
462        if let Some(period) = period {
463            params.insert("period".to_string(), period.into());
464        }
465
466        self.send_public("public/get_funding_rate_history", &Value::Object(params))
467            .await
468    }
469
470    /// Fetches OHLCV candles via `public/get_tradingview_chart_data`.
471    ///
472    /// `start_timestamp` / `end_timestamp` are UNIX **seconds** and bound the
473    /// returned window. `period` is the bucket size in seconds; the venue
474    /// accepts 60, 300, 900, 1800, 3600, 14400, 28800, 86400, and 604800.
475    /// The venue ships `result` as a flat array; the client decodes it
476    /// directly into `Vec<DerivePublicCandle>`.
477    ///
478    /// # Errors
479    ///
480    /// Returns an error if transport, HTTP, or JSON-RPC processing fails.
481    pub async fn get_candles(
482        &self,
483        instrument_name: &str,
484        start_timestamp: i64,
485        end_timestamp: i64,
486        period: u32,
487    ) -> Result<Vec<DerivePublicCandle>> {
488        let params = serde_json::json!({
489            "instrument_name": instrument_name,
490            "start_timestamp": start_timestamp,
491            "end_timestamp": end_timestamp,
492            "period": period,
493        });
494        self.send_public("public/get_tradingview_chart_data", &params)
495            .await
496    }
497
498    /// Fetches current ticker snapshots.
499    ///
500    /// `currency` is the underlying (`"ETH"`, `"BTC"`, etc.). Options require
501    /// both `currency` and `expiry_date`; perps and ERC-20 spot pairs reject
502    /// `expiry_date`.
503    ///
504    /// # Errors
505    ///
506    /// Returns an error if transport, HTTP, or JSON-RPC processing fails.
507    pub async fn get_tickers(
508        &self,
509        instrument_type: DeriveInstrumentType,
510        currency: Option<&str>,
511        expiry_date: Option<&str>,
512    ) -> Result<DeriveTickersResult> {
513        let mut params = serde_json::Map::new();
514        params.insert(
515            "instrument_type".to_string(),
516            serde_json::to_value(instrument_type).map_err(DeriveHttpError::from)?,
517        );
518
519        if let Some(currency) = currency {
520            params.insert("currency".to_string(), currency.into());
521        }
522
523        if let Some(expiry_date) = expiry_date {
524            params.insert("expiry_date".to_string(), expiry_date.into());
525        }
526
527        self.send_public("public/get_tickers", &Value::Object(params))
528            .await
529    }
530
531    /// Fetches the current ticker snapshot for one instrument.
532    ///
533    /// This is a single-instrument convenience wrapper over
534    /// `public/get_tickers`, which replaced Derive's deprecated
535    /// `public/get_ticker` RPC.
536    ///
537    /// # Errors
538    ///
539    /// Returns an error if transport, HTTP, or JSON-RPC processing fails, or the response omits the
540    /// requested instrument.
541    pub async fn get_ticker(&self, instrument_name: &str) -> Result<DeriveTickerSnapshot> {
542        let request = ticker_request(instrument_name)?;
543        let result = self
544            .get_tickers(
545                request.instrument_type,
546                Some(request.currency),
547                request.expiry_date,
548            )
549            .await?;
550
551        let mut ticker = result
552            .tickers
553            .get(instrument_name)
554            .cloned()
555            .ok_or_else(|| {
556                DeriveHttpError::decode(format!(
557                    "missing ticker `{instrument_name}` in public/get_tickers response"
558                ))
559            })?;
560
561        ticker.instrument_name = instrument_name.into();
562        Ok(ticker)
563    }
564
565    /// Submits a signed order to the venue.
566    ///
567    /// `params` must be the fully-built signed `private/order` body.
568    ///
569    /// # Errors
570    ///
571    /// Returns an error if no credentials were installed; otherwise propagates transport and venue
572    /// errors.
573    pub async fn submit_order(&self, params: &DeriveOrderParams) -> Result<DeriveOrder> {
574        let result: DeriveOrderResult = self
575            .send_private_write("private/order", params, params.instrument_name)
576            .await?;
577        Ok(result.order)
578    }
579
580    /// Cancels a single order by venue order id.
581    ///
582    /// # Errors
583    ///
584    /// Returns an error if no credentials were installed; otherwise propagates transport and venue
585    /// errors.
586    pub async fn cancel_order(&self, params: &DeriveCancelParams) -> Result<DeriveEmptyResult> {
587        self.send_private_write("private/cancel", params, params.instrument_name)
588            .await
589    }
590
591    /// Cancels every open order on the subaccount, optionally scoped to an
592    /// instrument.
593    ///
594    /// # Errors
595    ///
596    /// Returns an error if no credentials were installed; otherwise propagates transport and venue
597    /// errors.
598    pub async fn cancel_all(&self, params: &DeriveCancelAllParams) -> Result<DeriveEmptyResult> {
599        self.send_private_once("private/cancel_all", params).await
600    }
601
602    /// Cancels every open order for the given user label on the subaccount.
603    ///
604    /// # Errors
605    ///
606    /// Returns an error if no credentials were installed; otherwise propagates transport and venue
607    /// errors.
608    pub async fn cancel_by_label(
609        &self,
610        params: &DeriveCancelByLabelParams,
611    ) -> Result<DeriveCancelByLabelResult> {
612        self.send_private_once("private/cancel_by_label", params)
613            .await
614    }
615
616    /// Submits a signed `private/replace` request that cancels one order before
617    /// creating its replacement.
618    ///
619    /// `params` must be the fully-built typed request body.
620    ///
621    /// # Errors
622    ///
623    /// Returns an error if no credentials were installed; otherwise propagates transport and venue
624    /// errors.
625    pub async fn replace_order(
626        &self,
627        params: &DeriveReplaceParams,
628    ) -> Result<DeriveReplaceOutcome> {
629        let result: DeriveReplaceResult = self
630            .send_private_write("private/replace", params, params.order.instrument_name)
631            .await?;
632        result
633            .into_outcome(
634                &params.order_id_to_cancel,
635                &params.order.label,
636                params.order.envelope.subaccount_id,
637                params.order.instrument_name.as_str(),
638            )
639            .map_err(DeriveHttpError::decode)
640    }
641
642    /// Returns the subaccount snapshot including margin, balances, and
643    /// open orders.
644    ///
645    /// # Errors
646    ///
647    /// Returns an error if no credentials were installed; otherwise propagates transport and venue
648    /// errors. Returns a decode error if a response subaccount ID differs from the request.
649    pub async fn get_subaccount(
650        &self,
651        params: &DeriveGetSubaccountParams,
652    ) -> Result<DeriveSubaccount> {
653        let result: DeriveSubaccount = self.send_private("private/get_subaccount", params).await?;
654        validate_subaccount_id(params.subaccount_id, result.subaccount_id)?;
655        validate_order_subaccounts(params.subaccount_id, &result.open_orders)?;
656        Ok(result)
657    }
658
659    /// Returns currently open orders for the subaccount.
660    ///
661    /// # Errors
662    ///
663    /// Returns an error if no credentials were installed; otherwise propagates transport and venue
664    /// errors. Returns a decode error if a response subaccount ID differs from the request.
665    pub async fn get_open_orders(
666        &self,
667        params: &DeriveGetOpenOrdersParams,
668    ) -> Result<DeriveOpenOrdersResult> {
669        let result: DeriveOpenOrdersResult =
670            self.send_private("private/get_open_orders", params).await?;
671        validate_subaccount_id(params.subaccount_id, result.subaccount_id)?;
672        validate_order_subaccounts(params.subaccount_id, &result.orders)?;
673        Ok(result)
674    }
675
676    /// Returns currently untriggered trigger orders for the subaccount.
677    ///
678    /// # Errors
679    ///
680    /// Returns an error if no credentials were installed; otherwise propagates transport and venue
681    /// errors. Returns a decode error if a response subaccount ID differs from the request.
682    pub async fn get_trigger_orders(
683        &self,
684        params: &DeriveGetTriggerOrdersParams,
685    ) -> Result<DeriveOpenOrdersResult> {
686        let result: DeriveOpenOrdersResult = self
687            .send_private("private/get_trigger_orders", params)
688            .await?;
689        validate_subaccount_id(params.subaccount_id, result.subaccount_id)?;
690        validate_order_subaccounts(params.subaccount_id, &result.orders)?;
691        Ok(result)
692    }
693
694    /// Returns a single order by venue order id.
695    ///
696    /// # Errors
697    ///
698    /// Returns an error if no credentials were installed; otherwise propagates transport and venue
699    /// errors. Returns a decode error if a response subaccount ID differs from the request.
700    pub async fn get_order(&self, params: &DeriveGetOrderParams) -> Result<DeriveOrder> {
701        let result: DeriveOrder = self.send_private("private/get_order", params).await?;
702        validate_subaccount_id(params.subaccount_id, result.subaccount_id)?;
703        Ok(result)
704    }
705
706    /// Returns one page of order history for the subaccount, optionally
707    /// scoped to an instrument and time window.
708    ///
709    /// `from_timestamp` / `to_timestamp` are UNIX milliseconds. `page` is
710    /// 1-indexed and `page_size` is capped by the venue at 1000.
711    ///
712    /// # Errors
713    ///
714    /// Returns an error if no credentials were installed; otherwise propagates transport and venue
715    /// errors. Returns a decode error if a response subaccount ID differs from the request.
716    pub async fn get_order_history(
717        &self,
718        params: &DeriveGetOrderHistoryParams,
719    ) -> Result<DeriveOrdersResult> {
720        let result: DeriveOrdersResult = self
721            .send_private("private/get_order_history", params)
722            .await?;
723        validate_subaccount_id(params.subaccount_id, result.subaccount_id)?;
724        validate_order_subaccounts(params.subaccount_id, &result.orders)?;
725        Ok(result)
726    }
727
728    /// Returns one page of subaccount trade history.
729    ///
730    /// # Errors
731    ///
732    /// Returns an error if no credentials were installed; otherwise propagates transport and venue
733    /// errors. Returns a decode error if a response subaccount ID differs from the request.
734    pub async fn get_private_trade_history(
735        &self,
736        params: &DeriveGetTradeHistoryParams,
737    ) -> Result<DeriveTradesResult> {
738        let result: DeriveTradesResult = self
739            .send_private("private/get_trade_history", params)
740            .await?;
741        validate_subaccount_id(params.subaccount_id, result.subaccount_id)?;
742        for trade in &result.trades {
743            validate_subaccount_id(params.subaccount_id, trade.subaccount_id)?;
744        }
745
746        Ok(result)
747    }
748
749    /// Returns the positions held by the subaccount.
750    ///
751    /// # Errors
752    ///
753    /// Returns an error if no credentials were installed; otherwise propagates transport and venue
754    /// errors. Returns a decode error if a response subaccount ID differs from the request.
755    pub async fn get_positions(
756        &self,
757        params: &DeriveGetPositionsParams,
758    ) -> Result<DerivePositionsResult> {
759        let result: DerivePositionsResult =
760            self.send_private("private/get_positions", params).await?;
761        validate_subaccount_id(params.subaccount_id, result.subaccount_id)?;
762        Ok(result)
763    }
764
765    async fn dispatch<P, R>(
766        &self,
767        method: &str,
768        params: &P,
769        id: u64,
770        authenticate: bool,
771        retry: bool,
772        instrument_name: Option<Ustr>,
773    ) -> Result<R>
774    where
775        P: Serialize + ?Sized,
776        R: DeserializeOwned,
777    {
778        let url = format!(
779            "{}/{}",
780            self.base_url.expose(),
781            method.trim_start_matches('/')
782        );
783        let mut body_value = serde_json::to_value(params).map_err(DeriveHttpError::from)?;
784        let body = serde_json::to_string(&body_value).map_err(DeriveHttpError::from);
785
786        let rate_class = rate_limit::rate_class_for_method(method);
787
788        let instrument_name = instrument_name.or_else(|| {
789            body_value
790                .get("instrument_name")
791                .and_then(Value::as_str)
792                .map(Ustr::from)
793        });
794
795        zeroize_json_value(&mut body_value);
796        let body = SecretString::from(body?);
797
798        // Sign per-attempt so the venue never sees a stale `X-DeriveTimestamp`
799        // after a long backoff window; single-shot writes still run the
800        // closure once and use freshly built headers. The pacing wait
801        // happens inside the closure, so pacing delays never consume the
802        // signed timestamp's validity.
803        let attempt = || async {
804            if authenticate {
805                self.rate_limiter
806                    .await_class_ready(rate_class, instrument_name.as_ref())
807                    .await;
808            } else {
809                self.rate_limiter.await_public_ready().await;
810            }
811
812            let mut headers: AHashMap<String, String> = AHashMap::with_capacity(4);
813            headers.insert("Content-Type".to_string(), "application/json".to_string());
814
815            if authenticate {
816                let auth = self.build_auth_headers(method)?;
817                headers.insert(HEADER_DERIVE_WALLET.to_string(), auth.wallet);
818                headers.insert(HEADER_DERIVE_TIMESTAMP.to_string(), auth.timestamp);
819                headers.insert(
820                    HEADER_DERIVE_SIGNATURE.to_string(),
821                    auth.signature.into_inner(),
822                );
823            }
824
825            let response = self
826                .client
827                .request_with_secret_body(
828                    Method::POST,
829                    url.clone(),
830                    None,
831                    Some(headers.into_iter().collect()),
832                    body.clone(),
833                    Some(self.timeout_secs),
834                    None,
835                )
836                .await
837                .map_err(DeriveHttpError::from)?;
838
839            decode_envelope(method, id, response)
840        };
841
842        if retry {
843            self.retry_manager
844                .invocation(
845                    method,
846                    attempt,
847                    should_retry_http_error,
848                    DeriveHttpError::Retry,
849                )
850                .retry_delay(&DeriveHttpError::retry_after)
851                .execute()
852                .await
853        } else {
854            attempt().await
855        }
856    }
857
858    fn build_auth_headers(&self, method: &str) -> Result<AuthHeaders> {
859        let credentials =
860            self.credentials
861                .as_ref()
862                .ok_or_else(|| DeriveHttpError::MissingCredentials {
863                    method: method.to_owned(),
864                })?;
865
866        let auth = build_rest_auth_headers(&credentials.wallet_address, &credentials.signer)?;
867        Ok(auth)
868    }
869}
870
871#[derive(Debug, Clone, Copy)]
872struct TickerRequest<'a> {
873    instrument_type: DeriveInstrumentType,
874    currency: &'a str,
875    expiry_date: Option<&'a str>,
876}
877
878fn ticker_request(instrument_name: &str) -> Result<TickerRequest<'_>> {
879    let Some((currency, suffix)) = instrument_name.split_once('-') else {
880        return Err(DeriveHttpError::decode(format!(
881            "invalid Derive instrument name `{instrument_name}`"
882        )));
883    };
884
885    if suffix == "PERP" {
886        return Ok(TickerRequest {
887            instrument_type: DeriveInstrumentType::Perp,
888            currency,
889            expiry_date: None,
890        });
891    }
892
893    let mut parts = suffix.split('-');
894
895    let Some(expiry_date) = parts.next() else {
896        return Ok(TickerRequest {
897            instrument_type: DeriveInstrumentType::Erc20,
898            currency,
899            expiry_date: None,
900        });
901    };
902
903    let has_option_tail = parts.clone().count() == 2;
904    if expiry_date.len() == 8 && expiry_date.chars().all(|c| c.is_ascii_digit()) && has_option_tail
905    {
906        return Ok(TickerRequest {
907            instrument_type: DeriveInstrumentType::Option,
908            currency,
909            expiry_date: Some(expiry_date),
910        });
911    }
912
913    Ok(TickerRequest {
914        instrument_type: DeriveInstrumentType::Erc20,
915        currency,
916        expiry_date: None,
917    })
918}
919
920fn build_client(
921    timeout_secs: u64,
922    proxy_url: Option<String>,
923) -> std::result::Result<HttpClient, HttpClientError> {
924    HttpClient::builder()
925        .redirect_policy(HttpRedirectPolicy::Reject)
926        .headers(create_standard_nautilus_headers().into_iter().collect())
927        .header_keys(vec![RETRY_AFTER.as_str().to_string()])
928        .timeout_secs(timeout_secs)
929        .maybe_proxy_url(proxy_url)
930        .rate_limiters(Vec::new())
931        .build()
932}
933
934fn trim_trailing_slash(url: String) -> String {
935    if url.ends_with('/') {
936        url.trim_end_matches('/').to_string()
937    } else {
938        url
939    }
940}
941
942fn decode_envelope<R: DeserializeOwned>(
943    method: &str,
944    request_id: u64,
945    response: HttpResponse,
946) -> Result<R> {
947    let status = response.status.as_u16();
948
949    let retry_after = response
950        .headers
951        .get(RETRY_AFTER.as_str())
952        .and_then(|value| {
953            parse_retry_after(
954                value,
955                nautilus_core::UnixNanos::from(nautilus_core::time::nanos_since_unix_epoch())
956                    .to_datetime_utc(),
957            )
958        });
959
960    let is_success_status = (200..300).contains(&status);
961    let body = response.body;
962
963    let envelope: JsonRpcResponse<R> = match serde_json::from_slice(&body) {
964        Ok(env) => env,
965        Err(e) => {
966            if !is_success_status {
967                let text = String::from_utf8_lossy(&body).into_owned();
968                return Err(DeriveHttpError::Http {
969                    status,
970                    message: truncate(text, 512),
971                    retry_after,
972                });
973            }
974
975            return Err(DeriveHttpError::decode(format!(
976                "failed to decode `{method}` response: {e}",
977            )));
978        }
979    };
980
981    if let Some(err) = envelope.error {
982        return Err(DeriveHttpError::JsonRpc {
983            code: err.code,
984            message: err.message,
985            data: err.data,
986            retry_after,
987        });
988    }
989
990    // Gateways (Cloudflare, the wallet auth proxy) return non-2xx with a JSON body
991    // like {"message": "Unauthorized"} that parses into an empty envelope. Surface
992    // those as Http errors so retry/reconcile logic sees the real status code
993    // instead of MissingResult.
994    if !is_success_status {
995        let text = String::from_utf8_lossy(&body).into_owned();
996        return Err(DeriveHttpError::Http {
997            status,
998            message: truncate(text, 512),
999            retry_after,
1000        });
1001    }
1002
1003    if let Some(echoed) = envelope.id
1004        && echoed != request_id
1005    {
1006        log::debug!(
1007            "derive: id mismatch for `{method}` (sent={request_id}, recv={echoed}); accepting result",
1008        );
1009    }
1010
1011    envelope
1012        .result
1013        .ok_or_else(|| DeriveHttpError::MissingResult {
1014            method: method.to_owned(),
1015        })
1016}
1017
1018fn truncate(s: String, max: usize) -> String {
1019    if s.len() <= max {
1020        return s;
1021    }
1022
1023    let mut cutoff = max;
1024    while cutoff > 0 && !s.is_char_boundary(cutoff) {
1025        cutoff -= 1;
1026    }
1027
1028    let mut out = String::with_capacity(cutoff + 3);
1029    out.push_str(&s[..cutoff]);
1030    out.push_str("...");
1031    out
1032}
1033
1034fn validate_order_subaccounts(expected: u64, orders: &[DeriveOrder]) -> Result<()> {
1035    for order in orders {
1036        validate_subaccount_id(expected, order.subaccount_id)?;
1037    }
1038
1039    Ok(())
1040}
1041
1042fn validate_subaccount_id(expected: u64, received: i64) -> Result<()> {
1043    if u64::try_from(received).ok() != Some(expected) {
1044        return Err(DeriveHttpError::decode(format!(
1045            "subaccount response identity mismatch: requested {expected}, received {received}",
1046        )));
1047    }
1048
1049    Ok(())
1050}
1051
1052#[cfg(test)]
1053mod tests {
1054    use std::collections::HashMap;
1055
1056    use nautilus_network::http::{HttpStatus, StatusCode};
1057    use nautilus_testkit::http::assert_http_redirect_rejected;
1058    use rstest::rstest;
1059
1060    use super::*;
1061
1062    const SESSION_KEY_HEX: &str =
1063        "0x2ae8be44db8a590d20bffbe3b6872df9b569147d3bf6801a35a28281a4816bbd";
1064    const TEST_WALLET: &str = "0x000000000000000000000000000000000000aaaa";
1065
1066    #[rstest]
1067    #[case::credentials(
1068        "https://URL_USER:URL_PASSWORD@public.example:8443/URL_PATH?token=URL_QUERY#URL_FRAGMENT",
1069        "https://public.example:8443"
1070    )]
1071    #[case::invalid("URL_PATH", REDACTED)]
1072    #[case::unsupported("file:///URL_PATH", REDACTED)]
1073    fn test_client_debug_redacts_endpoint(#[case] url: &str, #[case] origin: &str) {
1074        let credentials = DeriveCredentials::new(TEST_WALLET, SESSION_KEY_HEX).unwrap();
1075        let client = DeriveHttpClient::with_credentials(
1076            url,
1077            credentials,
1078            None,
1079            Some("http://PROXY_USER:PROXY_PASSWORD@proxy.example:8080".to_string()),
1080            None,
1081        )
1082        .unwrap();
1083
1084        assert_eq!(client.base_url(), url);
1085        assert!(format!("{client:?}").contains(&format!("base_url: {origin:?}")));
1086
1087        for debug in [format!("{client:?}"), format!("{client:#?}")] {
1088            for marker in [
1089                "URL_USER",
1090                "URL_PASSWORD",
1091                "URL_PATH",
1092                "URL_QUERY",
1093                "URL_FRAGMENT",
1094                "PROXY_USER",
1095                "PROXY_PASSWORD",
1096                SESSION_KEY_HEX,
1097            ] {
1098                assert!(!debug.contains(marker), "Debug disclosed {marker}");
1099            }
1100        }
1101    }
1102
1103    fn test_client() -> DeriveHttpClient {
1104        DeriveHttpClient::new("https://api.example/", None, None, None).expect("client builds")
1105    }
1106
1107    fn test_response(status: u16, body: &serde_json::Value) -> HttpResponse {
1108        let status_code = StatusCode::from_u16(status).unwrap();
1109
1110        HttpResponse {
1111            status: HttpStatus::new(status_code),
1112            headers: HashMap::new(),
1113            body: serde_json::to_vec(body).unwrap().into(),
1114        }
1115    }
1116
1117    #[tokio::test]
1118    async fn test_authenticated_client_rejects_redirects() {
1119        let client = build_client(3, None).unwrap();
1120        assert_http_redirect_rejected(|url| async move {
1121            client
1122                .get(url, None, None, Some(3), None)
1123                .await
1124                .unwrap()
1125                .status
1126                .as_u16()
1127        })
1128        .await;
1129    }
1130
1131    #[rstest]
1132    fn test_credentials_debug_redacts_signer() {
1133        let creds = DeriveCredentials::new(TEST_WALLET, SESSION_KEY_HEX).unwrap();
1134        let dbg = format!("{creds:?}");
1135        assert!(dbg.contains(REDACTED));
1136        assert!(dbg.contains(TEST_WALLET));
1137        assert!(!dbg.contains(SESSION_KEY_HEX));
1138    }
1139
1140    #[rstest]
1141    fn test_credentials_rejects_invalid_session_key() {
1142        let err = DeriveCredentials::new(TEST_WALLET, "not-hex").expect_err("must reject");
1143        match err {
1144            DeriveHttpError::Decode(msg) => assert!(msg.contains("invalid session key")),
1145            other => panic!("expected Decode, was {other:?}"),
1146        }
1147    }
1148
1149    #[rstest]
1150    fn test_base_url_trims_trailing_slash() {
1151        let client = test_client();
1152        assert_eq!(client.base_url(), "https://api.example");
1153    }
1154
1155    #[rstest]
1156    fn test_new_has_no_credentials() {
1157        assert!(!test_client().has_credentials());
1158    }
1159
1160    #[rstest]
1161    fn test_with_credentials_sets_creds() {
1162        let creds = DeriveCredentials::new(TEST_WALLET, SESSION_KEY_HEX).unwrap();
1163        let client =
1164            DeriveHttpClient::with_credentials("https://api.example", creds, None, None, None)
1165                .unwrap();
1166        assert!(client.has_credentials());
1167    }
1168
1169    #[rstest]
1170    fn test_next_id_increments_monotonically() {
1171        let client = test_client();
1172        let a = client.next_id();
1173        let b = client.next_id();
1174        let c = client.next_id();
1175        assert_eq!(b, a + 1);
1176        assert_eq!(c, b + 1);
1177    }
1178
1179    #[rstest]
1180    fn test_decode_envelope_returns_result() {
1181        let resp = test_response(200, &serde_json::json!({"id": 1, "result": {"ok": true}}));
1182        let value: Value = decode_envelope("public/get_instruments", 1, resp).unwrap();
1183        assert_eq!(value["ok"], true);
1184    }
1185
1186    #[rstest]
1187    fn test_decode_envelope_accepts_null_empty_result() {
1188        let resp = test_response(200, &serde_json::json!({"id": 1, "result": null}));
1189        let result: DeriveEmptyResult = decode_envelope("private/cancel", 1, resp).unwrap();
1190        assert_eq!(result, DeriveEmptyResult {});
1191    }
1192
1193    #[rstest]
1194    fn test_decode_envelope_propagates_jsonrpc_error() {
1195        let resp = test_response(
1196            200,
1197            &serde_json::json!({
1198                "id": 1,
1199                "error": {"code": -32601, "message": "Method not found"}
1200            }),
1201        );
1202        let err: DeriveHttpError = decode_envelope::<Value>("public/missing", 1, resp).unwrap_err();
1203        match err {
1204            DeriveHttpError::JsonRpc { code, message, .. } => {
1205                assert_eq!(code, -32601);
1206                assert_eq!(message, "Method not found");
1207            }
1208            other => panic!("expected JsonRpc, was {other:?}"),
1209        }
1210    }
1211
1212    #[rstest]
1213    fn test_decode_envelope_flags_missing_result() {
1214        let resp = test_response(200, &serde_json::json!({"id": 1}));
1215        let err = decode_envelope::<Value>("public/get_instruments", 1, resp).unwrap_err();
1216        assert!(matches!(err, DeriveHttpError::MissingResult { .. }));
1217    }
1218
1219    #[rstest]
1220    fn test_decode_envelope_flags_non_2xx_with_unparsable_body() {
1221        let status_code = StatusCode::from_u16(503).unwrap();
1222
1223        let response = HttpResponse {
1224            status: HttpStatus::new(status_code),
1225            headers: HashMap::new(),
1226            body: bytes::Bytes::from_static(b"<html>upstream down</html>"),
1227        };
1228
1229        let err = decode_envelope::<Value>("public/get_instruments", 1, response).unwrap_err();
1230        match err {
1231            DeriveHttpError::Http {
1232                status, message, ..
1233            } => {
1234                assert_eq!(status, 503);
1235                assert!(message.contains("upstream down"));
1236            }
1237            other => panic!("expected Http, was {other:?}"),
1238        }
1239    }
1240
1241    #[rstest]
1242    fn test_decode_envelope_flags_non_2xx_with_non_envelope_json() {
1243        // Gateways return non-2xx with JSON bodies like {"message": "Unauthorized"}.
1244        // These parse as an empty JsonRpcResponse; the status must still surface.
1245        let resp = test_response(401, &serde_json::json!({"message": "Unauthorized"}));
1246        let err = decode_envelope::<Value>("private/order", 1, resp).unwrap_err();
1247        match err {
1248            DeriveHttpError::Http {
1249                status, message, ..
1250            } => {
1251                assert_eq!(status, 401);
1252                assert!(message.contains("Unauthorized"));
1253            }
1254            other => panic!("expected Http, was {other:?}"),
1255        }
1256    }
1257
1258    #[rstest]
1259    fn test_decode_envelope_prefers_jsonrpc_error_over_http_status() {
1260        // When the venue returns a proper JSON-RPC error envelope with a non-2xx
1261        // status, the envelope wins because it carries richer venue context.
1262        let status_code = StatusCode::from_u16(400).unwrap();
1263        let body = serde_json::json!({
1264            "id": 1,
1265            "error": {"code": -32602, "message": "Invalid params"},
1266        });
1267
1268        let response = HttpResponse {
1269            status: HttpStatus::new(status_code),
1270            headers: HashMap::new(),
1271            body: serde_json::to_vec(&body).unwrap().into(),
1272        };
1273
1274        let err = decode_envelope::<Value>("private/order", 1, response).unwrap_err();
1275        assert!(matches!(err, DeriveHttpError::JsonRpc { code: -32602, .. }));
1276    }
1277
1278    #[rstest]
1279    fn test_truncate_handles_multi_byte_char_at_boundary() {
1280        // "Ω" is two bytes (0xCE 0xA9). Truncating to a length that lands mid-glyph
1281        // must not panic; we step back to the prior char boundary.
1282        let s = "ΩΩΩΩΩΩΩΩΩΩ".to_string();
1283        assert_eq!(s.len(), 20);
1284        let out = truncate(s, 5);
1285        assert!(out.ends_with("..."));
1286        let prefix = out.trim_end_matches("...");
1287        assert!(prefix.is_char_boundary(prefix.len()));
1288        assert!(prefix.chars().all(|c| c == 'Ω'));
1289    }
1290
1291    #[rstest]
1292    fn test_truncate_returns_input_when_under_limit() {
1293        let s = "short".to_string();
1294        assert_eq!(truncate(s, 16), "short");
1295    }
1296
1297    #[rstest]
1298    fn test_decode_envelope_non_2xx_body_with_non_ascii_does_not_panic() {
1299        // Regression: a Cloudflare-style 503 page containing non-ASCII bytes near
1300        // the truncation cutoff must not panic.
1301        let glyph = "Ω";
1302        let body = glyph.repeat(600);
1303        let status_code = StatusCode::from_u16(503).unwrap();
1304
1305        let response = HttpResponse {
1306            status: HttpStatus::new(status_code),
1307            headers: HashMap::new(),
1308            body: body.into_bytes().into(),
1309        };
1310
1311        let err = decode_envelope::<Value>("public/get_instruments", 1, response).unwrap_err();
1312        assert!(matches!(err, DeriveHttpError::Http { status: 503, .. }));
1313    }
1314
1315    #[rstest]
1316    fn test_decode_envelope_accepts_id_mismatch() {
1317        let resp = test_response(200, &serde_json::json!({"id": 99, "result": "ok"}));
1318        let value: Value = decode_envelope("public/get_instruments", 1, resp).unwrap();
1319        assert_eq!(value, serde_json::json!("ok"));
1320    }
1321
1322    #[tokio::test]
1323    async fn test_send_private_without_credentials_errors() {
1324        let client = test_client();
1325        let err = client
1326            .send_private::<_, Value>("private/order", &serde_json::json!({}))
1327            .await
1328            .expect_err("must require credentials");
1329
1330        match err {
1331            DeriveHttpError::MissingCredentials { method } => {
1332                assert_eq!(method, "private/order");
1333            }
1334            other => panic!("expected MissingCredentials, was {other:?}"),
1335        }
1336    }
1337}