Binance liquidation custom data requires BINANCE venue instr

Error message

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

What it means

For `BinanceFuturesLiquidation` custom-data subscriptions, omitting `instrument_id` metadata is valid (the all-market forceOrder stream is used); supplying one is only valid when its venue is BINANCE. This guard rejects the subscribe before the `force_order_refs` refcounts are touched, so the adapter never opens a liquidation stream keyed to another venue's instrument.

Source

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

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

Solutions

Set the metadata instrument_id to a BINANCE futures instrument, e.g. {'instrument_id': 'ETHUSDT-PERP.BINANCE'}
Or remove the instrument_id key entirely to subscribe to the all-market liquidation stream
Add a venue assertion in your subscription wrapper before calling the Binance client

Example fix

# before
meta = {'instrument_id': 'ETHUSDT-PERP.OKX'}
actor.subscribe_custom_data(DataType(BinanceFuturesLiquidation, metadata=meta))

# after: per-instrument stream on the right venue
meta = {'instrument_id': 'ETHUSDT-PERP.BINANCE'}
actor.subscribe_custom_data(DataType(BinanceFuturesLiquidation, metadata=meta))
# or all-market stream: metadata=None / omit instrument_id

Defensive patterns

Strategy: validation

Validate before calling

def liquidation_metadata(instrument_id=None):
    if instrument_id is None:
        return None  # all-market forceOrder stream: no venue constraint
    if instrument_id.venue.value != 'BINANCE':
        raise ValueError(f'Binance liquidation stream needs a BINANCE instrument, got {instrument_id}')
    return {'instrument_id': str(instrument_id)}

actor.subscribe_custom_data(DataType(BinanceFuturesLiquidation, metadata=liquidation_metadata(instrument_id)))

Type guard

def is_binance_instrument(instrument_id) -> bool:
    return instrument_id.venue.value == 'BINANCE'

Try / catch

try:
    actor.subscribe_custom_data(data_type)
except Exception as e:
    if 'liquidation custom data requires BINANCE venue instrument' in str(e):
        raise ValueError('Fix the instrument_id venue to BINANCE, or drop the key to use the all-market stream') from e
    raise

Prevention

Remember omitting instrument_id is valid and subscribes the all-market liquidation stream
Use one helper to build liquidation metadata for both subscribe and unsubscribe so venues cannot diverge

When it happens

Trigger: `subscribe_custom_data` with data type name `BinanceFuturesLiquidation` and metadata `{'instrument_id': 'ETHUSDT-PERP.OKX'}` — any successfully parsed InstrumentId whose venue differs from BINANCE. Missing or empty instrument_id metadata does NOT trigger this (it selects the all-market stream).

Common situations: Strategy config templating that injects the same instrument string into every venue's client; renaming venues in config and forgetting the liquidation metadata; copy-paste from another adapter's liquidation example.

Related errors

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