Settlement
Key Concepts
Introduction
After you trade an asset, the brokerage needs to settle the funds in your account. The most common type of settlement is immediate, where the funds are immediately available for trading after the transaction. In some cases, you may have delayed settlement, where you sell an asset and need to wait a few days to spend the cash you receive from the sale. A settlement model simulates these settlement rules.
Set Models
The brokerage model of your algorithm automatically sets the settlement model for each security, but you can override it. To manually set the settlement model of a security, call the set_settlement_model
method on the Security
object.
def initialize(self) -> None: security = self.add_equity("SPY") # Set a delayed settlement model that settles 7 days after the trade at 8 AM # This can better mimic actual settlement of some brokerage, providing more realistic fund and margin available security.set_settlement_model(DelayedSettlementModel(7, timedelta(hours=8)))
You can also set the settlement model in a security initializer. If your algorithm has a universe, use the security initializer technique. In order to initialize single security subscriptions with the security initializer, call set_security_initializer
before you create the subscriptions.
class BrokerageModelExampleAlgorithm(QCAlgorithm): def initialize(self) -> None: # In the Initialize method, set the security initializer to seed initial the prices and models of assets. self.set_security_initializer(MySecurityInitializer(self.brokerage_model, FuncSecuritySeeder(self.get_last_known_prices))) # Outside of the algorithm class class MySecurityInitializer(BrokerageModelSecurityInitializer): def __init__(self, brokerage_model: IBrokerageModel, security_seeder: ISecuritySeeder) -> None: super().__init__(brokerage_model, security_seeder) def initialize(self, security: Security) -> None: # First, call the superclass definition. # This method sets the reality models of each security using the default reality models of the brokerage model. super().initialize(security) # Next, overwrite some of the reality models security.set_settlement_model(DelayedSettlementModel(7, timedelta(hours=8)))
To view all the pre-built settlement models, see Supported Models.
Default Behavior
The brokerage model of your algorithm automatically sets the settlement model for each security. The default brokerage model is the DefaultBrokerageModel
, which sets the settlement model based on the security type and your account type. The following table shows how it sets the settlement models:
Security Type | Account Type | Settlement Model |
---|---|---|
Equity | Cash | DelayedSettlementModel with the default settlement rules |
Option | Cash | DelayedSettlementModel with the default settlement rules |
Future | Any | FutureSettlementModel |
For all other cases, the DefaultBrokerageModel
uses the ImmediateSettlementModel.
The default delayed settlement rule for US Equity trades is T+2 at 8 AM Eastern Time (ET). For example, if you sell on Monday, the trade settles on Wednesday at 8 AM. The default delayed settlement rule for Future and Option contracts is T+1 at 8 AM.
Model Structure
Settlement models must extend the ISettlementModel
interface. Extensions of the ISettlementModel
interface must implement the scan
and apply_funds
methods. The scan
method is automatically called at the top of each hour and it receives a ScanSettlementModelParameters
object. The apply_funds
method receives an ApplyFundsSettlementModelParameters
object and applies the settlement rules. The apply_funds
method is also automatically called, but its frequency depends on the security type. The apply_funds
method is automatically called when you fill an order for the following security types:
- Equity
- Equity Options
- Crypto
- Forex
- Future Options
- Index Options
The apply_funds
method is automatically called when you close a position for the following security types:
- Futures
- Crypto Futures
- CFD
class CustomSettlementModelExampleAlgorithm(QCAlgorithm): def initialize(self) -> None: security = self.add_equity("SPY") # Set the custom settlement model of the selected security to reflect actual scenario for more realistic margin available security.set_settlement_model(MySettlementModel()) # Define the custom settlement model outside of the algorithm class MySettlementModel: def apply_funds(self, applyFundsParameters: ApplyFundsSettlementModelParameters) -> None: currency = applyFundsParameters.cash_amount.currency amount = applyFundsParameters.cash_amount.amount applyFundsParameters.portfolio.cash_book[currency].add_amount(amount) def scan(self, settlementParameters: ScanSettlementModelParameters) -> None: pass def get_unsettled_cash(self) -> CashAmount: return CashAmount(0, 'USD')
For a full example algorithm, see this backtest .
ApplyFundsSettlementModelParameters
objects have the following properties:
ScanSettlementModelParameters
objects have the following properties:
You likely don't need to create a custom settlement model because the supported models already implement immediate and delayed settlement rules.
Examples
The following examples demonstrate some common practices for implementing the settlement model.
Example 1: 2-day Settlement
The following algorithm simulates Interactive Brokers cash account. According to IB's website, cash positions will be settled in 48 hours. Thus, we can implement
DelayedSettlementModel
to mimic that. We hold the intra-day position of SPY to implement the settlement logic.
# region imports from AlgorithmImports import * # endregion class SettlementModelAlgorithm(QCAlgorithm): def initialize(self) -> None: self.set_start_date(2023, 10, 1) self.set_end_date(2024, 10, 1) # Simulate a cash account of IB. self.set_brokerage_model(BrokerageName.INTERACTIVE_BROKERS_BROKERAGE, AccountType.CASH) # We need to set the settlement model in the security initializer. self.set_security_initializer(CustomSecurityInitializer(self.brokerage_model, SecuritySeeder.NULL)) # Request SPY data for trading. self.spy = self.add_equity("SPY").symbol def on_data(self, slice: Slice) -> None: # Trade based on updated data. bar = slice.bars.get(self.spy) if bar and not self.portfolio.invested: # Order based on the current available cash. quantity = (self.portfolio.cash - self.portfolio.unsettled_cash) // bar.close if quantity > 0: self.market_order(self.spy, quantity) # Exit position before market close; we only hold the intraday position. if slice.time.hour == 15 and slice.time.minute == 45: self.liquidate() class CustomSecurityInitializer(BrokerageModelSecurityInitializer): def __init__(self, brokerage_model: IBrokerageModel, security_seeder: ISecuritySeeder): super().__init__(brokerage_model, security_seeder) def initialize(self, security: Security) -> None: super().initialize(security) # IB settles cash in 48 hours. security.set_settlement_model(DelayedSettlementModel(2, timedelta(hours=0)))