nautilus_deribit/http/
models.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 API models and types.
17
18use nautilus_core::serialization::{deserialize_decimal, deserialize_optional_decimal};
19use rust_decimal::Decimal;
20use serde::{Deserialize, Serialize};
21use ustr::Ustr;
22
23pub use crate::common::{
24    enums::{DeribitCurrency, DeribitOptionType, DeribitProductType},
25    rpc::{DeribitJsonRpcError, DeribitJsonRpcRequest, DeribitJsonRpcResponse},
26};
27
28/// JSON-RPC 2.0 response payload (either success or error).
29#[derive(Debug, Serialize, Deserialize)]
30#[serde(untagged)]
31pub enum DeribitResponsePayload<T> {
32    /// Successful response with result data
33    Success { result: T },
34    /// Error response with error details
35    Error { error: DeribitJsonRpcError },
36}
37
38/// Deribit instrument definition.
39#[derive(Clone, Debug, Serialize, Deserialize)]
40pub struct DeribitInstrument {
41    /// The underlying currency being traded
42    pub base_currency: Ustr,
43    /// Block trade commission for instrument
44    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
45    pub block_trade_commission: Option<Decimal>,
46    /// Minimum amount for block trading
47    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
48    pub block_trade_min_trade_amount: Option<Decimal>,
49    /// Specifies minimal price change for block trading
50    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
51    pub block_trade_tick_size: Option<Decimal>,
52    /// Contract size for instrument
53    #[serde(deserialize_with = "deserialize_decimal")]
54    pub contract_size: Decimal,
55    /// Counter currency for the instrument
56    pub counter_currency: Option<Ustr>,
57    /// The time when the instrument was first created (milliseconds since UNIX epoch)
58    pub creation_timestamp: i64,
59    /// The time when the instrument will expire (milliseconds since UNIX epoch)
60    pub expiration_timestamp: Option<i64>,
61    /// Future type (deprecated, use instrument_type instead)
62    pub future_type: Option<String>,
63    /// Instrument ID
64    pub instrument_id: i64,
65    /// Unique instrument identifier (e.g., "BTC-PERPETUAL")
66    pub instrument_name: Ustr,
67    /// Type of the instrument: "linear" or "reversed"
68    pub instrument_type: Option<String>,
69    /// Indicates if the instrument can currently be traded
70    pub is_active: bool,
71    /// Product type: "future", "option", "spot", "future_combo", "option_combo"
72    pub kind: DeribitProductType,
73    /// Maker commission for instrument
74    #[serde(deserialize_with = "deserialize_decimal")]
75    pub maker_commission: Decimal,
76    /// Maximal leverage for instrument (only for futures)
77    pub max_leverage: Option<i64>,
78    /// Maximal liquidation trade commission for instrument (only for futures)
79    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
80    pub max_liquidation_commission: Option<Decimal>,
81    /// Minimum amount for trading
82    #[serde(deserialize_with = "deserialize_decimal")]
83    pub min_trade_amount: Decimal,
84    /// The option type (only for options)
85    pub option_type: Option<DeribitOptionType>,
86    /// Name of price index that is used for this instrument
87    pub price_index: Option<String>,
88    /// The currency in which the instrument prices are quoted
89    pub quote_currency: Ustr,
90    /// Settlement currency for the instrument (not present for spot)
91    pub settlement_currency: Option<Ustr>,
92    /// The settlement period (not present for spot)
93    pub settlement_period: Option<String>,
94    /// The strike value (only for options)
95    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
96    pub strike: Option<Decimal>,
97    /// Taker commission for instrument
98    #[serde(deserialize_with = "deserialize_decimal")]
99    pub taker_commission: Decimal,
100    /// Specifies minimal price change and number of decimal places for instrument prices
101    #[serde(deserialize_with = "deserialize_decimal")]
102    pub tick_size: Decimal,
103    /// Tick size steps for different price ranges
104    pub tick_size_steps: Option<Vec<DeribitTickSizeStep>>,
105}
106
107/// Tick size step definition for price-dependent tick sizes.
108#[derive(Clone, Debug, Serialize, Deserialize)]
109pub struct DeribitTickSizeStep {
110    /// The price from which the increased tick size applies
111    #[serde(deserialize_with = "deserialize_decimal")]
112    pub above_price: Decimal,
113    /// Tick size to be used above the price
114    #[serde(deserialize_with = "deserialize_decimal")]
115    pub tick_size: Decimal,
116}
117
118/// Wrapper for the account summaries response.
119///
120/// The API returns an object with a `summaries` field containing the array of account summaries,
121/// plus account-level metadata.
122#[derive(Debug, Clone, Serialize, Deserialize)]
123pub struct DeribitAccountSummariesResponse {
124    /// Array of per-currency account summaries
125    pub summaries: Vec<DeribitAccountSummary>,
126    /// Account ID
127    #[serde(default)]
128    pub id: Option<i64>,
129    /// Account email
130    #[serde(default)]
131    pub email: Option<String>,
132    /// System name
133    #[serde(default)]
134    pub system_name: Option<String>,
135    /// Account username
136    #[serde(default)]
137    pub username: Option<String>,
138    /// Account type (e.g., "main", "subaccount")
139    #[serde(rename = "type", default)]
140    pub account_type: Option<String>,
141    /// Account creation timestamp (milliseconds since UNIX epoch)
142    #[serde(default)]
143    pub creation_timestamp: Option<i64>,
144    /// Referrer ID (affiliation program)
145    #[serde(default)]
146    pub referrer_id: Option<String>,
147    /// Whether login is enabled for this account
148    #[serde(default)]
149    pub login_enabled: Option<bool>,
150    /// Whether security keys are enabled
151    #[serde(default)]
152    pub security_keys_enabled: Option<bool>,
153    /// Whether MMP (Market Maker Protection) is enabled
154    #[serde(default)]
155    pub mmp_enabled: Option<bool>,
156    /// Whether inter-user transfers are enabled
157    #[serde(default)]
158    pub interuser_transfers_enabled: Option<bool>,
159    /// Self-trading reject mode
160    #[serde(default)]
161    pub self_trading_reject_mode: Option<String>,
162    /// Whether self-trading is extended to subaccounts
163    #[serde(default)]
164    pub self_trading_extended_to_subaccounts: Option<bool>,
165    /// Block RFQ self match prevention
166    #[serde(default)]
167    pub block_rfq_self_match_prevention: Option<bool>,
168}
169
170/// Account summary for a single currency.
171///
172/// Contains balance, equity, margin information, and profit/loss data.
173#[derive(Debug, Clone, Serialize, Deserialize)]
174pub struct DeribitAccountSummary {
175    /// Currency code (e.g., "BTC", "ETH")
176    pub currency: Ustr,
177    /// Account equity (balance + unrealized PnL)
178    #[serde(deserialize_with = "deserialize_decimal")]
179    pub equity: Decimal,
180    /// Account balance
181    #[serde(deserialize_with = "deserialize_decimal")]
182    pub balance: Decimal,
183    /// Available funds for trading
184    #[serde(deserialize_with = "deserialize_decimal")]
185    pub available_funds: Decimal,
186    /// Margin balance (for derivatives)
187    #[serde(deserialize_with = "deserialize_decimal")]
188    pub margin_balance: Decimal,
189    /// Initial margin (required for current positions)
190    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
191    pub initial_margin: Option<Decimal>,
192    /// Maintenance margin
193    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
194    pub maintenance_margin: Option<Decimal>,
195    /// Total profit/loss
196    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
197    pub total_pl: Option<Decimal>,
198    /// Session unrealized profit/loss
199    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
200    pub session_upl: Option<Decimal>,
201    /// Session realized profit/loss
202    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
203    pub session_rpl: Option<Decimal>,
204    /// Portfolio margining enabled
205    #[serde(default)]
206    pub portfolio_margining_enabled: Option<bool>,
207}
208
209/// Extended account summary with additional account details.
210///
211/// Returned by `private/get_account_summary` with `extended=true`.
212/// Contains all fields from [`DeribitAccountSummary`] plus account metadata,
213/// position Greeks, detailed margins, and fee structures.
214#[derive(Debug, Clone, Serialize, Deserialize)]
215pub struct DeribitAccountSummaryExtended {
216    /// Currency code (e.g., "BTC", "ETH")
217    pub currency: Ustr,
218    /// Account equity (balance + unrealized PnL)
219    #[serde(deserialize_with = "deserialize_decimal")]
220    pub equity: Decimal,
221    /// Account balance
222    #[serde(deserialize_with = "deserialize_decimal")]
223    pub balance: Decimal,
224    /// Available funds for trading
225    #[serde(deserialize_with = "deserialize_decimal")]
226    pub available_funds: Decimal,
227    /// Margin balance (for derivatives)
228    #[serde(deserialize_with = "deserialize_decimal")]
229    pub margin_balance: Decimal,
230    /// Initial margin (required for current positions)
231    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
232    pub initial_margin: Option<Decimal>,
233    /// Maintenance margin
234    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
235    pub maintenance_margin: Option<Decimal>,
236    /// Total profit/loss
237    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
238    pub total_pl: Option<Decimal>,
239    /// Session unrealized profit/loss
240    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
241    pub session_upl: Option<Decimal>,
242    /// Session realized profit/loss
243    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
244    pub session_rpl: Option<Decimal>,
245    /// Portfolio margining enabled
246    #[serde(default)]
247    pub portfolio_margining_enabled: Option<bool>,
248    // Extended fields below
249    /// Account ID
250    #[serde(default)]
251    pub id: Option<i64>,
252    /// Account email
253    #[serde(default)]
254    pub email: Option<String>,
255    /// Account username
256    #[serde(default)]
257    pub username: Option<String>,
258    /// System name
259    #[serde(default)]
260    pub system_name: Option<String>,
261    /// Account type (e.g., "main", "subaccount")
262    #[serde(rename = "type", default)]
263    pub account_type: Option<String>,
264    /// Futures session unrealized P&L
265    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
266    pub futures_session_upl: Option<Decimal>,
267    /// Futures session realized P&L
268    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
269    pub futures_session_rpl: Option<Decimal>,
270    /// Options session unrealized P&L
271    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
272    pub options_session_upl: Option<Decimal>,
273    /// Options session realized P&L
274    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
275    pub options_session_rpl: Option<Decimal>,
276    /// Futures profit/loss
277    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
278    pub futures_pl: Option<Decimal>,
279    /// Options profit/loss
280    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
281    pub options_pl: Option<Decimal>,
282    /// Options delta
283    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
284    pub options_delta: Option<Decimal>,
285    /// Options gamma
286    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
287    pub options_gamma: Option<Decimal>,
288    /// Options vega
289    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
290    pub options_vega: Option<Decimal>,
291    /// Options theta
292    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
293    pub options_theta: Option<Decimal>,
294    /// Options value
295    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
296    pub options_value: Option<Decimal>,
297    /// Total delta across all positions
298    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
299    pub delta_total: Option<Decimal>,
300    /// Projected delta total
301    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
302    pub projected_delta_total: Option<Decimal>,
303    /// Projected initial margin
304    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
305    pub projected_initial_margin: Option<Decimal>,
306    /// Projected maintenance margin
307    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
308    pub projected_maintenance_margin: Option<Decimal>,
309    /// Estimated liquidation ratio
310    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
311    pub estimated_liquidation_ratio: Option<Decimal>,
312    /// Available withdrawal funds
313    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
314    pub available_withdrawal_funds: Option<Decimal>,
315    /// Spot reserve
316    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
317    pub spot_reserve: Option<Decimal>,
318    /// Fee balance
319    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
320    pub fee_balance: Option<Decimal>,
321    /// Margin model (e.g., "segregated_sm", "cross_pm")
322    #[serde(default)]
323    pub margin_model: Option<String>,
324    /// Cross collateral enabled
325    #[serde(default)]
326    pub cross_collateral_enabled: Option<bool>,
327    /// Account creation timestamp (milliseconds since UNIX epoch)
328    #[serde(default)]
329    pub creation_timestamp: Option<i64>,
330    /// Whether login is enabled for this account
331    #[serde(default)]
332    pub login_enabled: Option<bool>,
333    /// Whether security keys are enabled
334    #[serde(default)]
335    pub security_keys_enabled: Option<bool>,
336    /// Whether MMP (Market Maker Protection) is enabled
337    #[serde(default)]
338    pub mmp_enabled: Option<bool>,
339    /// Whether inter-user transfers are enabled
340    #[serde(default)]
341    pub interuser_transfers_enabled: Option<bool>,
342    /// Self-trading reject mode
343    #[serde(default)]
344    pub self_trading_reject_mode: Option<String>,
345    /// Whether self-trading is extended to subaccounts
346    #[serde(default)]
347    pub self_trading_extended_to_subaccounts: Option<bool>,
348    /// Referrer ID (affiliation program)
349    #[serde(default)]
350    pub referrer_id: Option<String>,
351    /// Block RFQ self match prevention
352    #[serde(default)]
353    pub block_rfq_self_match_prevention: Option<bool>,
354}
355
356/// Deribit public trade data from the market data API.
357///
358/// Represents a single trade returned by `/public/get_last_trades_by_instrument_and_time`
359/// and other trade-related endpoints.
360#[derive(Clone, Debug, Serialize, Deserialize)]
361pub struct DeribitPublicTrade {
362    /// Trade amount. For perpetual and inverse futures the amount is in USD units.
363    /// For options and linear futures it is the underlying base currency coin.
364    #[serde(deserialize_with = "deserialize_decimal")]
365    pub amount: Decimal,
366    /// Trade size in contract units (optional, may be absent in historical trades).
367    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
368    pub contracts: Option<Decimal>,
369    /// Direction of the trade: "buy" or "sell"
370    pub direction: String,
371    /// Index Price at the moment of trade (can be empty for some trade types).
372    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
373    pub index_price: Option<Decimal>,
374    /// Unique instrument identifier.
375    pub instrument_name: String,
376    /// Option implied volatility for the price (Option only).
377    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
378    pub iv: Option<Decimal>,
379    /// Optional field (only for trades caused by liquidation).
380    #[serde(default)]
381    pub liquidation: Option<String>,
382    /// Mark Price at the moment of trade (can be empty for some trade types).
383    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
384    pub mark_price: Option<Decimal>,
385    /// Price in base currency.
386    #[serde(deserialize_with = "deserialize_decimal")]
387    pub price: Decimal,
388    /// Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).
389    pub tick_direction: i32,
390    /// The timestamp of the trade (milliseconds since the UNIX epoch).
391    pub timestamp: i64,
392    /// Unique (per currency) trade identifier.
393    pub trade_id: String,
394    /// The sequence number of the trade within instrument.
395    pub trade_seq: i64,
396    /// Block trade id - when trade was part of a block trade.
397    #[serde(default)]
398    pub block_trade_id: Option<String>,
399    /// Block trade leg count - when trade was part of a block trade.
400    #[serde(default)]
401    pub block_trade_leg_count: Option<i32>,
402    /// ID of the Block RFQ - when trade was part of the Block RFQ.
403    #[serde(default)]
404    pub block_rfq_id: Option<i64>,
405    /// Optional field containing combo instrument name if the trade is a combo trade.
406    #[serde(default)]
407    pub combo_id: Option<String>,
408    /// Optional field containing combo trade identifier if the trade is a combo trade.
409    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
410    pub combo_trade_id: Option<Decimal>,
411}
412
413/// Response wrapper for trades endpoints.
414///
415/// Contains the trades array and pagination information.
416#[derive(Clone, Debug, Serialize, Deserialize)]
417pub struct DeribitTradesResponse {
418    /// Whether there are more trades available.
419    pub has_more: bool,
420    /// Array of trade objects.
421    pub trades: Vec<DeribitPublicTrade>,
422}
423
424/// Response from `public/get_tradingview_chart_data` endpoint.
425///
426/// Contains OHLCV data in array format where each array element corresponds
427/// to a single candle at the index in the `ticks` array.
428#[derive(Clone, Debug, Serialize, Deserialize)]
429pub struct DeribitTradingViewChartData {
430    /// List of prices at close (one per candle)
431    pub close: Vec<f64>,
432    /// List of cost bars (volume in quote currency, one per candle)
433    #[serde(default)]
434    pub cost: Vec<f64>,
435    /// List of highest price levels (one per candle)
436    pub high: Vec<f64>,
437    /// List of lowest price levels (one per candle)
438    pub low: Vec<f64>,
439    /// List of prices at open (one per candle)
440    pub open: Vec<f64>,
441    /// Status of the query: "ok" or "no_data"
442    pub status: String,
443    /// Values of the time axis given in milliseconds since UNIX epoch
444    pub ticks: Vec<i64>,
445    /// List of volume bars (in base currency, one per candle)
446    pub volume: Vec<f64>,
447}
448
449/// Response from `public/get_order_book` endpoint.
450///
451/// Contains the current order book state with bids, asks, and market data.
452#[derive(Clone, Debug, Serialize, Deserialize)]
453pub struct DeribitOrderBook {
454    /// The timestamp of the order book (milliseconds since UNIX epoch)
455    pub timestamp: i64,
456    /// Unique instrument identifier
457    pub instrument_name: String,
458    /// List of bids as [price, amount] pairs (kept as f64 for performance)
459    pub bids: Vec<[f64; 2]>,
460    /// List of asks as [price, amount] pairs (kept as f64 for performance)
461    pub asks: Vec<[f64; 2]>,
462    /// The state of the order book: "open" or "closed"
463    pub state: String,
464    /// The current best bid price (null if there aren't any bids)
465    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
466    pub best_bid_price: Option<Decimal>,
467    /// The current best ask price (null if there aren't any asks)
468    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
469    pub best_ask_price: Option<Decimal>,
470    /// The order size of all best bids
471    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
472    pub best_bid_amount: Option<Decimal>,
473    /// The order size of all best asks
474    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
475    pub best_ask_amount: Option<Decimal>,
476    /// The mark price for the instrument
477    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
478    pub mark_price: Option<Decimal>,
479    /// The price for the last trade
480    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
481    pub last_price: Option<Decimal>,
482    /// Current index price
483    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
484    pub index_price: Option<Decimal>,
485    /// The total amount of outstanding contracts
486    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
487    pub open_interest: Option<Decimal>,
488    /// The maximum price for the future
489    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
490    pub max_price: Option<Decimal>,
491    /// The minimum price for the future
492    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
493    pub min_price: Option<Decimal>,
494    /// Current funding (perpetual only)
495    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
496    pub current_funding: Option<Decimal>,
497    /// Funding 8h (perpetual only)
498    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
499    pub funding_8h: Option<Decimal>,
500    /// The settlement price for the instrument (when state = open)
501    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
502    pub settlement_price: Option<Decimal>,
503    /// The settlement/delivery price for the instrument (when state = closed)
504    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
505    pub delivery_price: Option<Decimal>,
506    /// (Only for option) implied volatility for best bid
507    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
508    pub bid_iv: Option<Decimal>,
509    /// (Only for option) implied volatility for best ask
510    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
511    pub ask_iv: Option<Decimal>,
512    /// (Only for option) implied volatility for mark price
513    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
514    pub mark_iv: Option<Decimal>,
515    /// Underlying price for implied volatility calculations (options only)
516    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
517    pub underlying_price: Option<Decimal>,
518    /// Name of the underlying future, or index_price (options only)
519    #[serde(default)]
520    pub underlying_index: Option<serde_json::Value>,
521    /// Interest rate used in implied volatility calculations (options only)
522    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
523    pub interest_rate: Option<Decimal>,
524}
525
526/// Book summary data from `/public/get_book_summary_by_currency` endpoint.
527///
528/// Each entry represents a single instrument's book summary including the
529/// forward/underlying price used for ATM determination.
530#[derive(Clone, Debug, Serialize, Deserialize)]
531pub struct DeribitBookSummary {
532    /// Unique instrument identifier (e.g. "BTC-28MAR25-90000-C")
533    pub instrument_name: String,
534    /// The forward/underlying price for implied volatility calculations
535    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
536    pub underlying_price: Option<Decimal>,
537    /// Name of the underlying future or index (e.g. "BTC-28MAR25" or "SYN.BTC-28MAR25")
538    #[serde(default)]
539    pub underlying_index: Option<String>,
540    /// Mark price for the instrument
541    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
542    pub mark_price: Option<Decimal>,
543    /// The time when the instrument was created (milliseconds since UNIX epoch)
544    pub creation_timestamp: i64,
545}
546
547/// Ticker data from `/public/ticker` endpoint.
548///
549/// Only the fields needed for forward price extraction are included;
550/// serde will ignore the many additional fields returned by the API.
551#[derive(Clone, Debug, Serialize, Deserialize)]
552pub struct DeribitTicker {
553    /// Unique instrument identifier (e.g., "BTC-28FEB26-65000-C")
554    pub instrument_name: String,
555    /// Underlying price for implied volatility calculations (options only)
556    #[serde(default, deserialize_with = "deserialize_optional_decimal")]
557    pub underlying_price: Option<Decimal>,
558    /// Name of the underlying future or index (e.g., "BTC-28MAR25" or "SYN.BTC-28MAR25")
559    #[serde(default)]
560    pub underlying_index: Option<String>,
561}
562
563/// Position data from `/private/get_positions` endpoint.
564///
565/// Contains information about a single position in a specific instrument.
566#[derive(Debug, Clone, Serialize, Deserialize)]
567pub struct DeribitPosition {
568    /// Unique instrument identifier
569    pub instrument_name: Ustr,
570    /// Position direction: "buy" (long), "sell" (short), or "zero" (flat)
571    pub direction: String,
572    /// Position size in contracts (positive = long, negative = short)
573    #[serde(
574        serialize_with = "nautilus_core::serialization::serialize_decimal",
575        deserialize_with = "nautilus_core::serialization::deserialize_decimal"
576    )]
577    pub size: Decimal,
578    /// Average entry price
579    #[serde(
580        serialize_with = "nautilus_core::serialization::serialize_decimal",
581        deserialize_with = "nautilus_core::serialization::deserialize_decimal"
582    )]
583    pub average_price: Decimal,
584    /// Current mark price
585    #[serde(
586        serialize_with = "nautilus_core::serialization::serialize_decimal",
587        deserialize_with = "nautilus_core::serialization::deserialize_decimal"
588    )]
589    pub mark_price: Decimal,
590    /// Current index price
591    #[serde(
592        default,
593        serialize_with = "nautilus_core::serialization::serialize_optional_decimal",
594        deserialize_with = "nautilus_core::serialization::deserialize_optional_decimal"
595    )]
596    pub index_price: Option<Decimal>,
597    /// Maintenance margin
598    #[serde(
599        serialize_with = "nautilus_core::serialization::serialize_decimal",
600        deserialize_with = "nautilus_core::serialization::deserialize_decimal"
601    )]
602    pub maintenance_margin: Decimal,
603    /// Initial margin
604    #[serde(
605        serialize_with = "nautilus_core::serialization::serialize_decimal",
606        deserialize_with = "nautilus_core::serialization::deserialize_decimal"
607    )]
608    pub initial_margin: Decimal,
609    /// Leverage used for the position
610    #[serde(default)]
611    pub leverage: Option<i64>,
612    /// Current unrealized profit/loss
613    #[serde(
614        serialize_with = "nautilus_core::serialization::serialize_decimal",
615        deserialize_with = "nautilus_core::serialization::deserialize_decimal"
616    )]
617    pub floating_profit_loss: Decimal,
618    /// Realized profit/loss for this position
619    #[serde(
620        serialize_with = "nautilus_core::serialization::serialize_decimal",
621        deserialize_with = "nautilus_core::serialization::deserialize_decimal"
622    )]
623    pub realized_profit_loss: Decimal,
624    /// Total profit/loss (floating + realized)
625    #[serde(
626        serialize_with = "nautilus_core::serialization::serialize_decimal",
627        deserialize_with = "nautilus_core::serialization::deserialize_decimal"
628    )]
629    pub total_profit_loss: Decimal,
630    /// Product type: future, option, spot, etc.
631    pub kind: DeribitProductType,
632    /// Position size in currency units (for currency-quoted positions)
633    #[serde(
634        default,
635        serialize_with = "nautilus_core::serialization::serialize_optional_decimal",
636        deserialize_with = "nautilus_core::serialization::deserialize_optional_decimal"
637    )]
638    pub size_currency: Option<Decimal>,
639    /// Estimated liquidation price
640    #[serde(
641        default,
642        serialize_with = "nautilus_core::serialization::serialize_optional_decimal",
643        deserialize_with = "nautilus_core::serialization::deserialize_optional_decimal"
644    )]
645    pub estimated_liquidation_price: Option<Decimal>,
646    /// Position delta (for options)
647    #[serde(
648        default,
649        serialize_with = "nautilus_core::serialization::serialize_optional_decimal",
650        deserialize_with = "nautilus_core::serialization::deserialize_optional_decimal"
651    )]
652    pub delta: Option<Decimal>,
653    /// Position gamma (for options)
654    #[serde(
655        default,
656        serialize_with = "nautilus_core::serialization::serialize_optional_decimal",
657        deserialize_with = "nautilus_core::serialization::deserialize_optional_decimal"
658    )]
659    pub gamma: Option<Decimal>,
660    /// Position vega (for options)
661    #[serde(
662        default,
663        serialize_with = "nautilus_core::serialization::serialize_optional_decimal",
664        deserialize_with = "nautilus_core::serialization::deserialize_optional_decimal"
665    )]
666    pub vega: Option<Decimal>,
667    /// Position theta (for options)
668    #[serde(
669        default,
670        serialize_with = "nautilus_core::serialization::serialize_optional_decimal",
671        deserialize_with = "nautilus_core::serialization::deserialize_optional_decimal"
672    )]
673    pub theta: Option<Decimal>,
674    /// Settlement price (if settled)
675    #[serde(
676        default,
677        serialize_with = "nautilus_core::serialization::serialize_optional_decimal",
678        deserialize_with = "nautilus_core::serialization::deserialize_optional_decimal"
679    )]
680    pub settlement_price: Option<Decimal>,
681    /// Open orders margin for this position
682    #[serde(
683        default,
684        serialize_with = "nautilus_core::serialization::serialize_optional_decimal",
685        deserialize_with = "nautilus_core::serialization::deserialize_optional_decimal"
686    )]
687    pub open_orders_margin: Option<Decimal>,
688    /// Average price in USD (for currency-margined contracts)
689    #[serde(
690        default,
691        serialize_with = "nautilus_core::serialization::serialize_optional_decimal",
692        deserialize_with = "nautilus_core::serialization::deserialize_optional_decimal"
693    )]
694    pub average_price_usd: Option<Decimal>,
695    /// Realized profit loss (session)
696    #[serde(
697        default,
698        serialize_with = "nautilus_core::serialization::serialize_optional_decimal",
699        deserialize_with = "nautilus_core::serialization::deserialize_optional_decimal"
700    )]
701    pub realized_profit_loss_session: Option<Decimal>,
702    /// Floating profit loss in USD
703    #[serde(
704        default,
705        serialize_with = "nautilus_core::serialization::serialize_optional_decimal",
706        deserialize_with = "nautilus_core::serialization::deserialize_optional_decimal"
707    )]
708    pub floating_profit_loss_usd: Option<Decimal>,
709}
710
711/// Response wrapper for user trades endpoints.
712///
713/// Contains the trades array and pagination information.
714/// Used by `/private/get_user_trades_by_*` endpoints.
715#[derive(Clone, Debug, Serialize, Deserialize)]
716pub struct DeribitUserTradesResponse {
717    /// Whether there are more trades available.
718    pub has_more: bool,
719    /// Array of user trade objects.
720    pub trades: Vec<crate::websocket::messages::DeribitUserTradeMsg>,
721}
722
723#[cfg(test)]
724mod tests {
725    use rstest::rstest;
726    use rust_decimal_macros::dec;
727
728    use super::*;
729
730    #[rstest]
731    fn test_deserialize_public_trade_with_empty_mark_and_index_price() {
732        let json = r#"{
733            "amount": 1.0,
734            "direction": "sell",
735            "index_price": "",
736            "instrument_name": "ETH-PERPETUAL",
737            "mark_price": "",
738            "price": 2968.3,
739            "tick_direction": 0,
740            "timestamp": 1766332040636,
741            "trade_id": "ETH-123",
742            "trade_seq": 1
743        }"#;
744
745        let trade: DeribitPublicTrade = serde_json::from_str(json).unwrap();
746        assert_eq!(trade.index_price, None);
747        assert_eq!(trade.mark_price, None);
748        assert_eq!(trade.price, dec!(2968.3));
749    }
750
751    #[rstest]
752    fn test_deserialize_public_trade_with_missing_mark_and_index_price() {
753        let json = r#"{
754            "amount": 1.0,
755            "direction": "sell",
756            "instrument_name": "ETH-PERPETUAL",
757            "price": 2968.3,
758            "tick_direction": 0,
759            "timestamp": 1766332040636,
760            "trade_id": "ETH-123",
761            "trade_seq": 1
762        }"#;
763
764        let trade: DeribitPublicTrade = serde_json::from_str(json).unwrap();
765        assert_eq!(trade.index_price, None);
766        assert_eq!(trade.mark_price, None);
767    }
768
769    #[rstest]
770    fn test_deserialize_public_trade_with_present_mark_and_index_price() {
771        let json = r#"{
772            "amount": 1.0,
773            "direction": "sell",
774            "index_price": 2967.73,
775            "instrument_name": "ETH-PERPETUAL",
776            "mark_price": 2968.01,
777            "price": 2968.3,
778            "tick_direction": 0,
779            "timestamp": 1766332040636,
780            "trade_id": "ETH-123",
781            "trade_seq": 1
782        }"#;
783
784        let trade: DeribitPublicTrade = serde_json::from_str(json).unwrap();
785        assert_eq!(trade.index_price, Some(dec!(2967.73)));
786        assert_eq!(trade.mark_price, Some(dec!(2968.01)));
787    }
788}
nautilus_deribit/http/models.rs

nautilus_deribit/http/
models.rs
