nautilus_binance/futures/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//! Binance Futures HTTP response models.
17
18use serde::{Deserialize, Serialize};
19use serde_json::Value;
20use ustr::Ustr;
21
22use crate::common::{
23    enums::{
24        BinanceContractStatus, BinanceFuturesOrderType, BinanceIncomeType, BinanceMarginType,
25        BinanceOrderStatus, BinancePositionSide, BinancePriceMatch, BinanceSelfTradePreventionMode,
26        BinanceSide, BinanceTimeInForce, BinanceTradingStatus, BinanceWorkingType,
27    },
28    models::BinanceRateLimit,
29};
30
31/// Server time response from `GET /fapi/v1/time`.
32#[derive(Clone, Debug, Serialize, Deserialize)]
33#[serde(rename_all = "camelCase")]
34pub struct BinanceServerTime {
35    /// Server timestamp in milliseconds.
36    pub server_time: i64,
37}
38
39/// USD-M Futures exchange information response from `GET /fapi/v1/exchangeInfo`.
40#[derive(Clone, Debug, Serialize, Deserialize)]
41#[serde(rename_all = "camelCase")]
42pub struct BinanceFuturesUsdExchangeInfo {
43    /// Server timezone.
44    pub timezone: String,
45    /// Server timestamp in milliseconds.
46    pub server_time: i64,
47    /// Rate limit definitions.
48    pub rate_limits: Vec<BinanceRateLimit>,
49    /// Exchange-level filters.
50    #[serde(default)]
51    pub exchange_filters: Vec<Value>,
52    /// Asset definitions.
53    #[serde(default)]
54    pub assets: Vec<BinanceFuturesAsset>,
55    /// Trading symbols.
56    pub symbols: Vec<BinanceFuturesUsdSymbol>,
57}
58
59/// Futures asset definition.
60#[derive(Clone, Debug, Serialize, Deserialize)]
61#[serde(rename_all = "camelCase")]
62pub struct BinanceFuturesAsset {
63    /// Asset name.
64    pub asset: Ustr,
65    /// Whether margin is available.
66    pub margin_available: bool,
67    /// Auto asset exchange threshold.
68    #[serde(default)]
69    pub auto_asset_exchange: Option<String>,
70}
71
72/// USD-M Futures symbol definition.
73#[derive(Clone, Debug, Serialize, Deserialize)]
74#[serde(rename_all = "camelCase")]
75pub struct BinanceFuturesUsdSymbol {
76    /// Symbol name (e.g., "BTCUSDT").
77    pub symbol: Ustr,
78    /// Trading pair (e.g., "BTCUSDT").
79    pub pair: Ustr,
80    /// Contract type (PERPETUAL, CURRENT_QUARTER, NEXT_QUARTER).
81    pub contract_type: String,
82    /// Delivery date timestamp.
83    pub delivery_date: i64,
84    /// Onboard date timestamp.
85    pub onboard_date: i64,
86    /// Trading status.
87    pub status: BinanceTradingStatus,
88    /// Maintenance margin percent.
89    pub maint_margin_percent: String,
90    /// Required margin percent.
91    pub required_margin_percent: String,
92    /// Base asset.
93    pub base_asset: Ustr,
94    /// Quote asset.
95    pub quote_asset: Ustr,
96    /// Margin asset.
97    pub margin_asset: Ustr,
98    /// Price precision.
99    pub price_precision: i32,
100    /// Quantity precision.
101    pub quantity_precision: i32,
102    /// Base asset precision.
103    pub base_asset_precision: i32,
104    /// Quote precision.
105    pub quote_precision: i32,
106    /// Underlying type.
107    #[serde(default)]
108    pub underlying_type: Option<String>,
109    /// Underlying sub type.
110    #[serde(default)]
111    pub underlying_sub_type: Vec<String>,
112    /// Settle plan.
113    #[serde(default)]
114    pub settle_plan: Option<i64>,
115    /// Trigger protect threshold.
116    #[serde(default)]
117    pub trigger_protect: Option<String>,
118    /// Liquidation fee.
119    #[serde(default)]
120    pub liquidation_fee: Option<String>,
121    /// Market take bound.
122    #[serde(default)]
123    pub market_take_bound: Option<String>,
124    /// Allowed order types.
125    pub order_types: Vec<String>,
126    /// Time in force options.
127    pub time_in_force: Vec<String>,
128    /// Symbol filters.
129    pub filters: Vec<Value>,
130}
131
132/// COIN-M Futures exchange information response from `GET /dapi/v1/exchangeInfo`.
133#[derive(Clone, Debug, Serialize, Deserialize)]
134#[serde(rename_all = "camelCase")]
135pub struct BinanceFuturesCoinExchangeInfo {
136    /// Server timezone.
137    pub timezone: String,
138    /// Server timestamp in milliseconds.
139    pub server_time: i64,
140    /// Rate limit definitions.
141    pub rate_limits: Vec<BinanceRateLimit>,
142    /// Exchange-level filters.
143    #[serde(default)]
144    pub exchange_filters: Vec<Value>,
145    /// Trading symbols.
146    pub symbols: Vec<BinanceFuturesCoinSymbol>,
147}
148
149/// COIN-M Futures symbol definition.
150#[derive(Clone, Debug, Serialize, Deserialize)]
151#[serde(rename_all = "camelCase")]
152pub struct BinanceFuturesCoinSymbol {
153    /// Symbol name (e.g., "BTCUSD_PERP").
154    pub symbol: Ustr,
155    /// Trading pair (e.g., "BTCUSD").
156    pub pair: Ustr,
157    /// Contract type (PERPETUAL, CURRENT_QUARTER, NEXT_QUARTER).
158    pub contract_type: String,
159    /// Delivery date timestamp.
160    pub delivery_date: i64,
161    /// Onboard date timestamp.
162    pub onboard_date: i64,
163    /// Trading status.
164    #[serde(default)]
165    pub contract_status: Option<BinanceContractStatus>,
166    /// Contract size.
167    pub contract_size: i64,
168    /// Maintenance margin percent.
169    pub maint_margin_percent: String,
170    /// Required margin percent.
171    pub required_margin_percent: String,
172    /// Base asset.
173    pub base_asset: Ustr,
174    /// Quote asset.
175    pub quote_asset: Ustr,
176    /// Margin asset.
177    pub margin_asset: Ustr,
178    /// Price precision.
179    pub price_precision: i32,
180    /// Quantity precision.
181    pub quantity_precision: i32,
182    /// Base asset precision.
183    pub base_asset_precision: i32,
184    /// Quote precision.
185    pub quote_precision: i32,
186    /// Equal quantity precision.
187    #[serde(default, rename = "equalQtyPrecision")]
188    pub equal_qty_precision: Option<i32>,
189    /// Trigger protect threshold.
190    #[serde(default)]
191    pub trigger_protect: Option<String>,
192    /// Liquidation fee.
193    #[serde(default)]
194    pub liquidation_fee: Option<String>,
195    /// Market take bound.
196    #[serde(default)]
197    pub market_take_bound: Option<String>,
198    /// Allowed order types.
199    pub order_types: Vec<String>,
200    /// Time in force options.
201    pub time_in_force: Vec<String>,
202    /// Symbol filters.
203    pub filters: Vec<Value>,
204}
205
206/// 24hr ticker price change statistics for futures.
207#[derive(Clone, Debug, Serialize, Deserialize)]
208#[serde(rename_all = "camelCase")]
209pub struct BinanceFuturesTicker24hr {
210    /// Symbol name.
211    pub symbol: Ustr,
212    /// Price change in quote asset.
213    pub price_change: String,
214    /// Price change percentage.
215    pub price_change_percent: String,
216    /// Weighted average price.
217    pub weighted_avg_price: String,
218    /// Last traded price.
219    pub last_price: String,
220    /// Last traded quantity.
221    #[serde(default)]
222    pub last_qty: Option<String>,
223    /// Opening price.
224    pub open_price: String,
225    /// Highest price.
226    pub high_price: String,
227    /// Lowest price.
228    pub low_price: String,
229    /// Total traded base asset volume.
230    pub volume: String,
231    /// Total traded quote asset volume.
232    pub quote_volume: String,
233    /// Statistics open time.
234    pub open_time: i64,
235    /// Statistics close time.
236    pub close_time: i64,
237    /// First trade ID.
238    #[serde(default)]
239    pub first_id: Option<i64>,
240    /// Last trade ID.
241    #[serde(default)]
242    pub last_id: Option<i64>,
243    /// Total number of trades.
244    #[serde(default)]
245    pub count: Option<i64>,
246}
247
248/// Mark price and funding rate for futures.
249#[derive(Clone, Debug, Serialize, Deserialize)]
250#[serde(rename_all = "camelCase")]
251pub struct BinanceFuturesMarkPrice {
252    /// Symbol name.
253    pub symbol: Ustr,
254    /// Mark price.
255    pub mark_price: String,
256    /// Index price.
257    #[serde(default)]
258    pub index_price: Option<String>,
259    /// Estimated settle price (only for delivery contracts).
260    #[serde(default)]
261    pub estimated_settle_price: Option<String>,
262    /// Last funding rate.
263    #[serde(default)]
264    pub last_funding_rate: Option<String>,
265    /// Next funding time.
266    #[serde(default)]
267    pub next_funding_time: Option<i64>,
268    /// Interest rate.
269    #[serde(default)]
270    pub interest_rate: Option<String>,
271    /// Timestamp.
272    pub time: i64,
273}
274
275/// Order book depth snapshot.
276#[derive(Clone, Debug, Serialize, Deserialize)]
277#[serde(rename_all = "camelCase")]
278pub struct BinanceOrderBook {
279    /// Last update ID.
280    pub last_update_id: i64,
281    /// Bid levels as `[price, quantity]` arrays.
282    pub bids: Vec<(String, String)>,
283    /// Ask levels as `[price, quantity]` arrays.
284    pub asks: Vec<(String, String)>,
285    /// Message output time.
286    #[serde(default, rename = "E")]
287    pub event_time: Option<i64>,
288    /// Transaction time.
289    #[serde(default, rename = "T")]
290    pub transaction_time: Option<i64>,
291}
292
293/// Best bid/ask from book ticker endpoint.
294#[derive(Clone, Debug, Serialize, Deserialize)]
295#[serde(rename_all = "camelCase")]
296pub struct BinanceBookTicker {
297    /// Symbol name.
298    pub symbol: Ustr,
299    /// Best bid price.
300    pub bid_price: String,
301    /// Best bid quantity.
302    pub bid_qty: String,
303    /// Best ask price.
304    pub ask_price: String,
305    /// Best ask quantity.
306    pub ask_qty: String,
307    /// Event time.
308    #[serde(default)]
309    pub time: Option<i64>,
310}
311
312/// Price ticker.
313#[derive(Clone, Debug, Serialize, Deserialize)]
314#[serde(rename_all = "camelCase")]
315pub struct BinancePriceTicker {
316    /// Symbol name.
317    pub symbol: Ustr,
318    /// Current price.
319    pub price: String,
320    /// Event time.
321    #[serde(default)]
322    pub time: Option<i64>,
323}
324
325/// Funding rate history record.
326#[derive(Clone, Debug, Serialize, Deserialize)]
327#[serde(rename_all = "camelCase")]
328pub struct BinanceFundingRate {
329    /// Symbol name.
330    pub symbol: Ustr,
331    /// Funding rate value.
332    pub funding_rate: String,
333    /// Funding time in milliseconds.
334    pub funding_time: i64,
335    /// Mark price at the funding time.
336    #[serde(default)]
337    pub mark_price: Option<String>,
338    /// Index price at the funding time.
339    #[serde(default)]
340    pub index_price: Option<String>,
341}
342
343/// Open interest record.
344#[derive(Clone, Debug, Serialize, Deserialize)]
345#[serde(rename_all = "camelCase")]
346pub struct BinanceOpenInterest {
347    /// Symbol name.
348    pub symbol: Ustr,
349    /// Total open interest.
350    pub open_interest: String,
351    /// Timestamp in milliseconds.
352    pub time: i64,
353}
354
355/// Futures account balance entry.
356#[derive(Clone, Debug, Serialize, Deserialize)]
357#[serde(rename_all = "camelCase")]
358pub struct BinanceFuturesBalance {
359    /// Account alias (only USD-M).
360    #[serde(default)]
361    pub account_alias: Option<String>,
362    /// Asset code (e.g., "USDT").
363    pub asset: Ustr,
364    /// Total balance.
365    pub balance: String,
366    /// Cross wallet balance.
367    #[serde(default)]
368    pub cross_wallet_balance: Option<String>,
369    /// Unrealized PnL for cross positions.
370    #[serde(default)]
371    pub cross_un_pnl: Option<String>,
372    /// Available balance.
373    pub available_balance: String,
374    /// Maximum withdrawable amount.
375    #[serde(default)]
376    pub max_withdraw_amount: Option<String>,
377    /// Whether margin trading is available.
378    #[serde(default)]
379    pub margin_available: Option<bool>,
380    /// Timestamp of last update in milliseconds.
381    pub update_time: i64,
382    /// Withdrawable amount (COIN-M specific).
383    #[serde(default)]
384    pub withdraw_available: Option<String>,
385}
386
387/// Position risk record.
388#[derive(Clone, Debug, Serialize, Deserialize)]
389#[serde(rename_all = "camelCase")]
390pub struct BinancePositionRisk {
391    /// Symbol name.
392    pub symbol: Ustr,
393    /// Position quantity.
394    pub position_amt: String,
395    /// Entry price.
396    pub entry_price: String,
397    /// Mark price.
398    pub mark_price: String,
399    /// Unrealized profit and loss.
400    #[serde(default)]
401    pub un_realized_profit: Option<String>,
402    /// Liquidation price.
403    #[serde(default)]
404    pub liquidation_price: Option<String>,
405    /// Applied leverage.
406    pub leverage: String,
407    /// Max notional value.
408    #[serde(default)]
409    pub max_notional_value: Option<String>,
410    /// Margin type (CROSSED or ISOLATED).
411    #[serde(default)]
412    pub margin_type: Option<BinanceMarginType>,
413    /// Isolated margin amount.
414    #[serde(default)]
415    pub isolated_margin: Option<String>,
416    /// Auto add margin flag.
417    #[serde(default)]
418    pub is_auto_add_margin: Option<bool>,
419    /// Position side (BOTH, LONG, SHORT).
420    #[serde(default)]
421    pub position_side: Option<BinancePositionSide>,
422    /// Notional position value.
423    #[serde(default)]
424    pub notional: Option<String>,
425    /// Isolated wallet balance.
426    #[serde(default)]
427    pub isolated_wallet: Option<String>,
428    /// ADL quantile indicator.
429    #[serde(default)]
430    pub adl_quantile: Option<u8>,
431    /// Last update time.
432    #[serde(default)]
433    pub update_time: Option<i64>,
434    /// Break-even price.
435    #[serde(default)]
436    pub break_even_price: Option<String>,
437    /// Bankruptcy price.
438    #[serde(default)]
439    pub bust_price: Option<String>,
440}
441
442/// Income history record.
443#[derive(Clone, Debug, Serialize, Deserialize)]
444#[serde(rename_all = "camelCase")]
445pub struct BinanceIncomeRecord {
446    /// Symbol name (may be empty for transfers).
447    #[serde(default)]
448    pub symbol: Option<Ustr>,
449    /// Income type (e.g., FUNDING_FEE, COMMISSION).
450    pub income_type: BinanceIncomeType,
451    /// Income amount.
452    pub income: String,
453    /// Asset code.
454    pub asset: Ustr,
455    /// Event time in milliseconds.
456    pub time: i64,
457    /// Additional info field.
458    #[serde(default)]
459    pub info: Option<String>,
460    /// Transaction ID.
461    #[serde(default)]
462    pub tran_id: Option<i64>,
463    /// Related trade ID.
464    #[serde(default)]
465    pub trade_id: Option<i64>,
466}
467
468/// User trade record.
469#[derive(Clone, Debug, Serialize, Deserialize)]
470#[serde(rename_all = "camelCase")]
471pub struct BinanceUserTrade {
472    /// Symbol name.
473    pub symbol: Ustr,
474    /// Trade ID.
475    pub id: i64,
476    /// Order ID.
477    pub order_id: i64,
478    /// Trade price.
479    pub price: String,
480    /// Executed quantity.
481    pub qty: String,
482    /// Quote quantity.
483    #[serde(default)]
484    pub quote_qty: Option<String>,
485    /// Realized PnL for the trade.
486    pub realized_pnl: String,
487    /// Buy/sell side.
488    pub side: BinanceSide,
489    /// Position side (BOTH, LONG, SHORT).
490    #[serde(default)]
491    pub position_side: Option<BinancePositionSide>,
492    /// Trade time in milliseconds.
493    pub time: i64,
494    /// Was the buyer the maker?
495    pub buyer: bool,
496    /// Was the trade maker liquidity?
497    pub maker: bool,
498    /// Commission paid.
499    #[serde(default)]
500    pub commission: Option<String>,
501    /// Commission asset.
502    #[serde(default)]
503    pub commission_asset: Option<Ustr>,
504    /// Margin asset (if provided).
505    #[serde(default)]
506    pub margin_asset: Option<Ustr>,
507}
508
509/// Futures order information.
510#[derive(Clone, Debug, Serialize, Deserialize)]
511#[serde(rename_all = "camelCase")]
512pub struct BinanceFuturesOrder {
513    /// Symbol name.
514    pub symbol: Ustr,
515    /// Order ID.
516    pub order_id: i64,
517    /// Client order ID.
518    pub client_order_id: String,
519    /// Original order quantity.
520    pub orig_qty: String,
521    /// Executed quantity.
522    pub executed_qty: String,
523    /// Cumulative quote asset transacted.
524    pub cum_quote: String,
525    /// Original limit price.
526    pub price: String,
527    /// Average execution price.
528    #[serde(default)]
529    pub avg_price: Option<String>,
530    /// Stop price.
531    #[serde(default)]
532    pub stop_price: Option<String>,
533    /// Order status.
534    pub status: BinanceOrderStatus,
535    /// Time in force.
536    pub time_in_force: BinanceTimeInForce,
537    /// Order type.
538    #[serde(rename = "type")]
539    pub order_type: BinanceFuturesOrderType,
540    /// Original order type.
541    #[serde(default)]
542    pub orig_type: Option<BinanceFuturesOrderType>,
543    /// Order side (BUY/SELL).
544    pub side: BinanceSide,
545    /// Position side (BOTH/LONG/SHORT).
546    #[serde(default)]
547    pub position_side: Option<BinancePositionSide>,
548    /// Reduce-only flag.
549    #[serde(default)]
550    pub reduce_only: Option<bool>,
551    /// Close position flag (for stop orders).
552    #[serde(default)]
553    pub close_position: Option<bool>,
554    /// Trailing delta activation price.
555    #[serde(default)]
556    pub activate_price: Option<String>,
557    /// Trailing callback rate.
558    #[serde(default)]
559    pub price_rate: Option<String>,
560    /// Working type (CONTRACT_PRICE or MARK_PRICE).
561    #[serde(default)]
562    pub working_type: Option<BinanceWorkingType>,
563    /// Whether price protection is enabled.
564    #[serde(default)]
565    pub price_protect: Option<bool>,
566    /// Whether order uses isolated margin.
567    #[serde(default)]
568    pub is_isolated: Option<bool>,
569    /// Good till date (for GTD orders).
570    #[serde(default)]
571    pub good_till_date: Option<i64>,
572    /// Price match mode.
573    #[serde(default)]
574    pub price_match: Option<BinancePriceMatch>,
575    /// Self-trade prevention mode.
576    #[serde(default)]
577    pub self_trade_prevention_mode: Option<BinanceSelfTradePreventionMode>,
578    /// Last update time.
579    #[serde(default)]
580    pub update_time: Option<i64>,
581    /// Working order ID for tracking.
582    #[serde(default)]
583    pub working_type_id: Option<i64>,
584}
nautilus_binance/futures/http/models.rs

nautilus_binance/futures/http/
models.rs
