Fix Deribit chart bar volume for inverse perpetuals (#4245)

Author: filipmacek

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

@@ -25,12 +25,12 @@ use nautilus_core::{
 };
 use nautilus_model::{
     data::{Bar, BarType, BookOrder, TradeTick},
-    enums::{AccountType, AggressorSide, BookType, OptionKind, OrderSide},
+    enums::{AccountType, AggressorSide, BookType, InstrumentClass, OptionKind, OrderSide},
     events::AccountState,
     identifiers::{AccountId, InstrumentId, Symbol, TradeId},
     instruments::{
         CryptoFuture, CryptoFuturesSpread, CryptoOption, CryptoOptionSpread, CryptoPerpetual,
-        CurrencyPair, any::InstrumentAny,
+        CurrencyPair, Instrument, any::InstrumentAny,
     },
     orderbook::OrderBook,
     types::{AccountBalance, Currency, MarginBalance, Money, Price, Quantity},
@@ -860,11 +860,35 @@ pub fn parse_trade_tick(
     ))
 }
 
+/// Returns true when `Bar.volume` should be populated from the chart `cost` field (USD) instead
+/// of the `volume` field (base currency).
+///
+/// Deribit's `trades.{instrument}` channel reports each trade's `amount` in USD for inverse
+/// perpetuals and inverse futures, and in the underlying base currency for options and linear
+/// futures. To keep `Bar.volume` and `TradeTick.size` on a single unit per instrument, route
+/// inverse non-option products through `cost`. Options and option spreads stay on `volume` even
+/// when flagged `is_inverse`, because their trade `amount` is reported in base currency.
+///
+/// Reference: <https://docs.deribit.com/api-reference/market-data/public-get_last_trades_by_currency>
+#[must_use]
+pub fn use_cost_for_bar_volume(instrument: &InstrumentAny) -> bool {
+    if !instrument.is_inverse() {
+        return false;
+    }
+    !matches!(
+        instrument.instrument_class(),
+        InstrumentClass::Option | InstrumentClass::OptionSpread
+    )
+}
+
 /// Parses Deribit TradingView chart data into Nautilus [`Bar`]s.
 ///
 /// Converts OHLCV arrays from the `public/get_tradingview_chart_data` endpoint
 /// into a vector of [`Bar`] objects.
 ///
+/// When `use_cost_for_volume` is true, `Bar.volume` is populated from `chart_data.cost` (USD)
+/// instead of `chart_data.volume` (base currency) — see [`use_cost_for_bar_volume`].
+///
 /// # Errors
 ///
 /// Returns an error if:
@@ -876,6 +900,7 @@ pub fn parse_bars(
     bar_type: BarType,
     price_precision: u8,
     size_precision: u8,
+    use_cost_for_volume: bool,
     ts_init: UnixNanos,
 ) -> anyhow::Result<Vec<Bar>> {
     // Check status
@@ -894,7 +919,8 @@ pub fn parse_bars(
             && chart_data.high.len() == num_bars
             && chart_data.low.len() == num_bars
             && chart_data.close.len() == num_bars
-            && chart_data.volume.len() == num_bars,
+            && chart_data.volume.len() == num_bars
+            && chart_data.cost.len() == num_bars,
         "Inconsistent array lengths in chart data"
     );
 
@@ -913,7 +939,12 @@ pub fn parse_bars(
             .with_context(|| format!("Invalid low price at index {i}"))?;
         let close = Price::new_checked(chart_data.close[i], price_precision)
             .with_context(|| format!("Invalid close price at index {i}"))?;
-        let volume = Quantity::new_checked(chart_data.volume[i], size_precision)
+        let raw_volume = if use_cost_for_volume {
+            chart_data.cost[i]
+        } else {
+            chart_data.volume[i]
+        };
+        let volume = Quantity::new_checked(raw_volume, size_precision)
             .with_context(|| format!("Invalid volume at index {i}"))?;
 
         // Convert timestamp from milliseconds to nanoseconds
@@ -1402,7 +1433,56 @@ mod tests {
     }
 
     #[rstest]
-    fn test_parse_bars() {
+    fn test_use_cost_for_bar_volume() {
+        // Inverse perpetual: BTC-PERPETUAL → cost (USD)
+        let perp_json = load_test_json("http_get_instrument.json");
+        let perp_response: DeribitJsonRpcResponse<DeribitInstrument> =
+            serde_json::from_str(&perp_json).unwrap();
+        let perp_inst = perp_response.result.expect("Test data must have result");
+        let perp =
+            parse_deribit_instrument_any(&perp_inst, UnixNanos::default(), UnixNanos::default())
+                .unwrap()
+                .expect("Should parse perpetual");
+        assert!(perp.is_inverse());
+        assert!(use_cost_for_bar_volume(&perp));
+
+        // BTC inverse option: is_inverse, but trade amount is in BTC, so stay on volume
+        let instruments_json = load_test_json("http_get_instruments.json");
+        let instruments_response: DeribitJsonRpcResponse<Vec<DeribitInstrument>> =
+            serde_json::from_str(&instruments_json).unwrap();
+        let instruments = instruments_response
+            .result
+            .expect("Test data must have result");
+
+        let option_inst = instruments
+            .iter()
+            .find(|i| i.instrument_name.as_str() == "BTC-27DEC24-100000-C")
+            .expect("Test data must contain BTC-27DEC24-100000-C");
+        let option =
+            parse_deribit_instrument_any(option_inst, UnixNanos::default(), UnixNanos::default())
+                .unwrap()
+                .expect("Should parse option");
+        assert!(option.is_inverse());
+        assert!(
+            !use_cost_for_bar_volume(&option),
+            "options report trade amount in base currency, must keep using volume",
+        );
+
+        // Inverse future: same convention as perp — cost (USD)
+        let future_inst = instruments
+            .iter()
+            .find(|i| i.instrument_name.as_str() == "BTC-27DEC24")
+            .expect("Test data must contain BTC-27DEC24");
+        let future =
+            parse_deribit_instrument_any(future_inst, UnixNanos::default(), UnixNanos::default())
+                .unwrap()
+                .expect("Should parse future");
+        assert!(future.is_inverse());
+        assert!(use_cost_for_bar_volume(&future));
+    }
+
+    #[rstest]
+    fn test_parse_bars_uses_volume_field() {
         let json_data = load_test_json("http_get_tradingview_chart_data.json");
         let response: DeribitJsonRpcResponse<DeribitTradingViewChartData> =
             serde_json::from_str(&json_data).unwrap();
@@ -1411,7 +1491,8 @@ mod tests {
         let bar_type = BarType::from("BTC-PERPETUAL.DERIBIT-1-MINUTE-LAST-EXTERNAL");
         let ts_init = UnixNanos::from(1766487086146245_u64 * NANOSECONDS_IN_MICROSECOND);
 
-        let bars = parse_bars(&chart_data, bar_type, 1, 8, ts_init).expect("Should parse bars");
+        let bars =
+            parse_bars(&chart_data, bar_type, 1, 8, false, ts_init).expect("Should parse bars");
 
         assert_eq!(bars.len(), 5, "Should parse 5 bars");
 
@@ -1442,6 +1523,24 @@ mod tests {
         );
     }
 
+    #[rstest]
+    fn test_parse_bars_cost_path() {
+        let json_data = load_test_json("http_get_tradingview_chart_data.json");
+        let response: DeribitJsonRpcResponse<DeribitTradingViewChartData> =
+            serde_json::from_str(&json_data).unwrap();
+        let chart_data = response.result.expect("Test data must have result");
+
+        let bar_type = BarType::from("BTC-PERPETUAL.DERIBIT-1-MINUTE-LAST-EXTERNAL");
+        let ts_init = UnixNanos::from(1766487086146245_u64 * NANOSECONDS_IN_MICROSECOND);
+
+        // Cost path picks `cost` (USD), matching trade `amount` on inverse perps/futures.
+        let bars =
+            parse_bars(&chart_data, bar_type, 1, 0, true, ts_init).expect("Should parse bars");
+        assert_eq!(bars.len(), 5);
+        assert_eq!(bars[0].volume, Quantity::from("257490"));
+        assert_eq!(bars[4].volume, Quantity::from("8910"));
+    }
+
     #[rstest]
     fn test_parse_order_book() {
         let json_data = load_test_json("http_get_order_book.json");

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

@@ -79,6 +79,7 @@ use crate::{
         parse::{
             extract_server_timestamp, parse_account_state, parse_bars,
             parse_deribit_instrument_any, parse_order_book, parse_trade_tick,
+            use_cost_for_bar_volume,
         },
         urls::get_http_base_url,
     },
@@ -1433,11 +1434,15 @@ impl DeribitHttpClient {
             return Ok(Vec::new());
         }
 
-        // Get instrument from cache to determine precisions
+        // Get instrument from cache to determine precisions and volume-field selection.
         let instrument_id = bar_type.instrument_id();
-        let (price_precision, size_precision) =
+        let (price_precision, size_precision, use_cost_for_volume) =
             if let Some(instrument) = self.get_instrument(&instrument_id.symbol.inner()) {
-                (instrument.price_precision(), instrument.size_precision())
+                (
+                    instrument.price_precision(),
+                    instrument.size_precision(),
+                    use_cost_for_bar_volume(&instrument),
+                )
             } else {
                 log::warn!("Instrument {instrument_id} not in cache, skipping bars request");
                 anyhow::bail!("Instrument {instrument_id} not in cache");
@@ -1449,6 +1454,7 @@ impl DeribitHttpClient {
             bar_type,
             price_precision,
             size_precision,
+            use_cost_for_volume,
             ts_init,
         )?;
 

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

@@ -515,7 +515,6 @@ pub struct DeribitTradingViewChartData {
     /// List of prices at close (one per candle)
     pub close: Vec<f64>,
     /// List of cost bars (volume in quote currency, one per candle)
-    #[serde(default)]
     pub cost: Vec<f64>,
     /// List of highest price levels (one per candle)
     pub high: Vec<f64>,

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

@@ -70,7 +70,7 @@ use crate::{
     common::{
         consts::{DERIBIT_POST_ONLY_ERROR_CODE, DERIBIT_RATE_LIMIT_KEY_ORDER, DERIBIT_VENUE},
         enums::DeribitInstrumentState,
-        parse::parse_portfolio_to_account_state,
+        parse::{parse_portfolio_to_account_state, use_cost_for_bar_volume},
     },
     data_types::DeribitVolatilityIndex,
 };
@@ -1935,12 +1935,15 @@ impl DeribitWsFeedHandler {
                                             Ok(bar_type) => {
                                                 let price_precision = instrument.price_precision();
                                                 let size_precision = instrument.size_precision();
+                                                let use_cost_for_volume =
+                                                    use_cost_for_bar_volume(instrument);
 
                                                 match parse_chart_msg(
                                                     &chart_msg,
                                                     bar_type,
                                                     price_precision,
                                                     size_precision,
+                                                    use_cost_for_volume,
                                                     self.bars_timestamp_on_close,
                                                     ts_init,
                                                 ) {

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

@@ -659,6 +659,11 @@ pub fn resolution_to_bar_type(
 /// Converts a single OHLCV data point from the `chart.trades.{instrument}.{resolution}` channel
 /// into a Nautilus Bar object.
 ///
+/// When `use_cost_for_volume` is true, `Bar.volume` is populated from `chart_msg.cost` (USD) to
+/// match instruments whose trade `amount` is in USD (inverse perpetuals / inverse futures).
+/// Otherwise `chart_msg.volume` (base currency) is used. Callers derive this from the instrument
+/// via [`crate::common::parse::use_cost_for_bar_volume`].
+///
 /// # Errors
 ///
 /// Returns an error if:
@@ -669,6 +674,7 @@ pub fn parse_chart_msg(
     bar_type: BarType,
     price_precision: u8,
     size_precision: u8,
+    use_cost_for_volume: bool,
     timestamp_on_close: bool,
     ts_init: UnixNanos,
 ) -> anyhow::Result<Bar> {
@@ -677,8 +683,12 @@ pub fn parse_chart_msg(
     let low = Price::new_checked(chart_msg.low, price_precision).context("Invalid low price")?;
     let close =
         Price::new_checked(chart_msg.close, price_precision).context("Invalid close price")?;
-    let volume =
-        Quantity::new_checked(chart_msg.volume, size_precision).context("Invalid volume")?;
+    let raw_volume = if use_cost_for_volume {
+        chart_msg.cost
+    } else {
+        chart_msg.volume
+    };
+    let volume = Quantity::new_checked(raw_volume, size_precision).context("Invalid volume")?;
 
     // Convert timestamp from milliseconds to nanoseconds
     let mut ts_event = UnixNanos::from(chart_msg.tick * NANOSECONDS_IN_MILLISECOND);
@@ -1872,8 +1882,13 @@ mod tests {
     }
 
     #[rstest]
-    fn test_parse_chart_msg() {
+    fn test_parse_chart_msg_uses_cost() {
         let instrument = test_perpetual_instrument();
+        assert!(
+            instrument.is_inverse(),
+            "test fixture is expected to be an inverse perp"
+        );
+
         let json = load_test_json("ws_chart.json");
         let response: serde_json::Value = serde_json::from_str(&json).unwrap();
         let chart_msg: DeribitChartMsg =
@@ -1896,6 +1911,7 @@ mod tests {
             bar_type,
             instrument.price_precision(),
             instrument.size_precision(),
+            true, // use_cost_for_volume
             true,
             UnixNanos::default(),
         )
@@ -1906,7 +1922,7 @@ mod tests {
         assert_eq!(bar.high, instrument.make_price(87500.0));
         assert_eq!(bar.low, instrument.make_price(87465.0));
         assert_eq!(bar.close, instrument.make_price(87474.0));
-        assert_eq!(bar.volume, instrument.make_qty(1.0, None)); // Rounded to 1.0 with size_precision=0
+        assert_eq!(bar.volume, instrument.make_qty(83970.0, None));
 
         // ts_event should be close time (open + 1 minute)
         assert_eq!(bar.ts_event, UnixNanos::new(1_767_200_100_000_000_000));