OHLCV and bar data

QuantCraft backtests need OHLCV (open, high, low, close, volume) candles for each symbol you trade. The engine loads that data before your strategy runs, then drives your strategy lifecycle callbacks with a current bar view (bar) on each step. At the end of the run you can optionally work with the full series passed into on_finish(bars, …). Configure loads from Test (Running code).

This page covers where data comes from (loaders), how date ranges and warmup work, and how to use the full-series bars argument in on_finish. Pair with Fundamentals when you mix price and filings data; see Account model for how trades relate to prices.

---

Loaders (data sources)

On the Symbol & data tab of Run backtest you choose a price feed. The engine uses one of two loaders behind the scenes:

Alpaca

• Loads candles from Alpaca using your API key and secret, or an OAuth-linked Alpaca connection with a valid link id.
• Supports US equities and crypto (you pick the asset type in the dialog).
• Supports many timeframes — daily, weekly, hourly, 4-hour, and several intraday minute bars (aligned with the app’s chart timeframe labels).
• History is fetched in chunks until the requested range is satisfied (or until a minimum bar count is reached when you use the legacy “no explicit dates” mode).

Use Alpaca when you want broker-connected feeds or the full intraday timeframe set (1-minute through 4-hour, plus daily and weekly).

QuantCraft storage (hosted)

• Loads candles from QuantCraft hosted storage when you are signed in (the app sends your session token).
• Files are organized by symbol and timeframe: 5-minute, hourly, daily, weekly, and monthly.
• The full file is fetched, then optionally filtered to your chosen calendar date range.

Use QuantCraft storage when you are signed in without Alpaca credentials, or when you want hosted OHLCV bundles from the QuantCraft symbol catalog (5-minute, hourly, daily, weekly, or monthly).

Choosing between them

In strategy callbacks, read prices from the bar object the engine passes you — not from a global OHLCV singleton. In the IDE, module-level qc_ohlcv is often unset when your file loads; relying on it can break. The bar view is always correct for the current simulation step.

---

Time ranges

You control which bars participate in the backtest with start date, end date, and optionally warmup.

Calendar range (start_date + end_date)

When you set both dates on the Simulation tab (format YYYY-MM-DD, interpreted as UTC calendar days):

• The engine keeps only bars that fall in that window.
• The range is treated as a half-open interval: from the start of the start day through the end of the end day in the product’s usual convention (bars on the end calendar day are included as configured by the engine).

Alpaca: candles are requested for that calendar span.

QuantCraft storage: the full series for the file is downloaded, then filtered to the same calendar-day window.

If you omit both dates:

• Alpaca uses a legacy backward walk: the engine walks backward in time until enough history is loaded (subject to timeframe limits), rather than a fixed calendar window you typed.
• QuantCraft storage uses all bars in the file (no extra filter).

Warmup bars (warmup_bars)

Optional non-negative integer: extra bars loaded before your start date so indicators can look back without running out of history.

• Warmup bars are visible through bar.close[1], bar.close[2], … and bar.bars_back on the first execution bar.
• on_bar / on_tick / on_timer still run only inside your selected execution window — warmup is for history only, not extra simulated “trading days” in the result.

bar_index vs calendar

• bar_index counts execution bars only (first bar inside your selected range is 0, then 1, …). It does not count warmup-only bars.
• Bars are simulated oldest to newest within the execution window.

---

Bar data inside callbacks (bar)

On every on_bar and on_tick (and on_timer on forward runs when configured), the engine passes bar: an OHLC bar view (OhlcvBarView) for the symbol that callback is for. It behaves like a read-only mapping but isinstance(bar, dict) is false — use bar["close"] or attribute-style access, not dict-only APIs.

In backtest, on_tick receives synthetic prices from each bar's OHLC (four calls per bar, no real tick history). On forward runs, on_tick fires on each live broker quote from Alpaca while the price argument tracks the latest mark — see Strategy lifecycle.

You can use it like a read-only mapping:

You can also read history relative to the current bar with offset indexing (same bar, previous closes, etc.):

• bar.close[0] is the close for the current bar context (same idea as float(bar["close"]) in backtest on_bar).
• Larger indexes walk backward in time; bar.bars_back tells you how far you can look.

Forward runs (chart toolbar timeframe):

• In on_bar after a bar completes, bar.close[0] is the just-completed close; bar.close[1] is the previous completed bar.
• In on_tick, bar.close[0] is the forming bar / live price; the last completed close is at bar.close[1] while a bar is forming.

Volume at [0]:

• Forward on_tick: volume[0] on the forming candle is provisional (often a single tick’s size). Use volume[1] for the last completed bar’s volume.
• Backtest: all four synthetic ticks use the full bar row — volume[0] is the full bar volume, not a provisional tick size.

This is the right place for per-step trading logic: entries, exits at bar close, simple moving averages, and anything that only needs the current bar plus lookback.

---

Primary and additional timeframes (get_bar)

The primary run timeframe is always available via rt.get_bar (you do not need to list it under Additional timeframes). When your strategy also needs bars at a different resolution (for example daily trend filters on a 5-minute backtest), select those extras in the Run backtest modal Additional timeframes dropdown on Symbol & data, then read them from any callback:

Configure Additional timeframes in Backtests; save selections in run presets (.qcs) under secondaryTimeframes.

BarSnapshot fields

get_bar returns a BarSnapshot (or None) with: open, high, low, close, volume, t.

shift semantics

Backtest: at shift=0, secondary high/low are time-aligned to the simulation clock for each TF.

Forward run: the primary bar follows the chart toolbar timeframe. Secondary buffers update when a bar completes on that TF's stream — high/low at shift=0 may lag until that bucket completes; prefer shift=1 for reliable previous-bar OHLC. In on_tick, volume[0] on the primary bar may be provisional (still forming).

Returns None when that timeframe has no buffer for the run (not the primary TF and not selected under Additional timeframes) or data is unavailable.

Timeframe enum

Import with from quantcraft import Timeframe:

---

Optional full series: on_finish(bars, …)

When the simulation ends, the engine calls on_finish once. If your strategy defines the extended signature, you receive full-series OHLC rows for post-processing — indicators over the whole run, exporting series, final refresh_metrics marks, etc.

bars — clock symbol, oldest first

• bars is a list of dictionaries for the clock symbol (script SYMBOL if that ticker is loaded, otherwise the first loaded symbol — the modal has no primary-symbol control).
• Order is chronological: oldest bar first, newest last — the opposite convention from QcOhlcv index [0] = newest in notebook-style APIs.
• Each row includes at least open, high, low, close, volume, and t when timestamps exist. When fundamentals are enabled, rows may also include a fundamentals snapshot for that bar.

Typical uses:

Use bars[-1]["close"] (or the last row’s fields) as the final mark when calling account.refresh_metrics({symbol: last_price}) so open positions are valued at the end of the run.

bars_by_symbol — multi-symbol runs

When you backtest more than one ticker, bars still refers to the clock symbol only. For every symbol’s full aligned series, use bars_by_symbol:

• A mapping from uppercase ticker → same shape of list as bars (chronological dicts per symbol).
• Use it when you need cross-sectional or per-symbol full histories at finish time (correlation, relative strength, per-symbol indicators).

When you don’t need on_finish

If your strategy only needs the current bar and lookback offsets, you can implement on_bar / on_tick only and skip heavy full-series work. on_finish is optional for logic — but it is still the right place for chart_indicators payloads and refresh_metrics that need the last price.

---

How this ties to Test Results

The structured backtest result includes an ohlcv.bars (or equivalent) list: one row per simulated execution step, with OHLC fields and optional fundamentals snapshots — aligned with what you saw in callbacks. on_finish(bars, …) is the same chronological series the engine uses for “whole run” math on the clock symbol, so your finish-time code matches what appears in results and charts.

---

Quick reference