Vela, our next-generation charting platform, is live at vela.luxalgo.com.
LuxAlgo
Symbols and sessions

Timeframes and sessions

Timeframe string conventions, regular and extended trading hours, market calendars, display time zones, and session presets.

View as Markdown

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.

SourceString passed to your provider
Top bar timeframe presetsConfigured 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 optionExact 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 without limit.
  • 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 without limit.

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, or Market 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 presetWindow definition
Full dayCalendar 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-market09:00-13:30, 13:30-20:00, and 20:00-24:00 UTC
London, New York, Asia08:00-16:30, 13:00-22:00, and 00:00-09:00 UTC
CustomStart 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.

On this page