Contract rolls in live trading
A continuous series such as fut:XCME:ES moves from one dated contract to the next four times a year. A backtest makes each roll inside the engine, and most strategies never notice. A live strategy trades through the roll: real orders are cancelled and placed again, the position moves from one contract to the next, and the prices the strategy calculates on jump by the gap between the two contracts. This section puts the whole roll in one place: who names the contract, what happens at the roll and in what order, what the prices do, and what the strategy must do itself. It ends with a demo, rolltrend, run across a real roll.
In short:
- The strategy names only the logical root. Its own engine turns
fut:XCME:ESinto the contract the series holds, such asESZ26. The desk and the broker see only dated contracts. - A live run on a real-time feed needs the roll rebase, which is on by default (GLE-1502). The strategy then calculates on the held contract’s own prices, and at each roll the engine moves the strategy’s history onto the next contract’s prices.
- The engine makes the roll. It cancels the working orders, rolls the position with two market orders and places the orders again on the next contract, at their moved levels. The strategy is told of the roll, not of the legs.
- The SDK moves what it keeps; the strategy moves what it keeps. The SDK moves the series, the position’s cost, the working orders and
TradeState. A price the strategy keeps itself, such as a remembered level or an indicator’s running value, it moves inOnRebase. Otherwise the live run stops trading as its backtest does.
The reference sections behind this one are Re-adjusting at each roll (the strategy’s side), Continuous futures in live mode (the venue’s side), Running live on a real-time feed (the stream’s side) and Roll execution at the cut (the backtest’s roll, which the live roll follows).
Who names the contract

The translation from the logical root to a dated contract happens in the strategy’s own engine, not at the desk:
- The engine holds the contract the series is on, from the roll schedule marketfeed serves. An order for
fut:XCME:ESgoes out as an order for that contract. Under the roll rebase the strategy’s prices are already the held contract’s own, so only the name changes. The engine also makes every roll’s orders. - The desk sees dated contracts only: the member’s orders, its positions (
DeskHolding, one per contract) and the roll’s legs, which carryroll_leg. Its configuration lists both contracts of a roll, and a member’s limits must allow one close leg and one open leg of the position’s size (A demo for a roll at a real venue). Its trade director judges the open leg as a transfer of the position. - The broker knows a contract by its own id. The venue finds each contract from the terms the data adapter serves: symbol, contract month, exchange and expiry (Finding contracts at the IBKR venue).
A strategy may address the held contract itself (ctx.ActiveContract(symbol), priced from Bar.RawClose). Such an order is pinned: the roll cancels it, with CANCEL_REASON_ROLL, and does not carry it to the next contract. An order on the logical symbol is carried.
A roll, step by step
The sequence below is the ES roll from ESU26 to ESZ26 on Sunday 13 September 2026, for a strategy on daily bars. The cut, 22:00 UTC, fell at the ETH open, after the weekend.

- The schedule. Marketfeed’s forward roll calendar names the roll and its cut well before it. A live run’s venue contracts are fixed at its start: the held contract and the next one the schedule names.
- The last bar of the old contract. The strategy decides on it at
ESU26’s own price. - The roll fires at the later of the cut and the incoming contract’s ETH open, so the market is open when the legs go. On a daily series the loop wakes for it between bars, as it does for a timer.
- The seam. Marketfeed measures the gap on the live bars, usually just after the cut. Until it arrives the roll is held and openings stop, for up to
roll_deadline(ten minutes by default on a stream). - The strategy hears the roll first:
OnRoll, then the rebase. The SDK moves its own state, and thenOnRebaseruns. Nothing reaches the venue until the strategy has heard the roll.OnRebaseplaces no orders, andOnRollhas no context to log with, so log inOnRebase. - The cancels. The engine cancels the working orders on the outgoing contract and waits until the venue confirms each one. The strategy is not told of these cancels. An order that fills before its cancel takes effect reaches the strategy as an ordinary fill, and the legs move the position left after it.
- The legs. Two DAY market orders, the close of
ESU26first, then the open ofESZ26. The engine waits until both have filled, up toroll_deadline(two minutes by default) from the roll’s start. - The orders again. Each order on the logical symbol is placed again on
ESZ26at its moved level. Under order lifetime v2 each becomes a new attempt, and the strategy gets oneOrderUpdatenaming the attempt it replaces (Order lifetime v2 across a roll). - The first bar of the new contract. The strategy decides on it at
ESZ26’s own price.
The operator sees each step on standard error. The roll’s lines for this roll would read, with the venue’s fill prices in place of <price>:
algo: the roll ESU26->ESZ26 of fut:XCME:ES@1d fires at 2026-09-13T22:00:00Z (its cut 2026-09-13T22:00:00Z)
algo: roll leg sell 1 ESU26 filled at <price> against the served seam 7659.5: slip <slip>
algo: roll leg buy 1 ESZ26 filled at <price> against the served seam 7727.25: slip <slip>The served seam is the price each leg fills at in the backtest. The difference is the roll’s slip: real money that the backtest does not see.
What the prices do
marketfeed serves a continuous series adjusted from its end: every bar is on the basis of the newest contract the data reaches. Live, there is no newest contract yet. Under the roll rebase, on by default since GLE-1502, the strategy sees each bar at its own contract’s price, in a backtest as live, and at each roll the engine moves the history onto the next contract’s basis. Under panama it adds the gap to every older bar. Under ratio it multiplies them by the ratio of the two prices.

On Friday 11 September the live strategy’s last close is ESU26’s 7660.75. A backtest with --roll-rebase=false shows that bar at 7728.50: ESU26’s close plus the 67.75 gap of a roll that has not happened yet, as is every bar before it. A backtest under the default shows 7660.75, as the live run does. That is why the rebase is the default: a strategy is validated on the prices it will see live.
The moved history is the old contract’s prices plus the gap, not the new contract’s own history. The two are close, as the right panel shows, because the gap between two contracts moves slowly.
A price moves in one of two ways:
- A level (a price, a stop, an average) moves to
r.Level(x):xplus the gap under panama,xtimes the ratio under ratio. - A distance (an average true range, a trailing amount, a band’s width) moves to
r.Distance(d): unchanged under panama, times the ratio under ratio.
What the strategy must move
| What the strategy holds | Who moves it | How |
|---|---|---|
ctx.Series(id): the bars, at the declared lookback | the SDK | the engine sends the moved history |
An indicator computed from ctx.Series on every bar (SMA, ATR, RSI, highest high) | nothing to do | it is computed from the moved bars at the next bar |
The position’s AvgPrice and AvgPriceAdjusted | the SDK | by Level; AvgPriceRaw and Realized stay |
| Working orders on the logical symbol: limit and stop prices, trailing amounts, attached orders | the SDK and the engine | by Level and Distance, to the bit |
ctx.TradeState: entry price, entry high and low, peak, trough | the SDK | by Level |
| A price level the strategy keeps: a remembered high, a breakout level, an EMA’s running value | the strategy, in OnRebase | r.Level(x) |
| A distance the strategy keeps: an ATR’s running value, the average gain and loss behind an RSI, a trailing amount | the strategy, in OnRebase | r.Distance(d) |
| A number that does not depend on the basis: bars since entry, an RSI or z-score reading kept for later | nothing to do | |
| A percentage or a log return it keeps, under panama | the strategy, in OnRebase | rebuild it from r.Bars |
kit.Tracker, kit.StopSuite, kit.LotBook | the strategy, in OnRebase | .Rebase(r.Gap, r.Ratio) |
A running indicator that is linear in the prices, such as an EMA, moves exactly by Level. One that is not, such as a percentage change under panama, has no exact move: rebuild it from r.Bars, the moved history, oldest first. r.Bars holds only the series’ declared lookback, so declare enough for the indicator to settle.
The rule of thumb: if a value would change when the whole history moved by the gap (under panama) or was scaled by the ratio (under ratio), the strategy must move it. If the SDK holds it, the SDK already has.
The demo: rolltrend
rolltrend (strategies/demo/go/rolltrend) is a long-only trend follower on one continuous future. It keeps two prices of its own and lets the SDK move everything else:
- flat, it buys
Lotsat the market when the close crosses above anEMA-bar exponential moving average of the closes, which it keeps as running state; - once long, it places one protective GTC sell stop
StopATRaverage true ranges below its entry, and never moves it; - it sells at the market when the close falls
TrailATRaverage true ranges below the highest close since its entry, which it remembers.
The average true range is computed from ctx.Series on every bar, so it needs nothing at a roll. The protective stop is a working order, which the SDK and the engine move. The EMA and the highest close are the strategy’s own, so it moves them in OnRebase (the inputs’ descriptions are trimmed here):
type RollTrend struct {
Lots int `algolang:"default=1,min=1"`
EMA int `algolang:"default=20,min=2,max=400"`
ATR int `algolang:"default=14,min=1,max=400"`
StopATR float64 `algolang:"default=4,min=0.1"`
TrailATR float64 `algolang:"default=3,min=0.1"`
Tick float64 `algolang:"default=0,min=0"`
MoveState bool `algolang:"default=true"`
Verbose bool `algolang:"default=false"`
avg ema // the EMA of the closes: a price level
prevAbove bool // the last close was above the EMA as it stood then
high float64 // the highest close since the entry: a level; 0 while flat
}
func (s *RollTrend) OnRebase(ctx *algolang.Context, r algolang.Rebase) {
if s.MoveState {
s.move(r)
}
// ... logs the roll, the moved values and the stop the SDK moved
}
// move moves the two prices the strategy keeps: both are price levels.
func (s *RollTrend) move(r algolang.Rebase) {
s.avg.Value = r.Level(s.avg.Value)
if s.high != 0 { // 0 while flat
s.high = r.Level(s.high)
}
}prevAbove, whether the last close was above the EMA, needs no move: the close and the EMA move together. MoveState=false skips the two moves, to show what goes wrong.
Three runs over the archive
The demo runs on ES daily bars from 2023 to October 2026, across 15 rolls, three ways:
# the served end-adjusted prices, the rebase off
bin/algo run --strategy bin/rolltrend --symbol fut:XCME:ES --bar-interval 1d \
--date-from 2023-01-01 --date-to 2026-11-01 --roll-rebase=false
# the default: as a live run calculates
bin/algo run --strategy bin/rolltrend --symbol fut:XCME:ES --bar-interval 1d \
--date-from 2023-01-01 --date-to 2026-11-01
# the same, with the strategy's own prices not moved
bin/algo run --strategy bin/rolltrend --symbol fut:XCME:ES --bar-interval 1d \
--date-from 2023-01-01 --date-to 2026-11-01 --inputs MoveState=false| Run | Fills | Net profit | Trades the same as the rebase-off run |
|---|---|---|---|
--roll-rebase=false | 61 | +57,862.50 | |
| the default | 61 | +57,862.50 | all 61 fills, at the same prices |
the default, MoveState=false | 61 | +60,525.00 | four trades differ |
With OnRebase moving its two prices, the default run makes every trade of the rebase-off run, fill for fill. A live run on a real-time feed calculates as the default run does, so it would make them too. With MoveState=false four trades change, each in the days after a roll:
| Roll (gap) | With OnRebase | MoveState=false | Why |
|---|---|---|---|
ESH23->ESM23, 12 Mar 2023 (+34.75) | buys on 21 Mar at 4038.75 | buys on 16 Mar at 3995 | the close is compared with an EMA 34.75 too low |
ESU23->ESZ23, 10 Sep 2023 (+49.5) | sells on 20 Sep at 4445 | sells on 21 Sep at 4370.25 | the highest close is 49.5 too low, so the exit comes a day late |
ESZ24->ESH25, 15 Dec 2024 (+70.25) | buys on 24 Dec at 6099.25 | buys on 23 Dec at 6037.75 | the EMA is 70.25 too low |
ESU26->ESZ26, 13 Sep 2026 (+67.75) | buys on 18 Sep at 7722 | buys on 14 Sep at 7699.25 | the EMA is 67.75 too low; see below |
Over this window the four changes happened to make 2,662.50 dollars more. That is luck, not a better rule. On other data they lose, and either way the live run no longer trades as the backtest that was used to judge it.
The roll of 13 September 2026
--inputs Verbose=true logs each bar. Around the ESU26->ESZ26 roll, the default run reads (prefixes trimmed):
rolltrend: 2026-09-09 close 7648 < 7648.25, 3 ATRs below the highest close 7825.25: sell 1
rolltrend: sold 1 fut:XCME:ES at 7646.5 (exit-2026-09-09)
rolltrend: 2026-09-10 ESU26 close 7602 EMA 7682.53 ATR 61.00 flat
rolltrend: 2026-09-11 ESU26 close 7660.75 EMA 7680.46 ATR 63.93 flat
rolltrend: 2026-09-13 rolled ESU26 -> ESZ26, gap 67.75: EMA 7680.46 -> 7748.21
rolltrend: 2026-09-14 ESZ26 close 7700 EMA 7743.62 ATR 64.89 flat
rolltrend: 2026-09-15 ESZ26 close 7663.75 EMA 7736.01 ATR 66.18 flat
rolltrend: 2026-09-16 ESZ26 close 7622 EMA 7725.15 ATR 71.27 flat
rolltrend: 2026-09-17 ESZ26 close 7702.25 EMA 7722.97 ATR 73.70 flat
rolltrend: 2026-09-18 ESZ26 close 7725 EMA 7723.16 ATR 74.71 flat
rolltrend: 2026-09-18 close 7725 crossed above the EMA 7723.16: buy 1
rolltrend: bought 1 fut:XCME:ES at 7722 (entry-2026-09-18)The EMA moves from 7680.46 to 7748.21 at the cut, by the gap. The rebase-off run’s EMA on 11 September is 7748.21 too: it was on ESZ26’s basis all along. From 14 September the two runs see the same bars and the same EMA, and both buy on 18 September. The run with MoveState=false leaves the EMA behind:
rolltrend: 2026-09-13 rolled ESU26 -> ESZ26, gap 67.75: EMA 7680.36 kept (MoveState=false)
rolltrend: 2026-09-14 ESZ26 close 7700 EMA 7682.23 ATR 64.89 flat
rolltrend: 2026-09-14 close 7700 crossed above the EMA 7682.23: buy 1
rolltrend: bought 1 fut:XCME:ES at 7699.25 (entry-2026-09-14)The first ESZ26 bar closes at 7700, below the moved EMA but above the one left on ESU26’s prices. The market did not cross anything: the strategy compared a price on one contract with an average on the other.
An EMA left behind is wrong for a while, not for ever: each new close shrinks the error, by a factor of 1 - 2/21 a bar for EMA(20), so it fades over a few months. Before this roll the EMA left behind reads 7680.36, not 7680.46: the June roll’s 62.5 has almost gone. The damage falls in the weeks after each roll, which is where all four changed trades are.

The protective stop needs no code. Before the 2023 roll from ESH23 to ESM23 the strategy placed it at 3832 on ESH23’s prices. At the roll the SDK and the engine moved it by the gap to 3866.75 and placed it again on ESM23. It filled there on 13 March, as it does with the rebase off.
The figures are drawn by scripts/doc-figures/live_rolls.py from these runs.
Taking it live
A live run on a real-time feed needs, for a continuous series:
- the roll rebase, which is on by default (GLE-1502). A run that turns it off (
--roll-rebase=false,"roll_rebase": falsein a deployment file) is refused at its start; - a strategy that accepts the
roll-rebasecapability, onstdio-pb-v1orstdio-csv-v2: the Go SDK and the nine language ports all do (GLE-1505). One that does not is refused after itsInit; - a
--date-fromat the current minute. An open--date-fromanchors the adjustment at 1970 and is refused (ADJUST_ANCHOR_UNHELD).
As a member of a deployment against the desk:
{
// rolltrend.json names bin/rolltrend on fut:XCME:ES, run id rolltrend-es
"portfolio": "rolltrend.json",
"mode": "paper",
"desk": "https://127.0.0.1:8442",
"feed": "stream",
// the roll rebase is on by default (GLE-1502), so no "roll_rebase" key
// the wait for the legs (default 2m) and for the seam (default 10m)
"roll_deadline": "2m",
"members": {"rolltrend-es": {}}
}The desk’s configuration lists both contracts of the next roll, ESZ26 and ESH27, each with marketfeed’s name for its quotes as its feed_symbol. A demo for a roll at a real venue walks through a whole PAPER setup.
What else to watch
Before going live
- Backtest under the default and with
--roll-rebase=false, and compare the trades. A difference is a price the strategy keeps and does not move. - Prefer order lifetime v2. Under v1, the live default, a roll with no position drops a bracket child without telling the strategy, so its view keeps an order the venue no longer has.
- Find orders by label, side and type, never by broker id. A roll gives every order it places again a new broker id, and under v2 a new attempt.
- Place an order on the logical symbol, not on the held contract, unless it should end at the roll.
At each roll
- Openings stop while a roll waits for its seam, while the feed is down and while the run catches up. An order that would open or add to a position is refused with
REJECTEDunder its own label. Retry it on a later bar, asrollholddoes. Orders that only reduce a position go through. - A Day order the venue ended at the session close is not carried.
- A stop the new contract’s price is already through cannot rest. The roll sends it as the order it has become, a market order, as the venue would trigger it, and the strategy sees its fill under the stop’s label.
- The legs fill at the market, not at the seam. The slip is real money, so the live P&L moves away from the backtest by it.
- A trade director, the desk’s or the run’s own, judges the open leg as a transfer. If it refuses, the position closes on the old contract and the bracket children that were to ride the open leg are lost. Under v1 the run stops.
- With several roots, each rolls on its own schedule, so a spread’s two legs roll at different times. A timer due after a cut sees the new contract.
When a roll fails
- A cancel not confirmed, or a leg not filled, within
roll_deadlinestops the run. When the close leg did not fill, the position is still on the old contract, and a restart finishes the roll. When only the open leg failed, the member is flat and the operator restores the position. - A seam that does not arrive within the hold stops the run, and a restart finishes the roll.
- A roll into a contract outside the run’s venue contracts, such as the roll after next, stops the run. Restart the run between rolls.
- A schedule that moves a roll the run already holds stops the run.
- A late roll, whose outgoing contract expired before the cut, trades nothing: settle the position at the venue, then restart.
Restarts
- A restart after a missed cut makes one catch-up roll before its first bar. The strategy hears
OnRollbut no rebase, because its history already starts on the new contract’s basis. The legs fill at the market on the next bar of each contract. - Do not roll a position early by hand. A restart that finds a position on a contract the series has not reached yet refuses to start (reconciliation invariant 5).
- A strategy that keeps prices in its process loses them at a restart, as
rolltrendloses its highest close and restarts it from the current close. Rebuild such a value on the first bar fromctx.Seriesandctx.Position, or accept the difference.