bybit/models/coin_data.rs
1use crate::prelude::*;
2
3/// Represents balance and margin data for a specific currency in the account.
4///
5/// This struct details the financial state of a single currency (e.g., USDT, BTC) within a Bybit account, used for multi-currency margin management (https://bybit-exchange.github.io/docs/v5/account/wallet-balance).
6/// For trading bots, `CoinData` is critical for allocating collateral, managing borrowing, and tracking currency-specific PNL in perpetual futures.
7#[derive(Serialize, Deserialize, Debug, Clone)]
8#[serde(rename_all = "camelCase")]
9pub struct CoinData {
10 /// The currency, e.g., "USDT", "BTC".
11 ///
12 /// This identifies the coin for which balance and margin data is provided, critical for multi-currency accounts (https://bybit-exchange.github.io/docs/v5/account/wallet-balance).
13 /// **Bot Implication**: Bots use `coin` to route funds and collateral correctly, ensuring proper currency alignment for trades and margin.
14 pub coin: String,
15
16 /// Total equity for the currency, including wallet balance and unrealized PNL.
17 ///
18 /// This represents the net worth of the currency in the account, used for leverage and risk calculations (https://bybit-exchange.github.io/docs/v5/account/wallet-balance).
19 /// **Bot Implication**: Bots monitor `equity` to assess currency-specific financial health, guiding allocation and risk decisions.
20 #[serde(with = "string_to_float")]
21 pub equity: f64,
22
23 /// USD value of the currency’s equity, converted at the current market rate.
24 ///
25 /// This normalizes the currency’s equity to USD for cross-currency comparisons and risk aggregation (https://bybit-exchange.github.io/docs/v5/account/wallet-balance).
26 /// **Bot Implication**: Bots use `usd_value` to standardize risk exposure across currencies, simplifying account-level risk management.
27 #[serde(with = "string_to_float")]
28 pub usd_value: f64,
29
30 /// Available balance for the currency, excluding margin and locked funds.
31 ///
32 /// This is the liquid balance available for trading or withdrawal in the specific currency (https://bybit-exchange.github.io/docs/v5/account/wallet-balance).
33 /// **Bot Implication**: Bots track `wallet_balance` to ensure sufficient liquidity for new positions or margin top-ups in the currency.
34 #[serde(with = "string_to_float")]
35 pub wallet_balance: f64,
36
37 /// Amount available for withdrawal in the currency, if specified.
38 ///
39 /// This reflects the portion of the wallet balance that can be withdrawn, accounting for restrictions like pending orders (https://bybit-exchange.github.io/docs/v5/account/wallet-balance).
40 /// **Bot Implication**: Bots use `available_to_withdraw` to manage cash flow, ensuring funds are accessible when needed without disrupting trading.
41 #[serde(with = "string_to_float_optional")]
42 pub available_to_withdraw: Option<f64>,
43
44 /// Amount available to borrow in the currency, if specified.
45 ///
46 /// This indicates the additional leverage available for the currency in Bybit’s unified margin account (https://bybit-exchange.github.io/docs/v5/account/borrow).
47 /// **Bot Implication**: bots use `available_to_borrow` to expand positions, but must balance borrowing with liquidation risks in volatile markets.
48 #[serde(with = "string_to_float_optional")]
49 pub available_to_borrow: Option<f64>,
50
51 /// Total borrowed amount in the currency.
52 ///
53 /// This tracks loans taken in the currency, impacting leverage and interest costs (https://bybit-exchange.github.io/docs/v5/account/borrow).
54 /// **Bot Implication**: Bots monitor `borrow_amount` to manage interest expenses and ensure borrowed funds don’t exceed risk thresholds.
55 #[serde(with = "string_to_float")]
56 pub borrow_amount: f64,
57
58 /// Accrued interest on borrowed funds in the currency.
59 ///
60 /// This represents the cost of borrowing, which accumulates over time and affects profitability (https://bybit-exchange.github.io/docs/v5/account/borrow).
61 /// **Bot Implication**: Bots track `accrued_interest` to optimize borrowing strategies, minimizing costs while maintaining leverage.
62 #[serde(with = "string_to_float")]
63 pub accrued_interest: f64,
64
65 /// Initial margin for orders in the currency.
66 ///
67 /// This is the collateral required for open orders in the currency, impacting available balance (https://bybit-exchange.github.io/docs/v5/account/risk-limit).
68 /// **Bot Implication**: Bots use `total_order_im` to allocate margin efficiently, ensuring orders don’t overcommit funds.
69 #[serde(rename = "totalOrderIM", with = "string_to_float")]
70 pub total_order_im: f64,
71
72 /// Initial margin for positions in the currency, as a string.
73 ///
74 /// This is the collateral tied up in open positions, expressed as a string for precision (https://bybit-exchange.github.io/docs/v5/account/risk-limit).
75 /// **Bot Implication**: Bots monitor `total_position_im` to manage position margin, preventing over-leveraging or margin shortages.
76 #[serde(rename = "totalPositionIM", with = "string_to_float")]
77 pub total_position_im: f64,
78
79 /// Maintenance margin for positions in the currency, as a string.
80 ///
81 /// This is the minimum collateral needed to maintain positions, critical for avoiding liquidations (https://bybit-exchange.github.io/docs/v5/account/risk-limit).
82 /// **Bot Implication**: Bots prioritize `total_position_mm` to ensure positions remain funded, adjusting leverage or topping up margin as needed.
83 #[serde(rename = "totalPositionMM", with = "string_to_float")]
84 pub total_position_mm: f64,
85
86 /// Unrealized profit and loss for positions in the currency.
87 ///
88 /// This reflects paper gains or losses on open positions, affecting equity and margin (https://bybit-exchange.github.io/docs/v5/account/position).
89 /// **Bot Implication**: Bots use `unrealised_pnl` to evaluate position performance and adjust risk controls, as large losses can trigger margin calls.
90 #[serde(with = "string_to_float")]
91 pub unrealised_pnl: f64,
92
93 /// Cumulative realized profit and loss for the currency.
94 ///
95 /// This tracks the net realized gains or losses from closed positions, impacting account equity (https://bybit-exchange.github.io/docs/v5/account/position).
96 /// **Bot Implication**: Bots use `cum_realised_pnl` to assess strategy performance and update capital allocation based on realized outcomes.
97 #[serde(with = "string_to_float")]
98 pub cum_realised_pnl: f64,
99
100 /// Bonus balance in the currency, e.g., promotional credits.
101 ///
102 /// This represents non-withdrawable funds, often from Bybit promotions, used for trading (https://bybit-exchange.github.io/docs/v5/account/wallet-balance).
103 /// **Bot Implication**: Bots account for `bonus` in balance calculations, but must adjust for withdrawal restrictions when planning cash flow.
104 #[serde(with = "string_to_float")]
105 pub bonus: f64,
106
107 /// Indicates if the currency can be used as collateral.
108 ///
109 /// When `true`, the currency is eligible for margin calculations in Bybit’s unified account (https://bybit-exchange.github.io/docs/v5/account/margin-mode).
110 /// **Bot Implication**: Bots check `collateral_switch` to ensure only eligible currencies are used for margin, avoiding funding errors.
111 pub collateral_switch: bool,
112
113 /// Indicates if the currency is used as margin collateral.
114 ///
115 /// When `true`, the currency actively contributes to margin requirements (https://bybit-exchange.github.io/docs/v5/account/margin-mode).
116 /// **Bot Implication**: Bots prioritize `margin_collateral` currencies for margin allocation, optimizing collateral efficiency.
117 pub margin_collateral: bool,
118
119 /// Amount of the currency locked, e.g., for pending orders, as a string.
120 ///
121 /// This represents funds tied up in non-withdrawable states, reducing available balance (https://bybit-exchange.github.io/docs/v5/account/wallet-balance).
122 /// **Bot Implication**: Bots track `locked` to avoid overestimating available funds, ensuring accurate liquidity planning.
123 #[serde(with = "string_to_float")]
124 pub locked: f64,
125
126 /// Quantity of the currency used for spot hedging.
127 ///
128 /// This reflects the amount allocated to spot positions for hedging futures exposure, as a string (https://bybit-exchange.github.io/docs/v5/account/position).
129 /// **Bot Implication**: Bots use `spot_hedging_qty` to balance futures and spot positions, minimizing directional risk in hedging strategies.
130 #[serde(with = "string_to_float")]
131 pub spot_hedging_qty: f64,
132}