bybit/models/trade_history.rs
1use crate::prelude::*;
2
3/// Represents a single trade history record.
4///
5/// Each record details an executed trade, including execution price, quantity, fees, and timestamps. Bots use this to track trade outcomes, calculate realized profits, and assess strategy effectiveness in perpetual futures.
6#[derive(Serialize, Deserialize, Clone, Debug)]
7#[serde(rename_all = "camelCase")]
8pub struct TradeHistory {
9 /// The trading pair symbol (e.g., "BTCUSDT").
10 ///
11 /// Identifies the perpetual futures contract for the trade. Bots should verify this matches the requested symbol to ensure data accuracy.
12 pub symbol: String,
13
14 /// The order type (e.g., "Limit", "Market").
15 ///
16 /// Indicates whether the trade was executed via a limit or market order. Bots use this to analyze execution strategy effectiveness.
17 pub order_type: String,
18
19 /// The underlying price (optional).
20 ///
21 /// For derivatives, this may represent the price of the underlying asset. Often empty for perpetual futures. Bots can ignore this unless analyzing specific derivative products.
22 #[serde(default, skip_serializing_if = "String::is_empty")]
23 pub underlying_price: String,
24
25 /// The user-defined order link ID (optional).
26 ///
27 /// A custom identifier for the order. Bots can use this to correlate trades with specific strategies or client orders.
28 #[serde(default, skip_serializing_if = "String::is_empty")]
29 pub order_link_id: String,
30
31 /// The trade side ("Buy" or "Sell").
32 ///
33 /// Indicates whether the trade was a buy or sell. Bots use this to track position direction and calculate net exposure.
34 pub side: String,
35
36 /// The index price at execution (optional).
37 ///
38 /// The index price of the asset at the time of execution, used for mark-to-market calculations in perpetual futures. Often empty in some responses. Bots can use this for P&L calculations if available.
39 #[serde(default, skip_serializing_if = "String::is_empty")]
40 pub index_price: String,
41
42 /// The unique order ID.
43 ///
44 /// Identifies the order associated with the trade. Bots use this to link trades to specific orders in their tracking systems.
45 pub order_id: String,
46
47 /// The stop order type (e.g., "StopLoss", "TakeProfit").
48 ///
49 /// Indicates if the trade was triggered by a stop order. Bots use this to analyze conditional order executions.
50 pub stop_order_type: String,
51
52 /// The remaining quantity after execution.
53 ///
54 /// The unfilled portion of the order after the trade. Bots use this to track partial fills and manage order status.
55 pub leaves_qty: String,
56
57 /// The timestamp of the trade execution.
58 ///
59 /// Indicates when the trade occurred. Bots use this to align trade data with other time-series data for analysis.
60 pub exec_time: String,
61
62 /// The currency of the fees (optional).
63 ///
64 /// Specifies the currency in which fees were charged (e.g., "USDT"). Bots use this to calculate net profitability.
65 #[serde(default, skip_serializing_if = "String::is_empty")]
66 pub fee_currency: String,
67
68 /// Indicates if the trade was executed as a maker.
69 ///
70 /// `true` if the trade was a maker order (added liquidity), `false` if taker (removed liquidity). Bots use this to optimize fee structures, as maker fees are typically lower.
71 pub is_maker: bool,
72
73 /// The execution fee for the trade.
74 ///
75 /// The fee charged for the trade, in the settlement currency. Bots use this to calculate net P&L and assess trading costs in perpetual futures.
76 #[serde(with = "string_to_float")]
77 pub exec_fee: f64,
78
79 /// The fee rate applied to the trade.
80 ///
81 /// The percentage fee rate (e.g., "0.00055" for 0.055%). Bots use this to verify fee calculations and optimize for lower-cost execution strategies.
82 pub fee_rate: String,
83
84 /// The unique execution ID.
85 ///
86 /// A unique identifier for the trade execution on Bybit’s exchange. Bots use this to track specific trades and avoid duplicates.
87 pub exec_id: String,
88
89 /// The implied volatility for the trade (optional).
90 ///
91 /// Relevant for options trading, typically empty for perpetual futures. Bots can ignore this unless trading options.
92 #[serde(default, skip_serializing_if = "String::is_empty")]
93 pub trade_iv: String,
94
95 /// The block trade ID (optional).
96 ///
97 /// Identifies if the trade was a block trade, executed off the public order book. Bots can use this to detect large institutional trades.
98 #[serde(default, skip_serializing_if = "String::is_empty")]
99 pub block_trade_id: String,
100
101 /// The mark price at execution.
102 ///
103 /// The mark price used for P&L calculations in perpetual futures. Bots use this to calculate unrealized P&L and assess position health.
104 #[serde(with = "string_to_float")]
105 pub mark_price: f64,
106
107 /// The execution price of the trade.
108 ///
109 /// The price at which the trade was executed. Bots use this to calculate realized P&L and analyze execution quality.
110 #[serde(with = "string_to_float")]
111 pub exec_price: f64,
112
113 /// The mark implied volatility (optional).
114 ///
115 /// Relevant for options, typically empty for perpetual futures. Bots can ignore this field.
116 #[serde(default, skip_serializing_if = "String::is_empty")]
117 pub mark_iv: String,
118
119 /// The total order quantity.
120 ///
121 /// The total quantity of the order associated with the trade. Bots use this to track order size and fill progress.
122 #[serde(with = "string_to_float")]
123 pub order_qty: f64,
124
125 /// The order price.
126 ///
127 /// The price specified in the order (for limit orders). Bots use this to compare with `exec_price` to assess slippage.
128 #[serde(with = "string_to_float")]
129 pub order_price: f64,
130
131 /// The execution value of the trade.
132 ///
133 /// The monetary value of the trade (`exec_price` * `exec_qty`). Bots use this to calculate trade size in the settlement currency.
134 #[serde(with = "string_to_float")]
135 pub exec_value: f64,
136
137 /// The execution type (e.g., "Trade", "Funding").
138 ///
139 /// Indicates the nature of the execution (e.g., regular trade or funding fee). Bots use this to filter trades for P&L calculations.
140 pub exec_type: String,
141
142 /// The executed quantity of the trade.
143 ///
144 /// The amount of the base asset traded. Bots use this to track fill amounts and update position sizes.
145 #[serde(with = "string_to_float")]
146 pub exec_qty: f64,
147
148 /// The closed position size (optional).
149 ///
150 /// The portion of the position closed by this trade, if applicable. Bots use this to track position reductions.
151 #[serde(
152 rename = "closedSize",
153 default,
154 skip_serializing_if = "String::is_empty"
155 )]
156 pub closed_size: String,
157
158 /// The sequence number of the trade.
159 ///
160 /// A unique sequence ID for ordering trades. Bots can use this to ensure proper chronological processing of trade data.
161 pub seq: u64,
162}
163
164impl<'a> TradeHistoryRequest<'a> {
165 /// Creates a default TradeHistory request.
166 ///
167 /// Returns a request with `category` set to `Linear` and all other fields unset. Suitable for broad queries but should be customized for specific analysis needs.
168 pub fn default() -> TradeHistoryRequest<'a> {
169 TradeHistoryRequest::new(
170 Category::Linear,
171 None,
172 None,
173 None,
174 None,
175 None,
176 None,
177 None,
178 None,
179 )
180 }
181 /// Constructs a new TradeHistory request with specified parameters.
182 ///
183 /// Allows full customization. Bots should use this to specify the exact symbol, time range, and filters to align with their analysis requirements.
184 pub fn new(
185 category: Category,
186 symbol: Option<&'a str>,
187 order_id: Option<&'a str>,
188 order_link_id: Option<&'a str>,
189 base_coin: Option<&'a str>,
190 start_time: Option<u64>,
191 end_time: Option<u64>,
192 exec_type: Option<&'a str>,
193 limit: Option<u64>,
194 ) -> TradeHistoryRequest<'a> {
195 TradeHistoryRequest {
196 category,
197 symbol: symbol.map(Cow::Borrowed),
198 order_id: order_id.map(Cow::Borrowed),
199 order_link_id: order_link_id.map(Cow::Borrowed),
200 base_coin: base_coin.map(Cow::Borrowed),
201 start_time,
202 end_time,
203 exec_type: exec_type.map(Cow::Borrowed),
204 limit,
205 }
206 }
207}