Skip to main content

Datafeed subscriptions

Overview​

A subscription is a continuous stream of real-time data for a specific dataset. The library creates subscriptions to keep the chart and other UI elements up to date with the latest market data.

A dataset is defined by the combination of the following properties:

  • Symbol
  • Resolution
  • Currency
  • Chart type

If any of these properties differ, the library treats it as a separate dataset and creates a new subscription with its own unique listener ID (subscriberUID). For example, AAPL at 1D resolution in USD and AAPL at 1D resolution in EUR are different datasets that require separate subscriptions.

However, if a dataset already has an active subscription, the library reuses it. For example, if a user opens a second chart with the same symbol, resolution, currency, and chart type, the library does not call subscribeBars again.

Multiple subscriptions​

The library can maintain several active subscriptions at the same time. This happens because each unique dataset gets its own subscription, and when a user switches symbols or resolutions, the library keeps the previous subscription alive for a short period.

Your datafeed must handle each subscriberUID independently. When you receive an update from your server, route it to every active callback whose symbol, resolution, currency, and chart type match.

Subscription lifecycle​

Subscribing for updates​

The library starts a subscription by calling the subscribeBars method with the following parameters:

  • symbolInfo — the instrument information.
  • resolution — the time interval for this subscription.
  • subscriberUID — a unique string that identifies this subscription. Use it to route incoming data to the correct callback.
  • onTick — the function your datafeed must call to deliver updates to the chart.

Getting updates​

Every time the price or volume changes, call SubscribeBarsCallback with a complete bar object that represents the current state of the bar. The library does not accept ticks or price deltas; it expects the OHLCV values of the most recent bar.

warning

If you send data that does not match the subscriber's dataset, the putToCacheNewBar: time violation issue can occur.

Unsubscribing from updates​

To stop a subscription, the library calls the unsubscribeBars method with listenerGuid to terminate. The listenerGuid parameter matches subscriberUID that was originally passed to subscribeBars.

The library does not call unsubscribeBars immediately when a user switches symbols or closes a chart. Instead, it keeps the subscription active for a short period (typically 5 seconds). This allows instant recovery if the user quickly switches back: the data stream is already running, so the chart updates without a loading flicker.

info

Continue sending updates for a subscriberUID until you receive an explicit unsubscribeBars call for that exact ID, even if you have already received a subscribeBars call for a different dataset.

Example​

The current symbol is AAPL at 1D resolution. The user switches to a five-minute resolution.

  1. The library calls subscribeBars for the new 5-minute dataset.
  2. After a short delay, it calls unsubscribeBars for the old 1D dataset.

During this overlap, both subscriptions are active. Suppose the last bars are:

  • {time: 1684368000000, open: 10, high: 12, low: 9, close: 11} — 1D subscriber
  • {time: 1684422300000, open: 10.5, high: 11.5, low: 10, close: 11} — five-minute subscriber

If the price jumps to 13, send the following updates:

  • {time: 1684368000000, open: 10, high: 13, low: 9, close: 13} — to the 1D subscriber
  • {time: 1684422300000, open: 10.5, high: 13, low: 10, close: 13} — to the 5-minute subscriber