Common

The common subpackage provides generic/common parts for assembling the frameworks various components.

More domain specific concepts are introduced above the core base layer. The ID cache is implemented, a base Clock with Test and Live implementations which can control many Timer instances.

Trading domain specific components for generating Order and Identifier objects, common logging components, a high performance Queue and UUID4 factory.

The Actor class allows traders to implement their own customized components.

A user can inherit from Actor and optionally override any of the “on” named event methods. The class is not entirely initialized in a stand-alone way, the intended usage is to pass actors to a Trader so that they can be fully “wired” into the platform. Exceptions will be raised if an Actor attempts to operate without a managing Trader instance.

class Actor ( config : Optional [ ActorConfig ] = None )

Bases: Component

The base class for all actor components.

Parameters :

config ( ActorConfig , optional ) – The actor configuration.

Raises :

TypeError – If config is not of type ActorConfig .

Warning

This class should not be used directly, but through a concrete subclass.

active_task_ids ( self ) → list

Return the active task identifiers.

Returns :

list[TaskId]

add_synthetic ( self , SyntheticInstrument synthetic ) → void

Add the created synthetic instrument to the cache.

Parameters :

synthetic ( SyntheticInstrument ) – The synthetic instrument to add to the cache.

Raises :

KeyError – If synthetic is already in the cache.

Notes

If you are updating the synthetic instrument then you should use the update_synthetic method.

cache

The read-only cache for the actor.

Returns :

CacheFacade

cancel_all_tasks ( self ) → void

Cancel all queued and active tasks.

cancel_task ( self , task_id : TaskId ) → void

Cancel the task with the given task_id (if queued or active).

If the task is not found then a warning is logged.

Parameters :

task_id ( TaskId ) – The task identifier.

clock

The actors clock.

Returns :

Clock

config

The actors configuration.

Returns :

NautilusConfig

degrade ( self ) → void

Degrade the component.

While executing on_degrade() any exception will be logged and reraised, then the component will remain in a DEGRADING state.

Warning

Do not override.

If the component is not in a valid state from which to execute this method, then the component state will not change, and an error will be logged.

deregister_warning_event ( self , type event ) → void

Deregister the given event type from warning log levels.

Parameters :

event ( type ) – The event class to deregister.

dispose ( self ) → void

Dispose of the component.

While executing on_dispose() any exception will be logged and reraised, then the component will remain in a DISPOSING state.

Warning

Do not override.

If the component is not in a valid state from which to execute this method, then the component state will not change, and an error will be logged.

fault ( self ) → void

Fault the component.

Calling this method multiple times has the same effect as calling it once (it is idempotent). Once called, it cannot be reversed, and no other methods should be called on this instance.

While executing on_fault() any exception will be logged and reraised, then the component will remain in a FAULTING state.

Warning

Do not override.

If the component is not in a valid state from which to execute this method, then the component state will not change, and an error will be logged.

classmethod fully_qualified_name ( cls ) → str

Return the fully qualified name for the components class.

Returns :

str

References

https://www.python.org/dev/peps/pep-3155/

handle_bar ( self , Bar bar ) → void

Handle the given bar data.

If state is RUNNING then passes to on_bar .

Parameters :

bar ( Bar ) – The bar received.

Warning

System method (not intended to be called by user code).

handle_bars ( self , list bars ) → void

Handle the given historical bar data by handling each bar individually.

Parameters :

bars ( list [ Bar ] ) – The bars to handle.

Warning

System method (not intended to be called by user code).

handle_data ( self , Data data ) → void

Handle the given data.

If state is RUNNING then passes to on_data .

Parameters :

data ( Data ) – The data received.

Warning

System method (not intended to be called by user code).

handle_event ( self , Event event ) → void

Handle the given event.

If state is RUNNING then passes to on_event .

Parameters :

event ( Event ) – The event received.

Warning

System method (not intended to be called by user code).

handle_historical_data ( self , Data data ) → void

Handle the given historical data.

Parameters :

data ( Data ) – The historical data received.

Warning

System method (not intended to be called by user code).

handle_instrument ( self , Instrument instrument ) → void

Handle the given instrument.

Passes to on_instrument if state is RUNNING .

Parameters :

instrument ( Instrument ) – The instrument received.

Warning

System method (not intended to be called by user code).

handle_instrument_close ( self , InstrumentClose update ) → void

Handle the given instrument close update.

If state is RUNNING then passes to on_instrument_close .

Parameters :

update ( InstrumentClose ) – The update received.

Warning

System method (not intended to be called by user code).

handle_instrument_status_update ( self , InstrumentStatusUpdate update ) → void

Handle the given instrument status update.

If state is RUNNING then passes to on_instrument_status_update .

Parameters :

update ( InstrumentStatusUpdate ) – The update received.

Warning

System method (not intended to be called by user code).

handle_instruments ( self , list instruments ) → void

Handle the given instruments data by handling each instrument individually.

Parameters :

instruments ( list [ Instrument ] ) – The instruments received.

Warning

System method (not intended to be called by user code).

handle_order_book ( self , OrderBook order_book ) → void

Handle the given order book.

Passes to on_order_book if state is RUNNING .

Parameters :

order_book ( OrderBook ) – The order book received.

Warning

System method (not intended to be called by user code).

handle_order_book_deltas ( self , OrderBookDeltas deltas ) → void

Handle the given order book deltas.

Passes to on_order_book_delta if state is RUNNING .

Parameters :

deltas ( OrderBookDeltas ) – The order book deltas received.

Warning

System method (not intended to be called by user code).

handle_quote_tick ( self , QuoteTick tick ) → void

Handle the given quote tick.

If state is RUNNING then passes to on_quote_tick .

Parameters :

tick ( QuoteTick ) – The tick received.

Warning

System method (not intended to be called by user code).

handle_quote_ticks ( self , list ticks ) → void

Handle the given historical quote tick data by handling each tick individually.

Parameters :

ticks ( list [ QuoteTick ] ) – The ticks received.

Warning

System method (not intended to be called by user code).

handle_ticker ( self , Ticker ticker ) → void

Handle the given ticker.

If state is RUNNING then passes to on_ticker .

Parameters :

ticker ( Ticker ) – The ticker received.

Warning

System method (not intended to be called by user code).

handle_trade_tick ( self , TradeTick tick ) → void

Handle the given trade tick.

If state is RUNNING then passes to on_trade_tick .

Parameters :

tick ( TradeTick ) – The tick received.

Warning

System method (not intended to be called by user code).

handle_trade_ticks ( self , list ticks ) → void

Handle the given tick data by handling each tick individually.

Parameters :

ticks ( list [ TradeTick ] ) – The ticks received.

Warning

System method (not intended to be called by user code).

handle_venue_status_update ( self , VenueStatusUpdate update ) → void

Handle the given venue status update.

If state is RUNNING then passes to on_venue_status_update .

Parameters :

update ( VenueStatusUpdate ) – The update received.

Warning

System method (not intended to be called by user code).

has_active_tasks ( self ) → bool

Return a value indicating whether there are any active tasks.

Returns :

bool

has_any_tasks ( self ) → bool

Return a value indicating whether there are any queued or active tasks.

Returns :

bool

has_pending_requests ( self ) → bool

Return whether the actor is pending processing for any requests.

Returns :

bool – True if any requests are pending, else False.

has_queued_tasks ( self ) → bool

Return a value indicating whether there are any queued tasks.

Returns :

bool

id

The components ID.

Returns :

ComponentId

is_degraded

bool

Return whether the current component state is DEGRADED .

Returns :

bool

Type :

Component.is_degraded

is_disposed

bool

Return whether the current component state is DISPOSED .

Returns :

bool

Type :

Component.is_disposed

is_faulted

bool

Return whether the current component state is FAULTED .

Returns :

bool

Type :

Component.is_faulted

is_initialized

bool

Return whether the component has been initialized (component.state >= INITIALIZED ).

Returns :

bool

Type :

Component.is_initialized

is_pending_request ( self , UUID4 request_id ) → bool

Return whether the request for the given identifier is pending processing.

Parameters :

request_id ( UUID4 ) – The request ID to check.

Returns :

bool – True if request is pending, else False.

is_running

bool

Return whether the current component state is RUNNING .

Returns :

bool

Type :

Component.is_running

is_stopped

bool

Return whether the current component state is STOPPED .

Returns :

bool

Type :

Component.is_stopped

load ( self , dict state ) → void

Load the actor/strategy state from the give state dictionary.

Calls on_load and passes the state.

Parameters :

state ( dict [ str , object ] ) – The state dictionary.

Raises :

RuntimeError – If actor/strategy is not registered with a trader.

Warning

Exceptions raised will be caught, logged, and reraised.

log

The actors logger.

Returns :

LoggerAdapter

msgbus

The message bus for the actor (if registered).

Returns :

MessageBus or None

on_bar ( self , Bar bar ) → void

Actions to be performed when running and receives a bar.

Parameters :

bar ( Bar ) – The bar received.

Warning

System method (not intended to be called by user code).

on_data ( self , Data data ) → void

Actions to be performed when running and receives generic data.

Parameters :

data ( Data ) – The data received.

Warning

System method (not intended to be called by user code).

on_degrade ( self ) → void

Actions to be performed on degrade.

Warning

System method (not intended to be called by user code).

Should be overridden in the actor implementation.

on_dispose ( self ) → void

Actions to be performed on dispose.

Cleanup/release any resources used here.

Warning

System method (not intended to be called by user code).

on_event ( self , Event event ) → void

Actions to be performed running and receives an event.

Parameters :

event ( Event ) – The event received.

Warning

System method (not intended to be called by user code).

on_fault ( self ) → void

Actions to be performed on fault.

Cleanup any resources used by the actor here.

Warning

System method (not intended to be called by user code).

Should be overridden in the actor implementation.

on_historical_data ( self , Data data ) → void

Actions to be performed when running and receives historical data.

Parameters :

data ( Data ) – The historical data received.

Warning

System method (not intended to be called by user code).

on_instrument ( self , Instrument instrument ) → void

Actions to be performed when running and receives an instrument.

Parameters :

instrument ( Instrument ) – The instrument received.

Warning

System method (not intended to be called by user code).

on_instrument_close ( self , InstrumentClose update ) → void

Actions to be performed when running and receives an instrument close update.

Parameters :

update ( InstrumentClose ) – The update received.

Warning

System method (not intended to be called by user code).

on_instrument_status_update ( self , InstrumentStatusUpdate update ) → void

Actions to be performed when running and receives an instrument status update.

Parameters :

update ( InstrumentStatusUpdate ) – The update received.

Warning

System method (not intended to be called by user code).

on_load ( self , dict state ) → void

Actions to be performed when the actor state is loaded.

Saved state values will be contained in the give state dictionary.

Warning

System method (not intended to be called by user code).

on_order_book ( self , OrderBook order_book ) → void

Actions to be performed when running and receives an order book.

Parameters :

order_book ( OrderBook ) – The order book received.

Warning

System method (not intended to be called by user code).

on_order_book_deltas ( self , OrderBookDeltas deltas ) → void

Actions to be performed when running and receives order book deltas.

Parameters :

deltas ( OrderBookDeltas ) – The order book deltas received.

Warning

System method (not intended to be called by user code).

on_quote_tick ( self , QuoteTick tick ) → void

Actions to be performed when running and receives a quote tick.

Parameters :

tick ( QuoteTick ) – The tick received.

Warning

System method (not intended to be called by user code).

on_reset ( self ) → void

Actions to be performed on reset.

Warning

System method (not intended to be called by user code).

Should be overridden in a user implementation.

on_resume ( self ) → void

Actions to be performed on resume.

Warning

System method (not intended to be called by user code).

on_save ( self ) → dict

Actions to be performed when the actor state is saved.

Create and return a state dictionary of values to be saved.

Returns :

dict[str, bytes] – The strategy state dictionary.

Warning

System method (not intended to be called by user code).

on_start ( self ) → void

Actions to be performed on start.

The intent is that this method is called once per trading ‘run’, when initially starting.

It is recommended to subscribe/request for data here.

Warning

System method (not intended to be called by user code).

Should be overridden in a user implementation.

on_stop ( self ) → void

Actions to be performed on stop.

The intent is that this method is called to pause, or when done for day.

Warning

System method (not intended to be called by user code).

Should be overridden in a user implementation.

on_ticker ( self , Ticker ticker ) → void

Actions to be performed when running and receives a ticker.

Parameters :

ticker ( Ticker ) – The ticker received.

Warning

System method (not intended to be called by user code).

on_trade_tick ( self , TradeTick tick ) → void

Actions to be performed when running and receives a trade tick.

Parameters :

tick ( TradeTick ) – The tick received.

Warning

System method (not intended to be called by user code).

on_venue_status_update ( self , VenueStatusUpdate update ) → void

Actions to be performed when running and receives a venue status update.

Parameters :

update ( VenueStatusUpdate ) – The update received.

Warning

System method (not intended to be called by user code).

pending_requests ( self ) → set

Return the request IDs which are currently pending processing.

Returns :

set[UUID4]

publish_data ( self , DataType data_type , Data data ) → void

Publish the given data to the message bus.

Parameters :

• data_type ( DataType ) – The data type being published.

• data ( Data ) – The data to publish.

publish_signal ( self , unicode name , value , uint64_t ts_event=0 ) → void

Publish the given value as a signal to the message bus. Optionally setup persistence for this signal .

Parameters :

• name ( str ) – The name of the signal being published.

• value ( object ) – The signal data to publish.

• ts_event ( uint64_t , optional ) – The UNIX timestamp (nanoseconds) when the signal event occurred. If None then will timestamp current time.

queue_for_executor ( self, func: Callable[..., Any], tuple args=None, dict kwargs=None )

Queues the callable func to be executed as fn(*args, **kwargs) sequentially.

Parameters :

• func ( Callable ) – The function to be executed.

• args ( positional arguments ) – The positional arguments for the call to func .

• kwargs ( arbitrary keyword arguments ) – The keyword arguments for the call to func .

Raises :

TypeError – If func is not of type Callable .

Notes

For backtesting the func is immediately executed, as there’s no need for a Future object that can be awaited. In a backtesting scenario, the execution is not in real time, and so the results of func are ‘immediately’ available after it’s called.

queued_task_ids ( self ) → list

Return the queued task identifiers.

Returns :

list[TaskId]

register_base ( self , MessageBus msgbus , CacheFacade cache , Clock clock , Logger logger ) → void

Register with a trader.

Parameters :

• msgbus ( MessageBus ) – The message bus for the actor.

• cache ( CacheFacade ) – The read-only cache for the actor.

• clock ( Clock ) – The clock for the actor.

• logger ( Logger ) – The logger for the actor.

Warning

System method (not intended to be called by user code).

register_executor ( self , loop : asyncio.AbstractEventLoop , executor : Executor ) → void

Register the given Executor for the actor.

Parameters :

• loop ( asyncio.AsbtractEventLoop ) – The event loop of the application.

• executor ( concurrent.futures.Executor ) – The executor to register.

Raises :

TypeError – If executor is not of type concurrent.futures.Executor

register_warning_event ( self , type event ) → void

Register the given event type for warning log levels.

Parameters :

event ( type ) – The event class to register.

request_bars ( self, BarType bar_type, datetime start=None, datetime end=None, ClientId client_id=None, callback: Callable[[UUID4], None] | None = None ) → UUID4

Request historical Bar data.

If end is None then will request up to the most recent data.

Parameters :

• bar_type ( BarType ) – The bar type for the request.

• start ( datetime , optional ) – The start datetime (UTC) of request time range (inclusive).

• end ( datetime , optional ) – The end datetime (UTC) of request time range (inclusive). If None then will default to the current datetime (UTC).

• client_id ( ClientId , optional ) – The specific client ID for the command. If None then will be inferred from the venue in the instrument ID.

• callback ( Callable [ [ UUID4 ] , None ] , optional ) – The registered callback, to be called with the request ID when the response has completed processing.

Returns :

UUID4 – The request_id for the request.

Raises :

• ValueError – If start is not less than end .

• TypeError – If callback is not None and not of type Callable .

request_data ( self, DataType data_type, ClientId client_id, callback: Callable[[UUID4], None] | None = None ) → UUID4

Request custom data for the given data type from the given data client.

Parameters :

• data_type ( DataType ) – The data type for the request.

• client_id ( ClientId ) – The data client ID.

• callback ( Callable [ [ UUID4 ] , None ] , optional ) – The registered callback, to be called with the request ID when the response has completed processing.

Returns :

UUID4 – The request_id for the request.

Raises :

TypeError – If callback is not None and not of type Callable .

request_instrument ( self, InstrumentId instrument_id, ClientId client_id=None, callback: Callable[[UUID4], None] | None = None ) → UUID4

Request Instrument data for the given instrument ID.

Parameters :

• instrument_id ( InstrumentId ) – The instrument ID for the request.

• client_id ( ClientId , optional ) – The specific client ID for the command. If None then will be inferred from the venue in the instrument ID.

• callback ( Callable [ [ UUID4 ] , None ] , optional ) – The registered callback, to be called with the request ID when the response has completed processing.

Returns :

UUID4 – The request_id for the request.

Raises :

TypeError – If callback is not None and not of type Callable .

request_instruments ( self, Venue venue, ClientId client_id=None, callback: Callable[[UUID4], None] | None = None ) → UUID4

Request all Instrument data for the given venue.

Parameters :

• venue ( Venue ) – The venue for the request.

• client_id ( ClientId , optional ) – The specific client ID for the command. If None then will be inferred from the venue in the instrument ID.

• callback ( Callable [ [ UUID4 ] , None ] , optional ) – The registered callback, to be called with the request ID when the response has completed processing.

Returns :

UUID4 – The request_id for the request.

Raises :

TypeError – If callback is not None and not of type Callable .

request_quote_ticks ( self, InstrumentId instrument_id, datetime start=None, datetime end=None, ClientId client_id=None, callback: Callable[[UUID4], None] | None = None ) → UUID4

Request historical QuoteTick data.

If end is None then will request up to the most recent data.

Parameters :

• instrument_id ( InstrumentId ) – The tick instrument ID for the request.

• start ( datetime , optional ) – The start datetime (UTC) of request time range (inclusive).

• end ( datetime , optional ) – The end datetime (UTC) of request time range (inclusive). If None then will default to the current datetime (UTC).

• client_id ( ClientId , optional ) – The specific client ID for the command. If None then will be inferred from the venue in the instrument ID.

• callback ( Callable [ [ UUID4 ] , None ] , optional ) – The registered callback, to be called with the request ID when the response has completed processing.

Returns :

UUID4 – The request_id for the request.

Raises :

• ValueError – If start is not less than end .

• TypeError – If callback is not None and not of type Callable .

request_trade_ticks ( self, InstrumentId instrument_id, datetime start=None, datetime end=None, ClientId client_id=None, callback: Callable[[UUID4], None] | None = None ) → UUID4

Request historical TradeTick data.

If end is None then will request up to the most recent data.

Parameters :

• instrument_id ( InstrumentId ) – The tick instrument ID for the request.

• start ( datetime , optional ) – The start datetime (UTC) of request time range (inclusive).

• end ( datetime , optional ) – The end datetime (UTC) of request time range (inclusive). If None then will default to the current datetime (UTC).

• client_id ( ClientId , optional ) – The specific client ID for the command. If None then will be inferred from the venue in the instrument ID.

• callback ( Callable [ [ UUID4 ] , None ] , optional ) – The registered callback, to be called with the request ID when the response has completed processing.

Returns :

UUID4 – The request_id for the request.

Raises :

• ValueError – If start is not less than end .

• TypeError – If callback is not None and not of type Callable .

reset ( self ) → void

Reset the component.

All stateful fields are reset to their initial value.

While executing on_reset() any exception will be logged and reraised, then the component will remain in a RESETTING state.

Warning

Do not override.

If the component is not in a valid state from which to execute this method, then the component state will not change, and an error will be logged.

resume ( self ) → void

Resume the component.

While executing on_resume() any exception will be logged and reraised, then the component will remain in a RESUMING state.

Warning

Do not override.

If the component is not in a valid state from which to execute this method, then the component state will not change, and an error will be logged.

run_in_executor ( self, func: Callable[..., Any], tuple args=None, dict kwargs=None )

Schedules the callable func to be executed as fn(*args, **kwargs) .

Parameters :

• func ( Callable ) – The function to be executed.

• args ( positional arguments ) – The positional arguments for the call to func .

• kwargs ( arbitrary keyword arguments ) – The keyword arguments for the call to func .

Returns :

TaskId – The unique task identifier for the execution. This also corresponds to any future objects memory address.

Raises :

TypeError – If func is not of type Callable .

Notes

For backtesting the func is immediately executed, as there’s no need for a Future object that can be awaited. In a backtesting scenario, the execution is not in real time, and so the results of func are ‘immediately’ available after it’s called.

save ( self ) → dict

Return the actor/strategy state dictionary to be saved.

Calls on_save .

Raises :

RuntimeError – If actor/strategy is not registered with a trader.

Warning

Exceptions raised will be caught, logged, and reraised.

start ( self ) → void

Start the component.

While executing on_start() any exception will be logged and reraised, then the component will remain in a STARTING state.

Warning

Do not override.

If the component is not in a valid state from which to execute this method, then the component state will not change, and an error will be logged.

state

ComponentState

Return the components current state.

Returns :

ComponentState

Type :

Component.state

stop ( self ) → void

Stop the component.

While executing on_stop() any exception will be logged and reraised, then the component will remain in a STOPPING state.

Warning

Do not override.

If the component is not in a valid state from which to execute this method, then the component state will not change, and an error will be logged.

subscribe_bars ( self , BarType bar_type , ClientId client_id=None ) → void

Subscribe to streaming Bar data for the given bar type.

Parameters :

• bar_type ( BarType ) – The bar type to subscribe to.

• client_id ( ClientId , optional ) – The specific client ID for the command. If None then will be inferred from the venue in the instrument ID.

subscribe_data ( self , DataType data_type , ClientId client_id=None ) → void

Subscribe to data of the given data type.

Parameters :

• data_type ( DataType ) – The data type to subscribe to.

• client_id ( ClientId , optional ) – The data client ID. If supplied then a Subscribe command will be sent to the corresponding data client.

subscribe_instrument ( self , InstrumentId instrument_id , ClientId client_id=None ) → void

Subscribe to update Instrument data for the given instrument ID.

Parameters :

• instrument_id ( InstrumentId ) – The instrument ID for the subscription.

• client_id ( ClientId , optional ) – The specific client ID for the command. If None then will be inferred from the venue in the instrument ID.

subscribe_instrument_close ( self , InstrumentId instrument_id , ClientId client_id=None ) → void

Subscribe to close updates for the given instrument ID.

Parameters :

• instrument_id ( InstrumentId ) – The instrument to subscribe to status updates for.

• client_id ( ClientId , optional ) – The specific client ID for the command. If None then will be inferred from the venue in the instrument ID.

subscribe_instrument_status_updates ( self , InstrumentId instrument_id , ClientId client_id=None ) → void

Subscribe to status updates for the given instrument ID.

Parameters :

• instrument_id ( InstrumentId ) – The instrument to subscribe to status updates for.

• client_id ( ClientId , optional ) – The specific client ID for the command. If None then will be inferred from the venue in the instrument ID.

subscribe_instruments ( self , Venue venue , ClientId client_id=None ) → void

Subscribe to update Instrument data for the given venue.

Parameters :

• venue ( Venue ) – The venue for the subscription.

• client_id ( ClientId , optional ) – The specific client ID for the command. If None then will be inferred from the venue.

subscribe_order_book_deltas ( self , InstrumentId instrument_id , BookType book_type=BookType.L2_MBP , int depth=0 , dict kwargs=None , ClientId client_id=None ) → void

Subscribe to the order book data stream, being a snapshot then deltas for the given instrument ID.

Parameters :

• instrument_id ( InstrumentId ) – The order book instrument ID to subscribe to.

• book_type (BookType { L1_TBBO , L2_MBP , L3_MBO }) – The order book type.

• depth ( int , optional ) – The maximum depth for the order book. A depth of 0 is maximum depth.

• kwargs ( dict , optional ) – The keyword arguments for exchange specific parameters.

• client_id ( ClientId , optional ) – The specific client ID for the command. If None then will be inferred from the venue in the instrument ID.

subscribe_order_book_snapshots ( self , InstrumentId instrument_id , BookType book_type=BookType.L2_MBP , int depth=0 , int interval_ms=1000 , dict kwargs=None , ClientId client_id=None ) → void

Subscribe to OrderBook snapshots at a specified interval, for the given instrument ID.

The DataEngine will only maintain one order book for each instrument. Because of this - the level, depth and kwargs for the stream will be set as per the last subscription request (this will also affect all subscribers).

Parameters :

• instrument_id ( InstrumentId ) – The order book instrument ID to subscribe to.

• book_type (BookType { L1_TBBO , L2_MBP , L3_MBO }) – The order book type.

• depth ( int , optional ) – The maximum depth for the order book. A depth of 0 is maximum depth.

• interval_ms ( int ) – The order book snapshot interval in milliseconds.

• kwargs ( dict , optional ) – The keyword arguments for exchange specific parameters.

• client_id ( ClientId , optional ) – The specific client ID for the command. If None then will be inferred from the venue in the instrument ID.

Raises :

• ValueError – If depth is negative (< 0).

• ValueError – If interval_ms is not positive (> 0).

subscribe_quote_ticks ( self , InstrumentId instrument_id , ClientId client_id=None ) → void

Subscribe to streaming QuoteTick data for the given instrument ID.

Parameters :

• instrument_id ( InstrumentId ) – The tick instrument to subscribe to.

• client_id ( ClientId , optional ) – The specific client ID for the command. If None then will be inferred from the venue in the instrument ID.

subscribe_ticker ( self , InstrumentId instrument_id , ClientId client_id=None ) → void

Subscribe to streaming Ticker data for the given instrument ID.

Parameters :

• instrument_id ( InstrumentId ) – The tick instrument to subscribe to.

• client_id ( ClientId , optional ) – The specific client ID for the command. If None then will be inferred from the venue in the instrument ID.

subscribe_trade_ticks ( self , InstrumentId instrument_id , ClientId client_id=None ) → void

Subscribe to streaming TradeTick data for the given instrument ID.

Parameters :

• instrument_id ( InstrumentId ) – The tick instrument to subscribe to.

• client_id ( ClientId , optional ) – The specific client ID for the command. If None then will be inferred from the venue in the instrument ID.

subscribe_venue_status_updates ( self , Venue venue , ClientId client_id=None ) → void

Subscribe to status updates for the given venue.

Parameters :

• venue ( Venue ) – The venue to subscribe to.

• client_id ( ClientId , optional ) – The specific client ID for the command. If None then will be inferred from the venue.

to_importable_config ( self ) → ImportableActorConfig

Returns an importable configuration for this actor.

Returns :

ImportableActorConfig

trader_id

The trader ID associated with the component.

Returns :

TraderId

type

The components type.

Returns :

type

unsubscribe_bars ( self , BarType bar_type , ClientId client_id=None ) → void

Unsubscribe from streaming Bar data for the given bar type.

Parameters :

• bar_type ( BarType ) – The bar type to unsubscribe from.

• client_id ( ClientId , optional ) – The specific client ID for the command. If None then will be inferred from the venue in the instrument ID.

unsubscribe_data ( self , DataType data_type , ClientId client_id=None ) → void

Unsubscribe from data of the given data type.

Parameters :

• data_type ( DataType ) – The data type to unsubscribe from.

• client_id ( ClientId , optional ) – The data client ID. If supplied then an Unsubscribe command will be sent to the data client.

unsubscribe_instrument ( self , InstrumentId instrument_id , ClientId client_id=None ) → void

Unsubscribe from update Instrument data for the given instrument ID.

Parameters :

• instrument_id ( InstrumentId ) – The instrument to unsubscribe from.

• client_id ( ClientId , optional ) – The specific client ID for the command. If None then will be inferred from the venue in the instrument ID.

unsubscribe_instrument_status_updates ( self , InstrumentId instrument_id , ClientId client_id=None ) → void

Unsubscribe to status updates of the given venue.

Parameters :

• instrument_id ( InstrumentId ) – The instrument to unsubscribe to status updates for.

• client_id ( ClientId , optional ) – The specific client ID for the command. If None then will be inferred from the venue.

unsubscribe_instruments ( self , Venue venue , ClientId client_id=None ) → void

Unsubscribe from update Instrument data for the given venue.

Parameters :

• venue ( Venue ) – The venue for the subscription.

• client_id ( ClientId , optional ) – The specific client ID for the command. If None then will be inferred from the venue.

unsubscribe_order_book_deltas ( self , InstrumentId instrument_id , ClientId client_id=None ) → void

Unsubscribe the order book deltas stream for the given instrument ID.

Parameters :

• instrument_id ( InstrumentId ) – The order book instrument to subscribe to.

• client_id ( ClientId , optional ) – The specific client ID for the command. If None then will be inferred from the venue in the instrument ID.

unsubscribe_order_book_snapshots ( self , InstrumentId instrument_id , int interval_ms=1000 , ClientId client_id=None ) → void

Unsubscribe from OrderBook snapshots, for the given instrument ID.

The interval must match the previously subscribed interval.

Parameters :

• instrument_id ( InstrumentId ) – The order book instrument to subscribe to.

• interval_ms ( int ) – The order book snapshot interval in milliseconds.

• client_id ( ClientId , optional ) – The specific client ID for the command. If None then will be inferred from the venue in the instrument ID.

unsubscribe_quote_ticks ( self , InstrumentId instrument_id , ClientId client_id=None ) → void

Unsubscribe from streaming QuoteTick data for the given instrument ID.

Parameters :

• instrument_id ( InstrumentId ) – The tick instrument to unsubscribe from.

• client_id ( ClientId , optional ) – The specific client ID for the command. If None then will be inferred from the venue in the instrument ID.

unsubscribe_ticker ( self , InstrumentId instrument_id , ClientId client_id=None ) → void

Unsubscribe from streaming Ticker data for the given instrument ID.

Parameters :

• instrument_id ( InstrumentId ) – The tick instrument to unsubscribe from.

• client_id ( ClientId , optional ) – The specific client ID for the command. If None then will be inferred from the venue in the instrument ID.

unsubscribe_trade_ticks ( self , InstrumentId instrument_id , ClientId client_id=None ) → void

Unsubscribe from streaming TradeTick data for the given instrument ID.

Parameters :

• instrument_id ( InstrumentId ) – The tick instrument ID to unsubscribe from.

• client_id ( ClientId , optional ) – The specific client ID for the command. If None then will be inferred from the venue in the instrument ID.

unsubscribe_venue_status_updates ( self , Venue venue , ClientId client_id=None ) → void

Unsubscribe to status updates for the given venue.

Parameters :

• venue ( Venue ) – The venue to unsubscribe from.

• client_id ( ClientId , optional ) – The specific client ID for the command. If None then will be inferred from the venue.

update_synthetic ( self , SyntheticInstrument synthetic ) → void

Update the synthetic instrument in the cache.

Parameters :

synthetic ( SyntheticInstrument ) – The synthetic instrument to update in the cache.

Raises :

KeyError – If synthetic does not already exist in the cache.

Notes

If you are adding a new synthetic instrument then you should use the add_synthetic method.

Clock

class Clock

Bases: object

The base class for all clocks.

Notes

An active timer is one which has not expired.

Warning

This class should not be used directly, but through a concrete subclass.

cancel_timer ( self , unicode name ) → void

Cancel the timer corresponding to the given label.

Parameters :

name ( str ) – The name for the timer to cancel.

Raises :

• ValueError – If name is not a valid string.

• KeyError – If name is not an active timer name for this clock.

cancel_timers ( self ) → void

Cancel all timers.

local_now ( self , tzinfo tz=None ) → datetime

Return the current datetime of the clock in the given local timezone.

Parameters :

tz ( tzinfo , optional ) – The local timezone (if None the system local timezone is assumed for the target timezone).

Returns :

datetime – tz-aware in local timezone.

next_time_ns ( self , unicode name ) → uint64_t

Find a particular timer.

Parameters :

name ( str ) – The name of the timer.

Returns :

uint64_t

Raises :

ValueError – If name is not a valid string.

register_default_handler ( self , handler : Callable [ [ TimeEvent ] , None ] ) → void

Register the given handler as the clocks default handler.

handler Callable[[TimeEvent], None]

The handler to register.

Raises :

TypeError – If handler is not of type Callable .

set_time_alert ( self, unicode name, datetime alert_time, callback: Callable[[TimeEvent], None] = None ) → void

Set a time alert for the given time.

When the time is reached the handler will be passed the TimeEvent containing the timers unique name. If no handler is passed then the default handler (if registered) will receive the TimeEvent .

Parameters :

• name ( str ) – The name for the alert (must be unique for this clock).

• alert_time ( datetime ) – The time for the alert.

• callback ( Callable [ [ TimeEvent ] , None ] , optional ) – The callback to receive time events.

Raises :

• ValueError – If name is not a valid string.

• KeyError – If name is not unique for this clock.

• TypeError – If handler is not of type Callable or None .

• ValueError – If handler is None and no default handler is registered.

Warning

If alert_time is in the past or at current time, then an immediate time event will be generated (rather than being invalid and failing a condition check).

set_time_alert_ns ( self, unicode name, uint64_t alert_time_ns, callback: Callable[[TimeEvent], None] = None ) → void

Set a time alert for the given time.

When the time is reached the handler will be passed the TimeEvent containing the timers unique name. If no callback is passed then the default handler (if registered) will receive the TimeEvent .

Parameters :

• name ( str ) – The name for the alert (must be unique for this clock).

• alert_time_ns ( uint64_t ) – The UNIX time (nanoseconds) for the alert.

• callback ( Callable [ [ TimeEvent ] , None ] , optional ) – The callback to receive time events.

Raises :

• ValueError – If name is not a valid string.

• ValueError – If name is not unique for this clock.

• TypeError – If callback is not of type Callable or None .

• ValueError – If callback is None and no default handler is registered.

Warning

If alert_time_ns is in the past or at current time, then an immediate time event will be generated (rather than being invalid and failing a condition check).

set_timer ( self, unicode name, timedelta interval, datetime start_time=None, datetime stop_time=None, callback: Optional[Callable[[TimeEvent], None]] = None ) → void

Set a timer to run.

The timer will run from the start time (optionally until the stop time). When the intervals are reached the handlers will be passed the TimeEvent containing the timers unique name. If no handler is passed then the default handler (if registered) will receive the TimeEvent .

Parameters :

• name ( str ) – The name for the timer (must be unique for this clock).

• interval ( timedelta ) – The time interval for the timer.

• start_time ( datetime , optional ) – The start time for the timer (if None then starts immediately).

• stop_time ( datetime , optional ) – The stop time for the timer (if None then repeats indefinitely).

• callback ( Callable [ [ TimeEvent ] , None ] , optional ) – The callback to receive time events.

Raises :

• ValueError – If name is not a valid string.

• KeyError – If name is not unique for this clock.

• ValueError – If interval is not positive (> 0).

• ValueError – If stop_time is not None and stop_time < time now.

• ValueError – If stop_time is not None and start_time + interval > stop_time .

• TypeError – If handler is not of type Callable or None .

• ValueError – If handler is None and no default handler is registered.

set_timer_ns ( self, unicode name, uint64_t interval_ns, uint64_t start_time_ns, uint64_t stop_time_ns, callback: Optional[Callable[[TimeEvent], None]] = None ) → void

Set a timer to run.

The timer will run from the start time until the stop time. When the intervals are reached the handlers will be passed the TimeEvent containing the timers unique name. If no handler is passed then the default handler (if registered) will receive the TimeEvent .

Parameters :

• name ( str ) – The name for the timer (must be unique for this clock).

• interval_ns ( uint64_t ) – The time interval (nanoseconds) for the timer.

• start_time_ns ( uint64_t ) – The start UNIX time (nanoseconds) for the timer.

• stop_time_ns ( uint64_t ) – The stop UNIX time (nanoseconds) for the timer.

• callback ( Callable [ [ TimeEvent ] , None ] , optional ) – The callback to receive time events.

Raises :

• ValueError – If name is not a valid string.

• KeyError – If name is not unique for this clock.

• ValueError – If interval is not positive (> 0).

• ValueError – If stop_time is not None and stop_time < time now.

• ValueError – If stop_time is not None and start_time + interval > stop_time .

• TypeError – If callback is not of type Callable or None .

• ValueError – If callback is None and no default handler is registered.

timer_count

int

Return the count of active timers running in the clock.

Returns :

int

Type :

Clock.timer_count

timer_names

list[str]

Return the names of active timers running in the clock.

Returns :

list[str]

Type :

Clock.timer_names

timestamp ( self ) → double

Return the current UNIX time in seconds.

Returns :

double

References

https://en.wikipedia.org/wiki/Unix_time

timestamp_ms ( self ) → uint64_t

Return the current UNIX time in milliseconds (ms).

Returns :

uint64_t

References

https://en.wikipedia.org/wiki/Unix_time

timestamp_ns ( self ) → uint64_t

Return the current UNIX time in nanoseconds (ns).

Returns :

uint64_t

References

https://en.wikipedia.org/wiki/Unix_time

utc_now ( self ) → datetime

Return the current time (UTC).

Returns :

datetime – The current tz-aware UTC time of the clock.

class LiveClock ( loop : Optional [ asyncio.AbstractEventLoop ] = None )

Bases: Clock

Provides a monotonic clock for live trading.

All times are tz-aware UTC.

Parameters :

loop ( asyncio.AbstractEventLoop ) – The event loop for the clocks timers.

cancel_timer ( self , unicode name ) → void

cancel_timers ( self ) → void

local_now ( self , tzinfo tz=None ) → datetime

Return the current datetime of the clock in the given local timezone.

Parameters :

tz ( tzinfo , optional ) – The local timezone (if None the system local timezone is assumed for the target timezone).

Returns :

datetime – tz-aware in local timezone.

next_time_ns ( self , unicode name ) → uint64_t

register_default_handler ( self , callback : Callable [ [ TimeEvent ] , None ] ) → void

set_time_alert ( self, unicode name, datetime alert_time, callback: Callable[[TimeEvent], None] = None ) → void

Set a time alert for the given time.

When the time is reached the handler will be passed the TimeEvent containing the timers unique name. If no handler is passed then the default handler (if registered) will receive the TimeEvent .

Parameters :

• name ( str ) – The name for the alert (must be unique for this clock).

• alert_time ( datetime ) – The time for the alert.

• callback ( Callable [ [ TimeEvent ] , None ] , optional ) – The callback to receive time events.

Raises :

• ValueError – If name is not a valid string.

• KeyError – If name is not unique for this clock.

• TypeError – If handler is not of type Callable or None .

• ValueError – If handler is None and no default handler is registered.

Warning

If alert_time is in the past or at current time, then an immediate time event will be generated (rather than being invalid and failing a condition check).

set_time_alert_ns ( self, unicode name, uint64_t alert_time_ns, callback: Optional[Callable[[TimeEvent], None]] = None ) → void

set_timer ( self, unicode name, timedelta interval, datetime start_time=None, datetime stop_time=None, callback: Optional[Callable[[TimeEvent], None]] = None ) → void

Set a timer to run.

The timer will run from the start time (optionally until the stop time). When the intervals are reached the handlers will be passed the TimeEvent containing the timers unique name. If no handler is passed then the default handler (if registered) will receive the TimeEvent .

Parameters :

• name ( str ) – The name for the timer (must be unique for this clock).

• interval ( timedelta ) – The time interval for the timer.

• start_time ( datetime , optional ) – The start time for the timer (if None then starts immediately).

• stop_time ( datetime , optional ) – The stop time for the timer (if None then repeats indefinitely).

• callback ( Callable [ [ TimeEvent ] , None ] , optional ) – The callback to receive time events.

Raises :

• ValueError – If name is not a valid string.

• KeyError – If name is not unique for this clock.

• ValueError – If interval is not positive (> 0).

• ValueError – If stop_time is not None and stop_time < time now.

• ValueError – If stop_time is not None and start_time + interval > stop_time .

• TypeError – If handler is not of type Callable or None .

• ValueError – If handler is None and no default handler is registered.

set_timer_ns ( self, unicode name, uint64_t interval_ns, uint64_t start_time_ns, uint64_t stop_time_ns, callback: Optional[Callable[[TimeEvent], None]] = None ) → void

timer_count

int

Type :

LiveClock.timer_count

timer_names

list[str]

Type :

LiveClock.timer_names

timestamp ( self ) → double

timestamp_ms ( self ) → uint64_t

timestamp_ns ( self ) → uint64_t

utc_now ( self ) → datetime

Return the current time (UTC).

Returns :

datetime – The current tz-aware UTC time of the clock.

class TestClock

Bases: Clock

Provides a monotonic clock for backtesting and unit testing.

advance_time ( self , uint64_t to_time_ns , bool set_time=True ) → list

Advance the clocks time to the given to_time_ns .

Parameters :

• to_time_ns ( uint64_t ) – The UNIX time (nanoseconds) to advance the clock to.

• set_time ( bool ) – If the clock should also be set to the given to_time_ns .

Returns :

list[TimeEventHandler] – Sorted chronologically.

Raises :

ValueError – If to_time_ns is < the clocks current time.

cancel_timer ( self , unicode name ) → void

cancel_timers ( self ) → void

local_now ( self , tzinfo tz=None ) → datetime

Return the current datetime of the clock in the given local timezone.

Parameters :

tz ( tzinfo , optional ) – The local timezone (if None the system local timezone is assumed for the target timezone).

Returns :

datetime – tz-aware in local timezone.

next_time_ns ( self , unicode name ) → uint64_t

register_default_handler ( self , callback : Callable [ [ TimeEvent ] , None ] ) → void

set_time ( self , uint64_t to_time_ns ) → void

Set the clocks datetime to the given time (UTC).

Parameters :

to_time_ns ( uint64_t ) – The UNIX time (nanoseconds) to set.

set_time_alert ( self, unicode name, datetime alert_time, callback: Callable[[TimeEvent], None] = None ) → void

Set a time alert for the given time.

When the time is reached the handler will be passed the TimeEvent containing the timers unique name. If no handler is passed then the default handler (if registered) will receive the TimeEvent .

Parameters :

• name ( str ) – The name for the alert (must be unique for this clock).

• alert_time ( datetime ) – The time for the alert.

• callback ( Callable [ [ TimeEvent ] , None ] , optional ) – The callback to receive time events.

Raises :

• ValueError – If name is not a valid string.

• KeyError – If name is not unique for this clock.

• TypeError – If handler is not of type Callable or None .

• ValueError – If handler is None and no default handler is registered.

Warning

If alert_time is in the past or at current time, then an immediate time event will be generated (rather than being invalid and failing a condition check).

set_time_alert_ns ( self, unicode name, uint64_t alert_time_ns, callback: Optional[Callable[[TimeEvent], None]] = None ) → void

set_timer ( self, unicode name, timedelta interval, datetime start_time=None, datetime stop_time=None, callback: Optional[Callable[[TimeEvent], None]] = None ) → void

Set a timer to run.

The timer will run from the start time (optionally until the stop time). When the intervals are reached the handlers will be passed the TimeEvent containing the timers unique name. If no handler is passed then the default handler (if registered) will receive the TimeEvent .

Parameters :

• name ( str ) – The name for the timer (must be unique for this clock).

• interval ( timedelta ) – The time interval for the timer.

• start_time ( datetime , optional ) – The start time for the timer (if None then starts immediately).

• stop_time ( datetime , optional ) – The stop time for the timer (if None then repeats indefinitely).

• callback ( Callable [ [ TimeEvent ] , None ] , optional ) – The callback to receive time events.

Raises :

• ValueError – If name is not a valid string.

• KeyError – If name is not unique for this clock.

• ValueError – If interval is not positive (> 0).

• ValueError – If stop_time is not None and stop_time < time now.

• ValueError – If stop_time is not None and start_time + interval > stop_time .

• TypeError – If handler is not of type Callable or None .

• ValueError – If handler is None and no default handler is registered.

set_timer_ns ( self, unicode name, uint64_t interval_ns, uint64_t start_time_ns, uint64_t stop_time_ns, callback: Optional[Callable[[TimeEvent], None]] = None ) → void

timer_count

int

Type :

TestClock.timer_count

timer_names

list[str]

Type :

TestClock.timer_names

timestamp ( self ) → double

timestamp_ms ( self ) → uint64_t

timestamp_ns ( self ) → uint64_t

utc_now ( self ) → datetime

Return the current time (UTC).

Returns :

datetime – The current tz-aware UTC time of the clock.

Component

class Component ( Clock clock , Logger logger , TraderId trader_id=None , Identifier component_id=None , unicode component_name=None , MessageBus msgbus=None , dict config=None )

Bases: object

The base class for all system components.

A component is not considered initialized until a message bus is registered (this either happens when one is passed to the constructor, or when registered with a trader).

Thus, if the component does not receive a message bus through the constructor, then it will be in a PRE_INITIALIZED state, otherwise if one is passed then it will be in an INITIALIZED state.

Parameters :

• clock ( Clock ) – The clock for the component.

• logger ( Logger ) – The logger for the component.

• trader_id ( TraderId , optional ) – The trader ID associated with the component.

• component_id ( Identifier , optional ) – The component ID. If None is passed then the identifier will be taken from type(self).__name__ .

• component_name ( str , optional ) – The custom component name.

• msgbus ( MessageBus , optional ) – The message bus for the component (required before initialized).

• config ( dict [ str , Any ] , optional ) – The configuration for the component.

Raises :

ValueError – If component_name is not a valid string.

Warning

This class should not be used directly, but through a concrete subclass.

degrade ( self ) → void

Degrade the component.

While executing on_degrade() any exception will be logged and reraised, then the component will remain in a DEGRADING state.

Warning

Do not override.

If the component is not in a valid state from which to execute this method, then the component state will not change, and an error will be logged.

dispose ( self ) → void

Dispose of the component.

While executing on_dispose() any exception will be logged and reraised, then the component will remain in a DISPOSING state.

Warning

Do not override.

If the component is not in a valid state from which to execute this method, then the component state will not change, and an error will be logged.

fault ( self ) → void

Fault the component.

Calling this method multiple times has the same effect as calling it once (it is idempotent). Once called, it cannot be reversed, and no other methods should be called on this instance.

While executing on_fault() any exception will be logged and reraised, then the component will remain in a FAULTING state.

Warning

Do not override.

If the component is not in a valid state from which to execute this method, then the component state will not change, and an error will be logged.

classmethod fully_qualified_name ( cls ) → str

Return the fully qualified name for the components class.

Returns :

str

References

https://www.python.org/dev/peps/pep-3155/

id

The components ID.

Returns :

ComponentId

is_degraded

bool

Return whether the current component state is DEGRADED .

Returns :

bool

Type :

Component.is_degraded

is_disposed

bool

Return whether the current component state is DISPOSED .

Returns :

bool

Type :

Component.is_disposed

is_faulted

bool

Return whether the current component state is FAULTED .

Returns :

bool

Type :

Component.is_faulted

is_initialized

bool

Return whether the component has been initialized (component.state >= INITIALIZED ).

Returns :

bool

Type :

Component.is_initialized

is_running

bool

Return whether the current component state is RUNNING .

Returns :

bool

Type :

Component.is_running

is_stopped

bool

Return whether the current component state is STOPPED .

Returns :

bool

Type :

Component.is_stopped

reset ( self ) → void

Reset the component.

All stateful fields are reset to their initial value.

While executing on_reset() any exception will be logged and reraised, then the component will remain in a RESETTING state.

Warning

Do not override.

If the component is not in a valid state from which to execute this method, then the component state will not change, and an error will be logged.

resume ( self ) → void

Resume the component.

While executing on_resume() any exception will be logged and reraised, then the component will remain in a RESUMING state.

Warning

Do not override.

If the component is not in a valid state from which to execute this method, then the component state will not change, and an error will be logged.

start ( self ) → void

Start the component.

While executing on_start() any exception will be logged and reraised, then the component will remain in a STARTING state.

Warning

Do not override.

If the component is not in a valid state from which to execute this method, then the component state will not change, and an error will be logged.

state

ComponentState

Return the components current state.

Returns :

ComponentState

Type :

Component.state

stop ( self ) → void

Stop the component.

While executing on_stop() any exception will be logged and reraised, then the component will remain in a STOPPING state.

Warning

Do not override.

If the component is not in a valid state from which to execute this method, then the component state will not change, and an error will be logged.

trader_id

The trader ID associated with the component.

Returns :

TraderId

type

The components type.

Returns :

type

class ComponentFSMFactory

Bases: object

Provides a generic component Finite-State Machine.

static get_state_transition_table ( ) → dict

The default state transition table.

Returns :

dict[int, int] – C Enums.

Executor

class TaskId ( value : str )

Bases: object

Represents a unique identifier for a task managed by the ActorExecutor.

This ID can be associated with a task that is either queued for execution or actively executing as an asyncio.Future .

classmethod create ( ) → TaskId

Create and return a new task identifier with a UUID v4 value.

Returns :

TaskId

class ActorExecutor ( loop : AbstractEventLoop , executor : Executor , logger : LoggerAdapter )

Bases: object

Provides an executor for Actor and Strategy classes.

Provides an executor designed to handle asynchronous tasks for Actor and Strategy classes. This custom executor queues and executes tasks within a given event loop and is tailored for single-threaded applications.

The ActorExecutor maintains its internal state to manage both queued and active tasks, providing facilities for scheduling, cancellation, and monitoring. It can be used to create more controlled execution flows within complex asynchronous systems.

Parameters :

• loop ( AbstractEventLoop ) – The event loop for the application.

• executor ( Executor ) – The inner executor to register.

• logger ( LoggerAdatper ) – The logger for the executor.

Warning

This executor is not thread-safe and must be invoked from the same thread in which it was created. Special care should be taken to ensure thread consistency when integrating with multi-threaded applications.

reset ( ) → None

Reset the executor.

This will cancel all queued and active tasks, and drain the internal queue without executing those tasks.

get_future ( task_id : TaskId ) → _asyncio.Future | None

Return the executing Future with the given task_id (if found).

Parameters :

task_id ( TaskId ) – The task identifier for the future.

Returns :

asyncio.Future or None

async shutdown ( ) → None

Shutdown the executor in an async context.

This will cancel the inner worker task.

queue_for_executor ( func : Callable [ [ ... ] , Any ] , * args : Any , ** kwargs : Any ) → TaskId

Enqueue the given func to be executed sequentially.

Parameters :

• func ( Callable ) – The function to be executed.

• args ( positional arguments ) – The positional arguments for the call to func .

• kwargs ( arbitrary keyword arguments ) – The keyword arguments for the call to func .

Returns :

TaskId

run_in_executor ( func : Callable [ [ ... ] , Any ] , * args : Any , ** kwargs : Any ) → TaskId

Arrange for the given func to be called in the executor.

Parameters :

• func ( Callable ) – The function to be executed.

• args ( positional arguments ) – The positional arguments for the call to func .

• kwargs ( arbitrary keyword arguments ) – The keyword arguments for the call to func .

Returns :

TaskId

queued_task_ids ( ) → list [ nautilus_trader.common.executor.TaskId ]

Return the queued task identifiers.

Returns :

list[TaskId]

active_task_ids ( ) → list [ nautilus_trader.common.executor.TaskId ]

Return the active task identifiers.

Returns :

list[TaskId]

has_queued_tasks ( ) → bool

Return a value indicating whether there are any queued tasks.

Returns :

bool

has_active_tasks ( ) → bool

Return a value indicating whether there are any active tasks.

Returns :

bool

cancel_task ( task_id : TaskId ) → None

Cancel the task with the given task_id (if queued or active).

If the task is not found then a warning is logged.

Parameters :

task_id ( TaskId ) – The active task identifier.

cancel_all_tasks ( ) → None

Cancel all active and queued tasks.

class OrderFactory ( TraderId trader_id , StrategyId strategy_id , Clock clock , CacheFacade cache: Optional[CacheFacade] = None , int initial_order_id_count=0 , int initial_order_list_id_count=0 )

Bases: object

A factory class which provides different order types.

The TraderId tag and StrategyId tag will be inserted into all IDs generated.

Parameters :

• trader_id ( TraderId ) – The trader ID (only numerical tag sent to venue).

• strategy_id ( StrategyId ) – The strategy ID (only numerical tag sent to venue).

• clock ( Clock ) – The clock for the factory.

• cache ( CacheFacade , optional ) – The cache facade for the order factory.

• initial_order_id_count ( int , optional ) – The initial order ID count for the factory.

• initial_order_list_id_count ( int , optional ) – The initial order list ID count for the factory.

Raises :

• ValueError – If initial_order_id_count is negative (< 0).

• ValueError – If initial_order_list_id_count is negative (< 0).

bracket ( self , InstrumentId instrument_id , OrderSide order_side , Quantity quantity , Price entry_trigger_price=None , Price entry_price=None , Price sl_trigger_price=None , Price tp_trigger_price=None , Price tp_price=None , OrderType entry_order_type=OrderType.MARKET , OrderType tp_order_type=OrderType.LIMIT , TimeInForce time_in_force=TimeInForce.GTC , datetime expire_time=None , bool entry_post_only=False , bool tp_post_only=True , bool quote_quantity=False , TriggerType emulation_trigger=TriggerType.NO_TRIGGER , InstrumentId trigger_instrument_id=None , ContingencyType contingency_type=ContingencyType.OUO , ExecAlgorithmId entry_exec_algorithm_id=None , ExecAlgorithmId sl_exec_algorithm_id=None , ExecAlgorithmId tp_exec_algorithm_id=None , dict entry_exec_algorithm_params=None , dict tp_exec_algorithm_params=None , dict sl_exec_algorithm_params=None , unicode entry_tags=u'ENTRY' , unicode tp_tags=u'TAKE_PROFIT' , unicode sl_tags=u'STOP_LOSS' ) → OrderList

Create a bracket order with optional entry of take-profit order types.

The stop-loss order will always be STOP_MARKET . The bracketing stop-loss and take-profit orders will have a time in force of GTC .

Parameters :

• instrument_id ( InstrumentId ) – The orders instrument ID.

• order_side (OrderSide { BUY , SELL }) – The entry orders side.

• quantity ( Quantity ) – The entry orders quantity (> 0).

• entry_trigger_price ( Price , optional ) – The entry order trigger price (STOP).

• entry_price ( Price , optional ) – The entry order price (LIMIT).

• sl_trigger_price ( Price , optional ) – The stop-loss child order trigger price (STOP).

• tp_trigger_price ( Price , optional ) – The take-profit child order trigger price (STOP).

• tp_price ( Price , optional ) – The take-profit child order price (LIMIT).

• entry_order_type (OrderType { MARKET , LIMIT , LIMIT_IF_TOUCHED , MARKET_IF_TOUCHED }, default MARKET ) – The entry order type.

• tp_order_type (OrderType { LIMIT , LIMIT_IF_TOUCHED , MARKET_IF_TOUCHED }, default LIMIT ) – The take-profit order type.

• time_in_force (TimeInForce { DAY , GTC }, optional) – The entry orders time in force.

• expire_time ( datetime , optional ) – The order expiration (for GTD orders).

• entry_post_only ( bool , default False ) – If the entry order will only provide liquidity (make a market).

• tp_post_only ( bool , default False ) – If the take-profit order will only provide liquidity (make a market).

• quote_quantity ( bool ) – If order quantity is denominated in the quote currency.

• emulation_trigger (TriggerType, default NO_TRIGGER ) – The emulation trigger type for the entry, as well as the TP and SL bracket orders.

• trigger_instrument_id ( InstrumentId , optional ) – The emulation trigger instrument ID for the order (if None then will be the instrument_id ).

• contingency_type (ContingencyType, default OUO ) – The contingency type for the TP and SL bracket orders.

• entry_exec_algorithm_id ( ExecAlgorithmId , optional ) – The entry order execution algorithm ID.

• sl_exec_algorithm_id ( ExecAlgorithmId , optional ) – The stop-loss order execution algorithm ID.

• tp_exec_algorithm_id ( ExecAlgorithmId , optional ) – The take-profit order execution algorithm ID.

• entry_exec_algorithm_params ( dict [ str , Any ] , optional ) – The execution algorithm parameters for the order.

• tp_exec_algorithm_params ( dict [ str , Any ] , optional ) – The execution algorithm parameters for the order.

• sl_exec_algorithm_params ( dict [ str , Any ] , optional ) – The execution algorithm parameters for the order.

• entry_tags ( str , default "ENTRY" ) – The custom user tags for the entry order. These are optional and can contain any arbitrary delimiter if required.

• tp_tags ( str , default "TAKE_PROFIT" ) – The custom user tags for the take-profit order. These are optional and can contain any arbitrary delimiter if required.

• sl_tags ( str , default "STOP_LOSS" ) – The custom user tags for the stop-loss order. These are optional and can contain any arbitrary delimiter if required.

Returns :

OrderList

create_list ( self , list orders ) → OrderList

Return a new order list containing the given orders .

Parameters :

orders ( list [ Order ] ) – The orders for the list.

Returns :

OrderList

Raises :

ValueError – If orders is empty.

Notes

The order at index 0 in the list will be considered the ‘first’ order.

generate_client_order_id ( self ) → ClientOrderId

Generate and return a new client order ID.

The identifier will be the next in the logical sequence.

Returns :

ClientOrderId

generate_order_list_id ( self ) → OrderListId

Generate and return a new order list ID.

The identifier will be the next in the logical sequence.

Returns :

OrderListId

limit ( self , InstrumentId instrument_id , OrderSide order_side , Quantity quantity , Price price , TimeInForce time_in_force=TimeInForce.GTC , datetime expire_time=None , bool post_only=False , bool reduce_only=False , bool quote_quantity=False , Quantity display_qty=None , TriggerType emulation_trigger=TriggerType.NO_TRIGGER , InstrumentId trigger_instrument_id=None , ExecAlgorithmId exec_algorithm_id=None , dict exec_algorithm_params=None , unicode tags=None ) → LimitOrder

Create a new LIMIT order.

Parameters :

• instrument_id ( InstrumentId ) – The orders instrument ID.

• order_side (OrderSide { BUY , SELL }) – The orders side.

• quantity ( Quantity ) – The orders quantity (> 0).

• price ( Price ) – The orders price.

• time_in_force (TimeInForce { GTC , IOC , FOK , GTD , DAY , AT_THE_OPEN , AT_THE_CLOSE }, default GTC ) – The orders time in force.

• expire_time ( datetime , optional ) – The order expiration (for GTD orders).

• post_only ( bool , default False ) – If the order will only provide liquidity (make a market).

• reduce_only ( bool , default False ) – If the order carries the ‘reduce-only’ execution instruction.

• quote_quantity ( bool ) – If the order quantity is denominated in the quote currency.

• display_qty ( Quantity , optional ) – The quantity of the order to display on the public book (iceberg).

• emulation_trigger (TriggerType, default NO_TRIGGER ) – The orders emulation trigger.

• trigger_instrument_id ( InstrumentId , optional ) – The emulation trigger instrument ID for the order (if None then will be the instrument_id ).

• exec_algorithm_id ( ExecAlgorithmId , optional ) – The execution algorithm ID for the order.

• exec_algorithm_params ( dict [ str , Any ] , optional ) – The execution algorithm parameters for the order.

• tags ( str , optional ) – The custom user tags for the order. These are optional and can contain any arbitrary delimiter if required.

Returns :

LimitOrder

Raises :

• ValueError – If quantity is not positive (> 0).

• ValueError – If time_in_force is GTD and expire_time <= UNIX epoch.

• ValueError – If display_qty is negative (< 0) or greater than quantity .

limit_if_touched ( self , InstrumentId instrument_id , OrderSide order_side , Quantity quantity , Price price , Price trigger_price , TriggerType trigger_type=TriggerType.DEFAULT , TimeInForce time_in_force=TimeInForce.GTC , datetime expire_time=None , bool post_only=False , bool reduce_only=False , bool quote_quantity=False , Quantity display_qty=None , TriggerType emulation_trigger=TriggerType.NO_TRIGGER , InstrumentId trigger_instrument_id=None , ExecAlgorithmId exec_algorithm_id=None , dict exec_algorithm_params=None , unicode tags=None ) → LimitIfTouchedOrder

Create a new LIMIT_IF_TOUCHED (LIT) conditional order.

Parameters :

• instrument_id ( InstrumentId ) – The orders instrument ID.

• order_side (OrderSide { BUY , SELL }) – The orders side.

• quantity ( Quantity ) – The orders quantity (> 0).

• price ( Price ) – The orders limit price.

• trigger_price ( Price ) – The orders trigger stop price.

• trigger_type (TriggerType, default DEFAULT ) – The order trigger type.

• time_in_force (TimeInForce { GTC , IOC , FOK , GTD , DAY }, default GTC ) – The orders time in force.

• expire_time ( datetime , optional ) – The order expiration (for GTD orders).

• post_only ( bool , default False ) – If the order will only provide liquidity (make a market).

• reduce_only ( bool , default False ) – If the order carries the ‘reduce-only’ execution instruction.

• quote_quantity ( bool ) – If the order quantity is denominated in the quote currency.

• display_qty ( Quantity , optional ) – The quantity of the order to display on the public book (iceberg).

• emulation_trigger (TriggerType, default NO_TRIGGER ) – The orders emulation trigger.

• trigger_instrument_id ( InstrumentId , optional ) – The emulation trigger instrument ID for the order (if None then will be the instrument_id ).

• exec_algorithm_id ( ExecAlgorithmId , optional ) – The execution algorithm ID for the order.

• exec_algorithm_params ( dict [ str , Any ] , optional ) – The execution algorithm parameters for the order.

• tags ( str , optional ) – The custom user tags for the order. These are optional and can contain any arbitrary delimiter if required.

Returns :

LimitIfTouchedOrder

Raises :

• ValueError – If quantity is not positive (> 0).

• ValueError – If trigger_type is NO_TRIGGER .

• ValueError – If time_in_force is AT_THE_OPEN or AT_THE_CLOSE .

• ValueError – If time_in_force is GTD and expire_time <= UNIX epoch.

• ValueError – If display_qty is negative (< 0) or greater than quantity .

market ( self , InstrumentId instrument_id , OrderSide order_side , Quantity quantity , TimeInForce time_in_force=TimeInForce.GTC , bool reduce_only=False , bool quote_quantity=False , ExecAlgorithmId exec_algorithm_id=None , dict exec_algorithm_params=None , unicode tags=None ) → MarketOrder

Create a new MARKET order.

Parameters :

• instrument_id ( InstrumentId ) – The orders instrument ID.

• order_side (OrderSide { BUY , SELL }) – The orders side.

• quantity ( Quantity ) – The orders quantity (> 0).

• time_in_force (TimeInForce { GTC , IOC , FOK , DAY , AT_THE_OPEN , AT_THE_CLOSE }, default GTC ) – The orders time in force. Often not applicable for market orders.

• reduce_only ( bool , default False ) – If the order carries the ‘reduce-only’ execution instruction.

• quote_quantity ( bool ) – If the order quantity is denominated in the quote currency.

• exec_algorithm_id ( ExecAlgorithmId , optional ) – The execution algorithm ID for the order.

• exec_algorithm_params ( dict [ str , Any ] , optional ) – The execution algorithm parameters for the order.

• tags ( str , optional ) – The custom user tags for the order. These are optional and can contain any arbitrary delimiter if required.

Returns :

MarketOrder

Raises :

• ValueError – If quantity is not positive (> 0).

• ValueError – If time_in_force is GTD .

market_if_touched ( self , InstrumentId instrument_id , OrderSide order_side , Quantity quantity , Price trigger_price , TriggerType trigger_type=TriggerType.DEFAULT , TimeInForce time_in_force=TimeInForce.GTC , datetime expire_time=None , bool reduce_only=False , bool quote_quantity=False , TriggerType emulation_trigger=TriggerType.NO_TRIGGER , InstrumentId trigger_instrument_id=None , ExecAlgorithmId exec_algorithm_id=None , dict exec_algorithm_params=None , unicode tags=None ) → MarketIfTouchedOrder

Create a new MARKET_IF_TOUCHED (MIT) conditional order.

Parameters :

• instrument_id ( InstrumentId ) – The orders instrument ID.

• order_side (OrderSide { BUY , SELL }) – The orders side.

• quantity ( Quantity ) – The orders quantity (> 0).

• trigger_price ( Price ) – The orders trigger price (STOP).

• trigger_type (TriggerType, default DEFAULT ) – The order trigger type.

• time_in_force (TimeInForce { GTC , IOC , FOK , GTD , DAY }, default GTC ) – The orders time in force.

• expire_time ( datetime , optional ) – The order expiration (for GTD orders).

• reduce_only ( bool , default False ) – If the order carries the ‘reduce-only’ execution instruction.

• quote_quantity ( bool ) – If the order quantity is denominated in the quote currency.

• emulation_trigger (TriggerType, default NO_TRIGGER ) – The orders emulation trigger.

• trigger_instrument_id ( InstrumentId , optional ) – The emulation trigger instrument ID for the order (if None then will be the instrument_id ).

• exec_algorithm_id ( ExecAlgorithmId , optional ) – The execution algorithm ID for the order.

• exec_algorithm_params ( dict [ str , Any ] , optional ) – The execution algorithm parameters for the order.

• tags ( str , optional ) – The custom user tags for the order. These are optional and can contain any arbitrary delimiter if required.

Returns :

MarketIfTouchedOrder

Raises :

• ValueError – If quantity is not positive (> 0).

• ValueError – If trigger_type is NO_TRIGGER .

• ValueError – If time_in_force is AT_THE_OPEN or AT_THE_CLOSE .

• ValueError – If time_in_force is GTD and expire_time <= UNIX epoch.

market_to_limit ( self , InstrumentId instrument_id , OrderSide order_side , Quantity quantity , TimeInForce time_in_force=TimeInForce.GTC , datetime expire_time=None , bool reduce_only=False , bool quote_quantity=False , Quantity display_qty=None , ExecAlgorithmId exec_algorithm_id=None , dict exec_algorithm_params=None , unicode tags=None ) → MarketToLimitOrder

Create a new MARKET order.

Parameters :

• instrument_id ( InstrumentId ) – The orders instrument ID.

• order_side (OrderSide { BUY , SELL }) – The orders side.

• quantity ( Quantity ) – The orders quantity (> 0).

• time_in_force (TimeInForce { GTC , GTD , IOC , FOK }, default GTC ) – The orders time in force.

• expire_time ( datetime , optional ) – The order expiration (for GTD orders).

• reduce_only ( bool , default False ) – If the order carries the ‘reduce-only’ execution instruction.

• quote_quantity ( bool ) – If the order quantity is denominated in the quote currency.

• display_qty ( Quantity , optional ) – The quantity of the limit order to display on the public book (iceberg).

• exec_algorithm_id ( ExecAlgorithmId , optional ) – The execution algorithm ID for the order.

• exec_algorithm_params ( dict [ str , Any ] , optional ) – The execution algorithm parameters for the order.

• tags ( str , optional ) – The custom user tags for the order. These are optional and can contain any arbitrary delimiter if required.

Returns :

MarketToLimitOrder

Raises :

• ValueError – If quantity is not positive (> 0).

• ValueError – If time_in_force is AT_THE_OPEN or AT_THE_CLOSE .

reset ( self ) → void

Reset the order factory.

All stateful fields are reset to their initial value.

set_client_order_id_count ( self , int count ) → void

Set the internal order ID generator count to the given count.

Parameters :

count ( int ) – The count to set.

Warning

System method (not intended to be called by user code).

set_order_list_id_count ( self , int count ) → void

Set the internal order list ID generator count to the given count.

Parameters :

count ( int ) – The count to set.

Warning

System method (not intended to be called by user code).

stop_limit ( self , InstrumentId instrument_id , OrderSide order_side , Quantity quantity , Price price , Price trigger_price , TriggerType trigger_type=TriggerType.DEFAULT , TimeInForce time_in_force=TimeInForce.GTC , datetime expire_time=None , bool post_only=False , bool reduce_only=False , bool quote_quantity=False , Quantity display_qty=None , TriggerType emulation_trigger=TriggerType.NO_TRIGGER , InstrumentId trigger_instrument_id=None , ExecAlgorithmId exec_algorithm_id=None , dict exec_algorithm_params=None , unicode tags=None ) → StopLimitOrder

Create a new STOP_LIMIT conditional order.

Parameters :

• instrument_id ( InstrumentId ) – The orders instrument ID.

• order_side (OrderSide { BUY , SELL }) – The orders side.

• quantity ( Quantity ) – The orders quantity (> 0).

• price ( Price ) – The orders limit price.

• trigger_price ( Price ) – The orders trigger stop price.

• trigger_type (TriggerType, default DEFAULT ) – The order trigger type.

• time_in_force (TimeInForce { GTC , IOC , FOK , GTD , DAY }, default GTC ) – The orders time in force.

• expire_time ( datetime , optional ) – The order expiration (for GTD orders).

• post_only ( bool , default False ) – If the order will only provide liquidity (make a market).

• reduce_only ( bool , default False ) – If the order carries the ‘reduce-only’ execution instruction.

• quote_quantity ( bool ) – If the order quantity is denominated in the quote currency.

• display_qty ( Quantity , optional ) – The quantity of the order to display on the public book (iceberg).

• emulation_trigger (TriggerType, default NO_TRIGGER ) – The orders emulation trigger.

• trigger_instrument_id ( InstrumentId , optional ) – The emulation trigger instrument ID for the order (if None then will be the instrument_id ).

• exec_algorithm_id ( ExecAlgorithmId , optional ) – The execution algorithm ID for the order.

• exec_algorithm_params ( dict [ str , Any ] , optional ) – The execution algorithm parameters for the order.

• tags ( str , optional ) – The custom user tags for the order. These are optional and can contain any arbitrary delimiter if required.

Returns :

StopLimitOrder

Raises :

• ValueError – If quantity is not positive (> 0).

• ValueError – If trigger_type is NO_TRIGGER .

• ValueError – If time_in_force is AT_THE_OPEN or AT_THE_CLOSE .

• ValueError – If time_in_force is GTD and expire_time <= UNIX epoch.

• ValueError – If display_qty is negative (< 0) or greater than quantity .

stop_market ( self , InstrumentId instrument_id , OrderSide order_side , Quantity quantity , Price trigger_price , TriggerType trigger_type=TriggerType.DEFAULT , TimeInForce time_in_force=TimeInForce.GTC , datetime expire_time=None , bool reduce_only=False , bool quote_quantity=False , TriggerType emulation_trigger=TriggerType.NO_TRIGGER , InstrumentId trigger_instrument_id=None , ExecAlgorithmId exec_algorithm_id=None , dict exec_algorithm_params=None , unicode tags=None ) → StopMarketOrder

Create a new STOP_MARKET conditional order.

Parameters :

• instrument_id ( InstrumentId ) – The orders instrument ID.

• order_side (OrderSide { BUY , SELL }) – The orders side.

• quantity ( Quantity ) – The orders quantity (> 0).

• trigger_price ( Price ) – The orders trigger price (STOP).

• trigger_type (TriggerType, default DEFAULT ) – The order trigger type.

• time_in_force (TimeInForce { GTC , IOC , FOK , GTD , DAY }, default GTC ) – The orders time in force.

• expire_time ( datetime , optional ) – The order expiration (for GTD orders).

• reduce_only ( bool , default False ) – If the order carries the ‘reduce-only’ execution instruction.

• quote_quantity ( bool ) – If the order quantity is denominated in the quote currency.

• emulation_trigger (TriggerType, default NO_TRIGGER ) – The orders emulation trigger.

• trigger_instrument_id ( InstrumentId , optional ) – The emulation trigger instrument ID for the order (if None then will be the instrument_id ).

• exec_algorithm_id ( ExecAlgorithmId , optional ) – The execution algorithm ID for the order.

• exec_algorithm_params ( dict [ str , Any ] , optional ) – The execution algorithm parameters for the order.

• tags ( str , optional ) – The custom user tags for the order. These are optional and can contain any arbitrary delimiter if required.

Returns :

StopMarketOrder

Raises :

• ValueError – If quantity is not positive (> 0).

• ValueError – If trigger_type is NO_TRIGGER .

• ValueError – If time_in_force is AT_THE_OPEN or AT_THE_CLOSE .

• ValueError – If time_in_force is GTD and expire_time <= UNIX epoch.

strategy_id

The order factories trading strategy ID.

Returns :

StrategyId

trader_id

The order factories trader ID.

Returns :

TraderId

trailing_stop_limit ( self , InstrumentId instrument_id , OrderSide order_side , Quantity quantity , limit_offset: Decimal , trailing_offset: Decimal , Price price=None , Price trigger_price=None , TriggerType trigger_type=TriggerType.DEFAULT , TrailingOffsetType trailing_offset_type=TrailingOffsetType.PRICE , TimeInForce time_in_force=TimeInForce.GTC , datetime expire_time=None , bool post_only=False , bool reduce_only=False , bool quote_quantity=False , Quantity display_qty=None , TriggerType emulation_trigger=TriggerType.NO_TRIGGER , InstrumentId trigger_instrument_id=None , ExecAlgorithmId exec_algorithm_id=None , dict exec_algorithm_params=None , unicode tags=None ) → TrailingStopLimitOrder

Create a new TRAILING_STOP_LIMIT conditional order.

Parameters :

• instrument_id ( InstrumentId ) – The orders instrument ID.

• order_side (OrderSide { BUY , SELL }) – The orders side.

• quantity ( Quantity ) – The orders quantity (> 0).

• trailing_offset ( Decimal ) – The trailing offset for the trigger price (STOP).

• limit_offset ( Decimal ) – The trailing offset for the order price (LIMIT).

• price ( Price , optional ) – The order price (LIMIT). If None then will typically default to the delta of market price and limit_offset .

• trigger_price ( Price , optional ) – The order trigger price (STOP). If None then will typically default to the delta of market price and trailing_offset .

• trigger_type (TriggerType, default DEFAULT ) – The order trigger type.

• trailing_offset_type (TrailingOffsetType, default PRICE ) – The order trailing offset type.

• time_in_force (TimeInForce { GTC , IOC , FOK , GTD , DAY }, default GTC ) – The orders time in force.

• expire_time ( datetime , optional ) – The order expiration (for GTD orders).

• post_only ( bool , default False ) – If the order will only provide liquidity (make a market).

• reduce_only ( bool , default False ) – If the order carries the ‘reduce-only’ execution instruction.

• quote_quantity ( bool ) – If the order quantity is denominated in the quote currency.

• display_qty ( Quantity , optional ) – The quantity of the order to display on the public book (iceberg).

• emulation_trigger (TriggerType, default NO_TRIGGER ) – The orders emulation trigger.

• trigger_instrument_id ( InstrumentId , optional ) – The emulation trigger instrument ID for the order (if None then will be the instrument_id ).

• exec_algorithm_id ( ExecAlgorithmId , optional ) – The execution algorithm ID for the order.

• exec_algorithm_params ( dict [ str , Any ] , optional ) – The execution algorithm parameters for the order.

• tags ( str , optional ) – The custom user tags for the order. These are optional and can contain any arbitrary delimiter if required.

Returns :

TrailingStopLimitOrder

Raises :

• ValueError – If quantity is not positive (> 0).

• ValueError – If trigger_type is NO_TRIGGER .

• ValueError – If trailing_offset_type is NO_TRAILING_OFFSET .

• ValueError – If time_in_force is AT_THE_OPEN or AT_THE_CLOSE .

• ValueError – If time_in_force is GTD and expire_time <= UNIX epoch.

• ValueError – If display_qty is negative (< 0) or greater than quantity .

trailing_stop_market ( self , InstrumentId instrument_id , OrderSide order_side , Quantity quantity , trailing_offset: Decimal , Price trigger_price=None , TriggerType trigger_type=TriggerType.DEFAULT , TrailingOffsetType trailing_offset_type=TrailingOffsetType.PRICE , TimeInForce time_in_force=TimeInForce.GTC , datetime expire_time=None , bool reduce_only=False , bool quote_quantity=False , TriggerType emulation_trigger=TriggerType.NO_TRIGGER , InstrumentId trigger_instrument_id=None , ExecAlgorithmId exec_algorithm_id=None , dict exec_algorithm_params=None , unicode tags=None ) → TrailingStopMarketOrder

Create a new TRAILING_STOP_MARKET conditional order.

Parameters :

• instrument_id ( InstrumentId ) – The orders instrument ID.

• order_side (OrderSide { BUY , SELL }) – The orders side.

• quantity ( Quantity ) – The orders quantity (> 0).

• trailing_offset ( Decimal ) – The trailing offset for the trigger price (STOP).

• trigger_price ( Price , optional ) – The order trigger price (STOP). If None then will typically default to the delta of market price and trailing_offset .

• trigger_type (TriggerType, default DEFAULT ) – The order trigger type.

• trailing_offset_type (TrailingOffsetType, default PRICE ) – The order trailing offset type.

• time_in_force (TimeInForce { GTC , IOC , FOK , GTD , DAY }, default GTC ) – The orders time in force.

• expire_time ( datetime , optional ) – The order expiration (for GTD orders).

• reduce_only ( bool , default False ) – If the order carries the ‘reduce-only’ execution instruction.

• quote_quantity ( bool ) – If the order quantity is denominated in the quote currency.

• emulation_trigger (TriggerType, default NO_TRIGGER ) – The orders emulation trigger.

• exec_algorithm_id ( ExecAlgorithmId , optional ) – The execution algorithm ID for the order.

• exec_algorithm_params ( dict [ str , Any ] , optional ) – The execution algorithm parameters for the order.

• tags ( str , optional ) – The custom user tags for the order. These are optional and can contain any arbitrary delimiter if required.

Returns :

TrailingStopMarketOrder

Raises :

• ValueError – If quantity is not positive (> 0).

• ValueError – If trigger_type is NO_TRIGGER .

• ValueError – If trailing_offset_type is NO_TRAILING_OFFSET .

• ValueError – If time_in_force is AT_THE_OPEN or AT_THE_CLOSE .

• ValueError – If time_in_force is GTD and expire_time <= UNIX epoch.

Generators

class ClientOrderIdGenerator ( TraderId trader_id , StrategyId strategy_id , Clock clock , int initial_count=0 )

Bases: IdentifierGenerator

Provides a generator for unique ` ClientOrderId`(s).

Parameters :

• trader_id ( TraderId ) – The trader ID for the generator.

• strategy_id ( StrategyId ) – The strategy ID for the generator.

• clock ( Clock ) – The clock for the generator.

• initial_count ( int ) – The initial count for the generator.

Raises :

ValueError – If initial_count is negative (< 0).

count

The count of IDs generated.

Returns :

int

generate ( self ) → ClientOrderId

Return a unique client order ID.

Returns :

ClientOrderId

reset ( self ) → void

Reset the ID generator.

All stateful fields are reset to their initial value.

set_count ( self , int count ) → void

Set the internal counter to the given count.

Parameters :

count ( int ) – The count to set.

class IdentifierGenerator ( TraderId trader_id , Clock clock )

Bases: object

Provides a generator for unique ID strings.

Parameters :

• trader_id ( TraderId ) – The ID tag for the trader.

• clock ( Clock ) – The internal clock.

class OrderListIdGenerator ( TraderId trader_id , StrategyId strategy_id , Clock clock , int initial_count=0 )

Bases: IdentifierGenerator

Provides a generator for unique ` OrderListId`(s).

Parameters :

• trader_id ( TraderId ) – The trader ID for the generator.

• strategy_id ( StrategyId ) – The strategy ID for the generator.

• clock ( Clock ) – The clock for the generator.

• initial_count ( int ) – The initial count for the generator.

Raises :

ValueError – If initial_count is negative (< 0).

count

The count of IDs generated.

Returns :

int

generate ( self ) → OrderListId

Return a unique order list ID.

Returns :

OrderListId

reset ( self ) → void

Reset the ID generator.

All stateful fields are reset to their initial value.

set_count ( self , int count ) → void

Set the internal counter to the given count.

Parameters :

count ( int ) – The count to set.

class PositionIdGenerator ( TraderId trader_id , Clock clock )

Bases: IdentifierGenerator

Provides a generator for unique PositionId(s).

Parameters :

trader_id ( TraderId ) – The trader ID tag for the generator.

generate ( self , StrategyId strategy_id , bool flipped=False ) → PositionId

Return a unique position ID.

Parameters :

• strategy_id ( StrategyId ) – The strategy ID associated with the position.

• flipped ( bool ) – If the position is being flipped. If True then the generated id will be appended with ‘F’.

Returns :

PositionId

get_count ( self , StrategyId strategy_id ) → int

Return the internal position count for the given strategy ID.

Parameters :

strategy_id ( StrategyId ) – The strategy ID associated with the count.

Returns :

int

reset ( self ) → void

Reset the ID generator.

All stateful fields are reset to their initial value.

set_count ( self , StrategyId strategy_id , int count ) → void

Set the internal position count for the given strategy ID.

Parameters :

• strategy_id ( StrategyId ) – The strategy ID associated with the count.

• count ( int ) – The count to set.

Raises :

ValueError – If count is negative (< 0).

Logging

class Logger ( Clock clock , TraderId trader_id=None , unicode machine_id=None , UUID4 instance_id=None , LogLevel level_stdout=LogLevel.INFO , LogLevel level_file=LogLevel.DEBUG , bool file_logging=False , unicode directory=None , unicode file_name=None , unicode file_format=None , dict component_levels: dict[ComponentId , LogLevel] = None , bool bypass=False , bool dummy=False )

Bases: object

Provides a high-performance logger.

Parameters :

• clock ( Clock ) – The clock for the logger.

• trader_id ( TraderId , optional ) – The trader ID for the logger.

• machine_id ( str , optional ) – The machine ID.

• instance_id ( UUID4 , optional ) – The instance ID.

• level_stdout (LogLevel, default INFO ) – The minimum log level to write to stdout.

• level_file (LogLevel, default DEBUG ) – The minimum log level to write to a file.

• file_logging ( bool , default False ) – If logging to a file is enabled.

• directory ( str , optional ) – The path to the log file directory. If None then will write to the current working directory.

• file_name ( str , optional ) – The custom log file name (will use a ‘.log’ suffix for plain text or ‘.json’ for JSON). If None will not log to a file (unless file_auto is True).

• file_format ( str { 'JSON' } , optional ) – The log file format. If None (default) then will log in plain text. If set to ‘JSON’ then logs will be in JSON format.

• component_levels ( dict [ ComponentId , LogLevel ] ) – The additional per component log level filters, where keys are component IDs (e.g. actor/strategy IDs) and values are log levels.

• bypass ( bool , default False ) – If the log output is bypassed.

• dummy ( bool , default False ) – If logger is a ‘dummy’ logger (intended as a placeholder during initialization).

change_clock ( self , Clock clock ) → void

Change the loggers internal clock to the given clock.

Parameters :

clock ( Clock ) –

instance_id

UUID4

Return the loggers system instance ID.

Returns :

UUID4

Type :

Logger.instance_id

is_bypassed

bool

Return whether the logger is in bypass mode.

Returns :

bool

Type :

Logger.is_bypassed

machine_id

str

Return the loggers machine ID.

Returns :

str

Type :

Logger.machine_id

trader_id

TraderId

Return the loggers trader ID.

Returns :

TraderId

Type :

Logger.trader_id

class LoggerAdapter ( unicode component_name , Logger logger )

Bases: object

Provides an adapter for a components logger.

Parameters :

• component_name ( str ) – The name of the component.

• logger ( Logger ) – The logger for the component.

component

str

Return the loggers component name.

Returns :

str

Type :

LoggerAdapter.component

critical ( self , unicode message , LogColor color=LogColor.RED , dict annotations=None ) → void

Log the given critical message with the logger.

Parameters :

• message ( str ) – The log message content.

• color ( LogColor , optional ) – The log message color.

• annotations ( dict [ str , object ] , optional ) – The annotations for the log record.

debug ( self , unicode message , LogColor color=LogColor.NORMAL , dict annotations=None ) → void

Log the given debug message with the logger.

Parameters :

• message ( str ) – The log message content.

• color ( LogColor , optional ) – The log message color.

• annotations ( dict [ str , object ] , optional ) – The annotations for the log record.

error ( self , unicode message , LogColor color=LogColor.RED , dict annotations=None ) → void

Log the given error message with the logger.

Parameters :

• message ( str ) – The log message content.

• color ( LogColor , optional ) – The log message color.

• annotations ( dict [ str , object ] , optional ) – The annotations for the log record.

exception ( self , unicode message , ex , dict annotations=None ) → void

Log the given exception including stack trace information.

Parameters :

• message ( str ) – The log message content.

• ex ( Exception ) – The exception to log.

• annotations ( dict [ str , object ] , optional ) – The annotations for the log record.

get_logger ( self ) → Logger

Return the encapsulated logger.

Returns :

Logger

info ( self , unicode message , LogColor color=LogColor.NORMAL , dict annotations=None ) → void

Log the given information message with the logger.

Parameters :

• message ( str ) – The log message content.

• color ( LogColor , optional ) – The log message color.

• annotations ( dict [ str , object ] , optional ) – The annotations for the log record.

instance_id

UUID4

Return the loggers system instance ID.

Returns :

UUID4

Type :

LoggerAdapter.instance_id

is_bypassed

str

Return whether the logger is in bypass mode.

Returns :

str

Type :

LoggerAdapter.is_bypassed

machine_id

str

Return the loggers machine ID.

Returns :

str

Type :

LoggerAdapter.machine_id

trader_id

TraderId

Return the loggers trader ID.

Returns :

TraderId

Type :

LoggerAdapter.trader_id

warning ( self , unicode message , LogColor color=LogColor.YELLOW , dict annotations=None ) → void

Log the given warning message with the logger.

Parameters :

• message ( str ) – The log message content.

• color ( LogColor , optional ) – The log message color.

• annotations ( dict [ str , object ] , optional ) – The annotations for the log record.

log_memory ( LoggerAdapter logger ) → void

nautilus_header ( LoggerAdapter logger ) → void

class InstrumentProvider ( venue : Venue , logger : Logger , config : nautilus_trader.config.common.InstrumentProviderConfig | None = None )

Bases: object

The base class for all instrument providers.

Parameters :

• venue ( Venue ) – The venue for the provider.

• logger ( Logger ) – The logger for the provider.

• config ( InstrumentProviderConfig , optional ) – The instrument provider config.

Warning

This class should not be used directly, but through a concrete subclass.

property venue : Venue

Return the providers venue.

Returns :

Venue

property count : int

Return the count of instruments held by the provider.

Returns :

int

async load_all_async ( filters : dict | None = None ) → None

Load the latest instruments into the provider asynchronously, optionally applying the given filters.

async load_ids_async ( instrument_ids : list [ nautilus_trader.model.identifiers.InstrumentId ] , filters : dict | None = None ) → None

Load the instruments for the given IDs into the provider, optionally applying the given filters.

Parameters :

• instrument_ids ( list [ InstrumentId ] ) – The instrument IDs to load.

• filters ( dict , optional ) – The venue specific instrument loading filters to apply.

Raises :

ValueError – If any instrument_id.venue is not equal to self.venue .

async load_async ( instrument_id : InstrumentId , filters : dict | None = None ) → None

Load the instrument for the given ID into the provider asynchronously, optionally applying the given filters.

Parameters :

• instrument_id ( InstrumentId ) – The instrument ID to load.

• filters ( dict , optional ) – The venue specific instrument loading filters to apply.

Raises :

ValueError – If instrument_id.venue is not equal to self.venue .

async initialize ( ) → None

Initialize the instrument provider.

If initialize() then will immediately return.

load_all ( filters : dict | None = None ) → None

Load the latest instruments into the provider, optionally applying the given filters.

Parameters :

filters ( dict , optional ) – The venue specific instrument loading filters to apply.

load_ids ( instrument_ids : list [