Equity Instrument Fields, Trading Constraints, and Whole-Share Quantities
Article NautilusTrader
Summary
This reference explains how the Nautilus trading framework models a listed share or ETF as an equity instrument. It describes required identifiers, venue symbol, quote currency, price precision and increment, timestamps, and optional metadata such as lot size, price and quantity limits, margin rates, and tick scheme. It also distinguishes instrument properties from contract types that have expiries or derivative-specific terms.
A key operational constraint is that equity quantity precision is fixed at zero, so orders must use whole-share quantities; the risk engine rejects fractional quantities. The documentation gives Rust and Python construction examples and points to representative data and broker adapters. The example includes a board lot, but lot-size conventions and published price limits depend on the venue. This is an instrument-model reference, not a trading strategy, and it provides no performance or market analysis.
Key ideas
- An equity instrument represents a listed cash-market security without a contract expiry.
- Price precision and increment describe valid price quoting steps.
- Equity order quantities have zero decimal precision, so fractional-share orders are rejected.
- Lot size, price bounds, margin settings, and tick schemes are optional instrument attributes.
- Price limits should be set only when the venue publishes them.
Tags
Full text
# Equity
# Equity
`Equity` represents a listed share, ETF, or similar cash-market security. Nautilus uses
this type for instruments that trade in whole units, quote in one currency, and have no
contract expiry.
Examples include `AAPL.XNAS`, `MSFT.XNAS`, and venue-specific ETF symbols.
## 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 | Quote and settlement currency. |
| `price_precision` | `u8` | `int` | Required | Decimal places allowed for prices. |
| `price_increment` | `Price` | `Price` | Required | Smallest valid price step. |
| `lot_size` | `Option<Quantity>` | `Quantity \| None` | `None` | Board lot or whole-share lot size. |
| `ts_event` | `UnixNanos` | `int` | Required | Event timestamp in nanoseconds. |
| `ts_init` | `UnixNanos` | `int` | Required | Initialization timestamp in nanoseconds. |
| `isin` | `Option<Ustr>` | `str \| None` | `None` | International Securities ID when known. |
| `max_quantity` | `Option<Quantity>` | `Quantity \| None` | `None` | Maximum order quantity. |
| `min_quantity` | `Option<Quantity>` | `Quantity \| None` | `None` | 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. |
| `margin_init` | `Option<Decimal>` | `Decimal \| None` | `0` | Initial margin rate. |
| `margin_maint` | `Option<Decimal>` | `Decimal \| None` | `0` | Maintenance margin rate. |
| `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
- `Equity` has asset class `Equity` and instrument class `Spot`.
- Quantity precision is always zero, so orders use whole-share quantities.
- The multiplier and size increment are one.
- It has no base currency, expiry, strike, option kind, or inverse costing flag.
- Use price limits only when the venue publishes them.
:::warning
`Equity` fixes size precision at zero. The `RiskEngine` denies any order whose quantity
precision exceeds the instrument size precision, so fractional-share quantities are rejected.
:::
## Example
```rust tab="Rust"
use nautilus_core::UnixNanos;
use nautilus_model::{
identifiers::{InstrumentId, Symbol},
instruments::Equity,
types::{Currency, Price, Quantity},
};
use ustr::Ustr;
let aapl = Equity::builder()
.instrument_id(InstrumentId::from("AAPL.XNAS"))
.raw_symbol(Symbol::from("AAPL"))
.isin(Ustr::from("US0378331005"))
.currency(Currency::from("USD"))
.price_precision(2)
.price_increment(Price::from("0.01"))
.lot_size(Quantity::from("100"))
.ts_event(UnixNanos::default())
.ts_init(UnixNanos::default())
.build()
.unwrap();
```
```python tab="Python"
from nautilus_trader.model import Currency
from nautilus_trader.model import Equity
from nautilus_trader.model import InstrumentId
from nautilus_trader.model import Price
from nautilus_trader.model import Quantity
from nautilus_trader.model import Symbol
aapl = Equity(
instrument_id=InstrumentId.from_str("AAPL.XNAS"),
raw_symbol=Symbol("AAPL"),
currency=Currency.from_str("USD"),
price_precision=2,
price_increment=Price.from_str("0.01"),
ts_event=0,
ts_init=0,
isin="US0378331005",
lot_size=Quantity.from_int(100),
)
```
## Adapters
Representative adapters that create or consume `Equity` instruments include:
- [Databento](../../integrations/databento.md) for listed US equities and ETFs.
- [Interactive Brokers](../../integrations/interactive_brokers.md) for listed equity contracts.
## Related guides
- [Data](../data/) explains market data that references instruments.
- [Value types](../value_types.md) explains `Price`, `Quantity`, and `Money`.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.