# Symbology (/vela-pro/data/symbols/symbology)



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'`:

```ts
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 [#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 [#structuring-listsymbols-descriptors]

```ts
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](/vela-pro/data/symbols/symbol-search) for how descriptor `type` values map to category tabs.

## Symbol metadata [#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](/vela-pro/data/symbols/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 [#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 [#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](/vela-pro/persistence/stores/drawings) for configuration details.

## Related [#related]

* [Data providers](/vela/user/data-providers#symbol-formats) in the core documentation
* [Custom data providers](/vela-pro/data/custom-source)
* [Symbol search](/vela-pro/data/symbols/symbol-search)
