Martingale42/nautilus-dev / skills/nt-model
nt-model
VerifiedUse when working with domain model types, instruments, identifiers, value types, enums, or currencies in NautilusTrader.
nt-model
What This Skill Covers
NautilusTrader domain model — instruments, identifiers, value types, enums, and currencies.
Python modules: model/identifiers, model/instruments/ (14 types), model/types/, model/objects, model/enums, model/tick_scheme/
Rust crates: nautilus_model (identifiers, instruments, types, enums)
When To Use
- Working with domain model types (instruments, identifiers, value types)
- Creating or configuring instruments
- Understanding identifier string formats
- Using
Price,Quantity,Money,Currencytypes - Defining
SyntheticInstrumentor custom tick schemes - Understanding enum types used across the system
When NOT To Use
- Custom data for signals → use
nt-signals(@customdataclass) - Order lifecycle → use
nt-trading - Data persistence → use
nt-data - Adapter-specific instrument loading → use
nt-adapters
Python Usage
Identifiers
from nautilus_trader.model.identifiers import InstrumentId, Venue, Symbol, TraderId, StrategyId
instrument_id = InstrumentId.from_str("ETHUSDT-PERP.BINANCE")
venue = Venue("BINANCE")
symbol = Symbol("ETHUSDT-PERP")
# Identifier components
instrument_id.venue # Venue("BINANCE")
instrument_id.symbol # Symbol("ETHUSDT-PERP")
Value Types
from nautilus_trader.model.objects import Price, Quantity, Money, Currency
# Price with precision
price = Price.from_str("1850.50")
price = Price(1850.50, precision=2)
# Quantity with precision
qty = Quantity.from_str("1.5")
qty = Quantity(1.5, precision=1)
# Money
balance = Money(10_000, Currency.from_str("USD"))
balance = Money.from_str("10000 USD")
# Arithmetic
total = price * qty # Returns float
Instruments
from nautilus_trader.model.instruments import CurrencyPair, Equity, CryptoPerpetual, FuturesContract
# Instruments are typically loaded from adapters or created for backtests
# Access via cache:
instrument = self.cache.instrument(instrument_id)
# Key properties:
instrument.id # InstrumentId
instrument.venue # Venue
instrument.base_currency # Currency (for pairs)
instrument.quote_currency # Currency
instrument.price_precision # int
instrument.size_precision # int
instrument.lot_size # Quantity
instrument.min_quantity # Quantity
instrument.max_quantity # Quantity
instrument.min_price # Price
instrument.max_price # Price
# Create quantity/price with correct precision:
qty = instrument.make_qty(1.5)
price = instrument.make_price(1850.50)
14 instrument types:
CurrencyPair— FX pairs (EUR/USD)Equity— stocksFuturesContract— dated futuresOptionContract— dated optionsCryptoPerpetual— perpetual swapsCryptoFuture— crypto dated futuresCryptoOption— crypto optionsCommodity— commoditiesIndex— indicesCFD— contracts for differenceBettingInstrument— betting marketsBinaryOption— binary optionsSyntheticInstrument— user-defined syntheticInstrument— base class
Enums
from nautilus_trader.model.enums import (
OrderSide, # BUY, SELL
OrderType, # MARKET, LIMIT, STOP_MARKET, STOP_LIMIT, etc.
TimeInForce, # GTC, IOC, FOK, GTD, DAY
PositionSide, # LONG, SHORT, FLAT
OmsType, # HEDGING, NETTING
AccountType, # CASH, MARGIN
OrderStatus, # INITIALIZED, SUBMITTED, ACCEPTED, FILLED, CANCELED, etc.
BarAggregation, # TICK, SECOND, MINUTE, HOUR, DAY, etc.
PriceType, # BID, ASK, MID, LAST
BookType, # L1_MBP, L2_MBP, L3_MBO
)
Currencies
from nautilus_trader.model.currencies import BTC, ETH, USD, USDT
# Or dynamically:
currency = Currency.from_str("USD")
Python Extension
SyntheticInstrument
from nautilus_trader.model.instruments import SyntheticInstrument
# Define a synthetic instrument from a formula combining other instruments
synthetic = SyntheticInstrument(
symbol=Symbol("SPREAD-1"),
price_precision=2,
components=[instrument_id_1, instrument_id_2],
formula="(component_0 - component_1)",
)
Custom Tick Schemes
from nautilus_trader.model.tick_scheme import TickScheme
# Define custom tick schemes for instruments with non-uniform tick sizes
Rust Usage
use nautilus_model::identifiers::{InstrumentId, Venue, Symbol};
use nautilus_model::instruments::CryptoPerpetual;
use nautilus_model::types::{Price, Quantity, Money};
use nautilus_model::enums::{OrderSide, OrderType};
Rust Extension
New Instrument Types
All 14 instrument types are defined in Rust (crates/model/src/instruments/) and exposed to Python via PyO3. New instruments follow the same pattern:
use pyo3::prelude::*;
use nautilus_model::identifiers::InstrumentId;
use nautilus_model::types::{Price, Quantity, Currency};
#[pyclass]
pub struct MyInstrument {
id: InstrumentId,
price_precision: u8,
size_precision: u8,
// Custom fields
}
#[pymethods]
impl MyInstrument {
#[new]
fn new(id: InstrumentId, price_precision: u8, size_precision: u8) -> Self { ... }
#[getter]
fn id(&self) -> InstrumentId { self.id }
fn make_price(&self, value: f64) -> Price {
Price::new(value, self.price_precision)
}
fn make_qty(&self, value: f64) -> Quantity {
Quantity::new(value, self.size_precision)
}
}
New Identifier Types
Identifiers are lightweight string wrappers with Copy semantics:
use pyo3::prelude::*;
use nautilus_model::identifier::Ustr; // Interned string type
#[pyclass]
#[derive(Clone, Copy, Debug, Hash, PartialEq, Eq)]
pub struct MyIdentifier {
value: Ustr, // Interned for O(1) equality checks
}
#[pymethods]
impl MyIdentifier {
#[new]
fn new(value: &str) -> Self {
Self { value: Ustr::from(value) }
}
fn __repr__(&self) -> String { format!("MyIdentifier('{}')", self.value) }
fn __hash__(&self) -> u64 { ... }
}
Value Types in Rust
Value types (Price, Quantity, Money) use fixed-point representation internally:
- Standard mode:
i64backing with precision 0-9 - High-precision mode:
i128backing (enablehigh-precisionfeature flag) - Construction:
Price::new(value, precision)orPrice::from_raw(raw_value, precision) - Cross-FFI: use
from_rawto preserve exact precision when passing between Rust and Python
PyO3 Binding Conventions
- Use
#[pyclass]and#[pymethods]for Python-visible types - Register in
crates/pyo3/src/lib.rs - Identifier types: implement
Hash,PartialEq,Eq,Copy - Value types: use
Copysemantics, implementDisplayfor__repr__ - Wrap FFI functions in
abort_on_panic(|| { ... }) - Use
Ustr(interned strings) for identifiers — O(1) equality and hashing
Key Conventions
Identifier String Formats
InstrumentId:"{symbol}.{venue}"(e.g.,"ETHUSDT-PERP.BINANCE")Venue: uppercase alphanumeric (e.g.,"BINANCE","SIM")Symbol: venue-specific format (e.g.,"ETHUSDT-PERP","EUR/USD")TraderId:"{name}-{tag}"(e.g.,"TRADER-001")StrategyId:"{name}-{tag}"(e.g.,"EMACross-001")
Instrument Creation Patterns
- Live: Instruments loaded automatically by adapter's
InstrumentProvider - Backtest: Created via
TestInstrumentProvideror loaded from catalog - Always use
instrument.make_qty()andinstrument.make_price()for correct precision
Value Type Precision
PriceandQuantitycarry precision metadata- Always construct with correct precision for the instrument
- Use
instrument.make_qty(value)/instrument.make_price(value)helpers - High-precision mode available for sub-tick precision needs
Rust ↔ Python Conversion
Value types convert automatically between Rust and Python via PyO3:
- Rust
Price↔ PythonPrice(transparent) - Rust
Quantity↔ PythonQuantity(transparent) - String identifiers convert via
from_str()/to_string()
References
references/concepts/— instruments, value types, overviewreferences/api/model/— identifiers, instruments, orders, position, events, objects, data, book, tick_scheme, index
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |