nautechsystems/nautilus_trader · error · anyhow::Error

Binance US market data requires spot_market_data_mode=Json

Error message

Binance US market data requires spot_market_data_mode=Json

What it means

Binance US market data is only supported via the JSON (REST/polling) feed, not the WebSocket SOR/futures stream modes. validate() throws this error when `us` is true but spot_market_data_mode is not BinanceSpotMarketDataMode::Json.

Solutions

1. Set spot_market_data_mode = BinanceSpotMarketDataMode::Json when us = true.
2. Set us = false if websocket market data mode is required and you have Binance global access.

Example fix

// before
let config = BinanceDataClientConfig { us: true, spot_market_data_mode: BinanceSpotMarketDataMode::WebSocket, .. };
// after
let config = BinanceDataClientConfig { us: true, spot_market_data_mode: BinanceSpotMarketDataMode::Json, .. };

fn us_md_ok(us: bool, mode: BinanceSpotMarketDataMode) -> bool {
    !us || mode == BinanceSpotMarketDataMode::Json
}

When it happens

Trigger: Constructing BinanceDataClientConfig with us=true and spot_market_data_mode set to a non-Json mode (e.g. WebSocket/Sbe), then calling validate().

Common situations: Enabling the lower-latency websocket market data mode for performance and also setting us=true; copying a global-Binance config optimized for websocket data into a Binance US deployment.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• Binance US supports Spot clients only
• Binance US supports the Live environment only
• Allowed token pair -> is not fully pinned by the deployment…
• Binance instrument filter
• Binance load_ids value

AI-assisted analysis of nautechsystems/nautilus_trader@18893faf8b (2026-09-08). Data as JSON: /api/errors/17f976013f88f25c. Report an issue: GitHub.

Appendix: source

Thrown at crates/adapters/binance/src/config.rs:265

    /// Validates Binance data client configuration.
    ///
    /// # Errors
    ///
    /// Returns an error for invalid receive-window, provider, or Binance US settings.
    pub fn validate(&self) -> anyhow::Result<()> {
        validate_recv_window(self.recv_window_ms)?;
        self.instrument_provider.validate(self.product_type)?;

        if self.us {
            anyhow::ensure!(
                self.product_type == BinanceProductType::Spot,
                "Binance US supports Spot clients only"
            );
            anyhow::ensure!(
                self.environment == BinanceEnvironment::Live,
                "Binance US supports the Live environment only"
            );
            anyhow::ensure!(
                self.spot_market_data_mode == BinanceSpotMarketDataMode::Json,
                "Binance US market data requires spot_market_data_mode=Json"
            );
        }

        Ok(())
    }
}

impl ClientConfig for BinanceDataClientConfig {
    fn as_any(&self) -> &dyn Any {
        self
    }
}

/// Configuration for Binance execution client.
///
/// Global execution uses WebSocket API authentication with Ed25519 credentials.

View on GitHub (pinned to 18893faf8b)