3. API reference

Everything a host page can use to configure, drive and listen to an embedded chart. Three layers, each built on the one before:

1. The chart page: URL options and page configuration of apps/web/index.html.
2. The postMessage protocol: the messages the chart's embed bridge accepts and sends. Use it directly from a native web view or a page without npm.
3. @kandlo/react: <KandloChart/>, createKandloChart() and the TypeScript types.

The sources this page describes: apps/web/src/interactions/embed-bridge.js, apps/web/src/interactions/embed-protocol.js, packages/kandlo-react/src/*.js and packages/kandlo-react/*.d.ts. Unit tests: npm test.

Times are unix seconds everywhere. Timeframes are names ('M5') on the API and seconds (300) on the wire to the feed.

Commands at a glance#

The same operation in each layer. A dash means the layer has no shortcut for it; use the handle (the component's ref) or request().

1. The chart page#

1.1 Chart page URL options#

The embed bridge starts only when both hold:

• the page is inside a frame (window.self !== window.top), and
• the URL has embed=1 (or embed=true).

A top-level visit, or a frame without embed=1, is the normal standalone chart: no listener, no style change, no URL option below is read.

symbol, chartType and timeframe are checked like the matching commands once the feed's symbol list has arrived. An invalid value is skipped with a console warning ([embed] ignored ?symbol=: ...); the others still apply.

In an embed, the chart type, timeframe and theme the host sets are not saved in the chart origin's localStorage, and the values saved by the standalone chart on the same origin are not restored over the host's choice.

The standalone page also understands replay=1: it plays the recorded session in apps/web/assets/fixtures/ instead of connecting to a feed (one recorded series, relabelled to whatever symbol is asked for). Pass it through params: { replay: 1 } from the React package.

1.2 Page configuration#

Set in apps/web/index.html, in the inline script that defines var AppData = {...}, which runs before app.js.

Example, added right after the var AppData = {...}; line:

<script>
  AppData['embed-allowed-origins'] = ['https://app.example.com'];
  AppData['relay-servers-list'] = [{ server: 'wss://feed.example.com', name: 'Primary' }];
</script>

Feature switches on window.__kiFeature (read each time they are needed, so they can be set in that same inline script):

In an embed the bridge sets both keys when it starts, over any value from the inline script; the URL option synth=1 is the way to keep the backfill there.

1.3 Which parent origin the bridge accepts#

The bridge decides once, at start, the single origin it exchanges messages with:

1. A parentOrigin that is not a bare http(s) origin (a path, query, credentials, *, null, another scheme) disables the bridge.
2. With embed-allowed-origins set:
   • parentOrigin must be on the list;
   • without parentOrigin, a list of exactly one origin is used;
   • a longer list without parentOrigin uses the origin the browser reports for the parent (location.ancestorOrigins, where available) if it is on the list; otherwise the bridge is disabled.
3. Without the list, parentOrigin is used as given (development only). No list and no parentOrigin disables the bridge.
4. Where the browser reports the real parent origin, it must equal the chosen origin, or the bridge is disabled.

A disabled bridge logs [embed] bridge disabled: <reason> in the chart page's console and answers nothing. The client libraries then fail with timeout.

After that, an incoming message is processed only if it comes from window.parent and from the chosen origin. Everything the bridge sends goes to window.parent with that origin as targetOrigin, never '*'.

2. The postMessage protocol#

2.1 Envelope#

All messages are plain objects (structured clone), protocol version 1.

// host -> chart: a command
{ kandlo: 1, id: 'k1', type: 'setSymbol', payload: { symbol: 'EURUSD' } }

// chart -> host: the reply
{ kandlo: 1, re: 'k1', ok: true,  result: { chartId: 'chart-1', symbol: 'EURUSD' } }
{ kandlo: 1, re: 'k1', ok: false, error: { code: 'unknown_symbol', message: 'unknown symbol: EURUSDX' } }

// chart -> host: an event (no `re`)
{ kandlo: 1, event: 'symbolChange', payload: { chartId: 'chart-1', symbol: 'EURUSD' } }

• id: a non-empty string of at most 64 characters, or a safe integer. It is echoed as re. Use a fresh one per command.
• payload: a plain object. null or a missing payload is read as {}.
• Every command gets exactly one reply.

How the bridge treats malformed input:

Results and event payloads are copied through JSON, so they contain only JSON values.

2.2 Panes#

A layout shows one to four chart panes, chart-1 to chart-4. Commands that accept chartId default to the active pane, the first visible one; with the default single-pane layout that is always chart-1. A chartId that is not on screen is refused with unknown_chart.

2.3 Commands#

Notes per command:

• setSymbol: the symbol must be in listSymbols(); otherwise unknown_symbol and nothing reaches the feed. The chart then requests history for it; listen for symbolChange, or poll getState().candleCount, to know when it is drawn.

• setTimeframe: a name from listTimeframes() or its seconds. Unsupported seconds are unknown_timeframe.

• setChartType: setting a line-family type (Line, Area and the other line variants) switches the pane to S1. Set the chart type first and the timeframe second. The React component does this ordering for you.

• setTheme: applied to the whole page, chart and surrounding UI. Not saved in an embed.

• setLayout: new panes open on the current symbol. Panes a smaller layout hides are no longer addressable.

• listIndicatorTypes: pane is 'overlay' (drawn on the price pane) or 'separate' (its own pane below). defaults is the full default settings object; rules holds limits for some numeric settings, for example { period: { min: 1, max: 100 } } (some also carry precision). A rule applies to every setting with that key, at any depth.

• addIndicator: settings override the type's defaults and are deep-merged onto them. Only keys present in the defaults are accepted (plus a boolean show on a line), each with the default's type: numbers must be finite and inside the rules limits, strings at most 64 characters. Arrays and other non-scalar values cannot be set. At most 3 levels of nesting and 64 keys per object. At most 30 indicators per pane (limit_reached). The returned id looks like ext-mvdmt4ud-1. Example:

  JavaScriptCopy code

  { type: 'rsi', settings: { period: 21, lines: { main: { color: '#ffaa00' } } } }

• updateIndicator: the same checks against the indicator's type; the values are deep-merged into its current settings.

• listDrawingTools: tool is the name to pass to startDrawing ('TREND_LINE', 'FIBONACCI_RETRACEMENT', ...), type the engine's numeric id, label the display name. group and groupLabel are the groups of the chart's own drawings panel, in its order: lines, channels, fib, gann, pitchfork, patterns, shapes, notes, measure.

• startDrawing: tool must be a name from listDrawingTools() (unknown_drawing_tool otherwise). placement is 'click' (default) or 'auto'.

  • 'click' arms the pane: the pointer turns into a crosshair and the next click on that pane creates the drawing with the tool's default style and moves it so its first point is under the click. A two-point tool (trend line, ray, rectangle, Fibonacci retracement, ...) then follows the pointer with its second point until a second click fixes it. Other tools are complete after the first click, at their default size (shrunk toward the click when that size would leave the visible area). The clicks that place are kept from the chart (they neither pan nor select). Escape in the chart, cancelDrawing, or another startDrawing ends the placement; a two-point drawing that has only its first point is removed. The reply comes at once; follow the placement through drawingChange.
  • 'auto' adds the drawing at once at a default position in the visible area, as the chart's drawings panel does, and returns its id.

  The chart allows at most 15 drawings per symbol, counted over every pane showing that symbol (limit_reached). Once placed, a drawing is moved and edited in the chart like one added from its own panel. Its id is a request id until the feed server confirms the drawing.

• cancelDrawing: cancelled is false when no click placement was waiting; tool is the tool that was being placed, or null.

• listDrawings: tool and label as in listDrawingTools(); type is the numeric tool id.

• getCandles: count is an integer from 1 to 5000, default 500. Values are market prices even for derived chart types (Heikin Ashi, Renko and so on). A pane with no data returns [] or not_ready.

• Indicators and drawings live in the page: they do not survive a reload of the chart page. Re-apply them after ready.

ChartState#

{
  protocol: 1,
  version: '1.0.0',                 // the chart page's bridge version
  chart: { chartId, symbol, timeframe, seconds, chartType } | null,
  theme: string,
  layout: string | null,            // 'FULL', 'VERTICAL_2', ...
  chartIds: string[],               // panes on screen, in layout order
  activeChartId: string,
  indicators: IndicatorInstance[],  // of this pane
  drawingCount: number,             // of this pane
  candleCount: number,              // candles the pane holds
}

2.4 Events#

Events are sent only after ready.

A pane that appears through a layout change does not send change events for its initial values; layoutChange covers it.

2.5 Error codes#

2.6 Timing#

• Commands that need the chart (all but ping, subscribe, listThemes and setTheme) are held until the chart has its store and the feed's symbol list, then run in arrival order. Up to 50 are held; more are refused with busy. So a host can send its setup straight after the frame loads. If the chart never starts (no feed), held commands get no reply; the client libraries then reject them with timeout.
• ready comes later, when data is drawn.
• A message posted into the frame before the chart page has loaded is lost by the browser. Either wait for ready (the bridge sends it unprompted), or send ping until it answers, as createKandloChart() does.

3. @kandlo/react#

Installed from the tarball packages/kandlo-react/dist/kandlo-react-1.0.0.tgz (see Quickstart). React 17 or later is an optional peer dependency; the plain API needs no React. No other runtime dependencies.

3.1 Entry points and exports#

3.2 createKandloChart(element, options)#

Appends an iframe that fills element and returns a promise of a ChartHandle, resolved on the chart's first ready.

The iframe also gets referrerpolicy="strict-origin-when-cross-origin" and style="border:0; display:block; width:100%; height:100%". Give element a size.

The promise rejects with a KandloError:

3.3 ChartHandle#

Properties:

Methods. Every command method returns a promise of the result in 2.3, or rejects with a KandloError carrying the chart's error code (2.5), timeout (no reply within requestTimeout), destroyed, or no_bridge (the frame has no window to post to).

undefined fields are left out of the payload, so setSymbol('X', undefined) sends { symbol: 'X' }.

The crosshair and candle streams are switched on in the chart only while at least one listener for them is attached; the handle sends subscribe for you. After a reload of the chart page inside the frame, the handle restores them on the next ready.

A listener that throws is logged with console.error and does not stop the other listeners.

3.4 <KandloChart/>#

<KandloChart
  ref={chartRef}                       // ChartHandle once ready, null before and after unmount
  src="https://charts.example.com/"
  symbol="EURUSD" timeframe="M5" chartType="Candles" theme="dark-blue"
  layout="FULL"
  indicators={[{ type: 'rsi', settings: { period: 21 } }]}
  chrome="minimal"
  style={{ height: 480 }}
  onReady={(state, chart) => {}}
  onCrosshair={(e) => {}}
  onError={(err) => {}}
/>

Behaviour:

• Commands from prop changes are sent in the order the props changed, one after the other.
• chartType is applied before timeframe; after a line-family type pins the pane to S1, the component sends your timeframe again.
• Props are not forced back. When the user picks another symbol in the chart's toolbar, onSymbolChange reports it and the chart keeps it until your symbol prop changes.
• Callbacks can be new functions on every render; nothing is recreated.
• StrictMode-safe: the development double mount leaves one live iframe.
• Server rendering: react.js starts with 'use client'. On the server the component renders only its empty container <div data-kandlo-chart>; the iframe is created in an effect, in the browser. No module of the package reads window or document when it is imported.

3.5 Client error codes#

KandloError.code is one of the chart's codes (2.5) or the client's own:

3.6 TypeScript#

index.d.ts (main entry) and vanilla.d.ts declare every type used above: ChartHandle, CreateChartOptions, FrameOptions, InitialState, KandloChartProps, IndicatorSpec, ChartState, ReadyState, ChartView, Candle, SymbolInfo, TimeframeInfo, LayoutInfo, IndicatorTypeInfo, IndicatorInstance, DrawingInfo, DrawingToolInfo, DrawingPlacement, StartDrawingOptions, StartDrawingResult, IndicatorSettings, CrosshairEvent, CandleEvent, DrawingChangeEvent, ChartEvents, ChartEventName, ChartListener, PaneOption, RequestOptions, Timeframe, TimeframeName, KandloErrorCode. on() is typed per event:

chart.on('crosshair', (e) => e.candle?.close);   // e: CrosshairEvent