JavaScript API

Getting a chart

The loader gives you a controller for any placeholder it has mounted. Pass the element or a selector:

<div class="vp-chart" id="mine" data-symbol="BTCUSDT" data-datafeed="myfeed" data-height="480"></div>

<!-- No `async`: the loader defines `vpEmbed` when it executes, and the
     inline script below calls it. See the note under this block. -->
<script src="https://view.verticalprop.com/embed.js"></script>

<script>
  var chart = vpEmbed.chart('#mine');
  chart.setInterval('60');
</script>

Every method returns a promise, because every call crosses an origin boundary. You can ignore the return value, the call still happens, but a rejection is how the chart tells you an argument was wrong, so it is worth catching while you are building.

Chart state

Order lines

An order line is a horizontal level with a label, a quantity badge and, if you let it, a drag handle and a cancel button. This is the primitive for “here is a working order”.

var line = await chart.createOrderLine({
  price: 64500,
  text: 'Buy limit',
  quantity: '1.5',
  lineColor: '#26a69a',
  editable: true,      // the reader may drag it
  cancellable: true    // …and dismiss it
});

// Later
line.setPrice(64200);
line.set({ text: 'Buy limit (moved)', lineColor: '#f7931a' });
line.remove();

Position lines and brackets

A position line carries entry, and optionally the whole bracket. Passing null to a leg removes it, which is how you cancel a stop without redrawing the position.

var pos = await chart.createPositionLine({
  price: 64000,
  text: 'Long 2 BTC',
  quantity: '2',
  takeProfit: 68000,
  stopLoss: 62500
});

pos.set({ stopLoss: 63000 });   // trail it up
pos.set({ takeProfit: null });  // cancel the target

Buy and sell markers

An execution marker is a fill, an entry, a signal at a point in time and price. Unlike a line it belongs to a bar rather than to a level.

await chart.createExecutionShape({
  time: 1767225600,      // SECONDS
  price: 64100,
  direction: 'buy',      // 'buy' | 'sell'
  text: 'Filled 1.5',
  arrowColor: '#26a69a'
});

A marker also carries a tooltip, which is where the detail that would not fit in text goes. It is a multi-line string, and it opens when a reader points at the arrow or its label.

await chart.createExecutionShape({
  time: 1767225600,
  price: 76365.29,
  direction: 'buy',
  text: 'Buy 0.5',
  tooltip: 'BUY 0.5 BTC\nPrice 76365.29\nFee 0.04%\n2026-08-24 00:00 UTC'
});

markerStyle picks the shape. The default arrow is a triangle at the price with the label beside it, which is right for one marker; badge puts the label INSIDE a roundel sitting against the price, which is what a HISTORY wants; a column of fills reads as B / S bubbles rather than as triangles each trailing a caption. The roundel's near edge is at the price, so the candle it marks stays visible beside it.

await chart.createExecutionShape({
  time: 1767225600,
  price: 76365.29,
  direction: 'buy',
  markerStyle: 'badge',
  text: 'B',                       // drawn INSIDE the roundel
  tooltip: 'BUY 0.5 BTC\nPrice 76365.29\n2026-08-24 00:00 UTC',
  arrowColor: '#26a69a',
  textColor: '#ffffff'             // read against arrowColor, not the chart
});

Drawings

Place a shape at a point, or across several. Both resolve to an entity id you can remove later.

var level = await chart.createShape(
  { time: 1767225600, price: 65000 },
  { shape: 'horizontal_line', text: 'Resistance', color: '#ef5350' }
);

var trend = await chart.createMultipointShape(
  [{ time: 1766620800, price: 61000 }, { time: 1767830400, price: 66000 }],
  { shape: 'trend_line' }
);

chart.removeEntity(level);
chart.removeAllShapes();

The lists are separate and a shape from the wrong one is refused rather than placed at a guessed second point. Options are text, color, backgroundColor, textColor and lock; the full style schema stays with the reader, in the chart’s own settings dialog.

Indicators

var ma = await chart.createStudy('Simple Moving Average', [20]);
var rsi = await chart.createStudy('RSI', [14]);

chart.removeEntity(ma);
chart.removeAllStudies();

Names resolve case-insensitively, and an id works too, 'Simple Moving Average', 'simple moving average' and 'sma' are the same study. A name that resolves to nothing rejects with the name in the message rather than resolving to a null id you would then pass to removeEntity.

These are the engine’s built-in studies. Community indicators are a different thing with a different trust story, see the indicators page.

A control of your own, in the chart’s toolbar

This is the one place your page's own UI can live INSIDE the frame. You name a label and are told when it was pressed; the frame draws it in the chart's own button style, beside the interval picker.

const watch = await chart.createToolbarButton({
  text: 'Watch',
  tooltip: 'Add BTC-USDT to your watchlist',
});

chart.on('toolbarButtonClick', async (e) => {
  if (e.handle !== watch.id) return;
  const on = await addToWatchlist(await chart.getSymbol());
  watch.set({ text: on ? 'Watching' : 'Watch', active: on });
});

// …and when your component unmounts
watch.remove();

You supply a STRING, never markup. That is the boundary doing its job rather than a limitation of the control: the whole reason the embed is an iframe is that your code does not execute on our origin, and an option that took HTML would hand back exactly what the frame exists to withhold. What you get instead is a button that already matches the chart it is in, on both themes, at every size, without a stylesheet.

The press arrives as toolbarButtonClick carrying the handle's id, which is why the example compares it: a chart with three buttons reports all three presses through one event. Pointer and keyboard both fire it: the control is a real tab stop and answers Enter and Space, so it is not a button only a mouse can reach.

Run the whole thing

Every object above, on one chart, with the events printing underneath it. The series is generated inside the pen, so it needs no key and cannot be taken down by a venue; drag the blue line and watch orderMove arrive.

<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', async () => {
  // Declare that this page can carry an order, or the price-scale menu
  // offers alerts and drawings only.
  await chart.setTrading({ quantity: 1 });

  const entry = await chart.createOrderLine({
    price: 101, text: 'Buy limit', quantity: '1', lineColor: '#26a69a',
  });

  await chart.createPositionLine({
    price: 99.5, text: 'Long', quantity: '2',
    takeProfit: 104, stopLoss: 97,
  });

  await chart.createExecutionShape({
    // SECONDS here, and it must be a bar's own opening time.
    time: Math.floor(Date.now() / 3600000) * 3600 - 3600 * 6,
    price: 99.5, direction: 'buy', text: 'Filled 2 @ 99.50',
    tooltip: 'Entry\n2 @ 99.50',
  });

  // One message, one repaint. There is no chaining.
  await entry.set({ price: 100.8, text: 'Buy limit (moved)' });
  log('objects placed. Drag the blue line.');
});

chart.on('orderMove', ({ handle, price }) => log('moved ' + handle + ' to ' + price));
chart.on('orderCancel', ({ handle }) => log('cancelled ' + handle));
chart.on('orderSubmit', (o) => log('submit ' + JSON.stringify(o)));
chart.on('positionClose', ({ handle }) => log('close ' + handle));
</script>

Events

on(name, fn) returns an unsubscriber. Listen so your page stays in step with a chart the reader is also driving, the toolbar changes the same state your calls do.

var off = chart.on('intervalChanged', function (e) {
  console.log('now on', e.interval);
});

// The ones that make a line a control rather than a picture:
chart.on('orderMove',   function (e) { placeOrder(e.handle, e.price); });
chart.on('orderCancel', function (e) { cancelOrder(e.handle); });
chart.on('positionClose', function (e) { closePosition(e.handle); });

off();  // stop listening

Every property

The tables below are the complete set, checked against the validator on every build in both directions, so nothing here is missing, and nothing here has stopped existing. An unknown property is refused, so a stale row would break your chart rather than be ignored.

These thirteen are carried by both an order line and a position line.

createOrderLine adds three. The first two are what turn a drawn level into something the reader can act on.

createPositionLine adds five, two controls and the three legs of a bracket.

createExecutionShape has its own set: a marker belongs to a bar rather than to a level, so it takes a time and points a direction.

Every command

What the loader calls, and the wire name behind it. You need the second column only if you are driving the frame with postMessage yourself, the two that have no method of their own, updateLine and removeLine, are what a handle’s set() and remove() send.

When a call is refused

The promise rejects with a real Error naming the problem. Refusals are shape-level and specific, because the reader of the message is whoever wrote the call:

try {
  await line.set({ lineColour: '#fff' });   // British spelling
} catch (e) {
  console.error(e.message);   // unknown property "lineColour"
}

Unknown properties are refused rather than dropped, on purpose. A silently ignored property is a chart that never gets the colour you set, with no error anywhere, which is the failure this API has produced twice while every test around it passed.

The wire, if you are not using the loader

The loader is a convenience over postMessage. Everything above is one message type:

frame.contentWindow.postMessage({
  ns: 'vp-embed', v: 1, type: 'command',
  id: 'c1',                       // yours, echoed back
  method: 'createOrderLine',
  args: [{ price: 100, text: 'Buy' }]
}, '*');

// Back: { ns, v, type: 'commandResult', id: 'c1', value: 'order-1' }
//   or: { ns, v, type: 'commandError',  id: 'c1', reason: '…' }
//   or: { ns, v, type: 'event', name: 'orderMove', payload: { handle, price } }

Two older types remain for symbol and theme (setSymbol, setTheme), one door each, and those are the doors that were documented first.

Listening safely on your side

If you handle messages yourself rather than through the loader, check both the origin and the source. Origin alone is not enough when a page embeds more than one frame, without the source check, one frame can drive another.

window.addEventListener('message', function (ev) {
  if (ev.origin !== 'https://view.verticalprop.com') return;
  if (ev.source !== frame.contentWindow) return;   // the one people forget
  // …
});

Versioning

Every message carries v. A loader cached on your site for a year will still be talking to a server we have redeployed many times, and the version is how a newer embed recognises an older loader instead of misreading it. Messages whose version we do not understand are ignored, never guessed at.