Principle:Nautechsystems Nautilus trader Data Event Handling
| Field | Value |
|---|---|
| sources | https://github.com/nautechsystems/nautilus_trader , https://nautilustrader.io/docs/ |
| domains | algorithmic trading, event-driven architecture, reactive programming, data processing |
| last_updated | 2026-02-10 12:00 GMT |
Overview
Data event handling defines the reactive pattern by which a trading strategy processes incoming market data events through well-defined handler methods, transforming raw data into trading decisions.
Description
In an event-driven trading system, strategies do not control the flow of execution. Instead, the system delivers data events to the strategy as they arrive, and the strategy reacts by executing the appropriate handler. This inversion of control is fundamental to the architecture:
- The strategy does not decide when to process data -- the system decides by calling the handler when data is available.
- The strategy decides what to do with the data by implementing the handler logic.
Each data type has a dedicated handler method:
- on_bar(bar): Invoked when an aggregated bar (OHLCV) is received. This is the most common handler for strategies that operate on periodic price summaries.
- on_trade_tick(tick): Invoked for each individual trade execution at the venue. Used for strategies that need tick-level precision.
- on_quote_tick(tick): Invoked for each best bid/ask update. Used for market-making strategies or spread monitoring.
- on_order_book(book): Invoked when a full order book snapshot is received.
- on_data(data): A generic handler for custom data types.
These handlers form a contract between the strategy and the framework. The framework guarantees:
- Handlers are called only when the strategy is in the RUNNING state.
- Handlers are called on the event loop thread, so no concurrent access protection is needed within a single strategy.
- The order of handler invocations respects the timestamp ordering of events.
The strategy author's responsibility is to implement the handler methods with the trading logic that transforms data events into order actions.
Usage
Apply data event handling when:
- Implementing any strategy that processes market data to generate trading signals.
- You need to react to multiple data types (bars, ticks, order books) in the same strategy.
- Building strategies where the decision logic depends on the latest market state.
Theoretical Basis
Data event handling implements the Template Method Pattern combined with Reactive Programming principles:
Template Method Pattern: The base class defines the skeleton of the event processing flow (receive event, validate state, dispatch to handler), while subclasses provide the concrete handler implementation. The base class ensures that handlers are only called when the strategy is in the correct state.
Reactive Programming: The strategy is a reactive stream processor -- it transforms an input stream of data events into an output stream of order commands. The processing is purely event-driven with no polling or blocking.
DATA FLOW:
[Market Data Source]
|
v
[Data Engine] --- publishes to ---> [Message Bus]
| |
| routes to subscribed handlers
v |
[Data Client] [Strategy.on_bar()]
[Strategy.on_trade_tick()]
[Strategy.on_quote_tick()]
|
v
[Trading Logic]
|
v
[Order Submission]
Pseudocode for data event handling:
CLASS Strategy:
// Framework calls these methods -- user overrides them
FUNCTION on_bar(bar: Bar):
UPDATE indicators with bar data
IF entry_signal_detected(bar):
CREATE and SUBMIT order
ELSE IF exit_signal_detected(bar):
CLOSE position
FUNCTION on_trade_tick(tick: TradeTick):
UPDATE tick-level state
IF tick confirms entry signal:
REFINE entry timing and SUBMIT order
FUNCTION on_quote_tick(tick: QuoteTick):
UPDATE spread state
IF spread is favorable:
ADJUST limit order prices
Key invariants:
- Single-threaded execution: All handler calls for a given strategy happen sequentially on the same event loop. No locks are needed.
- No-throw contract: Handlers should not raise unhandled exceptions. If they do, the framework logs the error and may transition the strategy to a FAULTED state.
- Stateless with respect to call order: While handlers may update internal state, the framework makes no guarantee about the relative order of different handler types for events with identical timestamps.