nautechsystems/nautilus_trader · error

Spot ticker requires a BINANCE instrument

Error message

Spot ticker requires a BINANCE instrument

What it means

The 24-hour ticker custom-data subscription extracted an instrument_id from the command metadata, but its venue is not BINANCE (the venue this Spot data client serves). The client validates that ticker requests target BINANCE instruments before registering the subscription.

Solutions

  1. Pass a BINANCE-spot instrument_id in the ticker data type metadata (use the instrument ID registered with this client).
  2. Verify the instrument was loaded from the Binance adapter's instrument provider.
  3. Fix the strategy/config that constructs the Subscribe command.

Example fix

// before
let data_type = DataType::new("BinanceSpotTicker24h").with_metadata("instrument_id", bybit_instrument_id);
// after
let data_type = DataType::new("BinanceSpotTicker24h").with_metadata("instrument_id", binance_spot_instrument_id); // venue == BINANCE
Defensive patterns

Strategy: validation

Validate before calling

fn ensure_binance_instrument(instrument_id: &InstrumentId, venue: Venue) -> Result<(), String> {
    if instrument_id.venue == venue { Ok(()) } else { Err(format!("{} is not a BINANCE instrument", instrument_id)) }
}

Type guard

fn is_binance_instrument(id: &InstrumentId) -> bool {
    id.venue.as_str() == "BINANCE"
}

Try / catch

if let Err(e) = client.subscribe(cmd) {
    if e.to_string().contains("requires a BINANCE instrument") {
        log::error!("bad instrument metadata: {e}");
    } else { return Err(e.into()); }
}

Prevention

When it happens

Trigger: Subscribing to the Binance spot 24hr ticker custom data type with an instrument_id whose venue is another venue (e.g. BYBIT, ETH perp IDs, or a synthetic venue) supplied via data-type metadata.

Common situations: Copy-pasted instrument IDs across venues; strategy config pointing at the wrong venue; building the custom data type with an instrument from a different adapter.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors


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

Appendix: source

Thrown at crates/adapters/binance/src/spot/data.rs:1789

    fn is_disconnected(&self) -> bool {
        !self.is_connected()
    }

    fn subscribe(&mut self, cmd: SubscribeCustomData) -> anyhow::Result<()> {
        if cmd.data_type.type_name() != "BinanceSpotTicker" {
            log::warn!(
                "Unsupported custom data subscription: {}",
                cmd.data_type.type_name()
            );
            return Ok(());
        }
        anyhow::ensure!(
            self.spot_market_data_mode == BinanceSpotMarketDataMode::Json,
            "Binance Spot 24-hour ticker custom data requires JSON market-data mode"
        );
        let instrument_id = Self::required_instrument_id_metadata(&cmd.data_type)?;
        anyhow::ensure!(
            instrument_id.venue == self.venue(),
            "Spot ticker requires a BINANCE instrument"
        );
        let should_subscribe = {
            let previous = self
                .ticker_refs
                .load()
                .get(&instrument_id)
                .copied()
                .unwrap_or(0);
            self.ticker_refs
                .rcu(|refs| *refs.entry(instrument_id).or_insert(0) += 1);
            previous == 0
        };

        if should_subscribe {
            let ws = self.ws_client.clone();
            let stream = format!("{}@ticker", instrument_id.symbol.as_str().to_lowercase());

View on GitHub (pinned to 18893faf8b)