Symbology
Symbol string formats, cross-provider resolution rules, symbol metadata fields, and instrument ID mapping.
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.
| Format | Example | Resolution target |
|---|---|---|
TICKER | AAPL | First registered provider whose symbol list contains TICKER |
PROVIDER:TICKER | acme:AAPL | Provider registered under PROVIDER (case-insensitive) |
PREFIX:TICKER | NASDAQ:AAPL | Provider whose symbol list declares PREFIX as the listing prefix for TICKER |
TICKER.EXT | BTCUSDT.P | Resolved 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
- If the prefix matches a registered provider key (case-insensitively), the symbol routes immediately to that provider, even before
listSymbolshas completed. - Any other prefix is matched strictly against the
prefixfield of descriptors in registered providers' symbol lists. - An unprefixed symbol routes to the first provider in registration order (the key order of the workspace
providersobject) 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
prefixwhen the listing exchange is part of the instrument's standard market identity, such as equities and futures. This value enablesNASDAQ:AAPLresolution and renders as the venue badge across the UI. Omitprefixwhen 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 aprefixstill resolve when addressed by provider key (acme:AAPL). - Futures roots. Define a futures root row by setting
tickerequal togroup, followed by contract rows sharing thatgroupunder their contract tickers. Symbol search folds contracts beneath an expandable root row, and loading the root (ESorCME:ES) resolves automatically to the contract markeddefault: true(or the first listed contract when none or multiple carrydefault: true). - Market. Set
marketwhen 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).
| Field | Consumers |
|---|---|
mintick | Price axis decimal precision, quote formatting in Vela Pro, and syminfo.mintick |
timezone | The 'exchange' display time zone and the IANA zone in which session hours are interpreted (defaults to 'Etc/UTC') |
session, session_extended | Trading session schedule and regular/extended session toggle. See Timeframes and sessions |
timeframes | Supported timeframe bounds (finest, plus optional default and list) |
volume: false | Prevents automatic addition of the default Volume indicator and disables the Footprint chart type |
ohlc: false | Forces line rendering regardless of selected chart style and disables Candles, Bars, Heikin Ashi, Footprint, and TPO |
description, type, currency, basecurrency, pointvalue, and other fields | Exposed 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 passestickerdirectly togetBars,subscribe, andgetSymbolInfowithout modification. - Normalize letter case in your provider. Resolution is case-insensitive, and an explicit provider prefix on a provider without
listSymbolsforwards user casing verbatim (acme:aaplcallsgetBarswith'aapl'). - Avoid colons inside
tickervalues. 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 asprovider:TICKER(acme:EURUSD). Renaming that provider key later leaves previously saved symbols unresolved. - Order
providersintentionally when tickers overlap. When two providers listBTCUSDT, 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 callslistSymbolsonce 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.
Related
- Data providers in the core documentation
- Custom data providers
- Symbol search