How Exchange-Defined Futures Spreads Are Represented as Instruments
Article NautilusTrader
Summary
This reference explains how an exchange-defined futures spread is represented as a single tradable instrument, including calendar and inter-commodity spreads. The venue supplies the strategy symbol, tick size, expiry, and other contract details. The specification lists identifying fields, underlying product and strategy type, activation and expiration times, settlement currency, price and size increments, multiplier, lot size, optional margin and quantity bounds, and timestamps. It distinguishes the native venue symbol from the instrument identifier and notes that adapter metadata may hold venue-specific leg details.
The behavior notes emphasize that spreads trade in whole contracts and that their prices may be zero or negative; the risk engine accepts non-positive prices for this instrument class. Rust and Python construction examples illustrate how to populate a spread definition, and named adapters show where such instruments may be encountered. This is primarily a data-model and integration reference, rather than a trading method or analysis of spread returns. It does not explain how to choose spread legs, value a spread, manage leg risk, or assess liquidity, so those questions require other sources.
Key ideas
- An exchange-defined futures spread is represented as one tradable instrument, even when it has multiple legs.
- The venue determines key contract details such as symbol, tick size, and expiry.
- Spread contracts use whole-number size increments, and their prices may be zero or negative.
- Adapter metadata can provide venue-specific information about the spread legs.
- The reference documents instrument fields and construction examples, not spread valuation or trading performance.
Tags
Full text
# Futures Spread
# Futures Spread
`FuturesSpread` represents an exchange-defined futures strategy with more than one leg,
such as a calendar spread or inter-commodity spread. The venue defines the strategy,
symbol, tick size, and expiry.
Examples include listed futures calendar spreads and exchange-supported spread markets.
## 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. |
| `asset_class` | `AssetClass` | `AssetClass` | Required | Asset class of the underlying strategy. |
| `exchange` | `Option<Ustr>` | `str \| None` | `None` | Exchange MIC or venue code when known. |
| `underlying` | `Ustr` | `str` | Required | Underlying product or product family. |
| `strategy_type` | `Ustr` | `str` | Required | Venue strategy type, such as calendar. |
| `activation_ns` | `UnixNanos` | `int` | Required | Strategy activation timestamp. |
| `expiration_ns` | `UnixNanos` | `int` | Required | Strategy expiration timestamp. |
| `currency` | `Currency` | `Currency` | Required | Quote and settlement currency. |
| `price_precision` | `u8` | `int` | Required | Decimal places allowed for prices. |
| `price_increment` | `Price` | `Price` | Required | Smallest valid price step. |
| `size_precision` | `u8` | `int` | Fixed `0` | Futures spreads trade in whole contracts. |
| `size_increment` | `Quantity` | `Quantity` | Fixed `1` | Minimum contract size step. |
| `multiplier` | `Quantity` | `Quantity` | Required | Strategy multiplier. |
| `lot_size` | `Quantity` | `Quantity` | Required | Rounded lot or contract lot size. |
| `margin_init` | `Option<Decimal>` | `Decimal \| None` | `0` | Initial margin rate. |
| `margin_maint` | `Option<Decimal>` | `Decimal \| None` | `0` | Maintenance margin rate. |
| `max_quantity` | `Option<Quantity>` | `Quantity \| None` | `None` | Maximum order quantity. |
| `min_quantity` | `Option<Quantity>` | `Quantity \| None` | `1` | Minimum order quantity. |
| `max_price` | `Option<Price>` | `Price \| None` | `None` | Maximum valid quote or order price. |
| `min_price` | `Option<Price>` | `Price \| None` | `None` | Minimum valid quote or order price. |
| `tick_scheme` | `Option<Ustr>` | `str \| None` | `None` | Registered variable tick scheme name. |
| `info` | `Option<Params>` | `dict \| None` | `None` | Adapter metadata. |
| `ts_event` | `UnixNanos` | `int` | Required | Event timestamp in nanoseconds. |
| `ts_init` | `UnixNanos` | `int` | Required | Initialization timestamp in nanoseconds. |
*Note: Python constructors use `instrument_id`; Rust stores the same value as `id`.*
## Behavior
- `FuturesSpread` has instrument class `FuturesSpread`.
- The venue publishes the spread as a single tradable instrument.
- It trades in whole contracts with size precision `0` and size increment `1`.
- Spread prices can be zero or negative, and the `RiskEngine` accepts non-positive prices
for this instrument class.
- Use leg data from the adapter metadata when a strategy needs venue-specific leg details.
## Example
```rust tab="Rust"
use jiff::Timestamp;
use nautilus_core::UnixNanos;
use nautilus_model::{
enums::AssetClass,
identifiers::{InstrumentId, Symbol},
instruments::FuturesSpread,
types::{Currency, Price, Quantity},
};
use ustr::Ustr;
let activation: Timestamp = "2022-06-21T13:30:00Z".parse().unwrap();
let expiration: Timestamp = "2024-06-21T13:30:00Z".parse().unwrap();
let es_spread = FuturesSpread::builder()
.instrument_id(InstrumentId::from("ESM4-ESU4.GLBX"))
.raw_symbol(Symbol::from("ESM4-ESU4"))
.asset_class(AssetClass::Index)
.exchange(Ustr::from("XCME"))
.underlying(Ustr::from("ES"))
.strategy_type(Ustr::from("EQ"))
.activation_ns(UnixNanos::from(activation))
.expiration_ns(UnixNanos::from(expiration))
.currency(Currency::from("USD"))
.price_precision(2)
.price_increment(Price::from("0.01"))
.multiplier(Quantity::from("1"))
.lot_size(Quantity::from("1"))
.ts_event(UnixNanos::default())
.ts_init(UnixNanos::default())
.build()
.unwrap();
```
```python tab="Python"
import pandas as pd
from nautilus_trader.model import AssetClass
from nautilus_trader.model import Currency
from nautilus_trader.model import FuturesSpread
from nautilus_trader.model import InstrumentId
from nautilus_trader.model import Price
from nautilus_trader.model import Quantity
from nautilus_trader.model import Symbol
es_spread = FuturesSpread(
instrument_id=InstrumentId.from_str("ESM4-ESU4.GLBX"),
raw_symbol=Symbol("ESM4-ESU4"),
asset_class=AssetClass.INDEX,
underlying="ES",
strategy_type="EQ",
activation_ns=pd.Timestamp("2022-06-21T13:30:00", tz="UTC").value,
expiration_ns=pd.Timestamp("2024-06-21T13:30:00", tz="UTC").value,
currency=Currency.from_str("USD"),
price_precision=2,
price_increment=Price.from_str("0.01"),
multiplier=Quantity.from_int(1),
lot_size=Quantity.from_int(1),
ts_event=0,
ts_init=0,
exchange="XCME",
)
```
## Adapters
Representative adapters that create or consume `FuturesSpread` instruments include:
- [Databento](../../integrations/databento.md) for listed futures spread markets.
- [Interactive Brokers](../../integrations/interactive_brokers.md) for exchange-defined futures strategies.
## Related guides
- [Futures Contract](futures_contract.md) covers single-leg futures.
- [Continuous Futures](../continuous_futures.md) covers roll-adjusted futures series.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.