Symbols & resolutions

The symbol is yours

The chart does not know what BTCUSDT means, and deliberately does not try. It passes the string from data-symbol to your datafeed’s resolveSymbol, and whatever comes back is what the chart draws and captions. Your feed is the authority on your own universe.

That is why there is no symbol registry to register with, no prefix convention to learn, and no mapping table to keep in sync. If your backend calls an instrument NASDAQ:AAPL, or aapl.us, or 7, use that.

What resolveSymbol has to answer

Most of the fields are display decisions, and the two that are not are pricescale and session. Everything else has a sensible default.

A note on the last two. If your data is delayed or comes through a redistributor, saying so costs a small glyph in the legend; not saying so means a reader treats a fifteen-minute print as the current price. The chart draws nothing at all when a feed is real-time and venue-direct, so honesty is free in the common case.

Resolution strings

The chart asks for an interval as a string, in the vocabulary the common datafeed contract uses, so if you have implemented one before, this is already familiar.

A bare number is minutes. Anything else carries a letter. Your getBars maps them to whatever your upstream calls the same thing, a dictionary is usually the whole implementation:

var STEP = {
  '1': '1m', '5': '5m', '15': '15m', '30': '30m',
  '60': '1h', '240': '4h', '1D': '1d', '1W': '1w', '1M': '1M'
};

Offer only what you can serve. supported_resolutions is what the picker shows, and an interval in that list that returns an empty page reads to a reader as a broken chart rather than as an unsupported timeframe.

The two unit traps

These are not exotic. They are the reason a feed that looks entirely correct draws an empty chart, and between them they account for most of the time anyone loses here.

1. The window is in SECONDS, a bar’s time is in MILLISECONDS

getBars receives period.from and period.to as UNIX seconds, and every bar you return must carry time in UNIX milliseconds. It is inherited from the contract this mirrors, it is the commonest mistake, and it fails silently: return seconds and every bar lands in 1970, so the chart draws nothing in the window it asked about and reports no error.

return rows.map(function (r) {
  return { time: r.openTimeSeconds, open: r.o, high: r.h, low: r.l, close: r.c };
});

return rows.map(function (r) {
  return { time: r.openTimeSeconds * 1000, open: r.o, high: r.h, low: r.l, close: r.c };
});

2. Serve countBack bars ENDING at `to`, not everything after `from`

The request carries a countBack alongside the window, and it is the number the chart actually needs. Paging from from returns too few bars whenever the window holds less history than the chart asked for, which is every request near the start of an instrument’s life, and the reason a chart can look fine on BTC and empty on a recently listed pair.

url.searchParams.set('endTime', String(period.to * 1000));
url.searchParams.set('limit', String(Math.min(1000, period.countBack)));

Return the bars ascending by time, with no duplicates. The chart validates both and refuses a page that is out of order rather than drawing it, an unordered series produces a chart that is wrong in a way nobody can see.

Where history ends

Return an empty array. That is how the chart learns to stop asking for older windows, and it is a valid answer rather than an error, refusing it would make “no more data” indistinguishable from a broken feed, and the chart would page backwards forever.

The same applies within a series: a period your venue was closed for legitimately returns no bars. Do not fill it. A synthesised bar is a price nobody traded at, and it is indistinguishable on screen from one somebody did.

Real-time bars

subscribeBars hands you a push function. Call it with the CURRENT bar, the same object shape, with the same millisecond time, as often as it changes. Re-pushing a bar with an existing timestamp updates it in place; pushing a new timestamp opens a new bar. There is no separate “tick” shape to learn.

subscribeBars: function (symbol, resolution, uid, push) {
  var ws = new WebSocket(streamUrlFor(symbol, resolution));
  ws.onmessage = function (ev) {
    var k = JSON.parse(ev.data);
    push({ time: k.t, open: +k.o, high: +k.h, low: +k.l, close: +k.c, volume: +k.v });
  };
  sockets[uid] = ws;
},

unsubscribeBars: function (uid) {
  if (sockets[uid]) { sockets[uid].close(); delete sockets[uid]; }
}

Keep the uid. It is the only handle you get, and a subscription that is never closed is a socket per chart per symbol change, the reason unsubscribeBars exists at all.