Value ref
live_positionA metric of the CURRENTLY OPEN position, read live every bar (not a
frozen snapshot from entry — contrast entry_bar/sequence_step,
which capture a value once and hold it).
field selects: entry_price, bars_in_position,
unrealized_pnl_pct / unrealized_pnl_usd, or
max_excursion_pct / min_excursion_pct (the best/worst unrealized
PnL% reached since entry — MAE/MFE). All are NaN while flat.
bars_in_position counts the bars the position has been open in,
INCLUDING the bar it filled in: it is 1 at the close of the fill bar, not
0. An exit on bars_in_position >= N therefore decides at the close of
the Nth held bar and fills at the next bar's open, so the trade's
exit_bar - entry_bar is exactly N.
VIB-1398 / VIB-1370 / VIB-1319: the sub-metric selector is named
field across every ValueRef-style type. The legacy name
position_metric was removed (mirrors the IR-side
LivePositionRef.metric → field rename that VIB-1394 shipped).
Backing types
LivePositionValueRef
Required fields
fieldreqenum: entry_price, bars_in_position, unrealized_pnl_pct, unrealized_pnl_usd, max_excursion_pct, min_excursion_pct-Optional fields
kindstring-resolutionanyOf (2 variants)Optional higher-timeframe override for this value ref. Set it inside left/right refs such as {'kind': 'indicator', ..., 'resolution': '4h'} or {'kind': 'price', 'field': 'close', 'resolution': '4h'}. Do not put timeframe/source_timeframe on the parent condition. None = strategy timeframe.symbolanyOf (2 variants)Optional reference symbol this value ref reads from (e.g. 'SPY'). None = the traded/primary symbol. Mutually exclusive with resolution.Backing types
The IR ValueRef classes this builder field resolves to.