nautechsystems/nautilus_trader · error

Invalid instrument type for OKX: {instrument:?}

Error message

Invalid instrument type for OKX: {instrument:?}

What it means

okx_instrument_type maps Nautilus instrument kinds to OKX instrument types (BinaryOption→Events, CurrencyPair→Spot, CryptoPerpetual→Swap, CryptoFuture→Futures, CryptoOption→Option). Any other instrument kind (equities, futures, spreads as instruments, etc.) has no OKX equivalent and is rejected.

Source

Thrown at crates/adapters/okx/src/common/parse.rs:228

        .map_err(|e| serde::de::Error::custom(format!("Invalid VIP level '{s}': {e}")))?;

    Ok(OKXVipLevel::from(level_num))
}

/// Returns the [`OKXInstrumentType`] that corresponds to the supplied
/// [`InstrumentAny`].
///
/// # Errors
///
/// Returns an error if the instrument variant is not supported by OKX.
pub fn okx_instrument_type(instrument: &InstrumentAny) -> anyhow::Result<OKXInstrumentType> {
    match instrument {
        InstrumentAny::BinaryOption(_) => Ok(OKXInstrumentType::Events),
        InstrumentAny::CurrencyPair(_) => Ok(OKXInstrumentType::Spot),
        InstrumentAny::CryptoPerpetual(_) => Ok(OKXInstrumentType::Swap),
        InstrumentAny::CryptoFuture(_) => Ok(OKXInstrumentType::Futures),
        InstrumentAny::CryptoOption(_) => Ok(OKXInstrumentType::Option),
        _ => anyhow::bail!("Invalid instrument type for OKX: {instrument:?}"),
    }
}

/// Returns whether the OKX symbol uses the spread ID format.
#[must_use]
pub fn is_okx_spread_symbol(symbol: &str) -> bool {
    symbol.contains('_')
}

/// Parses `OKXInstrumentType` from an instrument symbol.
///
/// OKX instrument symbol formats:
/// - SPOT: {BASE}-{QUOTE} (e.g., BTC-USDT)
/// - MARGIN: {BASE}-{QUOTE} (same as SPOT, determined by trade mode)
/// - SWAP: {BASE}-{QUOTE}-SWAP (e.g., BTC-USDT-SWAP)
/// - FUTURES: {BASE}-{QUOTE}-{YYMMDD} (e.g., BTC-USDT-250328)
/// - OPTION: {BASE}-{QUOTE}-{YYMMDD}-{STRIKE}-{C/P} (e.g., BTC-USD-250328-50000-C)
/// - EVENTS: venue-defined event contract IDs (e.g., BTC-ABOVE-DAILY-260224-1600-65000)

View on GitHub (pinned to 18893faf8b)

Solutions

1. Ensure only OKX-compatible instruments (spot, perpetual, dated future, option, binary) reach the OKX adapter
2. Check instrument loading/mapping so the correct InstrumentAny variant is constructed for the OKX symbol
3. Handle spreads via the adapter's spread ID path rather than generic instruments

// Rust
fn okx_supported(inst: &InstrumentAny) -> bool {
    matches!(inst,
        InstrumentAny::BinaryOption(_)
        | InstrumentAny::CurrencyPair(_)
        | InstrumentAny::CryptoPerpetual(_)
        | InstrumentAny::CryptoFuture(_)
        | InstrumentAny::CryptoOption(_))
}

fn is_crypto_instrument(inst: &InstrumentAny) -> bool {
    matches!(inst,
        InstrumentAny::CurrencyPair(_) | InstrumentAny::CryptoPerpetual(_)
        | InstrumentAny::CryptoFuture(_) | InstrumentAny::CryptoOption(_)
        | InstrumentAny::BinaryOption(_))
}

When it happens

Trigger: Calling any of the dependent entry points (request_mark_price, request_order_status_reports_scoped, request_fill_reports_scoped, request_position_status_reports_scoped, cancel_all_orders, place_order_with_domain_types) with a non-crypto instrument, e.g. an Equity or Future loaded into an OKX-centric strategy.

Common situations: Mixing instruments from other adapters in one portfolio/strategy; loading the wrong catalog instrument for an OKX symbol; spread instruments hitting the generic path instead of the spread-specific handling.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• instrument update lock poisoned
• option_summary_family_subs mutex poisoned
• Conditional order types must use OKXAlgoOrderType
• Invalid `OrderType` cannot be represented on OKX: {value:?}
• Not a conditional order type: {order_type:?}

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