nautilus_binance/common/
consts.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 venue constants and API endpoints.
17
18use std::{num::NonZeroU32, sync::LazyLock};
19
20use nautilus_model::identifiers::Venue;
21use nautilus_network::ratelimiter::quota::Quota;
22use ustr::Ustr;
23
24use super::enums::{BinanceRateLimitInterval, BinanceRateLimitType};
25
26/// The Binance venue identifier string.
27pub const BINANCE: &str = "BINANCE";
28
29/// Static venue instance for Binance.
30pub static BINANCE_VENUE: LazyLock<Venue> = LazyLock::new(|| Venue::new(BINANCE));
31
32/// Binance Link and Trade broker ID for Spot.
33///
34/// <https://developers.binance.com/docs/binance_link/link-and-trade>
35pub const BINANCE_NAUTILUS_SPOT_BROKER_ID: &str = "TD67BGP9";
36
37/// Binance Link and Trade broker ID for Futures.
38///
39/// <https://developers.binance.com/docs/binance_link/link-and-trade>
40pub const BINANCE_NAUTILUS_FUTURES_BROKER_ID: &str = "aHRE4BCj";
41
42/// Binance Spot API base URL (mainnet).
43pub const BINANCE_SPOT_HTTP_URL: &str = "https://api.binance.com";
44
45/// Binance USD-M Futures API base URL (mainnet).
46pub const BINANCE_FUTURES_USD_HTTP_URL: &str = "https://fapi.binance.com";
47
48/// Binance COIN-M Futures API base URL (mainnet).
49pub const BINANCE_FUTURES_COIN_HTTP_URL: &str = "https://dapi.binance.com";
50
51/// Binance European Options API base URL (mainnet).
52pub const BINANCE_OPTIONS_HTTP_URL: &str = "https://eapi.binance.com";
53
54/// Binance Spot API base URL (testnet).
55pub const BINANCE_SPOT_TESTNET_HTTP_URL: &str = "https://testnet.binance.vision";
56
57/// Binance USD-M Futures API base URL (testnet).
58pub const BINANCE_FUTURES_USD_TESTNET_HTTP_URL: &str = "https://demo-fapi.binance.com";
59
60/// Binance COIN-M Futures API base URL (testnet).
61pub const BINANCE_FUTURES_COIN_TESTNET_HTTP_URL: &str = "https://testnet.binancefuture.com";
62
63/// Binance Spot API base URL (demo).
64pub const BINANCE_SPOT_DEMO_HTTP_URL: &str = "https://demo-api.binance.com";
65
66/// Binance USD-M Futures API base URL (demo).
67pub const BINANCE_FUTURES_USD_DEMO_HTTP_URL: &str = "https://demo-fapi.binance.com";
68
69/// Binance COIN-M Futures API base URL (demo, same as COIN-M testnet).
70pub const BINANCE_FUTURES_COIN_DEMO_HTTP_URL: &str = "https://testnet.binancefuture.com";
71
72/// Binance Spot WebSocket base URL (mainnet).
73pub const BINANCE_SPOT_WS_URL: &str = "wss://stream.binance.com:9443/ws";
74
75/// Binance USD-M Futures WebSocket base URL (mainnet).
76pub const BINANCE_FUTURES_USD_WS_URL: &str = "wss://fstream.binance.com/market/ws";
77
78/// Binance USD-M Futures WebSocket public stream URL (mainnet, high-frequency book data).
79pub const BINANCE_FUTURES_USD_WS_PUBLIC_URL: &str = "wss://fstream.binance.com/public/ws";
80
81/// Binance USD-M Futures WebSocket private stream URL (mainnet).
82pub const BINANCE_FUTURES_USD_WS_PRIVATE_URL: &str = "wss://fstream.binance.com/private/ws";
83
84/// Binance COIN-M Futures WebSocket base URL (mainnet).
85pub const BINANCE_FUTURES_COIN_WS_URL: &str = "wss://dstream.binance.com/ws";
86
87/// Binance European Options WebSocket base URL (mainnet).
88pub const BINANCE_OPTIONS_WS_URL: &str = "wss://nbstream.binance.com/eoptions";
89
90/// Binance Spot SBE WebSocket stream URL (mainnet).
91pub const BINANCE_SPOT_SBE_WS_URL: &str = "wss://stream-sbe.binance.com/ws";
92
93/// Binance Spot SBE WebSocket API URL (mainnet).
94pub const BINANCE_SPOT_SBE_WS_API_URL: &str =
95    "wss://ws-api.binance.com:443/ws-api/v3?responseFormat=sbe&sbeSchemaId=3&sbeSchemaVersion=3";
96
97/// Binance USD-M Futures WebSocket Trading API URL (mainnet).
98pub const BINANCE_FUTURES_USD_WS_API_URL: &str = "wss://ws-fapi.binance.com/ws-fapi/v1";
99
100/// Binance USD-M Futures WebSocket Trading API URL (testnet).
101pub const BINANCE_FUTURES_USD_WS_API_TESTNET_URL: &str =
102    "wss://testnet.binancefuture.com/ws-fapi/v1";
103
104/// Binance Spot SBE WebSocket API URL (testnet).
105pub const BINANCE_SPOT_SBE_WS_API_TESTNET_URL: &str = "wss://ws-api.testnet.binance.vision/ws-api/v3?responseFormat=sbe&sbeSchemaId=3&sbeSchemaVersion=3";
106
107/// Binance Spot SBE WebSocket API URL (demo).
108pub const BINANCE_SPOT_SBE_WS_API_DEMO_URL: &str =
109    "wss://demo-ws-api.binance.com/ws-api/v3?responseFormat=sbe&sbeSchemaId=3&sbeSchemaVersion=3";
110
111/// Binance Spot WebSocket base URL (testnet).
112pub const BINANCE_SPOT_TESTNET_WS_URL: &str = "wss://stream.testnet.binance.vision/ws";
113
114/// Binance Spot WebSocket base URL (demo).
115pub const BINANCE_SPOT_DEMO_WS_URL: &str = "wss://demo-stream.binance.com/ws";
116
117/// Binance USD-M Futures WebSocket base URL (testnet).
118pub const BINANCE_FUTURES_USD_TESTNET_WS_URL: &str = "wss://fstream.binancefuture.com/ws";
119
120/// Binance COIN-M Futures WebSocket base URL (testnet).
121pub const BINANCE_FUTURES_COIN_TESTNET_WS_URL: &str = "wss://dstream.binancefuture.com/ws";
122
123/// HTTP header name for the Binance API key.
124pub const BINANCE_API_KEY_HEADER: &str = "X-MBX-APIKEY";
125
126/// Binance Spot API version path.
127pub const BINANCE_SPOT_API_PATH: &str = "/api/v3";
128
129/// Binance USD-M Futures API version path.
130pub const BINANCE_FAPI_PATH: &str = "/fapi/v1";
131
132/// Binance COIN-M Futures API version path.
133pub const BINANCE_DAPI_PATH: &str = "/dapi/v1";
134
135/// Binance European Options API version path.
136pub const BINANCE_EAPI_PATH: &str = "/eapi/v1";
137
138/// Describes a static rate limit quota for a product type.
139#[derive(Clone, Copy, Debug)]
140pub struct BinanceRateLimitQuota {
141    /// Rate limit type.
142    pub rate_limit_type: BinanceRateLimitType,
143    /// Time interval unit.
144    pub interval: BinanceRateLimitInterval,
145    /// Number of intervals.
146    pub interval_num: u32,
147    /// Maximum allowed requests for the interval.
148    pub limit: u32,
149}
150
151/// Spot & margin REST limits (default IP weights).
152///
153/// References:
154/// - <https://developers.binance.com/docs/binance-spot-api-docs/limits>
155pub const BINANCE_SPOT_RATE_LIMITS: &[BinanceRateLimitQuota] = &[
156    BinanceRateLimitQuota {
157        rate_limit_type: BinanceRateLimitType::RequestWeight,
158        interval: BinanceRateLimitInterval::Minute,
159        interval_num: 1,
160        limit: 1_200,
161    },
162    BinanceRateLimitQuota {
163        rate_limit_type: BinanceRateLimitType::Orders,
164        interval: BinanceRateLimitInterval::Second,
165        interval_num: 1,
166        limit: 10,
167    },
168    BinanceRateLimitQuota {
169        rate_limit_type: BinanceRateLimitType::Orders,
170        interval: BinanceRateLimitInterval::Day,
171        interval_num: 1,
172        limit: 100_000,
173    },
174];
175
176/// USD-M Futures REST limits (default IP weights).
177///
178/// References:
179/// - <https://developers.binance.com/docs/derivatives/usds-margined-futures/general-info#limits>
180pub const BINANCE_FAPI_RATE_LIMITS: &[BinanceRateLimitQuota] = &[
181    BinanceRateLimitQuota {
182        rate_limit_type: BinanceRateLimitType::RequestWeight,
183        interval: BinanceRateLimitInterval::Minute,
184        interval_num: 1,
185        limit: 2_400,
186    },
187    BinanceRateLimitQuota {
188        rate_limit_type: BinanceRateLimitType::Orders,
189        interval: BinanceRateLimitInterval::Second,
190        interval_num: 1,
191        limit: 50,
192    },
193    BinanceRateLimitQuota {
194        rate_limit_type: BinanceRateLimitType::Orders,
195        interval: BinanceRateLimitInterval::Minute,
196        interval_num: 1,
197        limit: 1_200,
198    },
199];
200
201/// COIN-M Futures REST limits (default IP weights).
202///
203/// References:
204/// - <https://developers.binance.com/docs/derivatives/coin-margined-futures/general-info#limits>
205pub const BINANCE_DAPI_RATE_LIMITS: &[BinanceRateLimitQuota] = &[
206    BinanceRateLimitQuota {
207        rate_limit_type: BinanceRateLimitType::RequestWeight,
208        interval: BinanceRateLimitInterval::Minute,
209        interval_num: 1,
210        limit: 1_200,
211    },
212    BinanceRateLimitQuota {
213        rate_limit_type: BinanceRateLimitType::Orders,
214        interval: BinanceRateLimitInterval::Second,
215        interval_num: 1,
216        limit: 20,
217    },
218    BinanceRateLimitQuota {
219        rate_limit_type: BinanceRateLimitType::Orders,
220        interval: BinanceRateLimitInterval::Minute,
221        interval_num: 1,
222        limit: 1_200,
223    },
224];
225
226/// Options REST limits (default IP weights).
227///
228/// References:
229/// - <https://developers.binance.com/docs/derivatives/european-options/general-info#limits>
230pub const BINANCE_EAPI_RATE_LIMITS: &[BinanceRateLimitQuota] = &[
231    BinanceRateLimitQuota {
232        rate_limit_type: BinanceRateLimitType::RequestWeight,
233        interval: BinanceRateLimitInterval::Minute,
234        interval_num: 1,
235        limit: 3_000,
236    },
237    BinanceRateLimitQuota {
238        rate_limit_type: BinanceRateLimitType::Orders,
239        interval: BinanceRateLimitInterval::Second,
240        interval_num: 1,
241        limit: 5,
242    },
243    BinanceRateLimitQuota {
244        rate_limit_type: BinanceRateLimitType::Orders,
245        interval: BinanceRateLimitInterval::Minute,
246        interval_num: 1,
247        limit: 200,
248    },
249];
250
251/// WebSocket subscription rate limit: 5 messages per second.
252///
253/// Binance limits incoming WebSocket messages (subscribe/unsubscribe) to 5 per second.
254pub static BINANCE_WS_SUBSCRIPTION_QUOTA: LazyLock<Quota> = LazyLock::new(|| {
255    Quota::per_second(NonZeroU32::new(5).expect("non-zero")).expect("valid constant")
256});
257
258/// WebSocket connection rate limit: 1 per second (conservative).
259///
260/// Binance limits connections to 300 per 5 minutes per IP. This conservative quota
261/// of 1 per second helps avoid hitting the connection limit during reconnection storms.
262pub static BINANCE_WS_CONNECTION_QUOTA: LazyLock<Quota> = LazyLock::new(|| {
263    Quota::per_second(NonZeroU32::new(1).expect("non-zero")).expect("valid constant")
264});
265
266/// Pre-interned rate limit key for WebSocket subscription operations.
267pub static BINANCE_RATE_LIMIT_KEY_SUBSCRIPTION: LazyLock<[Ustr; 1]> =
268    LazyLock::new(|| [Ustr::from("subscription")]);
269
270/// Binance error code for GTX (post-only) order rejection.
271///
272/// Returned when a GTX order would immediately match as taker.
273pub const BINANCE_GTX_ORDER_REJECT_CODE: i64 = -5022;
274
275/// Binance error code for new order rejected.
276///
277/// For spot LIMIT_MAKER orders, this code is returned with the message
278/// "Order would immediately match and take." to indicate a post-only rejection.
279pub const BINANCE_NEW_ORDER_REJECTED_CODE: i64 = -2010;
280
281/// Binance Spot LIMIT_MAKER rejection message.
282///
283/// This message is specific to post-only (LIMIT_MAKER) orders that would match immediately.
284pub const BINANCE_SPOT_POST_ONLY_REJECT_MSG: &str = "Order would immediately match and take.";
285
286/// Valid order book depth levels for Binance.
287pub const BINANCE_BOOK_DEPTHS: [u32; 7] = [5, 10, 20, 50, 100, 500, 1000];
nautilus_binance/common/consts.rs

nautilus_binance/common/
consts.rs
