ContextQMD
Back to Nautilus Trader

Synthetic Instrument

docs/concepts/instruments/synthetic_instrument.md

1.230.04.3 KB
Original Source

Synthetic Instrument

SyntheticInstrument represents a local instrument whose price comes from a formula over other instruments. It is useful for spreads, baskets, ratios, and other derived prices that should appear in the system as an instrument.

Examples include (BTC.BINANCE + LTC.BINANCE) / 2.0 and ratio-style pairs built from component instrument prices.

Fields

<Tabs items={["Rust", "Python"]}> <Tab value="Rust">

FieldTypeRequired/defaultNotes
symbolSymbolRequiredSynthetic symbol used with venue SYNTH.
idInstrumentIdDerivedInstrument ID formed from symbol.SYNTH.
price_precisionu8RequiredDecimal places allowed for synthetic price.
price_incrementPriceDerivedSmallest price step from precision.
componentsVec<InstrumentId>RequiredComponent instruments used by the formula.
formulaStringRequiredNumeric expression over component IDs.
ts_eventUnixNanosRequiredEvent timestamp in nanoseconds.
ts_initUnixNanosRequiredInitialization timestamp in nanoseconds.
</Tab> <Tab value="Python">
FieldTypeRequired/defaultNotes
symbolSymbolRequiredSynthetic symbol used with venue SYNTH.
idInstrumentIdDerivedInstrument ID formed from symbol.SYNTH.
price_precisionintRequiredDecimal places allowed for synthetic price.
price_incrementPriceDerivedSmallest price step from precision.
componentslist[InstrumentId]RequiredComponent instruments used by the formula.
formulastrRequiredNumeric expression over component IDs.
ts_eventintRequiredEvent timestamp in nanoseconds.
ts_initintRequiredInitialization timestamp in nanoseconds.
</Tab> </Tabs>

Note: Python constructs the instrument ID from symbol and the SYNTH venue. Rust stores the same value as id.

Behavior

  • SyntheticInstrument is local to Nautilus and does not represent a venue orderable market.
  • It always uses the synthetic venue SYNTH.
  • Python requires at least two component instrument IDs.
  • The formula must compile against the supplied component identifiers before the object is valid.
  • It has no venue limits, margins, fees, order book, or adapter-specific metadata.

Example

rust
use nautilus_core::UnixNanos;
use nautilus_model::{
    identifiers::{InstrumentId, Symbol},
    instruments::SyntheticInstrument,
};

let synthetic = SyntheticInstrument::new(
    Symbol::from("BTC-LTC"),
    2,
    vec![
        InstrumentId::from("BTC.BINANCE"),
        InstrumentId::from("LTC.BINANCE"),
    ],
    "(BTC.BINANCE + LTC.BINANCE) / 2.0",
    UnixNanos::default(),
    UnixNanos::default(),
);
python
from nautilus_trader.model import InstrumentId
from nautilus_trader.model import Symbol
from nautilus_trader.model import SyntheticInstrument

synthetic = SyntheticInstrument(
    symbol=Symbol("BTC-LTC"),
    price_precision=2,
    components=[
        InstrumentId.from_str("BTC.BINANCE"),
        InstrumentId.from_str("LTC.BINANCE"),
    ],
    formula="(BTC.BINANCE + LTC.BINANCE) / 2.0",
    ts_event=0,
    ts_init=0,
)

Adapters

SyntheticInstrument is local only. It derives prices from component instruments that may come from any adapter already loaded into the system.

  • Synthetics covers formula-derived instruments and synthetic bars.
  • Data explains market data that references instruments.