Reality Modeling
Brokerage Message Handler
Introduction
When your brokerage sends a message, you receive this information in the algorithm and can take any actions. When you place an order through your brokerage platform instead of placing it through LEAN, you can decide whether the transaction handler should process the order. By default, the transaction handler only process orders that you place through LEAN. Custom brokerage message handlers enable you to instruct the transaction handler to process orders that you create directly through your brokerage's platform.
Default Behavior
The default brokerage message handler is the DefaultBrokerageMessageHandler
. The following table describes how the DefaultBrokerageMessageHandler
processes brokerage messages:
Brokerage Message Type | Action |
---|---|
BrokerageMessageType.InformationINFORMATION | Sends a debug message for the algorithm. |
BrokerageMessageType.WarningWARNING | Sends an error message for the algorithm. |
BrokerageMessageType.ErrorERROR | Sets the algorithm runtime error and stops it. |
BrokerageMessageType.DisconnectDISCONNECT | Stops the algorithm after 15 minutes if the market is open. Otherwise, it stops five minutes after market open. |
BrokerageMessageType.ReconnectRECONNECT | Cancels the disconnection process. |
The default brokerage message handler rejects orders you create through the brokerage. An example of this is when you place an order using the brokerage website or a third-party software.
The following table describes the arguments the model accepts:
Argument | Data Type | Description | Default Value |
---|---|---|---|
algorithm algorithm | IAlgorithm | The running algorithm. | |
initialDelay initial_delay | TimeSpan? timedelta/NoneType | The amount of time LEAN will wait after a brokerage disconnection message for a reconnection message. If the reconnection message doesn't arrive before the time limit, LEAN stops running. If you don't provide a value, it uses TimeSpan.FromMinutes(15) timedelta(minutes=15) . | null None |
openThreshold open_threshold | TimeSpan? timedelta/NoneType | Defines how long before market open to re-check for brokerage reconnect message. If you don't provide a value, it uses TimeSpan.FromMinutes(5) timedelta(minutes=5) . | null None |
To view the implementation of this model, see the LEAN GitHub repository.
Model Structure
Brokerage message handlers extend the DefaultBrokerageMessageHandler
class.
Extensions of the DefaultBrokerageMessageHandler
class should define the HandleMessage
handle_message
and HandleOrder
handle_order
methods.
The HandleMessage
handle_message
method processes the brokerage message event. It triggers any actions in the algorithm or notifications system required.
The HandleOrder
handle_order
method defines whether the transaction handler should process a new order you placed directly through the brokerage's website or third-party software.
// In the Initialize method, set the brokerage message handler SetBrokerageMessageHandler(new MyBrokerageMessageHandler(this)); // Define the custom brokerage message handler public class MyBrokerageMessageHandler : DefaultBrokerageMessageHandler { private readonly IAlgorithm _algorithm; public MyBrokerageMessageHandler(IAlgorithm algorithm) : base(algorithm) { _algorithm = algorithm; } public void HandleMessage(BrokerageMessageEvent message) { _algorithm.Debug($"{_algorithm.Time.ToStringInvariant("o")} Event: {message.Message}"); } public bool HandleOrder(NewBrokerageOrderNotificationEventArgs eventArgs) { return false; } }
# In the Initialize method, set the brokerage message handler self.set_brokerage_message_handler(MyBrokerageMessageHandler(self)) # Define the custom brokerage message handler class MyBrokerageMessageHandler(DefaultBrokerageMessageHandler): def __init__(self, algorithm): self._algorithm = algorithm def handle_message(self, message: BrokerageMessageEvent) -> None: self._algorithm.debug(f"{self._algorithm.time} Event: {message.message}") def handle_order(self, event_args: NewBrokerageOrderNotificationEventArgs) -> bool: return False
The BrokerageMessageEvent
class has the following properties:
The NewBrokerageOrderNotificationEventArgs
class has the following properties:
Brokerage Support
Most QuantConnect brokerage integrations don't support brokerage-side orders.
If you create an order directly through your brokerage instead of through LEAN, your algorithm won't process the order because the return value of the HandleOrder
handle_order
method is ignored.
Terminal Link is the exception that can support brokerage-side orders.
This algorithmThis algorithm demonstrates how to implement a custom brokerage handler that accepts orders with a target TerminalLinkOrderProperties.CustomNotes1
TerminalLinkOrderProperties.custom_notes_1
value.