nautechsystems/nautilus_trader · 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 does not serve the Protobuf market-data stream variant the global exchange offers, so with us=True the spot market data mode must be Json. BinanceDataClientConfig.validate enforces spot_market_data_mode == Json as one of the three US constraints.

Source

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

    /// 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 a4b06ed870)

Solutions

1. Set spot_market_data_mode='JSON' for the binance.us client.
2. Keep Protobuf mode only for us=False (global exchange) configs.
3. Leave the field at its default when targeting binance.us — Json is the default.

Example fix

# before
BinanceDataClientConfig(us=True, spot_market_data_mode=BinanceSpotMarketDataMode.PROTOBUF)

# after
BinanceDataClientConfig(us=True, spot_market_data_mode=BinanceSpotMarketDataMode.JSON)

if config.us:
    assert config.spot_market_data_mode == BinanceSpotMarketDataMode.JSON
config.validate()

When it happens

Trigger: BinanceDataClientConfig(us=True, spot_market_data_mode='PROTOBUF' or 'PROTO') — e.g. a config tuned for max throughput on the global exchange reused unchanged for the US venue.

Common situations: Performance-tuned templates that default spot_market_data_mode to Protobuf; upgrading a config written before the us flag existed; copying a global spot config and only setting us=True.

Related errors

• Binance US supports Spot clients only
• Binance US supports the Live environment only
• Binance v2 does not support instrument filter_callable {filt
• invalid Binance load_ids value {raw:?}: {e}
• unsupported Binance instrument filter {key:?} for {product_t

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