bybit/models/position_data.rs
1use crate::prelude::*;
2
3/// Represents detailed data about a single position in Bybit's perpetual futures market.
4///
5/// This struct contains comprehensive information about a position, including size, leverage, profit/loss, and risk parameters.
6///
7/// # Bybit API Reference
8/// Part of the position WebSocket stream (https://bybit-exchange.github.io/docs/v5/websocket/private/position).
9///
10/// # Perpetual Futures Context
11/// Position data is critical for risk management in futures trading. Bots use this to monitor margin requirements, unrealized PnL, and liquidation risks.
12#[derive(Serialize, Deserialize, Debug, Clone)]
13#[serde(rename_all = "camelCase")]
14pub struct PositionData {
15 /// The position index (0 for one-way mode, 1 for buy-side hedge, 2 for sell-side hedge).
16 ///
17 /// Indicates the position mode. Bots must handle different indices for hedged vs. one-way positions to manage risk accurately.
18 pub position_idx: u8,
19
20 /// The trading mode (0 for regular, 1 for isolated margin).
21 ///
22 /// Specifies whether the position uses cross or isolated margin. Bots need to adjust margin calculations based on this mode.
23 pub trade_mode: u8,
24
25 /// The risk ID for the position's risk limit.
26 ///
27 /// Corresponds to Bybit's risk limit tiers, which define margin requirements. Bots should monitor this to ensure compliance with risk limits.
28 pub risk_id: u8,
29
30 /// The risk limit value (as a string, e.g., "1000000").
31 ///
32 /// Represents the maximum exposure allowed for the risk tier. Bots use this to cap position sizes and avoid margin violations.
33 pub risk_limit_value: String,
34
35 /// The trading pair symbol (e.g., "BTCUSDT").
36 ///
37 /// Identifies the market for the position. Bots filter by symbol to manage specific markets.
38 pub symbol: String,
39
40 /// The side of the position ("Buy" for long, "Sell" for short).
41 ///
42 /// Indicates the direction of the position. Bots use this to calculate exposure and hedge positions.
43 pub side: Side,
44
45 /// The size of the position (in contracts or base currency).
46 ///
47 /// Represents the volume of the position. Bots monitor this to manage exposure and ensure it aligns with strategy limits.
48 #[serde(with = "string_to_float")]
49 pub size: f64,
50
51 /// The average entry price of the position.
52 ///
53 /// The price at which the position was opened. Bots use this to calculate unrealized PnL and set stop-loss/take-profit levels.
54 #[serde(with = "string_to_float")]
55 pub entry_price: f64,
56
57 /// The leverage used for the position (as a string, e.g., "10").
58 ///
59 /// Indicates the leverage multiplier (e.g., 10x). Higher leverage increases potential returns but also liquidation risk. Bots must adjust position sizes based on leverage to manage risk.
60 pub leverage: String,
61
62 /// The total value of the position (in quote currency).
63 ///
64 /// Calculated as size * entry price. Bots use this to assess exposure and margin requirements.
65 #[serde(with = "string_to_float")]
66 pub position_value: f64,
67
68 /// The margin allocated to the position.
69 ///
70 /// Represents the funds reserved for the position. Bots monitor this to ensure sufficient margin and avoid liquidation.
71 #[serde(with = "string_to_float")]
72 pub position_balance: f64,
73
74 /// The current mark price of the position.
75 ///
76 /// The fair value of the asset, used for PnL and margin calculations. Bots use this to track unrealized PnL and liquidation risks.
77 #[serde(with = "string_to_float")]
78 pub mark_price: f64,
79
80 /// The initial margin requirement (as a string, e.g., "1000").
81 ///
82 /// The minimum margin needed to open the position. Bots use this to calculate capital requirements and optimize margin usage.
83 #[serde(rename = "positionIM")]
84 pub position_im: String,
85
86 /// The maintenance margin requirement (as a string, e.g., "500").
87 ///
88 /// The minimum margin needed to maintain the position. Falling below this triggers liquidation. Bots must monitor this closely to avoid forced closures.
89 #[serde(rename = "positionMM")]
90 pub position_mm: String,
91
92 /// The take-profit price for the position.
93 ///
94 /// The price at which the position will automatically close for a profit. Bots can set this to lock in gains and automate exits.
95 #[serde(with = "string_to_float")]
96 pub take_profit: f64,
97
98 /// The stop-loss price for the position.
99 ///
100 /// The price at which the position will automatically close to limit losses. Bots use this to manage downside risk.
101 #[serde(with = "string_to_float")]
102 pub stop_loss: f64,
103
104 /// The trailing stop price (optional).
105 ///
106 /// A dynamic stop-loss that follows the market price. Bots can use this for trend-following strategies to lock in profits while allowing upside potential.
107 #[serde(with = "string_to_float_optional")]
108 pub trailing_stop: Option<f64>,
109
110 /// The unrealized profit and loss (as a string, e.g., "100.50").
111 ///
112 /// The current profit or loss based on the mark price. Bots use this to monitor performance and make real-time adjustments.
113 #[serde(rename = "unrealisedPnl")]
114 pub unrealised_pnl: String,
115
116 /// The cumulative realized profit and loss (as a string, e.g., "500.75").
117 ///
118 /// The total profit or loss from closed portions of the position. Bots use this to track overall performance.
119 #[serde(rename = "cumRealisedPnl")]
120 pub cum_realised_pnl: String,
121
122 /// The timestamp when the position was created (in milliseconds).
123 ///
124 /// Indicates when the position was opened. Bots use this for position aging and strategy timing.
125 #[serde(with = "string_to_u64")]
126 pub created_time: u64,
127
128 /// The timestamp when the position was last updated (in milliseconds).
129 ///
130 /// Indicates the most recent change to the position. Bots use this to track updates and ensure data freshness.
131 #[serde(with = "string_to_u64")]
132 pub updated_time: u64,
133
134 /// The take-profit/stop-loss mode (e.g., "Full" or "Partial").
135 ///
136 /// Specifies how TP/SL orders are applied. Bots must handle different modes to execute correct exit strategies.
137 #[serde(rename = "tpslMode")]
138 pub tpsl_mode: String,
139
140 /// The liquidation price for the position.
141 ///
142 /// The price at which the position will be forcibly closed due to insufficient margin. Bots must monitor this to avoid unexpected liquidations, especially in volatile markets.
143 #[serde(with = "string_to_float")]
144 pub liq_price: f64,
145
146 /// The bankruptcy price for the position (optional).
147 ///
148 /// The price at which the position's margin is completely depleted, leading to a total loss. This is critical for bots to monitor, as it represents the worst-case scenario. Bots should use this to set conservative stop-losses and avoid catastrophic losses.
149 #[serde(with = "string_to_float_optional")]
150 pub bust_price: Option<f64>,
151
152 /// The category of the position (e.g., "linear" for USDT-margined futures).
153 ///
154 /// Specifies the contract type. Bots must handle different categories (e.g., linear vs. inverse) due to differences in margin and settlement.
155 pub category: String,
156
157 /// The status of the position (e.g., "Normal").
158 ///
159 /// Indicates whether the position is active or in a special state (e.g., liquidation). Bots use this to filter active positions for management.
160 pub position_status: String,
161
162 /// The auto-deleveraging (ADL) rank indicator (0-4).
163 ///
164 /// Indicates the likelihood of the position being auto-deleveraged in extreme market conditions. Higher ranks mean higher risk. Bots should monitor this to reduce exposure in volatile markets.
165 pub adl_rank_indicator: u8,
166
167 /// Whether auto-margin addition is enabled (0 for disabled, 1 for enabled).
168 ///
169 /// If enabled, Bybit automatically adds margin to prevent liquidation. Bots should account for this in margin management to avoid unexpected changes.
170 pub auto_add_margin: u8,
171
172 /// The timestamp when the maintenance margin rate was last updated (optional, in milliseconds).
173 ///
174 /// Indicates when margin requirements changed. Bots can use this to track margin updates and adjust strategies.
175 #[serde(with = "string_to_u64_optional")]
176 pub mmr_sys_updated_time: Option<u64>,
177
178 /// The timestamp when the leverage was last updated (optional, in milliseconds).
179 ///
180 /// Indicates when leverage settings changed. Bots should monitor this to ensure leverage aligns with risk parameters.
181 #[serde(with = "string_to_u64_optional")]
182 pub leverage_sys_updated_time: Option<u64>,
183
184 /// The sequence number for the position update.
185 ///
186 /// Used to ensure updates are processed in order. Bots should validate sequence numbers to avoid missing or duplicate updates.
187 pub seq: u64,
188
189 /// Whether the position is reduce-only.
190 ///
191 /// If `true`, the position can only reduce size (e.g., close trades). Bots must respect this to avoid placing invalid orders.
192 pub is_reduce_only: bool,
193}