Rust edition: this page follows the live DeepWiki structure but treats the current Rust crates as implementation authority. Non-Rust surfaces are identified at their boundary and are not presented as Rust APIs.

Instruments and Market Metadata

Relevant Rust source files

• crates/model/src/instruments/mod.rs
• crates/model/src/identifiers/instrument_id.rs
• crates/model/src/types/price.rs
• crates/model/src/types/quantity.rs

Purpose and Scope

This document covers the instrument specification system in NautilusTrader—how tradable assets and contracts are represented, identified, and accessed. An instrument defines the complete specification for trading a particular asset, including its symbology, precision constraints, fee structure, trading limits, and venue-specific parameters.

Instrument logic is defined by nautilus-model; its Rust constructors and validators enforce precision, currency, identifier, and instrument-specific invariants.

Instrument Type Hierarchy

NautilusTrader models instruments using a hierarchy rooted in the Instrument base class Each concrete instrument type captures asset-class-specific parameters while sharing common identification and precision fields.

Type Classification

Instrument variants cover cash and spot products, derivatives, betting instruments and synthetic products. Each variant retains canonical InstrumentId, venue, currency, precision, increment and asset-specific metadata behind the shared instrument interface.

Sources:

Common Instrument Properties

All instrument types inherit from the Instrument base class and share these fundamental fields:

Field	Type	Purpose
id	InstrumentId	Unique identifier combining symbol and venue
raw_symbol	Symbol	Native symbol as used by the venue
asset_class	AssetClass	Enum (EQUITY, CRYPTOCURRENCY, FX, etc.)
instrument_class	InstrumentClass	Specific type (SPOT, FUTURE, OPTION, etc.)
price_precision	int	Decimal places for prices
size_precision	int	Decimal places for quantities
price_increment	Price	Minimum price movement (tick size)
size_increment	Quantity	Minimum quantity movement
multiplier	Quantity	Contract multiplier (determines tick value)
maker_fee	Decimal	Fee rate for liquidity makers
taker_fee	Decimal	Fee rate for liquidity takers

Sources:

Precision System

The precision system ensures that all prices and quantities conform to the venue's specific constraints. NautilusTrader uses fixed-point arithmetic for these values to avoid floating-point errors.

Implementation and Enforcement

The Instrument class provides helper methods to create valid Price and Quantity objects that are automatically rounded or validated against the instrument's specific increments.

Price and quantity construction validates values against the instrument tick size, step size and precision before producing canonical Price and Quantity values.

• make_price(value): Creates a Price object with the instrument's price_precision
• make_qty(value, round_down): Creates a Quantity object with the instrument's size_precision, optionally rounding down to the nearest size_increment
• price_increment: Used to calculate valid price steps, such as next_bid_price or next_ask_price

Validation logic in the Rust core ensures that precision fields are consistent with their corresponding increments during construction

Sources:

Specialized Instrument Types

Crypto Derivatives

Crypto-specific instruments like CryptoPerpetual and CryptoFuture include fields for settlement and inverse costing.

• Inverse Costing: If is_inverse is True, the quantity is expressed in quote currency units (e.g., USD) while the underlying is the base (e.g., BTC)
• Settlement: Defines the settlement_currency which may differ from the quote currency
• Activation/Expiration: CryptoFuture tracks contract lifecycle via activation_ns and expiration_ns

Betting Instruments

The BettingInstrument supports sports betting markets (e.g., Betfair). It includes extensive metadata such as event_id, competition_name, and selection_handicap It maps to AssetClass.ALTERNATIVE and InstrumentClass.SPORTS_BETTING

Options and Binary Options

• OptionContract: Represents standard options with strike_price, option_kind (CALL/PUT), and expiration_ns
• BinaryOption: Used for prediction markets like Polymarket, featuring an outcome (e.g., "Yes") and description

Spreads

NautilusTrader supports exchange-traded spreads via FuturesSpread and OptionSpread.

• FuturesSpread: Represents a spread between two or more futures legs
• Identification: Spread IDs often use a specific separator (default ___) to delineate legs

Sources:

Market Metadata and Symbology

Instrument Identification

Instruments are uniquely identified by an InstrumentId which is a combination of a Symbol and a Venue

• Symbol: Represents the ticker. Symbols can be "composite" if they contain a period (e.g., "CL.FUT")
• Venue: Represents the exchange or liquidity provider (e.g., "BINANCE", "XCME")

Tick Schemes

Instruments can be associated with a TickScheme, which defines more complex price increment rules than a single static price_increment.

• FixedTickScheme: A single constant tick size.
• TieredTickScheme: Tick sizes that change based on the price level (common in betting exchanges like Betfair)

Instrument Providers

The InstrumentProvider base class manages the lifecycle of loading instruments from venues

• Async Loading: Supports load_all_async and load_ids_async for fetching metadata from remote APIs
• Test fixtures: Rust testkit helpers and adapter fixtures provide standardized instruments for backtests and integration tests.

Provider metadata enters an InstrumentProvider, is validated and normalized, and only then becomes a canonical instrument cached for data, risk and execution consumers.

Sources: