Datafeed API

Bring your own data

This is the model, not an advanced option. We distribute a charting engine, not market data: you connect a feed you already have the right to show your readers, and the chart renders it. Nothing about your symbols or your bars reaches us.

That is a deliberate trade, and it is worth being plain about both halves:

• Your data, your licence. Whatever you are permitted to display, you can display here. We are not in the middle re-publishing somebody’s feed to your readers.
• Your quota, your scale. Requests go to your backend and grow with your traffic. There is no shared allowance to exhaust and no rate limit of ours between your readers and your chart.
• You write about twenty lines. Two required methods. The quickstart below is a complete working feed you can paste as-is.

Quickstart: a live Binance chart

Copy this into a page and open it. It draws BTCUSDT from Binance’s public market-data host, no key, no backend of your own, and no account with us.

<div class="vp-chart"
     data-symbol="BTCUSDT"
     data-datafeed="binance"
     data-height="480"></div>
<script src="https://view.verticalprop.com/embed.js"></script>

<script>
  // Chart resolutions → Binance intervals.
  var STEP = {
    '1': '1m', '5': '5m', '15': '15m', '30': '30m',
    '60': '1h', '240': '4h', '1D': '1d', '1W': '1w', '1M': '1M'
  };
  var sockets = {};

  vpEmbed.datafeed('binance', {
    onReady: function () {
      return { supported_resolutions: Object.keys(STEP) };
    },

    resolveSymbol: function (name) {
      return {
        name: name,
        description: name,
        session: '24x7',            // crypto never closes
        timezone: 'Etc/UTC',
        pricescale: 100,            // BTCUSDT quotes to 2 decimal places
        minmov: 1,
        has_intraday: true,
        supported_resolutions: Object.keys(STEP),
        data_status: 'streaming',
        provider: 'Binance'         // shown as attribution on the chart
      };
    },

    getBars: function (symbol, resolution, period) {
      var url = new URL('https://data-api.binance.vision/api/v3/klines');
      url.searchParams.set('symbol', symbol);
      url.searchParams.set('interval', STEP[resolution] || '1d');
      // endTime, NOT startTime: the chart needs `countBack` bars ENDING at
      // `to`, and asking from `from` returns too few whenever the window
      // holds less history than the chart asked for.
      url.searchParams.set('endTime', String(period.to * 1000));
      url.searchParams.set('limit', String(Math.min(1000, period.countBack)));

      return fetch(url).then(function (r) { return r.json(); }).then(function (rows) {
        // Binance already stamps kline open times in MILLISECONDS, which is
        // what a bar wants — even though period.from/to arrived in seconds.
        return rows.map(function (k) {
          return {
            time: k[0],
            open: Number(k[1]), high: Number(k[2]),
            low: Number(k[3]), close: Number(k[4]), volume: Number(k[5])
          };
        });
      });
      // Past the listing date Binance returns [], which is exactly how the
      // chart learns to stop asking for older history.
    },

    subscribeBars: function (symbol, resolution, uid, push) {
      var stream = symbol.toLowerCase() + '@kline_' + (STEP[resolution] || '1d');
      var ws = new WebSocket('wss://data-stream.binance.vision/ws/' + stream);
      ws.onmessage = function (ev) {
        var k = JSON.parse(ev.data).k;
        push({
          time: k.t,
          open: Number(k.o), high: Number(k.h),
          low: Number(k.l), close: Number(k.c), volume: Number(k.v)
        });
      };
      sockets[uid] = ws;
    },

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

And this is the chart it draws, running here, on this page, right now. It is the same /embed document your snippet would frame, so what you are looking at is the product rather than a picture of it.

To take the contract apart rather than copy it, this playground is the same six methods over a series generated inside the pen. It reaches no venue, so it draws on the first run and any change you make is the only thing that can alter what appears.

<script src="https://view.verticalprop.com/embed.js"></script>
<div class="vp-chart"
     data-symbol="DEMO"
     data-interval="60"
     data-toolbar="1"
     data-theme="dark"
     data-datafeed="myFeed"
     style="height: 420px"></div>
<pre id="log"></pre>

<style>
body { margin: 0; background: #0b0f19; color: #e6e8eb;
       font: 13px/1.5 ui-monospace, monospace; }
#log { padding: 8px 12px; margin: 0; white-space: pre-wrap; }
</style>

<script>
// A deterministic series, so the pen never depends on a venue and the
// same code always draws the same chart.
function bars(from, to, stepSec) {
  const out = [];
  let price = 100;
  for (let t = Math.ceil(from / stepSec) * stepSec; t <= to; t += stepSec) {
    price += Math.sin(t / 5000) * 0.6;
    const open = price;
    const close = price + Math.cos(t / 3000) * 0.8;
    out.push({
      time: t * 1000,                       // a bar's time is MILLISECONDS
      open, close,
      high: Math.max(open, close) + 0.5,
      low: Math.min(open, close) - 0.5,
      volume: 1000 + (t % 500),
    });
  }
  return out;
}

vpEmbed.datafeed('myFeed', {
  onReady: () => ({ supported_resolutions: ['60'] }),
  resolveSymbol: (name) => ({
    name, ticker: name, pricescale: 100, session: '24x7', timezone: 'Etc/UTC',
  }),
  // from and to are SECONDS; a bar's own time is MILLISECONDS.
  getBars: (symbol, resolution, from, to) => bars(from, to, 3600),
  subscribeBars: () => {},
  unsubscribeBars: () => {},
});

const log = (m) => { document.getElementById('log').textContent += m + '\n'; };
const chart = vpEmbed.chart(document.querySelector('.vp-chart'));
chart.on('dataLoaded', () => log('bars drawn, every one from getBars'));
chart.on('intervalChanged', ({ interval }) => log('getBars called again for ' + interval));
</script>

Everything below is the reference for what those methods receive and must return.

The two pieces

One attribute and one registration. data-datafeed names an object on your page; naming one IS the request to supply data, so there is no second mode flag to forget.

Registration order does not matter. A feed registered after the chart mounted attaches to it; a chart mounted after the feed was registered picks it up. Both are ordinary on a page that loads scripts asynchronously.

Required methods

Two. Everything else is optional and has a defined behaviour when absent, a feed that implements only these two draws a working chart.

resolveSymbol

Called once per symbol, before any bars are requested. Describe the instrument: how to format its prices, when it trades, and what to call it.

resolveSymbol(symbolName)  →  SymbolInfo | Promise<SymbolInfo>

pricescale is the field to get right and the easiest to overlook: it decides where the decimal point goes on every price the reader sees, on the axis, in the legend and in the crosshair. A crypto pair quoted to eight places with the default 100 renders every price as the same rounded number.

Throw, or reject, to refuse a symbol. The chart shows the reader that the symbol could not be resolved rather than an empty plot.

resolveSymbol(name) {
  const meta = MY_SYMBOLS[name];
  if (!meta) throw new Error('unknown symbol');
  return {
    name,
    description: meta.longName,
    session: '0930-1600',
    timezone: 'America/New_York',
    pricescale: 100,
    minmov: 1,
    has_intraday: true,
    supported_resolutions: ['1', '5', '60', '1D'],
    data_status: 'delayed_streaming',
    delay: 900,
  };
}

pricescale is the field whose effect is easiest to see and easiest to get wrong. Two charts, one instrument, one number different:

getBars

Called whenever the chart needs history it does not have, on first load, and again each time the reader scrolls or zooms past the left edge of what it holds.

getBars(symbol, resolution, period)  →  Bar[] | Promise<Bar[]>

A bar is { time, open, high, low, close } with an optional volume. time is epoch MILLISECONDS while from and to are seconds. That asymmetry is inherited from the charting convention this API follows, it is the single most common mistake when connecting a feed, and it fails in a way that looks like no data at all: bars stamped in seconds land in 1970 and the chart draws nothing in the window it asked about.

[
  { time: 1755561600000, open: 100.0, high: 101.2, low: 99.4, close: 100.8, volume: 12500 },
  { time: 1755648000000, open: 100.8, high: 102.6, low: 100.1, close: 102.2, volume: 18300 }
]

Rules for the array you return

• Ascending order, no duplicate timestamps. Checked, and refused with a message rather than rendered, a descending page draws a chart whose axis runs backwards inside one request and forwards across requests, which is very hard to recognise as an ordering problem.
• Prefer countBack over the window. Return at least countBack bars ending at to, reaching further back than from if that is what it takes. The chart computes from from your session, so on a thinly traded symbol, or one with an unusual calendar, the window can hold fewer bars than it needs, and it will keep asking.
• Return everything you have in the range. Truncating to exactly countBack when more exists leaves gaps the chart will ask about again.
• Return an empty array when history runs out. That is how the chart learns to stop asking. A feed that always returns something turns one scroll to the left into an unbounded loop of requests.
• Never return one bar. Two is the minimum a renderer can scale a range from.

Optional methods

Everything from here down can be left out. Each has a defined behaviour when absent, and none of them is called unless you implement it, so a feed that stops at getBars is a complete feed.

subscribeBars / unsubscribeBars

Real-time updates. The chart hands you a subscriber id and a function; call the function with a bar whenever you have one. A bar whose time matches the most recent one REPLACES it, that is how a forming candle updates, and a later time appends a new one.

subscribeBars(symbol, resolution, subscriberUID, push)
unsubscribeBars(subscriberUID)

const sockets = {};

subscribeBars(symbol, resolution, uid, push) {
  const ws = new WebSocket(`wss://my-feed.example/${symbol}`);
  ws.onmessage = (ev) => {
    const t = JSON.parse(ev.data);
    push({ time: t.time, open: t.o, high: t.h, low: t.l, close: t.c, volume: t.v });
  };
  sockets[uid] = ws;
},

unsubscribeBars(uid) {
  sockets[uid]?.close();
  delete sockets[uid];
}

Omit both for an end-of-day feed. The chart draws its history and stops, which is correct; it does not poll and does not show a stale “live” indicator.

A live subscription is what turns the last candle into a moving one. Watch the right-hand edge of this chart, every update is a push() from a feed:

searchSymbols

Powers the symbol search in the toolbar. Omit it if your embed charts one instrument, or if the reader should not be choosing.

searchSymbols(userInput, exchange, symbolType)  →  SearchItem[]

// SearchItem: { symbol, description?, exchange?, type?, ticker? }
// "ticker" is what resolveSymbol will be called with; defaults to "symbol".

Rows that are not usable are dropped individually rather than failing the search, nine good results are worth more than an error about the tenth.

onReady

Called once, first. Return configuration for the chart’s own UI, which resolutions to offer, which exchanges and symbol types to show in search. Every field is optional and the whole method is optional.

onReady() {
  return {
    supported_resolutions: ['1', '5', '15', '60', '1D', '1W'],
    exchanges: [{ value: '', name: 'All', desc: '' }],
    symbols_types: [{ name: 'All', value: '' }],
  };
}

Call sequence

What happens when a reader opens a chart, in order:

Errors and timeouts

Throw or reject to report a failure. The message reaches the chart and is shown to the reader, so write it for them rather than for your logs.

A call that is never answered times out after 20 seconds and is reported as your feed not responding. That bound exists because the alternative, a chart waiting forever, is indistinguishable from a slow network, and the reader can do nothing about either.

Malformed data is refused with a specific reason rather than rendered: a bar that is not five finite numbers, a pricescale of zero, an unordered page. The reason names the field and, for bars, the index, these are checked because one bad value scales the whole visible range and takes the entire chart with it.

What we see

Nothing. In this mode the chart makes no market-data request, so no symbol you chart and no bar you draw reaches our servers. The frame still loads its own code and styles from us that is what an embed is, and the community-indicator features, if you enable them, still talk to us because that is what they are for.

getServerTime

Your server’s clock, in seconds. The chart draws its live edge against “now”; without this it uses the reader’s own clock, so a skewed one puts that edge in the wrong place.

getServerTime() {
  return Math.floor(Date.now() / 1000);   // or your server's, which is the point
}

getMarks

The round badge under a bar — a B or an S where a fill happened, with a tooltip on hover. Asked for only when your onReady config sets supports_marks: true.

onReady() {
  return { supported_resolutions: ['1D'], supports_marks: true };
},

getMarks(symbolInfo, from, to, resolution) {
  return fills.filter((f) => f.time >= from && f.time <= to).map((f) => ({
    id: f.id,
    time: f.time,               // SECONDS, and the BAR's own opening time
    label: f.side === 'buy' ? 'B' : 'S',
    color: f.side === 'buy' ? '#26a69a' : '#ef5350',
    labelFontColor: '#ffffff',
    text: [`${f.side} ${f.qty} @ ${f.price}`],
  }));
}

To push a set rather than answer a callback, which is the usual shape when the chart uses our market data and only the fills are yours, use chart.setMarks(marks) from your page. When both are present the pushed set wins.

getTimescaleMarks

Roundels in the time gutter, for events anchored to a moment rather than a level. Asked for only when your config sets supports_timescale_marks: true.

getTimescaleMarks(symbolInfo, from, to, resolution) {
  return earnings.map((e) => ({
    id: e.id,
    time: e.time,               // SECONDS
    label: 'E',
    color: '#7c5cff',
    tooltip: [e.title, e.detail],
  }));
}

searchSymbolsPaginated

A page of search results, for a catalogue too big to answer in one go.

searchSymbolsPaginated(query, exchange, type, page) {
  const size = 50;
  const all = myUniverse.filter((s) => s.symbol.includes(query.toUpperCase()));
  return {
    items: all.slice((page - 1) * size, page * size),
    hasMore: all.length > page * size,
  };
}