book
Checkout our new book! Hands on AI Trading with Python, QuantConnect, and AWS Learn More arrow

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.

Set Models

To set a brokerage message handler, in the initialize method, call the set_brokerage_message_handler method.

Select Language:
def initialize(self) -> None:
    # Set a custom brokerage message handler for the algorithm in Initialize method
    # It handles different type of returned message from the broker, helping you filter or abstract for the ones you care about
    self.set_brokerage_message_handler(MyBrokerageMessageHandler(self))

Default Behavior

The default brokerage message handler is the DefaultBrokerageMessageHandler. The following table describes how the DefaultBrokerageMessageHandler processes brokerage messages:

Brokerage Message TypeAction
BrokerageMessageType.INFORMATIONSends a debug message for the algorithm.
BrokerageMessageType.WARNINGSends an error message for the algorithm.
BrokerageMessageType.ERRORSets the algorithm runtime error and stops it.
BrokerageMessageType.DISCONNECTStops the algorithm after 15 minutes if the market is open. Otherwise, it stops five minutes after market open.
BrokerageMessageType.RECONNECTCancels 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:

ArgumentData TypeDescriptionDefault Value
algorithmIAlgorithmThe running algorithm.
initial_delaytimedelta/NoneTypeThe 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 timedelta(minutes=15).None
open_thresholdtimedelta/NoneTypeDefines how long before market open to re-check for brokerage reconnect message. If you don't provide a value, it uses timedelta(minutes=5).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 handle_message and handle_order methods.

The handle_message method processes the brokerage message event. It triggers any actions in the algorithm or notifications system required.

The 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.

Select Language:
class CustomBrokerageMessageHandlerExampleAlgorithm(QCAlgorithm):
    def initialize(self) -> None:
        # 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 handle_order method is ignored.

Terminal Link is the exception that can support brokerage-side orders. This algorithm demonstrates how to implement a custom brokerage handler that accepts orders with a target TerminalLinkOrderProperties.custom_notes_1 value.

Examples

The following examples demonstrate common practices for implementing a custom brokerage message handler.

Example 1: Notification

The following algorithm buys and holds SPY. It implemented a custom brokerage message handler to send notifications to users through email and SMS in cases of disconnection, reconnections, and outside trades.

Select Language:
class CustomBrokerageMessageHandlerAlgorithm(QCAlgorithm):
    def initialize(self) -> None:
        # To simulate the connection to IB brokerage.
        self.set_brokerage_model(BrokerageName.INTERACTIVE_BROKERS_BROKERAGE, AccountType.MARGIN)
        # Set the brokerage message handler to our custom model.
        self.set_brokerage_message_handler(CustomBrokerageMessageHandler(self))

        # Request SPY data for trading.
        self.spy = self.add_equity("SPY").symbol

    def on_data(self, slice: Slice) -> None:
        # Buy and hold SPY as a strategy.
        if not self.portfolio.invested:
            self.set_holdings(self.spy, 1)

class CustomBrokerageMessageHandler(DefaultBrokerageMessageHandler):
    def __init__(self, algorithm: QCAlgorithm) -> None:
        self._algorithm = algorithm

    def handle_message(self, message: BrokerageMessageEvent) -> None:
        # Notify the user by SMS of the disconnection of the algorithm instance from the brokerage.
        if message.type == BrokerageMessageType.DISCONNECT:
            self._algorithm.notify.sms(
                phone_number="<YOUR_PHONE_NUMBER>",
                message="Your QC Algorithm instance 'CustomBrokerageMessageHandlerAlgorithm' was disconnected from the IB brokerage."
            )
        # Notify the user by SMS on reconnection of the algorithm instance to the brokerage after disconnection.
        elif message.type == BrokerageMessageType.RECONNECT:
            self._algorithm.notify.sms(
                phone_number="<YOUR_PHONE_NUMBER>",
                message="Your QC Algorithm instance 'CustomBrokerageMessageHandlerAlgorithm' was reconnected to the IB brokerage."
            )

    def handle_order(self, event_args: NewBrokerageOrderNotificationEventArgs) -> bool:
        # Notify the user by email on receiving an order from outside the algorithm.
        self._algorithm.notify.email(
            address="<YOUR_EMAIL_ADDRESS@example.com>",
            subject="Outside Order",
            message="Your QC Algorithm instance 'CustomBrokerageMessageHandlerAlgorithm' detected an outside order from the IB brokerage; it has been processed to the algorithm."
        )
        # Process a new order placed through the brokerage's website or third-party software to handle it in the algorithm instance.
        return True

Other Examples

For more examples, see the following algorithms:

You can also see our Videos. You can also get in touch with us via Discord.

Did you find this page helpful?

Contribute to the documentation: