Portfolio

The Portfolio module is your central hub for account information. It tracks your current positions, active orders, and financial metrics (Balance, Equity, PnL) in real-time.

Read vs Write

Think of the Portfolio as your read-only view of the account state (Positions, PnL, Balance). To change the state (e.g., place orders, close positions), you use the Execution Engine.

Key Capabilities

Position Tracking

Monitor all open positions, including specific counts per symbol (Long/Short/Total).

Order Management

Track pending orders to avoid duplicate entries or manage grid strategies.

Account Financials

Real-time access to Account Balance, Equity, Unrealized PnL, and Realized PnL.

Risk Controls

Use current equity or position counts to enforce strategy-level risk limits (e.g., max 5 positions, stop trading at 5% drawdown).

Accessing Portfolio Data

In your strategy, the portfolio is accessible via the modules.PORTFOLIO object.

Check Open Positions

Before opening a new trade, it is common to check if you already have exposure in that symbol.

@strategy.custom_signal_engine(...)
def my_strategy(event: BarEvent, modules: Modules):
    # returns dict: {'BUY': int, 'SELL': int, 'TOTAL': int}
    positions = modules.PORTFOLIO.get_number_of_strategy_open_positions_by_symbol(event.symbol)

    # Only enter if flat
    if positions['TOTAL'] == 0:
        return [SignalEvent(...)]

    return []

Monitor Account Health

Adjust your trading behavior based on your account’s financial performance.

balance = modules.PORTFOLIO.get_account_balance()
equity = modules.PORTFOLIO.get_account_equity()

# Simple Drawdown Check
if equity < balance * 0.95:
    print("Drawdown > 5%, halting trading")
    return []

Pending Orders

Ensure you don’t stack multiple pending orders for the same signal.

orders = modules.PORTFOLIO.get_number_of_strategy_pending_orders_by_symbol(event.symbol)

if orders['TOTAL'] > 0:
    # We already have a limit/stop order waiting to fill
    return []

Common Use Cases

1. Max Positions Per Symbol

Limit the number of concurrent trades you take on a single instrument.

def check_max_positions(event, modules, max_positions: int) -> bool:
    counts = modules.PORTFOLIO.get_number_of_strategy_open_positions_by_symbol(event.symbol)

    return counts['TOTAL'] >= max_positions

2. Strategy-Wide Position Limit

Control the total number of concurrent trades you take across all instruments.

def check_portfolio_positions(event, modules, max_positions: int) -> bool:
    total_positions = 0
    universe = ['EURUSD', 'GBPUSD', 'SPX500', 'XAUUSD']

    for instrument in universe:
        p = modules.PORTFOLIO.get_number_of_strategy_open_positions_by_symbol(instrument)
        total_positions += p['TOTAL']

    return total_positions >= max_positions

3. Dynamic Position Sizing (Equity Based)

Pass current account equity to your sizing logic to maintain consistent risk per trade as the account grows (or shrinks).

# Conceptual example - sizing usually happens in the Sizing Engine
current_equity = modules.PORTFOLIO.get_account_equity()
risk_amount = current_equity * 0.01 # Risk 1% of current equity

Methods

Here is the complete list of methods available in the PORTFOLIO module.

Get Positions

Returns detailed objects for specific open positions, optionally filtering by symbol or ticket.

def get_positions(self, symbol: str = '', ticket: int = None) -> tuple[OpenPosition]

Parameter	Type	Description
symbol	str	Optional. Filter positions by this symbol.
ticket	int	Optional. Filter by a specific broker ticket ID.

Returns: A tuple of OpenPosition objects.

Get Pending Orders

Returns detailed objects for pending orders (Limit/Stop), optionally filtered.

def get_pending_orders(self, symbol: str = '', ticket: int = None) -> tuple[PendingOrder]

Parameter	Type	Description
symbol	str	Optional. Filter orders by this symbol.
ticket	int	Optional. Filter by a specific order ticket ID.

Returns: A tuple of PendingOrder objects.

Get Number Of Strategy Open Positions By Symbol

Quickly get the count of open positions for a symbol, broken down by side.

def get_number_of_strategy_open_positions_by_symbol(self, symbol: str) -> dict[str, int]

Parameter	Type	Description
symbol	str	The instrument symbol to check.

Returns: A dictionary with keys 'BUY', 'SELL', and 'TOTAL'.

Get Number Of Strategy Pending Orders By Symbol

Quickly get the count of pending orders for a symbol.

def get_number_of_strategy_pending_orders_by_symbol(self, symbol: str) -> dict[str, int]

Returns: A dictionary with keys 'BUY', 'SELL', and 'TOTAL'.

Get Account Balance

Returns the current “cash” balance of the account (realized PnL only).

def get_account_balance(self) -> Decimal

Get Account Equity

Returns the floating equity (Balance + Unrealized PnL).

def get_account_equity(self) -> Decimal

Get Account Unrealised PnL

Returns the current floating profit/loss across all open positions.

def get_account_unrealised_pnl(self) -> Decimal

Get Account Realised PnL

Returns the total profit/loss from closed trades.

def get_account_realised_pnl(self) -> Decimal