nautilus_binance/common/
models.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2025 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//! Shared data transfer objects used across Binance HTTP and WebSocket payloads.
17
18use serde::{Deserialize, Serialize};
19
20use crate::common::enums::BinanceFilterType;
21
22/// Binance API error response structure.
23///
24/// Binance returns this format for error responses:
25/// ```json
26/// {"code": -1000, "msg": "An unknown error occurred"}
27/// ```
28#[derive(Clone, Debug, Deserialize)]
29pub struct BinanceErrorResponse {
30    /// Binance error code (negative number indicates error).
31    pub code: i64,
32    /// Error message describing the issue.
33    pub msg: String,
34}
35
36/// Price filter for spot instruments.
37///
38/// # References
39/// - <https://developers.binance.com/docs/binance-spot-api-docs/filters#price_filter>
40#[derive(Clone, Debug, Serialize, Deserialize)]
41#[serde(rename_all = "camelCase")]
42pub struct SpotPriceFilter {
43    /// Filter type identifier.
44    pub filter_type: BinanceFilterType,
45    /// Minimum allowed price.
46    pub min_price: String,
47    /// Maximum allowed price.
48    pub max_price: String,
49    /// Tick size for price increments.
50    pub tick_size: String,
51}
52
53/// Lot size filter for spot instruments.
54///
55/// # References
56/// - <https://developers.binance.com/docs/binance-spot-api-docs/filters#lot_size>
57#[derive(Clone, Debug, Serialize, Deserialize)]
58#[serde(rename_all = "camelCase")]
59pub struct SpotLotSizeFilter {
60    /// Filter type identifier.
61    pub filter_type: BinanceFilterType,
62    /// Minimum order quantity.
63    pub min_qty: String,
64    /// Maximum order quantity.
65    pub max_qty: String,
66    /// Quantity increment step.
67    pub step_size: String,
68}
69
70/// Market lot size filter for spot instruments.
71///
72/// # References
73/// - <https://developers.binance.com/docs/binance-spot-api-docs/filters#market_lot_size>
74#[derive(Clone, Debug, Serialize, Deserialize)]
75#[serde(rename_all = "camelCase")]
76pub struct SpotMarketLotSizeFilter {
77    /// Filter type identifier.
78    pub filter_type: BinanceFilterType,
79    /// Minimum order quantity.
80    pub min_qty: String,
81    /// Maximum order quantity.
82    pub max_qty: String,
83    /// Quantity increment step.
84    pub step_size: String,
85}
86
87/// Notional filter for spot instruments.
88///
89/// # References
90/// - <https://developers.binance.com/docs/binance-spot-api-docs/filters#notional>
91#[derive(Clone, Debug, Serialize, Deserialize)]
92#[serde(rename_all = "camelCase")]
93pub struct SpotNotionalFilter {
94    /// Filter type identifier.
95    pub filter_type: BinanceFilterType,
96    /// Minimum notional value.
97    pub min_notional: String,
98    /// Apply minimum to market orders.
99    #[serde(default)]
100    pub apply_min_to_market: Option<bool>,
101    /// Maximum notional value.
102    #[serde(default)]
103    pub max_notional: Option<String>,
104    /// Apply maximum to market orders.
105    #[serde(default)]
106    pub apply_max_to_market: Option<bool>,
107    /// Average price in minutes.
108    #[serde(default)]
109    pub avg_price_mins: Option<i64>,
110}
111
112/// Percent price filter for spot instruments.
113///
114/// # References
115/// - <https://developers.binance.com/docs/binance-spot-api-docs/filters#percent_price>
116#[derive(Clone, Debug, Serialize, Deserialize)]
117#[serde(rename_all = "camelCase")]
118pub struct SpotPercentPriceFilter {
119    /// Filter type identifier.
120    pub filter_type: BinanceFilterType,
121    /// Maximum price deviation above average.
122    pub multiplier_up: String,
123    /// Maximum price deviation below average.
124    pub multiplier_down: String,
125    /// Average price minutes window.
126    #[serde(default)]
127    pub avg_price_mins: Option<i64>,
128}
129
130/// Price filter for futures instruments (USD-M and COIN-M).
131///
132/// # References
133/// - <https://developers.binance.com/docs/derivatives/usds-margined-futures/market-data/rest-api/Exchange-Information>
134#[derive(Clone, Debug, Serialize, Deserialize)]
135#[serde(rename_all = "camelCase")]
136pub struct FuturesPriceFilter {
137    /// Filter type identifier.
138    pub filter_type: BinanceFilterType,
139    /// Minimum allowed price.
140    pub min_price: String,
141    /// Maximum allowed price.
142    pub max_price: String,
143    /// Tick size for price increments.
144    pub tick_size: String,
145}
146
147/// Lot size filter for futures instruments.
148///
149/// # References
150/// - <https://developers.binance.com/docs/derivatives/usds-margined-futures/market-data/rest-api/Exchange-Information>
151#[derive(Clone, Debug, Serialize, Deserialize)]
152#[serde(rename_all = "camelCase")]
153pub struct FuturesLotSizeFilter {
154    /// Filter type identifier.
155    pub filter_type: BinanceFilterType,
156    /// Maximum order quantity.
157    pub max_qty: String,
158    /// Minimum order quantity.
159    pub min_qty: String,
160    /// Quantity increment step.
161    pub step_size: String,
162}
163
164/// Market lot size filter for futures instruments.
165///
166/// # References
167/// - <https://developers.binance.com/docs/derivatives/usds-margined-futures/market-data/rest-api/Exchange-Information>
168#[derive(Clone, Debug, Serialize, Deserialize)]
169#[serde(rename_all = "camelCase")]
170pub struct FuturesMarketLotSizeFilter {
171    /// Filter type identifier.
172    pub filter_type: BinanceFilterType,
173    /// Maximum order quantity.
174    pub max_qty: String,
175    /// Minimum order quantity.
176    pub min_qty: String,
177    /// Quantity increment step.
178    pub step_size: String,
179}
180
181/// Min notional filter for futures instruments.
182///
183/// # References
184/// - <https://developers.binance.com/docs/derivatives/usds-margined-futures/market-data/rest-api/Exchange-Information>
185#[derive(Clone, Debug, Serialize, Deserialize)]
186#[serde(rename_all = "camelCase")]
187pub struct FuturesMinNotionalFilter {
188    /// Filter type identifier.
189    pub filter_type: BinanceFilterType,
190    /// Minimum notional value.
191    pub notional: String,
192}
193
194/// Percent price filter for futures instruments.
195///
196/// # References
197/// - <https://developers.binance.com/docs/derivatives/usds-margined-futures/market-data/rest-api/Exchange-Information>
198#[derive(Clone, Debug, Serialize, Deserialize)]
199#[serde(rename_all = "camelCase")]
200pub struct FuturesPercentPriceFilter {
201    /// Filter type identifier.
202    pub filter_type: BinanceFilterType,
203    /// Maximum price deviation above mark price.
204    pub multiplier_up: String,
205    /// Maximum price deviation below mark price.
206    pub multiplier_down: String,
207    /// Multiplier decimal places.
208    #[serde(default)]
209    pub multiplier_decimal: Option<String>,
210}
211
212/// Max number of orders filter.
213#[derive(Clone, Debug, Serialize, Deserialize)]
214#[serde(rename_all = "camelCase")]
215pub struct MaxNumOrdersFilter {
216    /// Filter type identifier.
217    pub filter_type: BinanceFilterType,
218    /// Maximum number of open orders.
219    pub limit: i64,
220}
221
222/// Max number of algo orders filter.
223#[derive(Clone, Debug, Serialize, Deserialize)]
224#[serde(rename_all = "camelCase")]
225pub struct MaxNumAlgoOrdersFilter {
226    /// Filter type identifier.
227    pub filter_type: BinanceFilterType,
228    /// Maximum number of algo orders.
229    pub limit: i64,
230}
231
232/// Rate limit definition from exchange info.
233#[derive(Clone, Debug, Serialize, Deserialize)]
234#[serde(rename_all = "camelCase")]
235pub struct BinanceRateLimit {
236    /// Type of rate limit (REQUEST_WEIGHT, ORDERS, RAW_REQUESTS).
237    pub rate_limit_type: String,
238    /// Time interval (SECOND, MINUTE, DAY).
239    pub interval: String,
240    /// Interval number.
241    pub interval_num: i64,
242    /// Request limit.
243    pub limit: i64,
244}
nautilus_binance/common/models.rs

nautilus_binance/common/
models.rs
