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:

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.

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

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)

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.