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

Portfolio

Holdings

Introduction

The portfolio is a dictionary where the key is a Symbol and the value is a SecurityHolding.

Select Language: 
# Create shortcut helper to the SPY SecurityHolding object from the Portfolio collection.
security_holding = self.portfolio["SPY"]

Properties

SecurityHolding objects have the following properties:

SecurityHolding Select Language:
    Gets the current target holdings for this security
  • target: IPortfolioTarget
    • Average price of the security holdings.
  • average_price: decimal
    • Quantity of the security held.
  • quantity: decimal
    • Symbol identifier of the underlying security.
  • symbol: Symbol
    • The security type of the symbol
  • type: SecurityType
    • Leverage of the underlying security.
  • leverage: decimal
    • Acquisition cost of the security total holdings in units of the account's currency.
  • holdings_cost: decimal
    • Unlevered Acquisition cost of the security total holdings in units of the account's currency.
  • unlevered_holdings_cost: decimal
    • Current market price of the security.
  • price: decimal
    • Absolute holdings cost for current holdings in units of the account's currency.
  • absolute_holdings_cost: decimal
    • Unlevered absolute acquisition cost of the security total holdings in units of the account's currency.
  • unlevered_absolute_holdings_cost: decimal
    • Market value of our holdings in units of the account's currency.
  • holdings_value: decimal
    • Absolute of the market value of our holdings in units of the account's currency.
  • absolute_holdings_value: decimal
    • Boolean flag indicating if we hold any of the security
  • hold_stock: bool
    • Boolean flag indicating if we hold any of the security
  • invested: bool
    • The total transaction volume for this security since the algorithm started in units of the account's currency.
  • total_sale_volume: decimal
    • Total fees for this company since the algorithm started in units of the account's currency.
  • total_fees: decimal
    • Total dividends for this company since the algorithm started in units of the account's currency.
  • total_dividends: decimal
    • Boolean flag indicating we have a net positive holding of the security.
  • is_long: bool
    • BBoolean flag indicating we have a net negative holding of the security.
  • is_short: bool
    • Absolute quantity of holdings of this security
  • absolute_quantity: decimal
    • Record of the closing profit from the last trade conducted in units of the account's currency.
  • last_trade_profit: decimal
    • Calculate the total profit for this security in units of the account's currency.
  • profit: decimal
    • Return the net for this company measured by the profit less fees in units of the account's currency.
  • net_profit: decimal
    • Gets the unrealized profit as a percentage of holdings cost
  • unrealized_profit_percent: decimal
    • Unrealized profit of this security when absolute quantity held is more than zero in units of the account's currency.
  • unrealized_profit: decimal
Select Language: 
#  Save shortcut to SecurityHolding object, and fetch quantity and invested status.
security_holding = self.portfolio["SPY"]
quantity = security_holding.quantity
invested = security_holding.invested

FutureHolding objects also have settled_profit and unsettled_profit properties.

Get Total Close Profit

To get the profit of a position holding if you closed the position, call the total_close_profit method. The value this method returns is denominated in your account currency and accounts for order fees.

Select Language: 
profit = self.portfolio["SPY"].total_close_profit()

The total_close_profit method accepts the following optional arguments:

ArgumentData TypeDescriptionDefault Value
include_feesboolWhether to reduce the profit based on the estimated fee from the fee model.True
exit_pricefloat/NoneTypeA hypothetical exit price to use for the profit calculation. If you don't provide a value, it uses the bid price for sell orders or the ask price for buy orders.None
entry_pricefloat/NoneTypeA hypothetical exit price to use for the profit calculation. If you don't provide a value, it uses the average price of the SecurityHolding.None
quantityfloat/NoneTypeThe quantity to liquidate. If you don't provide a value, it uses the quantity of the SecurityHolding.None

LEAN uses this method to define the unrealized_profit property.

Get Quantity Value

To get the value of a security at any quantity, call the get_quantity_value method. The value this method returns is denominated in your account currency.

Select Language: 
# Get the quantity value at the current price
value_at_current_price = self.portfolio["SPY"].get_quantity_value(100)

# Get the quantity value at a specific price
value_at_specific_price = self.portfolio["SPY"].get_quantity_value(100, price=30)

Set Initial Holdings

When you deploy a backtest or a new paper trading algorithm, the default initial portfolio state contains $100,000 USD. However, in the initialize method, you can define the initial portfolio state to something else. To set the initial cash balances, call set_cash with the currency ticker and quantity. To set multiple currencies, call the method multiple times.

Select Language: 
self.set_cash(100000)       # Set the quantity of the account currency to 100,000
self.set_cash("BTC", 10)    # Set the Bitcoin quantity to 10
self.set_cash("EUR", 10000) # Set the EUR quantity to 10,000

To set the initial security holdings, subscribe to the security so that it enters your portfolio, then call the SecurityHolding.set_holdings method with the average purchase price and quantity.

Select Language: 
if not self.live_mode:
    self.portfolio["SPY"].set_holdings(average_price=500, quantity=100)

Examples

The following examples demonstrate common practices for setting the portfolio holdings.

Example 1: Initial Holdings

The following algorithm simulates an account with multiple initial positions and cash. Note that these initial holdings will affect the algorithm's performance.

Select Language: 
class PortfolioExampleAlgorithm(QCAlgorithm):
    def initialize(self) -> None:
        self.set_start_date(2024, 1, 1)
        self.set_end_date(2024, 1, 31)
        # Simulate initial cash in multiple currencies.
        # Note that all currencies other than the account currency will affect the performance.
        self.set_account_currency("USD", 10000)
        self.set_cash("EUR", 1000)
        self.set_cash("JPY", 1000000)
        self.set_cash("HKD", 10000)

        # Request data for some securities in the account already.
        spy = self.add_equity("SPY").symbol
        aapl = self.add_equity("AAPL").symbol
        btcusd = self.add_crypto("BTCUSD").symbol
        xauusd = self.add_cfd("XAUUSD").symbol

        # Simulate that the account initially holds some assets.
        # Note that all initial holdings will affect the performance.
        self.portfolio[spy].set_holdings(average_price=420, quantity=102)
        self.portfolio[aapl].set_holdings(average_price=120, quantity=25)
        self.portfolio[btcusd].set_holdings(average_price=45000, quantity=0.125)
        self.portfolio[xauusd].set_holdings(average_price=1000, quantity=100)

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: