Skip to content

State & account

Your position, account, persistent state, and signal proxies.

Start with the topic guide for worked examples. Signatures below show the available arguments.

position

your current position (dual-mode proxy)

Read the current single-instrument holding, or select an explicit member with position['TCS']. Multi-symbol scalar operations require a selected member. Fields are read-only; actions request changes. See positions.

Read-only properties

  • position.avg_entry — Deprecated alias of entry_price — kept for compatibility within this proxy. New code should use entry_price.
  • position.bars_held — Bars elapsed since the current position was opened. 0 when flat.
  • position.entry_bar — Observation index at entry; zero when flat or tracking is unavailable.
  • position.entry_price — Average entry price; zero when flat. Read position state before treating it as a price anchor.
  • position.entry_time — Entry timestamp; None when flat or tracking is unavailable.
  • position.is_flat — True when no material quantity is held.
  • position.is_long — True when the signed quantity is positive.
  • position.is_open — True when the position is not flat.
  • position.is_short — True when the signed quantity is negative.
  • position.max_drawdown_pct — Largest adverse excursion since entry as a percent number: 5.0 means 5%. Zero when flat or tracking is unavailable.
  • position.max_runup_pct — Largest favourable excursion since entry as a percent number: 5.0 means 5%. Zero when flat or tracking is unavailable.
  • position.peak — Peak price observed since entry. 0 when flat.
  • position.peak_price — Alias of peak — back-compat name within proxy.
  • position.qty — Current signed position quantity. 0 if flat, negative if short.
  • position.trough — Trough price observed since entry. 0 when flat.
  • position.trough_price — Alias of trough — back-compat name within proxy.
  • position.unrealized_pnl — Current unrealized P&L for this symbol's position.
  • position.value — Mark-to-market value of this position (qty × current price). Falls back to qty × entry_price when current price unavailable.

position.close(qty=None)

Flatten this position (or partial close if qty passed).

position.get(symbol: str, default=None)

Safe access — returns proxy if symbol has open qty, else default.

position.items()

Iterate (symbol, position_proxy) for open positions.

position.keys()

Sorted list of symbols with open qty (dict-like).

position.long(qty=None, **kwargs)

Request a long target for this selected instrument. Uses the same sizing/protection arguments as long.

position.set_stop(pct: float) -> None

Replace any registered stop with pct-loss-from-entry. Raises if flat. Silent replace if already registered.

position.set_target(pct: float) -> None

Replace any registered take-profit with pct-gain-from-entry. Raises if flat.

position.set_trail(pct: float) -> None

Replace any registered trailing stop with pct-from-anchor. Anchor is the current position's peak (long) or trough (short). Raises if flat.

position.short(qty=None, **kwargs)

Request a short target for this selected instrument. Uses the same sizing/protection arguments as short.

position.size_to(pct: float)

pct is a signed equity fraction for this selected instrument; 0.2 targets 20%. It can resize a continuing holding. This is allocation, not a take-profit distance.

position.values()

List of position proxies for open positions (dict-like).

portfolio

read-only account-level state

Read cash, marked equity and P&L from the portfolio view supplied to this run. These fields are read-only, and missing observations/funding can produce fallback values. See portfolio values.

Read-only properties

  • portfolio.cash — Cash/balance in the supplied accounting regime; not automatically available buying power.
  • portfolio.equity — Alias of portfolio.value, in account currency.
  • portfolio.realized_pnl — Cumulative realized P&L in account currency.
  • portfolio.return_pct — Return fraction: 0.05 means 5%. Uses (value - starting_capital) / starting_capital; zero starting capital returns zero.
  • portfolio.starting_capital — Recorded original funding; falls back to current cash when absent. Check recorded funding before interpreting return.
  • portfolio.unrealized_pnl — Account-currency MTM P&L across open positions.
  • portfolio.value — Portfolio equity under the portfolio's accounting regime.

state

mutable strategy memory between bars

Mutable attribute-based memory initialised by the second mapping returned from on_start(). It survives bars within a run and is per-symbol in broadcast mode. Restart restoration requires runtime support. This public proxy has no checkpoint/restore methods. See parameters and state.

state.to_dict() -> Dict[str, Any]

API snapshot method, but currently rejected in validated strategy drafts because .to_dict() triggers TS005. Read known state attributes for inspection instead. The API snapshot itself uses the current symbol's state in broadcast mode.

params

read-only configured strategy inputs

Read-only inputs initialised by the first mapping returned from on_start(). Attribute or dictionary access reads values; get can provide a default. See parameters and state.

params.get(name: str, default: Any = None) -> Any

Read a configured key, returning default if absent. It does not change the parameter mapping.

params.items()

Return configured name/value pairs.

params.keys()

Return the configured parameter names.

params.to_dict() -> Dict[str, Any]

API snapshot method, but currently rejected in validated strategy drafts because .to_dict() triggers TS005. Use dict(params.items()) for parameter inspection instead.

params.values()

Return configured parameter values.