Binance liquidation custom data requires BINANCE venue…

Error message

Binance liquidation custom data requires BINANCE venue instrument, received {instrument_id}

What it means

When subscribing to Binance liquidation custom data, if the DataCmd metadata specifies an instrument_id, that instrument must belong to the Binance venue this client serves. Subscribing with an instrument from another venue is rejected.

Solutions

Use an instrument_id whose venue matches the data client's venue (BINANCE futures client gets .BINANCE ids, COIN-M client gets COIN-M ids)
Omit instrument_id metadata if you intend to subscribe to all liquidations for the venue
Audit config to ensure instrument suffix/venue suffix matches the adapter instance

Example fix

// before
metadata = {"instrument_id": "BTCUSD_PERP.BINANCE_COINM"} // on a USDT-M client
// after
metadata = {"instrument_id": "BTCUSDT-PERP.BINANCE"}

Defensive patterns

Strategy: validation

Validate before calling

let id: InstrumentId = /* from metadata */;
assert_eq!(id.venue, Venue::new("BINANCE"), "instrument must match client venue");

Type guard

fn is_venue_binance(id: &InstrumentId, client_venue: &Venue) -> bool {
    &id.venue == client_venue
}

Try / catch

match client.subscribe(cmd).await {
    Err(e) if e.to_string().contains("requires BINANCE venue instrument") => return Err(anyhow::anyhow!("instrument venue mismatch: {e}")),
    other => other,
}

Prevention

Match instrument venue suffix to the data client instance
Omit instrument_id to subscribe to all liquidations
Centralize instrument id construction to avoid suffix drift

When it happens

Trigger: Calling subscribe with a BinanceFuturesLiquidation data type whose metadata instrument_id has venue != self.venue() (e.g. a BINANCE_COINM instrument delivered to a USDT-M futures client).

Common situations: Mixing USDT-M and COIN-M instrument identifiers in configuration, or a generic subscription builder that attaches an instrument_id of the wrong venue.

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/d1a804fe94c8bbe3. Report an issue: GitHub.

Appendix: source

Thrown at crates/adapters/binance/src/futures/data.rs:1898

                        ws.subscribe(vec![stream])
                            .await
                            .context("mark price custom subscription")
                    },
                    "mark price custom subscription",
                );
            }
            return Ok(());
        }

        if data_type != "BinanceFuturesLiquidation" {
            log::warn!("Unsupported custom data subscription: {data_type}");
            return Ok(());
        }

        let instrument_id = Self::custom_liquidation_instrument_id(&cmd.data_type)?;
        if let Some(instrument_id) = instrument_id {
            if instrument_id.venue != self.venue() {
                anyhow::bail!(
                    "Binance liquidation custom data requires BINANCE venue instrument, received {instrument_id}"
                );
            }

            let should_subscribe = {
                let prev = self
                    .force_order_refs
                    .load()
                    .get(&instrument_id)
                    .copied()
                    .unwrap_or(0);
                self.force_order_refs.rcu(|m| {
                    let count = m.entry(instrument_id).or_insert(0);
                    *count += 1;
                });
                prev == 0
            };

View on GitHub (pinned to 18893faf8b)