nautechsystems/nautilus_trader · error · anyhow::Error

Unsupported instrument symbol format for Hyperliquid: {symbo

Error message

Unsupported instrument symbol format for Hyperliquid: {symbol} (expected -PERP, -SPOT, or HIP-4 outcome `{{N}}-{{YES|NO}}-OUTCOME`)

What it means

validate_order_for_hyperliquid() rejects orders whose instrument symbol cannot be parsed into a Hyperliquid product type. Hyperliquid symbols must be a perpetual (-PERP), spot (-SPOT), or a HIP-4 outcome market of the form {N}-{YES|NO}-OUTCOME; anything else fails symbol parsing and produces this message.

Source

Thrown at crates/adapters/hyperliquid/src/execution.rs:2699

        }
    });

    pairs.into_iter().unzip()
}

/// Validates that an order is acceptable for submission to Hyperliquid.
///
/// Checks symbol format, order type support, and HIP-4-specific restrictions
/// (no reduce-only, no trigger order types on outcome side tokens).
///
/// # Errors
///
/// Returns an error describing the first validation failure encountered.
pub fn validate_order_for_hyperliquid(order: &OrderAny) -> anyhow::Result<()> {
    let instrument_id = order.instrument_id();
    let symbol = instrument_id.symbol.as_str();
    let product_type = HyperliquidProductType::from_symbol(symbol).map_err(|_| {
        anyhow::anyhow!(
            "Unsupported instrument symbol format for Hyperliquid: {symbol} \
             (expected -PERP, -SPOT, or HIP-4 outcome `{{N}}-{{YES|NO}}-OUTCOME`)"
        )
    })?;

    match order.order_type() {
        OrderType::Market
        | OrderType::Limit
        | OrderType::StopMarket
        | OrderType::StopLimit
        | OrderType::MarketIfTouched
        | OrderType::LimitIfTouched => {}
        _ => anyhow::bail!(
            "Unsupported order type for Hyperliquid: {:?}",
            order.order_type()
        ),
    }

View on GitHub (pinned to 18893faf8b)

Solutions

1. Rename the instrument to a supported format: e.g. BTC-PERP, ETH-SPOT, or {N}-{YES|NO}-OUTCOME for HIP-4 outcome markets
2. Verify the symbol exists on Hyperliquid and matches its exact venue naming
3. Check how the instrument was loaded/configured and correct the venue-specific symbol mapping
4. If trading HIP-3 builder-deployed markets, confirm the adapter version supports that symbol format

Example fix

// before
order.instrument_id = InstrumentId::from("BTC-USDT-PERP.HYPERLIQUID");
// after
order.instrument_id = InstrumentId::from("BTC-PERP.HYPERLIQUID");

fn is_valid_hl_symbol(sym: &str) -> bool {
    sym.ends_with("-PERP") || sym.ends_with("-SPOT")
        || (regex::Regex::new(r"^\d+-(YES|NO)-OUTCOME$").unwrap().is_match(sym))
}
// call before building the order: assert!(is_valid_hl_symbol(order.instrument_id().symbol.as_str()));

fn as_hyperliquid_symbol(sym: &str) -> Option<&str> {
    if sym.ends_with("-PERP") || sym.ends_with("-SPOT")
        || regex::Regex::new(r"^\d+-(YES|NO)-OUTCOME$").unwrap().is_match(sym) { Some(sym) } else { None }
}

if let Err(e) = client.submit_order(order).await { if e.to_string().contains("Unsupported instrument symbol") { fix_symbol_mapping(&e); } }

When it happens

Trigger: Submitting an order whose instrument_id.symbol does not match any supported Hyperliquid format — e.g. 'BTC', 'BTC-USDT-PERP', 'ETH/USD', or a malformed HIP-3/HIP-4 builder-deployed symbol.

Common situations: Configuring instruments using Binance/other-venue naming conventions instead of Hyperliquid's; typos in symbol suffixes; using builder-deployed HIP-3 markets whose symbol format this adapter does not recognize.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• {FAILED}: {e}
• {FAILED}: {e}
• {FAILED}: {e}
• {FAILED}: {e}
• {FAILED}: {e}

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