rust-okx 0.5.1

Async Rust client for the OKX v5 REST API
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324

//! Trading bot channel models (`grid-orders-*`, `grid-positions`, `recurring-buy`, etc.).
//!
//! Private channels; login required.

use serde::Deserialize;

use super::ExtraFields;
use crate::model::NumberString;

/// Spot/contract grid-order channel row.
///
/// OKX docs: <https://www.okx.com/docs-v5/en/#trading-bot-websocket-grid-orders-channel>
#[derive(Debug, Clone, Default, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct GridOrderUpdate {
    /// Instrument ID, e.g., `BTC-USDT`.
    #[serde(default)]
    pub inst_id: String,
    /// OKX-assigned algo order ID.
    #[serde(default)]
    pub algo_id: String,
    /// Client-supplied algo order ID.
    #[serde(default)]
    pub algo_cl_ord_id: String,
    /// Instrument type, e.g., `SPOT`, `SWAP`, `FUTURES`.
    #[serde(default)]
    pub inst_type: String,
    /// Algo order type.
    ///
    /// Documented values: `grid` (spot grid), `contract_grid` (contract grid),
    /// `moon_grid` (moon grid).
    #[serde(default)]
    pub algo_ord_type: String,
    /// Current state of the grid strategy.
    ///
    /// Documented values: `starting`, `running`, `stopping`, `stopped`.
    #[serde(default)]
    pub state: String,
    /// Grid direction: `long`, `short`, or `neutral`.
    #[serde(default)]
    pub direction: String,
    /// Grid spacing type: `arithmetic` or `geometric`.
    #[serde(default)]
    pub run_type: String,
    /// Total position size, in base currency for spot or contracts for derivatives.
    #[serde(default)]
    pub sz: NumberString,
    /// Initial investment amount.
    #[serde(default)]
    pub investment: NumberString,
    /// Total profit and loss since the strategy started.
    #[serde(default)]
    pub total_pnl: NumberString,
    /// Profit and loss ratio since the strategy started.
    #[serde(default)]
    pub pnl_ratio: NumberString,
    /// Type of stop condition that ended the strategy.
    ///
    /// Documented values: `0` (no stop), `1` (price stop), `2` (loss stop), `3` (profit stop).
    #[serde(default)]
    pub stop_type: String,
    /// Cancellation reason code when the strategy was stopped.
    #[serde(default)]
    pub cancel_type: String,
    /// Strategy creation time (Unix milliseconds).
    #[serde(default)]
    pub c_time: NumberString,
    /// Last update time (Unix milliseconds).
    #[serde(default)]
    pub u_time: NumberString,
    /// Push time (Unix milliseconds).
    #[serde(default)]
    pub p_time: NumberString,
    /// Unrecognized fields retained for forward compatibility.
    #[serde(flatten, default)]
    pub extra: ExtraFields,
}

/// Backward-compatible name for grid-order updates.
pub type TradingBotUpdate = GridOrderUpdate;

/// `grid-positions` channel row.
///
/// OKX docs: <https://www.okx.com/docs-v5/en/#trading-bot-websocket-grid-positions-channel>
#[derive(Debug, Clone, Default, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct GridPositionUpdate {
    /// OKX-assigned algo order ID of the grid strategy.
    #[serde(default)]
    pub algo_id: String,
    /// Instrument ID, e.g., `BTC-USDT-SWAP`.
    #[serde(default)]
    pub inst_id: String,
    /// Instrument type, e.g., `SWAP`, `FUTURES`.
    #[serde(default)]
    pub inst_type: String,
    /// Margin mode: `cross` or `isolated`.
    #[serde(default)]
    pub mgn_mode: String,
    /// Position side: `long`, `short`, or `net`.
    #[serde(default)]
    pub pos_side: String,
    /// Position quantity (number of contracts).
    #[serde(default)]
    pub pos: NumberString,
    /// Average entry price of the position.
    #[serde(default)]
    pub avg_px: NumberString,
    /// Unrealized profit and loss.
    #[serde(default)]
    pub upl: NumberString,
    /// Unrealized profit and loss ratio.
    #[serde(default)]
    pub upl_ratio: NumberString,
    /// Leverage.
    #[serde(default)]
    pub lever: NumberString,
    /// Estimated liquidation price.
    #[serde(default)]
    pub liq_px: NumberString,
    /// Last update time (Unix milliseconds).
    #[serde(default)]
    pub u_time: NumberString,
    /// Unrecognized fields retained for forward compatibility.
    #[serde(flatten, default)]
    pub extra: ExtraFields,
}

/// `grid-sub-orders` channel row.
///
/// OKX docs: <https://www.okx.com/docs-v5/en/#trading-bot-websocket-grid-sub-orders-channel>
#[derive(Debug, Clone, Default, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct GridSubOrderUpdate {
    /// Parent algo order ID of the grid strategy.
    #[serde(default)]
    pub algo_id: String,
    /// Instrument ID, e.g., `BTC-USDT`.
    #[serde(default)]
    pub inst_id: String,
    /// OKX-assigned order ID of this sub-order.
    #[serde(default)]
    pub ord_id: String,
    /// Client-supplied order ID of this sub-order.
    #[serde(default)]
    pub cl_ord_id: String,
    /// Order side: `buy` or `sell`.
    #[serde(default)]
    pub side: String,
    /// Order price.
    #[serde(default)]
    pub px: NumberString,
    /// Order size.
    #[serde(default)]
    pub sz: NumberString,
    /// Order state: `live`, `partially_filled`, `filled`, or `canceled`.
    #[serde(default)]
    pub state: String,
    /// Average fill price.
    #[serde(default)]
    pub avg_px: NumberString,
    /// Accumulated filled size.
    #[serde(default)]
    pub acc_fill_sz: NumberString,
    /// Fee amount (negative means deducted).
    #[serde(default)]
    pub fee: NumberString,
    /// Fee currency.
    #[serde(default)]
    pub fee_ccy: String,
    /// Profit and loss for this sub-order.
    #[serde(default)]
    pub pnl: NumberString,
    /// Order creation time (Unix milliseconds).
    #[serde(default)]
    pub c_time: NumberString,
    /// Last update time (Unix milliseconds).
    #[serde(default)]
    pub u_time: NumberString,
    /// Unrecognized fields retained for forward compatibility.
    #[serde(flatten, default)]
    pub extra: ExtraFields,
}

/// Currency allocation nested in [`RecurringBuyOrderUpdate`].
#[derive(Debug, Clone, Default, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct RecurringBuyAllocation {
    /// Currency code, e.g., `BTC`.
    #[serde(default)]
    pub ccy: String,
    /// Allocation ratio for this currency (0–1).
    #[serde(default)]
    pub ratio: NumberString,
    /// Unrecognized fields retained for forward compatibility.
    #[serde(flatten, default)]
    pub extra: ExtraFields,
}

/// `algo-recurring-buy` channel row.
///
/// OKX docs: <https://www.okx.com/docs-v5/en/#trading-bot-websocket-recurring-buy-orders-channel>
#[derive(Debug, Clone, Default, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct RecurringBuyOrderUpdate {
    /// OKX-assigned algo order ID.
    #[serde(default)]
    pub algo_id: String,
    /// Client-supplied algo order ID.
    #[serde(default)]
    pub algo_cl_ord_id: String,
    /// Instrument type covered by this strategy (typically `SPOT`).
    #[serde(default)]
    pub inst_type: String,
    /// Algo order type: `recurring_buy`.
    #[serde(default)]
    pub algo_ord_type: String,
    /// Strategy state: `running`, `stopping`, or `stopped`.
    #[serde(default)]
    pub state: String,
    /// User-defined strategy name.
    #[serde(default)]
    pub stgy_name: String,
    /// List of currencies and their allocation ratios.
    #[serde(default)]
    pub recurring_list: Vec<RecurringBuyAllocation>,
    /// Recurrence period: `monthly`, `weekly`, or `daily`.
    #[serde(default)]
    pub period: String,
    /// Day of the month or week on which to execute (applicable to monthly/weekly periods).
    #[serde(default)]
    pub recurring_day: String,
    /// Hour of day on which to execute (0–23).
    #[serde(default)]
    pub recurring_hour: String,
    /// Time (HH:MM) within the hour to execute.
    #[serde(default)]
    pub recurring_time: String,
    /// Time-zone identifier for `recurring_time`, e.g., `8` (UTC+8).
    #[serde(default)]
    pub time_zone: String,
    /// Quote-currency amount spent per execution cycle.
    #[serde(default)]
    pub amt: NumberString,
    /// Total quote-currency amount invested to date.
    #[serde(default)]
    pub investment_amt: NumberString,
    /// Quote currency used for investment, e.g., `USDT`.
    #[serde(default)]
    pub investment_ccy: String,
    /// Cumulative total investment amount.
    #[serde(default)]
    pub total_investment: NumberString,
    /// Total profit and loss since strategy start.
    #[serde(default)]
    pub total_pnl: NumberString,
    /// Annualized rate of return.
    #[serde(default)]
    pub total_ann_rate: NumberString,
    /// Profit and loss ratio since strategy start.
    #[serde(default)]
    pub pnl_ratio: NumberString,
    /// Total market cap of purchased assets in USD.
    #[serde(default)]
    pub mkt_cap: NumberString,
    /// Number of completed buy cycles.
    #[serde(default)]
    pub cycles: NumberString,
    /// Strategy tag.
    #[serde(default)]
    pub tag: String,
    /// Strategy creation time (Unix milliseconds).
    #[serde(default)]
    pub c_time: NumberString,
    /// Last update time (Unix milliseconds).
    #[serde(default)]
    pub u_time: NumberString,
    /// Push time (Unix milliseconds).
    #[serde(default)]
    pub p_time: NumberString,
    /// Unrecognized fields retained for forward compatibility.
    #[serde(flatten, default)]
    pub extra: ExtraFields,
}

/// `copytrading-notification` channel row.
///
/// OKX docs: <https://www.okx.com/docs-v5/en/#copy-trading-websocket-copy-trading-notification-channel>
#[derive(Debug, Clone, Default, Deserialize)]
#[serde(rename_all = "camelCase")]
#[non_exhaustive]
pub struct CopyTradingNotification {
    /// Type of copy-trading notification.
    ///
    /// Documented values: `open_position`, `close_position`, `adjust_margin`, etc.
    #[serde(default)]
    pub notification_type: String,
    /// Human-readable notification message.
    #[serde(default)]
    pub notification_msg: String,
    /// Instrument type, e.g., `SWAP`, `FUTURES`.
    #[serde(default)]
    pub inst_type: String,
    /// Instrument ID, e.g., `BTC-USDT-SWAP`.
    #[serde(default)]
    pub inst_id: String,
    /// Sub-position ID assigned by OKX.
    #[serde(default)]
    pub sub_pos_id: String,
    /// Unique code of the lead trader.
    #[serde(default)]
    pub unique_code: String,
    /// Notification push time (Unix milliseconds).
    #[serde(default)]
    pub ts: NumberString,
    /// Unrecognized fields retained for forward compatibility.
    #[serde(flatten, default)]
    pub extra: ExtraFields,
}