NautilusTrader
Concepts

Nightly docs

These docs track unreleased changes and may change without notice. Their code examples can use APIs that the latest release lacks, so run them with a development wheel or switch to the latest release docs.

Cache

The Cache is the central in-memory store for trading state and recent market data. Actors and strategies use it to read data maintained by the data and execution engines or to share raw bytes under application-defined keys.

The cache:

  • Stores current order books and bounded histories of quotes, trades, bars, and other market data.
  • Tracks orders, positions, accounts, instruments, and currencies until they are purged or reset.
  • Shares caller-serialized data between components and persists it when a backing database is configured.

How caching works

The engines add built-in and custom data to the Cache as events flow through the system. Live adapters feed events to the engine asynchronously, so the cache changes when the engine processes an event, not when the adapter first receives it.

For quotes, trades, bars, and custom data, the DataEngine attempts to write to the Cache before publishing to subscribers. After a successful write, the latest value is available by the time the strategy handler runs. Order book deltas and depth snapshots are published directly. BookUpdater subscriptions maintain current book state separately:

For the full step-by-step trace, see Data flow: life of a quote tick.

Basic example

Within a strategy, access the shared Cache through self.cache:

def on_bar(self, bar: Bar) -> None:

    # Read recent bars; index 0 is the same bar after a successful cache write
    last_bar = self.cache.bar(self.bar_type, index=0)
    previous_bar = self.cache.bar(self.bar_type, index=1)
    third_last_bar = self.cache.bar(self.bar_type, index=2)

    # Read current position state
    if self.last_position_opened_id is not None:
        position = self.cache.position(self.last_position_opened_id)
        if position is not None and position.is_open:
            open_quantity = position.quantity

    # Read open orders for the instrument
    open_orders = self.cache.orders_open(instrument_id=self.instrument_id)

Configuration

Use the CacheConfig class to configure the Cache behavior and capacity. Pass it to a BacktestEngine or LiveNode, depending on the environment context.

The same capacity settings apply in both environments:

from nautilus_trader.config import BacktestEngineConfig
from nautilus_trader.config import CacheConfig
from nautilus_trader.config import LiveNodeConfig

# For backtesting
engine_config = BacktestEngineConfig(
    cache=CacheConfig(
        # Retain up to 10,000 entries per instrument history or custom data topic
        data_capacity=10_000,
        # Store last 5,000 bars per bar type
        bar_capacity=5_000,
    ),
)

# For live trading
node_config = LiveNodeConfig(
    cache=CacheConfig(
        data_capacity=10_000,
        bar_capacity=5_000,
    ),
)

By default, data_capacity retains up to 10,000 values per instrument history or custom data topic. bar_capacity retains up to 10,000 bars per bar type. These are separate limits, not combined totals. Custom histories reserve space for the full data_capacity on first insertion, even if they remain short. Memory use grows with the capacity and number of distinct topics. Custom and built-in histories share this setting. Set each capacity to a value in [1, 1_000_000]. Increase them when a strategy needs a longer in-memory lookback and the additional memory use is acceptable.

Configuration options

The CacheConfig type supports these parameters:

use nautilus_common::{cache::CacheConfig, enums::SerializationEncoding};

let config = CacheConfig {
    encoding: SerializationEncoding::MsgPack,
    timestamps_as_iso8601: false,
    buffer_interval_ms: None,
    bulk_read_batch_size: None,
    use_trader_prefix: true,
    use_instance_id: false,
    flush_on_start: false,
    drop_instruments_on_reset: true,
    data_capacity: 10_000,
    bar_capacity: 10_000,
    persist_account_events: true,
    save_market_data: false,
};

Each bar type maintains its own capacity. For example, if you use both 1-minute and 5-minute bars, each stores up to bar_capacity bars. When bar_capacity is reached, the Cache automatically removes the oldest data.

Database configuration

CacheConfig controls cache behavior. Set connection details in RedisCacheConfig or PostgresCacheConfig.

Native backends implement CacheDatabaseFactory and CacheDatabaseAdapter and own their concrete connection settings. Python passes a concrete backend config or registered native factory to LiveNodeBuilder.with_cache_database_factory.

Custom backend factories must be integrated into NautilusTrader's native extension and use unique Python class names. Python does not expose a factory registration API for separately installed packages.

Persistence failure policy

Cache operations complete valid in-memory changes independently of optional database persistence. Persistence failures are logged at ERROR without failing the cache operation or interrupting event publication or command dispatch. This policy applies to all cache writes, including indexes, snapshots, component state, heartbeats, and purge deletions.

The cache still propagates:

  • Validation and in-memory operation errors.
  • DeFi currency integrity errors reported by the backing database.
  • Read, restoration, and explicit database flush errors returned by the backing.

For queued backings, persistence attempts can fail at writer-channel admission or later in the database worker. Both failures are logged. Cache success confirms the cache operation, not queue admission or durable storage. Restored state can therefore differ from the running cache.

:::note Shut down on persistence errors To request a normal shutdown when a persistence error is logged, set shutdown_on_error=True in LiveNodeConfig or BacktestEngineConfig. This setting responds to Rust error logs emitted after the runtime starts, including persistence errors. Shutdown takes effect when the runtime next checks the request; it does not abort the process or roll back the current operation. Error-triggered shutdown handling is disabled before final component-state saves. Those saves still follow the best-effort persistence policy, so their persistence failures are logged without failing finalization. :::

Recovery

  • Startup restores supported, successfully persisted general data, currencies, instruments, instrument closes, synthetics, accounts, orders, and positions. Postgres also restores Greeks and yield curves.
  • Loading replaces Greeks and yield curves already in memory; Redis loads empty maps.
  • Instrument closes persist whenever a backing is configured, regardless of save_market_data: they are recovery snapshots rather than bounded history.
  • Startup does not restore bounded market-data histories or the running process.
  • A backing does not provide a complete event archive or synchronize nodes. Each node owns its in-memory cache, even when nodes share a database namespace.
  • With the defi feature, Redis and Postgres restore full token currency definitions before dependent instruments. Instrument writes wait for persistent conflict checks, including legacy updates. Integrity conflicts fail recovery. See token currency recovery for legacy-data and instrument-replacement rules.

An event-store snapshot anchor records a reference and hash, not the snapshot blob. Recording an anchor does not confirm blob persistence, and recovery fails if the referenced blob is unavailable. Durable blob-before-anchor ordering requires a separate persistence acknowledgment; cache success cannot establish it. See Snapshot-anchored recovery.

Explicit database operations

  • cache.load_instrument(instrument_id) and cache.load_synthetic(instrument_id) check memory first, then load from the backing and cache successful results. Fill handling also uses this instrument fallback when processing order fills and orderless spread legs. Failed or missing reads leave memory unchanged.
  • cache.delete_actor(actor_id) and cache.delete_strategy(strategy_id) attempt to delete saved component state without unregistering components.
  • cache.heartbeat(timestamp) attempts to persist a caller-supplied timestamp in UNIX nanoseconds.

Deletions and heartbeats follow the persistence failure policy.

Postgres

  • With save_market_data = true, Postgres queues GreeksData per instrument and YieldCurve per name. Later writes replace earlier values, regardless of timestamp.
  • Cache validation rejects invalid yield curves. Postgres rejects non-finite Greeks for persistence; the cache logs the error and retains the Greeks in memory. Queueing failures also follow the persistence failure policy; the adapter logs later database write failures.
  • Order-book and funding-rate persistence are unsupported. With save_market_data = true, order-book and bulk funding-rate additions log an ERROR and update memory only.
  • Orders, positions, their snapshots, and accounts belong to a trader. Two traders can reuse client order or position IDs.
  • Flushes, including flush_on_start, delete only the trader's rows. Currencies, instruments, instrument closes, synthetics, market data (including Greeks and yield curves), and user general data stay shared. The trader's saved actor and strategy state and heartbeat are also deleted.
  • Actor and strategy state persistence supports load_state and save_state.
  • The cache-database: key prefix is reserved for backing data. User entries with this prefix do not restore.

Run nautilus database init to create the greeks and yield_curve tables before connecting, even with save_market_data = false.

Account events saved before trader scoping have no trader, and ownership cannot be inferred. Connecting fails for every node using that database until each affected account is assigned. The error lists the accounts. After initialization, assign each one:

nautilus database assign-account --account-id <ACCOUNT_ID> --trader-id <TRADER_ID>

Redis

  • Does not persist quotes, trades, bars, order books, funding rates, Greeks, or yield curves.
  • With save_market_data = true, each unsupported persistence attempt logs an ERROR and updates memory only. For funding rates, only bulk additions attempt persistence; single additions stay in memory.
  • Direct load_greeks and load_yield_curves calls return errors; load_all returns empty maps for them.
  • Disable save_market_data with Redis to avoid unsupported writes. Postgres supports quotes, trades, bars, Greeks, and yield curves; neither built-in backing persists order books or funding rates.

Connect a backing

Rust callers use CacheDatabaseFactory to construct an adapter:

use nautilus_common::{
    cache::{CacheConfig, database::CacheDatabaseFactory},
    enums::SerializationEncoding,
};
use nautilus_infrastructure::redis::cache::RedisCacheConfig;

let config = CacheConfig {
    encoding: SerializationEncoding::MsgPack,
    timestamps_as_iso8601: true,
    buffer_interval_ms: Some(100),
    ..Default::default()
};

let database = RedisCacheConfig {
    host: Some("localhost".to_string()),
    port: Some(6379),
    connection_timeout: 2,
    response_timeout: 2,
    ..Default::default()
};

let cache_database = database
    .create(trader_id, instance_id, config.clone())
    .await?;

Attach it to the node before startup:

let node_config = LiveNodeConfig {
    trader_id,
    ..Default::default()
};
let mut node = LiveNode::build("LiveNode".to_string(), Some(node_config))?;
node.set_cache_database(cache_database)?;
node.run().await?;

Python passes the config to LiveNodeBuilder.with_cache_database_factory. The node creates and owns the adapter when it starts:

from nautilus_trader.common import Environment
from nautilus_trader.infrastructure import RedisCacheConfig
from nautilus_trader.live import LiveNode
from nautilus_trader.model import TraderId

node = (
    LiveNode.builder("LiveNode", TraderId("TRADER-001"), Environment.LIVE)
    .with_cache_database_factory(RedisCacheConfig(host="localhost", port=6379))
    .build()
)

try:
    node.run()
finally:
    node.dispose()

Use PostgresCacheConfig for Postgres. Both configs come from nautilus_trader.infrastructure.

Python configures persistence through LiveNodeBuilder.with_cache_database_factory. Concrete cache database objects and their connection, read, and write methods are not exposed to Python. Use the runtime Cache API from actors and strategies to access cached data.

Missing PostgresCacheConfig fields resolve from Postgres environment variables and then built-in defaults. Explicit config fields take precedence over both.

Rust callers pass PostgresCacheConfig and TraderId to PostgresCacheDatabase::connect. Direct connections and the factory use the same native configuration path.

Startup and shutdown

  • LiveExecutionEngineConfig.load_cache = true (default) restores persisted state and rebuilds indexes before connecting clients or reconciling execution state.
  • CacheConfig.flush_on_start = true clears the backing instead. Postgres clears only the node's trader rows.

Always call dispose() after run(). It closes the backing and flushes buffered writes; returning from run() alone can drop them when CacheConfig.buffer_interval_ms is set.

Using the cache

Accessing market data

The Cache provides access to order books, quotes, trades, bars, and other market data. Cached market-data histories use reverse indexing: index 0 is the latest entry, and index 1 is the previous entry. The list accessors use the same order as the single-entry accessors.

Data typeHistoryLatest entry
Quotesquotes(instrument_id)quote(instrument_id)
Tradestrades(instrument_id)trade(instrument_id)
Barsbars(bar_type)bar(bar_type)
Mark pricesmark_prices(instrument_id)mark_price(instrument_id)
Index pricesindex_prices(instrument_id)index_price(instrument_id)
Funding ratesfunding_rates(instrument_id)funding_rate(instrument_id)
Instrument statusesinstrument_statuses(instrument_id)instrument_status(instrument_id)
Custom datacustom_data_history(data_type)custom_data(data_type)
  • Ordering: Bars use descending ts_event. Other histories use reverse insertion order, even for older timestamps; they are not sorted by ts_event or ts_init.
  • History lists: Built-in histories return a list, or None when the key has no entries. Custom histories return an empty list when absent. [-1] selects the oldest retained bar or the least recently inserted entry in other histories.
  • Single entries: quote(), trade(), bar(), mark_price(), index_price(), and funding_rate() accept index; custom data uses custom_data_at_index(). They return None for a missing entry at a valid non-negative index. Negative indices or values beyond the platform's unsigned index limit raise OverflowError; negative indexing works on returned Python lists.
  • Capacity: bar_capacity limits each bar type; data_capacity limits each other history per instrument and each custom history per data type topic. A new insertion at capacity removes the last entry.

Order book

The cache holds the current order book state for each instrument, rather than a history of book updates. Instrument closes also keep one value per instrument: instrument_close(instrument_id) returns the last inserted close, or None if absent.

# Get the current order book. Returns OrderBook or None
book = self.cache.order_book(instrument_id)

# Check whether an order book exists
has_book = self.cache.has_order_book(instrument_id)

# Get the number of applied book updates
update_count = self.cache.book_update_count(instrument_id)

Quote ticks

# Get quotes. Returns list[QuoteTick] or None
quotes = self.cache.quotes(instrument_id)

# Returns QuoteTick or None
latest_quote = self.cache.quote(instrument_id)

# Returns QuoteTick or None
second_last_quote = self.cache.quote(instrument_id, index=1)

# Check quote availability
quote_count = self.cache.quote_count(instrument_id)
has_quotes = self.cache.has_quote_ticks(instrument_id)

Trade ticks

# Get trades. Returns list[TradeTick] or None
trades = self.cache.trades(instrument_id)

# Returns TradeTick or None
latest_trade = self.cache.trade(instrument_id)

# Returns TradeTick or None
second_last_trade = self.cache.trade(instrument_id, index=1)

# Check trade availability
trade_count = self.cache.trade_count(instrument_id)
has_trades = self.cache.has_trade_ticks(instrument_id)

Quotes and trades accumulate all ticks, including those sharing a timestamp.

Bar access

# Get all cached bars for a bar type. Returns list[Bar] or None
bars = self.cache.bars(bar_type)

# Get the most recent bar. Returns Bar or None
latest_bar = self.cache.bar(bar_type)

# Get a historical bar by index (0 = most recent). Returns Bar or None
second_last_bar = self.cache.bar(bar_type, index=1)

# Check whether bars exist and get the count
bar_count = self.cache.bar_count(bar_type)
has_bars = self.cache.has_bars(bar_type)

To process bars from oldest to newest, reverse the returned list:

bars_chronological = list(reversed(self.cache.bars(bar_type) or []))

Bars newer than the cached latest are added; older bars are skipped but still delivered in the response.

  • Time bars: a bar with the same ts_event replaces the cached one (the later data wins), so duplicates from overlapping historical requests do not accumulate.
  • Non-time bars: Renko bricks or volume bars emitted from a single update can legitimately share a ts_event. All bars at the same timestamp are kept, including any re-delivered by an overlapping request.
  • Internal request aggregation: the cache inserts request-generated bars at their ordered position instead of skipping them. The cache is their only delivery path.

Price access

from nautilus_trader.model import PriceType

# Get the current price by type. Returns Price or None
price = self.cache.price(
    instrument_id=instrument_id,
    # Options: BID, ASK, MID, LAST, MARK
    price_type=PriceType.MID,
)

Bar types

from nautilus_trader.model import AggregationSource, PriceType

# Get all available bar types for an instrument. Returns list[BarType]
bar_types = self.cache.bar_types(
    instrument_id=instrument_id,
    # Options: BID, ASK, MID, LAST, MARK
    price_type=PriceType.LAST,
    aggregation_source=AggregationSource.EXTERNAL,
)

Simple example

from nautilus_trader.model import Bar, BarType
from nautilus_trader.trading import Strategy


class MarketDataStrategy(Strategy):
    def on_start(self) -> None:

        # Subscribe to 1-minute bars
        self.bar_type = BarType.from_str(f"{self.instrument_id}-1-MINUTE-LAST-EXTERNAL")
        self.subscribe_bars(self.bar_type)

    def on_bar(self, bar: Bar) -> None:
        bars = (self.cache.bars(self.bar_type) or [])[:3]
        if len(bars) < 3:
            return

        # Access the latest three bars for analysis
        current_bar = bars[0]
        prev_bar = bars[1]
        prev_prev_bar = bars[2]

        # Read the latest quote and trade
        latest_quote = self.cache.quote(self.instrument_id)
        latest_trade = self.cache.trade(self.instrument_id)

        if latest_quote is not None:
            current_spread = latest_quote.ask_price - latest_quote.bid_price
            self.log.info(f"Current spread: {current_spread}")

Trading objects

Orders

Query orders by venue, strategy, instrument, account, or order side.

Basic order access:

# Get a specific order by its client order ID
order = self.cache.order(ClientOrderId("O-123"))

# Get all orders in the system
orders = self.cache.orders()

# All orders for a specific venue
orders_for_venue = self.cache.orders(venue=venue)

# All orders for a specific strategy
orders_for_strategy = self.cache.orders(strategy_id=strategy_id)

# All orders for an instrument
orders_for_instrument = self.cache.orders(instrument_id=instrument_id)

Order state queries:

# Orders currently active at the venue
open_orders = self.cache.orders_open()

# Orders that have completed their lifecycle
closed_orders = self.cache.orders_closed()

# Orders being simulated locally by the system
emulated_orders = self.cache.orders_emulated()

# Orders submitted (or modified) to venue, but not yet confirmed
inflight_orders = self.cache.orders_inflight()

# Orders still managed locally (initialized, emulated, or released)
local_active_orders = [order for order in self.cache.orders() if order.is_active_local]

# Checks if an order with the given ID exists in the cache
exists = self.cache.order_exists(client_order_id)

# Checks if an order is currently open
is_open = self.cache.is_order_open(client_order_id)

# Checks if an order is closed
is_closed = self.cache.is_order_closed(client_order_id)

# Checks if an order is being simulated locally
is_emulated = self.cache.is_order_emulated(client_order_id)

# Checks if an order is submitted or modified, but not yet confirmed
is_inflight = self.cache.is_order_inflight(client_order_id)

# Checks if an order is still managed locally
order = self.cache.order(client_order_id)
is_active_local = order is not None and order.is_active_local

Order statistics:

# Number of open orders
open_count = self.cache.orders_open_count()

# Number of closed orders
closed_count = self.cache.orders_closed_count()

# Number of emulated orders
emulated_count = self.cache.orders_emulated_count()

# Number of inflight orders
inflight_count = self.cache.orders_inflight_count()

# Number of locally active orders (initialized, emulated, or released)
local_active_count = sum(order.is_active_local for order in self.cache.orders())

# Total number of orders in the system
total_count = self.cache.orders_total_count()

# Number of currently open BUY orders
buy_orders_count = self.cache.orders_open_count(side=OrderSide.BUY)

# Total number of orders for a given venue
venue_orders_count = self.cache.orders_total_count(venue=venue)

Positions

The Cache keeps positions until they are purged or reset and provides several ways to query them.

Position access:

# Get a specific position by its ID
position = self.cache.position(PositionId("P-123"))

# All positions in the system
all_positions = self.cache.positions()

# All currently open positions
open_positions = self.cache.positions_open()

# All closed positions
closed_positions = self.cache.positions_closed()

# Positions for a specific venue
venue_positions = self.cache.positions(venue=venue)

# Positions for a specific instrument
instrument_positions = self.cache.positions(instrument_id=instrument_id)

# Positions for a specific strategy
strategy_positions = self.cache.positions(strategy_id=strategy_id)

# All long positions
long_positions = self.cache.positions(side=PositionSide.LONG)

Position state queries:

# Checks if a position with the given ID exists
exists = self.cache.position_exists(position_id)

# Checks if a position is open
is_open = self.cache.is_position_open(position_id)

# Checks if a position is closed
is_closed = self.cache.is_position_closed(position_id)

# All orders related to a specific position
orders = self.cache.orders_for_position(position_id)

# Find the position associated with a specific order
position = self.cache.position_for_order(client_order_id)

Position statistics:

# Number of currently open positions
open_count = self.cache.positions_open_count()

# Number of closed positions
closed_count = self.cache.positions_closed_count()

# Total number of positions in the system
total_count = self.cache.positions_total_count()

# Number of open long positions
long_positions_count = self.cache.positions_open_count(side=PositionSide.LONG)

# Number of positions for a given instrument
instrument_positions_count = self.cache.positions_total_count(instrument_id=instrument_id)

Accounts

# Retrieve account by ID
account = self.cache.account(account_id)

# Retrieve account for a specific venue
account = self.cache.account_for_venue(venue)

# Retrieve account ID for a venue
account_id = self.cache.account_id(venue)

A venue lookup resolves only when exactly one account is issued under the venue (the account ID prefix, such as BINANCE in BINANCE-001). When several accounts share a venue, account_for_venue and account_id return None. Get those accounts by ID.

Instruments

# Retrieve a specific instrument by its ID
instrument = self.cache.instrument(instrument_id)

# Retrieve all instruments in the cache
all_instruments = self.cache.instruments()

# Instruments for a specific venue
venue_instruments = self.cache.instruments(venue=venue)

# Get all instrument IDs
instrument_ids = self.cache.instrument_ids()

# Get instrument IDs for a specific venue
venue_instrument_ids = self.cache.instrument_ids(venue=venue)

Purging cached data

Long-running sessions accumulate closed orders, closed positions, account events, and unused instruments. The cache exposes targeted and bulk purge methods so strategies and the live trading engine can keep memory bounded without restarting the system.

Purges change memory only by default. Pass purge_from_database=True to order and position purge methods in Python to queue deletion of their persisted histories and routine snapshots. Rust callers pass the boolean explicitly. Persistence failures follow the persistence failure policy, so a successful return does not confirm queue admission or database deletion. Encoded position snapshots used to replay corrections remain persisted as general data. Instrument purges change memory only.

Targeted purges

Use these to drop a single entity. Order and position guards use in-memory state; direct purges can also target IDs absent from memory.

  • cache.purge_order(client_order_id): removes the order and each order-keyed index entry. Skips open orders.
  • cache.purge_position(position_id): removes the position, its snapshots, and position-keyed index entries. Skips open positions.
  • cache.purge_instrument(instrument_id): removes the instrument and its transient per-instrument maps (order book, quotes, trades, mark/index/funding prices, instrument status and close, greeks, and bars referencing the instrument), plus custom histories whose DataType.identifier equals the instrument ID. Skips while any associated order is non-terminal (anything that has not reached a closed state, including initialized, submitted, accepted, emulated, released, and inflight orders) or any associated position is non-closed. Cached orders and positions remain indexed until purged separately, preserving historical queries and realized PnL.

purge_instrument is intended for actors and strategies with their own lifecycle logic for deciding when an instrument is no longer needed. Purging an instrument that another component still relies on causes missing instrument lookups and loses market-data history. Active subscriptions belong to the data engine, so unsubscribe before purging if you no longer want updates.

Bulk purges

Use these to sweep older entries by age. They take the current timestamp and a buffer or lookback window in seconds.

  • cache.purge_closed_orders(ts_now, buffer_secs): closed orders whose close timestamp is older than buffer_secs.
  • cache.purge_closed_positions(ts_now, buffer_secs): closed positions whose close timestamp is older than buffer_secs.
  • cache.purge_account_events(ts_now, lookback_secs): account state events older than lookback_secs. The latest event always remains, including when the lookback is 0. With purge_from_database=True, Redis and Postgres log deletion requests and retain the full account history for incremental balance, margin, and starting-balance replay.

Keep the closed source position of a virtual HEDGING flip while its order can still receive fills. Purging it removes the history needed to route later fills and can cause the engine to reject them.

Automatic purging in live trading

LiveExecutionEngineConfig schedules the bulk purges on a timer. All purge intervals default to None, which disables the corresponding loop. Set an interval to enable a loop and set its buffer or lookback to control how recent entries stay protected. Set purge_from_database=True to also delete persisted closed orders and positions. Redis and Postgres retain persisted account-event history. This example uses the recommended starting values from the live-trading configuration guide and keeps purges in memory:

from nautilus_trader.config import LiveExecutionEngineConfig

exec_engine = LiveExecutionEngineConfig(
    purge_closed_orders_interval_mins=15,
    purge_closed_orders_buffer_mins=60,
    purge_closed_positions_interval_mins=15,
    purge_closed_positions_buffer_mins=60,
    purge_account_events_interval_mins=15,
    purge_account_events_lookback_mins=60,
)

A shorter interval runs a purge more often, while a shorter buffer or lookback removes newer data. Choose each value separately based on memory limits and the recent execution context needed for reconciliation or analysis. See Configure live trading: memory management for the full parameter reference.

The instrument purge has no automatic loop because the right time to drop an instrument depends on strategy state, not age. Call cache.purge_instrument from the actor or strategy that owns the instrument's lifecycle.

Custom data

Event histories

Each DataType topic, including its metadata and optional identifier, has an independent history. Use the payload's data_type for reads. A subscription without an identifier can receive identified payloads, whose histories remain separate from the subscription's data type.

Automatic retention applies to custom events processed by the data engine. Actor-published custom data and signals, and custom-data request responses, do not populate these histories automatically. Call self.cache.add_custom_data(data) explicitly when retaining one of those events.

def on_data(self, data: CustomData) -> None:
    latest = self.cache.custom_data(data.data_type)
    previous = self.cache.custom_data_at_index(data.data_type, 1)
    history = self.cache.custom_data_history(data.data_type)
  • Persistence: Custom histories stay in memory, including when save_market_data is enabled; database startup does not restore them.
  • Pipeline: Processing honors DataEngineConfig.disable_historical_cache. Direct, non-pipeline processing, including backtests, caches custom data regardless of that setting.
  • Reset: A cache reset clears all custom histories.

Basic storage and retrieval

The Cache stores raw bytes under application-defined string keys. Serialize values before adding them and deserialize them after retrieval. Actors and strategies can use these entries to share small amounts of application data.

# Store serialized data
self.cache.add(key="my_key", value=b"some binary data")

# Retrieve serialized data. Returns bytes or None
stored_data = self.cache.get("my_key")

The Cache is not a general database. Use a dedicated store for large datasets or complex queries.

Best practices and common questions

Cache vs. portfolio usage

Cache:

  • Keeps execution objects, selected object histories, and bounded recent market data until purge or reset.
  • Applies local state changes immediately, such as initializing an order before submission.
  • Applies external events when the engine processes them, such as when an order fills.

Portfolio:

  • Aggregates position, exposure, and account information.
  • Computes current portfolio values from cached state and market prices.
from nautilus_trader.model import PositionChanged
from nautilus_trader.trading import Strategy


class MyStrategy(Strategy):
    def on_position_changed(self, event: PositionChanged) -> None:

        # Read the fills retained by the cached position
        position = self.cache.position(event.position_id)
        fills = position.events() if position is not None else []

        # Read current aggregate exposure from the portfolio
        current_exposure = self.portfolio.net_exposure(event.instrument_id)

Cache vs. strategy variables

Use cache entries for shared, serialized data and strategy variables for local working state.

Cache storage:

  • Available to actors and strategies that share the system cache.
  • Can persist general byte entries when a backing database is configured and writes complete.
  • Stays available when an individual strategy resets, but a cache or execution-engine reset clears the in-memory entries.

Strategy variables:

  • Keep typed, strategy-specific calculations and intermediate values encapsulated.
  • Do not expose values to other components or persist them automatically.

Actor and strategy state persistence across process restarts uses separate on_save and on_load hooks with a supported backing. See the cache database configuration section of the live-trading guide.

Serialize shared data before adding it to the cache:

import json

from nautilus_trader.trading import Strategy


class MyStrategy(Strategy):
    def on_start(self) -> None:
        shared_data = {
            "last_reset": self.clock.timestamp_ns(),
            "trading_enabled": True,
        }
        self.cache.add("shared_strategy_info", json.dumps(shared_data).encode())

Another strategy can retrieve the cached data as follows:

import json

from nautilus_trader.trading import Strategy


class AnotherStrategy(Strategy):
    def on_start(self) -> None:
        data_bytes = self.cache.get("shared_strategy_info")
        if data_bytes is not None:
            shared_data = json.loads(data_bytes)
            self.log.info(f"Shared data retrieved: {shared_data}")
  • Data: Data types stored in the cache.
  • Strategies: Strategies access cache for market data and state.
  • Reports: Generate reports from cached data.

On this page