Timeframes and sessions
Timeframe string conventions, regular and extended trading hours, market calendars, display time zones, and session presets.
Each market data request specifies a single timeframe and trading session, and your provider serves as the source of truth for when each market is open. This page covers the timeframe strings passed to getBars and subscribe, regular and extended session filtering, the getCalendar contract, display time zones, and the session presets shared across Vela Pro profile features.
Timeframes
Vela's open-source core forwards the chart's timeframe string directly to getBars and subscribe without aggregating one timeframe from another. Each timeframe is requested and cached as an independent series. When your upstream API does not natively serve a requested interval, aggregate finer bars inside your provider.
| Source | String passed to your provider |
|---|---|
| Top bar timeframe presets | Configured preset string ('1', '5', '15', '30', '60', '240', 'D', 'W', and 'M' by default, replaceable via timeframes) |
Keyboard timeframe entry (45, 3h, 2D, 30S) | Intraday intervals normalized to minutes ('45', '180', '2880'), with seconds retaining 'S' ('30S') |
Constructor timeframe option | Exact string configured in options |
Numeric strings without a unit represent minutes. Uppercase 'D', 'W', and 'M' represent days, weeks, and months (optionally preceded by a multiplier such as '2W' or '3M'), while 'S' represents seconds. Lowercase aliases ('15m', '4h', '1d', '1w') are also accepted through options, which makes letter case significant between 'M' (month) and 'm' (minute). Always normalize incoming timeframe strings before mapping them to upstream API intervals, because many external APIs treat M as minutes.
Several Vela Pro features also request auxiliary timeframes directly from your provider:
- TPO requests candles at its configured block interval (
'5','15','30','60', or'240') regardless of the chart's active timeframe, issuing one[from, to]request per session withoutlimit. - Default quotes in the watchlist and symbol search request recent
'D'bars and subscribe to'D'updates. - Bar replay (when configured with the replay resolution control) requests the selected lower timeframe across
[from, to]windows withoutlimit.
Rejecting unsupported timeframes
Returning an empty array [] indicates that no bars exist within the requested time window. When an instrument never supports a requested timeframe granularity (for example, minute intervals on a monthly economic series), throw DataUnavailableError instead.
import { DataUnavailableError, type DataProvider } from '@luxalgo/vela';
declare const fetchCandles: DataProvider['getBars']; // upstream bar request
export const getBars: DataProvider['getBars'] = async (ticker, timeframe, range) => {
// Monthly macroeconomic series with no intraday data.
if (ticker === 'CPI' && /^\d+$/.test(timeframe)) {
throw new DataUnavailableError({ reason: 'timeframe', finest: '1M', default: '1M' });
}
return fetchCandles(ticker, timeframe, range);
};Throwing DataUnavailableError stops loading and polling for that series and emits data:unavailable. The workspace switches the chart to default (or finest when default is omitted) while preserving the user's chosen timeframe for the next symbol that supports it. Format finest and default using uppercase unit suffixes ('60', '1D', 'W', '1M'), matching the timeframes field in Symbol metadata.
Regular and extended sessions
A chart displays either the 'regular' session (default) or the 'extended' session, which includes pre-market and post-market trading. Set the initial session with the session workspace option; users can switch sessions from the bottom bar.
Every bar request includes the active session via range.session in getBars and opts.session (the fourth argument) in subscribe. Regular and extended bars are cached as separate series. Providers whose markets trade continuously can ignore this parameter.
Session controls, pre/post-market background shading, and calendar queries activate when getSymbolInfo declares session hours:
import type { DataProvider } from '@luxalgo/vela';
const API = 'https://api.example.com';
export const hours: Pick<DataProvider, 'getSymbolInfo' | 'getCalendar'> = {
async getSymbolInfo(ticker) {
// Regular and extended hours formatted as HHMM-HHMM in the exchange time zone.
return { ticker, timezone: 'America/New_York', session: '0930-1600', session_extended: '0400-2000' };
},
async getCalendar(ticker, range) {
const query = new URLSearchParams({ symbol: ticker, from: String(range.from), to: String(range.to), session: range.session ?? 'regular' });
const windows = (await (await fetch(`${API}/calendar?${query}`)).json()) as Array<[number, number]>;
return windows.sort((a, b) => a[0] - b[0]);
},
};session specifies regular trading hours, and session_extended specifies the full trading day surrounding them. An extended span whose end time precedes its start time ('1700-1600') represents an overnight trading day running from evening to evening. The chart computes pre-market and post-market background shading directly from these two strings.
Market calendar
getCalendar(ticker, range) returns the intervals during which the market is open between range.from and range.to as ascending [open, close) pairs in epoch milliseconds, with market holidays, early closes, and daylight saving time already applied. range.session selects either 'regular' windows (default) or 'extended' windows. Because the core contains no built-in holiday rules, getCalendar is the sole source of schedule exceptions.
On symbols whose getSymbolInfo metadata declares a session, three features read getCalendar:
- Market status badge in the chart status line (
Market Open,Pre-Market,Post-Market,Extended Hours,Market Closed, orMarket Holiday). It queries both regular and extended windows around the current time and updates automatically at each session boundary. - Session-anchored profiles (TPO, Session Volume Profile, and Session Volume Tails). Daily profiles cover the calendar's open window for each trading day, while weekly and monthly profiles group those daily windows.
- Live footprint filtering on regular-hours charts. Vela Pro drops incoming live footprint slices that fall outside the regular calendar windows.
Continuous markets
For markets that trade 24/7, omit getCalendar and return session: '24x7' (or omit session) from getSymbolInfo. The market status badge stays on Market Open, the bottom bar hides the session toggle, and session profiles align to UTC boundaries (00:00 UTC for days, Monday for weeks, and the first of the month for months).
Display time zone
The workspace timezone option sets the display time zone for the time axis and crosshair readout. Pass an IANA time zone string ('Etc/UTC' by default) or 'exchange', which renders each chart in the timezone declared by its symbol's metadata. Call workspace.setTimezone(zone) to update it programmatically, or let users switch zones from the bottom bar.
Time zone conversion applies to intraday bars only. Daily, weekly, and monthly bars represent calendar trading dates; stamp their time at 00:00:00 UTC of the trading date so they display that date consistently across every time zone.
Session presets
The TPO chart type, overlay TPO indicator, Session Volume Profile, and Session Volume Tails share a common session model. Profiles anchor to Day, Week, or Month periods, and Day profiles can be narrowed to a trading-hours preset:
| Trading hours preset | Window definition |
|---|---|
| Full day | Calendar windows matching the session currently shown on the chart |
| Regular hours (RTH), Extended hours (ETH) | Regular or extended calendar windows regardless of the chart's session toggle |
| Pre-market, Market, Post-market | 09:00-13:30, 13:30-20:00, and 20:00-24:00 UTC |
| London, New York, Asia | 08:00-16:30, 13:00-22:00, and 00:00-09:00 UTC |
| Custom | Start and end times formatted as HHMM in UTC (an end time earlier than start wraps past midnight) |
The first two rows follow your provider's getCalendar windows, whereas the named regional and sub-session presets use fixed UTC clock times. When a symbol has no calendar, Full day and Extended hours use 00:00-24:00 UTC and Regular hours uses 13:30-20:00 UTC.
Two preset labels differ between the TPO chart type and the indicators (Full day is labeled All day in the indicators, and Market is labeled Market (US)). See TPO and Built-in indicators for setting details.
Related
- Custom data providers
- Symbology
- Adding a data provider in the core documentation