Portfolio

The portfolio subpackage provides portfolio management functionality.

class Portfolio

Bases: PortfolioFacade

Portfolio(MessageBus msgbus, CacheFacade cache, Clock clock, config: PortfolioConfig | None = None) -> None

Provides a trading portfolio.

Currently there is a limitation of one account per ExecutionClient instance.

• Parameters:
  • msgbus (MessageBus) – The message bus for the engine.
  • cache (CacheFacade) – The read-only cache for the portfolio.
  • clock (Clock) – The clock for the portfolio.
  • config (PortfolioConfig) – The configuration for the instance.
• Raises: TypeError – If config is not of type PortfolioConfig.

account(self, Venue venue=None, AccountId account_id=None) → Account

Return the account for the given venue or account ID (if found).

• Parameters:
  • venue (Venue , optional) – The venue for the account.
  • account_id (AccountId , optional) – The account ID (takes priority if both venue and account_id are provided).
• Return type: Account or None

balances_locked(self, Venue venue=None, AccountId account_id=None) → dict

Return the balances locked for the given venue or account ID (if found).

• Parameters:
  • venue (Venue , optional) – The venue for the account.
  • account_id (AccountId , optional) – The account ID (takes priority if both venue and account_id are provided).
• Return type: dict[Currency, Money] or None

dispose(self) → None

Dispose of the portfolio.

All stateful fields are reset to their initial value.

initialize_orders(self) → void

Initialize the portfolios orders.

Performs all account calculations for the current orders state.

initialize_positions(self) → void

Initialize the portfolios positions.

Performs all account calculations for the current position state.

is_completely_flat(self, AccountId account_id=None) → bool

Return a value indicating whether the portfolio is completely flat.

• Parameters: account_id (AccountId , optional) – The account ID. If None, checks across all accounts.
• Returns: True if net flat across all instruments, else False.
• Return type: bool

is_flat(self, InstrumentId instrument_id, AccountId account_id=None) → bool

Return a value indicating whether the portfolio is flat for the given instrument ID.

• Parameters:
  • instrument_id (InstrumentId) – The instrument query filter.
  • account_id (AccountId , optional) – The account ID. If None, aggregates across all accounts.
• Returns: True if net flat, else False.
• Return type: bool

is_net_long(self, InstrumentId instrument_id, AccountId account_id=None) → bool

Return a value indicating whether the portfolio is net long the given instrument ID.

• Parameters:
  • instrument_id (InstrumentId) – The instrument for the query.
  • account_id (AccountId , optional) – The account ID. If None, aggregates across all accounts.
• Returns: True if net long, else False.
• Return type: bool

is_net_short(self, InstrumentId instrument_id, AccountId account_id=None) → bool

Return a value indicating whether the portfolio is net short the given instrument ID.

• Parameters:
  • instrument_id (InstrumentId) – The instrument for the query.
  • account_id (AccountId , optional) – The account ID. If None, aggregates across all accounts.
• Returns: True if net short, else False.
• Return type: bool

margins_init(self, Venue venue=None, AccountId account_id=None) → dict

Return the initial (order) margins for the given venue or account ID (if found).

• Parameters:
  • venue (Venue , optional) – The venue for the account.
  • account_id (AccountId , optional) – The account ID (takes priority if both venue and account_id are provided).
• Return type: dict[Currency, Money] or None

margins_maint(self, Venue venue=None, AccountId account_id=None) → dict

Return the maintenance (position) margins for the given venue or account ID (if found).

• Parameters:
  • venue (Venue , optional) – The venue for the account.
  • account_id (AccountId , optional) – The account ID (takes priority if both venue and account_id are provided).
• Return type: dict[Currency, Money] or None

net_exposure(self, InstrumentId instrument_id, Price price=None, AccountId account_id=None, Currency target_currency=None) → Money

Return the net exposure for the given instrument (if found).

• Parameters:
  • instrument_id (InstrumentId) – The instrument for the calculation.
  • price (Price , optional) – The reference price for the calculation. This could be the last, mid, bid, ask, a mark-to-market price, or any other suitably representative value.
  • account_id (AccountId , optional) – The account ID for the net exposure.
  • target_currency (Currency , optional) – The currency to convert the exposure into.
• Return type: Money or None

net_exposures(self, Venue venue=None, AccountId account_id=None, Currency target_currency=None) → dict

Return the net exposures for the given venue (if found).

• Parameters:
  • venue (Venue , optional) – The venue for the market value.
  • account_id (AccountId , optional) – The account ID for the net exposures.
  • target_currency (Currency , optional) – The currency to convert the exposures into.
• Return type: dict[Currency, Money] or None

net_position(self, InstrumentId instrument_id, AccountId account_id=None)

Return the net position for the given instrument ID. If account_id is provided, returns the net position for that account. If account_id is None, aggregates across all accounts. If no positions for instrument_id then will return Decimal(‘0’).

• Parameters:
  • instrument_id (InstrumentId) – The instrument for the query.
  • account_id (AccountId , optional) – The account ID. If None, aggregates across all accounts.
• Return type: Decimal

on_order_event(self, OrderEvent event) → void

Actions to be performed on receiving an order event.

• Parameters: event (OrderEvent) – The event received.

on_position_event(self, PositionEvent event) → void

Actions to be performed on receiving a position event.

• Parameters: event (PositionEvent) – The event received.

realized_pnl(self, InstrumentId instrument_id, AccountId account_id=None, Currency target_currency=None) → Money

Return the realized PnL for the given instrument ID (if found).

• Parameters:
  • instrument_id (InstrumentId) – The instrument for the realized PnL.
  • account_id (AccountId , optional) – The account ID for the realized PnL. If None, aggregates across all accounts.
  • target_currency (Currency , optional) – The currency to convert the PnL into.
• Return type: Money or None

realized_pnls(self, Venue venue=None, AccountId account_id=None, Currency target_currency=None) → dict

Return the realized PnLs for the given venue (if found).

If no positions exist for the venue or if any lookups fail internally, an empty dictionary is returned.

• Parameters:
  • venue (Venue , optional) – The venue for the realized PnLs.
  • account_id (AccountId , optional) – The account ID for the realized PnLs.
  • target_currency (Currency , optional) – The currency to convert the PnLs into.
• Return type: dict[Currency, Money]

reset(self) → None

Reset the portfolio.

All stateful fields are reset to their initial value.

set_use_mark_prices(self, bool value) → void

Set the use_mark_prices setting with the given value.

• Parameters: value (bool) – The value to set.

set_use_mark_xrates(self, bool value) → void

Set the use_mark_xrates setting with the given value.

• Parameters: value (bool) – The value to set.

total_pnl(self, InstrumentId instrument_id, Price price=None, AccountId account_id=None, Currency target_currency=None) → Money

Return the total PnL for the given instrument ID (if found).

• Parameters:
  • instrument_id (InstrumentId) – The instrument for the total PnL.
  • price (Price , optional) – The reference price for the calculation. This could be the last, mid, bid, ask, a mark-to-market price, or any other suitably representative value.
  • account_id (AccountId , optional) – The account ID for the total PnL.
  • target_currency (Currency , optional) – The currency to convert the PnL into.
• Return type: Money or None

total_pnls(self, Venue venue=None, AccountId account_id=None, Currency target_currency=None) → dict

Return the total PnLs for the given venue (if found).

• Parameters:
  • venue (Venue , optional) – The venue for the total PnLs.
  • account_id (AccountId , optional) – The account ID for the total PnLs.
  • target_currency (Currency , optional) – The currency to convert the PnLs into.
• Return type: dict[Currency, Money]

unrealized_pnl(self, InstrumentId instrument_id, Price price=None, AccountId account_id=None, Currency target_currency=None) → Money

Return the unrealized PnL for the given instrument ID (if found).

• If price is provided, a fresh calculation is performed without using or updating the cache.
• If price is omitted, the method returns the cached PnL if available, or computes and caches it if not.

Returns None if the calculation fails (e.g., the account or instrument cannot be found), or zero-valued Money if no positions are open. Otherwise, it returns a Money object (usually in the account’s base currency or the instrument’s settlement currency).

• Parameters:
  • instrument_id (InstrumentId) – The instrument for the unrealized PnL.
  • price (Price , optional) – The reference price for the calculation. This could be the last, mid, bid, ask, a mark-to-market price, or any other suitably representative value.
  • account_id (AccountId , optional) – The account ID for the unrealized PnL. If None, aggregates across all accounts.
  • target_currency (Currency , optional) – The currency to convert the PnL into.
• Returns: The unrealized PnL or None if the calculation cannot be performed.
• Return type: Money or None

unrealized_pnls(self, Venue venue=None, AccountId account_id=None, Currency target_currency=None) → dict

Return the unrealized PnLs for the given venue (if found).

• Parameters:
  • venue (Venue , optional) – The venue for the unrealized PnLs.
  • account_id (AccountId , optional) – The account ID for the unrealized PnLs.
  • target_currency (Currency , optional) – The currency to convert the PnLs into.
• Return type: dict[Currency, Money]

update_account(self, AccountState event) → void

Apply the given account state.

• Parameters: event (AccountState) – The account state to apply.

update_bar(self, Bar bar) → void

Update the portfolio with the given bar.

Clears the cached unrealized PnL for the associated instrument, and performs any initialization calculations which may have been pending an update.

• Parameters: bar (Bar) – The bar to update with.

update_mark_price(self, mark_price) → void

Update the portfolio with the given mark price.

update_order(self, OrderEvent event) → void

Update the portfolio with the given order.

• Parameters: event (OrderEvent) – The event to update with.

update_position(self, PositionEvent event) → void

Update the portfolio with the given position event.

• Parameters: event (PositionEvent) – The event to update with.

update_quote_tick(self, QuoteTick tick) → void

Update the portfolio with the given quote tick.

Clears the cached unrealized PnL for the associated instrument, and performs any initialization calculations which may have been pending an update.

• Parameters: quote_tick (QuoteTick) – The quote tick to update with.

class PortfolioFacade

Bases: object

Provides a read-only facade for a Portfolio.

account(self, Venue venue=None, AccountId account_id=None) → Account

Abstract method (implement in subclass).

analyzer

The portfolios analyzer.

• Returns: PortfolioAnalyzer

balances_locked(self, Venue venue=None, AccountId account_id=None) → dict

Abstract method (implement in subclass).

initialized

If the portfolio is initialized.

• Returns: bool

is_completely_flat(self, AccountId account_id=None) → bool

Abstract method (implement in subclass).

is_flat(self, InstrumentId instrument_id, AccountId account_id=None) → bool

Abstract method (implement in subclass).

is_net_long(self, InstrumentId instrument_id, AccountId account_id=None) → bool

Abstract method (implement in subclass).

is_net_short(self, InstrumentId instrument_id, AccountId account_id=None) → bool

Abstract method (implement in subclass).

margins_init(self, Venue venue=None, AccountId account_id=None) → dict

Abstract method (implement in subclass).

margins_maint(self, Venue venue=None, AccountId account_id=None) → dict

Abstract method (implement in subclass).

net_exposure(self, InstrumentId instrument_id, Price price=None, AccountId account_id=None, Currency target_currency=None) → Money

Abstract method (implement in subclass).

net_exposures(self, Venue venue=None, AccountId account_id=None, Currency target_currency=None) → dict

Abstract method (implement in subclass).

net_position(self, InstrumentId instrument_id, AccountId account_id=None)

Abstract method (implement in subclass).

realized_pnl(self, InstrumentId instrument_id, AccountId account_id=None, Currency target_currency=None) → Money

Abstract method (implement in subclass).

realized_pnls(self, Venue venue=None, AccountId account_id=None, Currency target_currency=None) → dict

Abstract method (implement in subclass).

total_pnl(self, InstrumentId instrument_id, Price price=None, AccountId account_id=None, Currency target_currency=None) → Money

Abstract method (implement in subclass).

total_pnls(self, Venue venue=None, AccountId account_id=None, Currency target_currency=None) → dict

Abstract method (implement in subclass).

unrealized_pnl(self, InstrumentId instrument_id, Price price=None, AccountId account_id=None, Currency target_currency=None) → Money

Abstract method (implement in subclass).

unrealized_pnls(self, Venue venue=None, AccountId account_id=None, Currency target_currency=None) → dict

Abstract method (implement in subclass).

The Portfolio facilitates the management of trading operations.

The intended use case is for a single Portfolio instance per running system, a fleet of trading strategies will organize around a portfolio with the help of the Trader` class.

The portfolio can satisfy queries for account information, margin balances, total risk exposures and total net positions.

class Portfolio

Bases: PortfolioFacade

Portfolio(MessageBus msgbus, CacheFacade cache, Clock clock, config: PortfolioConfig | None = None) -> None

Provides a trading portfolio.

Currently there is a limitation of one account per ExecutionClient instance.

• Parameters:
  • msgbus (MessageBus) – The message bus for the engine.
  • cache (CacheFacade) – The read-only cache for the portfolio.
  • clock (Clock) – The clock for the portfolio.
  • config (PortfolioConfig) – The configuration for the instance.
• Raises: TypeError – If config is not of type PortfolioConfig.

account(self, Venue venue=None, AccountId account_id=None) → Account

Return the account for the given venue or account ID (if found).

• Parameters:
  • venue (Venue , optional) – The venue for the account.
  • account_id (AccountId , optional) – The account ID (takes priority if both venue and account_id are provided).
• Return type: Account or None

analyzer

The portfolios analyzer.

• Returns: PortfolioAnalyzer

balances_locked(self, Venue venue=None, AccountId account_id=None) → dict

Return the balances locked for the given venue or account ID (if found).

• Parameters:
  • venue (Venue , optional) – The venue for the account.
  • account_id (AccountId , optional) – The account ID (takes priority if both venue and account_id are provided).
• Return type: dict[Currency, Money] or None

dispose(self) → None

Dispose of the portfolio.

All stateful fields are reset to their initial value.

initialize_orders(self) → void

Initialize the portfolios orders.

Performs all account calculations for the current orders state.

initialize_positions(self) → void

Initialize the portfolios positions.

Performs all account calculations for the current position state.

initialized

If the portfolio is initialized.

• Returns: bool

is_completely_flat(self, AccountId account_id=None) → bool

Return a value indicating whether the portfolio is completely flat.

• Parameters: account_id (AccountId , optional) – The account ID. If None, checks across all accounts.
• Returns: True if net flat across all instruments, else False.
• Return type: bool

is_flat(self, InstrumentId instrument_id, AccountId account_id=None) → bool

Return a value indicating whether the portfolio is flat for the given instrument ID.

• Parameters:
  • instrument_id (InstrumentId) – The instrument query filter.
  • account_id (AccountId , optional) – The account ID. If None, aggregates across all accounts.
• Returns: True if net flat, else False.
• Return type: bool

is_net_long(self, InstrumentId instrument_id, AccountId account_id=None) → bool

Return a value indicating whether the portfolio is net long the given instrument ID.

• Parameters:
  • instrument_id (InstrumentId) – The instrument for the query.
  • account_id (AccountId , optional) – The account ID. If None, aggregates across all accounts.
• Returns: True if net long, else False.
• Return type: bool

is_net_short(self, InstrumentId instrument_id, AccountId account_id=None) → bool

Return a value indicating whether the portfolio is net short the given instrument ID.

• Parameters:
  • instrument_id (InstrumentId) – The instrument for the query.
  • account_id (AccountId , optional) – The account ID. If None, aggregates across all accounts.
• Returns: True if net short, else False.
• Return type: bool

margins_init(self, Venue venue=None, AccountId account_id=None) → dict

Return the initial (order) margins for the given venue or account ID (if found).

• Parameters:
  • venue (Venue , optional) – The venue for the account.
  • account_id (AccountId , optional) – The account ID (takes priority if both venue and account_id are provided).
• Return type: dict[Currency, Money] or None

margins_maint(self, Venue venue=None, AccountId account_id=None) → dict

Return the maintenance (position) margins for the given venue or account ID (if found).

• Parameters:
  • venue (Venue , optional) – The venue for the account.
  • account_id (AccountId , optional) – The account ID (takes priority if both venue and account_id are provided).
• Return type: dict[Currency, Money] or None

net_exposure(self, InstrumentId instrument_id, Price price=None, AccountId account_id=None, Currency target_currency=None) → Money

Return the net exposure for the given instrument (if found).

• Parameters:
  • instrument_id (InstrumentId) – The instrument for the calculation.
  • price (Price , optional) – The reference price for the calculation. This could be the last, mid, bid, ask, a mark-to-market price, or any other suitably representative value.
  • account_id (AccountId , optional) – The account ID for the net exposure.
  • target_currency (Currency , optional) – The currency to convert the exposure into.
• Return type: Money or None

net_exposures(self, Venue venue=None, AccountId account_id=None, Currency target_currency=None) → dict

Return the net exposures for the given venue (if found).

• Parameters:
  • venue (Venue , optional) – The venue for the market value.
  • account_id (AccountId , optional) – The account ID for the net exposures.
  • target_currency (Currency , optional) – The currency to convert the exposures into.
• Return type: dict[Currency, Money] or None

net_position(self, InstrumentId instrument_id, AccountId account_id=None)

Return the net position for the given instrument ID. If account_id is provided, returns the net position for that account. If account_id is None, aggregates across all accounts. If no positions for instrument_id then will return Decimal(‘0’).

• Parameters:
  • instrument_id (InstrumentId) – The instrument for the query.
  • account_id (AccountId , optional) – The account ID. If None, aggregates across all accounts.
• Return type: Decimal

on_order_event(self, OrderEvent event) → void

Actions to be performed on receiving an order event.

• Parameters: event (OrderEvent) – The event received.

on_position_event(self, PositionEvent event) → void

Actions to be performed on receiving a position event.

• Parameters: event (PositionEvent) – The event received.

realized_pnl(self, InstrumentId instrument_id, AccountId account_id=None, Currency target_currency=None) → Money

Return the realized PnL for the given instrument ID (if found).

• Parameters:
  • instrument_id (InstrumentId) – The instrument for the realized PnL.
  • account_id (AccountId , optional) – The account ID for the realized PnL. If None, aggregates across all accounts.
  • target_currency (Currency , optional) – The currency to convert the PnL into.
• Return type: Money or None

realized_pnls(self, Venue venue=None, AccountId account_id=None, Currency target_currency=None) → dict

Return the realized PnLs for the given venue (if found).

If no positions exist for the venue or if any lookups fail internally, an empty dictionary is returned.

• Parameters:
  • venue (Venue , optional) – The venue for the realized PnLs.
  • account_id (AccountId , optional) – The account ID for the realized PnLs.
  • target_currency (Currency , optional) – The currency to convert the PnLs into.
• Return type: dict[Currency, Money]

reset(self) → None

Reset the portfolio.

All stateful fields are reset to their initial value.

set_use_mark_prices(self, bool value) → void

Set the use_mark_prices setting with the given value.

• Parameters: value (bool) – The value to set.

set_use_mark_xrates(self, bool value) → void

Set the use_mark_xrates setting with the given value.

• Parameters: value (bool) – The value to set.

total_pnl(self, InstrumentId instrument_id, Price price=None, AccountId account_id=None, Currency target_currency=None) → Money

Return the total PnL for the given instrument ID (if found).

• Parameters:
  • instrument_id (InstrumentId) – The instrument for the total PnL.
  • price (Price , optional) – The reference price for the calculation. This could be the last, mid, bid, ask, a mark-to-market price, or any other suitably representative value.
  • account_id (AccountId , optional) – The account ID for the total PnL.
  • target_currency (Currency , optional) – The currency to convert the PnL into.
• Return type: Money or None

total_pnls(self, Venue venue=None, AccountId account_id=None, Currency target_currency=None) → dict

Return the total PnLs for the given venue (if found).

• Parameters:
  • venue (Venue , optional) – The venue for the total PnLs.
  • account_id (AccountId , optional) – The account ID for the total PnLs.
  • target_currency (Currency , optional) – The currency to convert the PnLs into.
• Return type: dict[Currency, Money]

unrealized_pnl(self, InstrumentId instrument_id, Price price=None, AccountId account_id=None, Currency target_currency=None) → Money

Return the unrealized PnL for the given instrument ID (if found).

• If price is provided, a fresh calculation is performed without using or updating the cache.
• If price is omitted, the method returns the cached PnL if available, or computes and caches it if not.

Returns None if the calculation fails (e.g., the account or instrument cannot be found), or zero-valued Money if no positions are open. Otherwise, it returns a Money object (usually in the account’s base currency or the instrument’s settlement currency).

• Parameters:
  • instrument_id (InstrumentId) – The instrument for the unrealized PnL.
  • price (Price , optional) – The reference price for the calculation. This could be the last, mid, bid, ask, a mark-to-market price, or any other suitably representative value.
  • account_id (AccountId , optional) – The account ID for the unrealized PnL. If None, aggregates across all accounts.
  • target_currency (Currency , optional) – The currency to convert the PnL into.
• Returns: The unrealized PnL or None if the calculation cannot be performed.
• Return type: Money or None

unrealized_pnls(self, Venue venue=None, AccountId account_id=None, Currency target_currency=None) → dict

Return the unrealized PnLs for the given venue (if found).

• Parameters:
  • venue (Venue , optional) – The venue for the unrealized PnLs.
  • account_id (AccountId , optional) – The account ID for the unrealized PnLs.
  • target_currency (Currency , optional) – The currency to convert the PnLs into.
• Return type: dict[Currency, Money]

update_account(self, AccountState event) → void

Apply the given account state.

• Parameters: event (AccountState) – The account state to apply.

update_bar(self, Bar bar) → void

Update the portfolio with the given bar.

Clears the cached unrealized PnL for the associated instrument, and performs any initialization calculations which may have been pending an update.

• Parameters: bar (Bar) – The bar to update with.

update_mark_price(self, mark_price) → void

Update the portfolio with the given mark price.

update_order(self, OrderEvent event) → void

Update the portfolio with the given order.

• Parameters: event (OrderEvent) – The event to update with.

update_position(self, PositionEvent event) → void

Update the portfolio with the given position event.

• Parameters: event (PositionEvent) – The event to update with.

update_quote_tick(self, QuoteTick tick) → void

Update the portfolio with the given quote tick.

Clears the cached unrealized PnL for the associated instrument, and performs any initialization calculations which may have been pending an update.

• Parameters: quote_tick (QuoteTick) – The quote tick to update with.

class PortfolioFacade

Bases: object

Provides a read-only facade for a Portfolio.

account(self, Venue venue=None, AccountId account_id=None) → Account

Abstract method (implement in subclass).

analyzer

The portfolios analyzer.

• Returns: PortfolioAnalyzer

balances_locked(self, Venue venue=None, AccountId account_id=None) → dict

Abstract method (implement in subclass).

initialized

If the portfolio is initialized.

• Returns: bool

is_completely_flat(self, AccountId account_id=None) → bool

Abstract method (implement in subclass).

is_flat(self, InstrumentId instrument_id, AccountId account_id=None) → bool

Abstract method (implement in subclass).

is_net_long(self, InstrumentId instrument_id, AccountId account_id=None) → bool

Abstract method (implement in subclass).

is_net_short(self, InstrumentId instrument_id, AccountId account_id=None) → bool

Abstract method (implement in subclass).

margins_init(self, Venue venue=None, AccountId account_id=None) → dict

Abstract method (implement in subclass).

margins_maint(self, Venue venue=None, AccountId account_id=None) → dict

Abstract method (implement in subclass).

net_exposure(self, InstrumentId instrument_id, Price price=None, AccountId account_id=None, Currency target_currency=None) → Money

Abstract method (implement in subclass).

net_exposures(self, Venue venue=None, AccountId account_id=None, Currency target_currency=None) → dict

Abstract method (implement in subclass).

net_position(self, InstrumentId instrument_id, AccountId account_id=None)

Abstract method (implement in subclass).

realized_pnl(self, InstrumentId instrument_id, AccountId account_id=None, Currency target_currency=None) → Money

Abstract method (implement in subclass).

realized_pnls(self, Venue venue=None, AccountId account_id=None, Currency target_currency=None) → dict

Abstract method (implement in subclass).

total_pnl(self, InstrumentId instrument_id, Price price=None, AccountId account_id=None, Currency target_currency=None) → Money

Abstract method (implement in subclass).

total_pnls(self, Venue venue=None, AccountId account_id=None, Currency target_currency=None) → dict

Abstract method (implement in subclass).

unrealized_pnl(self, InstrumentId instrument_id, Price price=None, AccountId account_id=None, Currency target_currency=None) → Money

Abstract method (implement in subclass).

unrealized_pnls(self, Venue venue=None, AccountId account_id=None, Currency target_currency=None) → dict

Abstract method (implement in subclass).