Portfolios

A portfolio runs several assets from one shared pool of capital as a single book. Each asset carries its own strategy, and a contention rule decides who gets the cash when more than one asset wants to enter on the same bar. Where a single backtest is one symbol, one strategy and its own balance, a portfolio is a roster of assets competing for one pool, with a shared equity curve, per-asset attribution, and a record of every signal that could not be filled.

Building a book#

There are three ways in, and they all land on the same review then run flow. For a step by step walkthrough see Build a portfolio.

Buy BTCUSDT and ETHUSDT on 1d when price closes above the 20 EMA; exit when it closes below. $50k, prorata.

Each asset shows up as a review card with the clause the splitter assigned to it ("Split as"), its parsed logic, and its market. Before you run, you can edit any asset, copy one asset's rules to the whole roster, or remove it.

Shared capital & contention#

A book trades from one initial capital amount, not one balance per asset. The terminal starts a new book at $30,000; the API and MCP default to $100,000.

When two or more assets signal an entry on the same bar and there is not enough free cash for all of them, the contention rule resolves the conflict:

A signal that cannot be funded is never dropped silently. It is written to the skip ledger with a reason, see Reading the book report.

Rebalancing#

Off by default. You turn it on by naming target weights; percentage stops and take-profits are never mistaken for weights.

Rebalance monthly to 40% BTC, 30% ETH, 30% SOL.
Hold 60% BTCUSDT and 40% ETHUSDT, rebalance quarterly.
Allocate 50% BTCUSDT and 50% ETHUSDT once and never rebalance.
Hold 60% BTCUSDT and 40% ETHUSDT, rebalance monthly but skip rebalance trades under $500.
Equal weight BTCUSDT, ETHUSDT and SOLUSDT, rebalance monthly and also whenever a position drifts more than 5 points from its target.

Rotation#

Instead of fixed weights, rank the universe each rebalance and hold only the leaders, or the laggards.

Buy the top 3 by momentum over 30 days, rebalance weekly.
Hold the 2 lowest volatility coins, rebalance monthly.
Rotate into the best 2 by 30-day return and short the worst 2.

Rank by momentum, return, rate of change, RSI, Sharpe or volatility. A rotation is always an allocation book, the held set and the weights are both chosen by rank, so entry signals do not run.

Ranking is relative: it answers which of these is best, never is any of them any good. In a market where everything is falling, a top-N rotation dutifully buys the best of the losers and stays fully invested all the way down. Add the absolute test and the book goes to cash instead when nothing clears it:

Hold the top 2 by 90 day momentum but only while their momentum is positive, rebalance monthly.
Rotate into the top 3 by momentum, cash if none are positive.

That second test is what makes it dual momentum. The floor gates the LONG side only: it says which names are worth owning, not which are worth shorting, so a long/short rotation still takes its short sleeve from the worst-ranked names. When nothing clears the floor the run says so explicitly, so a book that deliberately sat out a bear market is never mistaken for a broken rotation.

Risk controls#

All optional, and all off unless you ask for them. State them once, anywhere in the prompt, a control that talks about the whole book never has to be repeated per asset. Percentages that belong to a leg ("stop loss 3%") are never mistaken for a book knob.

Every control below can be typed in the prompt or edited in the Book settings panel on the review page: including the ones whose value is a ladder, a schedule, a list of days or a session window. Clearing an editor turns that family off completely; there is no "set but inert" state. An edit you make by hand is authoritative: re-parsing the prompt afterwards will not overwrite it.

Size and concentration#

Timing and pacing#

Direction and regime#

A total exposure cap cannot express a market-neutral book: it reads a 100%-long book and a 50/50 long-short book as the same number. The net cap is judged across the whole bar, so a hedged pair is never refused for being "too long" on its first leg, only a lopsided bar loses its weakest name on the heavy side.

The regime gate can also act rather than merely pause, and it speaks plain words:

Entry filters on each leg's own chart#

The regime gate above judges ONE symbol for the whole book. These ask the same question of EVERY chart separately, which is the shape most trader filters take: "only trade when ADX is above 25" means each leg's own ADX.

Sessions and day boundaries#

Costs and execution#

A backtest with no fees and instant fills is a brochure, not a result. Both are stated once for the whole book.

One stop and one target for every position#

The most-used trader instruction of all, stated once for the whole book instead of repeated on every leg. An exit is added only where the leg does not already carry one of that type, the leg's own rule wins, and the result reports which legs took the book's exits and which kept their own.

The risk unit#

Traders think in R: what a trade risks, and what it pays if it works.

Scaling out#

Sizes are shares of the ORIGINAL position: "a third, then a third" really closes a third each time, with the remaining-quantity arithmetic handled for you. Slices appear on the closed trade as partial exits, the same shape the single-asset report already renders.

Pyramiding discipline#

A refused add leaves the position exactly as it was and is counted in the result, a disciplined book shows what it declined rather than looking like the adds never fired.

Protecting a profit#

Sizing that responds to something#

All of these are multipliers on the size you asked for, and they compose: with a ceiling, so several cannot conspire into a position nobody asked for.

Circuit breakers#

The count-based cousins of the daily loss limit: that one counts percent lost, these count events.

Aiming a control at one coin#

Almost every control above can name a single asset instead of the whole book. The more specific statement always wins.

Cap BTCUSDT at 40% and ETHUSDT at 20%.
Risk 2% on BTCUSDT and 1% on ETHUSDT.
Stop BTCUSDT at 10% and cut ETHUSDT if it's down 8%.
Hold ETHUSDT for at least 5 bars.
Wait 10 bars before re-entering BTCUSDT.

Custom indicators at the book level#

Anywhere a built-in indicator works in a book-level control, a custom (@-named) indicator you have uploaded works too. The series is loaded per leg through the same resolver a leg's own custom condition uses, so an unknown name fails the run loudly instead of gating on a column that is not there.

Capital deployment and signal selection#

What the book is measured against#

Every portfolio is compared to a benchmark, and by default that is an equal-weight buy-and-hold of the book's own constituents. That is often not the comparison you meant, so you can say which one you want.

Whatever you pick becomes the denominator for the numbers that actually answer "was this worth it": outperformance, beta, correlation, annualized alpha, tracking error, information ratio, and up/down capture. Add "assume a 4% risk free rate" and the alpha is measured over that hurdle instead of zero.

Deposits and withdrawals#

A book can also move money across the account boundary on a schedule: pay in every month, or take a share of the profits out.

This is not the same instruction as DCA. Dollar-cost averaging deploys the pool the book already has, buying a fixed amount on a schedule. A deposit grows the pool and leaves the timing to your rules. A withdrawal only ever comes out of cash the book is actually holding, it never sells a position to fund one, and a profit share never touches the starting capital.

Cross-asset conditions#

One asset's entry can depend on another. Gate a trade on a second symbol and the splitter attaches it as a cross-asset condition on the dependent asset.

When BTC RSI crosses above 65 on 1d, if ETH RSI is above 50, buy ETHUSDT.

Reading the book report#

A portfolio report shows what a single backtest cannot.

• Book equity versus its benchmark. The shared equity curve plotted against the benchmark, with a beating or trailing readout. The benchmark is an equal-weight buy and hold of the same assets unless you asked for another one; see What the book is measured against and it carries the relative numbers alongside it: outperformance, beta, correlation, alpha, tracking error, information ratio, and up/down capture.

• Per-asset results. Either full per-asset panels (grade, equity, trades) or a Per-asset attribution table (realized P&L, trades, win rate, exposure). Per-asset return and Sharpe are drawn on an equal-base display axis, a slice of the pool, not standalone capital.

• Skip ledger. Every entry signal that did not fill, with its reason. Read it before concluding a strategy did nothing: a book that suddenly trades less is usually a control doing its job.

  Reason	What happened
  NO_CAPITAL	the signal fired but the shared pool had no cash left for it
  BELOW_MIN_NOTIONAL	the affordable size was under the exchange minimum
  GUARD	a per-asset gate blocked it (session window, time filter, trading guard)
  PRE_LISTING / STALE_BAR	the asset had not listed yet, or had no bar closing on that tick
  PER_ASSET_CAP / MAX_CONCURRENT / EXPOSURE_CAP	a size or count cap was already reached
  CORRELATION_LIMIT	its returns were too correlated with a position already open
  GROUP_CAP / GROUP_POSITION_CAP	its sector was at its exposure cap, or already held its maximum number of names
  TRADE_THROTTLE	the book had already opened its allowance of new positions for the period
  LOSS_LIMIT_PAUSE	the book was paused for the rest of the period after hitting its loss limit
  REENTRY_COOLDOWN	the sleeve was still inside its post-exit cooldown
  LONG_EXPOSURE_CAP / SHORT_EXPOSURE_CAP / NET_EXPOSURE_CAP	it would have pushed exposure past a directional cap
  CASH_RESERVE	funding it would have spent the book below its cash reserve floor
  EQUITY_CURVE_FILTER	the book's own equity was below its moving average, so it was standing down
  REGIME_OFF	the book-wide regime filter was risk-off on that bar
  DIRECTION_MAX_POSITIONS	the book was already holding its maximum number of positions on that side
  SLEEVE_HALTED	that asset was retired for the rest of the run by the sleeve drawdown halt
  BOOK_TIME_FILTER / DATE_BLACKOUT	the book does not open on that day, hour or month, or the date fell inside a blackout window
  DIRECTION_BIAS	the book is restricted to one side and that signal was on the other
  WARMUP	the book was still inside its settle period
  TRADE_BUDGET / TRADE_PERIOD_BUDGET	the trade allowance for the run, or for this period, was spent
  ENTRY_SPACING	it came too soon after the previous entry
  TURNOVER_CAP	annualized turnover was already at its ceiling
  CONFIRMATION	fewer sleeves signalled together than the book requires
  BELOW_BOOK_MIN_NOTIONAL	it would have been smaller than the book's own minimum position size
  OPEN_RISK_CAP	funding it would have pushed total open risk past the book's budget
  GROUP_MAX_POSITIONS	its sector/group was already holding its maximum number of positions
  ASSET_TRADE_THROTTLE	that sleeve had already opened its allowance of positions for the period
  PER_ASSET_NOTIONAL_CAP	the sleeve was already at its dollar cap for open notional
  PERIOD_LOSS_LIMIT	the book was stopped for the rest of the period after hitting its loss limit
  LOSS_STREAK_PAUSE	the loss-streak breaker had paused new entries
  DAILY_GIVEBACK_STOP	the book had given back too much from the day's peak and stopped for the day
  OUTSIDE_TRADING_DAYS	the bar fell outside the weekdays the book may open on
  OUTSIDE_TRADING_HOURS	the bar fell outside the session window the book may open in
  BLACKOUT_DATE	the bar fell inside a date range the book sits out
  DIRECTION_NOT_ALLOWED	the book is restricted to the other side (long-only or short-only)
  BELOW_MIN_VOLUME	the bar traded less value than the book's liquidity floor
  BELOW_MIN_TRADE_NOTIONAL	the final size, after every cap, was under the book's minimum trade size
  BELOW_MIN_SIGNAL_MARGIN	the signal did not clear its own threshold by the required margin
  BENCHMARK_LAGGING	the asset had not outperformed the benchmark over the lookback
  INSUFFICIENT_HISTORY	the asset did not yet have the minimum bars of history behind it
  ROLLING_SHARPE_FLOOR	the book's rolling Sharpe was below its floor
  TOP_N_CONCENTRATION	the fill would have pushed the largest N positions past their combined cap
  ASSET_RETIRED	the sleeve had lost too much and stopped taking new signals
  WIN_STREAK_BREAKER	the book was standing down after a run of winning trades
  ASSET_ATTEMPT_CAP	that coin had already used up its allowance of entry attempts
  OPEN_LOSS_GATE	a position the book already held was too far underwater to take new risk
  DRAWDOWN_PAUSE	the book was too far below its high to open anything new, and had not recovered yet
  BIG_LOSS_COOLOFF	the book was cooling off after a single trade lost more than its limit
  BAR_ENTRY_CAP	the book had already opened its allowance of positions on that bar
  SIGNAL_EXPIRED	a signal the book could not fund waited too long and was dropped
  SIGNAL_NOT_HELD	the entry condition fired but had not held for long enough
  SIGNAL_TOO_WEAK	it cleared its own threshold by less than the other signals on that bar
  BETA_CAP	the book's beta to its benchmark was already at its ceiling
  BELOW_MIN_PRICE	the asset was trading below the minimum price the book will touch
  VOLATILITY_STANDDOWN	the book's own realised volatility was above its ceiling
  CLUSTER_CAP / SYMBOL_POSITION_CAP	its correlation cluster, or that symbol, was already full
  LOSS_STREAK_BREAKER / LOSING_PERIOD_BREAKER	the book was standing down after a run of losing trades, or of losing days
  PERFORMANCE_FLOOR	the book was halted because its win rate or profit factor fell through its floor
  ENTRY_FILTER	the book's entry filter was not satisfied on that leg's own chart
  PROFIT_LIMIT_PAUSE	the book had banked its profit target for the period and was done trading it

  Some controls act on exits or on the account rather than on an entry signal, so they never appear in this ledger. They are counted separately, under the book's risk controls: a minimum hold deferring an exit, a scheduled flatten, a sleeve being retired, positions being sized down or up by a responsive or market-state sizing rule, a position resized to a stated dollar risk or trimmed to its per-trade ceiling, an R target added to a leg, a time stop firing, an add refused by the pyramiding discipline, the book sent to cash by a regime break, a delayed fill, the book's profit floor closing it out, and each deposit or withdrawal.

  Three entries in that ledger are not a control turning a signal away, and the report marks them as such: ENTRY_FILTER_UNREADABLE means the filter could not be measured on that asset it did not fail the filter; NO_NEXT_BAR means the signal fired on the last bar of the data and a next-open fill needs a bar after it; and LIMIT_NOT_FILLED means the bar never traded through your limit, an execution miss rather than a rule. No fill is ever invented to hide one.

• Run warnings. What the engine decided, said out loud. Three of them mean the run's numbers are not comparable with a default run and are styled to say so: BOOK_COSTS_APPLIED (one cost model replaced every leg's own), FILL_TIMING_NEXT_OPEN (entries filled at the next open, not the signal close) and COMPOUNDING_OFF (every position sized off the starting capital). AVERAGED_DOWN is styled as a warning of its own, it is the only family that adds risk to a losing position.

• Money that moved outside trading. Withdrawals, profit shares and interest on idle cash all change what final equity means, so the header names them beside it. A shortfall count means a scheduled payout could not be funded in full.

• Retired sleeves. If the sleeve-retirement rule fired, the report names which asset the book gave up on and what it cost, usually the most actionable line in the whole thing.

• Book grade. One letter grade for the whole book, from the same grader as a single backtest, alongside book-level Monte Carlo and walk-forward robustness.

You can share a book as a read-only /sp/<token> page, and export the merged trades as CSV or the full result as JSON.

Known limits#

These are behaviours that are correct but surprising, the ones most likely to make a run look broken when it is doing exactly what it was told.

• Spacing between entries is measured across bars, not within one. "Leave 3 bars between any two entries" stops the book opening on bar 3 and again on bar 4. It does not stop three sleeves that all signal on the same bar from all opening at once, zero bars have passed between them. To bound a single bar's burst, say "at most one new position per bar"; the two rules compose.
• A total trade budget can finish slightly over. "No more than 100 trades" stops the book opening once 100 have booked, but positions already open still run to their own exits and book as they go. The overshoot is at most the number of positions open when the budget was reached; cap concurrent positions (or new positions per bar) to bound it.
• "Require the signal to hold for N bars" cannot be met by a crossover. A crossover is true on exactly one bar by construction, so asking it to hold for two blocks every entry and the book takes no trades. That is the rule being unsatisfiable, not an absence of edge, the run says so in its warnings. Use a threshold-style entry ("RSI is below 30") for a signal that can persist.
• A stand-down phrasing names the side you sit out. "Stop trading when the equity curve drops below its 50-day average" means trade while above it. Both readings are supported, "only trade while equity is below its average" is a valid, if unusual, instruction, so the wording decides, and the report echoes the side the book actually traded on.
• A rotation that holds cash is the momentum floor working. "Only while their momentum is positive" is an instruction to sit out, so a flat stretch with no trades in a falling market is the control doing its job, not a rotation that failed to rank. The run distinguishes the two: one warning says nothing cleared the floor, a different one says nothing could be ranked at all.
• A minimum number of holdings cannot be honoured. "Always hold at least 3 positions" is declined out loud. A signal-driven book can decline exposure but never manufacture it: there is no entry to take when nothing has signalled. State it as an allocation instead ("equal weight the book, rebalance monthly"), which holds targets rather than waiting for signals.
• A liquidity floor filters bars; it does not pick names. "Require $10m of daily volume" skips entries on thin bars for the assets you named. Choosing which assets to trade by liquidity or market cap is refused: it needs a point-in-time constituent list, and ranking today's names over history would put survivorship bias into every bar.
• Spot crypto only in v1; equities are rejected. A book holds up to 20 assets.
• Mixed timeframes are allowed. The book merges assets on absolute close time and reports the equity curve on the coarsest timeframe in the roster.
• Per-asset return and Sharpe use an equal-base display axis, not standalone capital. Win rate, profit factor and trade counts are each asset's real numbers.
• If the book hits the equity floor it halts early and flags ruin.
• Futures books are not supported yet.
• Starting capital stated in the prompt ("a $250k book") is carried into the run. If you drive the API or the MCP tools yourself, pass the settings object parse_portfolio returns straight to run_portfolio, it holds every book-level control the prompt stated, and a book run without it is a book without your risk limits.

Next: Build a portfolio step by step, or the MCP tools to run one programmatically.