Mark Price Updates for Derivatives Margining and PnL
Summary
This reference explains a mark price update as a data record for an instrument’s current mark price. The record includes an instrument identifier, price value, event timestamp, and initialization timestamp. It distinguishes mark prices from trade observations by describing their use as venue reference prices for margin calculations, liquidation checks, and unrealized profit and loss. The documentation also says received updates are cached by instrument and stored in a catalog with instrument and price precision metadata.
For backtesting, the stated use is to provide mark prices separately from trades so that simulated margin and PnL calculations can follow venues that publish a reference price stream. The example demonstrates the record’s construction in two programming languages, but it is illustrative rather than an empirical test. The page does not specify how any venue calculates its mark price, how frequently updates arrive, or how to handle missing or stale values. Those implementation details matter when reproducing venue behavior.
Key ideas
- A mark price update associates a reference price and two timestamps with an instrument.
- Derivatives venues commonly use mark prices in margining, liquidation checks, and unrealized PnL calculations.
- Backtests can ingest mark prices separately from trades to model venue reference-price behavior.
- The record is cached by instrument and stored with price precision metadata.
- The documentation does not explain venue-specific mark price formulas or stale-data handling.
Tags
Full text
# MarkPriceUpdate
# MarkPriceUpdate
`MarkPriceUpdate` represents an instrument's mark price. Derivatives venues commonly use mark
prices for margining, liquidation checks, and unrealized PnL calculations.
## Fields
| Field | Rust type | Python type | Required/default | Notes |
| --------------- | -------------- | -------------- | ---------------- | ---------------------------------------- |
| `instrument_id` | `InstrumentId` | `InstrumentId` | Required | Instrument for the mark price. |
| `value` | `Price` | `Price` | Required | Current mark price. |
| `ts_event` | `UnixNanos` | `int` | Required | Event timestamp in nanoseconds. |
| `ts_init` | `UnixNanos` | `int` | Required | Initialization timestamp in nanoseconds. |
## Behavior
- Mark prices are cached by instrument when received.
- Backtests can feed mark prices to align margin and PnL behavior with venues that
publish reference prices separately from trades.
- The catalog stores mark prices with instrument ID and price precision metadata.
## Example
```rust tab="Rust"
use nautilus_core::UnixNanos;
use nautilus_model::{
data::MarkPriceUpdate,
identifiers::InstrumentId,
types::Price,
};
let mark = MarkPriceUpdate::new(
InstrumentId::from("BTCUSDT-PERP.BINANCE"),
Price::from("65000.10"),
UnixNanos::from(1_000_000_000),
UnixNanos::from(1_000_000_100),
);
```
```python tab="Python"
from nautilus_trader.model import InstrumentId
from nautilus_trader.model import MarkPriceUpdate
from nautilus_trader.model import Price
mark = MarkPriceUpdate(
instrument_id=InstrumentId.from_str("BTCUSDT-PERP.BINANCE"),
value=Price.from_str("65000.10"),
ts_event=1_000_000_000,
ts_init=1_000_000_100,
)
```
## Related guides
- [IndexPriceUpdate](index_price_update.md) covers the index reference price.
- [FundingRateUpdate](funding_rate_update.md) covers perpetual funding metadata.
- [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.