Combine: one strategy across N symbols against ONE pot of capital.
Runs one strategy across a basket of symbols out of a single account. Each symbol's slice is a sleeve. The fetch fans out exactly like scan, then piner's PortfolioEngine drives N per-symbol engines on the union clock of all sleeves' bar times, reading back one portfolio equity curve, a merged symbol-tagged ledger, and a combined tearsheet. Two capital models select how sleeves share the pot: isolated (N sub-accounts; equals the per-symbol runs summed) and shared (one pot; sizing, funds checks, margin, and risk rules all read portfolio equity). For the full semantics and math, see How the portfolio model works.
pinerun portfolio <script.pine> --symbols <a,b,c> [options]| Flag | Default | Description |
|---|---|---|
--symbols a,b,c |
— | Basket in PRIORITY order — at equal timestamps earlier symbols fill first (spec S4). Supports full instrument addresses. |
--universe <file> |
— | Read the basket from a file, one symbol per line (blank lines and # comments ignored). Alternative to --symbols. |
--mode <m> |
isolated |
Capital model — isolated or shared. See Capital models. |
--capital <P> |
N × initial_capital | Total pot. Defaults to N times the script's initial_capital. |
--weights s=f,... |
equal | Per-symbol funding fractions, isolated mode only (e.g. BTCUSDT=0.5,ETHUSDT=0.3,SOLUSDT=0.2). Normalized; default equal-weight. |
--input name=value |
— | Fixed input override applied to every sleeve. One value each; repeatable (pass the flag once per input). |
--trades |
off | Also print the merged, symbol-tagged ledger. Over 20 trades elide to the first/last 5 rows. |
--no-chart |
off | Skip the in-terminal equity/drawdown/sleeve charts and the trade P/L histogram. MONTHLY RETURNS, MONTHLY TRADES, TOP DRAWDOWNS, and the isolated-mode SLEEVE RETURN CORRELATION matrix always print. |
--csv <dir> |
— | Write portfolio-trades.csv + portfolio-equity.csv plus per-sleeve CSVs into <dir>. |
--plot <dir> |
— | Write portfolio.html plus per-sleeve equity/drawdown charts into <dir>. |
isolated(default) — N sub-accounts, each fundedwᵢ·P. This equals running each symbol standalone and summing the equity curves; it is the equal-weight (or, with--weights, weighted-allocation) baseline. The engine reproduces that per-symbol sum bit-for-bit.shared— ONE pot.percent_of_equitysizing, funds checks, margin, andstrategy.risk.*rules all read portfolio equity, and sleeves compete for capital in basket (priority) order at each timestamp. This is a genuinely different backtest: one symbol's gains fund another's next entry, and an order can be rejected because an earlier sleeve already spent the cash. Trades can differ from any per-symbol run.
Without a source-requested Bar Magnifier, a symbol that fails to fetch is
dropped with a warning; under shared mode a smaller basket is a different
backtest, so the drop is called out loudly. When the source requests Bar
Magnifier, every requested sleeve must resolve or the whole portfolio aborts
before PortfolioSleeveSpec conversion. Strategy scripts only.
Portfolio has no v1-wide --bar-magnifier override. Each sleeve independently
resolves the strategy source's use_bar_magnifier declaration, complete chart
window, provider-specific exact dataset, and all static security dependencies
before the atomic engine run. A malformed/unsupported/provider-limited sleeve
or runtime-dynamic security identity aborts the basket; no magnified sleeve is
dropped and no smaller portfolio is reported as success.
Target/LTF timestamps are injected only into that sleeve and never join the
portfolio master clock, which remains the union of chart-bar opens in original
basket order. Piner is the sole fill, timestamp, and report authority; pinerun
does not invent intrabar ledger times. The shipped self-contained binary pins
the contract-capable @heyphat/piner 0.11.1 engine; exact sleeve preparation
still fails closed, and only piner can report active traversal.
The optional aggregate block is omitted when no sleeve requested magnification.
Otherwise per-sleeve authoritative blocks are retained and aggregate counters
are their sums. Coverage uses summed sleeve processed chart bars—not master-
clock length—as its denominator; state precedence is mixed-data-fallback,
then tv-cap-fallback, then complete (or no-data when none is active), and
the reported percentage is validated within 0–100%.
Plus shared flags — see common options:
- Data:
--tf·--from·--to·--limit·--provider·--asset-class·--data-dir·--csv-alignment·--csv-week-anchor·--csv-calendar·--csv-complete-record(exact CSV) (+ credentials) - Execution:
--backend·--concurrency·--no-security - Cache:
--no-cache·--cache-dir·--refresh - Metrics:
--periods-per-year·--risk-free-rate - Output:
--json
The terminal report opens with a combined tearsheet — RETURNS, RISK, and TRADES blocks computed on the portfolio equity curve and merged ledger — followed by a per-sleeve contribution table (SYMBOL, FUNDING, NET P/L, TRADES, CONTRIB%, RET-CORR). RET-CORR is each sleeve's per-bar return correlation with the portfolio in isolated mode (a diversification read); it reads na in shared mode, where every sleeve samples the one pot.
The tearsheet also prints MONTHLY RETURNS, MONTHLY TRADES (the merged ledger tallied by exit month as 5/3-style win/loss/even counts — green/red on a TTY, evens uncolored), and TOP DRAWDOWNS, plus — for an isolated-mode basket of two or more sleeves — the SLEEVE RETURN CORRELATION matrix of every pairwise per-bar return correlation (skipped in shared mode, where every pair reads 1.00). Unless --no-chart is set, it ends with in-terminal charts: the combined equity curve (braille line with a dashed initial-capital guide), the underwater drawdown, one cumulative-P/L sparkline per sleeve, and the trade P/L histogram — plain unicode, safe to pipe.
Portfolio drawdown/run-up are close-to-close on the combined curve in both modes: the sleeves' worst intrabar moments don't coincide and cross-symbol intrabar paths are unknowable, so this is the honest number. Per-sleeve reports keep their own intrabar extremes. There is no buy-&-hold benchmark — it's meaningless for a basket.
Artifacts. --csv <dir> writes portfolio-equity.csv (its bar column is the master clock) and portfolio-trades.csv (symbol-tagged, exit-time sorted; its entryBar/exitBar are sleeve-local indices, so join trades to the combined curve on entryTime/exitTime) plus per-sleeve <SYMBOL>-equity.csv/<SYMBOL>-trades.csv. --plot <dir> writes portfolio.html plus per-sleeve equity/drawdown charts.
JSON. --json emits the full PortfolioReport instead of the tearsheet:
equityCurve and times (chart-only master clock), initialCapital, summary,
metrics, trades (merged, symbol-tagged), sleeves (contribution plus each
optional authoritative Bar Magnifier block), optional aggregate barMagnifier
with its sleeve-sum denominator, fetchErrors, mode, and elapsedMs. A
permanent exact-mode abort is emitted as { ok: false, error, failure }.
Isolated baseline (default) — N equal-weight sub-accounts; equals running each symbol standalone and summing the curves, with RET-CORR reading diversification:
pinerun portfolio examples/sma-cross-param.pine \
--symbols BTCUSDT,ETHUSDT,SOLUSDT --tf 1h --limit 500For CSV sleeves, put use_bar_magnifier=true in the strategy header (portfolio
has no basket-wide override) and provide one explicit CSV evidence claim:
pinerun portfolio strategy.pine --symbols CSV:BTCUSDT,CSV:ETHUSDT --tf 1h \
--data-dir ./data --csv-alignment utc-24x7Which prints the combined tearsheet, the per-sleeve contribution table, the sleeve-correlation matrix, and the equity / drawdown / per-sleeve charts:
portfolio: 3 symbols @ 1h — mode=isolated, 30000.00 initial, 2026-06-21 → 2026-07-12
RETURNS
net profit -969.60 -3.23%
gross profit 3169.21 10.56%
gross loss 4138.81 13.80%
CAGR -43.92%
RISK
max drawdown 2824.37 9.36%
max runup 3508.08 12.82%
volatility (annual) 39.62%
sharpe -1.26
sortino -0.95
calmar -4.69
exposure 63.13%
(portfolio drawdown/run-up are close-to-close on the combined curve)
TRADES
closed trades 29 (8W 21L 0E)
win rate 27.59%
profit factor 0.77
expectancy -33.4346
avg win / loss 396.15 / 197.09
commission paid 0.0000
margin calls 0
SYMBOL FUNDING NET P/L TRADES CONTRIB% RET-CORR
--------------------------------------------------------------------
BTCUSDT 10000.00 -474.42 9 48.9 0.91
ETHUSDT 10000.00 -119.68 9 12.3 0.93
SOLUSDT 10000.00 -375.51 11 38.7 0.89
SLEEVE RETURN CORRELATION
BTCUSDT ETHUSDT SOLUSDT
BTCUSDT 1.00 0.87 0.68
ETHUSDT 0.87 1.00 0.70
SOLUSDT 0.68 0.70 1.00
MONTHLY RETURNS %
JAN FEB MAR APR MAY JUN JUL AUG SEP OCT NOV DEC YEAR
2026 · · · · · -6.3 3.2 · · · · · -3.2
MONTHLY TRADES (win/loss/even)
JAN FEB MAR APR MAY JUN JUL AUG SEP OCT NOV DEC YEAR
2026 · · · · · 4/10 6/8 · · · · · 10/18
TOP DRAWDOWNS
# DEPTH% PEAK TROUGH RECOVERY BARS
------------------------------------------------------
1 -9.36% 2026-06-24 2026-06-25 2026-07-03 215
2 -6.83% 2026-07-04 2026-07-09 — >183
3 -0.90% 2026-07-04 2026-07-04 2026-07-04 11
4 -0.82% 2026-07-03 2026-07-04 2026-07-04 8
5 -0.59% 2026-07-03 2026-07-03 2026-07-03 5
TRADE P/L DISTRIBUTION
857.56 → 1,029 ▇▇▇▇ 1
686.05 → 857.56 ▇▇▇▇ 1
514.54 → 686.05 ▇▇▇▇ 1
343.03 → 514.54 0
171.51 → 343.03 ▇▇▇▇▇▇▇▇▇▇▇ 3
0.00 → 171.51 ▇▇▇▇▇▇▇ 2
-154.77 → 0.00 ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 8
-309.54 → -154.77 ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ 11
-464.30 → -309.54 ▇▇▇▇▇▇▇ 2
EQUITY 30000.00 → 29030.40 (dashed = initial capital)
30,864 ┤ ⢠⣤⡄⡖⢦⣤⣀⣀
│ ⢀⣸ ⠉⠁ ⠸⢤
30,000 ┤⠤⠤⠤⠤⠤⠤⠤⠤⠤⡤ ⠤ ⠤ ⠤ ⠤ ⠤ ⠤ ⠤ ⢴⣆⡀⡼ ⠤ ⠤ ⠼⣆⡀⠤ ⠤ ⠤ ⠤ ⠤ ⠤
│ ⢧ ⢸⠉⠉⠁ ⢹⣀ ⢀⣀ ⣀
│ ⢸⣀⣀⡀ ⡼ ⠘⠋⠹⣄ ⢠⠞⢸⡤⠖⠚⢹
│ ⢳ ⣰⣦⠇ ⠘⠒⠒⠒⠒⠦⠞ ⠘⠋
│ ⢸ ⢀⣸⡇ ⡟⡆ ⡇
│ ⢸ ⢸⠙⠋⠉⠧⠤⠤⡄⣀⣤⡇⠙⠦⠤⢤⣸⠁
│ ⠈⠉⠉⠛ ⠙⠃
27,356 ┤
└2026-06-21 2026-07-01 2026-07-12
DRAWDOWN (close-to-close)
0% ┤⠉⠉⠉⠉⠉⠉⠉⠉⠉⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡟⠿⠿⠋⠋⠉⠛⠉⠻⠛⠛⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿
│ ⠘⠛⠛⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⣿⠃ ⠈⠛⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿
│ ⢸⣿⣿⡿⠿⠟⠏⣿⣿⣿⣿⣿⣿⠉⠿⣿⣿⣿⡿ ⠈⠈⠘⠻⠿⠿⠿⠿⠿⠏⠁⠘⠉⠉⠉⠸⠻
-9.36% ┤ ⠁ ⠉
SLEEVE cum P/L (closed trades)
BTCUSDT ██████▅▅▂▂▂▂▂▂▂▂▂▁▁▁▁▁▁▁▁▁███▄▂▂▁▁▁▁▁▁▁▃ -474.42
ETHUSDT ▆▆▆▆▆▆▄▄▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁██▇▇▆▄▄▄▄▄▄▄▄▅ -119.68
SOLUSDT ▆▆▆▆▆▆▃▃▁▁▁▁▂▂▂▁▁▂▂▂▂▂▂▂▂███▇▇▆▅▅▅▅▅▅▅▅▃ -375.51
3/3 sleeves combined annualized at 8766.00 periods/yr in 17ms
Shared pot — one account, sleeves compete for capital in basket (priority) order:
pinerun portfolio examples/sma-cross-param.pine \
--symbols BTCUSDT,ETHUSDT,SOLUSDT --tf 1h --limit 500 --mode shared --capital 30000Weighted isolated — fund BTC 50%, ETH 30%, SOL 20% of the pot (normalized):
pinerun portfolio examples/sma-cross-param.pine \
--symbols BTCUSDT,ETHUSDT,SOLUSDT --tf 1h --limit 500 \
--capital 30000 --weights BTCUSDT=0.5,ETHUSDT=0.3,SOLUSDT=0.2Basket from a universe file with a fixed input override applied to every sleeve:
pinerun portfolio examples/sma-cross-param.pine \
--universe universe.txt --tf 1d --limit 365 --input fast=10 --input slow=50Merged ledger plus CSV/HTML exports (portfolio-*.csv, portfolio.html, per-sleeve files):
pinerun portfolio examples/sma-cross-param.pine \
--symbols BTCUSDT,ETHUSDT,SOLUSDT --tf 1h --limit 500 --mode shared \
--trades --csv out/ --plot out/JSON — full report (equityCurve, summary, metrics, sleeves, fetchErrors) for piping:
pinerun portfolio examples/sma-cross-param.pine \
--symbols BTCUSDT,ETHUSDT,SOLUSDT --tf 1h --limit 500 --mode shared --json- How the portfolio model works — the capital models, union clock, and math in detail.
backtest— single-symbol tearsheet (a portfolio sleeve in isolation).scan— screen symbols independently instead of pooling capital.- Command index