nautechsystems/nautilus_trader · error

Binance US supports the Live environment only

Error message

Binance US supports the Live environment only

What it means

With us=True the data client must run against the Live environment, since binance.us provides no testnet/demo endpoints. BinanceDataClientConfig.validate rejects any other BinanceEnvironment (Testnet or Demo) before the client is created.

Source

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

    }
}

impl BinanceDataClientConfig {
    /// 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
    }
}

View on GitHub (pinned to a4b06ed870)

Solutions

1. Set environment='LIVE' (the default) when us=True.
2. Keep testnet development on the global exchange: us=False, environment='TESTNET'.
3. Assert the invariant at config build time: if cfg.us, cfg.environment == 'LIVE'.

Example fix

# before
BinanceDataClientConfig(us=True, environment=BinanceEnvironment.TESTNET)

# after
BinanceDataClientConfig(us=True, environment=BinanceEnvironment.LIVE)

if config.us:
    assert config.environment == BinanceEnvironment.LIVE, \
        'binance.us has no testnet; use us=False for TESTNET'
config.validate()

When it happens

Trigger: BinanceDataClientConfig(us=True, environment='TESTNET' or 'DEMO') — typically a leftover environment toggle from development against the global testnet while the us flag is also enabled.

Common situations: Switching a testnet-developed strategy to binance.us but forgetting to flip environment back to LIVE; templates that hardcode environment='TESTNET'; sharing one config dict between global and US clients.

Related errors

• Binance US supports Spot clients only
• Binance US market data requires spot_market_data_mode=Json
• 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/da3587af8d438e6b. Report an issue: GitHub.