Skip to content

Symbol Resolution

Jump to bottom
levi edited this page Nov 6, 2025 · 2 revisions

Symbol Resolution

Table of Contents

  1. Introduction
  2. Core Data Structure: TVLibrarySymbolInfo
  3. Implementation of resolveSymbol Method
  4. Field-by-Field Analysis of TVLibrarySymbolInfo
  5. Relationship Between Symbol Metadata and Chart Functionality
  6. Common Issues and Troubleshooting
  7. Best Practices for Error Handling and Validation

Introduction

The resolveSymbol method is a critical component of the TradingView datafeed integration, responsible for providing complete symbol metadata to the charting library. This document provides comprehensive guidance on implementing the resolveSymbol method to deliver fully populated TVLibrarySymbolInfo objects. The method serves as the bridge between raw market data and the visual charting interface, ensuring that all necessary symbol metadata is accurately conveyed for proper chart rendering and functionality. The implementation must handle symbol resolution requests, construct appropriate symbol information objects, and manage error conditions gracefully to ensure a robust user experience.

Core Data Structure: TVLibrarySymbolInfo

The TVLibrarySymbolInfo class represents the complete metadata structure for trading symbols within the TradingView ecosystem. This data structure contains all essential information required for chart rendering, market context, and trading functionality. The class is designed to accommodate both required and optional fields, allowing for flexible representation of various instrument types across different markets. The structure includes metadata for display purposes, trading session configuration, price formatting, resolution support, and additional classification data. Proper population of this structure is essential for accurate chart behavior and user experience.

classDiagram
class TVLibrarySymbolInfo {
+name : str
+description : str
+type : str
+session : str
+exchange : str
+listed_exchange : str
+timezone : Timezone
+format : SeriesFormat
+pricescale : int
+minmov : int
+ticker : str
+has_intraday : bool
+supported_resolutions : List[str]
+volume_precision : int
}
Loading

Implementation of resolveSymbol Method

The resolveSymbol method implementation in the BADatafeed class demonstrates the proper pattern for resolving symbol information. The method takes a symbol name and callback functions for success and error handling, constructing a TVLibrarySymbolInfo object with complete metadata before invoking the resolution callback. The implementation includes error handling to catch exceptions during symbol resolution and properly report them through the error callback. The example shows a simplified approach where symbol information is constructed with default values, but in production systems, this would typically involve querying a database or external API to retrieve accurate symbol metadata.

sequenceDiagram
participant Client as "Charting Library"
participant Datafeed as "BADatafeed"
participant SymbolInfo as "TVLibrarySymbolInfo"
Client->>Datafeed : resolveSymbol("BTCUSDT", onResolve, onError)
Datafeed->>Datafeed : Construct symbol metadata
Datafeed->>SymbolInfo : Create TVLibrarySymbolInfo object
Datafeed->>Datafeed : Populate required fields
Datafeed->>Datafeed : Populate optional fields
Datafeed->>Client : onResolve(symbol_info)
Note over Datafeed,Client : Symbol successfully resolved
Loading

Field-by-Field Analysis of TVLibrarySymbolInfo

Required Fields

The TVLibrarySymbolInfo structure requires several essential fields that define the fundamental characteristics of a trading symbol:

  • name: The symbol name as recognized within the exchange (e.g., "BTCUSDT", "AAPL")
  • description: A human-readable description displayed in the chart legend
  • type: The instrument type (e.g., "crypto", "stock", "forex", "futures")
  • session: Trading hours specification in exchange timezone (e.g., "24x7", "0930-1600")
  • exchange: The traded exchange or proxy exchange
  • listed_exchange: The actual exchange where the symbol is listed
  • timezone: Exchange timezone in OlsonDB format (e.g., "Etc/UTC", "America/New_York")
  • format: Price scale label format ("price" for standard pricing, "volume" for volume-based)
  • pricescale: Defines the price precision as a power of 10 (e.g., 100 = 2 decimal places)
  • minmov: Minimum price movement units (tick size in price scale units)

Optional Fields

In addition to required fields, the structure supports numerous optional fields that enhance functionality:

  • ticker: Unique symbol identifier, often used for API references
  • has_intraday: Boolean indicating support for intraday resolutions
  • supported_resolutions: List of supported timeframes (e.g., ["1", "5", "15", "1D"])
  • volume_precision: Number of decimal places for volume display
  • session_display: Custom display format for trading sessions
  • corrections: Session correction rules for holidays or special trading days
  • fractional: Flag indicating fractional pricing (non-decimal)
  • has_daily: Boolean indicating support for daily bars
  • has_weekly_and_monthly: Boolean indicating support for weekly/monthly bars
  • visible_plots_set: Default visible plots configuration ("ohlcv", "candles", etc.)

Relationship Between Symbol Metadata and Chart Functionality

The metadata provided in the TVLibrarySymbolInfo object directly influences various aspects of chart behavior and display. The pricescale and minmov fields determine price precision and tick size, affecting how prices are displayed and rounded on the chart. The timezone field ensures that time axes are correctly aligned with the exchange's local time, preventing misalignment of candles. The session field defines market hours, which affects the display of trading sessions and the rendering of empty bars outside trading hours. Supported resolutions determine which timeframes are available to users in the chart interface. This metadata ensures that charts accurately represent market conditions and trading context.

flowchart TD
A[Symbol Resolution] --> B[TVLibrarySymbolInfo]
B --> C{Chart Functionality}
C --> D[Price Display Precision]
C --> E[Time Axis Alignment]
C --> F[Market Hours Display]
C --> G[Available Timeframes]
C --> H[Trading Session Indicators]
D --> I[pricescale & minmov]
E --> J[timezone]
F --> K[session]
G --> L[supported_resolutions]
H --> M[session_display]
style I fill:#f9f,stroke:#333
style J fill:#f9f,stroke:#333
style K fill:#f9f,stroke:#333
style L fill:#f9f,stroke:#333
style M fill:#f9f,stroke:#333
Loading

Common Issues and Troubleshooting

Several common issues can arise during symbol resolution that affect chart functionality:

  • Incomplete symbol information: Missing required fields can cause chart initialization failures or incorrect rendering
  • Incorrect timezone settings: Mismatched timezones lead to misaligned candles and incorrect time axis display
  • Improper session definitions: Incorrect session specifications result in inaccurate market hours display and trading session indicators
  • Unsupported resolutions: Providing resolutions not actually supported by the data source causes data retrieval failures
  • Invalid pricescale values: Incorrect pricescale values lead to improper price precision and display issues
  • Missing error handling: Uncaught exceptions during symbol resolution can cause the entire datafeed to fail

These issues typically manifest as chart loading errors, incorrect price displays, or missing data. Proper validation and comprehensive error handling are essential to prevent these problems.

Best Practices for Error Handling and Validation

Effective implementation of the resolveSymbol method requires robust error handling and validation practices:

  • Validate all required fields: Ensure that all required fields in TVLibrarySymbolInfo are properly populated before resolution
  • Implement comprehensive exception handling: Wrap symbol resolution logic in try-catch blocks to prevent unhandled exceptions
  • Provide meaningful error messages: Include specific details in error messages to aid debugging and troubleshooting
  • Validate resolution support: Ensure that supported_resolutions only includes timeframes actually supported by the data source
  • Verify timezone accuracy: Confirm that timezone values match the exchange's actual timezone
  • Test edge cases: Validate behavior with invalid symbol names, network failures, and database connectivity issues
  • Log resolution attempts: Maintain logs of symbol resolution requests and outcomes for monitoring and debugging

The BADatafeed implementation demonstrates these best practices by wrapping the symbol resolution logic in a try-except block and logging errors with descriptive messages before invoking the error callback.

Clone this wiki locally