参与者

信息

We are currently working on this concept 指南.

The Actor serves as the foundational 组件 for interacting with the trading system. It provides core functionality for receiving market 数据, handling events, and managing state within the trading 环境. The Strategy class inherits from Actor and extends its capabilities with 订单管理 methods.

Key capabilities:

Event subscription and handling
Market 数据 reception
State management
System interaction primitives

Basic example

Just like 策略, 参与者支持配置 through a very similar pattern.

from nautilus_trader.config import ActorConfig
from nautilus_trader.model import InstrumentId
from nautilus_trader.model import Bar, BarType
from nautilus_trader.common.actor import Actor


class MyActorConfig(ActorConfig):
    instrument_id: InstrumentId   # example value: "ETHUSDT-PERP.BINANCE"
    bar_type: BarType             # example value: "ETHUSDT-PERP.BINANCE-15-MINUTE[LAST]-INTERNAL"
    lookback_period: int = 10


class MyActor(Actor):
    def __init__(self, config: MyActorConfig) -> None:
        super().__init__(config)

        # Custom state variables
        self.count_of_processed_bars: int = 0

    def on_start(self) -> None:
        # Subscribe to all incoming bars
        self.subscribe_bars(self.config.bar_type)   # You can access configuration directly via `self.config`

    def on_bar(self, bar: Bar):
        self.count_of_processed_bars += 1

数据 handling and callbacks

When working with 数据 in Nautilus, it's important to understand the relationship between 数据 requests/subscriptions and their corresponding callback handlers. The system uses different handlers depending on whether the 数据 is historical or 实时.

Historical vs 实时数据

The system distinguishes between two types of 数据 flow:

Historical 数据 (from requests):
- Obtained through methods like request_bars(), request_quote_ticks(), etc.
- Processed through the on_historical_data() handler.
- Used for initial 数据 loading and historical analysis.
实时数据 (from subscriptions):
- Obtained through methods like subscribe_bars(), subscribe_quote_ticks(), etc.
- Processed through specific handlers like on_bar(), on_quote_tick(), etc.
- Used for live 数据 processing.

Callback handlers

Here's how different 数据 operations map to their handlers:

Operation	Category	Handler	Purpose
`subscribe_data()`	实时	`on_data()`	Live 数据 updates
`subscribe_instrument()`	实时	`on_instrument()`	Live instrument definition updates
`subscribe_instruments()`	实时	`on_instrument()`	Live instrument definition updates (for venue)
`subscribe_order_book_deltas()`	实时	`on_order_book_deltas()`	Live order book updates
`subscribe_quote_ticks()`	实时	`on_quote_tick()`	Live quote updates
`subscribe_trade_ticks()`	实时	`on_trade_tick()`	Live trade updates
`subscribe_mark_prices()`	实时	`on_mark_price()`	Live mark price updates
`subscribe_index_prices()`	实时	`on_index_price()`	Live index price updates
`subscribe_funding_rates()`	实时	`on_funding_rate()`	Live funding rate updates
`subscribe_bars()`	实时	`on_bar()`	Live bar updates
`subscribe_instrument_status()`	实时	`on_instrument_status()`	Live instrument status updates
`subscribe_instrument_close()`	实时	`on_instrument_close()`	Live instrument close updates
`request_data()`	Historical	`on_historical_data()`	Historical 数据 processing
`request_instrument()`	Historical	`on_instrument()`	Instrument definition updates
`request_instruments()`	Historical	`on_instrument()`	Instrument definition updates
`request_quote_ticks()`	Historical	`on_historical_data()`	Historical quotes processing
`request_trade_ticks()`	Historical	`on_historical_data()`	Historical trades processing
`request_bars()`	Historical	`on_historical_data()`	Historical bars processing
`request_aggregated_bars()`	Historical	`on_historical_data()`	Historical aggregated bars (on-the-fly)

Example

Here's an example demonstrating both historical and 实时数据 handling:

from nautilus_trader.common.actor import Actor
from nautilus_trader.config import ActorConfig
from nautilus_trader.core.data import Data
from nautilus_trader.model import Bar, BarType
from nautilus_trader.model import ClientId, InstrumentId


class MyActorConfig(ActorConfig):
    instrument_id: InstrumentId  # example value: "AAPL.XNAS"
    bar_type: BarType            # example value: "AAPL.XNAS-1-MINUTE-LAST-EXTERNAL"


class MyActor(Actor):
    def __init__(self, config: MyActorConfig) -> None:
        super().__init__(config)
        self.bar_type = config.bar_type

    def on_start(self) -> None:
        # Request historical data - will be processed by on_historical_data() handler
        self.request_bars(
            bar_type=self.bar_type,
            # Many optional parameters
            start=None,                # datetime, optional
            end=None,                  # datetime, optional
            callback=None,             # called with the request ID when completed
            update_catalog_mode=None,  # UpdateCatalogMode | None, default None
            params=None,               # dict[str, Any], optional
        )

        # Subscribe to real-time data - will be processed by on_bar() handler
        self.subscribe_bars(
            bar_type=self.bar_type,
            # Many optional parameters
            client_id=None,       # ClientId, optional
            await_partial=False,  # bool, default False
            params=None,          # dict[str, Any], optional
        )

    def on_historical_data(self, data: Data) -> None:
        # Handle historical data (from requests)
        if isinstance(data, Bar):
            self.log.info(f"Received historical bar: {data}")

    def on_bar(self, bar: Bar) -> None:
        # Handle real-time bar updates (from subscriptions)
        self.log.info(f"Received real-time bar: {bar}")

This separation between historical and 实时数据 handlers allows for different processing logic based on the 数据 context. For example, you might want to:

Use historical 数据 to initialize indicators or establish baseline metrics.
Process 实时数据 differently for 实时交易 decisions.
Apply different 验证 or 日志记录 for historical vs 实时数据.

提示

When 调试数据 flow issues, check that you're looking at the correct handler for your 数据 source. If you're not seeing 数据 in on_bar() but see log messages about receiving bars, check on_historical_data() as the 数据 might be coming from a request rather than a subscription.

Basic example​

数据 handling and callbacks​

Historical vs 实时 数据​

Callback handlers​

Example​

Basic example

数据 handling and callbacks

Historical vs 实时数据

Callback handlers

Example