1use nautilus_core::serialization::deserialize_optional_decimal_from_str;
22use rust_decimal::Decimal;
23use serde::Deserialize;
24use ustr::Ustr;
25
26#[derive(Clone, Debug, PartialEq, Deserialize)]
28#[serde(untagged)]
29pub enum BinancePapiBalanceResponse {
30 List(Vec<BinancePapiBalance>),
32 Single(Box<BinancePapiBalance>),
34}
35
36#[derive(Clone, Debug, PartialEq, Deserialize)]
38#[serde(rename_all = "camelCase")]
39pub struct BinancePapiBalance {
40 pub asset: Ustr,
42 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
44 pub total_wallet_balance: Option<Decimal>,
45 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
47 pub cross_margin_asset: Option<Decimal>,
48 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
50 pub cross_margin_borrowed: Option<Decimal>,
51 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
53 pub cross_margin_free: Option<Decimal>,
54 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
56 pub cross_margin_interest: Option<Decimal>,
57 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
59 pub cross_margin_locked: Option<Decimal>,
60 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
62 pub um_wallet_balance: Option<Decimal>,
63 #[serde(
65 rename = "umUnrealizedPNL",
66 default,
67 deserialize_with = "deserialize_optional_decimal_from_str"
68 )]
69 pub um_unrealized_pnl: Option<Decimal>,
70 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
72 pub cm_wallet_balance: Option<Decimal>,
73 #[serde(
75 rename = "cmUnrealizedPNL",
76 default,
77 deserialize_with = "deserialize_optional_decimal_from_str"
78 )]
79 pub cm_unrealized_pnl: Option<Decimal>,
80 #[serde(default)]
82 pub update_time: Option<i64>,
83 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
85 pub negative_balance: Option<Decimal>,
86}
87
88#[derive(Clone, Debug, PartialEq, Deserialize)]
90#[serde(rename_all = "camelCase")]
91pub struct BinancePapiAccountInfo {
92 #[serde(
94 rename = "uniMMR",
95 default,
96 deserialize_with = "deserialize_optional_decimal_from_str"
97 )]
98 pub uni_mmr: Option<Decimal>,
99 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
101 pub account_equity: Option<Decimal>,
102 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
104 pub actual_equity: Option<Decimal>,
105 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
107 pub account_initial_margin: Option<Decimal>,
108 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
110 pub account_maint_margin: Option<Decimal>,
111 #[serde(default)]
113 pub account_status: Option<Ustr>,
114 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
116 pub virtual_max_withdraw_amount: Option<Decimal>,
117 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
119 pub total_available_balance: Option<Decimal>,
120 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
122 pub total_margin_open_loss: Option<Decimal>,
123 #[serde(default)]
125 pub update_time: Option<i64>,
126}
127
128#[derive(Clone, Debug, PartialEq, Deserialize)]
130#[serde(rename_all = "camelCase")]
131pub struct BinancePapiFuturesAsset {
132 pub asset: Ustr,
134 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
136 pub cross_wallet_balance: Option<Decimal>,
137 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
139 pub cross_un_pnl: Option<Decimal>,
140 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
142 pub maint_margin: Option<Decimal>,
143 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
145 pub initial_margin: Option<Decimal>,
146 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
148 pub position_initial_margin: Option<Decimal>,
149 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
151 pub open_order_initial_margin: Option<Decimal>,
152 #[serde(default)]
154 pub update_time: Option<i64>,
155}
156
157#[derive(Clone, Debug, PartialEq, Deserialize)]
159pub struct BinancePapiUmAccount {
160 #[serde(default)]
162 pub assets: Option<Vec<BinancePapiFuturesAsset>>,
163 #[serde(default)]
165 pub positions: Option<Vec<BinancePapiUmPosition>>,
166}
167
168#[derive(Clone, Debug, PartialEq, Deserialize)]
170pub struct BinancePapiUmAccountV2 {
171 #[serde(default)]
173 pub assets: Option<Vec<BinancePapiFuturesAsset>>,
174 #[serde(default)]
176 pub positions: Option<Vec<BinancePapiUmPositionV2>>,
177}
178
179#[derive(Clone, Debug, PartialEq, Deserialize)]
181pub struct BinancePapiCmAccount {
182 #[serde(default)]
184 pub assets: Option<Vec<BinancePapiFuturesAsset>>,
185 #[serde(default)]
187 pub positions: Option<Vec<BinancePapiCmPosition>>,
188}
189
190#[derive(Clone, Debug, PartialEq, Deserialize)]
192#[serde(rename_all = "camelCase")]
193pub struct BinancePapiUmPosition {
194 pub symbol: Ustr,
196 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
198 pub initial_margin: Option<Decimal>,
199 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
201 pub maint_margin: Option<Decimal>,
202 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
204 pub unrealized_profit: Option<Decimal>,
205 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
207 pub position_initial_margin: Option<Decimal>,
208 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
210 pub open_order_initial_margin: Option<Decimal>,
211 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
213 pub leverage: Option<Decimal>,
214 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
216 pub entry_price: Option<Decimal>,
217 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
219 pub max_notional: Option<Decimal>,
220 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
222 pub bid_notional: Option<Decimal>,
223 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
225 pub ask_notional: Option<Decimal>,
226 pub position_side: Ustr,
228 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
230 pub position_amt: Option<Decimal>,
231 #[serde(default)]
233 pub update_time: Option<i64>,
234}
235
236#[derive(Clone, Debug, PartialEq, Deserialize)]
238#[serde(rename_all = "camelCase")]
239pub struct BinancePapiUmPositionV2 {
240 pub symbol: Ustr,
242 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
244 pub initial_margin: Option<Decimal>,
245 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
247 pub maint_margin: Option<Decimal>,
248 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
250 pub unrealized_profit: Option<Decimal>,
251 pub position_side: Ustr,
253 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
255 pub position_amt: Option<Decimal>,
256 #[serde(default)]
258 pub update_time: Option<i64>,
259 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
261 pub notional: Option<Decimal>,
262}
263
264#[derive(Clone, Debug, PartialEq, Deserialize)]
266#[serde(rename_all = "camelCase")]
267pub struct BinancePapiCmPosition {
268 pub symbol: Ustr,
270 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
272 pub position_amt: Option<Decimal>,
273 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
275 pub initial_margin: Option<Decimal>,
276 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
278 pub maint_margin: Option<Decimal>,
279 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
281 pub unrealized_profit: Option<Decimal>,
282 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
284 pub position_initial_margin: Option<Decimal>,
285 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
287 pub open_order_initial_margin: Option<Decimal>,
288 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
290 pub leverage: Option<Decimal>,
291 pub position_side: Ustr,
293 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
295 pub entry_price: Option<Decimal>,
296 #[serde(default, deserialize_with = "deserialize_optional_decimal_from_str")]
298 pub max_qty: Option<Decimal>,
299 #[serde(default)]
301 pub update_time: Option<i64>,
302}
303
304#[cfg(test)]
305mod tests {
306 use rstest::rstest;
307 use rust_decimal_macros::dec;
308
309 use super::*;
310
311 #[rstest]
312 fn test_balance_list_response_decodes_all_fields() {
313 let response: BinancePapiBalanceResponse = serde_json::from_str(include_str!(
314 "../../../test_data/papi/http_json/balance_list_response.json"
315 ))
316 .unwrap();
317
318 let BinancePapiBalanceResponse::List(balances) = response else {
319 panic!("expected list response");
320 };
321
322 assert_eq!(balances.len(), 2);
323
324 let usdt = &balances[0];
325 assert_eq!(usdt.asset, Ustr::from("USDT"));
326 assert_eq!(
327 usdt.total_wallet_balance,
328 Some(dec!(250.125000000000000001))
329 );
330 assert_eq!(usdt.cross_margin_asset, Some(dec!(140.500000000000000002)));
331 assert_eq!(usdt.cross_margin_borrowed, Some(dec!(12.25)));
332 assert_eq!(usdt.cross_margin_free, Some(dec!(125.25)));
333 assert_eq!(usdt.cross_margin_interest, Some(dec!(0.75)));
334 assert_eq!(usdt.cross_margin_locked, Some(dec!(15.25)));
335 assert_eq!(usdt.um_wallet_balance, Some(dec!(80.5)));
336 assert_eq!(usdt.um_unrealized_pnl, Some(dec!(-2.5)));
337 assert_eq!(usdt.cm_wallet_balance, Some(dec!(25.25)));
338 assert_eq!(usdt.cm_unrealized_pnl, Some(Decimal::ZERO));
339 assert_eq!(usdt.update_time, Some(1_700_000_000_123));
340 assert_eq!(usdt.negative_balance, Some(Decimal::ZERO));
341
342 let btc = &balances[1];
343 assert_eq!(btc.asset, Ustr::from("BTC"));
344 assert_eq!(btc.total_wallet_balance, Some(dec!(0.050000000000000001)));
345 assert_eq!(btc.cross_margin_asset, Some(dec!(0.020000000000000001)));
346 assert_eq!(btc.cross_margin_borrowed, Some(dec!(0.005)));
347 assert_eq!(btc.cross_margin_free, Some(dec!(0.015)));
348 assert_eq!(btc.cross_margin_interest, Some(dec!(0.0001)));
349 assert_eq!(btc.cross_margin_locked, Some(dec!(0.005)));
350 assert_eq!(btc.um_wallet_balance, Some(dec!(0.01)));
351 assert_eq!(btc.um_unrealized_pnl, None);
352 assert_eq!(btc.cm_wallet_balance, Some(dec!(0.02)));
353 assert_eq!(btc.cm_unrealized_pnl, Some(dec!(-0.0002)));
354 assert_eq!(btc.update_time, Some(1_700_000_000_456));
355 assert_eq!(btc.negative_balance, Some(dec!(-0.003)));
356 }
357
358 #[rstest]
359 fn test_balance_single_response_distinguishes_missing_empty_and_zero() {
360 let response: BinancePapiBalanceResponse = serde_json::from_str(include_str!(
361 "../../../test_data/papi/http_json/balance_single_response.json"
362 ))
363 .unwrap();
364
365 let BinancePapiBalanceResponse::Single(balance) = response else {
366 panic!("expected single response");
367 };
368
369 assert_eq!(balance.asset, Ustr::from("USDT"));
370 assert_eq!(balance.total_wallet_balance, Some(dec!(42.00000001)));
371 assert_eq!(balance.cross_margin_asset, None);
372 assert_eq!(balance.cross_margin_borrowed, Some(Decimal::ZERO));
373 assert_eq!(balance.cross_margin_free, Some(dec!(40.00000001)));
374 assert_eq!(balance.cross_margin_interest, None);
375 assert_eq!(balance.cross_margin_locked, Some(dec!(2)));
376 assert_eq!(balance.um_wallet_balance, None);
377 assert_eq!(balance.um_unrealized_pnl, None);
378 assert_eq!(balance.cm_wallet_balance, Some(Decimal::ZERO));
379 assert_eq!(balance.cm_unrealized_pnl, Some(Decimal::ZERO));
380 assert_eq!(balance.update_time, Some(1_700_000_000_789));
381 assert_eq!(balance.negative_balance, None);
382 }
383
384 #[rstest]
385 fn test_balance_invalid_decimal_returns_error() {
386 let error = serde_json::from_str::<BinancePapiBalance>(include_str!(
387 "../../../test_data/papi/http_json/balance_invalid_decimal_response.json"
388 ))
389 .unwrap_err();
390
391 assert!(error.to_string().contains("Invalid decimal"), "{error}");
392
393 let error = serde_json::from_str::<BinancePapiBalanceResponse>(include_str!(
394 "../../../test_data/papi/http_json/balance_invalid_decimal_response.json"
395 ))
396 .unwrap_err();
397
398 assert!(
399 error.to_string().contains("did not match any variant"),
400 "{error}"
401 );
402 }
403
404 #[rstest]
405 fn test_account_information_decodes_all_fields() {
406 let account: BinancePapiAccountInfo = serde_json::from_str(include_str!(
407 "../../../test_data/papi/http_json/account_information_response.json"
408 ))
409 .unwrap();
410
411 assert_eq!(account.uni_mmr, Some(dec!(0.123456789012345678)));
412 assert_eq!(account.account_equity, Some(dec!(1000.000000000000000001)));
413 assert_eq!(account.actual_equity, Some(dec!(1250.25)));
414 assert_eq!(account.account_initial_margin, Some(dec!(200.5)));
415 assert_eq!(account.account_maint_margin, Some(dec!(150.25)));
416 assert_eq!(account.account_status, Some(Ustr::from("MARGIN_CALL")));
417 assert_eq!(account.virtual_max_withdraw_amount, Some(dec!(300.75)));
418 assert_eq!(account.total_available_balance, None);
419 assert_eq!(account.total_margin_open_loss, Some(Decimal::ZERO));
420 assert_eq!(account.update_time, Some(1_700_000_001_000));
421 }
422
423 #[rstest]
424 fn test_um_account_v1_decodes_assets_and_positions() {
425 let account: BinancePapiUmAccount = serde_json::from_str(include_str!(
426 "../../../test_data/papi/http_json/um_account_detail_v1_response.json"
427 ))
428 .unwrap();
429 let assets = account.assets.unwrap();
430 let positions = account.positions.unwrap();
431 assert_eq!(assets.len(), 1);
432 assert_eq!(positions.len(), 1);
433
434 let asset = &assets[0];
435 assert_eq!(asset.asset, Ustr::from("USDT"));
436 assert_eq!(
437 asset.cross_wallet_balance,
438 Some(dec!(500.000000000000000001))
439 );
440 assert_eq!(asset.cross_un_pnl, Some(dec!(-2.5)));
441 assert_eq!(asset.maint_margin, Some(dec!(10.5)));
442 assert_eq!(asset.initial_margin, Some(dec!(12.5)));
443 assert_eq!(asset.position_initial_margin, Some(dec!(8.5)));
444 assert_eq!(asset.open_order_initial_margin, Some(dec!(4)));
445 assert_eq!(asset.update_time, Some(1_700_000_002_000));
446
447 let position = &positions[0];
448 assert_eq!(position.symbol, Ustr::from("BTCUSDT"));
449 assert_eq!(position.initial_margin, Some(dec!(12.5)));
450 assert_eq!(position.maint_margin, Some(dec!(10.5)));
451 assert_eq!(position.unrealized_profit, Some(dec!(-1.25)));
452 assert_eq!(position.position_initial_margin, Some(dec!(8.5)));
453 assert_eq!(position.open_order_initial_margin, Some(dec!(4)));
454 assert_eq!(position.leverage, Some(dec!(20)));
455 assert_eq!(position.entry_price, Some(dec!(50000.5)));
456 assert_eq!(position.max_notional, Some(dec!(100000)));
457 assert_eq!(position.bid_notional, Some(dec!(100.5)));
458 assert_eq!(position.ask_notional, Some(dec!(101.5)));
459 assert_eq!(position.position_side, Ustr::from("SHORT"));
460 assert_eq!(position.position_amt, Some(dec!(-0.025)));
461 assert_eq!(position.update_time, Some(1_700_000_002_001));
462 }
463
464 #[rstest]
465 fn test_um_account_v2_decodes_assets_and_positions() {
466 let account: BinancePapiUmAccountV2 = serde_json::from_str(include_str!(
467 "../../../test_data/papi/http_json/um_account_detail_v2_response.json"
468 ))
469 .unwrap();
470 let assets = account.assets.unwrap();
471 let positions = account.positions.unwrap();
472 assert_eq!(assets.len(), 1);
473 assert_eq!(positions.len(), 1);
474
475 let asset = &assets[0];
476 assert_eq!(asset.asset, Ustr::from("USDT"));
477 assert_eq!(asset.cross_wallet_balance, Some(dec!(600.25)));
478 assert_eq!(asset.cross_un_pnl, Some(dec!(2.25)));
479 assert_eq!(asset.maint_margin, Some(dec!(6.5)));
480 assert_eq!(asset.initial_margin, Some(dec!(7.5)));
481 assert_eq!(asset.position_initial_margin, Some(dec!(5.5)));
482 assert_eq!(asset.open_order_initial_margin, Some(dec!(2)));
483 assert_eq!(asset.update_time, Some(1_700_000_003_000));
484
485 let position = &positions[0];
486 assert_eq!(position.symbol, Ustr::from("ETHUSDT"));
487 assert_eq!(position.initial_margin, Some(dec!(7.5)));
488 assert_eq!(position.maint_margin, Some(dec!(6.5)));
489 assert_eq!(position.unrealized_profit, Some(dec!(2.25)));
490 assert_eq!(position.position_side, Ustr::from("LONG"));
491 assert_eq!(position.position_amt, Some(dec!(1.5)));
492 assert_eq!(position.update_time, Some(1_700_000_003_001));
493 assert_eq!(position.notional, Some(dec!(7500.25)));
494 }
495
496 #[rstest]
497 fn test_cm_account_decodes_assets_and_positions() {
498 let account: BinancePapiCmAccount = serde_json::from_str(include_str!(
499 "../../../test_data/papi/http_json/cm_account_detail_response.json"
500 ))
501 .unwrap();
502 let assets = account.assets.unwrap();
503 let positions = account.positions.unwrap();
504 assert_eq!(assets.len(), 1);
505 assert_eq!(positions.len(), 1);
506
507 let asset = &assets[0];
508 assert_eq!(asset.asset, Ustr::from("BTC"));
509 assert_eq!(asset.cross_wallet_balance, Some(dec!(0.050000000000000001)));
510 assert_eq!(asset.cross_un_pnl, Some(dec!(-0.0002)));
511 assert_eq!(asset.maint_margin, Some(dec!(0.0004)));
512 assert_eq!(asset.initial_margin, Some(dec!(0.0005)));
513 assert_eq!(asset.position_initial_margin, Some(dec!(0.0003)));
514 assert_eq!(asset.open_order_initial_margin, Some(dec!(0.0002)));
515 assert_eq!(asset.update_time, Some(1_700_000_004_000));
516
517 let position = &positions[0];
518 assert_eq!(position.symbol, Ustr::from("BTCUSD_261225"));
519 assert_eq!(position.position_amt, Some(dec!(-15)));
520 assert_eq!(position.initial_margin, Some(dec!(0.0005)));
521 assert_eq!(position.maint_margin, Some(dec!(0.0004)));
522 assert_eq!(position.unrealized_profit, Some(dec!(-0.00001)));
523 assert_eq!(position.position_initial_margin, Some(dec!(0.0003)));
524 assert_eq!(position.open_order_initial_margin, Some(dec!(0.0002)));
525 assert_eq!(position.leverage, Some(dec!(5)));
526 assert_eq!(position.position_side, Ustr::from("SHORT"));
527 assert_eq!(position.entry_price, Some(dec!(60000.5)));
528 assert_eq!(position.max_qty, Some(dec!(100)));
529 assert_eq!(position.update_time, Some(1_700_000_004_001));
530 }
531}