Instruments

An instrument represents the specification for a tradable asset, contract, or local synthetic market. Market data, orders, positions, accounting, portfolio calculations, and adapter symbology all refer back to an InstrumentId and its instrument definition.

NautilusTrader exposes the same instrument model to Rust and Python users. Rust examples use nautilus_model; Python examples use nautilus_trader.model.instruments.

Instrument types

Taxonomy

NautilusTrader groups instruments by the market structure they represent:

flowchart TD
    I[Instrument Types]
    I --> Spot
    I --> Derivatives
    I --> Other

    Spot --> Equity
    Spot --> CurrencyPair
    Spot --> Commodity
    Spot --> IndexInstrument
    Spot --> TokenizedAsset

    Derivatives --> Futures
    Derivatives --> Options
    Derivatives --> Swaps
    Derivatives --> Cfd

    Futures --> FuturesContract
    Futures --> FuturesSpread
    Futures --> CryptoFuture
    Futures --> CryptoFuturesSpread

    Options --> OptionContract
    Options --> OptionSpread
    Options --> CryptoOption
    Options --> CryptoOptionSpread
    Options --> BinaryOption

    Swaps --> CryptoPerpetual
    Swaps --> PerpetualContract

    Other --> BettingInstrument
    Other --> SyntheticInstrument

Common fields

Most concrete instruments share the same core shape. Individual type pages list the complete constructor and struct fields for that type.

Symbology

Every instrument has a unique InstrumentId made from the native symbol and venue, separated by a period. For example, Binance Futures represents the Ethereum perpetual contract as:

ETHUSDT-PERP.BINANCE

Native symbols should be unique for a venue, but this is not guaranteed by every exchange. The {symbol}.{venue} pair must be unique inside a Nautilus system.

:::warning The instrument definition must match the market data and venue order semantics. An incorrect instrument can truncate prices or quantities, calculate notional values with the wrong currency, or make a backtest accept prices a live venue would reject. :::

Rust and Python surfaces

Rust users work with the nautilus_model instrument structs and InstrumentAny:

use nautilus_model::instruments::{CurrencyPair, InstrumentAny};

Python users normally work with instrument classes from nautilus_trader.model.instruments:

from nautilus_trader.model.instruments import CurrencyPair

Both surfaces represent the same instrument contract: identity, precision, increments, currencies, limits, margins, fees, metadata, and timestamps.

Loading instruments

Generic test instruments can be instantiated through the TestInstrumentProvider:

from nautilus_trader.test_kit.providers import TestInstrumentProvider

audusd = TestInstrumentProvider.default_fx_ccy("AUD/USD")

Live integration adapters expose InstrumentProvider objects that cache instrument definitions. Use InstrumentProviderConfig(load_all=True) where the integration supports it, or load_ids to load a known set of instruments. Subscriptions and order methods expect matching instruments to already exist in the cache.

Finding instruments

Strategies and actors retrieve instruments from the central cache:

use nautilus_model::identifiers::InstrumentId;

let instrument_id = InstrumentId::from("ETHUSDT-PERP.BINANCE");
let instrument = cache.instrument(&instrument_id);

from nautilus_trader.model import InstrumentId

instrument_id = InstrumentId.from_str("ETHUSDT-PERP.BINANCE")
instrument = self.cache.instrument(instrument_id)

It is also possible to subscribe to one instrument or all instruments for a venue:

self.subscribe_instrument(instrument_id)
self.subscribe_instruments(venue)

When the DataEngine receives an instrument update, it passes the object to the on_instrument() handler.

Precision

Precision defines the number of decimal places allowed for prices and quantities on an instrument. NautilusTrader enforces this strictly because exchanges validate the same constraints, and backtests should not fill orders at prices or sizes that cannot exist in production.

The increment precision must match the declared precision. For example, price_precision=2 pairs with price_increment=Price(0.01, 2).

Use the instrument factory methods when producing order prices and sizes:

instrument = self.cache.instrument(instrument_id)

price = instrument.make_price(0.90500)
quantity = instrument.make_qty(150)

:::warning The RiskEngine does not round values automatically. If you create a Price with 5 decimal places for an instrument that supports 2, the order is denied. Use instrument.make_price() and instrument.make_qty() to round explicitly. :::

Limits, margins, and fees

Venue and adapter definitions can include optional limits:

• max_quantity and min_quantity.
• max_notional and min_notional.
• max_price and min_price.

The MarginAccount uses margin_init, margin_maint, and the taker fee when it calculates initial and maintenance margin. Nautilus uses one fee-rate convention across adapters and backtesting:

• Positive fee rates represent commissions.
• Negative fee rates represent rebates.

For deeper accounting behavior, see Accounting.

Metadata

The info field preserves raw or adapter-specific metadata as a JSON-serializable dictionary. Use it when the venue publishes useful details that do not belong in the unified Nautilus instrument API.

Related guides

• Data covers market data types that reference instruments.
• Orders covers order fields that reference instruments.
• Synthetics covers local formula-derived instruments.
• Python API Reference lists Python constructors and members.