Attaching a Portfolio: promotion and swaps
You attach a Portfolio to an account by promoting it. Promotion pushes a Portfolio, or a Backtest, into an account so the account trades it. The core rule that shapes everything on this page: every promotion is a swap. An account holds at most one Portfolio, so promoting into an account that already holds one replaces what was there. Swaps run only while the account is Stopped, and a promotion onto a Running or Paused account either forces its way to Stopped now or queues until the account gets there on its own.
Promotion: the three entry points
You promote from one of three places.
- At account creation. When you create an account, you can pick a Portfolio or a Backtest in the same step. Skipping the pick is allowed. The account is created empty and Stopped, and you promote into it later.
- From a Portfolio page. A "live trade this" call-to-action (placeholder label) pushes the Portfolio into an account of your choice.
- From a Backtest page. The same call-to-action. A Backtest cannot attach directly, because an account wraps a Portfolio, so the platform wraps the Backtest first. See Backtest promotion: auto-wrapping.
Every promotion is a swap
An account holds at most one Portfolio at a time. If the destination account already holds a Portfolio, promoting a new one replaces the old one. That replacement is a swap, and the word carries the same meaning for the rest of this page: attaching a Portfolio to an account that already has one, exchanging the old for the new. Promoting into an empty account is the degenerate case of a swap, with nothing to replace.
Backtest promotion: auto-wrapping
Promoting a Backtest auto-creates a Portfolio holding that single backtest at 100% allocation, then attaches that Portfolio to the account. You never see a separate "wrap into portfolio" step.
The auto-wrapped Portfolio lives inside the account's snapshot, not in your library. It behaves exactly like any other attached Portfolio. There is no behavioural difference between an account wrapping a Portfolio you built in your library and one wrapping an auto-created one. If you want an editable copy in your library, clone it out of the snapshot.
The auto-wrap is a convenience, not a second kind of Portfolio. Once attached, an account trading an auto-wrapped Portfolio and an account trading a library Portfolio are indistinguishable in how they run, swap, and record events.
Swaps require Stopped
A swap executes only while the account is Stopped. An account that is already Stopped swaps at once: the new Portfolio replaces the old, and the account is left Stopped on the new Portfolio, ready to run.
Initiating a promotion on a Running or Paused account presents two options for reaching Stopped.
Stop now
Force-close all open positions immediately, perform the swap, and resume Running on the new Portfolio. The account passes through Stopped in the same action and comes back up trading the newly attached Portfolio.
Stop now force-closes every open position immediately. Positions exit at the current market, not on their own exit logic, so use it only when you accept closing the book right now.
Queue the swap
The account moves to Paused. No new positions open. Existing positions are managed until they close naturally. When the last open position closes and the account reaches Stopped, the swap executes automatically and the account resumes Running on the new Portfolio. Nothing is force-closed, so the old Portfolio winds down on its own terms before the new one takes over.
Queued swaps are cancellable
While a swap is queued, you can cancel it. Cancellation leaves the account in its current state, typically Paused, without performing the swap. After cancelling, you can resume the account, stop it, or queue a different swap.
Cancellation is itself a ledger event, recorded alongside the queue and execute events for the swap. The ledger holds the full sequence, so a queued-then-cancelled swap leaves a trace even though the Portfolio never changed.
Telling a queued-swap account apart
A Paused account with a queued swap is meaningfully different from a plain Paused account. Both stop opening new positions, but only one has a Portfolio waiting to take over the moment the book empties. The account view distinguishes them: it carries an indicator that the account is Paused with a swap queued, surfaces which Portfolio is queued, and offers the cancel option inline.
The real distinction is the state itself, a Paused account with a swap queued, not any particular badge or wording used to surface it.
Related workflows
This page covers the model behind promotion and swaps. The step-by-step procedures live in workflow guides:
- Promote a backtest to a paper account: open a Backtest, use the "live trade this" call-to-action, choose the default paper account, and let auto-wrapping attach it. The account begins Running on the snapshot.
- Build a Portfolio, live-trade it, then swap it later: combine several backtests into a Portfolio, attach it to a live account, improve one backtest over time, rebuild the Portfolio, and promote the new version with Queue the swap so the running positions wind down naturally before the swap executes.
For how the attached Portfolio and its dependencies are captured and inspected, see snapshots and inspecting an account. For the states a swap moves an account through, see account states and lifecycle.