binance_async/
lib.rs

1//#![deny(unstable_features, unused_must_use, unused_mut, unused_imports, unused_import_braces)]
2//! # Binance Async
3//! Unofficial Rust Library for the [Binance API](https://github.com/binance-exchange/binance-official-api-docs)
4//! with Async/Await and ergonomic design.
5//!
6//! This repo is at its early stage, not all requests/websockets are implemented.
7//! However, the related mechanism is already there: adding support for new requests/websocket events
8//! should only require several lines of code. PRs are very welcomed!
9//!
10//! ## Design Goal
11//!
12//! Besides the async/await support, this library aims for being ergonomic by leveraging types. The struct
13//! for REST and Websocket only provides limited functions for you to call: for example, `Binance` is
14//! the struct for REST requests and it only exposes one function: `fn request`. Additionally,
15//! which API endpoint to call and what parameter to carry are all stored in the type information.
16//! for example, creating a new order is
17//! ```rust
18//! let binance = Binance::new();
19//! binance.request(usdm::NewOrderRequest {
20//!     symbol: "ethusdt".into(),
21//!     r#type: OrderType::Limit,
22//!     side: OrderSide::Buy,
23//!
24//!     price: Decimal::from_f64(1500.),
25//!     quantity: Decimal::from_f64(0.004),
26//!     time_in_force: Some(TimeInForce::GTC),
27//!     ..Default::default()
28//! })
29//! ```
30//!
31//! As you can see, `usdm::NewOrderRequest` itself knows which endpoint ("/fapi/v1/order") to send this request to. Moreover,
32//! all the request structs have `Default` implemented, which allows you to express different parameter
33//! combinations without making the code verbose.
34//!
35//! ## Examples
36//!
37//! ### Send a New Order and Cancel it
38//!
39//! ```rust
40//! async fn main() {
41//!    let binance = Binance::with_key_and_secret(&var("BINANCE_KEY")?, &var("BINANCE_SECRET")?);
42//!    let resp = binance
43//!        .request(usdm::NewOrderRequest {
44//!            symbol: "ethusdt".into(),
45//!            r#type: OrderType::Limit,
46//!            side: OrderSide::Buy,
47//!
48//!            price: Decimal::from_f64(1500.),
49//!            quantity: Decimal::from_f64(0.004),
50//!            time_in_force: Some(TimeInForce::GTC),
51//!            ..Default::default()
52//!        })
53//!        .await?;
54//!    println!("{resp:?}");
55//!
56//!    let resp = binance
57//!        .request(usdm::CancelOrderRequest {
58//!            symbol: "ethusdt".into(),
59//!            order_id: Some(resp.order_id),
60//!            ..Default::default()
61//!        })
62//!        .await?;
63//!    println!("{resp:?}");
64//! }
65//! ```
66//!
67//! ### Listening to WS
68//!
69//! ```rust
70//! async fn main() {
71//!     let binance = Binance::with_key(&var("BINANCE_KEY")?);
72//!     let listen_key = binance.request(StartUserDataStreamRequest {}).await?;
73//!     let mut ws: BinanceWebsocket<UsdMWebsocketMessage> = BinanceWebsocket::new(&[
74//!         listen_key.listen_key.as_str(),
75//!         "ethusdt@aggTrade",
76//!         "solusdt@bookTicker",
77//!     ])
78//!     .await?;
79//!
80//!     for _ in 0..10000 {
81//!         let msg = ws.next().await.expect("ws exited")?;
82//!         println!("{msg:?}");
83//!     }
84//! }
85//! ```
86//!
87//! ## Module Structure
88//!
89//! Since this library heavily uses type, there are a plenty of structs defined in each module. The
90//! organization of the structs follow the principle:
91//! 1. REST related types are defined in the `rest` module (mainly request and responses).
92//! 2. Websocket related types are defined in the `websocket` module (mainly websocket events).
93//! 3. Common types like `OrderType` are defined in the `models` module.
94//! 4. Binance distinguishes products like `Spot`, `USDM Futures`, so as our types. Types are further
95//!    stored under the `usdm`, `coinm` and `spot` module under the `rest` and `websocket` module.
96
97mod config;
98mod error;
99mod macros;
100pub mod models;
101mod parser;
102pub mod rest;
103pub mod websocket;
104
105pub use config::Config;
106pub use error::{BinanceError, BinanceResponse, BinanceResponseError};
107pub use rest::Binance;
108pub use websocket::BinanceWebsocket;
binance_async/lib.rs

binance_async/
lib.rs
