nautilus_binance/spot/websocket/streams/
messages.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Binance Spot WebSocket message types.
17//!
18//! The handler emits venue-specific types via [`BinanceSpotWsMessage`].
19//! Data client layers convert these to Nautilus domain types.
20
21use nautilus_network::websocket::WebSocketClient;
22use serde::{Deserialize, Serialize};
23
24use crate::common::enums::BinanceWsMethod;
25pub use crate::spot::sbe::stream::{
26    BestBidAskStreamEvent, DepthDiffStreamEvent, DepthSnapshotStreamEvent, PriceLevel, Trade,
27    TradesStreamEvent,
28};
29
30/// Output message from the Spot WebSocket streams handler.
31///
32/// Contains venue-specific SBE-decoded event types. The data client layer
33/// converts these to Nautilus domain types using parse functions with
34/// instrument context.
35#[derive(Debug, Clone)]
36pub enum BinanceSpotWsMessage {
37    /// Trade stream events (SBE decoded).
38    Trades(TradesStreamEvent),
39    /// Best bid/ask stream event (SBE decoded).
40    BestBidAsk(BestBidAskStreamEvent),
41    /// Depth snapshot stream event (SBE decoded).
42    DepthSnapshot(DepthSnapshotStreamEvent),
43    /// Depth diff stream event (SBE decoded).
44    DepthDiff(DepthDiffStreamEvent),
45    /// Raw binary message (unhandled SBE template).
46    RawBinary(Vec<u8>),
47    /// Raw JSON message (unhandled text frame).
48    RawJson(serde_json::Value),
49    /// Error from the server.
50    Error(BinanceWsErrorMsg),
51    /// WebSocket reconnected.
52    Reconnected,
53}
54
55/// Binance WebSocket error message.
56#[derive(Debug, Clone, Serialize, Deserialize)]
57pub struct BinanceWsErrorMsg {
58    /// Error code from Binance.
59    pub code: i32,
60    /// Error message from Binance.
61    pub msg: String,
62}
63
64/// Commands sent from the outer client to the inner handler.
65///
66/// The handler runs in a dedicated Tokio task and processes these commands
67/// to perform WebSocket operations.
68#[allow(
69    missing_debug_implementations,
70    clippy::large_enum_variant,
71    reason = "Commands are ephemeral and immediately consumed"
72)]
73pub enum BinanceSpotWsStreamsCommand {
74    /// Set the WebSocket client after connection.
75    SetClient(WebSocketClient),
76    /// Disconnect and clean up.
77    Disconnect,
78    /// Subscribe to streams.
79    Subscribe { streams: Vec<String> },
80    /// Unsubscribe from streams.
81    Unsubscribe { streams: Vec<String> },
82}
83
84/// Binance WebSocket subscription request.
85#[derive(Debug, Clone, Serialize)]
86pub struct BinanceWsSubscription {
87    /// Request method.
88    pub method: BinanceWsMethod,
89    /// Stream names to subscribe/unsubscribe.
90    pub params: Vec<String>,
91    /// Request ID for correlation.
92    pub id: u64,
93}
94
95impl BinanceWsSubscription {
96    /// Create a subscribe request.
97    #[must_use]
98    pub fn subscribe(streams: Vec<String>, id: u64) -> Self {
99        Self {
100            method: BinanceWsMethod::Subscribe,
101            params: streams,
102            id,
103        }
104    }
105
106    /// Create an unsubscribe request.
107    #[must_use]
108    pub fn unsubscribe(streams: Vec<String>, id: u64) -> Self {
109        Self {
110            method: BinanceWsMethod::Unsubscribe,
111            params: streams,
112            id,
113        }
114    }
115}
116
117/// Binance WebSocket subscription response.
118#[derive(Debug, Clone, Deserialize)]
119pub struct BinanceWsResponse {
120    /// Result (null on success).
121    pub result: Option<serde_json::Value>,
122    /// Request ID for correlation.
123    pub id: u64,
124}
125
126/// Binance WebSocket error response.
127#[derive(Debug, Clone, Deserialize)]
128pub struct BinanceWsErrorResponse {
129    /// Error code.
130    pub code: i32,
131    /// Error message.
132    pub msg: String,
133    /// Request ID if available.
134    pub id: Option<u64>,
135}
nautilus_binance/spot/websocket/streams/messages.rs

nautilus_binance/spot/websocket/streams/
messages.rs
