Skip to content

Latest commit

 

History

History

pinerun

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 
 
 
 
 

README.md

@heyphat/pinerun

The orchestration layer for the piner engine. Pinerun turns a single deterministic piner run into a programmable fan-out: run one Pine script across many symbols — or one script across many parameter sets on a single symbol — in parallel, then rank the results.

Because a piner run is a pure function of its source, chart/security/magnifier datasets, inputs, and execution options, every run is cacheable and reproducible — pinerun leans on that for memoization and for trivial parallelism across worker threads.

  • Browser-safe core (@heyphat/pinerun): the job model, the pure run primitive, an in-process runner, the ranker, the scan fan-out, the single-run backtest, the sweep parameter-optimization fan-out, and walkforward out-of-sample validation.
  • Node entry (@heyphat/pinerun/node): the WorkerPoolRunner (node:worker_threads) for real parallelism.
  • CLI (pinerun): seven verbs — init (scaffold a starter strategy), scan (screen many symbols), backtest (analyze one strategy deeply), compare (two strategies side by side), portfolio (one strategy, N symbols, one capital pot), sweep (optimize parameters), walkforward (validate the optimum out of sample) — plus upgrade (self-update the installed binary).

piner (@heyphat/piner) is a peer dependency; @heyphat/pinery is a regular dependency (used by scan / sweep to fetch history).

Prefer to drive these commands interactively? pinetop is a terminal UI over this CLI — one page per command, the flags editable beside the report, so an edit → rerun → reread loop does not mean retyping the invocation. It shells out to pinerun … --json and reuses the chart and tearsheet builders below, so its numbers are these numbers. Note that this makes the --json payload shapes and the exported renderers a contract with a second binary: changing one is a breaking change.

Install

The pinerun CLI ships as a single self-contained binary — the Bun runtime, the piner engine, and the pinery data layer are all baked in, so there is nothing else to install (no Node, no Bun, no npm):

curl -fsSL https://raw.githubusercontent.com/heyphat/pinestack/main/scripts/install.sh | sh

This downloads the right binary for your platform from the latest release into ~/.local/bin (override with PINERUN_INSTALL_DIR; pin a tag with PINERUN_VERSION=v0.1.0). Prebuilt targets: Linux and macOS on x64/arm64, plus a Windows x64 .exe from the Releases page. macOS users may need xattr -d com.apple.quarantine pinerun on an unsigned download. Once installed, pinerun upgrade updates the binary in place from the latest release (checksum-verified, atomic swap).

Build the binary from source

bun run build:bin              # this machine        → dist/pinerun
bun run build:bin --install    # this machine + copy onto your PATH
bun run build:bin linux-x64    # one target          → dist/pinerun-linux-x64
bun run build:bin all          # every platform      → dist/pinerun-<target>[.exe]
bun run build:bin --list       # supported targets

--install copies the host binary to a directory on your PATH (defaults to $PINERUN_INSTALL_DIR, then ~/.local/bin; override with --install=/usr/local/bin). Targets: linux-x64 linux-arm64 darwin-x64 darwin-arm64 windows-x64 (plus -musl / -baseline variants, e.g. linux-x64-musl for Alpine). Binaries are ~50–100 MB (the Bun runtime is embedded).

Programmatic use

The TypeScript workspace entry points are available when developing from a source checkout (bun install). Pinestack releases the self-contained pinerun binary; @heyphat/pinerun and @heyphat/pinery are not separately published npm artifacts. See Quick start for checkout-based API use.

Quick start (programmatic)

import { scan, LocalRunner } from '@heyphat/pinerun';
import { WorkerPoolRunner } from '@heyphat/pinerun/node';
import { BinanceProvider } from '@heyphat/pinery';

const source = `//@version=6
indicator("RSI scan")
plot(ta.rsi(close, 14), title="rsi")
`;

const runner = new WorkerPoolRunner({ size: 4 }); // or new LocalRunner()
try {
  const report = await scan({
    source,
    symbols: ['BTCUSDT', 'ETHUSDT', 'SOLUSDT'],
    timeframe: '1h',
    provider: new BinanceProvider(),
    range: { limit: 300 },
    rank: 'last(rsi)',
    top: 10,
    runner,
  });

  for (const { result, value } of report.ranked) {
    console.log(result.symbol, value);
  }
} finally {
  await runner.close();
}

Architecture

scan() is the orchestrator: it pulls history from pinery, resolves any exact lower-timeframe and static-security datasets before fan-out, sends work through a Runner, and ranks what comes back. Every run is a pure function of its complete serialized Job, which is what makes fan-out and memoization safe.

flowchart TB
  CLI["pinerun scan (CLI)"] --> SCAN
  APIU["scan() / Runner API"] --> SCAN

  SCAN["scan() orchestrator"]

  SCAN -->|"1. fetch history per symbol<br/>(bounded concurrency)"| PINERY
  PINERY["pinery HistoryProvider<br/>Binance / OKX / Kraken / Alpaca / Massive / CSV / Tiger futures"]
  PINERY <-->|"hit / miss"| DISK[("on-disk cache<br/>.pinery-cache")]
  PINERY -->|"Bar[]"| SCAN

  SCAN -->|"2. build Job[]<br/>{ source, symbol, tf, bars, inputs }"| RUNALL["runner.runAll(jobs)"]

  RUNALL --> FANOUT["fanOut()<br/>bounded concurrency + jobHash memo"]

  FANOUT --> POOL
  subgraph POOL["Runner backend (same interface)"]
    direction LR
    LOCAL["LocalRunner<br/>(in-process — browser/tests)"]
    WP["WorkerPoolRunner<br/>node:worker_threads × N"]
  end

  POOL -->|"one Job per worker"| EXEC
  subgraph EXEC["executeJob() — pure, per job"]
    direction TB
    C["compile(source)<br/>(compile-cache per worker)"] --> E["piner Engine.run(bars)"] --> P["project outputs<br/>→ RunResult"]
  end

  EXEC -->|"RunResult[]"| RANK["rankResults(spec)"]
  RANK --> REPORT["ScanReport<br/>→ ranked table / JSON"]
Loading

The fan-out, in ASCII — one compiled script, N symbols, run in parallel and collapsed to a ranked table:

                       one Pine source
                              │
        ┌──────────┬──────────┼──────────┬──────────┐
        ▼          ▼          ▼          ▼          ▼
     Job(BTC)   Job(ETH)   Job(SOL)   Job(BNB)   Job(XRP)     ← scan() builds jobs
        │          │          │          │          │            (bars fetched via pinery)
        ▼          ▼          ▼          ▼          ▼
   ┌─────────────────── worker pool (N threads) ───────────────────┐
   │  executeJob = compile(cache) → Engine.run(bars) → RunResult    │
   └────────────────────────────────────────────────────────────────┘
        │          │          │          │          │
        └──────────┴──────────┼──────────┴──────────┘
                              ▼
                     rankResults(spec)              ← e.g. last(rsi), desc, top 10
                              ▼
                       ranked table

Walkthrough of one scan:

  1. Fetch — scan() asks the pinery HistoryProvider for each symbol's bars (bounded concurrency). The Node disk cache serves repeats without hitting the API.
  2. Build jobs — each (symbol, bars) becomes a serializable Job carrying the Pine source string (not a compiled object — functions can't cross a worker boundary).
  3. Fan out — runner.runAll sends jobs through fanOut, which caps concurrency and memoizes by jobHash so complete execution-equivalent jobs never run twice.
  4. Execute — each worker runs the pure executeJob: compile the source (cached per worker, so one script scanned across N symbols compiles once per worker), run piner's Engine over the bars, and project the outputs into a RunResult.
  5. Rank — rankResults reduces each result to a scalar via the rank spec and sorts, producing the ScanReport the CLI prints as a table or JSON.

Tiger futures history is available for bare contracts with --provider tiger or per symbol with an address such as TG:FU:MGC. Pass --tiger-profile <path> to select a Tiger credential properties file; otherwise the SDK performs its normal current-directory then ~/.tigeropen/tiger_openapi_config.properties discovery. The provider is constructed lazily, so commands and routed symbols that never use Tiger do not load credentials. An explicit profile path participates in cache identity. The CLI supports Tiger's intraday futures history cadences (1m through 6h); it does not add exact-history evidence, so effective Bar Magnifier requests still fail closed unless the resolved source satisfies the exact contract.

The two runners implement the same Runner interface, so the identical scan runs in-process (LocalRunner, e.g. in a browser or a test) or across worker threads (WorkerPoolRunner, the CLI default) with no other change.

Concepts

Job — the unit of work

A fully serializable description of one run. It carries the Pine source string (never a compiled script — compiled bodies are functions and can't cross a worker boundary):

interface Job {
  id?: string; // defaults to `${symbol}@${timeframe}`
  source: string; // Pine v6 source
  symbol: string;
  timeframe: string; // piner timeframe label (see pinery toPinerTimeframe)
  bars: Bar[]; // OHLCV, ascending by time
  inputs?: Record<string, unknown>; // input overrides keyed by input title
  mintick?: number; // instrument tick size (default 0.01)
  minQty?: number; // instrument lot step — the broker's TV-parity quantity
  //                  truncation unit for derived order sizes and margin-call
  //                  liquidations (default 0.001)
  backend?: 'js' | 'interp'; // piner backend (default 'js')
  calcOnOrderFills?: boolean; // override the script's calc_on_order_fills
  //                  (TV "After order is filled"): true/false force it, unset
  //                  keeps the source header. Part of the determinism key.
  //                  Needs @heyphat/piner > 0.9.0 — an explicit override on an
  //                  older engine REJECTS the job with an actionable error
  useBarMagnifier?: boolean; // strict tri-state host override of the script's
  //                  use_bar_magnifier: unset keeps the header; true/false wins
  magnifier?: ResolvedMagnifierDataset; // exact, piner-ready LTF data resolved
  //                  before execution; includes chart closes, coverage,
  //                  provenance, contract/mapping versions, and acquisition key
}

RunResult — the result contract

A serializable projection of a piner run:

interface RunResult {
  id: string;
  symbol: string;
  timeframe: string;
  ok: boolean;
  bars: number; // bars executed
  plots: PlotResult[]; // { id, title, data: number[] } — NaN where `na`
  alerts: AlertResult[]; // { bar, message }
  strategy?: StrategySummary; // filled for strategy() scripts
  trades?: StrategyTrade[]; // closed-trade ledger — only when includeTrades
  equityCurve?: number[]; // per-bar equity — only when includeTrades
  barTimes?: number[]; // per-bar times aligned with equityCurve — only when includeTrades
  closes?: number[]; // per-bar close prices (price-chart input) — only when includeTrades
  securityRequests?: SecurityRequest[]; // request.security[_lower_tf] deps this run declared
  diagnostics?: string[]; // compile diagnostics ("error: ..." / "warning: ...")
  error?: string; // present when ok === false
  failure?: RunFailure; // serializable permanent Bar Magnifier / exact-history
  //                  rejection; ordinary compile/runtime errors keep `error`
  elapsedMs?: number;
}

interface StrategySummary {
  // sourced directly from piner's broker
  calcOnOrderFills?: boolean; // true ONLY when the engine actually ran
  //                  calc_on_order_fills (read from effective broker state,
  //                  never the requested configuration); omitted when off
  barMagnifier?: BarMagnifierSummary; // piner's optional authoritative report;
  //                  never inferred from the request or injected data
  initialCapital: number;
  netProfit: number;
  netProfitPercent: number;
  grossProfit: number;
  grossProfitPercent: number;
  grossLoss: number;
  grossLossPercent: number;
  profitFactor: number; // grossProfit / |grossLoss| (derived); Infinity if no losses
  wins: number;
  losses: number;
  closedTrades: number;
  winRate: number; // wins / (wins + losses), 0..1 (derived)
  avgTrade: number;
  avgTradePercent: number;
  avgWinningTrade: number;
  avgLosingTrade: number;
  maxDrawdown: number;
  maxDrawdownPercent: number; // peak-equity based (piner), matching TradingView
  maxRunup: number;
  maxRunupPercent: number;
  maxContractsHeld: number;
  evens: number; // break-even closed trades
  totalCommission: number; // TradingView's "Commission Paid"
  barsProcessed: number; // bars while the strategy was active
  barsInMarket: number; // bars with an open position
  metrics: StrategyMetrics; // derived analytics, computed BY PINER (below)
}

interface BarMagnifierSummary {
  requested: true;
  active: boolean;
  targetTimeframe: string; // piner's automatically mapped Pine timeframe
  magnifiedBars: number;
  fallbackBars: number;
  capFallbackBars: number;
  dataFallbackBars: number;
  intrabarsUsed: number;
  firstMagnifiedBar?: number;
  coverage: 'complete' | 'tv-cap-fallback' | 'mixed-data-fallback' | 'no-data';
}

type RunFailure = BarMagnifierFailure | ExactHistoryFailure;
// Both variants are serializable, permanent exact-boundary outcomes with a
// stable kind/code/message/details payload. Provider/network errors outside
// that boundary retain each command's existing bounded-retry/fetch behavior.

// piner's `Engine.strategyMetrics()` plus pinerun's normalized R-multiple
// fields — derived risk-adjusted analytics kept distinct from broker-verbatim
// numbers above.
interface StrategyMetrics {
  sharpe: number; // annualized, per-bar equity returns
  sortino: number; // Infinity when no downside and mean > 0
  volatilityPercent: number; // annualized return volatility
  arithmeticReturnPercent: number; // linearly annualized mean simple return
  geometricReturnPercent: number; // linearly annualized geometric mean return
  volatilityDragPercent: number; // arithmetic − geometric, percentage points
  cagrPercent: number;
  calmar: number; // CAGR % / max drawdown %
  exposurePercent: number; // barsInMarket / barsProcessed
  expectancy: number; // mean closed-trade profit
  rMultipleExpectancy: number | null; // mean net P&L / immutable initial risk
  rMultipleTradeCount: number; // closed-trade rows with valid initial risk
  maxConsecutiveWins: number;
  maxConsecutiveLosses: number;
  largestWin: number;
  largestLoss: number;
  avgBarsInTrade: number;
  buyHoldReturnPercent: number; // benchmark over the same bars
  outperformance: number; // net profit − buy-&-hold PnL on the same capital
  periodsPerYear: number; // the annualization actually used
}

arithmeticReturnPercent and geometricReturnPercent use the same finite per-bar simple-return sample and are both linearly scaled by periodsPerYear. Their exact nonnegative difference is volatilityDragPercent; this keeps the AM-GM identity intact. cagrPercent remains the separate endpoint-to-endpoint compound growth rate over the run's elapsed years. A negative gross return (r < -1) makes the geometric mean and drag unavailable (NaN in-process, null in JSON, na in the text tearsheet).

R-multiple fields require a piner engine that emits ClosedTrade.initialRisk. Older compatible engines remain supported and report null expectancy with zero coverage rather than deriving risk from max drawdown or another hindsight value.

executeJob(job) → Promise<RunResult>

The single, backend-agnostic run primitive: compiles the source (with a per-process compile cache), runs it over the job's bars via piner's Engine, and projects the outputs. Pure (piner-only, no I/O), so it runs identically in-process or inside a worker. Compile errors and runtime errors are captured into RunResult (ok: false) rather than thrown.

jobHash(job) → string

The determinism key is a strong full-content digest over the complete executable job: source, symbol/timeframe, chart and security bars, inputs, backend, instrument/metric/projection options, the tri-state overrides, and the resolved Bar Magnifier contract, mapping, chart-close, coverage, provenance, acquisition, and LTF-bar content. Equal jobs hash equally across local/worker paths; changing any execution-relevant byte changes the key. No sampled numeric digest or weak FNV shortcut is used.

Runners

All runners implement one interface:

interface Runner {
  run(job: Job): Promise<RunResult>;
  runAll(jobs: Job[], opts?: RunAllOptions): Promise<RunResult[]>;
  close(): Promise<void>;
}

interface RunAllOptions {
  concurrency?: number; // max jobs in flight (default: pool size; 4 for LocalRunner)
  onResult?: (r: RunResult, done: number, total: number) => void;
  noCache?: boolean; // skip determinism memo (default false)
}

LocalRunner

Runs jobs in-process (browser-safe). Ideal for tests, small scans, and the browser. runAll uses fanOut for bounded concurrency + per-hash memoization.

WorkerPoolRunner (@heyphat/pinerun/node)

Real parallelism via node:worker_threads. Same Runner contract, so it's a drop -in for LocalRunner. Each worker keeps its own compile cache, so scanning one script across N symbols compiles once per worker.

import { WorkerPoolRunner } from '@heyphat/pinerun/node';

const runner = new WorkerPoolRunner({ size: 8 }); // default: CPU count, clamped 1..16
// ... use runner.run / runner.runAll ...
await runner.close(); // terminate the pool when done

Note: always await runner.close() when finished, and if you drive a runner from a script's top level, use top-level await rather than a fire-and-forget promise — otherwise the runtime can tear down live worker threads before the promise settles.

fanOut(jobs, exec, opts?)

The shared bounded-concurrency scheduler with per-jobHash memoization. Both runners build on it; exported for custom execution strategies.

Ranking

Reduce each RunResult to a single scalar via a small, safe spec grammar (no eval) and sort.

import { parseRankSpec, evalRank, rankResults } from '@heyphat/pinerun';

Spec forms:

Spec Meaning
last(rsi) aggregate last over the plot titled rsi
max(#0) aggregate max over plot index 0 (id-sorted)
mean(close) aggregate mean over the plot titled close
last bare aggregate over the first plot
strategy.netProfit a strategy summary field (broker-verbatim)
strategy.sharpe a derived risk-adjusted metric

Aggregates: last first min max mean sum count (count = non-NaN samples). NaN values are ignored inside aggregates.

Strategy fields (broker-verbatim): initialCapital, netProfit, netProfitPercent, grossProfit, grossProfitPercent, grossLoss, grossLossPercent, profitFactor, wins, losses, evens, closedTrades, winRate, avgTrade, avgTradePercent, avgWinningTrade, avgLosingTrade, maxDrawdown, maxDrawdownPercent, maxRunup, maxRunupPercent, maxContractsHeld, totalCommission, barsProcessed, barsInMarket.

Derived metric fields (live under strategy.metrics on the summary, rank with the same flat strategy.<field> grammar): sharpe, sortino, volatilityPercent, arithmeticReturnPercent, geometricReturnPercent, volatilityDragPercent, cagrPercent, calmar, exposurePercent, expectancy, rMultipleExpectancy (null coverage ranks as NaN and is dropped — only stop-covered runs remain), maxConsecutiveWins, maxConsecutiveLosses, largestWin, largestLoss, avgBarsInTrade, buyHoldReturnPercent, outperformance.

const spec = parseRankSpec('last(rsi)');
const ranked = rankResults(results, spec, { direction: 'desc', top: 20 });
// RankedResult[] = { result: RunResult, value: number }[]

rankResults options: direction ('asc'|'desc', default desc), top (keep top N), dropNaN (drop failed/empty results, default true).

scan(options) → ScanReport

The flagship fan-out: fetch history for each symbol, build jobs, run them through a Runner, and rank. Browser-safe (pass any HistoryProvider and any Runner).

interface ScanOptions {
  source: string;
  symbols: string[];
  timeframe: string; // canonical pinery tf (e.g. "1h"), mapped internally
  provider: HistoryProvider;
  range?: HistoryRange;
  rank?: string; // rank spec, default "last"
  calcOnOrderFills?: boolean; // host override of the script's
  //                  calc_on_order_fills (unset → source header decides);
  //                  needs piner > 0.9.0, rejected otherwise
  useBarMagnifier?: boolean; // strict tri-state host override; target timeframe
  //                  is always piner's automatic TradingView mapping
  direction?: 'asc' | 'desc';
  top?: number;
  concurrency?: number; // job execution default: worker-pool size (4 for LocalRunner)
  backend?: 'js' | 'interp';
  inputs?: Record<string, unknown>;
  mintick?: number; // tick-size override; unset → provider instrument metadata
  minQty?: number; // lot-step override; unset → provider instrument metadata
  includeTrades?: boolean; // attach ledger + equity curve (strategies)
  metrics?: JobMetricsOptions; // { periodsPerYear?, riskFreeRate? } for derived metrics
  runner?: Runner; // default new LocalRunner()
  onResult?: (r, done, total) => void;
  onFetch?: (symbol, bars) => void;
  onFetchError?: (symbol, error) => void;
}

interface ScanReport {
  spec: RankSpec;
  ranked: RankedResult[]; // sorted, top-N applied
  results: RunResult[]; // every run (incl. failures), symbol order
  errors: RunResult[]; // compile/runtime and typed exact-mode failures
  fetchErrors: { symbol: string; error: string }[];
}

scan maps the canonical timeframe to piner's label with pinery's toPinerTimeframe. Ordinary mode fetches with bounded concurrency and preserves its established per-symbol fetchErrors behavior. When Bar Magnifier is effective, every symbol is preflighted and resolved exactly before fan-out; unsupported, malformed, dynamic-security, or provider-limited symbols remain in results/errors as typed failures rather than silently shrinking the universe.

On a live terminal, long scan and sweep runs show a self-erasing progress line on stderr (scan: 132/500 ran · 2 errors · 12.3s · ~40s left); when stderr is piped (CI, logs) it never prints, so captured output stays clean.

CLI

Once installed, invoke the pinerun binary directly:

pinerun init        [file.pine]    [options]
pinerun scan        <script.pine> [options]
pinerun backtest    <script.pine> [options]
pinerun compare     <a.pine> <b.pine> [options]
pinerun portfolio   <script.pine> [options]
pinerun sweep       <script.pine> [options]
pinerun walkforward <script.pine> [options]
pinerun upgrade     [--check]

Every command takes --help for its full flag list (e.g. pinerun scan --help), and pinerun --version (or -v) prints the CLI version and build commit. During development, run the CLI straight from source instead of building the binary: bun packages/pinerun/src/cli.ts <command> ….

Bar Magnifier exact mode

backtest, compare, scan, sweep, and walkforward accept strict tri-state --bar-magnifier / --no-bar-magnifier flags (including explicit boolean forms). Absent means the source's strategy(use_bar_magnifier=...) declaration decides; true or false overrides it. compare applies one shared override while keeping each source header independent. No custom target timeframe is accepted: piner's versioned TradingView mapping chooses it automatically. portfolio has no basket-wide v1 override; each sleeve follows the source declaration, and the CLI rejects either portfolio flag before script/provider I/O.

Pinerun performs metadata preflight, resolves every static request.security[_lower_tf] dependency through the coverage-aware exact seam, and acquires a complete mapped dataset before execution or fan-out. Runtime- dynamic security identities, unsupported alignment/timeframes, malformed data, incomplete coverage, gaps/truncation, and provider limits fail closed as typed permanent outcomes. Ordinary non-magnifier security discovery still uses the legacy history(): Bar[] path. Backtest/compare fail, watch stops, portfolio aborts atomically, and scan/sweep/walk-forward retain explicit failed runs or folds. Transient provider/network handling outside the exact boundary is unchanged.

Walk-forward acquires one complete IS+OOS dataset per fold before ranking. At most 200,000 eligible mapped target bars are allowed (200,000 succeeds; 200,001 fails), including a cap boundary that falls inside IS. Portfolio resolves every requested sleeve before creating engine specs, keeps LTF times out of the master clock, and reports coverage against the sum of sleeve processed chart bars.

Runtime and release matrix

Runtime Effective request
Shipped self-contained binary / this root checkout: @heyphat/piner 0.11.1 Contract-capable with traversal enabled. Pinerun maps, acquires, validates, and injects the exact dataset; piner alone reports whether magnification was active and owns target, counters, coverage, and fill timestamps.
Older or contract-incomplete piner Permanent piner-bar-magnifier-capability-unavailable during metadata preflight, before exact provider/static-security I/O or piner execution. No exact dataset is prepared. Explicit/source-effective false continues on chart OHLC.
Future contract-capable piner, traversal disabled May map, prepare, validate, and inject exact data, but piner must report requested: true, active: false; fills remain chart OHLC.

The release binary bakes in the Bun runtime, pinery, and the root-pinned piner version. Workspace packages are source/API entry points, not independently published npm artifacts that can replace the engine inside an existing binary.

Provider matrix behind the runtime gate

Provider Exact source evidence Limits / current posture
Binance spot UTC 24×7; 1s plus 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w 1,000/page, newest-first, default 50,000 source-bar cap.
Binance futures UTC 24×7; same common list, no 1s 1,000/page, default 50,000 source-bar cap.
OKX spot/swap UTC variants; 1s, common minute/hour steps, 1d, 2d, 3d, 1w 300/page recent, 100/page history, 200 pages; default effective 50,000 cap (60,000 page-capacity ceiling).
Kraken spot UTC 24×7; 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w, 15d Recent 720 bars only; older requested coverage fails provider-limited.
Alpaca / Massive Advertised equity cadences through weekly Alignment is unknown without versioned exchange-session evidence, so exact planning fails closed. Their feed/adjustment and cap settings remain part of source identity.
Static / CSV Default: unknown alignment and no declared exact timeframes Programmatic callers must provide alignment/timeframe evidence (plus a calendar for exchange alignment); content is fingerprinted and cacheIdentity can version the dataset. The CLI's --data-dir leaf discovers exact <SYMBOL>_<TF>.csv files and accepts explicit evidence: --csv-alignment utc-24x7, --csv-week-anchor, --csv-calendar <file.json>, and the authenticated --csv-complete-record assertion.
Legacy provider No resolveHistorySource exact contract Rejected in exact mode; non-magnifier history() behavior is preserved.

Provider caps apply to acquired source bars and are independent of piner's 200,000 eligible target-bar cap; either limit fails rather than attaching a partial fragment. See the complete provider lists and evidence requirements in common options.

Results mirror only piner's optional authoritative strategy.barMagnifier block. formatFillModel() distinguishes standard chart OHLC, requested/inactive, and active states without inspecting injected data. The shipped 0.11.1 runtime can report active traversal after exact preparation. A compatible but traversal-disabled runtime may prepare exact data and then authoritatively report requested/inactive; only an enabled piner report can claim active magnification.

Provider exactness is not TradingView-feed parity. Matching TradingView also requires its feed, sessions/calendar, timezone, adjustment policy, and OHLC construction; TradingView-observed fixtures remain the semantic parity evidence.

init — scaffold a starter strategy

New to Pine? init writes a complete, heavily commented strategy() you can run immediately — no Pine writing required. The scaffold explains how a strategy works (inputs, per-bar execution, entries/exits) and opens with copy-paste backtest / sweep / walkforward recipes whose --input names already match the script's input() titles.

pinerun init                              # → strategy.pine (SMA cross)
pinerun init rsi-bot.pine --template rsi  # a commented RSI starter
--template <name>     Starter to scaffold (default sma-cross):
                        sma-cross (trend) | rsi (mean-reversion) |
                        bollinger (breakout) | macd (momentum)
--name "Title"        strategy() title (default: a per-template label)
--force               Overwrite the file if it already exists
--stdout              Print the source to stdout instead of writing a file

It refuses to clobber an existing file without --force, and --stdout prints the source without writing (pipe or preview). The four templates mirror the examples/ strategy library. Programmatic: starterStrategy({ template, name }) in scaffold.ts is a pure, browser-safe string builder — only the CLI touches the filesystem.

scan

--symbols a,b,c       Inline symbol list (comma/space separated)
--universe <file>     File of symbols (one per line; # comments allowed)
--tf <1h>             Timeframe: 1m 5m 15m 1h 4h 1d 1w (default 1h)
--from <date>         Start (ISO date or unix seconds)
--to <date>           End (ISO date or unix seconds)
--limit <n>           Max bars per symbol
--rank <spec>         Ranking spec (default "last"), e.g. last(rsi), max(#0),
                        strategy.netProfit, strategy.sharpe
--top <n>             Keep only the top N
--asc                 Sort ascending (default descending)
--trades              Attach the closed-trade ledger + equity curve (a single-
                        symbol scan prints a PRICE chart + ledger; always in --json)
--no-chart            Skip the table sparklines — indicator scans get a SERIES
                        column (the ranked plot, per symbol); strategy scans
                        get an EQUITY column when the curve is retained
                        (--trades / --csv / --plot) — and the PRICE chart a
                        single-symbol --trades scan prints above its ledger
--periods-per-year <n> Metrics annualization override (e.g. 252 daily US-equity
                        bars; default: empirical bar times / 24/7 timeframe)
--risk-free-rate <r>  Annual risk-free rate for Sharpe/Sortino, as a fraction
                        (e.g. 0.02; default 0)
--csv <dir>           Write <label>-trades.csv + <label>-equity.csv per ranked
                        strategy result (pandas/Excel-ready; implies --trades)
--plot <dir>          Write a self-contained <label>.html equity + drawdown
                        chart per ranked strategy result (implies --trades)
--concurrency <n>     Max jobs in flight (default = workers)
--workers <n|local>   Worker threads (default = CPUs; "local" = in-process)
--backend js|interp   piner backend (default js)
--provider binance    Data provider (default binance): binance | okx | kraken |
                        alpaca | massive | csv
--asset-class <cls>   Asset class for multi-class providers (binance/okx:
                        crypto | futures; default: the provider's default)
--data-dir <dir>      Local CSV history for --provider csv / CSV: symbols
                        (one <SYMBOL>_<TF>.csv per instrument)
--csv-alignment utc-24x7
                      Assert CSV bars use the fixed UTC 24×7 grid (enables
                        exact planning over CSV files)
--csv-week-anchor <YYYY-MM-DD|seconds>
                      Opening timestamp on the CSV weekly grid (requires
                        --csv-alignment utc-24x7)
--csv-calendar <file.json>
                      Strict exchange-session calendar; conflicts with the
                        UTC alignment/week-anchor flags
--csv-complete-record Assert missing bars inside each exact file's span mean
                        no trades (requires explicit alignment/calendar)
--no-cache            Disable the on-disk history cache
--no-security         Skip request.security resolution (cross-symbol / lower-TF
                        fetch + inject); those requests degrade to na
--cache-dir <dir>     Cache directory (default .pinery-cache)
--refresh             Refresh cached history
--json                Emit JSON instead of a table

--symbols and --universe may be combined; symbols are de-duplicated. By default history is fetched through the Binance provider wrapped in pinery's on-disk cache, so repeat scans hit no network.

Credentials for the equities providers (security)

The crypto exchanges (Binance / OKX / Kraken) need no key. Alpaca and Massive do — and the safe way to supply it is environment variables, not CLI flags. A key passed as --api-key/--api-secret is written to your shell history file and is visible to anyone who can run ps, so prefer:

export ALPACA_API_KEY_ID=…                # Alpaca key id
export ALPACA_API_SECRET_KEY=…            # Alpaca secret
export MASSIVE_API_KEY=…                   # Massive key
# then just name the provider — no key on the command line:
pinerun scan strat.pine --provider alpaca --symbols AAPL,MSFT --tf 1d

The equities adapters read these env vars automatically when the flag is absent. --api-key/--api-secret/--feed iex|sip still exist (scripted/CI use, or overriding an env var) but the CLI prints a warning when a credential is passed on the command line — treat that as a nudge to switch to the env vars above.

Examples

# Rank a symbol list by current RSI, top 10, across worker threads
pinerun scan examples/rsi.pine \
  --symbols BTCUSDT,ETHUSDT,SOLUSDT,BNBUSDT,XRPUSDT \
  --tf 1h --limit 300 --rank "last(rsi)" --top 10

# Read symbols from a file, a fixed date range, JSON output for piping
pinerun scan rsi.pine \
  --universe universe.txt --tf 1d --from 2023-01-01 --to 2024-01-01 \
  --rank "mean(rsi)" --json

# Deterministic in-process run (no worker threads)
pinerun scan rsi.pine --symbols BTCUSDT --workers local

# Backtest a strategy across a universe, ranked by net profit
pinerun scan examples/sma-cross-param.pine \
  --symbols BTCUSDT,ETHUSDT,SOLUSDT,BNBUSDT,XRPUSDT \
  --tf 1h --limit 500 --rank "strategy.netProfit" --top 3

Sample table output:

  #  SYMBOL            VALUE  BARS  SERIES
  ------------------------------------------------------
   1 ETHUSDT         50.9528  299    ▂▆▇█▇█▇▅▆▄▄▅▄▄▅█▆█▅
   2 BTCUSDT         47.3813  299    ▂▅██▆█▇▅▅▄▅▆▄▄▇█▆▆▅
   3 BNBUSDT         43.2215  299    ▂▅▇█▆█▇▅█▄▅▆▃▅▆▇▅▇▅
   4 SOLUSDT         40.1425  299    ▂▆▇▇▆▇▄▃▅▄▅▅▂▃▅▇▄▅▄
   5 XRPUSDT         38.3130  299    ▂▆▇█▆█▇▄▄▄▄▄▂▄▅▇▅▆▃

  rank="last(rsi)"  5/5 ran  5 ranked  in 48ms

sweep

--symbol <sym>        Single symbol to backtest across the grid
--symbols a,b,c       Multi-symbol grid: every combo on every symbol (the symbol
                        becomes an implicit axis; bars fetched once per symbol)
--universe <file>     File of symbols for the multi-symbol grid (as scan)
--input name=spec     Swept input axis (REPEATABLE): list (fast=5,10,20) or
                        range (slow=30:100:10); name must match a Pine input() title
--sample <n>          Smart search: run n randomly sampled combos instead of the
                        exhaustive grid (the --max-combos guard applies to n)
--seed <n>            PRNG seed for --sample (default 42; same seed → same combos)
--heatmap             Print the 2-axis optimization surface as a value grid
                        (requires exactly two --input axes)
--points-csv <file>   Write every run as one CSV row (symbol, axes, value,
                        strategy stats, error) — pandas-ready, no ledgers needed
--tf <1h>             Timeframe (default 1h)
--from/--to/--limit   History window
--rank <spec>         Metric to optimize (default strategy.netProfit for a
                        strategy, else "last"), e.g. strategy.profitFactor,
                        strategy.sharpe
--top <n>             Keep only the top N combos
--asc                 Sort ascending (default descending)
--periods-per-year <n>  Metrics annualization override (as scan)
--risk-free-rate <r>  Annual risk-free rate for Sharpe/Sortino (as scan)
--csv <dir> / --plot <dir>  Per-combo CSV / HTML exports (as scan, labeled
                        <symbol>-<combo>)
--max-combos <n>      Cap on total runs: combos × symbols (default 5000; checked
                        before fetch)
--trades              Attach ledger + equity curve; prints the winning combo's
                        PRICE chart + ledger, and adds an EQUITY sparkline
                        column to the ranked table
--no-chart            Skip the table sparklines (EQUITY / SERIES columns) and
                        the winning combo's PRICE chart
--concurrency <n>     Max jobs in flight (default = workers)
--workers <n|local>   Worker threads (default = CPUs; "local" = in-process)
--backend js|interp   piner backend (default js)
--provider <name>     Data provider (default binance)
--no-security         Skip request.security resolution
--no-cache            Disable the on-disk history cache
--cache-dir <dir>     Cache directory (default .pinery-cache)
--refresh             Refresh cached history
--json                Emit JSON instead of a table

See Sweep — parameter optimization for the axis grammar, examples, and the programmatic API.

Strategies

pinerun runs Pine strategies as well as indicators. When a scanned script is a strategy(...), executeJob drives piner's broker over the bars and attaches a StrategySummary (see the result contract above) to each RunResult. Every metric is read straight off piner (the strategy.* namespace, the broker's own profitFactor / winRate convenience getters, and Engine.strategyMetrics() for the derived risk-adjusted block under strategy.metrics) — pinerun performs no strategy calculations of its own, so all numbers match what a Pine script / TradingView reports (e.g. maxDrawdownPercent is peak-equity based). A strategy scan is a parallel multi-symbol backtest: one strategy, N symbols, ranked by performance.

The derived metrics annualize from the run's real bar times by default; pass --periods-per-year (e.g. 252 for daily US-equity bars) and/or --risk-free-rate (annual fraction, e.g. 0.02) — or scan({ metrics: { periodsPerYear, riskFreeRate } }) — to apply a market-calendar convention.

Rank by any summary metric via the strategy.<field> spec — strategy.netProfit, strategy.profitFactor, strategy.winRate, and the derived strategy.sharpe, strategy.sortino, strategy.calmar, strategy.cagrPercent, strategy.arithmeticReturnPercent, strategy.geometricReturnPercent, strategy.volatilityDragPercent, strategy.rMultipleExpectancy, strategy.outperformance, plus the rest listed under Ranking. The CLI auto-detects a strategy scan, defaults the rank to strategy.netProfit (unless you pass --rank), and prints a backtest table instead of the single-value table:

# examples/sma-cross-param.pine — an SMA crossover strategy
pinerun scan examples/sma-cross-param.pine \
  --symbols BTCUSDT,ETHUSDT,SOLUSDT,BNBUSDT,XRPUSDT --tf 1h --limit 500
  #  SYMBOL        NET P/L      NET %  TRADES    WIN%    MAXDD%       PF   SHARPE      B&H %
  ------------------------------------------------------------------------------------------
   1 SOLUSDT        946.98      9.47%       8  50.00%    12.50%     2.06     3.25     17.90%
   2 XRPUSDT       -559.68     -5.60%       5  40.00%     8.00%     0.19     1.43     -0.64%
   3 BTCUSDT       -576.31     -5.76%       7  28.57%     9.51%     0.18     0.46     -2.67%
   4 BNBUSDT       -764.15     -7.64%       7  14.29%    12.06%     0.17    -2.90     -6.57%
   5 ETHUSDT       -861.44     -8.61%       7  28.57%    12.39%     0.13     0.82      5.37%

  rank="strategy.netProfit"  5/5 ran  5 ranked  in 177ms

Trade ledger + equity curve

Pass --trades (or scan({ includeTrades: true })) to attach the full closed-trade ledger (result.trades), per-bar equity curve (result.equityCurve), and close prices (result.closes). On a single-symbol scan the CLI prints the PRICE chart (close line with the trades marked at their fill prices, as in backtest) followed by the ledger; with --json everything is always included. Printed ledgers longer than 20 trades elide to the first and last 5 rows with an … row carrying the omitted count — the full ledger always lives in --csv / --json.

pinerun scan examples/sma-cross-param.pine \
  --symbols SOLUSDT --tf 1h --limit 500 --trades
  trades for SOLUSDT (8):
   #  DIR           QTY         ENTRY          EXIT        PROFIT           CUM        FEES
  -----------------------------------------------------------------------------------------
   1  long       144.91       69.0100       73.5300        654.98        654.98      0.0000
   2  long       144.20       73.8900       73.2800      -87.9623        567.02      0.0000
   ...
   8  long       133.11       75.4800       82.2400        899.82        946.98      0.0000

Each StrategyTrade is { entryId, dir (+1/-1), qty, entryPrice, exitPrice, entryBar, exitBar, entryTime, exitTime, profit, cumProfit, commission, maxRunup, maxDrawdown, initialRisk, rMultiple } — fill times are bar-time ms, commission is both sides' fees on the row, and the R fields are null when no valid initial protective stop/loss applied to that entry lot. maxRunup/maxDrawdown remain the hindsight trade-life intrabar excursions and are never used as risk.

Programmatically:

import { scan } from '@heyphat/pinerun';
import { BinanceProvider } from '@heyphat/pinery';
import { readFileSync } from 'node:fs';

const report = await scan({
  source: readFileSync('examples/sma-cross-param.pine', 'utf8'),
  symbols: ['BTCUSDT', 'ETHUSDT', 'SOLUSDT'],
  timeframe: '1h',
  provider: new BinanceProvider(),
  range: { limit: 500 },
  rank: 'strategy.profitFactor',
  includeTrades: true,
});

for (const { result } of report.ranked) {
  const s = result.strategy!;
  console.log(
    result.symbol,
    s.netProfit.toFixed(2),
    `${s.netProfitPercent.toFixed(1)}%`,
    `PF ${s.profitFactor.toFixed(2)}`,
    `${result.trades!.length} trades`,
  );
}

StrategySummary + the ledger are a projection of piner's broker report. For deeper detail (OCA groups, per-order events, intrabar equity), run piner's Engine directly — pinerun's executeJob is a thin wrapper over it.

CSV export + equity plot

--csv <dir> and --plot <dir> (both imply --trades) export every ranked strategy result — top-N applied, indicator scripts skipped:

pinerun scan examples/sma-cross-param.pine \
  --symbols SOLUSDT,BTCUSDT --tf 1h --limit 500 --csv out/ --plot out/
# out/SOLUSDT-trades.csv  out/SOLUSDT-equity.csv  out/SOLUSDT.html  (and BTCUSDT…)
  • <label>-trades.csv — the full ledger, one row per closed trade: symbol,entryId,dir,qty,entryPrice,exitPrice,entryBar,exitBar,entryTime,exitTime,profit,cumProfit,commission,maxRunup,maxDrawdown (times as ISO 8601 UTC, RFC 4180 quoting).
  • <label>-equity.csv — bar,time,equity, every bar emitted; bars before the strategy activated have an empty equity cell (pandas reads NaN).
  • <label>.html — a dependency-free page: equity curve with the initial-capital reference and green/red per-trade exit markers, over an underwater drawdown-% chart.

On sweep the label is <symbol>-<combo> (e.g. BTCUSDT-fast=10_slow=50), so a --top 10 --csv out/ sweep drops the ten best combos' ledgers side by side.

import pandas as pd
trades = pd.read_csv('out/SOLUSDT-trades.csv', parse_dates=['entryTime', 'exitTime'])
equity = pd.read_csv('out/SOLUSDT-equity.csv', parse_dates=['time'], index_col='time')

The underlying builders are exported, pure, and browser-safe — the CLI only adds the file writes: tradesToCsv(result), equityToCsv(result), and equityPlotHtml(result, { title? }) each return a string from a RunResult that carries trades / equityCurve / barTimes (i.e. ran with includeTrades).

Backtest — single-strategy tearsheet

Where scan answers "which symbols does this strategy work on?", backtest answers "how good is this strategy, exactly?" — one script, one symbol, full detail:

pinerun backtest examples/sma-cross-param.pine \
  --symbol SOLUSDT --tf 1h --limit 500
  backtest: SOLUSDT @ 1h — 500 bars, 2026-06-14 → 2026-07-05

  RETURNS
    net profit                  946.98       9.47%
    gross profit               1838.98      18.39%
    gross loss                  892.00       8.92%
    buy & hold                              17.90%
    outperformance             -843.33
    CAGR                                   390.10%
    arithmetic return                      172.88%
    geometric return                       158.72%
    volatility drag                         14.16%

  RISK
    max drawdown               1358.59      12.50%
    max runup                  1670.64      17.57%
    volatility (annual)                     53.22%
    sharpe                        3.25
    sortino                       2.28
    calmar                       31.20
    exposure                                48.40%

  TRADES
    closed trades                    8  (4W 4L 0E)
    win rate                                50.00%
    profit factor                 2.06
    expectancy                  118.37
    R-multiple expectancy           na       (0/8)
    avg win / loss        459.75 / 223.00
    largest win / loss    899.82 / -406.80
    max consecutive       2 win / 3 loss
    avg bars in trade            30.25
    commission paid             0.0000
    max contracts held          152.31

  initial capital 10000.00 · annualized at 8766.00 periods/yr · in 16ms

The ledger, equity curve, and bar times are always computed, so --trades (print the ledger), --csv <dir> / --plot <dir> (export), and --json (the full RunResult) need no extra flags. The stats blocks are followed by the analysis tables: MONTHLY RETURNS % (year × month grid, green/red on a TTY), MONTHLY TRADES (the same grid tallying closed trades by exit month in win/loss/even order — 5/3, 5/2/1; zero tallies omitted, wins green and losses red on a TTY, evens uncolored), TOP DRAWDOWNS (the five deepest episodes with peak/trough/recovery dates and durations; — + >N marks one still underwater), and TRADE P/L DISTRIBUTION (a bucketed histogram of closed-trade profits — zero is always a bucket edge, so every bar is purely wins or purely losses). Then three in-terminal charts (the histogram and charts skip with --no-chart; the tables always print): the PRICE panel — the close series as a braille line with every trade marked at its actual fill price: ▲ long / ▼ short entry, ● winning / ○ losing exit, colored cyan / green / red on a TTY while piped output stays plain unicode (the glyphs carry the same information) — then the EQUITY chart (braille line with a dashed initial-capital guide and a date axis) and the DRAWDOWN underwater strip.

Live mode: --watch [sec] (default 60, min 5) refreshes history, reruns, and redraws the tearsheet in place every cycle — a paper-trading dashboard for free. It requires a live terminal (refuses when piped) and is incompatible with --json; Ctrl-C exits. Fixed input overrides use --input name=value (repeatable, ONE value each — grids are sweep's job) and are validated against the script's input() titles before anything runs. Indicator scripts are rejected with a pointer to scan; strategies only.

Programmatic:

import { backtest } from '@heyphat/pinerun';

const { result, fetchError } = await backtest({
  source, // Pine v6 strategy
  symbol: 'SOLUSDT',
  timeframe: '1h', // canonical pinery tf
  provider: new BinanceProvider(),
  range: { limit: 500 },
  inputs: { fast: 10, slow: 50 }, // fixed overrides (optional)
  calcOnOrderFills: true, // TV "After order is filled" override (optional;
  //                         result.strategy.calcOnOrderFills reports the
  //                         EFFECTIVE mode — true only when the engine ran it)
  useBarMagnifier: true, // optional strict boolean override; target TF is
  //                        automatic and exact data resolves before execution
  metrics: { periodsPerYear: 252 }, // annualization convention (optional)
  // mintick?, backend?, resolveSecurity? (default true), onFetch?
});
// result.strategy  → StrategySummary (broker-verbatim + derived metrics)
// result.trades / result.equityCurve / result.barTimes / result.closes → always attached
// priceChartAscii(result.closes, { trades: result.trades, times: result.barTimes })

A backtest is a single executeJob — no runner/worker pool involved — so it also runs in the browser with any HistoryProvider.

Compare — two strategies, same bars

backtest answers "how good is this strategy?"; compare answers "which of these two?" — two scripts (or one script under two input sets) run on the same symbol and bars, printed side by side:

# two different strategies
pinerun compare examples/sma-cross-param.pine examples/rsi-mean-reversion.pine \
  --symbol BTCUSDT --tf 1h --limit 500

# one strategy, two parameterizations
pinerun compare strat.pine strat.pine --symbol BTCUSDT --tf 1h \
  --input-a fast=5 --input-b fast=20 --label-a fast-5 --label-b fast-20
  compare: SOLUSDT @ 1h — 499 bars, 2026-06-19 → 2026-07-10

                                 A: fast-5      B: fast-20
    ------------------------------------------------------
    net profit %                    -1.48%          11.30%
    profit factor                     0.91            2.74
    max drawdown %                  12.33%           7.46%
    sharpe                            0.12            5.28
    ...

  EQUITY %  ⣿ A: fast-5  ⣿ B: fast-20  (dashed = 0%)
    <both curves on one chart, A cyan / B yellow>

The metric table covers returns, risk, and trade quality for both sides; the equity curves are normalized to % return (so different initial_capitals compare fairly) and overlaid on one chart — A cyan, B yellow on a TTY. Piped output can't rely on color, so it prints two stacked monochrome charts instead. Flags: --input-a / --input-b (repeatable, one value each, validated per script), --label-a / --label-b (default: the filenames), --bar-magnifier / --no-bar-magnifier (one shared tri-state override; absent leaves the two source headers independent), --no-chart, --json (both full RunResults), plus the usual history/provider/backend/metrics flags. Strategy scripts only; the Bar Magnifier target timeframe is always automatic.

The overlay builder is exported and pure: overlayChartAscii(a, b, { times, guide, color, fmtLabel }) draws any two aligned series on a shared scale.

Sweep — parameter optimization

Where scan fans one script out over N symbols, sweep fans one script out over N parameter combinations: the cartesian product of a set of input axes, run in parallel and ranked. It's the same fan-out (same Job model, jobHash memo, Runner, and ranker) — only the job generation differs, so it inherits all the parallelism and determinism for free. Pass several symbols (--symbols) and the grid widens to symbols × combos — the symbol becomes an implicit axis, bars still fetched once per symbol.

Each combo becomes a Job whose inputs override the script's input(...) values by title, so the swept names must match the Pine input titles. Lift any hardcoded constant into an input(...) to make it sweepable:

fastLen = input.int(10, "fast")   // now overridable by --input fast=...
slowLen = input.int(30, "slow")
fast = ta.sma(close, fastLen)
slow = ta.sma(close, slowLen)
                 one Pine source, one symbol's bars
                              │
   ┌───────────┬─────────────┼─────────────┬───────────┐
   ▼           ▼             ▼             ▼           ▼
Job(5,30)   Job(5,50)   Job(10,30)   Job(10,50)  …          ← cartesian(axes)
   └───────────┴─────────────┼─────────────┴───────────┘       (bars fetched ONCE)
                             ▼
                  worker pool → executeJob (per combo)
                             ▼
                     rankResults(spec)                      ← e.g. strategy.netProfit
                             ▼
                  ranked table (a column per axis)

CLI

pinerun sweep examples/sma-cross-param.pine \
  --symbol BTCUSDT --tf 1h --limit 500 \
  --input fast=5,10,15,20 --input slow=30:100:10 --top 10
  sweep: BTCUSDT — 32 combos, ranked by strategy.netProfit (fast × slow)

  #  fast  slow       NET P/L      NET %  TRADES    WIN%    MAXDD%       PF   SHARPE
  ----------------------------------------------------------------------------------
   1   10    40       -148.43     -1.48%       5  40.00%     4.23%     0.13     3.10
   2   10    50       -156.22     -1.56%       5  20.00%     5.57%     0.39     2.56
   ...

  32/32 ran  10 ranked  in 85ms

Like scan, sweep auto-detects a strategy (defaults the rank to strategy.netProfit unless you pass --rank) and prints a backtest table with one column per swept axis; an indicator sweep prints a single VALUE column instead.

Axis grammar — each --input name=spec (repeatable) expands to a value list:

Spec Expands to Meaning
fast=5,10,20 [5, 10, 20] explicit list (a comma always wins)
slow=30:100:10 [30, 40, …, 100] inclusive range start:stop:step
len=5:8 [5, 6, 7, 8] range, default step 1
fast=5,10:20:5 [5, 10, 15, 20] a list member may itself be a range
useStop=true,false [true, false] booleans
mult=.5,1.5,2 [0.5, 1.5, 2] floats (leading-dot / 1e3 forms work)
src=close ["close"] single value

Tokens coerce to number / boolean / string automatically. Every axis is validated against the script's declared inputs before any fetch: an axis name that matches no input() title errors out (piner would otherwise silently ignore it and every combo would run identical defaults), and a value whose type doesn't match the input kind (a string reaching an input.int) errors instead of silently running as na. The total run count (combos × symbols) is capped by --max-combos (default 5000), also checked before any fetch.

Sweep-specific flags (everything else — --tf --from --to --limit --rank --top --asc --trades --concurrency --workers --backend --provider --api-key --api-secret --feed --periods-per-year --risk-free-rate --csv --plot --no-security --no-cache --cache-dir --refresh --json — matches scan):

--symbol <sym>        Single symbol to backtest across the grid
--symbols / --universe  Multi-symbol grid (symbol becomes an implicit axis)
--input name=spec     Swept input axis (REPEATABLE); name must match a Pine input() title
--sample <n> / --seed <n>  Seeded random subset instead of the exhaustive grid
--heatmap             2-axis optimization surface as a text grid
--points-csv <file>   The whole surface as CSV, one row per run
--max-combos <n>      Cap on total runs: combos × symbols (default 5000)

Multi-symbol grids, smart search, heatmap, points CSV

Multi-symbol grid — --symbols a,b,c (or --universe <file>) runs every combo on every symbol. Bars are fetched once per symbol (bounded concurrency) and shared across that symbol's combos. Ordinary fetch failures retain the legacy fetchErrors behavior; when magnification is effective, each requested symbol's permanent exact-resolution failure is expanded into explicit failed points for all of its combos, so the reported universe never shrinks silently. The table gains a SYMBOL column, exports are labeled <symbol>-<combo>, and the budget guard counts combos × symbols.

Smart search — --sample 200 swaps the exhaustive grid for 200 randomly sampled distinct combos, so a fast=1:100 slow=1:100 grid (10,000 combos) becomes tractable; --max-combos then applies to the sampled count. Sampling is seeded (--seed, default 42) and deterministic: the same seed reruns the same combos. Combos are decoded straight from their grid index (comboAt/sampleCombos in params.ts) — the full cartesian product is never materialized.

Heatmap — with exactly two swept axes, --heatmap prints the classic optimization surface (first axis down the rows, second across the columns, the ranked metric in each cell; · marks failed or sampled-out cells; one grid per symbol on a multi-symbol sweep). On a TTY the cells grade red → yellow → plain → green → bright green by value quintile, so the robust plateau (broad green regions, what you actually want) stands out from a lucky spike; piped output stays plain:

  strategy.netProfit by fast (rows) × slow (cols)

  fast     30      50
     5  -28.4   175.7
    10  192.3  -120.0
    15  413.2   -46.3

Points CSV — --points-csv out/points.csv writes EVERY run (not just the ranked top) as one row: symbol, one column per axis, the ranked value, the strategy summary block, and the error for failed runs. Unlike --csv it needs no trade ledgers, so it's cheap on huge grids and pivots straight into a pandas / Excel optimization surface. Programmatic: sweepPointsToCsv(report) / sweepHeatmap(report) are pure string builders exported from the package root.

Try it — scenario commands

Run these from the repo root; the on-disk history cache makes repeats fast:

# Multi-symbol grid — a SYMBOL column, one fetch per symbol, ranked across all symbols
pinerun sweep examples/sma-cross-param.pine \
  --symbols BTCUSDT,ETHUSDT,SOLUSDT --tf 1h --limit 500 \
  --input fast=5,10 --input slow=30,50 --top 10

# 2-axis heatmap under the ranked table
pinerun sweep examples/sma-cross-param.pine \
  --symbol BTCUSDT --tf 1h --limit 500 \
  --input fast=5:20:5 --input slow=30:100:10 --heatmap

# Multi-symbol + heatmap — one grid per symbol
pinerun sweep examples/sma-cross-param.pine \
  --symbols BTCUSDT,ETHUSDT --tf 1h --limit 500 \
  --input fast=5,10,15 --input slow=30,50 --heatmap

# Smart search — an 11k-combo grid sampled down to 50 runs
pinerun sweep examples/sma-cross-param.pine \
  --symbol BTCUSDT --tf 1h --limit 500 \
  --input fast=2:60 --input slow=10:200 --sample 50 --top 10

# Seed determinism — rerun with the same --seed and the table is identical;
# change the seed and the sampled combos change
pinerun sweep examples/sma-cross-param.pine \
  --symbol BTCUSDT --tf 1h --limit 500 \
  --input fast=2:60 --input slow=10:200 --sample 10 --seed 7

# Sampled heatmap — combos the sample skipped print as ·
pinerun sweep examples/sma-cross-param.pine \
  --symbol BTCUSDT --tf 1h --limit 500 \
  --input fast=5:20:5 --input slow=30:100:10 --sample 12 --heatmap

# Points CSV — every run as one row, cheap (no ledgers)
pinerun sweep examples/sma-cross-param.pine \
  --symbols BTCUSDT,ETHUSDT --tf 1h --limit 500 \
  --input fast=5,10,15 --input slow=30,50 --points-csv out/points.csv

# JSON — check symbols, combos, gridTotal, sample, and per-point symbol fields
pinerun sweep examples/sma-cross-param.pine \
  --symbols BTCUSDT,ETHUSDT --tf 1h --limit 300 \
  --input fast=5,10 --input slow=30 --sample 1 --json

Guard / failure paths — all fail fast with a clean message before any fetch:

# Budget counts combos × symbols: 4 combos × 2 symbols = 8 > 5
pinerun sweep examples/sma-cross-param.pine \
  --symbols BTCUSDT,ETHUSDT --tf 1h --input fast=5,10 --input slow=30,50 --max-combos 5

# An oversized exhaustive grid suggests --sample
pinerun sweep examples/sma-cross-param.pine \
  --symbol BTCUSDT --tf 1h --input fast=1:100 --input slow=1:100

# --heatmap with only one axis is rejected
pinerun sweep examples/sma-cross-param.pine \
  --symbol BTCUSDT --tf 1h --input fast=5,10 --heatmap

# A non-integer --sample is rejected
pinerun sweep examples/sma-cross-param.pine \
  --symbol BTCUSDT --tf 1h --input fast=5,10 --sample 2.5

# A bad symbol in a multi-symbol grid is reported but doesn't sink the rest
pinerun sweep examples/sma-cross-param.pine \
  --symbols BTCUSDT,NOTAREALSYM --tf 1h --limit 300 --input fast=5,10 --input slow=30

Regression check — walkforward drives sweep internally per window, so it should behave exactly as before these additions:

pinerun walkforward examples/sma-cross-param.pine \
  --symbol BTCUSDT --tf 1h --limit 2000 \
  --input fast=5,10,15 --input slow=30,50 --windows 3

Programmatic — sweep(options) → SweepReport

import { sweep, parseAxes } from '@heyphat/pinerun';
import { WorkerPoolRunner } from '@heyphat/pinerun/node';
import { BinanceProvider } from '@heyphat/pinery';
import { readFileSync } from 'node:fs';

const runner = new WorkerPoolRunner({ size: 8 });
try {
  const report = await sweep({
    source: readFileSync('examples/sma-cross-param.pine', 'utf8'),
    symbol: 'BTCUSDT',
    timeframe: '1h',
    provider: new BinanceProvider(),
    range: { limit: 500 },
    axes: parseAxes(['fast=5,10,15,20', 'slow=30:100:10']), // or build Axis[] by hand
    rank: 'strategy.netProfit',
    top: 10,
    runner,
  });

  for (const { inputs, result, value } of report.ranked) {
    console.log(inputs, value, `${result.strategy!.netProfitPercent.toFixed(1)}%`);
  }
} finally {
  await runner.close();
}
interface Axis {
  name: string;
  values: unknown[];
} // name = a Pine input() title

interface SweepOptions {
  source: string;
  symbol?: string; // single symbol…
  symbols?: string[]; // …or a multi-symbol grid (symbols × combos)
  timeframe: string; // canonical pinery tf (e.g. "1h"), mapped internally
  provider: HistoryProvider;
  range?: HistoryRange;
  axes: Axis[]; // the input grid (cartesian product)
  baseInputs?: Record<string, unknown>; // fixed inputs applied under every combo
  rank?: string; // default: strategy.netProfit for strategies, else "last"
  calcOnOrderFills?: boolean; // host override of calc_on_order_fills, applied
  //                  to every combo (part of each job's determinism key)
  useBarMagnifier?: boolean; // strict tri-state override applied to every combo;
  //                  one exact dataset is shared per symbol across the grid
  direction?: 'asc' | 'desc';
  top?: number;
  concurrency?: number; // default: worker-pool size (4 for LocalRunner)
  backend?: 'js' | 'interp';
  mintick?: number;
  includeTrades?: boolean;
  metrics?: JobMetricsOptions; // { periodsPerYear?, riskFreeRate? } for derived metrics
  resolveSecurity?: boolean; // default true (resolved once, shared across combos)
  maxCombos?: number; // default 5000; throws before I/O when exceeded
  sample?: number; // smart search: run N random combos instead of the grid
  seed?: number; // PRNG seed for sample (default 42, deterministic)
  runner?: Runner; // default new LocalRunner()
  onResult?: (r, done, total) => void;
  onFetch?: (symbol, bars) => void;
}

interface SweepPoint {
  symbol: string; // the symbol this run executed on
  inputs: Record<string, unknown>;
  result: RunResult;
  value: number;
}

interface SweepReport {
  symbol: string; // display label (comma-joined when multi-symbol)
  symbols: string[]; // every requested symbol
  rank: string; // the EFFECTIVE rank spec (reflects the strategy default)
  spec: RankSpec;
  axes: Axis[];
  total: number; // runs executed (== points.length == combos × fetched symbols)
  combos: number; // combos per symbol (full grid, or the sampled count)
  gridTotal: number; // full cartesian size — > combos when sample was used
  ranked: SweepPoint[]; // sorted, top-N applied; NaN dropped, ±Infinity kept
  points: SweepPoint[]; // every run, symbols outermost then cartesian order
  errors: RunResult[]; // compile/runtime and typed exact-mode failures
  warnings: string[]; // non-fatal ordinary-mode caveats (e.g. dynamic security)
  fetchErrors: { symbol: string; error: string }[]; // symbols whose fetch failed
  fetchError?: string; // set when EVERY symbol's fetch failed
}

The axis grammar is exported for building/validating axes yourself: parseAxes, parseAxis, parseSpec, coerceToken, expandRange, cartesian, comboAt, sampleCombos, comboId, countCombos, assertComboBudget, DEFAULT_MAX_COMBOS, DEFAULT_SAMPLE_SEED — plus the sweep exporters sweepPointsToCsv and sweepHeatmap.

Walk-forward — out-of-sample validation

A sweep picks the best combo on historical data; that combo is usually fit to noise. walkforward asks the only question that matters: does the edge survive on data the optimizer never saw?

History is split into N windows. In each window the grid is swept on the in-sample (IS) segment, the winner is picked by --rank, and that winner is measured on the following out-of-sample (OOS) segment. OOS segments tile the tail of history back to back, so every OOS bar is traded by parameters chosen strictly on earlier data. --windows 1 is the plain IS/OOS split; --anchored grows the IS from bar 0 instead of rolling it.

pinerun walkforward examples/sma-cross-param.pine \
  --symbol BTCUSDT --tf 1h --limit 2000 \
  --input fast=5,10,15,20 --input slow=30:100:10 --windows 5
  walk-forward: BTCUSDT — 5 windows (IS 375 → OOS 125 bars, rolling), rank strategy.netProfit

  #  IS SPAN                   OOS SPAN                  WINNER            IS NET%  OOS NET%  TRADES     EFF
  ----------------------------------------------------------------------------------------------------------
   1 2026-05-24 → 2026-06-09   2026-06-09 → 2026-06-14   fast=10|slow=30     2.01%     3.98%       1    5.95
   2 2026-05-29 → 2026-06-14   2026-06-14 → 2026-06-19   fast=10|slow=30     5.87%    -0.74%       3   -0.38
   3 2026-06-04 → 2026-06-19   2026-06-19 → 2026-06-24   fast=20|slow=40     7.57%    -3.28%       2   -1.30
   4 2026-06-09 → 2026-06-24   2026-06-24 → 2026-06-30   fast=10|slow=40     4.44%    -1.10%       2   -0.74
   5 2026-06-14 → 2026-06-30   2026-06-30 → 2026-07-05   fast=10|slow=40    -0.96%     4.13%       1      na

  aggregate: OOS positive 2/5 · mean IS 3.79% · mean OOS 0.60% · WFE 0.47 · in 272ms

Read the verdict off the aggregate: WFE (walk-forward efficiency) is per-bar OOS profit ÷ per-bar IS profit across all windows — ≈ 1 means the edge holds out of sample, ≪ 1 (like the 0.47 above) means the sweep was fitting noise. Also watch OOS-positive counts and whether the winning combo is stable across windows (a different winner every window is itself a red flag).

How OOS is measured (no warmup bias). Each window's winner runs over the full window (IS + OOS): the IS stretch doubles as indicator warmup, and — since a piner run is deterministic bar by bar — its IS prefix is identical to the sweep run that selected it (covered by a test). OOS performance is the equity-curve difference across the boundary; OOS trades are those that exit in the segment (a position opened in-sample and carried across counts, as it would live). Both are plain arithmetic on piner outputs.

Walk-forward flags: --windows <n> (default 5), --oos <f> (OOS share of each window, default 0.25), --anchored; everything else — --input axes, --rank, history/provider/backend/metrics flags, --max-combos, --json — matches sweep. Strategy scripts only (indicators are rejected). The table ends with an OOS EQUITY sparkline per window — each winner's out-of-sample equity segment, so "did the edge survive" is visible per row next to its OOS NET% (skip with --no-chart).

Programmatic — walkforward(options) → WalkforwardReport:

import { walkforward } from '@heyphat/pinerun';

const report = await walkforward({
  source, // Pine v6 strategy
  symbol: 'BTCUSDT',
  timeframe: '1h',
  provider: new BinanceProvider(),
  range: { limit: 2000 },
  axes: parseAxes(['fast=5,10,15,20', 'slow=30:100:10']),
  calcOnOrderFills: true, // optional: applied to BOTH the in-sample sweeps
  //                         and each window's full-window winner run
  useBarMagnifier: true, // optional tri-state override; each fold resolves one
  //                        exact full IS+OOS dataset before candidate ranking
  windows: 5, // default 5; 1 = plain IS/OOS split
  oosFraction: 0.25, // default
  anchored: false, // default: rolling IS
  rank: 'strategy.sharpe', // winner selector (default strategy.netProfit)
  // baseInputs?, concurrency?, backend?, mintick?, metrics?, maxCombos?, runner?
});
// report.windows[i]: { isFrom/isTo/oosFrom/oosTo (+times), winner, winnerId,
//   isProfitPercent, oosProfitPercent, oosTrades, efficiency, result, failure? }
// report.failure: typed preflight rejection before folds could be planned
// report.aggregate: { oosPositive, meanIsProfitPercent, meanOosProfitPercent,
//   walkForwardEfficiency, windows, failed }

The window planner is exported too: planWindows(totalBars, windows, oosFraction, anchored) returns the bar-index plan (isFrom/isTo/oosFrom/oosTo, half-open).

Bars are fetched once and shared across every combo (the worker pool also serializes the shared series to each worker once, not once per combo). In ordinary mode, request.security dependencies are likewise resolved once; dynamic runtime requests retain the legacy warning/degradation behavior and --no-security remains available. In effective Bar Magnifier mode there is no approximation: every static dependency is completed against the full fold, runtime-dynamic symbol/timeframe/lookahead identities are permanently rejected, and --no-security cannot bypass the exact requirement.

A magnified fold acquires one full IS+OOS envelope before ranking. The exported inspectWalkforwardMagnifierCap / assertWalkforwardMagnifierCap helpers enforce the inclusive 200,000 eligible-target-bar limit and report whether the moving cap boundary would fall inside IS; an over-cap fold is retained as a typed failed diagnostic before any candidate runs.

Overfitting. Picking the single best of many combos usually fits past noise, not a durable edge. Treat sweep as candidate generation and validate the winner on data it never saw (out-of-sample / walk-forward) before trusting it.

Portfolio — one strategy, N symbols, ONE capital pot

scan answers "which symbol is best?". portfolio answers the question a quant actually trades on: run this strategy across the whole basket out of one account. It fans out the fetch exactly like scan, then hands the injected bars to piner's PortfolioEngine — N per-symbol engines driven on the union clock of all sleeves' bar times — and reads back one portfolio equity curve, a merged symbol-tagged ledger, and a tearsheet computed by piner's computeStrategyMetrics.

Two capital models, selected with --mode:

  • isolated (default) — N sub-accounts, each funded wᵢ·P. This equals running each symbol standalone and summing the equity curves; it's the equal-weight (or, with --weights, weighted-allocation) baseline. Piner proves the engine reproduces that per-symbol sum bit-for-bit.
  • shared — one pot. percent_of_equity sizing, funds checks, margin, and strategy.risk.* rules all read portfolio equity, and sleeves compete for capital in basket 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.
pinerun portfolio examples/sma-cross-param.pine \
  --symbols BTCUSDT,ETHUSDT,SOLUSDT --tf 1h --limit 500 --mode shared --capital 30000
  portfolio: 3 symbols @ 1h — mode=shared, 30000.00 initial, 2026-06-18 → 2026-07-09

  RETURNS
    net profit                 53.3355       0.18%
    ...
  RISK
    max drawdown               3646.57      11.80%
    sharpe                        0.32
    exposure                                56.91%
    (portfolio drawdown/run-up are close-to-close on the combined curve)
  TRADES
    closed trades                   11  (4W 7L 0E)
    margin calls                     0

  SYMBOL               FUNDING     NET P/L  TRADES  CONTRIB%  RET-CORR
  --------------------------------------------------------------------
  BTCUSDT              (pot)     -843.32       3   -1581.2        na
  ETHUSDT              (pot)     -792.76       2   -1486.4        na
  SOLUSDT              (pot)     1689.41       6    3167.5        na

  3/3 sleeves combined  annualized at 8766.00 periods/yr  in 14ms

The contribution table attributes portfolio net profit to each sleeve; in isolated mode RET-CORR is each sleeve's per-bar return correlation with the portfolio (a diversification read), shown na under shared mode where every sleeve's curve samples the shared pot.

Under the contribution table, an isolated-mode basket of two or more sleeves prints the SLEEVE RETURN CORRELATION matrix — every pairwise per-bar return correlation, the direct answer to "do I hold four strategies or one strategy four times?" (skipped in shared mode, where sleeve curves sample the pot and every pair would read 1.00). The portfolio tearsheet also carries the same MONTHLY RETURNS, MONTHLY TRADES, TOP DRAWDOWNS, and TRADE P/L DISTRIBUTION blocks as backtest, computed on the combined curve and merged ledger.

The tearsheet ends with in-terminal charts (skip with --no-chart): the combined equity curve as a braille line chart with a dashed initial-capital guide, the close-to-close underwater drawdown, and one cumulative-P/L sparkline per sleeve — plain unicode, no colors, safe to pipe or log. The same builders are exported for programmatic use: equityChartAscii(equity, { times, capital, width, height }), priceChartAscii(closes, { times, trades, color }), drawdownChartAscii(equity, opts), sparkline(values, width).

Terminal charts run across the CLI, wherever the data is present (all skippable with --no-chart): backtest ends its tearsheet with a PRICE panel (close line, trades marked at their fill prices — ▲/▼ entries, ● win / ○ loss exits, colored on a TTY) plus the same equity + drawdown charts; compare overlays both strategies' normalized equity curves on one chart (A cyan / B yellow on a TTY, stacked monochrome charts when piped); scan adds a SERIES sparkline of the ranked plot per row (indicator scans) or an EQUITY sparkline per symbol (strategy scans with --trades/--csv/--plot), and a single-symbol --trades scan prints the PRICE chart above its ledger; sweep gains the same EQUITY column per combo under --trades plus the winning combo's PRICE chart, and --heatmap cells grade red → green on a TTY; walkforward shows each window's OOS equity segment as a sparkline — the "did the edge survive out of sample" question, answered per row at a glance. portfolio charts equity only: a basket mixes price scales, so per-trade context lives in the per-sleeve CSV/HTML exports instead. The backtest and portfolio tearsheets also print MONTHLY RETURNS, MONTHLY TRADES, TOP DRAWDOWNS, and TRADE P/L DISTRIBUTION blocks (see the backtest section) — pure-text tables that survive any 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). No buy-&-hold benchmark: it's meaningless for a basket.

Flags: --symbols/--universe (basket, priority order); --mode isolated|shared; --capital <P> (default N × the script's initial_capital); --weights sym=frac,... (isolated only; normalized); --input (applied to every sleeve); --trades/--csv/--plot/--json; plus the usual history/provider/backend/metrics flags. portfolio intentionally has no v1 portfolio-wide Bar Magnifier override: every sleeve resolves the shared source's header setting against its own symbol/window/provider before any PortfolioSleeveSpec is created. If magnification is requested, every requested sleeve must fetch and resolve successfully or the whole basket aborts atomically; no sleeve is silently dropped. Exact LTF timestamps are data for that sleeve only and never join the master clock. In ordinary non-magnifier mode, a symbol that fails to fetch retains the existing drop-with-warning behavior (especially loud under shared, where a smaller basket is a different backtest).

--csv writes portfolio-equity.csv + portfolio-trades.csv (symbol-tagged, exit-time sorted) plus per-sleeve files; --plot writes portfolio.html + per-sleeve charts. Strategy scripts only.

The report mirrors piner's authoritative per-sleeve and aggregate Bar Magnifier blocks without inferring activation from injected data. Aggregate counters are sleeve sums, coverage precedence is mixed-data-fallback then tv-cap-fallback then complete/no-data, and coverage uses the sum of sleeve processed chart bars (never the master-clock union), validated within 0–100%. Current probe-gated piner traversal therefore remains requested-but-inactive and does not alter merged-ledger event times.

CSV clocks. In portfolio-trades.csv the entryBar/exitBar columns are sleeve-local bar indices (they join that symbol's <SYMBOL>-equity.csv), while portfolio-equity.csv's bar column is the master clock. To join trades against the combined curve, key on entryTime/exitTime instead.

Try it — scenario commands

Run these from the repo root; the on-disk history cache makes repeats fast:

# Isolated baseline (default) — N equal-weight sub-accounts; equals running each
# symbol standalone and summing the equity curves. RET-CORR reads diversification.
pinerun portfolio examples/sma-cross-param.pine \
  --symbols BTCUSDT,ETHUSDT,SOLUSDT --tf 1h --limit 500

# 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 30000

# Weighted 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.2

# Basket from a universe file + 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=50

# Merged ledger + 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

Programmatic — portfolio(options) → PortfolioReport:

import { portfolio } from '@heyphat/pinerun';

const report = await portfolio({
  source, // Pine v6 strategy
  symbols: ['BTCUSDT', 'ETHUSDT', 'SOLUSDT'],
  timeframe: '1h',
  provider: new BinanceProvider(),
  range: { limit: 500 },
  mode: 'shared', // 'isolated' (default) | 'shared'
  capital: 30000, // default: N × the script's initial_capital
  weights: { BTCUSDT: 0.5, ETHUSDT: 0.3, SOLUSDT: 0.2 }, // isolated only
  // No useBarMagnifier option in v1: each sleeve follows source metadata.
  // inputs?, backend?, mintick?, concurrency?, metrics?, resolveSecurity?
});
// report.equityCurve / times (chart-only master clock), initialCapital,
// summary (StrategySummary), metrics (StrategyMetrics), trades (merged,
// symbol-tagged), sleeves (contribution + optional authoritative barMagnifier),
// barMagnifier (optional validated aggregate), fetchErrors, mode, elapsedMs

The exact multi-symbol capital semantics (what strategy.equity reads under a shared pot, fill ordering, per-sleeve margin against shared cash, portfolio-level risk halts) are specified in piner's docs/portfolio-semantics.md — TradingView has no multi-symbol strategy, so pinestack defines and versions these itself.

The pure alignment helpers are exported for building the post-hoc sum yourself (the oracle the engine is validated against): combineEquity(sleeves), unionTimes, alignEquity, returnCorrelation.

Cross-symbol and multi-timeframe data (request.security)

Piner never performs I/O. It declares request.security and request.security_lower_tf dependencies and consumes bars injected by its host. Pinerun resolves those dependencies by default; pass resolveSecurity: false or --no-security to disable resolution explicitly. The following planner describes ordinary (non-magnifier) resolution; effective Bar Magnifier mode instead uses the coverage-aware exact acquisition and proof path documented above.

Ordinary resolution is static-first:

  1. Discover. Read compile-time ScriptMetadata.securityDependencies without executing the strategy. Only dynamic symbol/timeframe expressions require a one-off discovery run under a sentinel symbol, which distinguishes syminfo.tickerid self-references from equal-looking literals.
  2. Plan. Deduplicate call sites, preserve exact symbol/timeframe keys, and choose the finest required base timeframe for each bare cross-symbol feed. The requested history envelope is expanded for finer feeds so their bars cover the chart range rather than merely matching its bar count.
  3. Fetch. Fetch each unique dependency once through pinery (and its identity-aware disk cache), sharing literal cross-symbol data across jobs. Self lower-timeframe dependencies remain per scanned symbol.
  4. Inject. Attach the complete securityBars map to each job before its single piner execution; there is no na discovery run followed by a second trading run.
Request on a 1h chart Fetch plan
security(syminfo.tickerid, "1D", …) Fetch that job symbol at 1d, inject under <symbol>@1D; only chart-TF identity reuses chart bars.
security("OTHER", "1D", …) Fetch OTHER at the chart/base timeframe once; piner resamples upward.
security("OTHER", "5", …) Fetch OTHER at 5m; a bare-symbol feed uses the finest timeframe required by its call sites.
security_lower_tf("OTHER", "5", …) Fetch OTHER at 5m, inject under the exact lower-timeframe key.
security_lower_tf(syminfo.tickerid, "5", …) Fetch each job symbol at 5m, inject under that symbol's exact key.
security(syminfo.tickerid, timeframe.period, …) Reuse the chart series; no secondary fetch.

For example, a script requesting OTHER at both 5m and 15m on a 1h chart fetches one complete 5m base feed; piner derives the requested buckets. A plain cross-symbol request below the chart timeframe is therefore not fetched at 1h and cannot lose the needed intrabars. For a limit-only chart load, ordinary finer-timeframe dependency fetches receive the loaded chart's concrete time envelope instead of the same bar-count limit; explicit ranges pass through unchanged. This legacy conversion is never used by exact acquisition.

# ETHUSDT is fetched once and shared across the scan.
pinerun scan examples/rs-vs-eth.pine \
  --symbols BTCUSDT,SOLUSDT,BNBUSDT --tf 1h --limit 300 \
  --rank "last(rs)"

Outside exact mode, a dependency whose fetch fails or is disabled retains the legacy degradation to na (regular security) / [] (lower-TF), and each run surfaces its requests on RunResult.securityRequests. Pinelive uses a stricter fail-closed policy before broker reconciliation; see the forward guide. When Bar Magnifier is effective, preflight uses piner's static metadata and every static dependency must resolve completely before execution. Runtime-dynamic symbol/timeframe/lookahead identities fail permanently as dynamic-security-unsupported-with-bar-magnifier; neither discovery probing nor --no-security may silently degrade an exact run.

Dynamic dependencies. Static metadata is authoritative when possible. A runtime-computed dependency discovered by the probe is included, but a sweep whose dependency itself changes with a swept input cannot be represented by one shared resolution. Sweep/walk-forward reports warn about this case; use --no-security or restructure the script rather than assuming all combinations received different feeds.

Dependency discovery is static-first: ordinary mode reads piner's compile-time securityDependencies and only runs a discovery pass when a symbol/timeframe is dynamic. RunResult.securityRequests still reports what each run declared. Effective Bar Magnifier mode is stricter: it never performs that dynamic probe and accepts only a complete static plan.

Time units. Pinery and pinerun expose Bar.time in Unix seconds. Piner's engine uses milliseconds. executeJob and pinery's toDataFeed convert at the engine boundary so bucketing, calendar/session builtins, and close-time alignment use the expected units.

API summary

@heyphat/pinerun

  • Job: Job, Bar, JobMetricsOptions, ResolvedMagnifierCoverage, ResolvedMagnifierDataset, jobId
  • Result: RunResult, RunFailure, PlotResult, AlertResult, StrategySummary, StrategyTrade, StrategyMetrics, BarMagnifierSummary; presentation: FillModelPresentation, formatFillModel
  • Run: executeJob, jobHash, assertResolvedMagnifierDatasetForJob, toPinerBarMagnifierData, projectAuthoritativeBarMagnifierReport
  • Exact failures/capabilities: BarMagnifierFailure, BarMagnifierFailureKind, BarMagnifierError, isBarMagnifierFailure, PinerCapabilityAdapter, pinerCapabilities, createPinerCapabilityAdapter, SUPPORTED_BAR_MAGNIFIER_CONTRACT_VERSION
  • Magnifier resolution: MagnifierPreflight, MagnifierResolution, ResolveBarMagnifierOptions, MagnifierAcquisitionKeyInput, magnifierMetadataKey, magnifierAcquisitionKey, preflightBarMagnifier, resolveBarMagnifier
  • Runners: Runner, RunAllOptions, LocalRunner, fanOut
  • Ranking: Aggregate, RankSpec, RankedResult, RankOptions, parseRankSpec, evalRank, rankResults, sortRanked, selectPlot
  • Scan: ScanOptions, ScanReport, scan
  • Backtest: BacktestOptions, BacktestReport, backtest
  • Portfolio: PortfolioOptions, PortfolioReport, SleeveContribution, PortfolioBarMagnifierSummary, portfolio; align helpers Sleeve, unionTimes, alignEquity, combineEquity, returnCorrelation
  • Sweep: SweepOptions, SweepReport, SweepPoint, sweep, validateAxes
  • Walkforward: WalkforwardOptions, WalkforwardReport, WalkforwardWindow, WalkforwardAggregate, WindowPlan, WalkforwardMagnifierCapObservation, walkforward, planWindows, inspectWalkforwardMagnifierCap, assertWalkforwardMagnifierCap, WALKFORWARD_MAGNIFIER_TARGET_BAR_LIMIT
  • CSV export: tradesToCsv, equityToCsv, equityPlotHtml, sweepPointsToCsv, sweepHeatmap, SweepHeatmapOptions
  • Terminal charts: EquityChartOptions, equityChartAscii, PriceChartOptions, PriceChartTrade, priceChartAscii, OverlayChartOptions, overlayChartAscii, drawdownChartAscii, sparkline (pure string builders — the CLI's braille price/equity/drawdown/overlay charts, trade markers, and table sparklines)
  • Tearsheet tables: monthlyReturnsAscii, monthlyTradesAscii, topDrawdownsAscii, drawdownEpisodes, profitHistogramAscii, correlationMatrixAscii (+ their option types) — the MONTHLY RETURNS / MONTHLY TRADES / TOP DRAWDOWNS / TRADE P/L / SLEEVE CORRELATION blocks as pure string builders
  • Scaffold (init): StarterTemplate, ScaffoldOptions, starterStrategy, isStarterTemplate, STARTER_TEMPLATES, STARTER_DESCRIPTIONS, SUGGESTED_FILE
  • Params (sweep axis grammar): Axis, ComboBudgetOptions, parseAxes, parseAxis, parseSpec, coerceToken, expandRange, cartesian, comboAt, sampleCombos, comboId, countCombos, assertComboBudget, DEFAULT_MAX_COMBOS, DEFAULT_SAMPLE_SEED
  • Security: resolveSecurity, discoverSecurityRequests, classifyRequests, planFromStatic, resolveLowerFetchTf, resolveSameSymbolFetchTf, assertStaticSecurityForBarMagnifier, assertResolvedSecurityForBarMagnifier, PROBE_SYMBOL, ClassifiedRequests, DiscoverOptions, ResolveSecurityOptions

@heyphat/pinerun/node

  • Everything above, plus WorkerPoolRunner and WorkerPoolOptions

License

GNU AGPL-3.0 © Phat Huynh.