Reference Index Instrument Modeling

Article NautilusTrader

Summary

This document explains a data model for reference indexes such as equity benchmarks and volatility indexes. An index instrument stores identifiers, its native symbol, quote currency, price and size precision, valid increments, timestamps, and optional tick-scheme and adapter metadata. Rust and Python field representations are listed, with an example showing how an index definition can be constructed in either language.

The central operational distinction is that this object represents a reference price series, not an orderable contract. It has no margin, fees, expiry, multiplier, or settlement currency. To trade exposure to an index, the document directs users to model the relevant listed option or futures contract instead. It also notes that a brokerage adapter can create these definitions. The examples clarify the required metadata, but the document does not describe market data ingestion, execution, or a trading strategy.

Key ideas

An index instrument represents benchmark data rather than a directly tradable contract.
Its metadata includes price and size precision, increments, currency, identifiers, and timestamps.
Optional fields can carry tick-scheme and adapter-specific information.
Index reference instruments have no contract expiry, margin, fee, or settlement terms.
Tradable index exposure should be represented by the corresponding option or futures instrument.

Tags

Multi-asset Futures Options Market microstructure

Full text

# Index Instrument


# Index Instrument

`IndexInstrument` represents a reference index such as an equity index, volatility index,
or benchmark price series. It carries precision and increment metadata so Nautilus can
store and route prices consistently, but it is not a directly tradable contract.

Examples include `SPX.XCBO`, `VIX.XCBO`, and venue-specific reference indexes.

## Fields

| Field             | Rust type        | Python type    | Required/default | Notes                                    |
| ----------------- | ---------------- | -------------- | ---------------- | ---------------------------------------- |
| `instrument_id`   | `InstrumentId`   | `InstrumentId` | Required         | Stored as `id` in Rust.                  |
| `raw_symbol`      | `Symbol`         | `Symbol`       | Required         | Native venue symbol.                     |
| `currency`        | `Currency`       | `Currency`     | Required         | Reference currency for quoted values.    |
| `price_precision` | `u8`             | `int`          | Required         | Decimal places allowed for prices.       |
| `size_precision`  | `u8`             | `int`          | Required         | Decimal places allowed for quantities.   |
| `price_increment` | `Price`          | `Price`        | Required         | Smallest valid price step.               |
| `size_increment`  | `Quantity`       | `Quantity`     | Required         | Smallest valid size step.                |
| `ts_event`        | `UnixNanos`      | `int`          | Required         | Event timestamp in nanoseconds.          |
| `ts_init`         | `UnixNanos`      | `int`          | Required         | Initialization timestamp in nanoseconds. |
| `tick_scheme`     | `Option<Ustr>`   | `str \| None`  | `None`           | Registered variable tick scheme name.    |
| `info`            | `Option<Params>` | `dict \| None` | `None`           | Adapter metadata.                        |

*Note: Python constructors use `instrument_id`; Rust stores the same value as `id`.*

## Behavior

- `IndexInstrument` has asset class `Index` and instrument class `Spot`.
- It has no limits, margins, fees, contract multiplier, expiry, or settlement currency.
- Use option or futures types for tradable derivatives whose underlyings are indexes.

:::warning
`IndexInstrument` is a reference instrument, not a tradable contract. Do not submit orders
against it; trade the corresponding futures or option instrument instead.
:::

## Example

```rust tab="Rust"
use nautilus_core::UnixNanos;
use nautilus_model::{
    identifiers::{InstrumentId, Symbol},
    instruments::IndexInstrument,
    types::{Currency, Price, Quantity},
};

let spx = IndexInstrument::builder()
    .instrument_id(InstrumentId::from("SPX.XCBO"))
    .raw_symbol(Symbol::from("SPX"))
    .currency(Currency::from("USD"))
    .price_precision(2)
    .size_precision(0)
    .price_increment(Price::from("0.01"))
    .size_increment(Quantity::from("1"))
    .ts_event(UnixNanos::default())
    .ts_init(UnixNanos::default())
    .build()
    .unwrap();
```

```python tab="Python"
from nautilus_trader.model import Currency
from nautilus_trader.model import IndexInstrument
from nautilus_trader.model import InstrumentId
from nautilus_trader.model import Price
from nautilus_trader.model import Quantity
from nautilus_trader.model import Symbol

spx = IndexInstrument(
    instrument_id=InstrumentId.from_str("SPX.XCBO"),
    raw_symbol=Symbol("SPX"),
    currency=Currency.from_str("USD"),
    price_precision=2,
    size_precision=0,
    price_increment=Price.from_str("0.01"),
    size_increment=Quantity.from_str("1"),
    ts_event=0,
    ts_init=0,
)
```

## Adapters

The [Interactive Brokers](../../integrations/interactive_brokers.md) adapter creates
`IndexInstrument` definitions for reference indexes.

## Related guides

- [Option Contract](option_contract.md) covers listed options on index underlyings.
- [Futures Contract](futures_contract.md) covers index futures.

Shown in full with attribution under the source's licence. Licence: LGPL-3.0

This summary was written by Stratmill's research agent from the original; it is not a copy of the source.

Modeling Reference Indexes Separately from Tradable Contracts

Summary

Key ideas

Tags