binance-rs Documentation

You can subscribe to public market data streams using the WebSockets struct.

Supported stream types include:

• Trades: Use stream names like !ticker@arr for all symbols or specific symbol tickers.
• Klines (Candlesticks): Use the format {symbol}@kline_{interval} (e.g., ethbtc@kline_1m).
• Depth: Use the format {symbol}@depth@{interval} (e.g., ethbtc@depth@100ms).

To listen to multiple streams simultaneously, use web_socket.connect_multiple_streams(&endpoints) where endpoints is a slice of formatted stream strings.

// Example: Multiple Streams (Depth)
let endpoints = ["ETHBTC", "BNBETH"]
    .map(|symbol| format!("{}@depth@100ms", symbol.to_lowercase()));

let mut web_socket = WebSockets::new(|event: WebsocketEvent| {
    if let WebsocketEvent::DepthOrderBook(depth_order_book) = event {
        println!("{:?}", depth_order_book);
    }
    Ok(())
});

web_socket.connect_multiple_streams(&endpoints).unwrap();

The UserStream struct allows you to listen to private user data (like account updates and order trades) via WebSockets.

Workflow:

1. Initialize UserStream with your API key.
2. Call .start() to receive a listen_key.
3. Use WebSockets::new with a callback to handle WebsocketEvent (e.g., AccountUpdate, OrderTrade).
4. Call web_socket.connect(&listen_key) to begin the stream.
5. Run the event_loop to process incoming events.
6. Use .keep_alive(&listen_key) periodically to prevent the stream from expiring.
7. Call .close(&listen_key) to end the stream.

use binance::api::Binance;
use binance::userstream::UserStream;
use binance::websockets::WebSockets;
use binance::websockets::WebsocketEvent;
use std::sync::atomic::AtomicBool;

fn main() {
    let api_key_user = Some("YOUR_KEY".into());
    let keep_running = AtomicBool::new(true);
    let user_stream: UserStream = Binance::new(api_key_user, None);

    if let Ok(answer) = user_stream.start() {
        let listen_key = answer.listen_key;

        let mut web_socket = WebSockets::new(|event: WebsocketEvent| {
            match event {
                WebsocketEvent::AccountUpdate(account_update) => {
                    for balance in &account_update.balance {
                        println!("Asset: {}, free: {}, locked: {}", balance.asset, balance.free, balance.locked);
                    }
                },
                WebsocketEvent::OrderTrade(trade) => {
                    println!("Symbol: {}, Side: {}, Price: {}, Execution Type: {}", trade.symbol, trade.side, trade.price, trade.execution_type);
                },
                _ => (),
            };
            Ok(())
        });

        web_socket.connect(&listen_key).unwrap();
        if let Err(e) = web_socket.event_loop(&keep_running) {
            println!("Error: {:?}", e);
        }
    }
}

The ExchangeInformation struct provides metadata about the exchange, including timezone, server time, rate limits, and a list of available Symbols. Each Symbol contains critical trading constraints via a filters field.

Common filters include:

• PRICE_FILTER: Defines min_price, max_price, and tick_size.
• LOT_SIZE: Defines min_qty, max_qty, and step_size.
• MIN_NOTIONAL: Defines minimum order value requirements.
• PERCENT_PRICE: Constraints based on a multiplier of the average price.
• MARKET_LOT_SIZE: Similar to LOT_SIZE but specifically for market orders.

Use these filters to validate order parameters (price and quantity) before sending them to the API to avoid rejection.

// Example of the structure of ExchangeInformation
// (Conceptual representation of the data returned)
ExchangeInformation {
    timezone: "UTC",
    server_time: 1626118018407,
    rate_limits: [...],
    symbols: [
        Symbol {
            symbol: "BTCUSDT",
            status: "TRADING",
            base_asset: "BTC",
            quote_asset: "USDT",
            filters: [
                Filters::PriceFilter { min_price: "0.01", max_price: "100000.00", tick_size: "0.01" },
                Filters::LotSize { min_qty: "0.00001", max_qty: "100.0", step_size: "0.00001" }
            ],
            ..
        }
    ],
}

To process incoming messages from a WebSocket connection, you must run the event_loop method. This method continuously reads messages from the socket, handles Pings/Pongs to keep the connection alive, and passes incoming data to your registered handler.

The loop runs as long as the provided AtomicBool is set to true. To stop the loop, set the boolean to false from another thread.

Error Handling

• If the connection is closed by the server, event_loop will return an error.
• If the handler returns an error, the loop will terminate with a bail! error.

use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::Arc;

let running = Arc::new(AtomicBool::new(true));
let r = running.clone();

// Run the event loop in a separate thread
std::thread::spawn(move || {
    ws.event_loop(&r).expect("Event loop failed");
});

// Later, to stop the loop:
running.store(false, Ordering::Relaxed);

The FuturesWebSockets struct provides several methods to establish connections to different Binance Futures markets. You must provide a callback function (handler) during initialization that processes incoming FuturesWebsocketEvent objects.

Connection Methods

• connect(market, subscription): Connects to a single stream using the default API pattern.
• connect_with_config(market, subscription, config): Connects using a custom WebSocket endpoint defined in the provided Config object.
• connect_multiple_streams(market, endpoints): Connects to multiple streams simultaneously using the MultiStream API pattern.

Supported Markets (FuturesMarket)

• USDM: USD-M Futures
• COINM: Coin-M Futures
• Vanilla: Vanilla Futures
• USDMTestnet, COINMTestnet, VanillaTestnet: Testnet versions of the above markets.

// Example: Initializing and connecting to a USD-M stream
let mut ws = FuturesWebSockets::new(|event| {
    match event {
        FuturesWebsocketEvent::Trade(trade) => println!("Trade: {:?}", trade),
        _ => {}
    }
    Ok(())
});

ws.connect(&FuturesMarket::USDM, "btcusdt@trade")?;