# 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](#overview) 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 [`subscribeBars`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.IDatafeedChartApi#subscribebars [`SubscribeBarsCallback`]: https://charting-library-docs.xstaging.tv/latest/api/modules/Datafeed#subscribebarscallback [time violation]: https://charting-library-docs.xstaging.tv/latest/connecting_data/Datafeed-Issues.md#time-violation [`unsubscribeBars`]: https://charting-library-docs.xstaging.tv/latest/api/interfaces/Charting_Library.IDatafeedChartApi#unsubscribebars --- ## Sitemap - [All documentation pages](https://charting-library-docs.xstaging.tv/llms.txt) - [Full page map with headings](https://charting-library-docs.xstaging.tv/docs_map.md)