AdvancedChartServices

The AdvancedChartServices object defines a set of methods used by the chart at runtime to fetch and manage the required data. It implements the following interface:

interface AdvancedChartServices {
  dataService: AdvancedChartDataService
}

AdvancedChartDataService

The AdvancedChartDataService interface defines the methods required for retrieving and managing chart-related data.

interface AdvancedChartDataService {
  getHistoryCandles(
    symbol: string,
    aggregation: AdvancedChartAggregationPeriod,
    period: { from: number; to?: never } | { from?: never; to: number },
    options: AdvancedChartCandlesRequestOptions,
    overrideCandles: (data: AdvancedChartCandleData[]) => void
  ): Promise<AdvancedChartCandleData[]>
  subscribeLastCandleUpdates(
    symbol: string,
    aggregation: AdvancedChartAggregationPeriod,
    options: AdvancedChartCandlesRequestOptions,
    callback: (data: AdvancedChartCandleData[]) => void
  ): AdvancedChartSubscription
  subscribeSummary(
    symbol: string,
    callback: (data: AdvancedChartSummaryData) => void
  ): AdvancedChartSubscription
  subscribeQuote(
    symbol: string,
    callback: (data: AdvancedChartQuoteData) => void
  ): AdvancedChartSubscription
  getTradingSessions(
    symbol: string,
    period: { from: number; to: number }
  ): Promise<AdvancedChartTradingSession[]>
  searchInstrument(search: string): Promise<AdvancedChartSearchInstrument[]>
  getInstrumentData(symbol: string): Promise<AdvancedChartInstrumentData>
}

note

Although all methods are mandatory to implement, some method calls can be ignored, depending on the widget configuration and the functionality used. Refer to the documentation of a specific method to understand what data it receives and why.

getHistoryCandles

This is the main method that used to provide data to the chart. The library calls this method to get initial set of history data, and when user goes into a chart history to lazy load past data.

The method is called with symbol, aggregation, period, options and overrideCandles and expects a candle data in return.

function createDataService() {
  return {
    getHistoryCandles(symbol, aggregation, period, options, overrideCandles) {
      const { extendedHours, priceType, candleAlignment } = options
      // ...
      return Promise.resolve([
        {
          time: 1732604400000,
          open: 100,
          high: 105,
          low: 90,
          close: 104,
          volume: 1000,
        },
        // other candles
      ])
    },
    // ...
  }
}

Initial history call

The library will call getHistoryCandles with the period.from value to retrieve the initial history data for the chart during its initial render or whenever the instrument, aggregation period, session display settings, or other related configurations are updated. The period.from value will depend on the viewport.

If the viewport value is not set, then period.from will be 0. In this case, you can pass any number of candles from the current time. The viewport will be automatically calculated based on the passed number of candles and set in the layout object.
If the viewport value is set, then period.from will be based on the left edge of the viewport on initial rendering, or the date of the oldest candle otherwise. In this case, you need to provide data at least from period.from but you can provide more history data.

In both cases, you need to pass candles to the current time, since lazy data loading only works when moving the viewport to the past.

Lazy loading call

If the viewport moves deeper in a history, and the library has no data to draw, then this function is called to load additional data. In this case, the library passes the period.to value equal to the time of the oldest available data on the chart.

The library expects any number of candles before the period.to (not inclusive). If you include candles that are equal to or greater than period.to, they will overwrite the saved candles, but with a large number of such candles, this will be less performant than providing only the necessary ones.

If fewer candles are passed than are needed to fill the empty space on the left of the viewport, then this method will be called with an updated period.to until the left part of the viewport is filled or until an empty array is passed, meaning that there is no more data.

note

Even though an empty array means there is no data, the library will always call this method when the viewport values changes and there is an empty space visible on the left side of the viewport.

Data format

Library expected you to provide data according to next interface:

interface AdvancedChartCandleData {
  time: number
  open: number
  high: number
  low: number
  close: number
  volume: number
}

Time requirements

The time property contains the Unix timestamp value. For proper rendering timestamp information, the time should be property formatted:

Sub-day Aggregations: Provide candle data with the time timestamps in UTC, representing the exact time of the period.
Daily and Longer Aggregations: Provide candle data with time timestamps in UTC, where the time must be set to 00:00:00.

Data order

This is not necessary to provide data in specific order for time-based aggregation, where each point in time corresponds to one candle, but is important for other types, such as tick-based or volume-based aggregation. Since in this case the data may have the same timestamp and the order of the candles will be important. If the data has the same timestamp, the library will draw the data based on its order in the array from left to right.

History override

The overrideCandles function provides the ability to rewrite all candles of the chart at any time. For example, if you need to adjust the history based on an external event. To do this, you just need to save a reference to this function.

function createDataService() {
  let updateHistoryCallback = undefined

  return {
    async getHistoryCandles(symbol, aggregation, period, options, overrideCandles) {
      updateHistoryCallback = overrideCandles
      // ...
    },
    // ...
  }
}

warning

overrideCandles rewrites the whole instrument's history data. So make sure to provide all history data, not just updates.

subscribeLastCandleUpdates

The library calls this method to subscribe to real-time updates of the latest candle, which should be provided to the callback. If you do not need the real-time updates, you can ignore calls of this method.

function createDataService() {
  return {
    subscribeLastCandleUpdates(symbol, aggregation, options, callback) {
      const { extendedHours, priceType, candleAlignment } = options

      return {
        unsubscribe: () => {
          // unsubscribe from you service subscription
        },
      }
    },
    // ...
  }
}

Update last candle

To update the last candle you need to pass an updated last candle that have the same timestamp properties to callback.

Add new candle

When new aggregation period begins you need to add a new candle to the chart. To do this you need to provide a new candle with new timestamp properties to callback.

Data format

The callback expects to receive data in the same format as used in the getHistoryCandles method.

subscribeSummary

The library calls this method to subscribe to the summary information of selected instrument and show this data as extra information on the price axis. This extra information is controlled by availablePriceLabels in widget configuration. If you do not want to show summary data in price axis, you can ignore calls of this method.

function createChartDataProvider() {
  return {
    subscribeSummary(symbol, callback) {
      callback({
        prevDayClosePrice: 105,
        prePostMarketClose: undefined,
      })

      return {
        unsubscribe: () => {
          // unsubscribe from you service subscription
        },
      }
    },
    // ...
  }
}

Data format

interface AdvancedChartSummaryData {
  prevDayClosePrice?: number // close price of regular session
  prePostMarketClose?: number // close price of pre-marker or after-market session
}

subscribeQuote

The library calls this method to subscribe to the Quote event of selected instrument and show this data as extra information on the price axis. This extra information is controlled by availablePriceLabels in widget configuration. If you do not want to show Quote event data in price axis, you can ignore calls of this method.

function createChartDataProvider() {
  return {
    subscribeQuote(symbol, callback) {
      callback({
        bid: 105.4,
        ask: 105.6,
      })

      return {
        unsubscribe: () => {
          // unsubscribe from you service subscription
        },
      }
    },
    // ...
  }
}

Data format

interface AdvancedChartQuoteData {
  bid?: number
  ask?: number
}

getTradingSessions

The library call this method to obtain information about trading sessions for specified symbol. This information required for the correct work of the session breaks and extended session functionality. You need to provide an array of the sessions according to period.from and period.to parameters.

warning

The library may request a trading session schedule up to 30 days in advance for proper operation.

function createChartDataProvider() {
  return {
    getTradingSessions(symbol, period) {
      return Promise.resolve([
        // sessions
      ])
    },
    // ...
  }
}

Session data format

The library expect to receive an array of objects, each defining a trading session according the following interface:

interface AdvancedChartTradingSession {
  readonly from: number // Unix timestamp in milliseconds
  readonly to: number // Unix timestamp in milliseconds
  readonly type: 'NO_TRADING' | 'PRE_MARKET' | 'REGULAR' | 'AFTER_MARKET'
}

Example:

const sessions = [
  { from: 1720569600000, to: 1720598400000, type: 'NO_TRADING' }, // 00:00 - 08:00
  { from: 1720598400000, to: 1720612800000, type: 'PRE_MARKET' }, // 08:00 - 12:00
  { from: 1720612800000, to: 1720641600000, type: 'REGULAR' }, // 12:00 - 20:00
  { from: 1720641600000, to: 1720652400000, type: 'AFTER_MARKET' }, // 20:00 - 23:00
  { from: 1720652400000, to: 1720684800000, type: 'NO_TRADING' }, // 23:00 - 08:00 (+1)
]

note

Time values are continuous, non-overlapping, and in GMT.

searchInstrument

Library calls this method to receive list of instruments for showing in them in SymbolSearch component.

function createChartDataProvider() {
  return {
    searchInstrument(search) {
      return Promise.resolve([
        // list of instruments
        {
          symbol: 'AAPL',
          type: 'STOCK',
          description: 'Apple Inc',
        },
      ])
    },
    // ...
  }
}

info

Return an empty array is you don't have matches

Data format

interface AdvancedChartSearchInstrument {
  symbol: string
  type: 'FOREX' | 'STOCK' | string
  description?: string
}

The type property can be any string, but 'FOREX' and 'STOCK' have pre-configured parameters based on the instrument's characteristics.

getInstrumentData

Library calls this method to receive detailed information about currently selected instrument.

function createChartDataProvider() {
  return {
    async getInstrumentData(symbol) {
      const instrument = await someInstrumentService.findBySymbol(symbol)
      if (instrument === undefined) {
        return Promise.reject('No such instrument')
      }
      return Promise.resolve(instrument)
    },
    // ...
  }
}

info

If you can't find selected instrument then reject promise

Data format

interface AdvancedChartInstrumentData {
  symbol: string
  type: 'FOREX' | 'STOCK' | string
  description?: string
  priceIncrements: number[]
  timezone: string
}

Price increments

The priceIncrements provides a special format for handling price precision of the instrument. It is an array of numbers that represent the price steps for an instrument on Y-Axis. Best way to understand the logic is to see examples:

const priceIncrements = [0.001, 1, 0.01, 1000, 1]

This price increments means that:

if price > -Infinity && price >= 1 then price increments is 0.001 and price will be shown with 3 decimal numbers
if price > 1 && price >= 1000 then price increments is 0.01 and price will be shown with 2 decimal numbers
if price > 1000 && price > +Infinity then price increments is 1 and price will be shown with 0 decimal numbers

Thus, the array consists of an odd number of elements, in which the first element defines the price step, and the next one defines the limit up to which this step is applied, the last price step has no limit. So, if one value is provided [0.01] then this price step will be applied to any price value.

Type

The type property can be any string, but 'FOREX' and 'STOCK' have pre-configured parameters based on the instrument's characteristics.

Type Reference

AdvancedChartAggregationPeriod

interface AdvancedChartAggregationPeriod {
  duration: number
  durationType: 't' | 'r' | 's' | 'm' | 'h' | 'd' | 'w' | 'mo' | 'y' | 'v'
}

Period type	durationType
Tick	t
Second	s
Minute	m
Hour	h
Day	d
Week	w
Month	mo
Year	y
Range	r
Volume	v

AdvancedChartCandlesRequestOptions

interface AdvancedChartCandlesRequestOptions {
  extendedHours: boolean
  priceType: 'last' | 'mark' | 'bid' | 'ask'
  candleAlignment: 'session_start' | 'midnight'
}

AdvancedChartSubscription

interface AdvancedChartSubscription {
  unsubscribe: () => void
}

AdvancedChartServices

AdvancedChartDataService​

getHistoryCandles​

Initial history call​

Lazy loading call​

Data format​

Time requirements​

Data order​

History override​

subscribeLastCandleUpdates​

Update last candle​

Add new candle​

Data format​

subscribeSummary​

Data format​

subscribeQuote​

Data format​

getTradingSessions​

Session data format​

searchInstrument​

Data format​

getInstrumentData​

Data format​

Price increments​

Type​

Type Reference​

AdvancedChartAggregationPeriod​

AdvancedChartCandlesRequestOptions​

AdvancedChartSubscription​

AdvancedChartDataService

getHistoryCandles

Initial history call

Lazy loading call

Data format

Time requirements

Data order

History override

subscribeLastCandleUpdates

Update last candle

Add new candle

Data format

subscribeSummary

Data format

subscribeQuote

Data format

getTradingSessions

Session data format

searchInstrument

Data format

getInstrumentData

Data format

Price increments

Type

Type Reference

AdvancedChartAggregationPeriod

AdvancedChartCandlesRequestOptions

AdvancedChartSubscription