nautechsystems/nautilus_trader · error · anyhow::Error

Binance Futures custom data requires BINANCE venue instrumen

Error message

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

What it means

`BinanceFuturesOpenInterest` and `BinanceFuturesOpenInterestHist` custom-data requests first parse the `instrument_id` metadata, then require its venue to equal the data client's venue (BINANCE). A wrong-venue instrument id is rejected before the period check (for Hist) and before the spawned HTTP fetch, so no request reaches Binance.

Source

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

                        }
                    }
                    Err(e) => log::error!("BinanceBar request failed for {bar_type}: {e:?}"),
                }
            });
            return Ok(());
        }

        if data_type_name != "BinanceFuturesOpenInterest"
            && data_type_name != "BinanceFuturesOpenInterestHist"
        {
            log::warn!("Unsupported custom data request: {data_type_name}");
            return Ok(());
        }

        let instrument_id = Self::required_instrument_id_metadata(&data_type)?;

        if instrument_id.venue != self.venue() {
            anyhow::bail!(
                "Binance Futures custom data requires BINANCE venue instrument, received {instrument_id}"
            );
        }

        let period = if data_type_name == "BinanceFuturesOpenInterestHist" {
            Some(Self::required_period_metadata(&data_type)?)
        } else {
            None
        };

        let http = self.http_client.clone();
        let sender = self.data_sender.clone();
        let request_id = request.request_id;
        let client_id = request.client_id;
        let params = request.params;
        let clock = self.clock;
        let venue = self.venue();
        let limit = request.limit.map(|n| n.get() as u32);

View on GitHub (pinned to a4b06ed870)

Solutions

  1. Use a BINANCE futures instrument id, e.g. {'instrument_id': 'BTCUSDT-PERP.BINANCE', 'period': '1h'} for the Hist variant
  2. Filter your instrument universe by venue before issuing open-interest requests to this client

Example fix

# before
meta = {'instrument_id': 'BTCUSDT-PERP.BYBIT', 'period': '1h'}
actor.request_custom_data(DataType(BinanceFuturesOpenInterestHist, meta), ...)

# after
meta = {'instrument_id': 'BTCUSDT-PERP.BINANCE', 'period': '1h'}
actor.request_custom_data(DataType(BinanceFuturesOpenInterestHist, meta), ...)
Defensive patterns

Strategy: validation

Validate before calling

def build_oi_request_metadata(data_type_name: str, instrument_id) -> dict:
    if instrument_id.venue.value != 'BINANCE':
        raise ValueError(f'{data_type_name} requests need a BINANCE instrument, got {instrument_id}')
    meta = {'instrument_id': str(instrument_id)}
    if data_type_name == 'BinanceFuturesOpenInterestHist':
        meta['period'] = '1h'  # required; one of 5m..1d
    return meta

Type guard

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

Try / catch

try:
    actor.request_custom_data(data_type, ...)
except Exception as e:
    if 'custom data requires BINANCE venue instrument' in str(e):
        raise ValueError('Filter your instrument universe by venue before sending open-interest requests to the Binance client') from e
    raise

Prevention

When it happens

Trigger: `request_data` with data type name `BinanceFuturesOpenInterest` or `BinanceFuturesOpenInterestHist` and metadata `{'instrument_id': 'BTC-PERP.BYBIT', ...}` — any parsed InstrumentId whose venue is not BINANCE. Missing/empty instrument_id metadata fails earlier with the separate 'custom data request requires `instrument_id` metadata' error.

Common situations: Sharing one metadata dict across venue clients; typo'd venue suffix in config; multi-venue research code requesting open interest for every instrument in a watchlist without filtering by venue.

Related errors

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