Instruments<a class="headerlink" href="#module-nautilus_trader.model.instruments" title="Link to this heading">¶

settlement_currency¶

The settlement currency for the contract.

Returns:: Currency

static to_dict(CryptoFuture obj) → dict[str, object]¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

underlying¶

The underlying asset for the contract.

Returns:: Currency

class CryptoOption¶

Bases: Instrument

CryptoOption(InstrumentId instrument_id, Symbol raw_symbol, Currency underlying, Currency quote_currency, Currency settlement_currency, bool is_inverse, OptionKind option_kind, Price strike_price, uint64_t activation_ns, uint64_t expiration_ns, int price_precision, int size_precision, Price price_increment, Quantity size_increment, uint64_t ts_event, uint64_t ts_init, Quantity multiplier=Quantity.from_int_c(1), Quantity lot_size=Quantity.from_int_c(1), Quantity max_quantity: Quantity | None = None, Quantity min_quantity: Quantity | None = None, Money max_notional: Money | None = None, Money min_notional: Money | None = None, Price max_price: Price | None = None, Price min_price: Price | None = None, margin_init: Decimal | None = None, margin_maint: Decimal | None = None, maker_fee: Decimal | None = None, taker_fee: Decimal | None = None, str tick_scheme_name=None, dict info=None) -> None

Represents an option instrument with crypto assets as underlying and for settlement.

Parameters:

instrument_id (InstrumentId) – The instrument ID.
raw_symbol (Symbol) – The raw/local/native symbol for the instrument, assigned by the venue.
underlying (Currency) – The underlying asset.
quote_currency (Currency) – The contract quote currency.
settlement_currency (Currency) – The settlement currency.
is_inverse (bool) – If the instrument costing is inverse (quantity expressed in quote currency units).
option_kind (OptionKind) – The kind of option (PUT | CALL).
strike_price (Price) – The option strike price.
activation_ns (uint64_t) – UNIX timestamp (nanoseconds) for contract activation.
expiration_ns (uint64_t) – UNIX timestamp (nanoseconds) for contract expiration.
price_precision (int) – The price decimal precision.
size_precision (int) – The trading size decimal precision.
price_increment (Price) – The minimum price increment (tick size).
size_increment (Quantity) – The minimum size increment.
ts_event (uint64_t) – UNIX timestamp (nanoseconds) when the data event occurred.
ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the data object was initialized.
multiplier (Quantity, default 1) – The contract multiplier.
lot_size (Quantity, default 1) – The rounded lot unit size (standard/board).
max_quantity (Quantity, optional) – The maximum allowable order quantity.
min_quantity (Quantity, optional) – The minimum allowable order quantity.
max_notional (Money, optional) – The maximum allowable order notional value.
min_notional (Money, optional) – The minimum allowable order notional value.
max_price (Price, optional) – The maximum allowable quoted price.
min_price (Price, optional) – The minimum allowable quoted price.
margin_init (Decimal, optional) – The initial (order) margin requirement in percentage of order value.
margin_maint (Decimal, optional) – The maintenance (position) margin in percentage of position value.
maker_fee (Decimal, optional) – The fee rate for liquidity makers as a percentage of order value.
taker_fee (Decimal, optional) – The fee rate for liquidity takers as a percentage of order value.
tick_scheme_name (str, optional) – The name of the tick scheme.
info (dict[str, object], optional) – The additional instrument information.

Raises:

ValueError – If price_precision is negative (< 0).
ValueError – If size_precision is negative (< 0).
ValueError – If price_increment is not positive (> 0).
ValueError – If size_increment is not positive (> 0).
ValueError – If lot size is not positive (> 0).
ValueError – If max_quantity is not positive (> 0).
ValueError – If min_quantity is negative (< 0).
ValueError – If max_notional is not positive (> 0).
ValueError – If min_notional is negative (< 0).
ValueError – If max_price is not positive (> 0).
ValueError – If min_price is negative (< 0).
ValueError – If margin_init is negative (< 0).
ValueError – If margin_maint is negative (< 0).

activation_ns¶

UNIX timestamp (nanoseconds) for contract activation.

Returns:: unit64_t

activation_utc¶

pd.Timestamp

Return the contract activation timestamp (UTC).

Returns:: tz-aware UTC.
Return type:: pd.Timestamp
Type:: CryptoOption.activation_utc

expiration_ns¶

UNIX timestamp (nanoseconds) for contract expiration.

Returns:: unit64_t

expiration_utc¶

pd.Timestamp

Return the contract expiration timestamp (UTC).

Returns:: tz-aware UTC.
Return type:: pd.Timestamp
Type:: CryptoOption.expiration_utc

static from_dict(dict values) → CryptoOption¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: CryptoOption

static from_pyo3(pyo3_instrument) → CryptoOption¶

Return legacy Cython option contract instrument converted from the given pyo3 Rust object.

Parameters:: pyo3_instrument (nautilus_pyo3.CryptoOption) – The pyo3 Rust option contract instrument to convert from.
Return type:: CryptoOption

get_base_currency(self) → Currency¶

Return the instruments base currency (underlying).

Return type:: Currency

get_cost_currency(self) → Currency¶

Return the currency used for PnL calculations for the instrument.

Standard linear instruments = quote_currency
Inverse instruments = underlying (base currency)

Return type:: Currency

get_settlement_currency(self) → Currency¶

Return the currency used to settle a trade of the instrument.

Return type:: Currency

notional_value(self, Quantity quantity, Price price, bool use_quote_for_inverse=False, Currency target_currency=None, Price conversion_price=None) → Money¶

Calculate the notional value.

Result will be in quote currency for standard instruments, or underlying currency for inverse instruments.

Parameters:

quantity (Quantity) – The total quantity.
price (Price) – The price for the calculation.
use_quote_for_inverse (bool) – For inverse instruments only: if True, treats the quantity as already representing notional value in quote currency and returns it directly without calculation. This is useful when quantity already represents a USD value that doesn’t need conversion (e.g., for display purposes). Has no effect on linear instruments.
target_currency (Currency, optional) – The target currency for conversion.
conversion_price (Price, optional) – The conversion price to the target currency.

Return type:

option_kind¶

The option kind (PUT | CALL) for the contract.

Returns:: OptionKind

settlement_currency¶

The settlement currency for the instrument.

Returns:: Currency

strike_price¶

The strike price for the contract.

Returns:: Price

static to_dict(CryptoOption obj) → dict[str, object]¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

underlying¶

The underlying asset for the contract.

Returns:: str

class CryptoPerpetual¶

Bases: Instrument

CryptoPerpetual(InstrumentId instrument_id, Symbol raw_symbol, Currency base_currency, Currency quote_currency, Currency settlement_currency, bool is_inverse, int price_precision, int size_precision, Price price_increment, Quantity size_increment, uint64_t ts_event, uint64_t ts_init, multiplier=Quantity.from_int_c(1), lot_size=Quantity.from_int_c(1), Quantity max_quantity: Quantity | None = None, Quantity min_quantity: Quantity | None = None, Money max_notional: Money | None = None, Money min_notional: Money | None = None, Price max_price: Price | None = None, Price min_price: Price | None = None, margin_init: Decimal | None = None, margin_maint: Decimal | None = None, maker_fee: Decimal | None = None, taker_fee: Decimal | None = None, str tick_scheme_name=None, dict info=None) -> None

Represents a crypto perpetual futures contract instrument (a.k.a. perpetual swap).

Parameters:

instrument_id (InstrumentId) – The instrument ID for the instrument.
raw_symbol (Symbol) – The raw/local/native symbol for the instrument, assigned by the venue.
base_currency (Currency, optional) – The base currency.
quote_currency (Currency) – The quote currency.
settlement_currency (Currency) – The settlement currency.
is_inverse (bool) – If the instrument costing is inverse (quantity expressed in quote currency units).
price_precision (int) – The price decimal precision.
size_precision (int) – The trading size decimal precision.
price_increment (Price) – The minimum price increment (tick size).
size_increment (Quantity) – The minimum size increment.
ts_event (uint64_t) – UNIX timestamp (nanoseconds) when the data event occurred.
ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the data object was initialized.
multiplier (Quantity, default 1) – The contract multiplier.
lot_size (Quantity, default 1) – The rounded lot unit size (standard/board).
max_quantity (Quantity, optional) – The maximum allowable order quantity.
min_quantity (Quantity, optional) – The minimum allowable order quantity.
max_notional (Money, optional) – The maximum allowable order notional value.
min_notional (Money, optional) – The minimum allowable order notional value.
max_price (Price, optional) – The maximum allowable quoted price.
min_price (Price, optional) – The minimum allowable quoted price.
margin_init (Decimal, optional) – The initial (order) margin requirement in percentage of order value.
margin_maint (Decimal, optional) – The maintenance (position) margin in percentage of position value.
maker_fee (Decimal, optional) – The fee rate for liquidity makers as a percentage of order value.
taker_fee (Decimal, optional) – The fee rate for liquidity takers as a percentage of order value.
tick_scheme_name (str, optional) – The name of the tick scheme.
info (dict[str, object], optional) – The additional instrument information.

Raises:

ValueError – If price_precision is negative (< 0).
ValueError – If size_precision is negative (< 0).
ValueError – If price_increment is not positive (> 0).
ValueError – If size_increment is not positive (> 0).
ValueError – If price_precision is not equal to price_increment.precision.
ValueError – If size_increment is not equal to size_increment.precision.
ValueError – If multiplier is not positive (> 0).
ValueError – If max_quantity is not positive (> 0).
ValueError – If min_quantity is negative (< 0).
ValueError – If max_notional is not positive (> 0).
ValueError – If min_notional is negative (< 0).
ValueError – If max_price is not positive (> 0).
ValueError – If min_price is negative (< 0).
ValueError – If margin_init is negative (< 0).
ValueError – If margin_maint is negative (< 0).

base_currency¶

The base currency for the instrument.

Returns:: Currency

static from_dict(dict values) → CryptoPerpetual¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: CryptoPerpetual

static from_pyo3(pyo3_instrument)¶

get_base_currency(self) → Currency¶

Return the instruments base currency.

Return type:: Currency

get_cost_currency(self) → Currency¶

Return the currency used for PnL calculations for the instrument.

Standard linear instruments = quote_currency
Inverse instruments = base_currency
Quanto instruments = settlement_currency

Return type:: Currency

get_settlement_currency(self) → Currency¶

Return the currency used to settle a trade of the instrument.

Return type:: Currency

is_quanto¶

If the instrument is quanto.

Returns:: bool

notional_value(self, Quantity quantity, Price price, bool use_quote_for_inverse=False, Currency target_currency=None, Price conversion_price=None) → Money¶

Calculate the notional value.

Result will be in quote currency for standard instruments, base currency for inverse instruments, or settlement currency for quanto instruments.

Parameters:

quantity (Quantity) – The total quantity.
price (Price) – The price for the calculation.
use_quote_for_inverse (bool) – For inverse instruments only: if True, treats the quantity as already representing notional value in quote currency and returns it directly without calculation. This is useful when quantity already represents a USD value that doesn’t need conversion (e.g., for display purposes). Has no effect on linear or quanto instruments.
target_currency (Currency, optional) – The target currency for conversion.
conversion_price (Price, optional) – The conversion price to the target currency.

Return type:

settlement_currency¶

The settlement currency for the instrument.

Returns:: Currency

static to_dict(CryptoPerpetual obj) → dict[str, object]¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

class CurrencyPair¶

Bases: Instrument

CurrencyPair(InstrumentId instrument_id, Symbol raw_symbol, Currency base_currency, Currency quote_currency, int price_precision, int size_precision, Price price_increment, Quantity size_increment, uint64_t ts_event, uint64_t ts_init, multiplier=Quantity.from_int_c(1), Quantity lot_size: Quantity | None = None, Quantity max_quantity: Quantity | None = None, Quantity min_quantity: Quantity | None = None, Money max_notional: Money | None = None, Money min_notional: Money | None = None, Price max_price: Price | None = None, Price min_price: Price | None = None, margin_init: Decimal | None = None, margin_maint: Decimal | None = None, maker_fee: Decimal | None = None, taker_fee: Decimal | None = None, str tick_scheme_name=None, dict info=None) -> None

Represents a generic currency pair instrument in a spot/cash market.

Can represent both Fiat FX and Cryptocurrency pairs.

Parameters:

instrument_id (InstrumentId) – The instrument ID for the instrument.
raw_symbol (Symbol) – The raw/local/native symbol for the instrument, assigned by the venue.
base_currency (Currency) – The base currency.
quote_currency (Currency) – The quote currency.
price_precision (int) – The price decimal precision.
size_precision (int) – The trading size decimal precision.
price_increment (Price) – The minimum price increment (tick size).
size_increment (Quantity) – The minimum size increment.
ts_event (uint64_t) – UNIX timestamp (nanoseconds) when the data event occurred.
ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the data object was initialized.
multiplier (Quantity, default 1) – The contract multiplier.
lot_size (Quantity, optional) – The rounded lot unit size.
max_quantity (Quantity, optional) – The maximum allowable order quantity.
min_quantity (Quantity, optional) – The minimum allowable order quantity.
max_notional (Money, optional) – The maximum allowable order notional value.
min_notional (Money, optional) – The minimum allowable order notional value.
max_price (Price, optional) – The maximum allowable quoted price.
min_price (Price, optional) – The minimum allowable quoted price.
margin_init (Decimal, optional) – The initial (order) margin requirement in percentage of order value.
margin_maint (Decimal, optional) – The maintenance (position) margin in percentage of position value.
maker_fee (Decimal, optional) – The fee rate for liquidity makers as a percentage of order value.
taker_fee (Decimal, optional) – The fee rate for liquidity takers as a percentage of order value.
tick_scheme_name (str, optional) – The name of the tick scheme.
info (dict[str, object], optional) – The additional instrument information.

Raises:

ValueError – If tick_scheme_name is not a valid string.
ValueError – If price_precision is negative (< 0).
ValueError – If size_precision is negative (< 0).
ValueError – If price_increment is not positive (> 0).
ValueError – If size_increment is not positive (> 0).
ValueError – If price_precision is not equal to price_increment.precision.
ValueError – If size_increment is not equal to size_increment.precision.
ValueError – If lot_size is not positive (> 0).
ValueError – If max_quantity is not positive (> 0).
ValueError – If min_quantity is negative (< 0).
ValueError – If max_notional is not positive (> 0).
ValueError – If min_notional is negative (< 0).
ValueError – If max_price is not positive (> 0).
ValueError – If min_price is negative (< 0).
ValueError – If margin_init is negative (< 0).
ValueError – If margin_maint is negative (< 0).

base_currency¶

The base currency for the instrument.

Returns:: Currency

static from_dict(dict values) → CurrencyPair¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: CurrencyPair

static from_pyo3(pyo3_instrument)¶

get_base_currency(self) → Currency¶

Return the instruments base currency.

Return type:: Currency

static to_dict(CurrencyPair obj) → dict[str, object]¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

class Equity¶

Bases: Instrument

Equity(InstrumentId instrument_id, Symbol raw_symbol, Currency currency, int price_precision, Price price_increment, Quantity lot_size, uint64_t ts_event, uint64_t ts_init, Quantity max_quantity: Quantity | None = None, Quantity min_quantity: Quantity | None = None, margin_init: Decimal | None = None, margin_maint: Decimal | None = None, maker_fee: Decimal | None = None, taker_fee: Decimal | None = None, str isin: str | None = None, str tick_scheme_name=None, dict info=None) -> None

Represents a generic equity instrument.

Parameters:

instrument_id (InstrumentId) – The instrument ID.
raw_symbol (Symbol) – The raw/local/native symbol for the instrument, assigned by the venue.
currency (Currency) – The futures contract currency.
price_precision (int) – The price decimal precision.
price_increment (Decimal) – The minimum price increment (tick size).
lot_size (Quantity) – The rounded lot unit size (standard/board).
ts_event (uint64_t) – UNIX timestamp (nanoseconds) when the data event occurred.
ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the data object was initialized.
margin_init (Decimal, optional) – The initial (order) margin requirement in percentage of order value.
margin_maint (Decimal, optional) – The maintenance (position) margin in percentage of position value.
maker_fee (Decimal, optional) – The fee rate for liquidity makers as a percentage of order value.
taker_fee (Decimal, optional) – The fee rate for liquidity takers as a percentage of order value.
isin (str, optional) – The instruments International Securities Identification Number (ISIN).
tick_scheme_name (str, optional) – The name of the tick scheme.
info (dict[str, object], optional) – The additional instrument information.

Raises:

ValueError – If price_precision is negative (< 0).
ValueError – If price_increment is not positive (> 0).
ValueError – If lot_size is not positive (> 0).
ValueError – If margin_init is negative (< 0).
ValueError – If margin_maint is negative (< 0).
ValueError – If isin is not None and not a valid string.

static from_dict(dict values) → Instrument¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: Equity

static from_pyo3(pyo3_instrument) → Equity¶

Return legacy Cython equity instrument converted from the given pyo3 Rust object.

Parameters:: pyo3_instrument (nautilus_pyo3.Equity) – The pyo3 Rust equity instrument to convert from.
Return type:: Equity

isin¶

The instruments International Securities Identification Number (ISIN).

Returns:: str or None

static to_dict(Instrument obj) → dict[str, object]¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

class FuturesContract¶

Bases: Instrument

FuturesContract(InstrumentId instrument_id, Symbol raw_symbol, AssetClass asset_class, Currency currency, int price_precision, Price price_increment, Quantity multiplier, Quantity lot_size, str underlying, uint64_t activation_ns, uint64_t expiration_ns, uint64_t ts_event, uint64_t ts_init, margin_init: Decimal | None = None, margin_maint: Decimal | None = None, maker_fee: Decimal | None = None, taker_fee: Decimal | None = None, str exchange=None, str tick_scheme_name=None, dict info=None) -> None

Represents a generic deliverable futures contract instrument.

Parameters:

instrument_id (InstrumentId) – The instrument ID.
raw_symbol (Symbol) – The raw/local/native symbol for the instrument, assigned by the venue.
asset_class (AssetClass) – The futures contract asset class.
currency (Currency) – The futures contract currency.
price_precision (int) – The price decimal precision.
price_increment (Decimal) – The minimum price increment (tick size).
multiplier (Quantity) – The contract multiplier.
lot_size (Quantity) – The rounded lot unit size (standard/board).
underlying (str) – The underlying asset.
activation_ns (uint64_t) – UNIX timestamp (nanoseconds) for contract activation.
expiration_ns (uint64_t) – UNIX timestamp (nanoseconds) for contract expiration.
ts_event (uint64_t) – UNIX timestamp (nanoseconds) when the data event occurred.
ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the data object was initialized.
margin_init (Decimal, optional) – The initial (order) margin requirement in percentage of order value.
margin_maint (Decimal, optional) – The maintenance (position) margin in percentage of position value.
maker_fee (Decimal, optional) – The fee rate for liquidity makers as a percentage of order value.
taker_fee (Decimal, optional) – The fee rate for liquidity takers as a percentage of order value.
exchange (str, optional) – The exchange ISO 10383 Market Identifier Code (MIC) where the instrument trades.
tick_scheme_name (str, optional) – The name of the tick scheme.
info (dict[str, object], optional) – The additional instrument information.

Raises:

ValueError – If multiplier is not positive (> 0).
ValueError – If price_precision is negative (< 0).
ValueError – If tick_size is not positive (> 0).
ValueError – If lot_size is not positive (> 0).
ValueError – If margin_init is negative (< 0).
ValueError – If margin_maint is negative (< 0).
ValueError – If exchange is not None and not a valid string.

activation_ns¶

UNIX timestamp (nanoseconds) for contract activation.

Returns:: unit64_t

activation_utc¶

pd.Timestamp

Return the contract activation timestamp (UTC).

Returns:: tz-aware UTC.
Return type:: pd.Timestamp
Type:: FuturesContract.activation_utc

exchange¶

The exchange ISO 10383 Market Identifier Code (MIC) where the instrument trades.

Returns:: str or None

expiration_ns¶

UNIX timestamp (nanoseconds) for contract expiration.

Returns:: unit64_t

expiration_utc¶

pd.Timestamp

Return the contract expiration timestamp (UTC).

Returns:: tz-aware UTC.
Return type:: pd.Timestamp
Type:: FuturesContract.expiration_utc

static from_dict(dict values) → FuturesContract¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: FuturesContract

static from_pyo3(pyo3_instrument) → FuturesContract¶

Return legacy Cython futures contract instrument converted from the given pyo3 Rust object.

Parameters:: pyo3_instrument (nautilus_pyo3.FuturesContract) – The pyo3 Rust futures contract instrument to convert from.
Return type:: FuturesContract

static to_dict(FuturesContract obj) → dict[str, object]¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

underlying¶

The underlying asset for the contract.

Returns:: str

class FuturesSpread¶

Bases: Instrument

FuturesSpread(InstrumentId instrument_id, Symbol raw_symbol, AssetClass asset_class, Currency currency, int price_precision, Price price_increment, Quantity multiplier, Quantity lot_size, str underlying, str strategy_type, uint64_t activation_ns, uint64_t expiration_ns, uint64_t ts_event, uint64_t ts_init, margin_init: Decimal | None = None, margin_maint: Decimal | None = None, maker_fee: Decimal | None = None, taker_fee: Decimal | None = None, str exchange=None, str tick_scheme_name=None, dict info=None) -> None

Represents a generic deliverable futures spread instrument.

Parameters:

instrument_id (InstrumentId) – The instrument ID.
raw_symbol (Symbol) – The raw/local/native symbol for the instrument, assigned by the venue.
asset_class (AssetClass) – The futures spread asset class.
currency (Currency) – The futures spread currency.
price_precision (int) – The price decimal precision.
price_increment (Decimal) – The minimum price increment (tick size).
multiplier (Quantity) – The contract multiplier.
lot_size (Quantity) – The rounded lot unit size (standard/board).
underlying (str) – The underlying asset.
strategy_type (str) – The strategy type for the spread.
activation_ns (uint64_t) – UNIX timestamp (nanoseconds) for contract activation.
expiration_ns (uint64_t) – UNIX timestamp (nanoseconds) for contract expiration.
ts_event (uint64_t) – UNIX timestamp (nanoseconds) when the data event occurred.
ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the data object was initialized.
margin_init (Decimal, optional) – The initial (order) margin requirement in percentage of order value.
margin_maint (Decimal, optional) – The maintenance (position) margin in percentage of position value.
maker_fee (Decimal, optional) – The fee rate for liquidity makers as a percentage of order value.
taker_fee (Decimal, optional) – The fee rate for liquidity takers as a percentage of order value.
exchange (str, optional) – The exchange ISO 10383 Market Identifier Code (MIC) where the instrument trades.
tick_scheme_name (str, optional) – The name of the tick scheme.
info (dict[str, object], optional) – The additional instrument information.

Raises:

ValueError – If strategy_type is not a valid string.
ValueError – If multiplier is not positive (> 0).
ValueError – If price_precision is negative (< 0).
ValueError – If tick_size is not positive (> 0).
ValueError – If lot_size is not positive (> 0).
ValueError – If margin_init is negative (< 0).
ValueError – If margin_maint is negative (< 0).
ValueError – If exchange is not None and not a valid string.

activation_ns¶

UNIX timestamp (nanoseconds) for contract activation.

Returns:: unit64_t

activation_utc¶

pd.Timestamp

Return the contract activation timestamp (UTC).

Returns:: tz-aware UTC.
Return type:: pd.Timestamp
Type:: FuturesSpread.activation_utc

exchange¶

The exchange ISO 10383 Market Identifier Code (MIC) where the instrument trades.

Returns:: str or None

expiration_ns¶

UNIX timestamp (nanoseconds) for contract expiration.

Returns:: unit64_t

expiration_utc¶

pd.Timestamp

Return the contract expiration timestamp (UTC).

Returns:: tz-aware UTC.
Return type:: pd.Timestamp
Type:: FuturesSpread.expiration_utc

static from_dict(dict values) → FuturesSpread¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: FuturesSpread

static from_pyo3(pyo3_instrument) → FuturesSpread¶

Return legacy Cython futures spread instrument converted from the given pyo3 Rust object.

Parameters:: pyo3_instrument (nautilus_pyo3.FuturesSpread) – The pyo3 Rust futures spread instrument to convert from.
Return type:: FuturesSpread

legs(self) → list¶

Return the list of leg tuples (instrument_id, ratio) for this spread.

If the instrument ID corresponds to a generic spread ID, returns the parsed legs using generic_spread_id_to_list. Otherwise returns an empty list.

Returns:: List of tuples containing (instrument_id, ratio) for each leg.
Return type:: list[tuple[InstrumentId, int]]

strategy_type¶

The strategy type of the spread.

Returns:: str

static to_dict(FuturesSpread obj) → dict[str, object]¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

underlying¶

The underlying asset for the spread.

Returns:: str

class IndexInstrument¶

Bases: Instrument

IndexInstrument(InstrumentId instrument_id, Symbol raw_symbol, Currency currency, int price_precision, int size_precision, Price price_increment, Quantity size_increment, uint64_t ts_event, uint64_t ts_init, str tick_scheme_name=None, dict info=None) -> None

Represents a spot index instrument (also known as a cash index).

A spot index is calculated from its underlying constituents. It is not directly tradable. To gain exposure you would typically use index futures, ETFs, or CFDs.

Parameters:

instrument_id (InstrumentId) – The instrument ID.
raw_symbol (Symbol) – The raw/local/native symbol for the instrument, assigned by the venue.
currency (Currency) – The futures contract currency.
price_precision (int) – The price decimal precision.
price_increment (Price) – The minimum price increment (tick size).
size_precision (int) – The trading size decimal precision.
size_increment (Quantity) – The minimum size increment.
ts_event (uint64_t) – UNIX timestamp (nanoseconds) when the data event occurred.
ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the data object was initialized.
tick_scheme_name (str, optional) – The name of the tick scheme.
info (dict[str, object], optional) – The additional instrument information.

Raises:

ValueError – If price_precision is negative (< 0).
ValueError – If size_precision is negative (< 0).
ValueError – If price_increment is not positive (> 0).
ValueError – If size_increment is not positive (> 0).
ValueError – If price_precision is not equal to price_increment.precision.
ValueError – If size_increment is not equal to size_increment.precision.

static from_dict(dict values) → Instrument¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: IndexInstrument

static from_pyo3(pyo3_instrument) → IndexInstrument¶

Return legacy Cython index instrument converted from the given pyo3 Rust object.

Parameters:: pyo3_instrument (nautilus_pyo3.IndexInstrument) – The pyo3 Rust index instrument to convert from.
Return type:: IndexInstrument

static to_dict(Instrument obj) → dict[str, object]¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

class Instrument¶

Bases: Data

Instrument(InstrumentId instrument_id, Symbol raw_symbol, AssetClass asset_class, InstrumentClass instrument_class, Currency quote_currency, bool is_inverse, int price_precision, int size_precision, Quantity size_increment, Quantity multiplier, margin_init: Decimal, margin_maint: Decimal, maker_fee: Decimal, taker_fee: Decimal, uint64_t ts_event, uint64_t ts_init, Price price_increment: Price | None = None, Quantity lot_size: Quantity | None = None, Quantity max_quantity: Quantity | None = None, Quantity min_quantity: Quantity | None = None, Money max_notional: Money | None = None, Money min_notional: Money | None = None, Price max_price: Price | None = None, Price min_price: Price | None = None, str tick_scheme_name=None, dict info=None) -> None

The base class for all instruments.

Represents a tradable instrument. This class can be used to define an instrument, or act as a parent class for more specific instruments.

Parameters:

instrument_id (InstrumentId) – The instrument ID for the instrument.
raw_symbol (Symbol) – The raw/local/native symbol for the instrument, assigned by the venue.
asset_class (AssetClass) – The instrument asset class.
instrument_class (InstrumentClass) – The instrument class.
quote_currency (Currency) – The quote currency.
is_inverse (bool) – If the instrument costing is inverse (quantity expressed in quote currency units).
price_precision (int) – The price decimal precision.
size_precision (int) – The trading size decimal precision.
size_increment (Quantity) – The minimum size increment.
multiplier (Quantity) – The contract value multiplier (determines tick value).
lot_size (Quantity, optional) – The rounded lot unit size (standard/board).
margin_init (Decimal) – The initial (order) margin requirement in percentage of order value.
margin_maint (Decimal) – The maintenance (position) margin in percentage of position value.
maker_fee (Decimal) – The fee rate for liquidity makers as a percentage of order value (where 1.0 is 100%).
taker_fee (Decimal) – The fee rate for liquidity takers as a percentage of order value (where 1.0 is 100%).
ts_event (uint64_t) – UNIX timestamp (nanoseconds) when the data event occurred.
ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the data object was initialized.
price_increment (Price, optional) – The minimum price increment (tick size).
max_quantity (Quantity, optional) – The maximum allowable order quantity.
min_quantity (Quantity, optional) – The minimum allowable order quantity.
max_notional (Money, optional) – The maximum allowable order notional value.
min_notional (Money, optional) – The minimum allowable order notional value.
max_price (Price, optional) – The maximum allowable quoted price.
min_price (Price, optional) – The minimum allowable quoted price.
tick_scheme_name (str, optional) – The name of the tick scheme.
info (dict[str, object], optional) – The additional instrument information.

Raises:

ValueError – If tick_scheme_name is not a valid string.
ValueError – If price_precision is negative (< 0).
ValueError – If size_precision is negative (< 0).
ValueError – If price_increment is not positive (> 0).
ValueError – If size_increment is not positive (> 0).
ValueError – If price_precision is not equal to price_increment.precision.
ValueError – If size_increment is not equal to size_increment.precision.
ValueError – If multiplier is not positive (> 0).
ValueError – If margin_init is negative (< 0).
ValueError – If margin_maint is negative (< 0).
ValueError – If lot size is not positive (> 0).
ValueError – If max_quantity is not positive (> 0).
ValueError – If min_quantity is negative (< 0).
ValueError – If max_notional is not positive (> 0).
ValueError – If min_notional is negative (< 0).
ValueError – If max_price is not positive (> 0).
ValueError – If min_price is negative (< 0).

asset_class¶

The asset class of the instrument.

Returns:: AssetClass

static base_from_dict(dict values) → Instrument¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: Instrument

static base_to_dict(Instrument obj)¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

calculate_base_quantity(self, Quantity quantity, Price last_px) → Quantity¶

Calculate the base asset quantity from the given quote asset quantity and last price.

Parameters:

quantity (Quantity) – The quantity to convert from.
last_px (Price) – The last price for the instrument.

Return type:

get_base_currency(self) → Currency¶

Return the instruments base currency (if applicable).

Return type:: Currency or None

get_cost_currency(self) → Currency¶

Return the currency used for PnL calculations for the instrument.

Standard linear instruments = quote_currency
Inverse instruments = base_currency
Quanto instruments TBD

Return type:: Currency

get_settlement_currency(self) → Currency¶

Return the currency used to settle a trade of the instrument.

Standard linear instruments = quote_currency
Inverse instruments = base_currency
Quanto instruments = settlement_currency

Return type:: Currency

id¶

The instrument ID.

Returns:: InstrumentId

info¶

The raw info for the instrument.

Returns:: dict[str, object]

instrument_class¶

The class of the instrument.

Returns:: InstrumentClass

is_inverse¶

If the quantity is expressed in quote currency.

Returns:: bool

is_spread(self) → bool¶

Return whether the instrument is a spread instrument.

Return type:: bool

legs(self) → list¶

Return the list of leg tuples (instrument_id, ratio) for this spread.

Base implementation returns an empty list. Override in spread instrument classes to return the actual legs.

Returns:: List of tuples containing (instrument_id, ratio) for each leg.
Return type:: list[tuple[InstrumentId, int]]

lot_size¶

The rounded lot unit size (standard/board) for the instrument.

Returns:: Quantity or None

make_price(self, value) → Price¶

Return a new price from the given value using the instruments price precision.

Parameters:: value (integer, float, str or Decimal) – The value of the price.
Return type:: Price

make_qty(self, value, bool round_down=False) → Quantity¶

Return a new quantity from the given value using the instruments size precision.

Parameters:

value (integer, float, str or Decimal) – The value of the quantity.
round_down (bool, default False) – If True, always rounds down to the nearest valid increment. If False, uses the round function (banker’s rounding) which rounds to the nearest even digit when exactly halfway between two values.

Return type:

Raises:

ValueError – If a non zero value is rounded to zero due to the instruments size increment or size precision.

maker_fee¶

The fee rate for liquidity makers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

margin_init¶

The initial (order) margin rate for the instrument.

Returns:: Decimal

margin_maint¶

The maintenance (position) margin rate for the instrument.

Returns:: Decimal

max_notional¶

The maximum notional order value for the instrument.

Returns:: Money or None

max_price¶

The maximum printable price for the instrument.

Returns:: Price or None

max_quantity¶

The maximum order quantity for the instrument.

Returns:: Quantity or None

min_notional¶

The minimum notional order value for the instrument.

Returns:: Money or None

min_price¶

The minimum printable price for the instrument.

Returns:: Price or None

min_quantity¶

The minimum order quantity for the instrument.

Returns:: Quantity or None

multiplier¶

The contract multiplier for the instrument (determines tick value).

Returns:: Quantity

next_ask_price(self, double value, int num_ticks=0) → Price¶

Return the price n ask ticks away from value.

If a given price is between two ticks, n=0 will find the nearest ask tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_ask_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks ask ticks away from value.

If a given price is between two ticks, the first price will be the nearest ask tick. Returns as many valid ticks as possible up to num_ticks. Will return an empty list if no valid ticks can be generated.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of ask prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_price(self, double value, int num_ticks=0) → Price¶

Return the price n bid ticks away from value.

If a given price is between two ticks, n=0 will find the nearest bid tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks bid ticks away from value.

If a given price is between two ticks, the first price will be the nearest bid tick. Returns as many valid ticks as possible up to num_ticks. Will return an empty list if no valid ticks can be generated.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of bid prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

notional_value(self, Quantity quantity, Price price, bool use_quote_for_inverse=False, Currency target_currency=None, Price conversion_price=None) → Money¶

Calculate the notional value.

Result will be in quote currency for standard instruments, or base currency for inverse instruments.

If target_currency and conversion_price are provided, the notional value will be converted to the target currency.

Parameters:

quantity (Quantity) – The total quantity.
price (Price) – The price for the calculation.
use_quote_for_inverse (bool) – If inverse instrument calculations use quote currency (instead of base).
target_currency (Currency, optional) – The target currency for conversion.
conversion_price (Price, optional) – The price to use for currency conversion.

Return type:

price_increment¶

The minimum price increment or tick size for the instrument.

Returns:: Price

price_precision¶

The price precision of the instrument.

Returns:: int

quote_currency¶

The quote currency for the instrument.

Returns:: Currency

raw_symbol¶

The raw/local/native symbol for the instrument, assigned by the venue.

Returns:: Symbol

set_tick_scheme(self, str tick_scheme_name) → void¶

Set the tick scheme for the instrument.

Sets both the tick_scheme_name and the corresponding tick scheme implementation used for price rounding and tick calculations.

This will override any previously set tick scheme, including the tick_scheme_name field.

Parameters:

tick_scheme_name (str) – The name of the registered tick scheme.

Raises:

ValueError – If tick_scheme_name is not a valid string.
ValueError – If tick_scheme_name is not a registered tick scheme.

size_increment¶

The minimum size increment for the instrument.

Returns:: Quantity

size_precision¶

The size precision of the instrument.

Returns:: int

symbol¶

Return the instruments ticker symbol.

Return type:: Symbol

taker_fee¶

The fee rate for liquidity takers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

tick_scheme_name¶

The tick scheme name.

Returns:: str or None

ts_event¶

UNIX timestamp (nanoseconds) when the data event occurred.

Returns:: uint64_t

ts_init¶

UNIX timestamp (nanoseconds) when the object was initialized.

Returns:: uint64_t

venue¶

Return the instruments trading venue.

Return type:: Venue

class OptionContract¶

Bases: Instrument

OptionContract(InstrumentId instrument_id, Symbol raw_symbol, AssetClass asset_class, Currency currency, int price_precision, Price price_increment, Quantity multiplier, Quantity lot_size, str underlying, OptionKind option_kind, Price strike_price, uint64_t activation_ns, uint64_t expiration_ns, uint64_t ts_event, uint64_t ts_init, margin_init: Decimal | None = None, margin_maint: Decimal | None = None, maker_fee: Decimal | None = None, taker_fee: Decimal | None = None, str exchange=None, str tick_scheme_name=None, dict info=None) -> None

Represents a generic option contract instrument.

Parameters:

instrument_id (InstrumentId) – The instrument ID.
raw_symbol (Symbol) – The raw/local/native symbol for the instrument, assigned by the venue.
asset_class (AssetClass) – The option contract asset class.
currency (Currency) – The option contract currency.
price_precision (int) – The price decimal precision.
price_increment (Price) – The minimum price increment (tick size).
multiplier (Quantity) – The option multiplier.
lot_size (Quantity) – The rounded lot unit size (standard/board).
underlying (str) – The underlying asset.
option_kind (OptionKind) – The kind of option (PUT | CALL).
strike_price (Price) – The option strike price.
activation_ns (uint64_t) – UNIX timestamp (nanoseconds) for contract activation.
expiration_ns (uint64_t) – UNIX timestamp (nanoseconds) for contract expiration.
ts_event (uint64_t) – UNIX timestamp (nanoseconds) when the data event occurred.
ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the data object was initialized.
margin_init (Decimal, optional) – The initial (order) margin requirement in percentage of order value.
margin_maint (Decimal, optional) – The maintenance (position) margin in percentage of position value.
maker_fee (Decimal, optional) – The fee rate for liquidity makers as a percentage of order value.
taker_fee (Decimal, optional) – The fee rate for liquidity takers as a percentage of order value.
exchange (str, optional) – The exchange ISO 10383 Market Identifier Code (MIC) where the instrument trades.
tick_scheme_name (str, optional) – The name of the tick scheme.
info (dict[str, object], optional) – The additional instrument information.

Raises:

ValueError – If multiplier is not positive (> 0).
ValueError – If price_precision is negative (< 0).
ValueError – If tick_size is not positive (> 0).
ValueError – If lot_size is not positive (> 0).
ValueError – If margin_init is negative (< 0).
ValueError – If margin_maint is negative (< 0).
ValueError – If exchange is not None and not a valid string.

activation_ns¶

UNIX timestamp (nanoseconds) for contract activation.

Returns:: unit64_t

activation_utc¶

pd.Timestamp

Return the contract activation timestamp (UTC).

Returns:: tz-aware UTC.
Return type:: pd.Timestamp
Type:: OptionContract.activation_utc

exchange¶

The exchange ISO 10383 Market Identifier Code (MIC) where the instrument trades.

Returns:: str or None

expiration_ns¶

UNIX timestamp (nanoseconds) for contract expiration.

Returns:: unit64_t

expiration_utc¶

pd.Timestamp

Return the contract expiration timestamp (UTC).

Returns:: tz-aware UTC.
Return type:: pd.Timestamp
Type:: OptionContract.expiration_utc

static from_dict(dict values) → OptionContract¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: OptionContract

static from_pyo3(pyo3_instrument) → OptionContract¶

Return legacy Cython option contract instrument converted from the given pyo3 Rust object.

Parameters:: pyo3_instrument (nautilus_pyo3.OptionContract) – The pyo3 Rust option contract instrument to convert from.
Return type:: OptionContract

option_kind¶

The option kind (PUT | CALL) for the contract.

Returns:: OptionKind

strike_price¶

The strike price for the contract.

Returns:: Price

static to_dict(OptionContract obj) → dict[str, object]¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

underlying¶

The underlying asset for the contract.

Returns:: str

class OptionSpread¶

Bases: Instrument

OptionSpread(InstrumentId instrument_id, Symbol raw_symbol, AssetClass asset_class, Currency currency, int price_precision, Price price_increment, Quantity multiplier, Quantity lot_size, str underlying, str strategy_type, uint64_t activation_ns, uint64_t expiration_ns, uint64_t ts_event, uint64_t ts_init, margin_init: Decimal | None = None, margin_maint: Decimal | None = None, maker_fee: Decimal | None = None, taker_fee: Decimal | None = None, str exchange=None, str tick_scheme_name=None, dict info=None) -> None

Represents a generic option spread instrument.

Parameters:

instrument_id (InstrumentId) – The instrument ID.
raw_symbol (Symbol) – The raw/local/native symbol for the instrument, assigned by the venue.
asset_class (AssetClass) – The option spread asset class.
currency (Currency) – The option spread currency.
price_precision (int) – The price decimal precision.
price_increment (Price) – The minimum price increment (tick size).
multiplier (Quantity) – The option multiplier.
lot_size (Quantity) – The rounded lot unit size (standard/board).
underlying (str) – The underlying asset.
strategy_type (str) – The strategy type of the spread.
activation_ns (uint64_t) – UNIX timestamp (nanoseconds) for contract activation.
expiration_ns (uint64_t) – UNIX timestamp (nanoseconds) for contract expiration.
ts_event (uint64_t) – UNIX timestamp (nanoseconds) when the data event occurred.
ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the data object was initialized.
margin_init (Decimal, optional) – The initial (order) margin requirement in percentage of order value.
margin_maint (Decimal, optional) – The maintenance (position) margin in percentage of position value.
maker_fee (Decimal, optional) – The fee rate for liquidity makers as a percentage of order value.
taker_fee (Decimal, optional) – The fee rate for liquidity takers as a percentage of order value.
exchange (str, optional) – The exchange ISO 10383 Market Identifier Code (MIC) where the instrument trades.
tick_scheme_name (str, optional) – The name of the tick scheme.
info (dict[str, object], optional) – The additional instrument information.

Raises:

ValueError – If strategy_type is not a valid string.
ValueError – If multiplier is not positive (> 0).
ValueError – If price_precision is negative (< 0).
ValueError – If tick_size is not positive (> 0).
ValueError – If lot_size is not positive (> 0).
ValueError – If margin_init is negative (< 0).
ValueError – If margin_maint is negative (< 0).
ValueError – If exchange is not None and not a valid string.

activation_ns¶

UNIX timestamp (nanoseconds) for contract activation.

Returns:: unit64_t

activation_utc¶

pd.Timestamp

Return the contract activation timestamp (UTC).

Returns:: tz-aware UTC.
Return type:: pd.Timestamp
Type:: OptionSpread.activation_utc

exchange¶

The exchang ISO 10383 Market Identifier Code (MIC) where the instrument trades.

Returns:: str or None

expiration_ns¶

UNIX timestamp (nanoseconds) for contract expiration.

Returns:: unit64_t

expiration_utc¶

pd.Timestamp

Return the contract expiration timestamp (UTC).

Returns:: tz-aware UTC.
Return type:: pd.Timestamp
Type:: OptionSpread.expiration_utc

static from_dict(dict values) → OptionSpread¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: OptionSpread

static from_pyo3(pyo3_instrument) → OptionSpread¶

Return legacy Cython option spread instrument converted from the given pyo3 Rust object.

Parameters:: pyo3_instrument (nautilus_pyo3.OptionSpread) – The pyo3 Rust option spread instrument to convert from.
Return type:: OptionSpread

legs(self) → list¶

Return the list of leg tuples (instrument_id, ratio) for this spread.

If the instrument ID corresponds to a generic spread ID, returns the parsed legs using generic_spread_id_to_list. Otherwise returns an empty list.

Returns:: List of tuples containing (instrument_id, ratio) for each leg.
Return type:: list[tuple[InstrumentId, int]]

strategy_type¶

The strategy type of the spread.

Returns:: str

static to_dict(OptionSpread obj) → dict[str, object]¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

underlying¶

The underlying asset for the contract.

Returns:: str

class PerpetualContract¶

Bases: Instrument

PerpetualContract(InstrumentId instrument_id, Symbol raw_symbol, str underlying, AssetClass asset_class, Currency quote_currency, Currency settlement_currency, bool is_inverse, int price_precision, int size_precision, Price price_increment, Quantity size_increment, uint64_t ts_event, uint64_t ts_init, Currency base_currency: Currency | None = None, multiplier=Quantity.from_int_c(1), lot_size=Quantity.from_int_c(1), Quantity max_quantity: Quantity | None = None, Quantity min_quantity: Quantity | None = None, Money max_notional: Money | None = None, Money min_notional: Money | None = None, Price max_price: Price | None = None, Price min_price: Price | None = None, margin_init: Decimal | None = None, margin_maint: Decimal | None = None, maker_fee: Decimal | None = None, taker_fee: Decimal | None = None, str tick_scheme_name=None, dict info=None) -> None

Represents a perpetual contract instrument (perpetual swap).

Supports perpetuals on any asset class including FX, equities, commodities, indexes, and cryptocurrencies.

Parameters:

instrument_id (InstrumentId) – The instrument ID for the instrument.
raw_symbol (Symbol) – The raw/local/native symbol for the instrument, assigned by the venue.
underlying (str) – The underlying asset identifier (e.g., “EURUSD”, “NVDA”, “GC”).
asset_class (AssetClass) – The asset class of the perpetual contract.
quote_currency (Currency) – The quote currency.
settlement_currency (Currency) – The settlement currency.
is_inverse (bool) – If the instrument costing is inverse (quantity expressed in quote currency units).
price_precision (int) – The price decimal precision.
size_precision (int) – The trading size decimal precision.
price_increment (Price) – The minimum price increment (tick size).
size_increment (Quantity) – The minimum size increment.
ts_event (uint64_t) – UNIX timestamp (nanoseconds) when the data event occurred.
ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the data object was initialized.
base_currency (Currency, optional) – The base currency (for FX/crypto underlyings).
multiplier (Quantity, default 1) – The contract multiplier.
lot_size (Quantity, default 1) – The rounded lot unit size (standard/board).
max_quantity (Quantity, optional) – The maximum allowable order quantity.
min_quantity (Quantity, optional) – The minimum allowable order quantity.
max_notional (Money, optional) – The maximum allowable order notional value.
min_notional (Money, optional) – The minimum allowable order notional value.
max_price (Price, optional) – The maximum allowable quoted price.
min_price (Price, optional) – The minimum allowable quoted price.
margin_init (Decimal, optional) – The initial (order) margin requirement in percentage of order value.
margin_maint (Decimal, optional) – The maintenance (position) margin in percentage of position value.
maker_fee (Decimal, optional) – The fee rate for liquidity makers as a percentage of order value.
taker_fee (Decimal, optional) – The fee rate for liquidity takers as a percentage of order value.
tick_scheme_name (str, optional) – The name of the tick scheme.
info (dict[str, object], optional) – The additional instrument information.

base_currency¶

The base currency for the instrument.

Returns:: Currency or None

static from_dict(dict values) → PerpetualContract¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: PerpetualContract

static from_pyo3(pyo3_instrument)¶

get_base_currency(self) → Currency¶

get_cost_currency(self) → Currency¶

get_settlement_currency(self) → Currency¶

is_quanto¶

If the instrument is a quanto perpetual.

Returns:: bool

notional_value(self, Quantity quantity, Price price, bool use_quote_for_inverse=False, Currency target_currency=None, Price conversion_price=None) → Money¶

settlement_currency¶

The settlement currency for the instrument.

Returns:: Currency

static to_dict(PerpetualContract obj) → dict[str, object]¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

underlying¶

The underlying asset identifier.

Returns:: str

class SyntheticInstrument¶

Bases: Data

SyntheticInstrument(Symbol symbol, uint8_t price_precision, list components, str formula, uint64_t ts_event, uint64_t ts_init) -> None

Represents a synthetic instrument with prices derived from component instruments using a formula.

The id for the synthetic will become {symbol}.{SYNTH}.

Parameters:

symbol (Symbol) – The symbol for the synthetic instrument.
price_precision (uint8_t) – The price precision for the synthetic instrument.
components (list[InstrumentId]) – The component instruments for the synthetic instrument.
formula (str) – The derivation formula for the synthetic instrument.
ts_event (uint64_t) – UNIX timestamp (nanoseconds) when the data event occurred.
ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the data object was initialized.

Raises:

ValueError – If price_precision is greater than 9.
OverflowError – If price_precision is negative (< 0).
ValueError – If the components list does not contain at least 2 instrument IDs.
ValueError – If the formula is not a valid string.
ValueError – If the formula is not a valid expression.

Warning

All component instruments should already be defined and exist in the cache prior to defining a new synthetic instrument.

calculate(self, list inputs) → Price¶

Calculate the price of the synthetic instrument from the given inputs.

Parameters:

inputs (list[double])

Return type:

Raises:

ValueError – If inputs is empty, contains a NaN value, or length is different from components count.
RuntimeError – If an internal error occurs when calculating the price.

change_formula(self, str formula) → void¶

Change the internal derivation formula for the synthetic instrument.

Parameters:

formula (str) – The derivation formula to change to.

Raises:

ValueError – If the formula is not a valid string.
ValueError – If the formula is not a valid expression.

components¶

list[InstrumentId]

Return the components of the synthetic instrument.

Return type:: list[InstrumentId]
Type:: SyntheticInstrument.components

formula¶

str

Return the synthetic instrument internal derivation formula.

Return type:: str
Type:: SyntheticInstrument.formula

static from_dict(dict values) → SyntheticInstrument¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: SyntheticInstrument

id¶

The instrument ID.

Returns:: InstrumentId

price_increment¶

Price

Return the minimum price increment (tick size) for the synthetic instrument.

Return type:: Price
Type:: SyntheticInstrument.price_increment

price_precision¶

int

Return the precision for the synthetic instrument.

Return type:: int
Type:: SyntheticInstrument.price_precision

static to_dict(SyntheticInstrument obj) → dict[str, object]¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

ts_event¶

int

UNIX timestamp (nanoseconds) when the data event occurred.

Return type:: int
Type:: SyntheticInstrument.ts_event

ts_init¶

int

UNIX timestamp (nanoseconds) when the object was initialized.

Return type:: int
Type:: SyntheticInstrument.ts_init

instruments_from_pyo3(list pyo3_instruments) → list¶

class BettingInstrument¶

Bases: Instrument

Represents an instrument in a betting market.

asset_class¶

The asset class of the instrument.

Returns:: AssetClass

static base_from_dict(dict values) → Instrument¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: Instrument

static base_to_dict(Instrument obj)¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

betting_type¶

calculate_base_quantity(self, Quantity quantity, Price last_px) → Quantity¶

Calculate the base asset quantity from the given quote asset quantity and last price.

Parameters:

quantity (Quantity) – The quantity to convert from.
last_px (Price) – The last price for the instrument.

Return type:

competition_id¶

competition_name¶

event_country_code¶

event_id¶

event_name¶

event_open_date¶

event_type_id¶

event_type_name¶

static from_dict(dict values) → BettingInstrument¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: BettingInstrument

classmethod fully_qualified_name(cls) → str¶

Return the fully qualified name for the Data class.

Return type:: str

References

get_base_currency(self) → Currency¶

Return the instruments base currency (if applicable).

Return type:: Currency or None

get_cost_currency(self) → Currency¶

Return the currency used for PnL calculations for the instrument.

Standard linear instruments = quote_currency
Inverse instruments = base_currency
Quanto instruments TBD

Return type:: Currency

get_settlement_currency(self) → Currency¶

Return the currency used to settle a trade of the instrument.

Standard linear instruments = quote_currency
Inverse instruments = base_currency
Quanto instruments = settlement_currency

Return type:: Currency

id¶

The instrument ID.

Returns:: InstrumentId

info¶

The raw info for the instrument.

Returns:: dict[str, object]

instrument_class¶

The class of the instrument.

Returns:: InstrumentClass

is_inverse¶

If the quantity is expressed in quote currency.

Returns:: bool

classmethod is_signal(cls, str name='') → bool¶

Determine if the current class is a signal type, optionally checking for a specific signal name.

Parameters:: name (str, optional) – The specific signal name to check. If name not provided or if an empty string is passed, the method checks whether the class name indicates a general signal type. If name is provided, the method checks if the class name corresponds to that specific signal.
Returns:: True if the class name matches the signal type or the specific signal name, otherwise False.
Return type:: bool

is_spread(self) → bool¶

Return whether the instrument is a spread instrument.

Return type:: bool

legs(self) → list¶

Return the list of leg tuples (instrument_id, ratio) for this spread.

Base implementation returns an empty list. Override in spread instrument classes to return the actual legs.

Returns:: List of tuples containing (instrument_id, ratio) for each leg.
Return type:: list[tuple[InstrumentId, int]]

lot_size¶

The rounded lot unit size (standard/board) for the instrument.

Returns:: Quantity or None

make_price(self, value) → Price¶

Return a new price from the given value using the instruments price precision.

Parameters:: value (integer, float, str or Decimal) – The value of the price.
Return type:: Price

make_qty(self, value, bool round_down=False) → Quantity¶

Return a new quantity from the given value using the instruments size precision.

Parameters:

value (integer, float, str or Decimal) – The value of the quantity.
round_down (bool, default False) – If True, always rounds down to the nearest valid increment. If False, uses the round function (banker’s rounding) which rounds to the nearest even digit when exactly halfway between two values.

Return type:

Raises:

ValueError – If a non zero value is rounded to zero due to the instruments size increment or size precision.

maker_fee¶

The fee rate for liquidity makers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

margin_init¶

The initial (order) margin rate for the instrument.

Returns:: Decimal

margin_maint¶

The maintenance (position) margin rate for the instrument.

Returns:: Decimal

market_id¶

market_name¶

market_start_time¶

market_type¶

max_notional¶

The maximum notional order value for the instrument.

Returns:: Money or None

max_price¶

The maximum printable price for the instrument.

Returns:: Price or None

max_quantity¶

The maximum order quantity for the instrument.

Returns:: Quantity or None

min_notional¶

The minimum notional order value for the instrument.

Returns:: Money or None

min_price¶

The minimum printable price for the instrument.

Returns:: Price or None

min_quantity¶

The minimum order quantity for the instrument.

Returns:: Quantity or None

multiplier¶

The contract multiplier for the instrument (determines tick value).

Returns:: Quantity

next_ask_price(self, double value, int num_ticks=0) → Price¶

Return the price n ask ticks away from value.

If a given price is between two ticks, n=0 will find the nearest ask tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_ask_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks ask ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of ask prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_price(self, double value, int num_ticks=0) → Price¶

Return the price n bid ticks away from value.

If a given price is between two ticks, n=0 will find the nearest bid tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks bid ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of bid prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

notional_value(self, Quantity quantity, Price price, bool use_quote_for_inverse=False, Currency target_currency=None, Price conversion_price=None) → Money¶

price_increment¶

The minimum price increment or tick size for the instrument.

Returns:: Price

price_precision¶

The price precision of the instrument.

Returns:: int

quote_currency¶

The quote currency for the instrument.

Returns:: Currency

raw_symbol¶

The raw/local/native symbol for the instrument, assigned by the venue.

Returns:: Symbol

selection_handicap¶

selection_id¶

selection_name¶

set_tick_scheme(self, str tick_scheme_name) → void¶

Set the tick scheme for the instrument.

Sets both the tick_scheme_name and the corresponding tick scheme implementation used for price rounding and tick calculations.

This will override any previously set tick scheme, including the tick_scheme_name field.

Parameters:

tick_scheme_name (str) – The name of the registered tick scheme.

Raises:

ValueError – If tick_scheme_name is not a valid string.
ValueError – If tick_scheme_name is not a registered tick scheme.

size_increment¶

The minimum size increment for the instrument.

Returns:: Quantity

size_precision¶

The size precision of the instrument.

Returns:: int

symbol¶

Return the instruments ticker symbol.

Return type:: Symbol

taker_fee¶

The fee rate for liquidity takers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

tick_scheme_name¶

The tick scheme name.

Returns:: str or None

static to_dict(BettingInstrument obj) → dict[str, object]¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

ts_event¶

UNIX timestamp (nanoseconds) when the data event occurred.

Returns:: uint64_t

ts_init¶

UNIX timestamp (nanoseconds) when the object was initialized.

Returns:: uint64_t

venue¶

Return the instruments trading venue.

Return type:: Venue

make_symbol(str market_id, int selection_id, float selection_handicap) → Symbol¶

Make symbol.

>>> make_symbol(market_id="1.201070830", selection_id=123456, selection_handicap=null_handicap())
Symbol('1-201070830-123456-None')

null_handicap() → double¶

order_side_to_bet_side(OrderSide order_side)¶

class BinaryOption¶

Bases: Instrument

Represents a generic binary option instrument.

Parameters:

instrument_id (InstrumentId) – The instrument ID.
raw_symbol (Symbol) – The raw/local/native symbol for the instrument, assigned by the venue.
asset_class (AssetClass) – The option contract asset class.
currency (Currency) – The option contract currency.
price_precision (int) – The price decimal precision.
size_precision (int) – The trading size decimal precision.
price_increment (Price) – The minimum price increment (tick size).
size_increment (Quantity) – The minimum size increment.
activation_ns (uint64_t) – UNIX timestamp (nanoseconds) for contract activation.
expiration_ns (uint64_t) – UNIX timestamp (nanoseconds) for contract expiration.
ts_event (uint64_t) – UNIX timestamp (nanoseconds) when the data event occurred.
ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the data object was initialized.
max_quantity (Quantity, optional) – The maximum allowable order quantity.
min_quantity (Quantity, optional) – The minimum allowable order quantity.
maker_fee (Decimal, optional) – The fee rate for liquidity makers as a percentage of order value.
taker_fee (Decimal, optional) – The fee rate for liquidity takers as a percentage of order value.
outcome (str, optional) – The binary outcome of the market.
description (str, optional) – The market description.
tick_scheme_name (str, optional) – The name of the tick scheme.
info (dict[str, object], optional) – The additional instrument information.

Raises:

ValueError – If price_precision is negative (< 0).
ValueError – If size_precision is negative (< 0).
ValueError – If price_increment is not positive (> 0).
ValueError – If size_increment is not positive (> 0).

activation_ns¶

UNIX timestamp (nanoseconds) for contract activation.

Returns:: unit64_t

activation_utc¶

pd.Timestamp

Return the contract activation timestamp (UTC).

Returns:: tz-aware UTC.
Return type:: pd.Timestamp
Type:: BinaryOption.activation_utc

asset_class¶

The asset class of the instrument.

Returns:: AssetClass

static base_from_dict(dict values) → Instrument¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: Instrument

static base_to_dict(Instrument obj)¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

calculate_base_quantity(self, Quantity quantity, Price last_px) → Quantity¶

Calculate the base asset quantity from the given quote asset quantity and last price.

Parameters:

quantity (Quantity) – The quantity to convert from.
last_px (Price) – The last price for the instrument.

Return type:

description¶

The market description.

Returns:: str or None

expiration_ns¶

UNIX timestamp (nanoseconds) for contract expiration.

Returns:: unit64_t

expiration_utc¶

pd.Timestamp

Return the contract expiration timestamp (UTC).

Returns:: tz-aware UTC.
Return type:: pd.Timestamp
Type:: BinaryOption.expiration_utc

static from_dict(dict values) → BinaryOption¶

Return an instrument from the given initialization values.

valuesdict[str, object]
The values to initialize the instrument with.

BinaryOption

classmethod fully_qualified_name(cls) → str¶

Return the fully qualified name for the Data class.

Return type:: str

References

get_base_currency(self) → Currency¶

Return the instruments base currency (if applicable).

Return type:: Currency or None

get_cost_currency(self) → Currency¶

Return the currency used for PnL calculations for the instrument.

Standard linear instruments = quote_currency
Inverse instruments = base_currency
Quanto instruments TBD

Return type:: Currency

get_settlement_currency(self) → Currency¶

Return the currency used to settle a trade of the instrument.

Standard linear instruments = quote_currency
Inverse instruments = base_currency
Quanto instruments = settlement_currency

Return type:: Currency

id¶

The instrument ID.

Returns:: InstrumentId

info¶

The raw info for the instrument.

Returns:: dict[str, object]

instrument_class¶

The class of the instrument.

Returns:: InstrumentClass

is_inverse¶

If the quantity is expressed in quote currency.

Returns:: bool

classmethod is_signal(cls, str name='') → bool¶

Determine if the current class is a signal type, optionally checking for a specific signal name.

Parameters:: name (str, optional) – The specific signal name to check. If name not provided or if an empty string is passed, the method checks whether the class name indicates a general signal type. If name is provided, the method checks if the class name corresponds to that specific signal.
Returns:: True if the class name matches the signal type or the specific signal name, otherwise False.
Return type:: bool

is_spread(self) → bool¶

Return whether the instrument is a spread instrument.

Return type:: bool

legs(self) → list¶

Return the list of leg tuples (instrument_id, ratio) for this spread.

Base implementation returns an empty list. Override in spread instrument classes to return the actual legs.

Returns:: List of tuples containing (instrument_id, ratio) for each leg.
Return type:: list[tuple[InstrumentId, int]]

lot_size¶

The rounded lot unit size (standard/board) for the instrument.

Returns:: Quantity or None

make_price(self, value) → Price¶

Return a new price from the given value using the instruments price precision.

Parameters:: value (integer, float, str or Decimal) – The value of the price.
Return type:: Price

make_qty(self, value, bool round_down=False) → Quantity¶

Return a new quantity from the given value using the instruments size precision.

Parameters:

value (integer, float, str or Decimal) – The value of the quantity.
round_down (bool, default False) – If True, always rounds down to the nearest valid increment. If False, uses the round function (banker’s rounding) which rounds to the nearest even digit when exactly halfway between two values.

Return type:

Raises:

ValueError – If a non zero value is rounded to zero due to the instruments size increment or size precision.

maker_fee¶

The fee rate for liquidity makers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

margin_init¶

The initial (order) margin rate for the instrument.

Returns:: Decimal

margin_maint¶

The maintenance (position) margin rate for the instrument.

Returns:: Decimal

max_notional¶

The maximum notional order value for the instrument.

Returns:: Money or None

max_price¶

The maximum printable price for the instrument.

Returns:: Price or None

max_quantity¶

The maximum order quantity for the instrument.

Returns:: Quantity or None

min_notional¶

The minimum notional order value for the instrument.

Returns:: Money or None

min_price¶

The minimum printable price for the instrument.

Returns:: Price or None

min_quantity¶

The minimum order quantity for the instrument.

Returns:: Quantity or None

multiplier¶

The contract multiplier for the instrument (determines tick value).

Returns:: Quantity

next_ask_price(self, double value, int num_ticks=0) → Price¶

Return the price n ask ticks away from value.

If a given price is between two ticks, n=0 will find the nearest ask tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_ask_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks ask ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of ask prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_price(self, double value, int num_ticks=0) → Price¶

Return the price n bid ticks away from value.

If a given price is between two ticks, n=0 will find the nearest bid tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks bid ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of bid prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

notional_value(self, Quantity quantity, Price price, bool use_quote_for_inverse=False, Currency target_currency=None, Price conversion_price=None) → Money¶

Calculate the notional value.

Result will be in quote currency for standard instruments, or base currency for inverse instruments.

If target_currency and conversion_price are provided, the notional value will be converted to the target currency.

Parameters:

quantity (Quantity) – The total quantity.
price (Price) – The price for the calculation.
use_quote_for_inverse (bool) – If inverse instrument calculations use quote currency (instead of base).
target_currency (Currency, optional) – The target currency for conversion.
conversion_price (Price, optional) – The price to use for currency conversion.

Return type:

https://en.wikipedia.org/wiki/Contract_for_difference

outcome¶

The binary outcome of the market.

Returns:: str or None

price_increment¶

The minimum price increment or tick size for the instrument.

Returns:: Price

price_precision¶

The price precision of the instrument.

Returns:: int

quote_currency¶

The quote currency for the instrument.

Returns:: Currency

raw_symbol¶

The raw/local/native symbol for the instrument, assigned by the venue.

Returns:: Symbol

set_tick_scheme(self, str tick_scheme_name) → void¶

Set the tick scheme for the instrument.

Sets both the tick_scheme_name and the corresponding tick scheme implementation used for price rounding and tick calculations.

This will override any previously set tick scheme, including the tick_scheme_name field.

Parameters:

tick_scheme_name (str) – The name of the registered tick scheme.

Raises:

ValueError – If tick_scheme_name is not a valid string.
ValueError – If tick_scheme_name is not a registered tick scheme.

size_increment¶

The minimum size increment for the instrument.

Returns:: Quantity

size_precision¶

The size precision of the instrument.

Returns:: int

symbol¶

Return the instruments ticker symbol.

Return type:: Symbol

taker_fee¶

The fee rate for liquidity takers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

tick_scheme_name¶

The tick scheme name.

Returns:: str or None

static to_dict(BinaryOption obj) → dict[str, object]¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

ts_event¶

UNIX timestamp (nanoseconds) when the data event occurred.

Returns:: uint64_t

ts_init¶

UNIX timestamp (nanoseconds) when the object was initialized.

Returns:: uint64_t

venue¶

Return the instruments trading venue.

Return type:: Venue

class Cfd¶

Bases: Instrument

Represents a Contract for Difference (CFD) instrument.

Can represent both Fiat FX and Cryptocurrency pairs.

Parameters:

instrument_id (InstrumentId) – The instrument ID for the instrument.
raw_symbol (Symbol) – The raw/local/native symbol for the instrument, assigned by the venue.
asset_class (AssetClass) – The CFD contract asset class.
quote_currency (Currency) – The quote currency.
price_precision (int) – The price decimal precision.
size_precision (int) – The trading size decimal precision.
price_increment (Price) – The minimum price increment (tick size).
size_increment (Quantity) – The minimum size increment.
ts_event (uint64_t) – UNIX timestamp (nanoseconds) when the data event occurred.
ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the data object was initialized.
base_currency (Currency, optional) – The base currency.
lot_size (Quantity, optional) – The rounded lot unit size.
max_quantity (Quantity, optional) – The maximum allowable order quantity.
min_quantity (Quantity, optional) – The minimum allowable order quantity.
max_notional (Money, optional) – The maximum allowable order notional value.
min_notional (Money, optional) – The minimum allowable order notional value.
max_price (Price, optional) – The maximum allowable quoted price.
min_price (Price, optional) – The minimum allowable quoted price.
margin_init (Decimal, optional) – The initial (order) margin requirement in percentage of order value.
margin_maint (Decimal, optional) – The maintenance (position) margin in percentage of position value.
maker_fee (Decimal, optional) – The fee rate for liquidity makers as a percentage of order value.
taker_fee (Decimal, optional) – The fee rate for liquidity takers as a percentage of order value.
tick_scheme_name (str, optional) – The name of the tick scheme.
info (dict[str, object], optional) – The additional instrument information.

Raises:

ValueError – If tick_scheme_name is not a valid string.
ValueError – If price_precision is negative (< 0).
ValueError – If size_precision is negative (< 0).
ValueError – If price_increment is not positive (> 0).
ValueError – If size_increment is not positive (> 0).
ValueError – If price_precision is not equal to price_increment.precision.
ValueError – If size_increment is not equal to size_increment.precision.
ValueError – If lot_size is not positive (> 0).
ValueError – If max_quantity is not positive (> 0).
ValueError – If min_quantity is negative (< 0).
ValueError – If max_notional is not positive (> 0).
ValueError – If min_notional is negative (< 0).
ValueError – If max_price is not positive (> 0).
ValueError – If min_price is negative (< 0).
ValueError – If margin_init is negative (< 0).
ValueError – If margin_maint is negative (< 0).

References

asset_class¶

The asset class of the instrument.

Returns:: AssetClass

base_currency¶

The base currency for the instrument.

Returns:: Currency or None

static base_from_dict(dict values) → Instrument¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: Instrument

static base_to_dict(Instrument obj)¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

calculate_base_quantity(self, Quantity quantity, Price last_px) → Quantity¶

Calculate the base asset quantity from the given quote asset quantity and last price.

Parameters:

quantity (Quantity) – The quantity to convert from.
last_px (Price) – The last price for the instrument.

Return type:

static from_dict(dict values) → Cfd¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: Cfd

static from_pyo3(pyo3_instrument)¶

classmethod fully_qualified_name(cls) → str¶

Return the fully qualified name for the Data class.

Return type:: str

References

get_base_currency(self) → Currency¶

Return the instruments base currency (if applicable).

Return type:: Currency or None

get_cost_currency(self) → Currency¶

Return the currency used for PnL calculations for the instrument.

Standard linear instruments = quote_currency
Inverse instruments = base_currency
Quanto instruments TBD

Return type:: Currency

get_settlement_currency(self) → Currency¶

Return the currency used to settle a trade of the instrument.

Standard linear instruments = quote_currency
Inverse instruments = base_currency
Quanto instruments = settlement_currency

Return type:: Currency

id¶

The instrument ID.

Returns:: InstrumentId

info¶

The raw info for the instrument.

Returns:: dict[str, object]

instrument_class¶

The class of the instrument.

Returns:: InstrumentClass

is_inverse¶

If the quantity is expressed in quote currency.

Returns:: bool

classmethod is_signal(cls, str name='') → bool¶

Determine if the current class is a signal type, optionally checking for a specific signal name.

Parameters:: name (str, optional) – The specific signal name to check. If name not provided or if an empty string is passed, the method checks whether the class name indicates a general signal type. If name is provided, the method checks if the class name corresponds to that specific signal.
Returns:: True if the class name matches the signal type or the specific signal name, otherwise False.
Return type:: bool

is_spread(self) → bool¶

Return whether the instrument is a spread instrument.

Return type:: bool

isin¶

The instruments International Securities Identification Number (ISIN).

Returns:: str or None

legs(self) → list¶

Return the list of leg tuples (instrument_id, ratio) for this spread.

Base implementation returns an empty list. Override in spread instrument classes to return the actual legs.

Returns:: List of tuples containing (instrument_id, ratio) for each leg.
Return type:: list[tuple[InstrumentId, int]]

lot_size¶

The rounded lot unit size (standard/board) for the instrument.

Returns:: Quantity or None

make_price(self, value) → Price¶

Return a new price from the given value using the instruments price precision.

Parameters:: value (integer, float, str or Decimal) – The value of the price.
Return type:: Price

make_qty(self, value, bool round_down=False) → Quantity¶

Return a new quantity from the given value using the instruments size precision.

Parameters:

value (integer, float, str or Decimal) – The value of the quantity.
round_down (bool, default False) – If True, always rounds down to the nearest valid increment. If False, uses the round function (banker’s rounding) which rounds to the nearest even digit when exactly halfway between two values.

Return type:

Raises:

ValueError – If a non zero value is rounded to zero due to the instruments size increment or size precision.

maker_fee¶

The fee rate for liquidity makers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

margin_init¶

The initial (order) margin rate for the instrument.

Returns:: Decimal

margin_maint¶

The maintenance (position) margin rate for the instrument.

Returns:: Decimal

max_notional¶

The maximum notional order value for the instrument.

Returns:: Money or None

max_price¶

The maximum printable price for the instrument.

Returns:: Price or None

max_quantity¶

The maximum order quantity for the instrument.

Returns:: Quantity or None

min_notional¶

The minimum notional order value for the instrument.

Returns:: Money or None

min_price¶

The minimum printable price for the instrument.

Returns:: Price or None

min_quantity¶

The minimum order quantity for the instrument.

Returns:: Quantity or None

multiplier¶

The contract multiplier for the instrument (determines tick value).

Returns:: Quantity

next_ask_price(self, double value, int num_ticks=0) → Price¶

Return the price n ask ticks away from value.

If a given price is between two ticks, n=0 will find the nearest ask tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_ask_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks ask ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of ask prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_price(self, double value, int num_ticks=0) → Price¶

Return the price n bid ticks away from value.

If a given price is between two ticks, n=0 will find the nearest bid tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks bid ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of bid prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

notional_value(self, Quantity quantity, Price price, bool use_quote_for_inverse=False, Currency target_currency=None, Price conversion_price=None) → Money¶

Calculate the notional value.

Result will be in quote currency for standard instruments, or base currency for inverse instruments.

If target_currency and conversion_price are provided, the notional value will be converted to the target currency.

Parameters:

quantity (Quantity) – The total quantity.
price (Price) – The price for the calculation.
use_quote_for_inverse (bool) – If inverse instrument calculations use quote currency (instead of base).
target_currency (Currency, optional) – The target currency for conversion.
conversion_price (Price, optional) – The price to use for currency conversion.

Return type:

price_increment¶

The minimum price increment or tick size for the instrument.

Returns:: Price

price_precision¶

The price precision of the instrument.

Returns:: int

quote_currency¶

The quote currency for the instrument.

Returns:: Currency

raw_symbol¶

The raw/local/native symbol for the instrument, assigned by the venue.

Returns:: Symbol

set_tick_scheme(self, str tick_scheme_name) → void¶

Set the tick scheme for the instrument.

Sets both the tick_scheme_name and the corresponding tick scheme implementation used for price rounding and tick calculations.

This will override any previously set tick scheme, including the tick_scheme_name field.

Parameters:

tick_scheme_name (str) – The name of the registered tick scheme.

Raises:

ValueError – If tick_scheme_name is not a valid string.
ValueError – If tick_scheme_name is not a registered tick scheme.

size_increment¶

The minimum size increment for the instrument.

Returns:: Quantity

size_precision¶

The size precision of the instrument.

Returns:: int

symbol¶

Return the instruments ticker symbol.

Return type:: Symbol

taker_fee¶

The fee rate for liquidity takers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

tick_scheme_name¶

The tick scheme name.

Returns:: str or None

static to_dict(Cfd obj) → dict[str, object]¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

ts_event¶

UNIX timestamp (nanoseconds) when the data event occurred.

Returns:: uint64_t

ts_init¶

UNIX timestamp (nanoseconds) when the object was initialized.

Returns:: uint64_t

venue¶

Return the instruments trading venue.

Return type:: Venue

class Commodity¶

Bases: Instrument

Represents a commodity instrument in a spot/cash market.

Parameters:

instrument_id (InstrumentId) – The instrument ID for the instrument.
raw_symbol (Symbol) – The raw/local/native symbol for the instrument, assigned by the venue.
asset_class (AssetClass) – The Commodity contract asset class.
quote_currency (Currency) – The quote currency.
price_precision (int) – The price decimal precision.
size_precision (int) – The trading size decimal precision.
price_increment (Price) – The minimum price increment (tick size).
size_increment (Quantity) – The minimum size increment.
ts_event (uint64_t) – UNIX timestamp (nanoseconds) when the data event occurred.
ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the data object was initialized.
lot_size (Quantity, optional) – The rounded lot unit size.
max_quantity (Quantity, optional) – The maximum allowable order quantity.
min_quantity (Quantity, optional) – The minimum allowable order quantity.
max_notional (Money, optional) – The maximum allowable order notional value.
min_notional (Money, optional) – The minimum allowable order notional value.
max_price (Price, optional) – The maximum allowable quoted price.
min_price (Price, optional) – The minimum allowable quoted price.
margin_init (Decimal, optional) – The initial (order) margin requirement in percentage of order value.
margin_maint (Decimal, optional) – The maintenance (position) margin in percentage of position value.
maker_fee (Decimal, optional) – The fee rate for liquidity makers as a percentage of order value.
taker_fee (Decimal, optional) – The fee rate for liquidity takers as a percentage of order value.
tick_scheme_name (str, optional) – The name of the tick scheme.
info (dict[str, object], optional) – The additional instrument information.

Raises:

ValueError – If tick_scheme_name is not a valid string.
ValueError – If price_precision is negative (< 0).
ValueError – If size_precision is negative (< 0).
ValueError – If price_increment is not positive (> 0).
ValueError – If size_increment is not positive (> 0).
ValueError – If price_precision is not equal to price_increment.precision.
ValueError – If size_increment is not equal to size_increment.precision.
ValueError – If lot_size is not positive (> 0).
ValueError – If max_quantity is not positive (> 0).
ValueError – If min_quantity is negative (< 0).
ValueError – If max_notional is not positive (> 0).
ValueError – If min_notional is negative (< 0).
ValueError – If max_price is not positive (> 0).
ValueError – If min_price is negative (< 0).
ValueError – If margin_init is negative (< 0).
ValueError – If margin_maint is negative (< 0).

asset_class¶

The asset class of the instrument.

Returns:: AssetClass

static base_from_dict(dict values) → Instrument¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: Instrument

static base_to_dict(Instrument obj)¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

calculate_base_quantity(self, Quantity quantity, Price last_px) → Quantity¶

Calculate the base asset quantity from the given quote asset quantity and last price.

Parameters:

quantity (Quantity) – The quantity to convert from.
last_px (Price) – The last price for the instrument.

Return type:

static from_dict(dict values) → Commodity¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: Commodity

static from_pyo3(pyo3_instrument)¶

classmethod fully_qualified_name(cls) → str¶

Return the fully qualified name for the Data class.

Return type:: str

References

get_base_currency(self) → Currency¶

Return the instruments base currency (if applicable).

Return type:: Currency or None

get_cost_currency(self) → Currency¶

Return the currency used for PnL calculations for the instrument.

Standard linear instruments = quote_currency
Inverse instruments = base_currency
Quanto instruments TBD

Return type:: Currency

get_settlement_currency(self) → Currency¶

Return the currency used to settle a trade of the instrument.

Standard linear instruments = quote_currency
Inverse instruments = base_currency
Quanto instruments = settlement_currency

Return type:: Currency

id¶

The instrument ID.

Returns:: InstrumentId

info¶

The raw info for the instrument.

Returns:: dict[str, object]

instrument_class¶

The class of the instrument.

Returns:: InstrumentClass

is_inverse¶

If the quantity is expressed in quote currency.

Returns:: bool

classmethod is_signal(cls, str name='') → bool¶

Determine if the current class is a signal type, optionally checking for a specific signal name.

Parameters:: name (str, optional) – The specific signal name to check. If name not provided or if an empty string is passed, the method checks whether the class name indicates a general signal type. If name is provided, the method checks if the class name corresponds to that specific signal.
Returns:: True if the class name matches the signal type or the specific signal name, otherwise False.
Return type:: bool

is_spread(self) → bool¶

Return whether the instrument is a spread instrument.

Return type:: bool

isin¶

The instruments International Securities Identification Number (ISIN).

Returns:: str or None

legs(self) → list¶

Return the list of leg tuples (instrument_id, ratio) for this spread.

Base implementation returns an empty list. Override in spread instrument classes to return the actual legs.

Returns:: List of tuples containing (instrument_id, ratio) for each leg.
Return type:: list[tuple[InstrumentId, int]]

lot_size¶

The rounded lot unit size (standard/board) for the instrument.

Returns:: Quantity or None

make_price(self, value) → Price¶

Return a new price from the given value using the instruments price precision.

Parameters:: value (integer, float, str or Decimal) – The value of the price.
Return type:: Price

make_qty(self, value, bool round_down=False) → Quantity¶

Return a new quantity from the given value using the instruments size precision.

Parameters:

value (integer, float, str or Decimal) – The value of the quantity.
round_down (bool, default False) – If True, always rounds down to the nearest valid increment. If False, uses the round function (banker’s rounding) which rounds to the nearest even digit when exactly halfway between two values.

Return type:

Raises:

ValueError – If a non zero value is rounded to zero due to the instruments size increment or size precision.

maker_fee¶

The fee rate for liquidity makers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

margin_init¶

The initial (order) margin rate for the instrument.

Returns:: Decimal

margin_maint¶

The maintenance (position) margin rate for the instrument.

Returns:: Decimal

max_notional¶

The maximum notional order value for the instrument.

Returns:: Money or None

max_price¶

The maximum printable price for the instrument.

Returns:: Price or None

max_quantity¶

The maximum order quantity for the instrument.

Returns:: Quantity or None

min_notional¶

The minimum notional order value for the instrument.

Returns:: Money or None

min_price¶

The minimum printable price for the instrument.

Returns:: Price or None

min_quantity¶

The minimum order quantity for the instrument.

Returns:: Quantity or None

multiplier¶

The contract multiplier for the instrument (determines tick value).

Returns:: Quantity

next_ask_price(self, double value, int num_ticks=0) → Price¶

Return the price n ask ticks away from value.

If a given price is between two ticks, n=0 will find the nearest ask tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_ask_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks ask ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of ask prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_price(self, double value, int num_ticks=0) → Price¶

Return the price n bid ticks away from value.

If a given price is between two ticks, n=0 will find the nearest bid tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks bid ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of bid prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

notional_value(self, Quantity quantity, Price price, bool use_quote_for_inverse=False, Currency target_currency=None, Price conversion_price=None) → Money¶

Calculate the notional value.

Result will be in quote currency for standard instruments, or base currency for inverse instruments.

If target_currency and conversion_price are provided, the notional value will be converted to the target currency.

Parameters:

quantity (Quantity) – The total quantity.
price (Price) – The price for the calculation.
use_quote_for_inverse (bool) – If inverse instrument calculations use quote currency (instead of base).
target_currency (Currency, optional) – The target currency for conversion.
conversion_price (Price, optional) – The price to use for currency conversion.

Return type:

price_increment¶

The minimum price increment or tick size for the instrument.

Returns:: Price

price_precision¶

The price precision of the instrument.

Returns:: int

quote_currency¶

The quote currency for the instrument.

Returns:: Currency

raw_symbol¶

The raw/local/native symbol for the instrument, assigned by the venue.

Returns:: Symbol

set_tick_scheme(self, str tick_scheme_name) → void¶

Set the tick scheme for the instrument.

Sets both the tick_scheme_name and the corresponding tick scheme implementation used for price rounding and tick calculations.

This will override any previously set tick scheme, including the tick_scheme_name field.

Parameters:

tick_scheme_name (str) – The name of the registered tick scheme.

Raises:

ValueError – If tick_scheme_name is not a valid string.
ValueError – If tick_scheme_name is not a registered tick scheme.

size_increment¶

The minimum size increment for the instrument.

Returns:: Quantity

size_precision¶

The size precision of the instrument.

Returns:: int

symbol¶

Return the instruments ticker symbol.

Return type:: Symbol

taker_fee¶

The fee rate for liquidity takers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

tick_scheme_name¶

The tick scheme name.

Returns:: str or None

static to_dict(Commodity obj) → dict[str, object]¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

ts_event¶

UNIX timestamp (nanoseconds) when the data event occurred.

Returns:: uint64_t

ts_init¶

UNIX timestamp (nanoseconds) when the object was initialized.

Returns:: uint64_t

venue¶

Return the instruments trading venue.

Return type:: Venue

class CryptoFuture¶

Bases: Instrument

Represents a deliverable futures contract instrument, with crypto assets as underlying and for settlement.

Parameters:

instrument_id (InstrumentId) – The instrument ID for the instrument.
raw_symbol (Symbol) – The raw/local/native symbol for the instrument, assigned by the venue.
underlying (Currency) – The underlying asset.
quote_currency (Currency) – The contract quote currency.
settlement_currency (Currency) – The settlement currency.
is_inverse (bool) – If the instrument costing is inverse (quantity expressed in quote currency units).
activation_ns (uint64_t) – UNIX timestamp (nanoseconds) for contract activation.
expiration_ns (uint64_t) – UNIX timestamp (nanoseconds) for contract expiration.
price_precision (int) – The price decimal precision.
size_precision (int) – The trading size decimal precision.
price_increment (Price) – The minimum price increment (tick size).
size_increment (Quantity) – The minimum size increment.
ts_event (uint64_t) – UNIX timestamp (nanoseconds) when the data event occurred.
ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the data object was initialized.
multiplier (Quantity, default 1) – The contract multiplier.
lot_size (Quantity) – The rounded lot unit size (standard/board).
max_quantity (Quantity, optional) – The maximum allowable order quantity.
min_quantity (Quantity, optional) – The minimum allowable order quantity.
max_notional (Money, optional) – The maximum allowable order notional value.
min_notional (Money, optional) – The minimum allowable order notional value.
max_price (Price, optional) – The maximum allowable quoted price.
min_price (Price, optional) – The minimum allowable quoted price.
margin_init (Decimal, optional) – The initial (order) margin requirement in percentage of order value.
margin_maint (Decimal, optional) – The maintenance (position) margin in percentage of position value.
maker_fee (Decimal, optional) – The fee rate for liquidity makers as a percentage of order value.
taker_fee (Decimal, optional) – The fee rate for liquidity takers as a percentage of order value.
tick_scheme_name (str, optional) – The name of the tick scheme.
info (dict[str, object], optional) – The additional instrument information.

Raises:

ValueError – If price_precision is negative (< 0).
ValueError – If size_precision is negative (< 0).
ValueError – If price_increment is not positive (> 0).
ValueError – If size_increment is not positive (> 0).
ValueError – If price_precision is not equal to price_increment.precision.
ValueError – If size_increment is not equal to size_increment.precision.
ValueError – If lot size is not positive (> 0).
ValueError – If max_quantity is not positive (> 0).
ValueError – If min_quantity is negative (< 0).
ValueError – If max_notional is not positive (> 0).
ValueError – If min_notional is negative (< 0).
ValueError – If max_price is not positive (> 0).
ValueError – If min_price is negative (< 0).
ValueError – If margin_init is negative (< 0).
ValueError – If margin_maint is negative (< 0).

activation_ns¶

UNIX timestamp (nanoseconds) for contract activation.

Returns:: unit64_t

activation_utc¶

pd.Timestamp

Return the contract activation timestamp (UTC).

Returns:: tz-aware UTC.
Return type:: pd.Timestamp
Type:: CryptoFuture.activation_utc

asset_class¶

The asset class of the instrument.

Returns:: AssetClass

static base_from_dict(dict values) → Instrument¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: Instrument

static base_to_dict(Instrument obj)¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

calculate_base_quantity(self, Quantity quantity, Price last_px) → Quantity¶

Calculate the base asset quantity from the given quote asset quantity and last price.

Parameters:

quantity (Quantity) – The quantity to convert from.
last_px (Price) – The last price for the instrument.

Return type:

expiration_ns¶

UNIX timestamp (nanoseconds) for contract expiration.

Returns:: unit64_t

expiration_utc¶

pd.Timestamp

Return the contract expiration timestamp (UTC).

Returns:: tz-aware UTC.
Return type:: pd.Timestamp
Type:: CryptoFuture.expiration_utc

static from_dict(dict values) → CryptoFuture¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: CryptoFuture

static from_pyo3(pyo3_instrument)¶

Return legacy Cython crypto future instrument converted from the given pyo3 Rust object.

Parameters:: pyo3_instrument (nautilus_pyo3.CryptoFuture) – The pyo3 Rust option contract instrument to convert from.
Return type:: CryptoFuture

classmethod fully_qualified_name(cls) → str¶

Return the fully qualified name for the Data class.

Return type:: str

References

get_base_currency(self) → Currency¶

Return the instruments base currency (underlying).

Return type:: Currency

get_cost_currency(self) → Currency¶

Return the currency used for PnL calculations for the instrument.

Standard linear instruments = quote_currency
Inverse instruments = underlying (base currency)
Quanto instruments = settlement_currency

Return type:: Currency

get_settlement_currency(self) → Currency¶

Return the currency used to settle a trade of the instrument.

Return type:: Currency

id¶

The instrument ID.

Returns:: InstrumentId

info¶

The raw info for the instrument.

Returns:: dict[str, object]

instrument_class¶

The class of the instrument.

Returns:: InstrumentClass

is_inverse¶

If the quantity is expressed in quote currency.

Returns:: bool

is_quanto¶

If the instrument is quanto.

Returns:: bool

classmethod is_signal(cls, str name='') → bool¶

Determine if the current class is a signal type, optionally checking for a specific signal name.

Parameters:: name (str, optional) – The specific signal name to check. If name not provided or if an empty string is passed, the method checks whether the class name indicates a general signal type. If name is provided, the method checks if the class name corresponds to that specific signal.
Returns:: True if the class name matches the signal type or the specific signal name, otherwise False.
Return type:: bool

is_spread(self) → bool¶

Return whether the instrument is a spread instrument.

Return type:: bool

legs(self) → list¶

Return the list of leg tuples (instrument_id, ratio) for this spread.

Base implementation returns an empty list. Override in spread instrument classes to return the actual legs.

Returns:: List of tuples containing (instrument_id, ratio) for each leg.
Return type:: list[tuple[InstrumentId, int]]

lot_size¶

The rounded lot unit size (standard/board) for the instrument.

Returns:: Quantity or None

make_price(self, value) → Price¶

Return a new price from the given value using the instruments price precision.

Parameters:: value (integer, float, str or Decimal) – The value of the price.
Return type:: Price

make_qty(self, value, bool round_down=False) → Quantity¶

Return a new quantity from the given value using the instruments size precision.

Parameters:

value (integer, float, str or Decimal) – The value of the quantity.
round_down (bool, default False) – If True, always rounds down to the nearest valid increment. If False, uses the round function (banker’s rounding) which rounds to the nearest even digit when exactly halfway between two values.

Return type:

Raises:

ValueError – If a non zero value is rounded to zero due to the instruments size increment or size precision.

maker_fee¶

The fee rate for liquidity makers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

margin_init¶

The initial (order) margin rate for the instrument.

Returns:: Decimal

margin_maint¶

The maintenance (position) margin rate for the instrument.

Returns:: Decimal

max_notional¶

The maximum notional order value for the instrument.

Returns:: Money or None

max_price¶

The maximum printable price for the instrument.

Returns:: Price or None

max_quantity¶

The maximum order quantity for the instrument.

Returns:: Quantity or None

min_notional¶

The minimum notional order value for the instrument.

Returns:: Money or None

min_price¶

The minimum printable price for the instrument.

Returns:: Price or None

min_quantity¶

The minimum order quantity for the instrument.

Returns:: Quantity or None

multiplier¶

The contract multiplier for the instrument (determines tick value).

Returns:: Quantity

next_ask_price(self, double value, int num_ticks=0) → Price¶

Return the price n ask ticks away from value.

If a given price is between two ticks, n=0 will find the nearest ask tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_ask_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks ask ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of ask prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_price(self, double value, int num_ticks=0) → Price¶

Return the price n bid ticks away from value.

If a given price is between two ticks, n=0 will find the nearest bid tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks bid ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of bid prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

notional_value(self, Quantity quantity, Price price, bool use_quote_for_inverse=False, Currency target_currency=None, Price conversion_price=None) → Money¶

Calculate the notional value.

Result will be in quote currency for standard instruments, underlying currency for inverse instruments, or settlement currency for quanto instruments.

Parameters:

quantity (Quantity) – The total quantity.
price (Price) – The price for the calculation.
use_quote_for_inverse (bool) – For inverse instruments only: if True, treats the quantity as already representing notional value in quote currency and returns it directly without calculation. This is useful when quantity already represents a USD value that doesn’t need conversion (e.g., for display purposes). Has no effect on linear or quanto instruments.
target_currency (Currency, optional) – The target currency for conversion.
conversion_price (Price, optional) – The conversion price to the target currency.

Return type:

price_increment¶

The minimum price increment or tick size for the instrument.

Returns:: Price

price_precision¶

The price precision of the instrument.

Returns:: int

quote_currency¶

The quote currency for the instrument.

Returns:: Currency

raw_symbol¶

The raw/local/native symbol for the instrument, assigned by the venue.

Returns:: Symbol

set_tick_scheme(self, str tick_scheme_name) → void¶

Set the tick scheme for the instrument.

Sets both the tick_scheme_name and the corresponding tick scheme implementation used for price rounding and tick calculations.

This will override any previously set tick scheme, including the tick_scheme_name field.

Parameters:

tick_scheme_name (str) – The name of the registered tick scheme.

Raises:

ValueError – If tick_scheme_name is not a valid string.
ValueError – If tick_scheme_name is not a registered tick scheme.

settlement_currency¶

The settlement currency for the contract.

Returns:: Currency

size_increment¶

The minimum size increment for the instrument.

Returns:: Quantity

size_precision¶

The size precision of the instrument.

Returns:: int

symbol¶

Return the instruments ticker symbol.

Return type:: Symbol

taker_fee¶

The fee rate for liquidity takers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

tick_scheme_name¶

The tick scheme name.

Returns:: str or None

static to_dict(CryptoFuture obj) → dict[str, object]¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

ts_event¶

UNIX timestamp (nanoseconds) when the data event occurred.

Returns:: uint64_t

ts_init¶

UNIX timestamp (nanoseconds) when the object was initialized.

Returns:: uint64_t

underlying¶

The underlying asset for the contract.

Returns:: Currency

venue¶

Return the instruments trading venue.

Return type:: Venue

class CryptoOption¶

Bases: Instrument

Represents an option instrument with crypto assets as underlying and for settlement.

Parameters:

instrument_id (InstrumentId) – The instrument ID.
raw_symbol (Symbol) – The raw/local/native symbol for the instrument, assigned by the venue.
underlying (Currency) – The underlying asset.
quote_currency (Currency) – The contract quote currency.
settlement_currency (Currency) – The settlement currency.
is_inverse (bool) – If the instrument costing is inverse (quantity expressed in quote currency units).
option_kind (OptionKind) – The kind of option (PUT | CALL).
strike_price (Price) – The option strike price.
activation_ns (uint64_t) – UNIX timestamp (nanoseconds) for contract activation.
expiration_ns (uint64_t) – UNIX timestamp (nanoseconds) for contract expiration.
price_precision (int) – The price decimal precision.
size_precision (int) – The trading size decimal precision.
price_increment (Price) – The minimum price increment (tick size).
size_increment (Quantity) – The minimum size increment.
ts_event (uint64_t) – UNIX timestamp (nanoseconds) when the data event occurred.
ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the data object was initialized.
multiplier (Quantity, default 1) – The contract multiplier.
lot_size (Quantity, default 1) – The rounded lot unit size (standard/board).
max_quantity (Quantity, optional) – The maximum allowable order quantity.
min_quantity (Quantity, optional) – The minimum allowable order quantity.
max_notional (Money, optional) – The maximum allowable order notional value.
min_notional (Money, optional) – The minimum allowable order notional value.
max_price (Price, optional) – The maximum allowable quoted price.
min_price (Price, optional) – The minimum allowable quoted price.
margin_init (Decimal, optional) – The initial (order) margin requirement in percentage of order value.
margin_maint (Decimal, optional) – The maintenance (position) margin in percentage of position value.
maker_fee (Decimal, optional) – The fee rate for liquidity makers as a percentage of order value.
taker_fee (Decimal, optional) – The fee rate for liquidity takers as a percentage of order value.
tick_scheme_name (str, optional) – The name of the tick scheme.
info (dict[str, object], optional) – The additional instrument information.

Raises:

ValueError – If price_precision is negative (< 0).
ValueError – If size_precision is negative (< 0).
ValueError – If price_increment is not positive (> 0).
ValueError – If size_increment is not positive (> 0).
ValueError – If lot size is not positive (> 0).
ValueError – If max_quantity is not positive (> 0).
ValueError – If min_quantity is negative (< 0).
ValueError – If max_notional is not positive (> 0).
ValueError – If min_notional is negative (< 0).
ValueError – If max_price is not positive (> 0).
ValueError – If min_price is negative (< 0).
ValueError – If margin_init is negative (< 0).
ValueError – If margin_maint is negative (< 0).

activation_ns¶

UNIX timestamp (nanoseconds) for contract activation.

Returns:: unit64_t

activation_utc¶

pd.Timestamp

Return the contract activation timestamp (UTC).

Returns:: tz-aware UTC.
Return type:: pd.Timestamp
Type:: CryptoOption.activation_utc

asset_class¶

The asset class of the instrument.

Returns:: AssetClass

static base_from_dict(dict values) → Instrument¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: Instrument

static base_to_dict(Instrument obj)¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

calculate_base_quantity(self, Quantity quantity, Price last_px) → Quantity¶

Calculate the base asset quantity from the given quote asset quantity and last price.

Parameters:

quantity (Quantity) – The quantity to convert from.
last_px (Price) – The last price for the instrument.

Return type:

expiration_ns¶

UNIX timestamp (nanoseconds) for contract expiration.

Returns:: unit64_t

expiration_utc¶

pd.Timestamp

Return the contract expiration timestamp (UTC).

Returns:: tz-aware UTC.
Return type:: pd.Timestamp
Type:: CryptoOption.expiration_utc

static from_dict(dict values) → CryptoOption¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: CryptoOption

static from_pyo3(pyo3_instrument) → CryptoOption¶

Return legacy Cython option contract instrument converted from the given pyo3 Rust object.

Parameters:: pyo3_instrument (nautilus_pyo3.CryptoOption) – The pyo3 Rust option contract instrument to convert from.
Return type:: CryptoOption

classmethod fully_qualified_name(cls) → str¶

Return the fully qualified name for the Data class.

Return type:: str

References

get_base_currency(self) → Currency¶

Return the instruments base currency (underlying).

Return type:: Currency

get_cost_currency(self) → Currency¶

Return the currency used for PnL calculations for the instrument.

Standard linear instruments = quote_currency
Inverse instruments = underlying (base currency)

Return type:: Currency

get_settlement_currency(self) → Currency¶

Return the currency used to settle a trade of the instrument.

Return type:: Currency

id¶

The instrument ID.

Returns:: InstrumentId

info¶

The raw info for the instrument.

Returns:: dict[str, object]

instrument_class¶

The class of the instrument.

Returns:: InstrumentClass

is_inverse¶

If the quantity is expressed in quote currency.

Returns:: bool

classmethod is_signal(cls, str name='') → bool¶

Determine if the current class is a signal type, optionally checking for a specific signal name.

Parameters:: name (str, optional) – The specific signal name to check. If name not provided or if an empty string is passed, the method checks whether the class name indicates a general signal type. If name is provided, the method checks if the class name corresponds to that specific signal.
Returns:: True if the class name matches the signal type or the specific signal name, otherwise False.
Return type:: bool

is_spread(self) → bool¶

Return whether the instrument is a spread instrument.

Return type:: bool

legs(self) → list¶

Return the list of leg tuples (instrument_id, ratio) for this spread.

Base implementation returns an empty list. Override in spread instrument classes to return the actual legs.

Returns:: List of tuples containing (instrument_id, ratio) for each leg.
Return type:: list[tuple[InstrumentId, int]]

lot_size¶

The rounded lot unit size (standard/board) for the instrument.

Returns:: Quantity or None

make_price(self, value) → Price¶

Return a new price from the given value using the instruments price precision.

Parameters:: value (integer, float, str or Decimal) – The value of the price.
Return type:: Price

make_qty(self, value, bool round_down=False) → Quantity¶

Return a new quantity from the given value using the instruments size precision.

Parameters:

value (integer, float, str or Decimal) – The value of the quantity.
round_down (bool, default False) – If True, always rounds down to the nearest valid increment. If False, uses the round function (banker’s rounding) which rounds to the nearest even digit when exactly halfway between two values.

Return type:

Raises:

ValueError – If a non zero value is rounded to zero due to the instruments size increment or size precision.

maker_fee¶

The fee rate for liquidity makers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

margin_init¶

The initial (order) margin rate for the instrument.

Returns:: Decimal

margin_maint¶

The maintenance (position) margin rate for the instrument.

Returns:: Decimal

max_notional¶

The maximum notional order value for the instrument.

Returns:: Money or None

max_price¶

The maximum printable price for the instrument.

Returns:: Price or None

max_quantity¶

The maximum order quantity for the instrument.

Returns:: Quantity or None

min_notional¶

The minimum notional order value for the instrument.

Returns:: Money or None

min_price¶

The minimum printable price for the instrument.

Returns:: Price or None

min_quantity¶

The minimum order quantity for the instrument.

Returns:: Quantity or None

multiplier¶

The contract multiplier for the instrument (determines tick value).

Returns:: Quantity

next_ask_price(self, double value, int num_ticks=0) → Price¶

Return the price n ask ticks away from value.

If a given price is between two ticks, n=0 will find the nearest ask tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_ask_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks ask ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of ask prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_price(self, double value, int num_ticks=0) → Price¶

Return the price n bid ticks away from value.

If a given price is between two ticks, n=0 will find the nearest bid tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks bid ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of bid prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

notional_value(self, Quantity quantity, Price price, bool use_quote_for_inverse=False, Currency target_currency=None, Price conversion_price=None) → Money¶

Calculate the notional value.

Result will be in quote currency for standard instruments, or underlying currency for inverse instruments.

Parameters:

quantity (Quantity) – The total quantity.
price (Price) – The price for the calculation.
use_quote_for_inverse (bool) – For inverse instruments only: if True, treats the quantity as already representing notional value in quote currency and returns it directly without calculation. This is useful when quantity already represents a USD value that doesn’t need conversion (e.g., for display purposes). Has no effect on linear instruments.
target_currency (Currency, optional) – The target currency for conversion.
conversion_price (Price, optional) – The conversion price to the target currency.

Return type:

option_kind¶

The option kind (PUT | CALL) for the contract.

Returns:: OptionKind

price_increment¶

The minimum price increment or tick size for the instrument.

Returns:: Price

price_precision¶

The price precision of the instrument.

Returns:: int

quote_currency¶

The quote currency for the instrument.

Returns:: Currency

raw_symbol¶

The raw/local/native symbol for the instrument, assigned by the venue.

Returns:: Symbol

set_tick_scheme(self, str tick_scheme_name) → void¶

Set the tick scheme for the instrument.

Sets both the tick_scheme_name and the corresponding tick scheme implementation used for price rounding and tick calculations.

This will override any previously set tick scheme, including the tick_scheme_name field.

Parameters:

tick_scheme_name (str) – The name of the registered tick scheme.

Raises:

ValueError – If tick_scheme_name is not a valid string.
ValueError – If tick_scheme_name is not a registered tick scheme.

settlement_currency¶

The settlement currency for the instrument.

Returns:: Currency

size_increment¶

The minimum size increment for the instrument.

Returns:: Quantity

size_precision¶

The size precision of the instrument.

Returns:: int

strike_price¶

The strike price for the contract.

Returns:: Price

symbol¶

Return the instruments ticker symbol.

Return type:: Symbol

taker_fee¶

The fee rate for liquidity takers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

tick_scheme_name¶

The tick scheme name.

Returns:: str or None

static to_dict(CryptoOption obj) → dict[str, object]¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

ts_event¶

UNIX timestamp (nanoseconds) when the data event occurred.

Returns:: uint64_t

ts_init¶

UNIX timestamp (nanoseconds) when the object was initialized.

Returns:: uint64_t

underlying¶

The underlying asset for the contract.

Returns:: str

venue¶

Return the instruments trading venue.

Return type:: Venue

class CryptoPerpetual¶

Bases: Instrument

Represents a crypto perpetual futures contract instrument (a.k.a. perpetual swap).

Parameters:

instrument_id (InstrumentId) – The instrument ID for the instrument.
raw_symbol (Symbol) – The raw/local/native symbol for the instrument, assigned by the venue.
base_currency (Currency, optional) – The base currency.
quote_currency (Currency) – The quote currency.
settlement_currency (Currency) – The settlement currency.
is_inverse (bool) – If the instrument costing is inverse (quantity expressed in quote currency units).
price_precision (int) – The price decimal precision.
size_precision (int) – The trading size decimal precision.
price_increment (Price) – The minimum price increment (tick size).
size_increment (Quantity) – The minimum size increment.
ts_event (uint64_t) – UNIX timestamp (nanoseconds) when the data event occurred.
ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the data object was initialized.
multiplier (Quantity, default 1) – The contract multiplier.
lot_size (Quantity, default 1) – The rounded lot unit size (standard/board).
max_quantity (Quantity, optional) – The maximum allowable order quantity.
min_quantity (Quantity, optional) – The minimum allowable order quantity.
max_notional (Money, optional) – The maximum allowable order notional value.
min_notional (Money, optional) – The minimum allowable order notional value.
max_price (Price, optional) – The maximum allowable quoted price.
min_price (Price, optional) – The minimum allowable quoted price.
margin_init (Decimal, optional) – The initial (order) margin requirement in percentage of order value.
margin_maint (Decimal, optional) – The maintenance (position) margin in percentage of position value.
maker_fee (Decimal, optional) – The fee rate for liquidity makers as a percentage of order value.
taker_fee (Decimal, optional) – The fee rate for liquidity takers as a percentage of order value.
tick_scheme_name (str, optional) – The name of the tick scheme.
info (dict[str, object], optional) – The additional instrument information.

Raises:

ValueError – If price_precision is negative (< 0).
ValueError – If size_precision is negative (< 0).
ValueError – If price_increment is not positive (> 0).
ValueError – If size_increment is not positive (> 0).
ValueError – If price_precision is not equal to price_increment.precision.
ValueError – If size_increment is not equal to size_increment.precision.
ValueError – If multiplier is not positive (> 0).
ValueError – If max_quantity is not positive (> 0).
ValueError – If min_quantity is negative (< 0).
ValueError – If max_notional is not positive (> 0).
ValueError – If min_notional is negative (< 0).
ValueError – If max_price is not positive (> 0).
ValueError – If min_price is negative (< 0).
ValueError – If margin_init is negative (< 0).
ValueError – If margin_maint is negative (< 0).

asset_class¶

The asset class of the instrument.

Returns:: AssetClass

base_currency¶

The base currency for the instrument.

Returns:: Currency

static base_from_dict(dict values) → Instrument¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: Instrument

static base_to_dict(Instrument obj)¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

calculate_base_quantity(self, Quantity quantity, Price last_px) → Quantity¶

Calculate the base asset quantity from the given quote asset quantity and last price.

Parameters:

quantity (Quantity) – The quantity to convert from.
last_px (Price) – The last price for the instrument.

Return type:

static from_dict(dict values) → CryptoPerpetual¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: CryptoPerpetual

static from_pyo3(pyo3_instrument)¶

classmethod fully_qualified_name(cls) → str¶

Return the fully qualified name for the Data class.

Return type:: str

References

get_base_currency(self) → Currency¶

Return the instruments base currency.

Return type:: Currency

get_cost_currency(self) → Currency¶

Return the currency used for PnL calculations for the instrument.

Standard linear instruments = quote_currency
Inverse instruments = base_currency
Quanto instruments = settlement_currency

Return type:: Currency

get_settlement_currency(self) → Currency¶

Return the currency used to settle a trade of the instrument.

Return type:: Currency

id¶

The instrument ID.

Returns:: InstrumentId

info¶

The raw info for the instrument.

Returns:: dict[str, object]

instrument_class¶

The class of the instrument.

Returns:: InstrumentClass

is_inverse¶

If the quantity is expressed in quote currency.

Returns:: bool

is_quanto¶

If the instrument is quanto.

Returns:: bool

classmethod is_signal(cls, str name='') → bool¶

Determine if the current class is a signal type, optionally checking for a specific signal name.

Parameters:: name (str, optional) – The specific signal name to check. If name not provided or if an empty string is passed, the method checks whether the class name indicates a general signal type. If name is provided, the method checks if the class name corresponds to that specific signal.
Returns:: True if the class name matches the signal type or the specific signal name, otherwise False.
Return type:: bool

is_spread(self) → bool¶

Return whether the instrument is a spread instrument.

Return type:: bool

legs(self) → list¶

Return the list of leg tuples (instrument_id, ratio) for this spread.

Base implementation returns an empty list. Override in spread instrument classes to return the actual legs.

Returns:: List of tuples containing (instrument_id, ratio) for each leg.
Return type:: list[tuple[InstrumentId, int]]

lot_size¶

The rounded lot unit size (standard/board) for the instrument.

Returns:: Quantity or None

make_price(self, value) → Price¶

Return a new price from the given value using the instruments price precision.

Parameters:: value (integer, float, str or Decimal) – The value of the price.
Return type:: Price

make_qty(self, value, bool round_down=False) → Quantity¶

Return a new quantity from the given value using the instruments size precision.

Parameters:

value (integer, float, str or Decimal) – The value of the quantity.
round_down (bool, default False) – If True, always rounds down to the nearest valid increment. If False, uses the round function (banker’s rounding) which rounds to the nearest even digit when exactly halfway between two values.

Return type:

Raises:

ValueError – If a non zero value is rounded to zero due to the instruments size increment or size precision.

maker_fee¶

The fee rate for liquidity makers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

margin_init¶

The initial (order) margin rate for the instrument.

Returns:: Decimal

margin_maint¶

The maintenance (position) margin rate for the instrument.

Returns:: Decimal

max_notional¶

The maximum notional order value for the instrument.

Returns:: Money or None

max_price¶

The maximum printable price for the instrument.

Returns:: Price or None

max_quantity¶

The maximum order quantity for the instrument.

Returns:: Quantity or None

min_notional¶

The minimum notional order value for the instrument.

Returns:: Money or None

min_price¶

The minimum printable price for the instrument.

Returns:: Price or None

min_quantity¶

The minimum order quantity for the instrument.

Returns:: Quantity or None

multiplier¶

The contract multiplier for the instrument (determines tick value).

Returns:: Quantity

next_ask_price(self, double value, int num_ticks=0) → Price¶

Return the price n ask ticks away from value.

If a given price is between two ticks, n=0 will find the nearest ask tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_ask_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks ask ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of ask prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_price(self, double value, int num_ticks=0) → Price¶

Return the price n bid ticks away from value.

If a given price is between two ticks, n=0 will find the nearest bid tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks bid ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of bid prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

notional_value(self, Quantity quantity, Price price, bool use_quote_for_inverse=False, Currency target_currency=None, Price conversion_price=None) → Money¶

Calculate the notional value.

Result will be in quote currency for standard instruments, base currency for inverse instruments, or settlement currency for quanto instruments.

Parameters:

quantity (Quantity) – The total quantity.
price (Price) – The price for the calculation.
use_quote_for_inverse (bool) – For inverse instruments only: if True, treats the quantity as already representing notional value in quote currency and returns it directly without calculation. This is useful when quantity already represents a USD value that doesn’t need conversion (e.g., for display purposes). Has no effect on linear or quanto instruments.
target_currency (Currency, optional) – The target currency for conversion.
conversion_price (Price, optional) – The conversion price to the target currency.

Return type:

price_increment¶

The minimum price increment or tick size for the instrument.

Returns:: Price

price_precision¶

The price precision of the instrument.

Returns:: int

quote_currency¶

The quote currency for the instrument.

Returns:: Currency

raw_symbol¶

The raw/local/native symbol for the instrument, assigned by the venue.

Returns:: Symbol

set_tick_scheme(self, str tick_scheme_name) → void¶

Set the tick scheme for the instrument.

Sets both the tick_scheme_name and the corresponding tick scheme implementation used for price rounding and tick calculations.

This will override any previously set tick scheme, including the tick_scheme_name field.

Parameters:

tick_scheme_name (str) – The name of the registered tick scheme.

Raises:

ValueError – If tick_scheme_name is not a valid string.
ValueError – If tick_scheme_name is not a registered tick scheme.

settlement_currency¶

The settlement currency for the instrument.

Returns:: Currency

size_increment¶

The minimum size increment for the instrument.

Returns:: Quantity

size_precision¶

The size precision of the instrument.

Returns:: int

symbol¶

Return the instruments ticker symbol.

Return type:: Symbol

taker_fee¶

The fee rate for liquidity takers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

tick_scheme_name¶

The tick scheme name.

Returns:: str or None

static to_dict(CryptoPerpetual obj) → dict[str, object]¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

ts_event¶

UNIX timestamp (nanoseconds) when the data event occurred.

Returns:: uint64_t

ts_init¶

UNIX timestamp (nanoseconds) when the object was initialized.

Returns:: uint64_t

venue¶

Return the instruments trading venue.

Return type:: Venue

class CurrencyPair¶

Bases: Instrument

Represents a generic currency pair instrument in a spot/cash market.

Can represent both Fiat FX and Cryptocurrency pairs.

Parameters:

instrument_id (InstrumentId) – The instrument ID for the instrument.
raw_symbol (Symbol) – The raw/local/native symbol for the instrument, assigned by the venue.
base_currency (Currency) – The base currency.
quote_currency (Currency) – The quote currency.
price_precision (int) – The price decimal precision.
size_precision (int) – The trading size decimal precision.
price_increment (Price) – The minimum price increment (tick size).
size_increment (Quantity) – The minimum size increment.
ts_event (uint64_t) – UNIX timestamp (nanoseconds) when the data event occurred.
ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the data object was initialized.
multiplier (Quantity, default 1) – The contract multiplier.
lot_size (Quantity, optional) – The rounded lot unit size.
max_quantity (Quantity, optional) – The maximum allowable order quantity.
min_quantity (Quantity, optional) – The minimum allowable order quantity.
max_notional (Money, optional) – The maximum allowable order notional value.
min_notional (Money, optional) – The minimum allowable order notional value.
max_price (Price, optional) – The maximum allowable quoted price.
min_price (Price, optional) – The minimum allowable quoted price.
margin_init (Decimal, optional) – The initial (order) margin requirement in percentage of order value.
margin_maint (Decimal, optional) – The maintenance (position) margin in percentage of position value.
maker_fee (Decimal, optional) – The fee rate for liquidity makers as a percentage of order value.
taker_fee (Decimal, optional) – The fee rate for liquidity takers as a percentage of order value.
tick_scheme_name (str, optional) – The name of the tick scheme.
info (dict[str, object], optional) – The additional instrument information.

Raises:

ValueError – If tick_scheme_name is not a valid string.
ValueError – If price_precision is negative (< 0).
ValueError – If size_precision is negative (< 0).
ValueError – If price_increment is not positive (> 0).
ValueError – If size_increment is not positive (> 0).
ValueError – If price_precision is not equal to price_increment.precision.
ValueError – If size_increment is not equal to size_increment.precision.
ValueError – If lot_size is not positive (> 0).
ValueError – If max_quantity is not positive (> 0).
ValueError – If min_quantity is negative (< 0).
ValueError – If max_notional is not positive (> 0).
ValueError – If min_notional is negative (< 0).
ValueError – If max_price is not positive (> 0).
ValueError – If min_price is negative (< 0).
ValueError – If margin_init is negative (< 0).
ValueError – If margin_maint is negative (< 0).

asset_class¶

The asset class of the instrument.

Returns:: AssetClass

base_currency¶

The base currency for the instrument.

Returns:: Currency

static base_from_dict(dict values) → Instrument¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: Instrument

static base_to_dict(Instrument obj)¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

calculate_base_quantity(self, Quantity quantity, Price last_px) → Quantity¶

Calculate the base asset quantity from the given quote asset quantity and last price.

Parameters:

quantity (Quantity) – The quantity to convert from.
last_px (Price) – The last price for the instrument.

Return type:

static from_dict(dict values) → CurrencyPair¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: CurrencyPair

static from_pyo3(pyo3_instrument)¶

classmethod fully_qualified_name(cls) → str¶

Return the fully qualified name for the Data class.

Return type:: str

References

get_base_currency(self) → Currency¶

Return the instruments base currency.

Return type:: Currency

get_cost_currency(self) → Currency¶

Return the currency used for PnL calculations for the instrument.

Standard linear instruments = quote_currency
Inverse instruments = base_currency
Quanto instruments TBD

Return type:: Currency

get_settlement_currency(self) → Currency¶

Return the currency used to settle a trade of the instrument.

Standard linear instruments = quote_currency
Inverse instruments = base_currency
Quanto instruments = settlement_currency

Return type:: Currency

id¶

The instrument ID.

Returns:: InstrumentId

info¶

The raw info for the instrument.

Returns:: dict[str, object]

instrument_class¶

The class of the instrument.

Returns:: InstrumentClass

is_inverse¶

If the quantity is expressed in quote currency.

Returns:: bool

classmethod is_signal(cls, str name='') → bool¶

Determine if the current class is a signal type, optionally checking for a specific signal name.

Parameters:: name (str, optional) – The specific signal name to check. If name not provided or if an empty string is passed, the method checks whether the class name indicates a general signal type. If name is provided, the method checks if the class name corresponds to that specific signal.
Returns:: True if the class name matches the signal type or the specific signal name, otherwise False.
Return type:: bool

is_spread(self) → bool¶

Return whether the instrument is a spread instrument.

Return type:: bool

legs(self) → list¶

Return the list of leg tuples (instrument_id, ratio) for this spread.

Base implementation returns an empty list. Override in spread instrument classes to return the actual legs.

Returns:: List of tuples containing (instrument_id, ratio) for each leg.
Return type:: list[tuple[InstrumentId, int]]

lot_size¶

The rounded lot unit size (standard/board) for the instrument.

Returns:: Quantity or None

make_price(self, value) → Price¶

Return a new price from the given value using the instruments price precision.

Parameters:: value (integer, float, str or Decimal) – The value of the price.
Return type:: Price

make_qty(self, value, bool round_down=False) → Quantity¶

Return a new quantity from the given value using the instruments size precision.

Parameters:

value (integer, float, str or Decimal) – The value of the quantity.
round_down (bool, default False) – If True, always rounds down to the nearest valid increment. If False, uses the round function (banker’s rounding) which rounds to the nearest even digit when exactly halfway between two values.

Return type:

Raises:

ValueError – If a non zero value is rounded to zero due to the instruments size increment or size precision.

maker_fee¶

The fee rate for liquidity makers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

margin_init¶

The initial (order) margin rate for the instrument.

Returns:: Decimal

margin_maint¶

The maintenance (position) margin rate for the instrument.

Returns:: Decimal

max_notional¶

The maximum notional order value for the instrument.

Returns:: Money or None

max_price¶

The maximum printable price for the instrument.

Returns:: Price or None

max_quantity¶

The maximum order quantity for the instrument.

Returns:: Quantity or None

min_notional¶

The minimum notional order value for the instrument.

Returns:: Money or None

min_price¶

The minimum printable price for the instrument.

Returns:: Price or None

min_quantity¶

The minimum order quantity for the instrument.

Returns:: Quantity or None

multiplier¶

The contract multiplier for the instrument (determines tick value).

Returns:: Quantity

next_ask_price(self, double value, int num_ticks=0) → Price¶

Return the price n ask ticks away from value.

If a given price is between two ticks, n=0 will find the nearest ask tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_ask_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks ask ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of ask prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_price(self, double value, int num_ticks=0) → Price¶

Return the price n bid ticks away from value.

If a given price is between two ticks, n=0 will find the nearest bid tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks bid ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of bid prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

notional_value(self, Quantity quantity, Price price, bool use_quote_for_inverse=False, Currency target_currency=None, Price conversion_price=None) → Money¶

Calculate the notional value.

Result will be in quote currency for standard instruments, or base currency for inverse instruments.

If target_currency and conversion_price are provided, the notional value will be converted to the target currency.

Parameters:

quantity (Quantity) – The total quantity.
price (Price) – The price for the calculation.
use_quote_for_inverse (bool) – If inverse instrument calculations use quote currency (instead of base).
target_currency (Currency, optional) – The target currency for conversion.
conversion_price (Price, optional) – The price to use for currency conversion.

Return type:

price_increment¶

The minimum price increment or tick size for the instrument.

Returns:: Price

price_precision¶

The price precision of the instrument.

Returns:: int

quote_currency¶

The quote currency for the instrument.

Returns:: Currency

raw_symbol¶

The raw/local/native symbol for the instrument, assigned by the venue.

Returns:: Symbol

set_tick_scheme(self, str tick_scheme_name) → void¶

Set the tick scheme for the instrument.

Sets both the tick_scheme_name and the corresponding tick scheme implementation used for price rounding and tick calculations.

This will override any previously set tick scheme, including the tick_scheme_name field.

Parameters:

tick_scheme_name (str) – The name of the registered tick scheme.

Raises:

ValueError – If tick_scheme_name is not a valid string.
ValueError – If tick_scheme_name is not a registered tick scheme.

size_increment¶

The minimum size increment for the instrument.

Returns:: Quantity

size_precision¶

The size precision of the instrument.

Returns:: int

symbol¶

Return the instruments ticker symbol.

Return type:: Symbol

taker_fee¶

The fee rate for liquidity takers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

tick_scheme_name¶

The tick scheme name.

Returns:: str or None

static to_dict(CurrencyPair obj) → dict[str, object]¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

ts_event¶

UNIX timestamp (nanoseconds) when the data event occurred.

Returns:: uint64_t

ts_init¶

UNIX timestamp (nanoseconds) when the object was initialized.

Returns:: uint64_t

venue¶

Return the instruments trading venue.

Return type:: Venue

class Equity¶

Bases: Instrument

Represents a generic equity instrument.

Parameters:

instrument_id (InstrumentId) – The instrument ID.
raw_symbol (Symbol) – The raw/local/native symbol for the instrument, assigned by the venue.
currency (Currency) – The futures contract currency.
price_precision (int) – The price decimal precision.
price_increment (Decimal) – The minimum price increment (tick size).
lot_size (Quantity) – The rounded lot unit size (standard/board).
ts_event (uint64_t) – UNIX timestamp (nanoseconds) when the data event occurred.
ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the data object was initialized.
margin_init (Decimal, optional) – The initial (order) margin requirement in percentage of order value.
margin_maint (Decimal, optional) – The maintenance (position) margin in percentage of position value.
maker_fee (Decimal, optional) – The fee rate for liquidity makers as a percentage of order value.
taker_fee (Decimal, optional) – The fee rate for liquidity takers as a percentage of order value.
isin (str, optional) – The instruments International Securities Identification Number (ISIN).
tick_scheme_name (str, optional) – The name of the tick scheme.
info (dict[str, object], optional) – The additional instrument information.

Raises:

ValueError – If price_precision is negative (< 0).
ValueError – If price_increment is not positive (> 0).
ValueError – If lot_size is not positive (> 0).
ValueError – If margin_init is negative (< 0).
ValueError – If margin_maint is negative (< 0).
ValueError – If isin is not None and not a valid string.

asset_class¶

The asset class of the instrument.

Returns:: AssetClass

static base_from_dict(dict values) → Instrument¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: Instrument

static base_to_dict(Instrument obj)¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

calculate_base_quantity(self, Quantity quantity, Price last_px) → Quantity¶

Calculate the base asset quantity from the given quote asset quantity and last price.

Parameters:

quantity (Quantity) – The quantity to convert from.
last_px (Price) – The last price for the instrument.

Return type:

static from_dict(dict values) → Instrument¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: Equity

static from_pyo3(pyo3_instrument) → Equity¶

Return legacy Cython equity instrument converted from the given pyo3 Rust object.

Parameters:: pyo3_instrument (nautilus_pyo3.Equity) – The pyo3 Rust equity instrument to convert from.
Return type:: Equity

classmethod fully_qualified_name(cls) → str¶

Return the fully qualified name for the Data class.

Return type:: str

References

get_base_currency(self) → Currency¶

Return the instruments base currency (if applicable).

Return type:: Currency or None

get_cost_currency(self) → Currency¶

Return the currency used for PnL calculations for the instrument.

Standard linear instruments = quote_currency
Inverse instruments = base_currency
Quanto instruments TBD

Return type:: Currency

get_settlement_currency(self) → Currency¶

Return the currency used to settle a trade of the instrument.

Standard linear instruments = quote_currency
Inverse instruments = base_currency
Quanto instruments = settlement_currency

Return type:: Currency

id¶

The instrument ID.

Returns:: InstrumentId

info¶

The raw info for the instrument.

Returns:: dict[str, object]

instrument_class¶

The class of the instrument.

Returns:: InstrumentClass

is_inverse¶

If the quantity is expressed in quote currency.

Returns:: bool

classmethod is_signal(cls, str name='') → bool¶

Determine if the current class is a signal type, optionally checking for a specific signal name.

Parameters:: name (str, optional) – The specific signal name to check. If name not provided or if an empty string is passed, the method checks whether the class name indicates a general signal type. If name is provided, the method checks if the class name corresponds to that specific signal.
Returns:: True if the class name matches the signal type or the specific signal name, otherwise False.
Return type:: bool

is_spread(self) → bool¶

Return whether the instrument is a spread instrument.

Return type:: bool

isin¶

The instruments International Securities Identification Number (ISIN).

Returns:: str or None

legs(self) → list¶

Return the list of leg tuples (instrument_id, ratio) for this spread.

Base implementation returns an empty list. Override in spread instrument classes to return the actual legs.

Returns:: List of tuples containing (instrument_id, ratio) for each leg.
Return type:: list[tuple[InstrumentId, int]]

lot_size¶

The rounded lot unit size (standard/board) for the instrument.

Returns:: Quantity or None

make_price(self, value) → Price¶

Return a new price from the given value using the instruments price precision.

Parameters:: value (integer, float, str or Decimal) – The value of the price.
Return type:: Price

make_qty(self, value, bool round_down=False) → Quantity¶

Return a new quantity from the given value using the instruments size precision.

Parameters:

value (integer, float, str or Decimal) – The value of the quantity.
round_down (bool, default False) – If True, always rounds down to the nearest valid increment. If False, uses the round function (banker’s rounding) which rounds to the nearest even digit when exactly halfway between two values.

Return type:

Raises:

ValueError – If a non zero value is rounded to zero due to the instruments size increment or size precision.

maker_fee¶

The fee rate for liquidity makers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

margin_init¶

The initial (order) margin rate for the instrument.

Returns:: Decimal

margin_maint¶

The maintenance (position) margin rate for the instrument.

Returns:: Decimal

max_notional¶

The maximum notional order value for the instrument.

Returns:: Money or None

max_price¶

The maximum printable price for the instrument.

Returns:: Price or None

max_quantity¶

The maximum order quantity for the instrument.

Returns:: Quantity or None

min_notional¶

The minimum notional order value for the instrument.

Returns:: Money or None

min_price¶

The minimum printable price for the instrument.

Returns:: Price or None

min_quantity¶

The minimum order quantity for the instrument.

Returns:: Quantity or None

multiplier¶

The contract multiplier for the instrument (determines tick value).

Returns:: Quantity

next_ask_price(self, double value, int num_ticks=0) → Price¶

Return the price n ask ticks away from value.

If a given price is between two ticks, n=0 will find the nearest ask tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_ask_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks ask ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of ask prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_price(self, double value, int num_ticks=0) → Price¶

Return the price n bid ticks away from value.

If a given price is between two ticks, n=0 will find the nearest bid tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks bid ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of bid prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

notional_value(self, Quantity quantity, Price price, bool use_quote_for_inverse=False, Currency target_currency=None, Price conversion_price=None) → Money¶

Calculate the notional value.

Result will be in quote currency for standard instruments, or base currency for inverse instruments.

If target_currency and conversion_price are provided, the notional value will be converted to the target currency.

Parameters:

quantity (Quantity) – The total quantity.
price (Price) – The price for the calculation.
use_quote_for_inverse (bool) – If inverse instrument calculations use quote currency (instead of base).
target_currency (Currency, optional) – The target currency for conversion.
conversion_price (Price, optional) – The price to use for currency conversion.

Return type:

price_increment¶

The minimum price increment or tick size for the instrument.

Returns:: Price

price_precision¶

The price precision of the instrument.

Returns:: int

quote_currency¶

The quote currency for the instrument.

Returns:: Currency

raw_symbol¶

The raw/local/native symbol for the instrument, assigned by the venue.

Returns:: Symbol

set_tick_scheme(self, str tick_scheme_name) → void¶

Set the tick scheme for the instrument.

Sets both the tick_scheme_name and the corresponding tick scheme implementation used for price rounding and tick calculations.

This will override any previously set tick scheme, including the tick_scheme_name field.

Parameters:

tick_scheme_name (str) – The name of the registered tick scheme.

Raises:

ValueError – If tick_scheme_name is not a valid string.
ValueError – If tick_scheme_name is not a registered tick scheme.

size_increment¶

The minimum size increment for the instrument.

Returns:: Quantity

size_precision¶

The size precision of the instrument.

Returns:: int

symbol¶

Return the instruments ticker symbol.

Return type:: Symbol

taker_fee¶

The fee rate for liquidity takers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

tick_scheme_name¶

The tick scheme name.

Returns:: str or None

static to_dict(Instrument obj) → dict[str, object]¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

ts_event¶

UNIX timestamp (nanoseconds) when the data event occurred.

Returns:: uint64_t

ts_init¶

UNIX timestamp (nanoseconds) when the object was initialized.

Returns:: uint64_t

venue¶

Return the instruments trading venue.

Return type:: Venue

class FuturesContract¶

Bases: Instrument

Represents a generic deliverable futures contract instrument.

Parameters:

instrument_id (InstrumentId) – The instrument ID.
raw_symbol (Symbol) – The raw/local/native symbol for the instrument, assigned by the venue.
asset_class (AssetClass) – The futures contract asset class.
currency (Currency) – The futures contract currency.
price_precision (int) – The price decimal precision.
price_increment (Decimal) – The minimum price increment (tick size).
multiplier (Quantity) – The contract multiplier.
lot_size (Quantity) – The rounded lot unit size (standard/board).
underlying (str) – The underlying asset.
activation_ns (uint64_t) – UNIX timestamp (nanoseconds) for contract activation.
expiration_ns (uint64_t) – UNIX timestamp (nanoseconds) for contract expiration.
ts_event (uint64_t) – UNIX timestamp (nanoseconds) when the data event occurred.
ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the data object was initialized.
margin_init (Decimal, optional) – The initial (order) margin requirement in percentage of order value.
margin_maint (Decimal, optional) – The maintenance (position) margin in percentage of position value.
maker_fee (Decimal, optional) – The fee rate for liquidity makers as a percentage of order value.
taker_fee (Decimal, optional) – The fee rate for liquidity takers as a percentage of order value.
exchange (str, optional) – The exchange ISO 10383 Market Identifier Code (MIC) where the instrument trades.
tick_scheme_name (str, optional) – The name of the tick scheme.
info (dict[str, object], optional) – The additional instrument information.

Raises:

ValueError – If multiplier is not positive (> 0).
ValueError – If price_precision is negative (< 0).
ValueError – If tick_size is not positive (> 0).
ValueError – If lot_size is not positive (> 0).
ValueError – If margin_init is negative (< 0).
ValueError – If margin_maint is negative (< 0).
ValueError – If exchange is not None and not a valid string.

activation_ns¶

UNIX timestamp (nanoseconds) for contract activation.

Returns:: unit64_t

activation_utc¶

pd.Timestamp

Return the contract activation timestamp (UTC).

Returns:: tz-aware UTC.
Return type:: pd.Timestamp
Type:: FuturesContract.activation_utc

asset_class¶

The asset class of the instrument.

Returns:: AssetClass

static base_from_dict(dict values) → Instrument¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: Instrument

static base_to_dict(Instrument obj)¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

calculate_base_quantity(self, Quantity quantity, Price last_px) → Quantity¶

Calculate the base asset quantity from the given quote asset quantity and last price.

Parameters:

quantity (Quantity) – The quantity to convert from.
last_px (Price) – The last price for the instrument.

Return type:

exchange¶

The exchange ISO 10383 Market Identifier Code (MIC) where the instrument trades.

Returns:: str or None

expiration_ns¶

UNIX timestamp (nanoseconds) for contract expiration.

Returns:: unit64_t

expiration_utc¶

pd.Timestamp

Return the contract expiration timestamp (UTC).

Returns:: tz-aware UTC.
Return type:: pd.Timestamp
Type:: FuturesContract.expiration_utc

static from_dict(dict values) → FuturesContract¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: FuturesContract

static from_pyo3(pyo3_instrument) → FuturesContract¶

Return legacy Cython futures contract instrument converted from the given pyo3 Rust object.

Parameters:: pyo3_instrument (nautilus_pyo3.FuturesContract) – The pyo3 Rust futures contract instrument to convert from.
Return type:: FuturesContract

classmethod fully_qualified_name(cls) → str¶

Return the fully qualified name for the Data class.

Return type:: str

References

get_base_currency(self) → Currency¶

Return the instruments base currency (if applicable).

Return type:: Currency or None

get_cost_currency(self) → Currency¶

Return the currency used for PnL calculations for the instrument.

Standard linear instruments = quote_currency
Inverse instruments = base_currency
Quanto instruments TBD

Return type:: Currency

get_settlement_currency(self) → Currency¶

Return the currency used to settle a trade of the instrument.

Standard linear instruments = quote_currency
Inverse instruments = base_currency
Quanto instruments = settlement_currency

Return type:: Currency

id¶

The instrument ID.

Returns:: InstrumentId

info¶

The raw info for the instrument.

Returns:: dict[str, object]

instrument_class¶

The class of the instrument.

Returns:: InstrumentClass

is_inverse¶

If the quantity is expressed in quote currency.

Returns:: bool

classmethod is_signal(cls, str name='') → bool¶

Determine if the current class is a signal type, optionally checking for a specific signal name.

Parameters:: name (str, optional) – The specific signal name to check. If name not provided or if an empty string is passed, the method checks whether the class name indicates a general signal type. If name is provided, the method checks if the class name corresponds to that specific signal.
Returns:: True if the class name matches the signal type or the specific signal name, otherwise False.
Return type:: bool

is_spread(self) → bool¶

Return whether the instrument is a spread instrument.

Return type:: bool

legs(self) → list¶

Return the list of leg tuples (instrument_id, ratio) for this spread.

Base implementation returns an empty list. Override in spread instrument classes to return the actual legs.

Returns:: List of tuples containing (instrument_id, ratio) for each leg.
Return type:: list[tuple[InstrumentId, int]]

lot_size¶

The rounded lot unit size (standard/board) for the instrument.

Returns:: Quantity or None

make_price(self, value) → Price¶

Return a new price from the given value using the instruments price precision.

Parameters:: value (integer, float, str or Decimal) – The value of the price.
Return type:: Price

make_qty(self, value, bool round_down=False) → Quantity¶

Return a new quantity from the given value using the instruments size precision.

Parameters:

value (integer, float, str or Decimal) – The value of the quantity.
round_down (bool, default False) – If True, always rounds down to the nearest valid increment. If False, uses the round function (banker’s rounding) which rounds to the nearest even digit when exactly halfway between two values.

Return type:

Raises:

ValueError – If a non zero value is rounded to zero due to the instruments size increment or size precision.

maker_fee¶

The fee rate for liquidity makers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

margin_init¶

The initial (order) margin rate for the instrument.

Returns:: Decimal

margin_maint¶

The maintenance (position) margin rate for the instrument.

Returns:: Decimal

max_notional¶

The maximum notional order value for the instrument.

Returns:: Money or None

max_price¶

The maximum printable price for the instrument.

Returns:: Price or None

max_quantity¶

The maximum order quantity for the instrument.

Returns:: Quantity or None

min_notional¶

The minimum notional order value for the instrument.

Returns:: Money or None

min_price¶

The minimum printable price for the instrument.

Returns:: Price or None

min_quantity¶

The minimum order quantity for the instrument.

Returns:: Quantity or None

multiplier¶

The contract multiplier for the instrument (determines tick value).

Returns:: Quantity

next_ask_price(self, double value, int num_ticks=0) → Price¶

Return the price n ask ticks away from value.

If a given price is between two ticks, n=0 will find the nearest ask tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_ask_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks ask ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of ask prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_price(self, double value, int num_ticks=0) → Price¶

Return the price n bid ticks away from value.

If a given price is between two ticks, n=0 will find the nearest bid tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks bid ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of bid prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

notional_value(self, Quantity quantity, Price price, bool use_quote_for_inverse=False, Currency target_currency=None, Price conversion_price=None) → Money¶

Calculate the notional value.

Result will be in quote currency for standard instruments, or base currency for inverse instruments.

If target_currency and conversion_price are provided, the notional value will be converted to the target currency.

Parameters:

quantity (Quantity) – The total quantity.
price (Price) – The price for the calculation.
use_quote_for_inverse (bool) – If inverse instrument calculations use quote currency (instead of base).
target_currency (Currency, optional) – The target currency for conversion.
conversion_price (Price, optional) – The price to use for currency conversion.

Return type:

price_increment¶

The minimum price increment or tick size for the instrument.

Returns:: Price

price_precision¶

The price precision of the instrument.

Returns:: int

quote_currency¶

The quote currency for the instrument.

Returns:: Currency

raw_symbol¶

The raw/local/native symbol for the instrument, assigned by the venue.

Returns:: Symbol

set_tick_scheme(self, str tick_scheme_name) → void¶

Set the tick scheme for the instrument.

Sets both the tick_scheme_name and the corresponding tick scheme implementation used for price rounding and tick calculations.

This will override any previously set tick scheme, including the tick_scheme_name field.

Parameters:

tick_scheme_name (str) – The name of the registered tick scheme.

Raises:

ValueError – If tick_scheme_name is not a valid string.
ValueError – If tick_scheme_name is not a registered tick scheme.

size_increment¶

The minimum size increment for the instrument.

Returns:: Quantity

size_precision¶

The size precision of the instrument.

Returns:: int

symbol¶

Return the instruments ticker symbol.

Return type:: Symbol

taker_fee¶

The fee rate for liquidity takers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

tick_scheme_name¶

The tick scheme name.

Returns:: str or None

static to_dict(FuturesContract obj) → dict[str, object]¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

ts_event¶

UNIX timestamp (nanoseconds) when the data event occurred.

Returns:: uint64_t

ts_init¶

UNIX timestamp (nanoseconds) when the object was initialized.

Returns:: uint64_t

underlying¶

The underlying asset for the contract.

Returns:: str

venue¶

Return the instruments trading venue.

Return type:: Venue

class FuturesSpread¶

Bases: Instrument

Represents a generic deliverable futures spread instrument.

Parameters:

instrument_id (InstrumentId) – The instrument ID.
raw_symbol (Symbol) – The raw/local/native symbol for the instrument, assigned by the venue.
asset_class (AssetClass) – The futures spread asset class.
currency (Currency) – The futures spread currency.
price_precision (int) – The price decimal precision.
price_increment (Decimal) – The minimum price increment (tick size).
multiplier (Quantity) – The contract multiplier.
lot_size (Quantity) – The rounded lot unit size (standard/board).
underlying (str) – The underlying asset.
strategy_type (str) – The strategy type for the spread.
activation_ns (uint64_t) – UNIX timestamp (nanoseconds) for contract activation.
expiration_ns (uint64_t) – UNIX timestamp (nanoseconds) for contract expiration.
ts_event (uint64_t) – UNIX timestamp (nanoseconds) when the data event occurred.
ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the data object was initialized.
margin_init (Decimal, optional) – The initial (order) margin requirement in percentage of order value.
margin_maint (Decimal, optional) – The maintenance (position) margin in percentage of position value.
maker_fee (Decimal, optional) – The fee rate for liquidity makers as a percentage of order value.
taker_fee (Decimal, optional) – The fee rate for liquidity takers as a percentage of order value.
exchange (str, optional) – The exchange ISO 10383 Market Identifier Code (MIC) where the instrument trades.
tick_scheme_name (str, optional) – The name of the tick scheme.
info (dict[str, object], optional) – The additional instrument information.

Raises:

ValueError – If strategy_type is not a valid string.
ValueError – If multiplier is not positive (> 0).
ValueError – If price_precision is negative (< 0).
ValueError – If tick_size is not positive (> 0).
ValueError – If lot_size is not positive (> 0).
ValueError – If margin_init is negative (< 0).
ValueError – If margin_maint is negative (< 0).
ValueError – If exchange is not None and not a valid string.

activation_ns¶

UNIX timestamp (nanoseconds) for contract activation.

Returns:: unit64_t

activation_utc¶

pd.Timestamp

Return the contract activation timestamp (UTC).

Returns:: tz-aware UTC.
Return type:: pd.Timestamp
Type:: FuturesSpread.activation_utc

asset_class¶

The asset class of the instrument.

Returns:: AssetClass

static base_from_dict(dict values) → Instrument¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: Instrument

static base_to_dict(Instrument obj)¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

calculate_base_quantity(self, Quantity quantity, Price last_px) → Quantity¶

Calculate the base asset quantity from the given quote asset quantity and last price.

Parameters:

quantity (Quantity) – The quantity to convert from.
last_px (Price) – The last price for the instrument.

Return type:

exchange¶

The exchange ISO 10383 Market Identifier Code (MIC) where the instrument trades.

Returns:: str or None

expiration_ns¶

UNIX timestamp (nanoseconds) for contract expiration.

Returns:: unit64_t

expiration_utc¶

pd.Timestamp

Return the contract expiration timestamp (UTC).

Returns:: tz-aware UTC.
Return type:: pd.Timestamp
Type:: FuturesSpread.expiration_utc

static from_dict(dict values) → FuturesSpread¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: FuturesSpread

static from_pyo3(pyo3_instrument) → FuturesSpread¶

Return legacy Cython futures spread instrument converted from the given pyo3 Rust object.

Parameters:: pyo3_instrument (nautilus_pyo3.FuturesSpread) – The pyo3 Rust futures spread instrument to convert from.
Return type:: FuturesSpread

classmethod fully_qualified_name(cls) → str¶

Return the fully qualified name for the Data class.

Return type:: str

References

get_base_currency(self) → Currency¶

Return the instruments base currency (if applicable).

Return type:: Currency or None

get_cost_currency(self) → Currency¶

Return the currency used for PnL calculations for the instrument.

Standard linear instruments = quote_currency
Inverse instruments = base_currency
Quanto instruments TBD

Return type:: Currency

get_settlement_currency(self) → Currency¶

Return the currency used to settle a trade of the instrument.

Standard linear instruments = quote_currency
Inverse instruments = base_currency
Quanto instruments = settlement_currency

Return type:: Currency

id¶

The instrument ID.

Returns:: InstrumentId

info¶

The raw info for the instrument.

Returns:: dict[str, object]

instrument_class¶

The class of the instrument.

Returns:: InstrumentClass

is_inverse¶

If the quantity is expressed in quote currency.

Returns:: bool

classmethod is_signal(cls, str name='') → bool¶

Determine if the current class is a signal type, optionally checking for a specific signal name.

Parameters:: name (str, optional) – The specific signal name to check. If name not provided or if an empty string is passed, the method checks whether the class name indicates a general signal type. If name is provided, the method checks if the class name corresponds to that specific signal.
Returns:: True if the class name matches the signal type or the specific signal name, otherwise False.
Return type:: bool

is_spread(self) → bool¶

Return whether the instrument is a spread instrument.

Return type:: bool

legs(self) → list¶

Return the list of leg tuples (instrument_id, ratio) for this spread.

If the instrument ID corresponds to a generic spread ID, returns the parsed legs using generic_spread_id_to_list. Otherwise returns an empty list.

Returns:: List of tuples containing (instrument_id, ratio) for each leg.
Return type:: list[tuple[InstrumentId, int]]

lot_size¶

The rounded lot unit size (standard/board) for the instrument.

Returns:: Quantity or None

make_price(self, value) → Price¶

Return a new price from the given value using the instruments price precision.

Parameters:: value (integer, float, str or Decimal) – The value of the price.
Return type:: Price

make_qty(self, value, bool round_down=False) → Quantity¶

Return a new quantity from the given value using the instruments size precision.

Parameters:

value (integer, float, str or Decimal) – The value of the quantity.
round_down (bool, default False) – If True, always rounds down to the nearest valid increment. If False, uses the round function (banker’s rounding) which rounds to the nearest even digit when exactly halfway between two values.

Return type:

Raises:

ValueError – If a non zero value is rounded to zero due to the instruments size increment or size precision.

maker_fee¶

The fee rate for liquidity makers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

margin_init¶

The initial (order) margin rate for the instrument.

Returns:: Decimal

margin_maint¶

The maintenance (position) margin rate for the instrument.

Returns:: Decimal

max_notional¶

The maximum notional order value for the instrument.

Returns:: Money or None

max_price¶

The maximum printable price for the instrument.

Returns:: Price or None

max_quantity¶

The maximum order quantity for the instrument.

Returns:: Quantity or None

min_notional¶

The minimum notional order value for the instrument.

Returns:: Money or None

min_price¶

The minimum printable price for the instrument.

Returns:: Price or None

min_quantity¶

The minimum order quantity for the instrument.

Returns:: Quantity or None

multiplier¶

The contract multiplier for the instrument (determines tick value).

Returns:: Quantity

next_ask_price(self, double value, int num_ticks=0) → Price¶

Return the price n ask ticks away from value.

If a given price is between two ticks, n=0 will find the nearest ask tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_ask_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks ask ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of ask prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_price(self, double value, int num_ticks=0) → Price¶

Return the price n bid ticks away from value.

If a given price is between two ticks, n=0 will find the nearest bid tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks bid ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of bid prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

notional_value(self, Quantity quantity, Price price, bool use_quote_for_inverse=False, Currency target_currency=None, Price conversion_price=None) → Money¶

Calculate the notional value.

Result will be in quote currency for standard instruments, or base currency for inverse instruments.

If target_currency and conversion_price are provided, the notional value will be converted to the target currency.

Parameters:

quantity (Quantity) – The total quantity.
price (Price) – The price for the calculation.
use_quote_for_inverse (bool) – If inverse instrument calculations use quote currency (instead of base).
target_currency (Currency, optional) – The target currency for conversion.
conversion_price (Price, optional) – The price to use for currency conversion.

Return type:

price_increment¶

The minimum price increment or tick size for the instrument.

Returns:: Price

price_precision¶

The price precision of the instrument.

Returns:: int

quote_currency¶

The quote currency for the instrument.

Returns:: Currency

raw_symbol¶

The raw/local/native symbol for the instrument, assigned by the venue.

Returns:: Symbol

set_tick_scheme(self, str tick_scheme_name) → void¶

Set the tick scheme for the instrument.

Sets both the tick_scheme_name and the corresponding tick scheme implementation used for price rounding and tick calculations.

This will override any previously set tick scheme, including the tick_scheme_name field.

Parameters:

tick_scheme_name (str) – The name of the registered tick scheme.

Raises:

ValueError – If tick_scheme_name is not a valid string.
ValueError – If tick_scheme_name is not a registered tick scheme.

size_increment¶

The minimum size increment for the instrument.

Returns:: Quantity

size_precision¶

The size precision of the instrument.

Returns:: int

strategy_type¶

The strategy type of the spread.

Returns:: str

symbol¶

Return the instruments ticker symbol.

Return type:: Symbol

taker_fee¶

The fee rate for liquidity takers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

tick_scheme_name¶

The tick scheme name.

Returns:: str or None

static to_dict(FuturesSpread obj) → dict[str, object]¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

ts_event¶

UNIX timestamp (nanoseconds) when the data event occurred.

Returns:: uint64_t

ts_init¶

UNIX timestamp (nanoseconds) when the object was initialized.

Returns:: uint64_t

underlying¶

The underlying asset for the spread.

Returns:: str

venue¶

Return the instruments trading venue.

Return type:: Venue

class IndexInstrument¶

Bases: Instrument

Represents a spot index instrument (also known as a cash index).

A spot index is calculated from its underlying constituents. It is not directly tradable. To gain exposure you would typically use index futures, ETFs, or CFDs.

Parameters:

instrument_id (InstrumentId) – The instrument ID.
raw_symbol (Symbol) – The raw/local/native symbol for the instrument, assigned by the venue.
currency (Currency) – The futures contract currency.
price_precision (int) – The price decimal precision.
price_increment (Price) – The minimum price increment (tick size).
size_precision (int) – The trading size decimal precision.
size_increment (Quantity) – The minimum size increment.
ts_event (uint64_t) – UNIX timestamp (nanoseconds) when the data event occurred.
ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the data object was initialized.
tick_scheme_name (str, optional) – The name of the tick scheme.
info (dict[str, object], optional) – The additional instrument information.

Raises:

ValueError – If price_precision is negative (< 0).
ValueError – If size_precision is negative (< 0).
ValueError – If price_increment is not positive (> 0).
ValueError – If size_increment is not positive (> 0).
ValueError – If price_precision is not equal to price_increment.precision.
ValueError – If size_increment is not equal to size_increment.precision.

asset_class¶

The asset class of the instrument.

Returns:: AssetClass

static base_from_dict(dict values) → Instrument¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: Instrument

static base_to_dict(Instrument obj)¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

calculate_base_quantity(self, Quantity quantity, Price last_px) → Quantity¶

Calculate the base asset quantity from the given quote asset quantity and last price.

Parameters:

quantity (Quantity) – The quantity to convert from.
last_px (Price) – The last price for the instrument.

Return type:

static from_dict(dict values) → Instrument¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: IndexInstrument

static from_pyo3(pyo3_instrument) → IndexInstrument¶

Return legacy Cython index instrument converted from the given pyo3 Rust object.

Parameters:: pyo3_instrument (nautilus_pyo3.IndexInstrument) – The pyo3 Rust index instrument to convert from.
Return type:: IndexInstrument

classmethod fully_qualified_name(cls) → str¶

Return the fully qualified name for the Data class.

Return type:: str

References

get_base_currency(self) → Currency¶

Return the instruments base currency (if applicable).

Return type:: Currency or None

get_cost_currency(self) → Currency¶

Return the currency used for PnL calculations for the instrument.

Standard linear instruments = quote_currency
Inverse instruments = base_currency
Quanto instruments TBD

Return type:: Currency

get_settlement_currency(self) → Currency¶

Return the currency used to settle a trade of the instrument.

Standard linear instruments = quote_currency
Inverse instruments = base_currency
Quanto instruments = settlement_currency

Return type:: Currency

id¶

The instrument ID.

Returns:: InstrumentId

info¶

The raw info for the instrument.

Returns:: dict[str, object]

instrument_class¶

The class of the instrument.

Returns:: InstrumentClass

is_inverse¶

If the quantity is expressed in quote currency.

Returns:: bool

classmethod is_signal(cls, str name='') → bool¶

Determine if the current class is a signal type, optionally checking for a specific signal name.

Parameters:: name (str, optional) – The specific signal name to check. If name not provided or if an empty string is passed, the method checks whether the class name indicates a general signal type. If name is provided, the method checks if the class name corresponds to that specific signal.
Returns:: True if the class name matches the signal type or the specific signal name, otherwise False.
Return type:: bool

is_spread(self) → bool¶

Return whether the instrument is a spread instrument.

Return type:: bool

legs(self) → list¶

Return the list of leg tuples (instrument_id, ratio) for this spread.

Base implementation returns an empty list. Override in spread instrument classes to return the actual legs.

Returns:: List of tuples containing (instrument_id, ratio) for each leg.
Return type:: list[tuple[InstrumentId, int]]

lot_size¶

The rounded lot unit size (standard/board) for the instrument.

Returns:: Quantity or None

make_price(self, value) → Price¶

Return a new price from the given value using the instruments price precision.

Parameters:: value (integer, float, str or Decimal) – The value of the price.
Return type:: Price

make_qty(self, value, bool round_down=False) → Quantity¶

Return a new quantity from the given value using the instruments size precision.

Parameters:

value (integer, float, str or Decimal) – The value of the quantity.
round_down (bool, default False) – If True, always rounds down to the nearest valid increment. If False, uses the round function (banker’s rounding) which rounds to the nearest even digit when exactly halfway between two values.

Return type:

Raises:

ValueError – If a non zero value is rounded to zero due to the instruments size increment or size precision.

maker_fee¶

The fee rate for liquidity makers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

margin_init¶

The initial (order) margin rate for the instrument.

Returns:: Decimal

margin_maint¶

The maintenance (position) margin rate for the instrument.

Returns:: Decimal

max_notional¶

The maximum notional order value for the instrument.

Returns:: Money or None

max_price¶

The maximum printable price for the instrument.

Returns:: Price or None

max_quantity¶

The maximum order quantity for the instrument.

Returns:: Quantity or None

min_notional¶

The minimum notional order value for the instrument.

Returns:: Money or None

min_price¶

The minimum printable price for the instrument.

Returns:: Price or None

min_quantity¶

The minimum order quantity for the instrument.

Returns:: Quantity or None

multiplier¶

The contract multiplier for the instrument (determines tick value).

Returns:: Quantity

next_ask_price(self, double value, int num_ticks=0) → Price¶

Return the price n ask ticks away from value.

If a given price is between two ticks, n=0 will find the nearest ask tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_ask_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks ask ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of ask prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_price(self, double value, int num_ticks=0) → Price¶

Return the price n bid ticks away from value.

If a given price is between two ticks, n=0 will find the nearest bid tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks bid ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of bid prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

notional_value(self, Quantity quantity, Price price, bool use_quote_for_inverse=False, Currency target_currency=None, Price conversion_price=None) → Money¶

Calculate the notional value.

Result will be in quote currency for standard instruments, or base currency for inverse instruments.

If target_currency and conversion_price are provided, the notional value will be converted to the target currency.

Parameters:

quantity (Quantity) – The total quantity.
price (Price) – The price for the calculation.
use_quote_for_inverse (bool) – If inverse instrument calculations use quote currency (instead of base).
target_currency (Currency, optional) – The target currency for conversion.
conversion_price (Price, optional) – The price to use for currency conversion.

Return type:

price_increment¶

The minimum price increment or tick size for the instrument.

Returns:: Price

price_precision¶

The price precision of the instrument.

Returns:: int

quote_currency¶

The quote currency for the instrument.

Returns:: Currency

raw_symbol¶

The raw/local/native symbol for the instrument, assigned by the venue.

Returns:: Symbol

set_tick_scheme(self, str tick_scheme_name) → void¶

Set the tick scheme for the instrument.

Sets both the tick_scheme_name and the corresponding tick scheme implementation used for price rounding and tick calculations.

This will override any previously set tick scheme, including the tick_scheme_name field.

Parameters:

tick_scheme_name (str) – The name of the registered tick scheme.

Raises:

ValueError – If tick_scheme_name is not a valid string.
ValueError – If tick_scheme_name is not a registered tick scheme.

size_increment¶

The minimum size increment for the instrument.

Returns:: Quantity

size_precision¶

The size precision of the instrument.

Returns:: int

symbol¶

Return the instruments ticker symbol.

Return type:: Symbol

taker_fee¶

The fee rate for liquidity takers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

tick_scheme_name¶

The tick scheme name.

Returns:: str or None

static to_dict(Instrument obj) → dict[str, object]¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

ts_event¶

UNIX timestamp (nanoseconds) when the data event occurred.

Returns:: uint64_t

ts_init¶

UNIX timestamp (nanoseconds) when the object was initialized.

Returns:: uint64_t

venue¶

Return the instruments trading venue.

Return type:: Venue

class PerpetualContract¶

Bases: Instrument

Represents a perpetual contract instrument (perpetual swap).

Supports perpetuals on any asset class including FX, equities, commodities, indexes, and cryptocurrencies.

Parameters:

instrument_id (InstrumentId) – The instrument ID for the instrument.
raw_symbol (Symbol) – The raw/local/native symbol for the instrument, assigned by the venue.
underlying (str) – The underlying asset identifier (e.g., “EURUSD”, “NVDA”, “GC”).
asset_class (AssetClass) – The asset class of the perpetual contract.
quote_currency (Currency) – The quote currency.
settlement_currency (Currency) – The settlement currency.
is_inverse (bool) – If the instrument costing is inverse (quantity expressed in quote currency units).
price_precision (int) – The price decimal precision.
size_precision (int) – The trading size decimal precision.
price_increment (Price) – The minimum price increment (tick size).
size_increment (Quantity) – The minimum size increment.
ts_event (uint64_t) – UNIX timestamp (nanoseconds) when the data event occurred.
ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the data object was initialized.
base_currency (Currency, optional) – The base currency (for FX/crypto underlyings).
multiplier (Quantity, default 1) – The contract multiplier.
lot_size (Quantity, default 1) – The rounded lot unit size (standard/board).
max_quantity (Quantity, optional) – The maximum allowable order quantity.
min_quantity (Quantity, optional) – The minimum allowable order quantity.
max_notional (Money, optional) – The maximum allowable order notional value.
min_notional (Money, optional) – The minimum allowable order notional value.
max_price (Price, optional) – The maximum allowable quoted price.
min_price (Price, optional) – The minimum allowable quoted price.
margin_init (Decimal, optional) – The initial (order) margin requirement in percentage of order value.
margin_maint (Decimal, optional) – The maintenance (position) margin in percentage of position value.
maker_fee (Decimal, optional) – The fee rate for liquidity makers as a percentage of order value.
taker_fee (Decimal, optional) – The fee rate for liquidity takers as a percentage of order value.
tick_scheme_name (str, optional) – The name of the tick scheme.
info (dict[str, object], optional) – The additional instrument information.

asset_class¶

The asset class of the instrument.

Returns:: AssetClass

base_currency¶

The base currency for the instrument.

Returns:: Currency or None

static base_from_dict(dict values) → Instrument¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: Instrument

static base_to_dict(Instrument obj)¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

calculate_base_quantity(self, Quantity quantity, Price last_px) → Quantity¶

Calculate the base asset quantity from the given quote asset quantity and last price.

Parameters:

quantity (Quantity) – The quantity to convert from.
last_px (Price) – The last price for the instrument.

Return type:

static from_dict(dict values) → PerpetualContract¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: PerpetualContract

static from_pyo3(pyo3_instrument)¶

classmethod fully_qualified_name(cls) → str¶

Return the fully qualified name for the Data class.

Return type:: str

References

get_base_currency(self) → Currency¶

get_cost_currency(self) → Currency¶

get_settlement_currency(self) → Currency¶

id¶

The instrument ID.

Returns:: InstrumentId

info¶

The raw info for the instrument.

Returns:: dict[str, object]

instrument_class¶

The class of the instrument.

Returns:: InstrumentClass

is_inverse¶

If the quantity is expressed in quote currency.

Returns:: bool

is_quanto¶

If the instrument is a quanto perpetual.

Returns:: bool

classmethod is_signal(cls, str name='') → bool¶

Determine if the current class is a signal type, optionally checking for a specific signal name.

Parameters:: name (str, optional) – The specific signal name to check. If name not provided or if an empty string is passed, the method checks whether the class name indicates a general signal type. If name is provided, the method checks if the class name corresponds to that specific signal.
Returns:: True if the class name matches the signal type or the specific signal name, otherwise False.
Return type:: bool

is_spread(self) → bool¶

Return whether the instrument is a spread instrument.

Return type:: bool

legs(self) → list¶

Return the list of leg tuples (instrument_id, ratio) for this spread.

Base implementation returns an empty list. Override in spread instrument classes to return the actual legs.

Returns:: List of tuples containing (instrument_id, ratio) for each leg.
Return type:: list[tuple[InstrumentId, int]]

lot_size¶

The rounded lot unit size (standard/board) for the instrument.

Returns:: Quantity or None

make_price(self, value) → Price¶

Return a new price from the given value using the instruments price precision.

Parameters:: value (integer, float, str or Decimal) – The value of the price.
Return type:: Price

make_qty(self, value, bool round_down=False) → Quantity¶

Return a new quantity from the given value using the instruments size precision.

Parameters:

value (integer, float, str or Decimal) – The value of the quantity.
round_down (bool, default False) – If True, always rounds down to the nearest valid increment. If False, uses the round function (banker’s rounding) which rounds to the nearest even digit when exactly halfway between two values.

Return type:

Raises:

ValueError – If a non zero value is rounded to zero due to the instruments size increment or size precision.

maker_fee¶

The fee rate for liquidity makers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

margin_init¶

The initial (order) margin rate for the instrument.

Returns:: Decimal

margin_maint¶

The maintenance (position) margin rate for the instrument.

Returns:: Decimal

max_notional¶

The maximum notional order value for the instrument.

Returns:: Money or None

max_price¶

The maximum printable price for the instrument.

Returns:: Price or None

max_quantity¶

The maximum order quantity for the instrument.

Returns:: Quantity or None

min_notional¶

The minimum notional order value for the instrument.

Returns:: Money or None

min_price¶

The minimum printable price for the instrument.

Returns:: Price or None

min_quantity¶

The minimum order quantity for the instrument.

Returns:: Quantity or None

multiplier¶

The contract multiplier for the instrument (determines tick value).

Returns:: Quantity

next_ask_price(self, double value, int num_ticks=0) → Price¶

Return the price n ask ticks away from value.

If a given price is between two ticks, n=0 will find the nearest ask tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_ask_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks ask ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of ask prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_price(self, double value, int num_ticks=0) → Price¶

Return the price n bid ticks away from value.

If a given price is between two ticks, n=0 will find the nearest bid tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks bid ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of bid prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

notional_value(self, Quantity quantity, Price price, bool use_quote_for_inverse=False, Currency target_currency=None, Price conversion_price=None) → Money¶

price_increment¶

The minimum price increment or tick size for the instrument.

Returns:: Price

price_precision¶

The price precision of the instrument.

Returns:: int

quote_currency¶

The quote currency for the instrument.

Returns:: Currency

raw_symbol¶

The raw/local/native symbol for the instrument, assigned by the venue.

Returns:: Symbol

set_tick_scheme(self, str tick_scheme_name) → void¶

Set the tick scheme for the instrument.

Sets both the tick_scheme_name and the corresponding tick scheme implementation used for price rounding and tick calculations.

This will override any previously set tick scheme, including the tick_scheme_name field.

Parameters:

tick_scheme_name (str) – The name of the registered tick scheme.

Raises:

ValueError – If tick_scheme_name is not a valid string.
ValueError – If tick_scheme_name is not a registered tick scheme.

settlement_currency¶

The settlement currency for the instrument.

Returns:: Currency

size_increment¶

The minimum size increment for the instrument.

Returns:: Quantity

size_precision¶

The size precision of the instrument.

Returns:: int

symbol¶

Return the instruments ticker symbol.

Return type:: Symbol

taker_fee¶

The fee rate for liquidity takers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

tick_scheme_name¶

The tick scheme name.

Returns:: str or None

static to_dict(PerpetualContract obj) → dict[str, object]¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

ts_event¶

UNIX timestamp (nanoseconds) when the data event occurred.

Returns:: uint64_t

ts_init¶

UNIX timestamp (nanoseconds) when the object was initialized.

Returns:: uint64_t

underlying¶

The underlying asset identifier.

Returns:: str

venue¶

Return the instruments trading venue.

Return type:: Venue

class OptionContract¶

Bases: Instrument

Represents a generic option contract instrument.

Parameters:

instrument_id (InstrumentId) – The instrument ID.
raw_symbol (Symbol) – The raw/local/native symbol for the instrument, assigned by the venue.
asset_class (AssetClass) – The option contract asset class.
currency (Currency) – The option contract currency.
price_precision (int) – The price decimal precision.
price_increment (Price) – The minimum price increment (tick size).
multiplier (Quantity) – The option multiplier.
lot_size (Quantity) – The rounded lot unit size (standard/board).
underlying (str) – The underlying asset.
option_kind (OptionKind) – The kind of option (PUT | CALL).
strike_price (Price) – The option strike price.
activation_ns (uint64_t) – UNIX timestamp (nanoseconds) for contract activation.
expiration_ns (uint64_t) – UNIX timestamp (nanoseconds) for contract expiration.
ts_event (uint64_t) – UNIX timestamp (nanoseconds) when the data event occurred.
ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the data object was initialized.
margin_init (Decimal, optional) – The initial (order) margin requirement in percentage of order value.
margin_maint (Decimal, optional) – The maintenance (position) margin in percentage of position value.
maker_fee (Decimal, optional) – The fee rate for liquidity makers as a percentage of order value.
taker_fee (Decimal, optional) – The fee rate for liquidity takers as a percentage of order value.
exchange (str, optional) – The exchange ISO 10383 Market Identifier Code (MIC) where the instrument trades.
tick_scheme_name (str, optional) – The name of the tick scheme.
info (dict[str, object], optional) – The additional instrument information.

Raises:

ValueError – If multiplier is not positive (> 0).
ValueError – If price_precision is negative (< 0).
ValueError – If tick_size is not positive (> 0).
ValueError – If lot_size is not positive (> 0).
ValueError – If margin_init is negative (< 0).
ValueError – If margin_maint is negative (< 0).
ValueError – If exchange is not None and not a valid string.

activation_ns¶

UNIX timestamp (nanoseconds) for contract activation.

Returns:: unit64_t

activation_utc¶

pd.Timestamp

Return the contract activation timestamp (UTC).

Returns:: tz-aware UTC.
Return type:: pd.Timestamp
Type:: OptionContract.activation_utc

asset_class¶

The asset class of the instrument.

Returns:: AssetClass

static base_from_dict(dict values) → Instrument¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: Instrument

static base_to_dict(Instrument obj)¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

calculate_base_quantity(self, Quantity quantity, Price last_px) → Quantity¶

Calculate the base asset quantity from the given quote asset quantity and last price.

Parameters:

quantity (Quantity) – The quantity to convert from.
last_px (Price) – The last price for the instrument.

Return type:

exchange¶

The exchange ISO 10383 Market Identifier Code (MIC) where the instrument trades.

Returns:: str or None

expiration_ns¶

UNIX timestamp (nanoseconds) for contract expiration.

Returns:: unit64_t

expiration_utc¶

pd.Timestamp

Return the contract expiration timestamp (UTC).

Returns:: tz-aware UTC.
Return type:: pd.Timestamp
Type:: OptionContract.expiration_utc

static from_dict(dict values) → OptionContract¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: OptionContract

static from_pyo3(pyo3_instrument) → OptionContract¶

Return legacy Cython option contract instrument converted from the given pyo3 Rust object.

Parameters:: pyo3_instrument (nautilus_pyo3.OptionContract) – The pyo3 Rust option contract instrument to convert from.
Return type:: OptionContract

classmethod fully_qualified_name(cls) → str¶

Return the fully qualified name for the Data class.

Return type:: str

References

get_base_currency(self) → Currency¶

Return the instruments base currency (if applicable).

Return type:: Currency or None

get_cost_currency(self) → Currency¶

Return the currency used for PnL calculations for the instrument.

Standard linear instruments = quote_currency
Inverse instruments = base_currency
Quanto instruments TBD

Return type:: Currency

get_settlement_currency(self) → Currency¶

Return the currency used to settle a trade of the instrument.

Standard linear instruments = quote_currency
Inverse instruments = base_currency
Quanto instruments = settlement_currency

Return type:: Currency

id¶

The instrument ID.

Returns:: InstrumentId

info¶

The raw info for the instrument.

Returns:: dict[str, object]

instrument_class¶

The class of the instrument.

Returns:: InstrumentClass

is_inverse¶

If the quantity is expressed in quote currency.

Returns:: bool

classmethod is_signal(cls, str name='') → bool¶

Determine if the current class is a signal type, optionally checking for a specific signal name.

Parameters:: name (str, optional) – The specific signal name to check. If name not provided or if an empty string is passed, the method checks whether the class name indicates a general signal type. If name is provided, the method checks if the class name corresponds to that specific signal.
Returns:: True if the class name matches the signal type or the specific signal name, otherwise False.
Return type:: bool

is_spread(self) → bool¶

Return whether the instrument is a spread instrument.

Return type:: bool

legs(self) → list¶

Return the list of leg tuples (instrument_id, ratio) for this spread.

Base implementation returns an empty list. Override in spread instrument classes to return the actual legs.

Returns:: List of tuples containing (instrument_id, ratio) for each leg.
Return type:: list[tuple[InstrumentId, int]]

lot_size¶

The rounded lot unit size (standard/board) for the instrument.

Returns:: Quantity or None

make_price(self, value) → Price¶

Return a new price from the given value using the instruments price precision.

Parameters:: value (integer, float, str or Decimal) – The value of the price.
Return type:: Price

make_qty(self, value, bool round_down=False) → Quantity¶

Return a new quantity from the given value using the instruments size precision.

Parameters:

value (integer, float, str or Decimal) – The value of the quantity.
round_down (bool, default False) – If True, always rounds down to the nearest valid increment. If False, uses the round function (banker’s rounding) which rounds to the nearest even digit when exactly halfway between two values.

Return type:

Raises:

ValueError – If a non zero value is rounded to zero due to the instruments size increment or size precision.

maker_fee¶

The fee rate for liquidity makers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

margin_init¶

The initial (order) margin rate for the instrument.

Returns:: Decimal

margin_maint¶

The maintenance (position) margin rate for the instrument.

Returns:: Decimal

max_notional¶

The maximum notional order value for the instrument.

Returns:: Money or None

max_price¶

The maximum printable price for the instrument.

Returns:: Price or None

max_quantity¶

The maximum order quantity for the instrument.

Returns:: Quantity or None

min_notional¶

The minimum notional order value for the instrument.

Returns:: Money or None

min_price¶

The minimum printable price for the instrument.

Returns:: Price or None

min_quantity¶

The minimum order quantity for the instrument.

Returns:: Quantity or None

multiplier¶

The contract multiplier for the instrument (determines tick value).

Returns:: Quantity

next_ask_price(self, double value, int num_ticks=0) → Price¶

Return the price n ask ticks away from value.

If a given price is between two ticks, n=0 will find the nearest ask tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_ask_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks ask ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of ask prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_price(self, double value, int num_ticks=0) → Price¶

Return the price n bid ticks away from value.

If a given price is between two ticks, n=0 will find the nearest bid tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks bid ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of bid prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

notional_value(self, Quantity quantity, Price price, bool use_quote_for_inverse=False, Currency target_currency=None, Price conversion_price=None) → Money¶

Calculate the notional value.

Result will be in quote currency for standard instruments, or base currency for inverse instruments.

If target_currency and conversion_price are provided, the notional value will be converted to the target currency.

Parameters:

quantity (Quantity) – The total quantity.
price (Price) – The price for the calculation.
use_quote_for_inverse (bool) – If inverse instrument calculations use quote currency (instead of base).
target_currency (Currency, optional) – The target currency for conversion.
conversion_price (Price, optional) – The price to use for currency conversion.

Return type:

option_kind¶

The option kind (PUT | CALL) for the contract.

Returns:: OptionKind

price_increment¶

The minimum price increment or tick size for the instrument.

Returns:: Price

price_precision¶

The price precision of the instrument.

Returns:: int

quote_currency¶

The quote currency for the instrument.

Returns:: Currency

raw_symbol¶

The raw/local/native symbol for the instrument, assigned by the venue.

Returns:: Symbol

set_tick_scheme(self, str tick_scheme_name) → void¶

Set the tick scheme for the instrument.

Sets both the tick_scheme_name and the corresponding tick scheme implementation used for price rounding and tick calculations.

This will override any previously set tick scheme, including the tick_scheme_name field.

Parameters:

tick_scheme_name (str) – The name of the registered tick scheme.

Raises:

ValueError – If tick_scheme_name is not a valid string.
ValueError – If tick_scheme_name is not a registered tick scheme.

size_increment¶

The minimum size increment for the instrument.

Returns:: Quantity

size_precision¶

The size precision of the instrument.

Returns:: int

strike_price¶

The strike price for the contract.

Returns:: Price

symbol¶

Return the instruments ticker symbol.

Return type:: Symbol

taker_fee¶

The fee rate for liquidity takers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

tick_scheme_name¶

The tick scheme name.

Returns:: str or None

static to_dict(OptionContract obj) → dict[str, object]¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

ts_event¶

UNIX timestamp (nanoseconds) when the data event occurred.

Returns:: uint64_t

ts_init¶

UNIX timestamp (nanoseconds) when the object was initialized.

Returns:: uint64_t

underlying¶

The underlying asset for the contract.

Returns:: str

venue¶

Return the instruments trading venue.

Return type:: Venue

class OptionSpread¶

Bases: Instrument

Represents a generic option spread instrument.

Parameters:

instrument_id (InstrumentId) – The instrument ID.
raw_symbol (Symbol) – The raw/local/native symbol for the instrument, assigned by the venue.
asset_class (AssetClass) – The option spread asset class.
currency (Currency) – The option spread currency.
price_precision (int) – The price decimal precision.
price_increment (Price) – The minimum price increment (tick size).
multiplier (Quantity) – The option multiplier.
lot_size (Quantity) – The rounded lot unit size (standard/board).
underlying (str) – The underlying asset.
strategy_type (str) – The strategy type of the spread.
activation_ns (uint64_t) – UNIX timestamp (nanoseconds) for contract activation.
expiration_ns (uint64_t) – UNIX timestamp (nanoseconds) for contract expiration.
ts_event (uint64_t) – UNIX timestamp (nanoseconds) when the data event occurred.
ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the data object was initialized.
margin_init (Decimal, optional) – The initial (order) margin requirement in percentage of order value.
margin_maint (Decimal, optional) – The maintenance (position) margin in percentage of position value.
maker_fee (Decimal, optional) – The fee rate for liquidity makers as a percentage of order value.
taker_fee (Decimal, optional) – The fee rate for liquidity takers as a percentage of order value.
exchange (str, optional) – The exchange ISO 10383 Market Identifier Code (MIC) where the instrument trades.
tick_scheme_name (str, optional) – The name of the tick scheme.
info (dict[str, object], optional) – The additional instrument information.

Raises:

ValueError – If strategy_type is not a valid string.
ValueError – If multiplier is not positive (> 0).
ValueError – If price_precision is negative (< 0).
ValueError – If tick_size is not positive (> 0).
ValueError – If lot_size is not positive (> 0).
ValueError – If margin_init is negative (< 0).
ValueError – If margin_maint is negative (< 0).
ValueError – If exchange is not None and not a valid string.

activation_ns¶

UNIX timestamp (nanoseconds) for contract activation.

Returns:: unit64_t

activation_utc¶

pd.Timestamp

Return the contract activation timestamp (UTC).

Returns:: tz-aware UTC.
Return type:: pd.Timestamp
Type:: OptionSpread.activation_utc

asset_class¶

The asset class of the instrument.

Returns:: AssetClass

static base_from_dict(dict values) → Instrument¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: Instrument

static base_to_dict(Instrument obj)¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

calculate_base_quantity(self, Quantity quantity, Price last_px) → Quantity¶

Calculate the base asset quantity from the given quote asset quantity and last price.

Parameters:

quantity (Quantity) – The quantity to convert from.
last_px (Price) – The last price for the instrument.

Return type:

exchange¶

The exchang ISO 10383 Market Identifier Code (MIC) where the instrument trades.

Returns:: str or None

expiration_ns¶

UNIX timestamp (nanoseconds) for contract expiration.

Returns:: unit64_t

expiration_utc¶

pd.Timestamp

Return the contract expiration timestamp (UTC).

Returns:: tz-aware UTC.
Return type:: pd.Timestamp
Type:: OptionSpread.expiration_utc

static from_dict(dict values) → OptionSpread¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: OptionSpread

static from_pyo3(pyo3_instrument) → OptionSpread¶

Return legacy Cython option spread instrument converted from the given pyo3 Rust object.

Parameters:: pyo3_instrument (nautilus_pyo3.OptionSpread) – The pyo3 Rust option spread instrument to convert from.
Return type:: OptionSpread

classmethod fully_qualified_name(cls) → str¶

Return the fully qualified name for the Data class.

Return type:: str

References

get_base_currency(self) → Currency¶

Return the instruments base currency (if applicable).

Return type:: Currency or None

get_cost_currency(self) → Currency¶

Return the currency used for PnL calculations for the instrument.

Standard linear instruments = quote_currency
Inverse instruments = base_currency
Quanto instruments TBD

Return type:: Currency

get_settlement_currency(self) → Currency¶

Return the currency used to settle a trade of the instrument.

Standard linear instruments = quote_currency
Inverse instruments = base_currency
Quanto instruments = settlement_currency

Return type:: Currency

id¶

The instrument ID.

Returns:: InstrumentId

info¶

The raw info for the instrument.

Returns:: dict[str, object]

instrument_class¶

The class of the instrument.

Returns:: InstrumentClass

is_inverse¶

If the quantity is expressed in quote currency.

Returns:: bool

classmethod is_signal(cls, str name='') → bool¶

Determine if the current class is a signal type, optionally checking for a specific signal name.

Parameters:: name (str, optional) – The specific signal name to check. If name not provided or if an empty string is passed, the method checks whether the class name indicates a general signal type. If name is provided, the method checks if the class name corresponds to that specific signal.
Returns:: True if the class name matches the signal type or the specific signal name, otherwise False.
Return type:: bool

is_spread(self) → bool¶

Return whether the instrument is a spread instrument.

Return type:: bool

legs(self) → list¶

Return the list of leg tuples (instrument_id, ratio) for this spread.

If the instrument ID corresponds to a generic spread ID, returns the parsed legs using generic_spread_id_to_list. Otherwise returns an empty list.

Returns:: List of tuples containing (instrument_id, ratio) for each leg.
Return type:: list[tuple[InstrumentId, int]]

lot_size¶

The rounded lot unit size (standard/board) for the instrument.

Returns:: Quantity or None

make_price(self, value) → Price¶

Return a new price from the given value using the instruments price precision.

Parameters:: value (integer, float, str or Decimal) – The value of the price.
Return type:: Price

make_qty(self, value, bool round_down=False) → Quantity¶

Return a new quantity from the given value using the instruments size precision.

Parameters:

value (integer, float, str or Decimal) – The value of the quantity.
round_down (bool, default False) – If True, always rounds down to the nearest valid increment. If False, uses the round function (banker’s rounding) which rounds to the nearest even digit when exactly halfway between two values.

Return type:

Raises:

ValueError – If a non zero value is rounded to zero due to the instruments size increment or size precision.

maker_fee¶

The fee rate for liquidity makers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

margin_init¶

The initial (order) margin rate for the instrument.

Returns:: Decimal

margin_maint¶

The maintenance (position) margin rate for the instrument.

Returns:: Decimal

max_notional¶

The maximum notional order value for the instrument.

Returns:: Money or None

max_price¶

The maximum printable price for the instrument.

Returns:: Price or None

max_quantity¶

The maximum order quantity for the instrument.

Returns:: Quantity or None

min_notional¶

The minimum notional order value for the instrument.

Returns:: Money or None

min_price¶

The minimum printable price for the instrument.

Returns:: Price or None

min_quantity¶

The minimum order quantity for the instrument.

Returns:: Quantity or None

multiplier¶

The contract multiplier for the instrument (determines tick value).

Returns:: Quantity

next_ask_price(self, double value, int num_ticks=0) → Price¶

Return the price n ask ticks away from value.

If a given price is between two ticks, n=0 will find the nearest ask tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_ask_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks ask ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of ask prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_price(self, double value, int num_ticks=0) → Price¶

Return the price n bid ticks away from value.

If a given price is between two ticks, n=0 will find the nearest bid tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks bid ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of bid prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

notional_value(self, Quantity quantity, Price price, bool use_quote_for_inverse=False, Currency target_currency=None, Price conversion_price=None) → Money¶

Calculate the notional value.

Result will be in quote currency for standard instruments, or base currency for inverse instruments.

If target_currency and conversion_price are provided, the notional value will be converted to the target currency.

Parameters:

quantity (Quantity) – The total quantity.
price (Price) – The price for the calculation.
use_quote_for_inverse (bool) – If inverse instrument calculations use quote currency (instead of base).
target_currency (Currency, optional) – The target currency for conversion.
conversion_price (Price, optional) – The price to use for currency conversion.

Return type:

price_increment¶

The minimum price increment or tick size for the instrument.

Returns:: Price

price_precision¶

The price precision of the instrument.

Returns:: int

quote_currency¶

The quote currency for the instrument.

Returns:: Currency

raw_symbol¶

The raw/local/native symbol for the instrument, assigned by the venue.

Returns:: Symbol

set_tick_scheme(self, str tick_scheme_name) → void¶

Set the tick scheme for the instrument.

Sets both the tick_scheme_name and the corresponding tick scheme implementation used for price rounding and tick calculations.

This will override any previously set tick scheme, including the tick_scheme_name field.

Parameters:

tick_scheme_name (str) – The name of the registered tick scheme.

Raises:

ValueError – If tick_scheme_name is not a valid string.
ValueError – If tick_scheme_name is not a registered tick scheme.

size_increment¶

The minimum size increment for the instrument.

Returns:: Quantity

size_precision¶

The size precision of the instrument.

Returns:: int

strategy_type¶

The strategy type of the spread.

Returns:: str

symbol¶

Return the instruments ticker symbol.

Return type:: Symbol

taker_fee¶

The fee rate for liquidity takers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

tick_scheme_name¶

The tick scheme name.

Returns:: str or None

static to_dict(OptionSpread obj) → dict[str, object]¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

ts_event¶

UNIX timestamp (nanoseconds) when the data event occurred.

Returns:: uint64_t

ts_init¶

UNIX timestamp (nanoseconds) when the object was initialized.

Returns:: uint64_t

underlying¶

The underlying asset for the contract.

Returns:: str

venue¶

Return the instruments trading venue.

Return type:: Venue

class SyntheticInstrument¶

Bases: Data

SyntheticInstrument(Symbol symbol, uint8_t price_precision, list components, str formula, uint64_t ts_event, uint64_t ts_init) -> None

Represents a synthetic instrument with prices derived from component instruments using a formula.

The id for the synthetic will become {symbol}.{SYNTH}.

Parameters:

symbol (Symbol) – The symbol for the synthetic instrument.
price_precision (uint8_t) – The price precision for the synthetic instrument.
components (list[InstrumentId]) – The component instruments for the synthetic instrument.
formula (str) – The derivation formula for the synthetic instrument.
ts_event (uint64_t) – UNIX timestamp (nanoseconds) when the data event occurred.
ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the data object was initialized.

Raises:

ValueError – If price_precision is greater than 9.
OverflowError – If price_precision is negative (< 0).
ValueError – If the components list does not contain at least 2 instrument IDs.
ValueError – If the formula is not a valid string.
ValueError – If the formula is not a valid expression.

Warning

All component instruments should already be defined and exist in the cache prior to defining a new synthetic instrument.

calculate(self, list inputs) → Price¶

Calculate the price of the synthetic instrument from the given inputs.

Parameters:

inputs (list[double])

Return type:

Raises:

ValueError – If inputs is empty, contains a NaN value, or length is different from components count.
RuntimeError – If an internal error occurs when calculating the price.

change_formula(self, str formula) → void¶

Change the internal derivation formula for the synthetic instrument.

Parameters:

formula (str) – The derivation formula to change to.

Raises:

ValueError – If the formula is not a valid string.
ValueError – If the formula is not a valid expression.

components¶

list[InstrumentId]

Return the components of the synthetic instrument.

Return type:: list[InstrumentId]
Type:: SyntheticInstrument.components

formula¶

str

Return the synthetic instrument internal derivation formula.

Return type:: str
Type:: SyntheticInstrument.formula

static from_dict(dict values) → SyntheticInstrument¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: SyntheticInstrument

classmethod fully_qualified_name(cls) → str¶

Return the fully qualified name for the Data class.

Return type:: str

References

id¶

The instrument ID.

Returns:: InstrumentId

classmethod is_signal(cls, str name='') → bool¶

Determine if the current class is a signal type, optionally checking for a specific signal name.

Parameters:: name (str, optional) – The specific signal name to check. If name not provided or if an empty string is passed, the method checks whether the class name indicates a general signal type. If name is provided, the method checks if the class name corresponds to that specific signal.
Returns:: True if the class name matches the signal type or the specific signal name, otherwise False.
Return type:: bool

price_increment¶

Price

Return the minimum price increment (tick size) for the synthetic instrument.

Return type:: Price
Type:: SyntheticInstrument.price_increment

price_precision¶

int

Return the precision for the synthetic instrument.

Return type:: int
Type:: SyntheticInstrument.price_precision

static to_dict(SyntheticInstrument obj) → dict[str, object]¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

ts_event¶

int

UNIX timestamp (nanoseconds) when the data event occurred.

Return type:: int
Type:: SyntheticInstrument.ts_event

ts_init¶

int

UNIX timestamp (nanoseconds) when the object was initialized.

Return type:: int
Type:: SyntheticInstrument.ts_init

class Instrument¶

Bases: Data

The base class for all instruments.

Represents a tradable instrument. This class can be used to define an instrument, or act as a parent class for more specific instruments.

Parameters:

instrument_id (InstrumentId) – The instrument ID for the instrument.
raw_symbol (Symbol) – The raw/local/native symbol for the instrument, assigned by the venue.
asset_class (AssetClass) – The instrument asset class.
instrument_class (InstrumentClass) – The instrument class.
quote_currency (Currency) – The quote currency.
is_inverse (bool) – If the instrument costing is inverse (quantity expressed in quote currency units).
price_precision (int) – The price decimal precision.
size_precision (int) – The trading size decimal precision.
size_increment (Quantity) – The minimum size increment.
multiplier (Quantity) – The contract value multiplier (determines tick value).
lot_size (Quantity, optional) – The rounded lot unit size (standard/board).
margin_init (Decimal) – The initial (order) margin requirement in percentage of order value.
margin_maint (Decimal) – The maintenance (position) margin in percentage of position value.
maker_fee (Decimal) – The fee rate for liquidity makers as a percentage of order value (where 1.0 is 100%).
taker_fee (Decimal) – The fee rate for liquidity takers as a percentage of order value (where 1.0 is 100%).
ts_event (uint64_t) – UNIX timestamp (nanoseconds) when the data event occurred.
ts_init (uint64_t) – UNIX timestamp (nanoseconds) when the data object was initialized.
price_increment (Price, optional) – The minimum price increment (tick size).
max_quantity (Quantity, optional) – The maximum allowable order quantity.
min_quantity (Quantity, optional) – The minimum allowable order quantity.
max_notional (Money, optional) – The maximum allowable order notional value.
min_notional (Money, optional) – The minimum allowable order notional value.
max_price (Price, optional) – The maximum allowable quoted price.
min_price (Price, optional) – The minimum allowable quoted price.
tick_scheme_name (str, optional) – The name of the tick scheme.
info (dict[str, object], optional) – The additional instrument information.

Raises:

ValueError – If tick_scheme_name is not a valid string.
ValueError – If price_precision is negative (< 0).
ValueError – If size_precision is negative (< 0).
ValueError – If price_increment is not positive (> 0).
ValueError – If size_increment is not positive (> 0).
ValueError – If price_precision is not equal to price_increment.precision.
ValueError – If size_increment is not equal to size_increment.precision.
ValueError – If multiplier is not positive (> 0).
ValueError – If margin_init is negative (< 0).
ValueError – If margin_maint is negative (< 0).
ValueError – If lot size is not positive (> 0).
ValueError – If max_quantity is not positive (> 0).
ValueError – If min_quantity is negative (< 0).
ValueError – If max_notional is not positive (> 0).
ValueError – If min_notional is negative (< 0).
ValueError – If max_price is not positive (> 0).
ValueError – If min_price is negative (< 0).

asset_class¶

The asset class of the instrument.

Returns:: AssetClass

static base_from_dict(dict values) → Instrument¶

Return an instrument from the given initialization values.

Parameters:: values (dict[str, object]) – The values to initialize the instrument with.
Return type:: Instrument

static base_to_dict(Instrument obj)¶

Return a dictionary representation of this object.

Return type:: dict[str, object]

calculate_base_quantity(self, Quantity quantity, Price last_px) → Quantity¶

Calculate the base asset quantity from the given quote asset quantity and last price.

Parameters:

quantity (Quantity) – The quantity to convert from.
last_px (Price) – The last price for the instrument.

Return type:

classmethod fully_qualified_name(cls) → str¶

Return the fully qualified name for the Data class.

Return type:: str

References

get_base_currency(self) → Currency¶

Return the instruments base currency (if applicable).

Return type:: Currency or None

get_cost_currency(self) → Currency¶

Return the currency used for PnL calculations for the instrument.

Standard linear instruments = quote_currency
Inverse instruments = base_currency
Quanto instruments TBD

Return type:: Currency

get_settlement_currency(self) → Currency¶

Return the currency used to settle a trade of the instrument.

Standard linear instruments = quote_currency
Inverse instruments = base_currency
Quanto instruments = settlement_currency

Return type:: Currency

id¶

The instrument ID.

Returns:: InstrumentId

info¶

The raw info for the instrument.

Returns:: dict[str, object]

instrument_class¶

The class of the instrument.

Returns:: InstrumentClass

is_inverse¶

If the quantity is expressed in quote currency.

Returns:: bool

classmethod is_signal(cls, str name='') → bool¶

Determine if the current class is a signal type, optionally checking for a specific signal name.

Parameters:: name (str, optional) – The specific signal name to check. If name not provided or if an empty string is passed, the method checks whether the class name indicates a general signal type. If name is provided, the method checks if the class name corresponds to that specific signal.
Returns:: True if the class name matches the signal type or the specific signal name, otherwise False.
Return type:: bool

is_spread(self) → bool¶

Return whether the instrument is a spread instrument.

Return type:: bool

legs(self) → list¶

Return the list of leg tuples (instrument_id, ratio) for this spread.

Base implementation returns an empty list. Override in spread instrument classes to return the actual legs.

Returns:: List of tuples containing (instrument_id, ratio) for each leg.
Return type:: list[tuple[InstrumentId, int]]

lot_size¶

The rounded lot unit size (standard/board) for the instrument.

Returns:: Quantity or None

make_price(self, value) → Price¶

Return a new price from the given value using the instruments price precision.

Parameters:: value (integer, float, str or Decimal) – The value of the price.
Return type:: Price

make_qty(self, value, bool round_down=False) → Quantity¶

Return a new quantity from the given value using the instruments size precision.

Parameters:

value (integer, float, str or Decimal) – The value of the quantity.
round_down (bool, default False) – If True, always rounds down to the nearest valid increment. If False, uses the round function (banker’s rounding) which rounds to the nearest even digit when exactly halfway between two values.

Return type:

Raises:

ValueError – If a non zero value is rounded to zero due to the instruments size increment or size precision.

maker_fee¶

The fee rate for liquidity makers as a percentage of order value (where 1.0 is 100%).

Returns:: Decimal

margin_init¶

The initial (order) margin rate for the instrument.

Returns:: Decimal

margin_maint¶

The maintenance (position) margin rate for the instrument.

Returns:: Decimal

max_notional¶

The maximum notional order value for the instrument.

Returns:: Money or None

max_price¶

The maximum printable price for the instrument.

Returns:: Price or None

max_quantity¶

The maximum order quantity for the instrument.

Returns:: Quantity or None

min_notional¶

The minimum notional order value for the instrument.

Returns:: Money or None

min_price¶

The minimum printable price for the instrument.

Returns:: Price or None

min_quantity¶

The minimum order quantity for the instrument.

Returns:: Quantity or None

multiplier¶

The contract multiplier for the instrument (determines tick value).

Returns:: Quantity

next_ask_price(self, double value, int num_ticks=0) → Price¶

Return the price n ask ticks away from value.

If a given price is between two ticks, n=0 will find the nearest ask tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_ask_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks ask ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of ask prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_price(self, double value, int num_ticks=0) → Price¶

Return the price n bid ticks away from value.

If a given price is between two ticks, n=0 will find the nearest bid tick.

Parameters:

value (double) – The reference value.
num_ticks (int, default 0) – The number of ticks to move.

Return type:

Raises:

ValueError – If a tick scheme is not initialized.

next_bid_prices(self, double value, int num_ticks=100) → list¶

Return a list of prices up to num_ticks bid ticks away from value.

Parameters:

value (double) – The reference value.
num_ticks (int, default 100) – The number of ticks to return.

Returns:

A list of bid prices as Decimal values.

Return type:

list[Decimal]

Raises:

ValueError – If a tick scheme is not initialized.

notional_value(self, Quantity quantity, Price price, bool use_quote_for_inverse=False, Currency target_currency=None, Price conversion_price=None) → Money¶

Calculate the notional value.

Result will be in quote currency for standard instruments, or base currency for inverse instruments.

If target_currency and conversion_price are provided, the notional value will be converted to the target currency.

Parameters:

quantity (Quantity) – The total quantity.
price (Price) – The price for the calculation.
use_quote_for_inverse (bool) – If inverse instrument calculations use quote currency (instead of base).
target_currency (Currency, optional) – The target currency for conversion.
conversion_price (Price, optional) – The price to use for currency conversion.

Return type: