bybit/models/amend_order_request.rs
1use crate::prelude::*;
2
3/// Represents a request to amend an existing order on Bybit.
4///
5/// This struct defines parameters for modifying an order’s attributes, such as price,
6/// quantity, or TP/SL. In perpetual futures, amending orders is essential for adapting
7/// to market movements (e.g., tightening stop-losses). Bots must ensure the `order_id`
8/// or `order_link_id` is valid and that changes comply with Bybit’s constraints (e.g.,
9/// minimum quantity, price tick size) to avoid rejections.
10#[derive(Clone, Default, Serialize)]
11pub struct AmendOrderRequest<'a> {
12 /// The category of the trading product (e.g., Spot, Linear).
13 ///
14 /// Specifies the market for the order being amended. Bots must match this to the
15 /// original order’s category to avoid errors. In perpetual futures, `Linear` is
16 /// typical for USDT-margined contracts.
17 pub category: Category,
18
19 /// The trading pair symbol, e.g., "BTCUSDT".
20 ///
21 /// Identifies the asset pair of the order. Must match the original order’s symbol.
22 /// Bots should validate symbol consistency to prevent API errors in perpetual futures
23 /// trading.
24 pub symbol: Cow<'a, str>,
25
26 /// The unique identifier of the order to amend.
27 ///
28 /// Provided by Bybit when the order was created. Bots must include either `order_id`
29 /// or `order_link_id` to identify the order. In perpetual futures, accurate order
30 /// identification is critical for amending the correct position.
31 pub order_id: Option<Cow<'a, str>>,
32
33 /// The user-defined identifier of the order to amend.
34 ///
35 /// Allows bots to reference orders using their custom ID. Useful for tracking
36 /// multiple orders in perpetual futures strategies. Either `order_id` or
37 /// `order_link_id` must be provided.
38 pub order_link_id: Option<Cow<'a, str>>,
39
40 /// The implied volatility for options orders (optional).
41 ///
42 /// Used for options trading, not perpetual futures. Bots can ignore this unless
43 /// amending options orders, where accurate volatility is needed for pricing.
44 pub order_iv: Option<f64>,
45
46 /// The new trigger price for conditional orders.
47 ///
48 /// Updates the price at which a conditional order (e.g., stop-loss) activates.
49 /// In perpetual futures, bots use this to adjust risk management dynamically based
50 /// on market conditions. Ensure the price aligns with symbol constraints.
51 pub trigger_price: Option<f64>,
52
53 /// The new quantity of the order.
54 ///
55 /// Updates the order size. In perpetual futures, bots must ensure the new quantity
56 /// is valid (e.g., within position limits, sufficient margin) to avoid rejections.
57 /// Over-sizing can increase liquidation risk.
58 pub qty: f64,
59
60 /// The new price for limit orders.
61 ///
62 /// Updates the target price for a limit order. Bots should validate the price against
63 /// the symbol’s tick size and market conditions to ensure execution feasibility in
64 /// volatile perpetual futures markets.
65 pub price: Option<f64>,
66
67 /// The new take-profit/stop-loss mode (e.g., "Full", "Partial").
68 ///
69 /// Updates whether TP/SL applies to the entire position or a portion. Bots should
70 /// adjust this based on exit strategy; "Full" simplifies risk management, while
71 /// "Partial" suits scaling out in perpetual futures.
72 pub tpsl_mode: Option<Cow<'a, str>>,
73
74 /// The new take-profit price.
75 ///
76 /// Updates the price to lock in profits. Bots should set this based on updated market
77 /// analysis, ensuring it’s realistic given volatility in perpetual futures.
78 pub take_profit: Option<f64>,
79
80 /// The new stop-loss price.
81 ///
82 /// Updates the price to limit losses. Critical for risk management in perpetual
83 /// futures, bots should adjust SL dynamically to protect against adverse price
84 /// movements while avoiding premature exits.
85 pub stop_loss: Option<f64>,
86
87 /// The new trigger price type for take-profit.
88 ///
89 /// Updates the price metric (e.g., "MarkPrice") for TP triggering. Bots should choose
90 /// a reliable metric to ensure consistent execution in perpetual futures markets.
91 pub tp_trigger_by: Option<Cow<'a, str>>,
92
93 /// The new trigger price type for stop-loss.
94 ///
95 /// Updates the price metric for SL triggering. Similar to `tp_trigger_by`, bots
96 /// should select a stable trigger type to protect against manipulation in perpetual
97 /// futures.
98 pub sl_trigger_by: Option<Cow<'a, str>>,
99
100 /// The new trigger price type for conditional orders.
101 ///
102 /// Updates the price metric for triggering conditional orders. Bots should ensure
103 /// consistency with the order’s strategy and market conditions in perpetual futures.
104 pub trigger_by: Option<Cow<'a, str>>,
105
106 /// The new limit price for take-profit orders.
107 ///
108 /// Updates the exact price for limit-based TP orders. Bots must balance precision
109 /// with execution likelihood in volatile perpetual futures markets.
110 pub tp_limit_price: Option<f64>,
111
112 /// The new limit price for stop-loss orders.
113 ///
114 /// Updates the exact price for limit-based SL orders. Bots should ensure the price
115 /// is achievable to effectively limit losses in perpetual futures.
116 pub sl_limit_price: Option<f64>,
117}
118
119impl<'a> AmendOrderRequest<'a> {
120 /// Creates a default `AmendOrderRequest` with predefined values.
121 ///
122 /// Initializes an amendment request with common defaults. Bots should modify
123 /// necessary fields before submission to align with the target order’s attributes.
124 pub fn default() -> Self {
125 Self {
126 category: Category::Linear,
127 symbol: Cow::Borrowed("BTCUSDT"),
128 order_id: None,
129 order_link_id: None,
130 order_iv: None,
131 trigger_price: None,
132 qty: 0.00,
133 price: None,
134 tpsl_mode: None,
135 take_profit: None,
136 stop_loss: None,
137 tp_trigger_by: None,
138 sl_trigger_by: None,
139 trigger_by: None,
140 tp_limit_price: None,
141 sl_limit_price: None,
142 }
143 }
144 /// Creates a custom `AmendOrderRequest` with specified parameters.
145 ///
146 /// Allows bots to tailor an amendment request fully. Ensure all parameters are valid
147 /// and consistent with the original order to avoid API errors in perpetual futures
148 /// trading.
149 pub fn custom(
150 category: Category,
151 symbol: &'a str,
152 order_id: Option<&'a str>,
153 order_link_id: Option<&'a str>,
154 order_iv: Option<f64>,
155 trigger_price: Option<f64>,
156 qty: f64,
157 price: Option<f64>,
158 tpsl_mode: Option<&'a str>,
159 take_profit: Option<f64>,
160 stop_loss: Option<f64>,
161 tp_trigger_by: Option<&'a str>,
162 sl_trigger_by: Option<&'a str>,
163 trigger_by: Option<&'a str>,
164 tp_limit_price: Option<f64>,
165 sl_limit_price: Option<f64>,
166 ) -> Self {
167 Self {
168 category,
169 symbol: Cow::Borrowed(symbol),
170 order_id: order_id.map(Cow::Borrowed),
171 order_link_id: order_link_id.map(Cow::Borrowed),
172 order_iv,
173 trigger_price,
174 qty,
175 price,
176 tpsl_mode: tpsl_mode.map(Cow::Borrowed),
177 take_profit,
178 stop_loss,
179 tp_trigger_by: tp_trigger_by.map(Cow::Borrowed),
180 sl_trigger_by: sl_trigger_by.map(Cow::Borrowed),
181 trigger_by: trigger_by.map(Cow::Borrowed),
182 tp_limit_price,
183 sl_limit_price,
184 }
185 }
186}