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.

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 a Nautilus symbol and venue, separated by a period. The separate raw_symbol field preserves the venue's native symbol. 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 Nautilus {symbol}.{venue} pair must be unique inside a 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:

from nautilus_trader.model 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.testkit.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. Order submission requires the matching instrument definition to exist in the central 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

For order validation, price_precision and size_precision set the maximum number of decimal places that the RiskEngine accepts. price_increment and size_increment record the corresponding minimum steps.

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

Use the instrument factory methods to round values to the configured precision:

instrument = self.cache.instrument(instrument_id)

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

These methods round to the corresponding increment precision, which instrument construction requires to match the declared precision. They do not ensure that the result is a multiple of an increment such as 0.25.

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.

Margin models use margin_init and margin_maint to calculate initial and maintenance margin. Maker and taker fee rates apply to commission calculations. 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.