Skip to main content

Time and sessions

Overview​

Correctly configuring time is crucial for ensuring that the library displays chart data accurately. A common source of confusion is the interaction between different time-related settings. This guide provides a step-by-step approach to setting up bar times correctly.

Core principles​

The library's time handling is based on a clear division of responsibilities between the datafeed and the library. To ensure correct time representation, it is crucial to understand the following fundamental principles.

Configure accurate symbol information​

The datafeed is responsible for providing the library with the necessary context for each symbol. To do this, your resolveSymbol implementation should return the LibrarySymbolInfo object with the necessary fields. The most critical fields are:

  • timezone — the time zone of the exchange where the symbol is traded.
  • session — the trading hours for the symbol, specified in the exchange's time zone.
  • supported_resolutions — a list of supported resolutions for a symbol.

Provide bars with UTC timestamps​

Your getBars implementation provides historical data. Your responsibility is to return bar data where the time property is a UTC timestamp in milliseconds. The value of this timestamp depends on the resolution:

  • For DWM bars (Daily, Weekly, Monthly), the timestamp must represent the beginning of the trading day at 00:00:00 UTC, not the start of the session. For example, if a trading day is March 5, the DWM bar's time must be set to March 5, 00:00:00 UTC. This rule applies universally, regardless of whether the exchange is located in Australia, New York, or California.

    warning

    Do not attempt to manually convert bar timestamps to UTC based on the session and time zone. This causes bars to appear on the wrong day in the library. Provide the timestamp as it is, in UTC, and the library will manage the conversions.

  • For intraday bars (seconds, minutes, hours), the timestamp must represent the beginning of the bar's time. It should be aligned with the exchange's trading session. For example, for the 09:30-16:00 session in America/New_York on April 10, 2024, the first 5-minute bar starts at 09:30 EDT, which is 13:30 UTC.

Let the library handle time conversions​

The library takes the universal UTC timestamps you provide and applies the symbol-specific rules you defined to correctly place the bars on the chart's time scale. The library handles all the complex logic, including:

  • Aligning bars according to the trading session.
  • Accounting for daylight saving time changes.
  • Converting the final, aligned time to whatever time zone the user has selected in the UI.

How to start​

  1. Implement the required Datafeed API methods.
  2. Make sure you correctly specify Symbology for each symbol. Provide it to the library in the resolveSymbol method as a LibrarySymbolInfo object.
  3. Implement getBars, considering the difference between DWM and intraday bars. When a user selects a resolution on the chart, the library calls getBars, passing the selected resolution as the resolution parameter. Your implementation must handle this resolution and return the appropriate bar data with correct timestamps.
  4. (Optional) Configure extended sessions if your symbol trades outside of regular trading hours.

Troubleshooting​

If you find that your bars are shifted or you are encountering any time-related errors, refer to the Datafeed: common issues article.