Skip to main content

bitvavo_api_client/
types.rs

1//! Data types shared by the REST and WebSocket clients.
2//!
3//! Monetary amounts and prices are kept as strings to preserve the exact
4//! decimal representation returned by the exchange.
5
6use serde::de::{self, Deserializer, SeqAccess, Visitor};
7use serde::{Deserialize, Serialize};
8use std::fmt;
9
10/// Order side.
11#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
12#[serde(rename_all = "lowercase")]
13pub enum Side {
14    Buy,
15    Sell,
16}
17
18/// Order type.
19#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
20#[serde(rename_all = "camelCase")]
21pub enum OrderType {
22    Limit,
23    Market,
24    StopLoss,
25    StopLossLimit,
26    TakeProfit,
27    TakeProfitLimit,
28}
29
30/// Response of `GET /time`.
31#[derive(Debug, Clone, Deserialize)]
32pub struct ServerTime {
33    pub time: u64,
34}
35
36/// A tradable market.
37#[derive(Debug, Clone, Deserialize)]
38#[serde(rename_all = "camelCase")]
39pub struct Market {
40    pub market: String,
41    pub status: String,
42    pub base: String,
43    pub quote: String,
44    #[serde(default)]
45    pub price_precision: Option<u32>,
46    #[serde(default)]
47    pub min_order_in_base_asset: Option<String>,
48    #[serde(default)]
49    pub min_order_in_quote_asset: Option<String>,
50    #[serde(default)]
51    pub max_order_in_base_asset: Option<String>,
52    #[serde(default)]
53    pub max_order_in_quote_asset: Option<String>,
54    #[serde(default)]
55    pub order_types: Vec<String>,
56}
57
58/// A supported asset.
59#[derive(Debug, Clone, Deserialize)]
60#[serde(rename_all = "camelCase")]
61pub struct Asset {
62    pub symbol: String,
63    pub name: String,
64    #[serde(default)]
65    pub decimals: Option<u32>,
66    #[serde(default)]
67    pub deposit_fee: Option<String>,
68    #[serde(default)]
69    pub deposit_confirmations: Option<u32>,
70    #[serde(default)]
71    pub deposit_status: Option<String>,
72    #[serde(default)]
73    pub withdrawal_fee: Option<String>,
74    #[serde(default)]
75    pub withdrawal_min_amount: Option<String>,
76    #[serde(default)]
77    pub withdrawal_status: Option<String>,
78    #[serde(default)]
79    pub networks: Vec<String>,
80    #[serde(default)]
81    pub message: Option<String>,
82}
83
84/// A single price level as `[price, size]`.
85pub type PriceLevel = [String; 2];
86
87/// Order book snapshot.
88#[derive(Debug, Clone, Deserialize)]
89#[serde(rename_all = "camelCase")]
90pub struct OrderBook {
91    pub market: String,
92    pub nonce: u64,
93    pub bids: Vec<PriceLevel>,
94    pub asks: Vec<PriceLevel>,
95}
96
97/// A public trade.
98#[derive(Debug, Clone, Deserialize)]
99#[serde(rename_all = "camelCase")]
100pub struct PublicTrade {
101    pub id: String,
102    pub timestamp: u64,
103    pub amount: String,
104    pub price: String,
105    pub side: Side,
106}
107
108/// A single OHLCV candle.
109/// The API returns candles as arrays of the form
110/// `[timestamp, open, high, low, close, volume]`.
111#[derive(Debug, Clone)]
112pub struct Candle {
113    pub timestamp: u64,
114    pub open: String,
115    pub high: String,
116    pub low: String,
117    pub close: String,
118    pub volume: String,
119}
120
121impl<'de> Deserialize<'de> for Candle {
122    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
123    where
124        D: Deserializer<'de>,
125    {
126        struct CandleVisitor;
127
128        impl<'de> Visitor<'de> for CandleVisitor {
129            type Value = Candle;
130
131            fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
132                f.write_str("a candle array [timestamp, open, high, low, close, volume]")
133            }
134
135            fn visit_seq<A>(self, mut seq: A) -> Result<Candle, A::Error>
136            where
137                A: SeqAccess<'de>,
138            {
139                let timestamp = seq
140                    .next_element()?
141                    .ok_or_else(|| de::Error::invalid_length(0, &self))?;
142                let open = seq
143                    .next_element()?
144                    .ok_or_else(|| de::Error::invalid_length(1, &self))?;
145                let high = seq
146                    .next_element()?
147                    .ok_or_else(|| de::Error::invalid_length(2, &self))?;
148                let low = seq
149                    .next_element()?
150                    .ok_or_else(|| de::Error::invalid_length(3, &self))?;
151                let close = seq
152                    .next_element()?
153                    .ok_or_else(|| de::Error::invalid_length(4, &self))?;
154                let volume = seq
155                    .next_element()?
156                    .ok_or_else(|| de::Error::invalid_length(5, &self))?;
157                Ok(Candle {
158                    timestamp,
159                    open,
160                    high,
161                    low,
162                    close,
163                    volume,
164                })
165            }
166        }
167
168        deserializer.deserialize_seq(CandleVisitor)
169    }
170}
171
172/// Latest trade price for a market.
173#[derive(Debug, Clone, Deserialize)]
174#[serde(rename_all = "camelCase")]
175pub struct TickerPrice {
176    pub market: String,
177    #[serde(default)]
178    pub price: Option<String>,
179}
180
181/// Best bid and ask for a market.
182#[derive(Debug, Clone, Deserialize)]
183#[serde(rename_all = "camelCase")]
184pub struct TickerBook {
185    pub market: String,
186    #[serde(default)]
187    pub bid: Option<String>,
188    #[serde(default)]
189    pub ask: Option<String>,
190    #[serde(default)]
191    pub bid_size: Option<String>,
192    #[serde(default)]
193    pub ask_size: Option<String>,
194}
195
196/// 24 hour ticker statistics for a market.
197#[derive(Debug, Clone, Deserialize)]
198#[serde(rename_all = "camelCase")]
199pub struct Ticker24h {
200    pub market: String,
201    #[serde(default)]
202    pub open: Option<String>,
203    #[serde(default)]
204    pub high: Option<String>,
205    #[serde(default)]
206    pub low: Option<String>,
207    #[serde(default)]
208    pub last: Option<String>,
209    #[serde(default)]
210    pub volume: Option<String>,
211    #[serde(default)]
212    pub volume_quote: Option<String>,
213    #[serde(default)]
214    pub bid: Option<String>,
215    #[serde(default)]
216    pub bid_size: Option<String>,
217    #[serde(default)]
218    pub ask: Option<String>,
219    #[serde(default)]
220    pub ask_size: Option<String>,
221    #[serde(default)]
222    pub timestamp: Option<u64>,
223    #[serde(default)]
224    pub start_timestamp: Option<u64>,
225    #[serde(default)]
226    pub open_timestamp: Option<u64>,
227    #[serde(default)]
228    pub close_timestamp: Option<u64>,
229}
230
231/// An order as returned by the trading endpoints.
232#[derive(Debug, Clone, Deserialize)]
233#[serde(rename_all = "camelCase")]
234pub struct Order {
235    pub order_id: String,
236    pub market: String,
237    #[serde(default)]
238    pub client_order_id: Option<String>,
239    #[serde(default)]
240    pub created: Option<u64>,
241    #[serde(default)]
242    pub updated: Option<u64>,
243    pub status: String,
244    pub side: Side,
245    pub order_type: OrderType,
246    #[serde(default)]
247    pub amount: Option<String>,
248    #[serde(default)]
249    pub amount_remaining: Option<String>,
250    #[serde(default)]
251    pub amount_quote: Option<String>,
252    #[serde(default)]
253    pub amount_quote_remaining: Option<String>,
254    #[serde(default)]
255    pub price: Option<String>,
256    #[serde(default)]
257    pub on_hold: Option<String>,
258    #[serde(default)]
259    pub on_hold_currency: Option<String>,
260    #[serde(default)]
261    pub filled_amount: Option<String>,
262    #[serde(default)]
263    pub filled_amount_quote: Option<String>,
264    #[serde(default)]
265    pub fee_paid: Option<String>,
266    #[serde(default)]
267    pub fee_currency: Option<String>,
268    #[serde(default)]
269    pub fills: Vec<OrderFill>,
270    #[serde(default)]
271    pub trigger_price: Option<String>,
272    #[serde(default)]
273    pub trigger_amount: Option<String>,
274    #[serde(default)]
275    pub trigger_type: Option<String>,
276    #[serde(default)]
277    pub trigger_reference: Option<String>,
278    #[serde(default)]
279    pub time_in_force: Option<String>,
280    #[serde(default)]
281    pub post_only: Option<bool>,
282    #[serde(default)]
283    pub self_trade_prevention: Option<String>,
284    #[serde(default)]
285    pub visible: Option<bool>,
286    #[serde(default)]
287    pub disable_market_protection: Option<bool>,
288}
289
290/// A fill embedded in an order response.
291#[derive(Debug, Clone, Deserialize)]
292#[serde(rename_all = "camelCase")]
293pub struct OrderFill {
294    pub id: String,
295    pub timestamp: u64,
296    pub amount: String,
297    pub price: String,
298    #[serde(default)]
299    pub taker: Option<bool>,
300    #[serde(default)]
301    pub fee: Option<String>,
302    #[serde(default)]
303    pub fee_currency: Option<String>,
304    #[serde(default)]
305    pub settled: Option<bool>,
306}
307
308/// Response of a cancel order request.
309#[derive(Debug, Clone, Deserialize)]
310#[serde(rename_all = "camelCase")]
311pub struct CanceledOrder {
312    pub order_id: String,
313    #[serde(default)]
314    pub client_order_id: Option<String>,
315}
316
317/// A private trade (an execution of one of your orders).
318#[derive(Debug, Clone, Deserialize)]
319#[serde(rename_all = "camelCase")]
320pub struct Trade {
321    pub id: String,
322    pub order_id: String,
323    #[serde(default)]
324    pub client_order_id: Option<String>,
325    pub timestamp: u64,
326    pub market: String,
327    pub side: Side,
328    pub amount: String,
329    pub price: String,
330    #[serde(default)]
331    pub taker: Option<bool>,
332    #[serde(default)]
333    pub fee: Option<String>,
334    #[serde(default)]
335    pub fee_currency: Option<String>,
336    #[serde(default)]
337    pub settled: Option<bool>,
338}
339
340/// Fee rates that apply to the account.
341#[derive(Debug, Clone, Deserialize)]
342#[serde(rename_all = "camelCase")]
343pub struct FeeRates {
344    #[serde(default)]
345    pub tier: Option<serde_json::Value>,
346    #[serde(default)]
347    pub taker: Option<String>,
348    #[serde(default)]
349    pub maker: Option<String>,
350    #[serde(default)]
351    pub volume: Option<String>,
352}
353
354/// Account information.
355#[derive(Debug, Clone, Deserialize)]
356#[serde(rename_all = "camelCase")]
357pub struct Account {
358    pub fees: FeeRates,
359    #[serde(default)]
360    pub capabilities: Vec<String>,
361}
362
363/// Balance of one asset.
364#[derive(Debug, Clone, Deserialize)]
365#[serde(rename_all = "camelCase")]
366pub struct Balance {
367    pub symbol: String,
368    pub available: String,
369    pub in_order: String,
370}
371
372/// Deposit address or bank details for an asset.
373#[derive(Debug, Clone, Deserialize)]
374#[serde(rename_all = "camelCase")]
375pub struct DepositInfo {
376    #[serde(default)]
377    pub address: Option<String>,
378    #[serde(default)]
379    pub payment_id: Option<String>,
380    #[serde(default)]
381    pub iban: Option<String>,
382    #[serde(default)]
383    pub bic: Option<String>,
384    #[serde(default)]
385    pub description: Option<String>,
386}
387
388/// Response of a withdrawal request.
389#[derive(Debug, Clone, Deserialize)]
390#[serde(rename_all = "camelCase")]
391pub struct WithdrawalResponse {
392    pub success: bool,
393    pub symbol: String,
394    pub amount: String,
395}
396
397/// A historical deposit.
398#[derive(Debug, Clone, Deserialize)]
399#[serde(rename_all = "camelCase")]
400pub struct DepositEntry {
401    pub timestamp: u64,
402    pub symbol: String,
403    pub amount: String,
404    #[serde(default)]
405    pub address: Option<String>,
406    #[serde(default)]
407    pub payment_id: Option<String>,
408    #[serde(default)]
409    pub tx_id: Option<String>,
410    #[serde(default)]
411    pub fee: Option<String>,
412    #[serde(default)]
413    pub status: Option<String>,
414}
415
416/// A historical withdrawal.
417#[derive(Debug, Clone, Deserialize)]
418#[serde(rename_all = "camelCase")]
419pub struct WithdrawalEntry {
420    pub timestamp: u64,
421    pub symbol: String,
422    pub amount: String,
423    #[serde(default)]
424    pub address: Option<String>,
425    #[serde(default)]
426    pub payment_id: Option<String>,
427    #[serde(default)]
428    pub tx_id: Option<String>,
429    #[serde(default)]
430    pub fee: Option<String>,
431    #[serde(default)]
432    pub status: Option<String>,
433}
434
435/// Ticker update pushed on the `ticker` WebSocket channel.
436#[derive(Debug, Clone, Deserialize)]
437#[serde(rename_all = "camelCase")]
438pub struct TickerEvent {
439    pub market: String,
440    #[serde(default)]
441    pub best_bid: Option<String>,
442    #[serde(default)]
443    pub best_bid_size: Option<String>,
444    #[serde(default)]
445    pub best_ask: Option<String>,
446    #[serde(default)]
447    pub best_ask_size: Option<String>,
448    #[serde(default)]
449    pub last_price: Option<String>,
450}
451
452/// Trade pushed on the `trades` WebSocket channel.
453#[derive(Debug, Clone, Deserialize)]
454#[serde(rename_all = "camelCase")]
455pub struct TradeEvent {
456    pub id: String,
457    pub timestamp: u64,
458    pub market: String,
459    pub amount: String,
460    pub price: String,
461    pub side: Side,
462}
463
464/// Candle update pushed on the `candles` WebSocket channel.
465#[derive(Debug, Clone, Deserialize)]
466#[serde(rename_all = "camelCase")]
467pub struct CandleEvent {
468    pub market: String,
469    pub interval: String,
470    pub candle: Vec<Candle>,
471}
472
473/// Order book delta pushed on the `book` WebSocket channel.
474#[derive(Debug, Clone, Deserialize)]
475#[serde(rename_all = "camelCase")]
476pub struct BookEvent {
477    pub market: String,
478    pub nonce: u64,
479    #[serde(default)]
480    pub bids: Vec<PriceLevel>,
481    #[serde(default)]
482    pub asks: Vec<PriceLevel>,
483}
484
485/// Order update pushed on the `account` WebSocket channel.
486#[derive(Debug, Clone, Deserialize)]
487#[serde(rename_all = "camelCase")]
488pub struct OrderEvent {
489    pub order_id: String,
490    pub market: String,
491    #[serde(default)]
492    pub client_order_id: Option<String>,
493    #[serde(default)]
494    pub created: Option<u64>,
495    #[serde(default)]
496    pub updated: Option<u64>,
497    pub status: String,
498    pub side: Side,
499    #[serde(default)]
500    pub order_type: Option<OrderType>,
501    #[serde(default)]
502    pub amount: Option<String>,
503    #[serde(default)]
504    pub amount_remaining: Option<String>,
505    #[serde(default)]
506    pub amount_quote: Option<String>,
507    #[serde(default)]
508    pub amount_quote_remaining: Option<String>,
509    #[serde(default)]
510    pub price: Option<String>,
511    #[serde(default)]
512    pub on_hold: Option<String>,
513    #[serde(default)]
514    pub on_hold_currency: Option<String>,
515    #[serde(default)]
516    pub time_in_force: Option<String>,
517    #[serde(default)]
518    pub post_only: Option<bool>,
519    #[serde(default)]
520    pub self_trade_prevention: Option<String>,
521    #[serde(default)]
522    pub visible: Option<bool>,
523}
524
525/// Fill pushed on the `account` WebSocket channel.
526#[derive(Debug, Clone, Deserialize)]
527#[serde(rename_all = "camelCase")]
528pub struct FillEvent {
529    pub market: String,
530    pub order_id: String,
531    pub fill_id: String,
532    pub timestamp: u64,
533    pub side: Side,
534    pub amount: String,
535    pub price: String,
536    #[serde(default)]
537    pub taker: Option<bool>,
538    #[serde(default)]
539    pub fee: Option<String>,
540    #[serde(default)]
541    pub fee_currency: Option<String>,
542}
543
544#[cfg(test)]
545mod tests {
546    use super::*;
547
548    #[test]
549    fn candle_deserializes_from_array() {
550        let json = r#"[1548051540000, "3416.3", "3416.3", "3396.1", "3396.1", "4.14"]"#;
551        let candle: Candle = serde_json::from_str(json).unwrap();
552        assert_eq!(candle.timestamp, 1548051540000);
553        assert_eq!(candle.open, "3416.3");
554        assert_eq!(candle.volume, "4.14");
555    }
556
557    mod fuzz {
558        use super::*;
559        use crate::tests::arb_json;
560        use proptest::prelude::*;
561
562        proptest! {
563            #[test]
564            fn candle_deserialize_never_panics(value in arb_json()) {
565                let _ = serde_json::from_value::<Candle>(value);
566            }
567
568            #[test]
569            fn candle_deserializes_valid_arrays(
570                timestamp in any::<u64>(),
571                fields in proptest::collection::vec("[0-9]{1,12}(\\.[0-9]{1,8})?", 5),
572            ) {
573                let json = serde_json::json!([
574                    timestamp, fields[0], fields[1], fields[2], fields[3], fields[4]
575                ]);
576                let candle: Candle = serde_json::from_value(json).unwrap();
577                prop_assert_eq!(candle.timestamp, timestamp);
578                prop_assert_eq!(&candle.volume, &fields[4]);
579            }
580        }
581    }
582
583    #[test]
584    fn side_serializes_lowercase() {
585        assert_eq!(serde_json::to_string(&Side::Buy).unwrap(), "\"buy\"");
586        assert_eq!(serde_json::to_string(&Side::Sell).unwrap(), "\"sell\"");
587    }
588
589    #[test]
590    fn order_type_serializes_camel_case() {
591        assert_eq!(
592            serde_json::to_string(&OrderType::StopLossLimit).unwrap(),
593            "\"stopLossLimit\""
594        );
595    }
596}