Instrument Trading Status Events

Article NautilusTrader

Summary

The document explains a data object for recording changes in an instrument's venue trading state. It includes the instrument identifier, a normalized status action, event and initialization timestamps, and optional fields for a reason, venue event label, trading availability, quoting availability, and short-sale restrictions. The described states include transitions such as pre-open, trading, halt, pause, and close.

Optional state fields let data adapters preserve information supplied by a venue without filling in unknown values. The normalized action provides a consistent high-level status alongside venue-specific details. Strategies can receive these updates through a status callback, which can support handling changes in trading or quoting availability. The document provides Rust and Python examples of constructing an event, but no exchange-specific mappings, scheduling behavior, or strategy outcomes. Implementations still depend on adapters to translate venue messages accurately and on strategies to decide how each state should affect orders and positions.

Key ideas

An instrument status event records a venue state change with event and initialization timestamps.
A normalized action can be stored alongside venue-specific reason and event details.
Optional booleans preserve known trading, quoting, and short-sale restriction states without guessing unknown values.
Strategies can respond to status updates through an instrument-status callback.
The examples show construction in Rust and Python, but do not specify venue mappings or trading responses.

Tags

Market microstructure Execution Risk management

Full text

# InstrumentStatus


# InstrumentStatus

`InstrumentStatus` represents a change in an instrument's trading state. It captures venue status
events such as pre-open, trading, halt, pause, close, and short-selling restriction changes.

## Fields

| Field                      | Rust type            | Python type          | Required/default | Notes                                     |
| -------------------------- | -------------------- | -------------------- | ---------------- | ----------------------------------------- |
| `instrument_id`            | `InstrumentId`       | `InstrumentId`       | Required         | Instrument whose status changed.          |
| `action`                   | `MarketStatusAction` | `MarketStatusAction` | Required         | Venue status action.                      |
| `ts_event`                 | `UnixNanos`          | `int`                | Required         | Event timestamp in nanoseconds.           |
| `ts_init`                  | `UnixNanos`          | `int`                | Required         | Initialization timestamp in nanoseconds.  |
| `reason`                   | `Option<Ustr>`       | `str \| None`        | `None`           | Cause of the status change when provided. |
| `trading_event`            | `Option<Ustr>`       | `str \| None`        | `None`           | Venue event label when provided.          |
| `is_trading`               | `Option<bool>`       | `bool \| None`       | `None`           | Whether trading is enabled when known.    |
| `is_quoting`               | `Option<bool>`       | `bool \| None`       | `None`           | Whether quoting is enabled when known.    |
| `is_short_sell_restricted` | `Option<bool>`       | `bool \| None`       | `None`           | Short-sell restriction state when known.  |

## Behavior

- Optional booleans allow adapters to preserve venue-provided state without guessing.
- `action` gives the normalized high-level status even when venue-specific details are
  also stored in `reason` or `trading_event`.
- Strategies can handle status updates through `on_instrument_status(...)`.

## Example

```rust tab="Rust"
use nautilus_core::UnixNanos;
use nautilus_model::{
    data::InstrumentStatus,
    enums::MarketStatusAction,
    identifiers::InstrumentId,
};
use ustr::Ustr;

let status = InstrumentStatus::new(
    InstrumentId::from("AAPL.XNAS"),
    MarketStatusAction::Trading,
    UnixNanos::from(1_000_000_000),
    UnixNanos::from(1_000_000_100),
    Some(Ustr::from("Normal trading")),
    Some(Ustr::from("MARKET_OPEN")),
    Some(true),
    Some(true),
    Some(false),
);
```

```python tab="Python"
from nautilus_trader.model import InstrumentId
from nautilus_trader.model import InstrumentStatus
from nautilus_trader.model import MarketStatusAction

status = InstrumentStatus(
    instrument_id=InstrumentId.from_str("AAPL.XNAS"),
    action=MarketStatusAction.TRADING,
    ts_event=1_000_000_000,
    ts_init=1_000_000_100,
    reason="Normal trading",
    trading_event="MARKET_OPEN",
    is_trading=True,
    is_quoting=True,
    is_short_sell_restricted=False,
)
```

## Related guides

- [InstrumentClose](instrument_close.md) covers instrument close price events.
- [Instruments](../instruments/) covers instrument definitions.
- [Python API reference](/docs/python-api-latest/model/data.html) lists Python members.

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.

Representing Instrument Trading Status as Timestamped Events

Summary

Key ideas

Tags