In This Page

Introduction

Set Models

Default Behavior

Model Structure

Disable Margin Calls

Monitor Margin Call Events

Submit Order Request

Examples

Reality Modeling

Margin Calls

Introduction

If the value of your portfolio falls below the maintenance margin, you receive a margin call. If you receive a margin call, you either need to add more capital to your brokerage account or the brokerage will liquidate some of your holdings to reduce your exposure and their risk. A margin call model monitors the margin levels of your portfolio, issues margin call warnings, and submits orders when margin calls occur.

Set Models

To set the margin call model, call the set_margin_call_model method of the portfolio object.

Select Language:

public override void Initialize()
{
	// Set margin call model for the whole portfolio, better with reference to your broker information
	Portfolio.SetMarginCallModel(new DefaultMarginCallModel(Portfolio, DefaultOrderProperties));
}

def initialize(self) -> None:
	# Set margin call model for the whole portfolio, better with reference to your broker information
	self.portfolio.set_margin_call_model(DefaultMarginCallModel(self.portfolio, self.default_order_properties))

Default Behavior

The brokerage model of your algorithm automatically sets the margin call model for the portfolio. The default brokerage model is the DefaultBrokerageModel, which sets the DefaultMarginCallModel. The DefaultMarginCallModel issues margin call warnings when the margin remaining in your portfolio is less than or equal to 5% of the total portfolio value. When your total margin used exceeds 10% of the total portfolio value, this model creates margin call orders. It sorts the generated margin call orders in ascending order by their unrealized profit and then synchronously executes each order until your portfolio is within the margin requirements.

The following table describes the arguments the model accepts:

Argument	Data Type	Description	Default Value
`portfolio`	`SecurityPortfolioManager`	The portfolio object to receive margin calls.
`defaultOrderPropertiesdefault_order_properties`	`IOrderProperties`	The default order properties to be use in margin call orders.
`marginBuffermargin_buffer`	`decimalfloat`	The percent margin buffer to use when checking whether the total margin used is above the total portfolio value to generate margin call orders.	`0.10m0.10` (10%)

To view the implementation of this model, see the LEAN GitHub repository.

Model Structure

Margin call models must extend the DefaultMarginCallModel class. Extensions of the DefaultMarginCallModel class can override the GetMarginCallOrdersget_margin_call_orders and ExecuteMarginCallexecute_margin_call methods.

The GetMarginCallOrdersget_margin_call_orders method scans the portfolio and the updated data for a potential margin call situation that may get the equity below zero. The method must return a tuple where the first element is a list of SubmitOrderRequest objects that represent the margin call orders and the second element is a boolean that represents whether or not to issue a margin call warning.

The ExecuteMarginCallexecute_margin_call method receives the list of SubmitOrderRequest objects from the GetMarginCallOrdersget_margin_call_orders method, executes some of them, and returns a list of OrderTicket objects.

Select Language:

public class CustomMarginCallModelExampleAlgorithm : QCAlgorithm
{
    public override void Initialize()
    {
        // Set margin call model for the whole portfolio, better with reference to your broker information
        Portfolio.SetMarginCallModel(new MyMarginCallModel(Portfolio, DefaultOrderProperties));
    }
}

// Define the custom margin call model  
public class MyMarginCallModel : DefaultMarginCallModel
{
    public MyMarginCallModel(
        SecurityPortfolioManager portfolio,
        IOrderProperties defaultOrderProperties)
        : base(portfolio, defaultOrderProperties)
    {
    }

    public override List<OrderTicket> ExecuteMarginCall(
        IEnumerable<SubmitOrderRequest> generatedMarginCallOrders)
    {
        return base.ExecuteMarginCall(generatedMarginCallOrders);
    }

    public List<SubmitOrderRequest> GetMarginCallOrders(out bool issueMarginCallWarning)
    {
        return base.GetMarginCallOrders(out issueMarginCallWarning);
    }
}

class CustomMarginCallModelExampleAlgorithm(QCAlgorithm):
    def initialize(self) -> None:
        # Set margin call model for the whole portfolio, better with reference to your broker information
        self.portfolio.set_margin_call_model(MyMarginCallModel(self.portfolio, self.default_order_properties))
        
# Define the custom margin call model        
class MyMarginCallModel(DefaultMarginCallModel):
    def __init__(self,
         portfolio: SecurityPortfolioManager,
         default_order_properties: IOrderProperties):
        super().__init__(portfolio, default_order_properties)

    def execute_margin_call(self,
         generatedMarginCallOrders: List[SubmitOrderRequest]) -> List[OrderTicket]:
        return super().execute_margin_call(generatedMarginCallOrders)

    def get_margin_call_orders(self,
         issue_margin_call_warning: bool) -> tuple[List[SubmitOrderRequest], bool]:
        (margin_call_orders, issue_margin_call_warning) = super().get_margin_call_orders(issue_margin_call_warning)
        return (margin_call_orders, issue_margin_call_warning)

For a full example algorithm, see this backtestthis backtest.

Disable Margin Calls

To disable margin calls, set the margin call model to the NullMarginCallModel.

Select Language:

public override void Initialize()
{
	Portfolio.MarginCallModel = MarginCallModel.Null;
}

def initialize(self) -> None:
	self.portfolio.margin_call_model = MarginCallModel.NULL

Monitor Margin Call Events

When the margin call model of your portfolio issues a margin call warning, we notify your algorithm through the OnMarginCallWarningon_margin_call_warning event handler.

Select Language:

public override void OnMarginCallWarning()
{
    Debug("Warning: Close to margin call");
}

def on_margin_call_warning(self) -> None:
    self.debug(f"Warning: Close to margin call")

Before we send the orders that the margin call model produces, we notify your algorithm through the OnMarginCallon_margin_call event handler. This notification gives your algorithm a chance to liquidate some positions or modify the margin call orders. To modify the orders, adjust the list of SubmitOrderRequest objects the event handler receives.

Select Language:

public override void OnMarginCall(List<SubmitOrderRequest> requests)
{
    for (var i = 0; i < requests.Count; i++)
    {
        var order = requests[i];
        // liquidate an extra 10% each time you get a margin call to give yourself more padding
        var newQuantity = (int)(order.Quantity * 1.1m);
        requests[i] = new SubmitOrderRequest(order.OrderType, order.SecurityType, 
                                            order.Symbol, newQuantity, order.StopPrice, 
                                            order.LimitPrice, 0, Time, "OnMarginCall");
    }
}

def on_margin_call(self, requests: List[SubmitOrderRequest]) -> List[SubmitOrderRequest]:
    for i, order in enumerate(requests):
        # liquidate an extra 10% each time you get a margin call to give yourself more padding
        new_quantity = int(order.quantity * 1.1)
        requests[i] = SubmitOrderRequest(order.order_type, order.security_type, 
                                        order.symbol, new_quantity, order.stop_price, 
                                        order.limit_price, 0, self.time, "OnMarginCall")
    return requests

Submit Order Request

If you receive a margin call or create a margin call model, you'll need to work with SubmitOrderRequest objects. These objects have the following properties:

SubmitOrderRequest Select Language:

Gets QuantConnect.Orders.OrderRequestType.Submit

order_request_type: OrderRequestType

Gets the security type of the symbol

security_type: SecurityType

Gets the symbol to be traded

symbol: Symbol

Gets the order type od the order

order_type: OrderType

Gets the quantity of the order

quantity: decimal

Gets the limit price of the order, zero if not a limit order

limit_price: decimal

Gets the stop price of the order, zero if not a stop order

stop_price: decimal

Price which must first be reached before a limit order can be submitted.

trigger_price: decimal

Trailing amount for a trailing stop order

trailing_amount: decimal

Determines whether the QuantConnect.Orders.SubmitOrderRequest.TrailingAmount is a percentage or an absolute currency value

trailing_as_percentage: bool

Gets the order properties for this request

order_properties: IOrderProperties

Gets the manager for the combo order. If null, the order is not a combo order.

group_order_manager: GroupOrderManager

Gets the status of this request

status: OrderRequestStatus

Gets the UTC time the request was created

time: DateTime

Gets the order id the request acts on

order_id: Int32

Gets a tag for this request

tag: string

Gets the response for this request. If this request was never processed then this will equal QuantConnect.Orders.OrderResponse.Unprocessed. This value is never equal to null.

response: OrderResponse

The following table describes the arguments of the SubmitOrderRequest constructor:

Argument	Data Type	Description	Default Value
`orderTypeorder_type`	`OrderType`	The order type to be submitted
`securityTypesecurity_type`	`SecurityType`	The security type of the asset
`symbol`	`Symbol`	The symbol to be traded
`quantity`	`decimalfloat`	The number of units to order
`stopPricestop_price`	`decimalfloat`	The stop price for stop orders
`limitPricelimit_price`	`decimalfloat`	The limit price for limit orders
`triggerPricetrigger_price`	`decimalfloat`	The trigger price for limit if touched orders
`time`	`DateTimedatetime`	The time this request was created
`tag`	`stringstr`	A custom tag for this request
`properties`	`IOrderProperties`	The order properties for this request	`nullNone`

Examples

Demonstration Algorithms

MarginCallEventsAlgorithm.py Python

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:

SIGN IN

Browse

Cloud Platform

Writing Algorithms

▶Key Concepts

Initialization

▶Securities

▶Portfolio

▶Universes

▶Datasets

▶Importing Data

▶Consolidating Data

▶Historical Data

▶Trading and Orders