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

Symbology

Symbol string formats, cross-provider resolution rules, symbol metadata fields, and instrument ID mapping.

View as Markdown

A symbol string identifies an instrument ticker and, optionally, its listing venue or data provider. Vela's open-source core resolves symbol strings deterministically across registered providers, which determines how you format listSymbols descriptors, how user-typed symbols route, and what identifiers are saved in persisted layouts and Pine Script® code.

FormatExampleResolution target
TICKERAAPLFirst registered provider whose symbol list contains TICKER
PROVIDER:TICKERacme:AAPLProvider registered under PROVIDER (case-insensitive)
PREFIX:TICKERNASDAQ:AAPLProvider whose symbol list declares PREFIX as the listing prefix for TICKER
TICKER.EXTBTCUSDT.PResolved identically to TICKER, passing the .EXT suffix through to the provider unchanged

Everything before the first colon is parsed as the prefix, and everything after the colon is forwarded to your provider as ticker. Provider registration keys may contain dots, so binance.us:BTCUSDT routes to the standalone provider registered as binance.us rather than acting as a modifier on binance.

You can inspect how chart.data resolves symbol strings at runtime. In the example below, the acme provider lists AAPL with prefix: 'NASDAQ':

import type { Vela } from '@luxalgo/vela';

export function inspect(chart: Vela): void {
    chart.data.resolve('AAPL'); // { provider: 'acme', ticker: 'AAPL' }
    chart.data.resolve('nasdaq:aapl'); // { provider: 'acme', ticker: 'AAPL' } (normalized to descriptor casing)
    chart.data.resolve('NYSE:AAPL'); // null (mismatched venue prefixes never fall back)
    chart.data.canonicalSymbol('acme:aapl'); // 'NASDAQ:AAPL'
    chart.data.displayPrefix('AAPL'); // 'NASDAQ'
}

Resolution order

  1. If the prefix matches a registered provider key (case-insensitively), the symbol routes immediately to that provider, even before listSymbols has completed.
  2. Any other prefix is matched strictly against the prefix field of descriptors in registered providers' symbol lists.
  3. An unprefixed symbol routes to the first provider in registration order (the key order of the workspace providers object) whose symbol list includes the ticker.

If no registered provider resolves a symbol yet, the chart does not throw an error. Instead, it waits, logs a console warning, emits data:unresolved, and loads the series automatically as soon as a provider serving that symbol is registered or finishes loading its symbol list.

Symbol search selections and persisted workspace state always record the canonical PREFIX:TICKER string, using the descriptor's prefix when declared or the provider's registration key otherwise. Selecting AAPL in symbol search sets NASDAQ:AAPL on the chart and in saved state documents.

Structuring listSymbols descriptors

import type { SymbolDescriptor } from '@luxalgo/vela';

export const symbols: SymbolDescriptor[] = [
    { ticker: 'AAPL', description: 'Apple Inc.', type: 'stock', prefix: 'NASDAQ' },
    { ticker: 'IBM', description: 'International Business Machines', type: 'stock', prefix: 'NYSE' },
    { ticker: 'EURUSD', description: 'Euro / US Dollar', type: 'forex' },
    // Futures root entry first, followed by individual contracts in display order.
    { ticker: 'ES', group: 'ES', description: 'E-mini S&P 500', type: 'root', prefix: 'CME' },
    { ticker: 'ES1!', group: 'ES', description: 'E-mini S&P 500, front month', type: 'futures', prefix: 'CME', default: true },
    { ticker: 'ES2!', group: 'ES', description: 'E-mini S&P 500, second month', type: 'futures', prefix: 'CME' },
];
  • Listing prefixes. Set prefix when the listing exchange is part of the instrument's standard market identity, such as equities and futures. This value enables NASDAQ:AAPL resolution and renders as the venue badge across the UI. Omit prefix when your provider itself represents the venue (such as single-exchange crypto or forex feeds), in which case the provider key serves as the prefix. Symbols with a prefix still resolve when addressed by provider key (acme:AAPL).
  • Futures roots. Define a futures root row by setting ticker equal to group, followed by contract rows sharing that group under their contract tickers. Symbol search folds contracts beneath an expandable root row, and loading the root (ES or CME:ES) resolves automatically to the contract marked default: true (or the first listed contract when none or multiple carry default: true).
  • Market. Set market when a single provider serves multiple product classes whose trading hours differ, such as equity index futures versus energy futures.

See Symbol search for how descriptor type values map to category tabs.

Symbol metadata

getSymbolInfo(ticker) returns instrument metadata for a single symbol. The chart reads specific typed fields for scale formatting and session controls, while scripting engines receive the full object (in Pine Script®, fields matching syminfo.* names populate those built-in variables).

FieldConsumers
mintickPrice axis decimal precision, quote formatting in Vela Pro, and syminfo.mintick
timezoneThe 'exchange' display time zone and the IANA zone in which session hours are interpreted (defaults to 'Etc/UTC')
session, session_extendedTrading session schedule and regular/extended session toggle. See Timeframes and sessions
timeframesSupported timeframe bounds (finest, plus optional default and list)
volume: falsePrevents automatic addition of the default Volume indicator and disables the Footprint chart type
ohlc: falseForces line rendering regardless of selected chart style and disables Candles, Bars, Heikin Ashi, Footprint, and TPO
description, type, currency, basecurrency, pointvalue, and other fieldsExposed to Pine Script® via syminfo.*

When getSymbolInfo is omitted or returns undefined, the Pine Script® engine populates syminfo.* with default placeholders (USD-quoted crypto defaults with mintick of 0.01), and the price axis infers decimal places from the visible price range. Return accurate metadata whenever scripts or price labels depend on tick sizes, currencies, or sessions.

The core deduplicates concurrent getSymbolInfo calls for the same symbol and caches each response in memory for 10 minutes, so your provider does not need an internal metadata cache.

Instrument ID mapping guidelines

  • Use your API's native instrument identifier as ticker. The core passes ticker directly to getBars, subscribe, and getSymbolInfo without modification.
  • Normalize letter case in your provider. Resolution is case-insensitive, and an explicit provider prefix on a provider without listSymbols forwards user casing verbatim (acme:aapl calls getBars with 'aapl').
  • Avoid colons inside ticker values. The parser always splits on the first colon to extract the prefix. Dots are preserved (BTCUSDT.P), allowing suffix conventions for perpetuals or contract months.
  • Keep provider registration keys stable. When descriptors omit prefix, saved layouts record symbols as provider:TICKER (acme:EURUSD). Renaming that provider key later leaves previously saved symbols unresolved.
  • Order providers intentionally when tickers overlap. When two providers list BTCUSDT, the first registered provider resolves bare 'BTCUSDT'. Selections made through symbol search are unaffected because they include the venue prefix.
  • Retry transient failures inside listSymbols. The workspace calls listSymbols once at registration time. If the call rejects, the provider runs without a symbol list, excluding its symbols from search and listing-prefix resolution.
  • Expect identical resolution in Pine Script®. Script requests such as request.security("NASDAQ:AAPL", ...) use the same resolver, while unprefixed symbols inside a script try the active chart's current provider first.

Symbol keys in Vela Pro

Vela Pro persists chart drawings per symbol. By default, the drawing store strips the prefix and keys drawings by bare ticker, so BTCUSDT, acme:BTCUSDT, and another venue's BTCUSDT share drawings. If identical tickers represent distinct instruments across venues in your application, configure the symbolKey option to include the venue prefix. See Drawing persistence for configuration details.

On this page