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) → Account

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

• Parameters: venue (Venue) – The venue for the account.
• Return type: Account or None

balances_locked(self, Venue venue) → dict

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

• Parameters: venue (Venue) – The venue for the margin.
• 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) → bool

Return a value indicating whether the portfolio is completely flat.

• Returns: True if net flat across all instruments, else False.
• Return type: bool

is_flat(self, InstrumentId instrument_id) → bool

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

• Parameters: instrument_id (InstrumentId) – The instrument query filter.
• Returns: True if net flat, else False.
• Return type: bool

is_net_long(self, InstrumentId instrument_id) → bool

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

• Parameters: instrument_id (InstrumentId) – The instrument for the query.
• Returns: True if net long, else False.
• Return type: bool

is_net_short(self, InstrumentId instrument_id) → bool

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

• Parameters: instrument_id (InstrumentId) – The instrument for the query.
• Returns: True if net short, else False.
• Return type: bool

margins_init(self, Venue venue) → dict

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

• Parameters: venue (Venue) – The venue for the margin.
• Return type: dict[Currency, Money] or None

margins_maint(self, Venue venue) → dict

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

• Parameters: venue (Venue) – The venue for the margin.
• Return type: dict[Currency, Money] or None

net_exposure(self, InstrumentId instrument_id, Price price=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.
• Return type: Money or None

net_exposures(self, Venue venue) → dict

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

• Parameters: venue (Venue) – The venue for the market value.
• Return type: dict[Currency, Money] or None

net_position(self, InstrumentId instrument_id)

Return the total net position for the given instrument ID. If no positions for instrument_id then will return Decimal(‘0’).

• Parameters: instrument_id (InstrumentId) – The instrument for the query.
• Return type: Decimal

realized_pnl(self, InstrumentId instrument_id) → Money

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

• Parameters: instrument_id (InstrumentId) – The instrument for the realized PnL.
• Return type: Money or None

realized_pnls(self, Venue venue) → 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) – The venue for the realized PnLs.
• Return type: dict[Currency, Money]

reset(self) → None

Reset the portfolio.

All stateful fields are reset to their initial value.

set_specific_venue(self, Venue venue) → void

Set a specific venue for the portfolio.

• Parameters: venue (Venue) – The specific venue to set.

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) → 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.
• Return type: Money or None

total_pnls(self, Venue venue) → dict

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

• Parameters: venue (Venue) – The venue for the total PnLs.
• Return type: dict[Currency, Money]

unrealized_pnl(self, InstrumentId instrument_id, Price price=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.
• Returns: The unrealized PnL or None if the calculation cannot be performed.
• Return type: Money or None

unrealized_pnls(self, Venue venue) → dict

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

• Parameters: venue (Venue) – The venue for the unrealized PnLs.
• 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

TBD

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) → Account

Abstract method (implement in subclass).

analyzer

The portfolios analyzer.

• Returns: PortfolioAnalyzer

balances_locked(self, Venue venue) → dict

Abstract method (implement in subclass).

initialized

If the portfolio is initialized.

• Returns: bool

is_completely_flat(self) → bool

Abstract method (implement in subclass).

is_flat(self, InstrumentId instrument_id) → bool

Abstract method (implement in subclass).

is_net_long(self, InstrumentId instrument_id) → bool

Abstract method (implement in subclass).

is_net_short(self, InstrumentId instrument_id) → bool

Abstract method (implement in subclass).

margins_init(self, Venue venue) → dict

Abstract method (implement in subclass).

margins_maint(self, Venue venue) → dict

Abstract method (implement in subclass).

net_exposure(self, InstrumentId instrument_id, Price price=None) → Money

Abstract method (implement in subclass).

net_exposures(self, Venue venue) → dict

Abstract method (implement in subclass).

net_position(self, InstrumentId instrument_id)

Abstract method (implement in subclass).

realized_pnl(self, InstrumentId instrument_id) → Money

Abstract method (implement in subclass).

realized_pnls(self, Venue venue) → dict

Abstract method (implement in subclass).

total_pnl(self, InstrumentId instrument_id, Price price=None) → Money

Abstract method (implement in subclass).

total_pnls(self, Venue venue) → dict

Abstract method (implement in subclass).

unrealized_pnl(self, InstrumentId instrument_id, Price price=None) → Money

Abstract method (implement in subclass).

unrealized_pnls(self, Venue venue) → 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) → Account

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

• Parameters: venue (Venue) – The venue for the account.
• Return type: Account or None

analyzer

The portfolios analyzer.

• Returns: PortfolioAnalyzer

balances_locked(self, Venue venue) → dict

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

• Parameters: venue (Venue) – The venue for the margin.
• 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) → bool

Return a value indicating whether the portfolio is completely flat.

• Returns: True if net flat across all instruments, else False.
• Return type: bool

is_flat(self, InstrumentId instrument_id) → bool

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

• Parameters: instrument_id (InstrumentId) – The instrument query filter.
• Returns: True if net flat, else False.
• Return type: bool

is_net_long(self, InstrumentId instrument_id) → bool

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

• Parameters: instrument_id (InstrumentId) – The instrument for the query.
• Returns: True if net long, else False.
• Return type: bool

is_net_short(self, InstrumentId instrument_id) → bool

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

• Parameters: instrument_id (InstrumentId) – The instrument for the query.
• Returns: True if net short, else False.
• Return type: bool

margins_init(self, Venue venue) → dict

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

• Parameters: venue (Venue) – The venue for the margin.
• Return type: dict[Currency, Money] or None

margins_maint(self, Venue venue) → dict

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

• Parameters: venue (Venue) – The venue for the margin.
• Return type: dict[Currency, Money] or None

net_exposure(self, InstrumentId instrument_id, Price price=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.
• Return type: Money or None

net_exposures(self, Venue venue) → dict

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

• Parameters: venue (Venue) – The venue for the market value.
• Return type: dict[Currency, Money] or None

net_position(self, InstrumentId instrument_id)

Return the total net position for the given instrument ID. If no positions for instrument_id then will return Decimal(‘0’).

• Parameters: instrument_id (InstrumentId) – The instrument for the query.
• Return type: Decimal

realized_pnl(self, InstrumentId instrument_id) → Money

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

• Parameters: instrument_id (InstrumentId) – The instrument for the realized PnL.
• Return type: Money or None

realized_pnls(self, Venue venue) → 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) – The venue for the realized PnLs.
• Return type: dict[Currency, Money]

reset(self) → None

Reset the portfolio.

All stateful fields are reset to their initial value.

set_specific_venue(self, Venue venue) → void

Set a specific venue for the portfolio.

• Parameters: venue (Venue) – The specific venue to set.

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) → 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.
• Return type: Money or None

total_pnls(self, Venue venue) → dict

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

• Parameters: venue (Venue) – The venue for the total PnLs.
• Return type: dict[Currency, Money]

unrealized_pnl(self, InstrumentId instrument_id, Price price=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.
• Returns: The unrealized PnL or None if the calculation cannot be performed.
• Return type: Money or None

unrealized_pnls(self, Venue venue) → dict

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

• Parameters: venue (Venue) – The venue for the unrealized PnLs.
• 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

TBD

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) → Account

Abstract method (implement in subclass).

analyzer

The portfolios analyzer.

• Returns: PortfolioAnalyzer

balances_locked(self, Venue venue) → dict

Abstract method (implement in subclass).

initialized

If the portfolio is initialized.

• Returns: bool

is_completely_flat(self) → bool

Abstract method (implement in subclass).

is_flat(self, InstrumentId instrument_id) → bool

Abstract method (implement in subclass).

is_net_long(self, InstrumentId instrument_id) → bool

Abstract method (implement in subclass).

is_net_short(self, InstrumentId instrument_id) → bool

Abstract method (implement in subclass).

margins_init(self, Venue venue) → dict

Abstract method (implement in subclass).

margins_maint(self, Venue venue) → dict

Abstract method (implement in subclass).

net_exposure(self, InstrumentId instrument_id, Price price=None) → Money

Abstract method (implement in subclass).

net_exposures(self, Venue venue) → dict

Abstract method (implement in subclass).

net_position(self, InstrumentId instrument_id)

Abstract method (implement in subclass).

realized_pnl(self, InstrumentId instrument_id) → Money

Abstract method (implement in subclass).

realized_pnls(self, Venue venue) → dict

Abstract method (implement in subclass).

total_pnl(self, InstrumentId instrument_id, Price price=None) → Money

Abstract method (implement in subclass).

total_pnls(self, Venue venue) → dict

Abstract method (implement in subclass).

unrealized_pnl(self, InstrumentId instrument_id, Price price=None) → Money

Abstract method (implement in subclass).

unrealized_pnls(self, Venue venue) → dict

Abstract method (implement in subclass).