nautilus_deribit/http/
query.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 query parameter builders.
17
18use derive_builder::Builder;
19use serde::{Deserialize, Serialize};
20
21use super::models::{DeribitCurrency, DeribitProductType};
22
23/// Query parameters for `/public/get_instruments` endpoint.
24#[derive(Clone, Debug, Deserialize, Serialize, Builder)]
25#[builder(setter(into, strip_option))]
26pub struct GetInstrumentsParams {
27    /// Currency filter
28    pub currency: DeribitCurrency,
29    /// Optional product type filter
30    #[serde(skip_serializing_if = "Option::is_none")]
31    #[builder(default)]
32    pub kind: Option<DeribitProductType>,
33    /// Whether to include expired instruments
34    #[serde(skip_serializing_if = "Option::is_none")]
35    #[builder(default)]
36    pub expired: Option<bool>,
37}
38
39impl GetInstrumentsParams {
40    /// Creates a new builder for [`GetInstrumentsParams`].
41    #[must_use]
42    pub fn builder() -> GetInstrumentsParamsBuilder {
43        GetInstrumentsParamsBuilder::default()
44    }
45
46    /// Creates parameters for a specific currency.
47    #[must_use]
48    pub fn new(currency: DeribitCurrency) -> Self {
49        Self {
50            currency,
51            kind: None,
52            expired: None,
53        }
54    }
55
56    /// Creates parameters for a specific currency and product type.
57    #[must_use]
58    pub fn with_kind(currency: DeribitCurrency, kind: DeribitProductType) -> Self {
59        Self {
60            currency,
61            kind: Some(kind),
62            expired: None,
63        }
64    }
65}
66
67/// Query parameters for `/public/get_instrument` endpoint.
68#[derive(Clone, Debug, Deserialize, Serialize, Builder)]
69pub struct GetInstrumentParams {
70    /// Instrument name (e.g., "BTC-PERPETUAL", "ETH-25MAR23-2000-C")
71    pub instrument_name: String,
72}
73
74/// Query parameters for `/private/get_account_summaries` endpoint.
75#[derive(Clone, Debug, Default, Deserialize, Serialize)]
76pub struct GetAccountSummariesParams {
77    /// The user id for the subaccount.
78    #[serde(skip_serializing_if = "Option::is_none")]
79    pub subaccount_id: Option<String>,
80    /// Include extended fields
81    #[serde(skip_serializing_if = "Option::is_none")]
82    pub extended: Option<bool>,
83}
84
85impl GetAccountSummariesParams {
86    /// Creates a new instance with both subaccount ID and extended flag.
87    #[must_use]
88    pub fn new(subaccount_id: String, extended: bool) -> Self {
89        Self {
90            subaccount_id: Some(subaccount_id),
91            extended: Some(extended),
92        }
93    }
94}
95
96/// Query parameters for `/public/get_last_trades_by_instrument_and_time` endpoint.
97#[derive(Clone, Debug, Deserialize, Serialize, Builder)]
98#[builder(setter(into, strip_option))]
99pub struct GetLastTradesByInstrumentAndTimeParams {
100    /// Instrument name (e.g., "BTC-PERPETUAL")
101    pub instrument_name: String,
102    /// The earliest timestamp to return result from (milliseconds since the UNIX epoch)
103    pub start_timestamp: i64,
104    /// The most recent timestamp to return result from (milliseconds since the UNIX epoch)
105    pub end_timestamp: i64,
106    /// Number of requested items, default - 10, maximum - 1000
107    #[serde(skip_serializing_if = "Option::is_none")]
108    #[builder(default)]
109    pub count: Option<u32>,
110    /// Direction of results sorting: "asc", "desc", or "default"
111    #[serde(skip_serializing_if = "Option::is_none")]
112    #[builder(default)]
113    pub sorting: Option<String>,
114}
115
116impl GetLastTradesByInstrumentAndTimeParams {
117    /// Creates a new instance with the required parameters.
118    #[must_use]
119    pub fn new(
120        instrument_name: impl Into<String>,
121        start_timestamp: i64,
122        end_timestamp: i64,
123        count: Option<u32>,
124        sorting: Option<String>,
125    ) -> Self {
126        Self {
127            instrument_name: instrument_name.into(),
128            start_timestamp,
129            end_timestamp,
130            count,
131            sorting,
132        }
133    }
134}
135
136/// Query parameters for `/public/get_tradingview_chart_data` endpoint.
137#[derive(Clone, Debug, Deserialize, Serialize)]
138pub struct GetTradingViewChartDataParams {
139    /// Instrument name (e.g., "BTC-PERPETUAL")
140    pub instrument_name: String,
141    /// The earliest timestamp to return result from (milliseconds since UNIX epoch)
142    pub start_timestamp: i64,
143    /// The most recent timestamp to return result from (milliseconds since UNIX epoch)
144    pub end_timestamp: i64,
145    /// Chart bars resolution given in full minutes or keyword "1D"
146    /// Supported resolutions: 1, 3, 5, 10, 15, 30, 60, 120, 180, 360, 720, 1D
147    pub resolution: String,
148}
149
150impl GetTradingViewChartDataParams {
151    /// Creates new parameters for chart data request.
152    #[must_use]
153    pub fn new(
154        instrument_name: String,
155        start_timestamp: i64,
156        end_timestamp: i64,
157        resolution: String,
158    ) -> Self {
159        Self {
160            instrument_name,
161            start_timestamp,
162            end_timestamp,
163            resolution,
164        }
165    }
166}
167
168/// Query parameters for `/public/get_order_book` endpoint.
169#[derive(Clone, Debug, Deserialize, Serialize, Builder)]
170#[builder(setter(into, strip_option))]
171pub struct GetOrderBookParams {
172    /// Instrument name (e.g., "BTC-PERPETUAL")
173    pub instrument_name: String,
174    /// The number of entries to return for bids and asks.
175    /// Valid values: 1, 5, 10, 20, 50, 100, 1000, 10000
176    /// Maximum: 10000
177    #[serde(skip_serializing_if = "Option::is_none")]
178    #[builder(default)]
179    pub depth: Option<u32>,
180}
181
182impl GetOrderBookParams {
183    /// Creates parameters with required fields.
184    #[must_use]
185    pub fn new(instrument_name: String, depth: Option<u32>) -> Self {
186        Self {
187            instrument_name,
188            depth,
189        }
190    }
191}
192
193/// Query parameters for `/private/get_order_state` endpoint.
194/// Retrieves a single order by its ID.
195#[derive(Clone, Debug, Deserialize, Serialize)]
196pub struct GetOrderStateParams {
197    /// The order ID to look up.
198    pub order_id: String,
199}
200
201impl GetOrderStateParams {
202    /// Creates parameters for a specific order ID.
203    #[must_use]
204    pub fn new(order_id: impl Into<String>) -> Self {
205        Self {
206            order_id: order_id.into(),
207        }
208    }
209}
210
211/// Query parameters for `/private/get_open_orders` endpoint.
212/// Retrieves all open orders across all currencies and instruments.
213#[derive(Clone, Debug, Default, Deserialize, Serialize)]
214pub struct GetOpenOrdersParams {}
215
216impl GetOpenOrdersParams {
217    /// Creates parameters to get all open orders.
218    #[must_use]
219    pub fn new() -> Self {
220        Self {}
221    }
222}
223
224/// Query parameters for `/private/get_open_orders_by_instrument` endpoint.
225/// Retrieves open orders for a specific instrument.
226#[derive(Clone, Debug, Deserialize, Serialize, Builder)]
227#[builder(setter(into, strip_option))]
228pub struct GetOpenOrdersByInstrumentParams {
229    /// Instrument name (e.g., "BTC-PERPETUAL")
230    pub instrument_name: String,
231    /// Order type filter: "all", "limit", "stop_all", "stop_limit", "stop_market",
232    /// "take_all", "take_limit", "take_market", "trailing_all", "trailing_stop"
233    #[serde(skip_serializing_if = "Option::is_none")]
234    #[builder(default)]
235    pub r#type: Option<String>,
236}
237
238impl GetOpenOrdersByInstrumentParams {
239    /// Creates parameters for a specific instrument.
240    #[must_use]
241    pub fn new(instrument_name: impl Into<String>) -> Self {
242        Self {
243            instrument_name: instrument_name.into(),
244            r#type: None,
245        }
246    }
247}
248
249/// Query parameters for `/private/get_order_history_by_instrument` endpoint.
250/// Retrieves historical orders for a specific instrument.
251#[derive(Clone, Debug, Deserialize, Serialize, Builder)]
252#[builder(setter(into, strip_option))]
253pub struct GetOrderHistoryByInstrumentParams {
254    /// Instrument name (e.g., "BTC-PERPETUAL")
255    pub instrument_name: String,
256    /// Number of requested items, default - 20
257    #[serde(skip_serializing_if = "Option::is_none")]
258    #[builder(default)]
259    pub count: Option<u32>,
260    /// Offset for pagination
261    #[serde(skip_serializing_if = "Option::is_none")]
262    #[builder(default)]
263    pub offset: Option<u32>,
264    /// Include orders older than 3 days
265    #[serde(skip_serializing_if = "Option::is_none")]
266    #[builder(default)]
267    pub include_old: Option<bool>,
268    /// Include unfilled orders
269    #[serde(skip_serializing_if = "Option::is_none")]
270    #[builder(default)]
271    pub include_unfilled: Option<bool>,
272}
273
274impl GetOrderHistoryByInstrumentParams {
275    /// Creates parameters for a specific instrument.
276    #[must_use]
277    pub fn new(instrument_name: impl Into<String>) -> Self {
278        Self {
279            instrument_name: instrument_name.into(),
280            count: None,
281            offset: None,
282            include_old: None,
283            include_unfilled: None,
284        }
285    }
286
287    /// Creates a new builder for [`GetOrderHistoryByInstrumentParams`].
288    #[must_use]
289    pub fn builder() -> GetOrderHistoryByInstrumentParamsBuilder {
290        GetOrderHistoryByInstrumentParamsBuilder::default()
291    }
292}
293
294/// Query parameters for `/private/get_order_history_by_currency` endpoint.
295/// Retrieves historical orders for a specific currency.
296#[derive(Clone, Debug, Deserialize, Serialize, Builder)]
297#[builder(setter(into, strip_option))]
298pub struct GetOrderHistoryByCurrencyParams {
299    /// Currency filter
300    pub currency: DeribitCurrency,
301    /// Optional product type filter
302    #[serde(skip_serializing_if = "Option::is_none")]
303    #[builder(default)]
304    pub kind: Option<DeribitProductType>,
305    /// Number of requested items, default - 20, maximum - 1000
306    #[serde(skip_serializing_if = "Option::is_none")]
307    #[builder(default)]
308    pub count: Option<u32>,
309    /// Offset for pagination
310    #[serde(skip_serializing_if = "Option::is_none")]
311    #[builder(default)]
312    pub offset: Option<u32>,
313    /// Include orders older than 3 days
314    #[serde(skip_serializing_if = "Option::is_none")]
315    #[builder(default)]
316    pub include_old: Option<bool>,
317    /// Include unfilled orders
318    #[serde(skip_serializing_if = "Option::is_none")]
319    #[builder(default)]
320    pub include_unfilled: Option<bool>,
321}
322
323impl GetOrderHistoryByCurrencyParams {
324    /// Creates parameters for a specific currency.
325    #[must_use]
326    pub fn new(currency: DeribitCurrency) -> Self {
327        Self {
328            currency,
329            kind: None,
330            count: None,
331            offset: None,
332            include_old: None,
333            include_unfilled: None,
334        }
335    }
336
337    /// Creates a new builder for [`GetOrderHistoryByCurrencyParams`].
338    #[must_use]
339    pub fn builder() -> GetOrderHistoryByCurrencyParamsBuilder {
340        GetOrderHistoryByCurrencyParamsBuilder::default()
341    }
342}
343
344/// Query parameters for `/private/get_user_trades_by_instrument_and_time` endpoint.
345/// Retrieves user trades for a specific instrument within a time range.
346#[derive(Clone, Debug, Deserialize, Serialize, Builder)]
347#[builder(setter(into, strip_option))]
348pub struct GetUserTradesByInstrumentAndTimeParams {
349    /// Instrument name (e.g., "BTC-PERPETUAL")
350    pub instrument_name: String,
351    /// Start timestamp in milliseconds since UNIX epoch
352    pub start_timestamp: i64,
353    /// End timestamp in milliseconds since UNIX epoch
354    pub end_timestamp: i64,
355    /// Number of requested items, default - 10, maximum - 1000
356    #[serde(skip_serializing_if = "Option::is_none")]
357    #[builder(default)]
358    pub count: Option<u32>,
359    /// Direction of results sorting: "asc", "desc", or "default"
360    #[serde(skip_serializing_if = "Option::is_none")]
361    #[builder(default)]
362    pub sorting: Option<String>,
363}
364
365impl GetUserTradesByInstrumentAndTimeParams {
366    /// Creates parameters with required fields.
367    #[must_use]
368    pub fn new(
369        instrument_name: impl Into<String>,
370        start_timestamp: i64,
371        end_timestamp: i64,
372    ) -> Self {
373        Self {
374            instrument_name: instrument_name.into(),
375            start_timestamp,
376            end_timestamp,
377            count: None,
378            sorting: None,
379        }
380    }
381
382    /// Creates a new builder for [`GetUserTradesByInstrumentAndTimeParams`].
383    #[must_use]
384    pub fn builder() -> GetUserTradesByInstrumentAndTimeParamsBuilder {
385        GetUserTradesByInstrumentAndTimeParamsBuilder::default()
386    }
387}
388
389/// Query parameters for `/private/get_user_trades_by_currency_and_time` endpoint.
390/// Retrieves user trades for a specific currency within a time range.
391#[derive(Clone, Debug, Deserialize, Serialize, Builder)]
392#[builder(setter(into, strip_option))]
393pub struct GetUserTradesByCurrencyAndTimeParams {
394    /// Currency filter
395    pub currency: DeribitCurrency,
396    /// Start timestamp in milliseconds since UNIX epoch
397    pub start_timestamp: i64,
398    /// End timestamp in milliseconds since UNIX epoch
399    pub end_timestamp: i64,
400    /// Optional product type filter
401    #[serde(skip_serializing_if = "Option::is_none")]
402    #[builder(default)]
403    pub kind: Option<DeribitProductType>,
404    /// Number of requested items, default - 10, maximum - 1000
405    #[serde(skip_serializing_if = "Option::is_none")]
406    #[builder(default)]
407    pub count: Option<u32>,
408    /// Direction of results sorting: "asc", "desc", or "default"
409    #[serde(skip_serializing_if = "Option::is_none")]
410    #[builder(default)]
411    pub sorting: Option<String>,
412}
413
414impl GetUserTradesByCurrencyAndTimeParams {
415    /// Creates parameters with required fields.
416    #[must_use]
417    pub fn new(currency: DeribitCurrency, start_timestamp: i64, end_timestamp: i64) -> Self {
418        Self {
419            currency,
420            start_timestamp,
421            end_timestamp,
422            kind: None,
423            count: None,
424            sorting: None,
425        }
426    }
427
428    /// Creates a new builder for [`GetUserTradesByCurrencyAndTimeParams`].
429    #[must_use]
430    pub fn builder() -> GetUserTradesByCurrencyAndTimeParamsBuilder {
431        GetUserTradesByCurrencyAndTimeParamsBuilder::default()
432    }
433}
434
435/// Query parameters for `/public/get_book_summary_by_currency` endpoint.
436#[derive(Clone, Debug, Deserialize, Serialize, Builder)]
437#[builder(setter(into, strip_option))]
438pub struct GetBookSummaryByCurrencyParams {
439    /// Currency filter (e.g., "BTC", "ETH")
440    pub currency: String,
441    /// Optional product type filter (e.g., "option", "future")
442    #[serde(skip_serializing_if = "Option::is_none")]
443    #[builder(default)]
444    pub kind: Option<String>,
445}
446
447impl GetBookSummaryByCurrencyParams {
448    /// Creates parameters for options book summaries for a given currency.
449    #[must_use]
450    pub fn options(currency: impl Into<String>) -> Self {
451        Self {
452            currency: currency.into(),
453            kind: Some("option".to_string()),
454        }
455    }
456}
457
458/// Query parameters for `/public/ticker` endpoint.
459#[derive(Clone, Debug, Deserialize, Serialize)]
460pub struct GetTickerParams {
461    /// Instrument name (e.g., "BTC-28FEB26-65000-C")
462    pub instrument_name: String,
463}
464
465/// Query parameters for `/private/get_positions` endpoint.
466/// Retrieves positions for a specific currency.
467#[derive(Clone, Debug, Deserialize, Serialize, Builder)]
468#[builder(setter(into, strip_option))]
469pub struct GetPositionsParams {
470    /// Currency filter
471    pub currency: DeribitCurrency,
472    /// Optional product type filter
473    #[serde(skip_serializing_if = "Option::is_none")]
474    #[builder(default)]
475    pub kind: Option<DeribitProductType>,
476}
477
478impl GetPositionsParams {
479    /// Creates parameters for a specific currency.
480    #[must_use]
481    pub fn new(currency: DeribitCurrency) -> Self {
482        Self {
483            currency,
484            kind: None,
485        }
486    }
487
488    /// Creates a new builder for [`GetPositionsParams`].
489    #[must_use]
490    pub fn builder() -> GetPositionsParamsBuilder {
491        GetPositionsParamsBuilder::default()
492    }
493}
nautilus_deribit/http/query.rs

nautilus_deribit/http/
query.rs
