Data types

These are the shared payload shapes used by iframe URLs, cacheCandle, and postMessage events.

Core candle types

Candle

Used by cacheCandle, replay payloads, and selected chart windows.

interface Candle {
  o: number; // open
  h: number; // high
  l: number; // low
  c: number; // close
  timestamp: number; // unix seconds
}

Field	Type	Notes
o	number	Open price
h	number	High price
l	number	Low price
c	number	Close price
timestamp	number	Bar time in unix seconds

cacheCandle request

type CacheCandleRequest = {
  candles: Candle[];
};

Example:

{
  "candles": [
    { "o": 1.08, "h": 1.09, "l": 1.07, "c": 1.085, "timestamp": 1719878400 }
  ]
}

Auth types

auth.signIn

Sign-in success envelope from the iframe:

type AuthSignInMessage = {
  name: "auth.signIn";
  data: {
    idToken: string;
  };
};

Store data.idToken as iccandle_token if your host needs to call cacheCandle or related APIs.

Loading type

type SelectorLoadingMessage = {
  name: "selector.loading";
  data: {
    isLoading: boolean;
  };
};

true means scan or AI preparation is in progress.

Replay types

ChartReplayData

Used by chart.play and chart.stop.

interface ChartReplayData {
  isReplay: boolean;
  predictCandles?: Candle[] | null;
  playEndTimestamp: number | null; // unix seconds
  selectedCandles: Candle[] | null;
}

Field	Type	Notes
isReplay	boolean	Whether replay mode is active
predictCandles	Candle[] | null	Generated or predicted candles to overlay
playEndTimestamp	number | null	Unix-second timestamp where replay should stop
selectedCandles	Candle[] | null	Source candles used for replay or analysis

chart.play

type ChartPlayMessage = {
  name: "chart.play";
  data: ChartReplayData;
};

chart.stop

type ChartStopMessage =
  | {
      name: "chart.stop";
      data: ChartReplayData;
    }
  | {
      name: "chart.stop";
      data: null;
    };

Navigation type

type NavClickMessage = {
  name: "nav.click";
  data: {
    href: string;
  };
};

href is the embed route or path the user selected.

News and event types

NewsEvent

Used by event-click messages and selected-news payloads.

interface NewsEvent {
  id: string;
  timestamp: number; // unix ms
  event_name: string;
  metric: string;
  forecast: string;
  actual: string;
  previous: string;
  currency: string;
}

Field	Type	Notes
id	string	Event identifier
timestamp	number	Event time in unix milliseconds
event_name	string	Human-readable event name
metric	string	Reported metric
forecast	string	Forecast value
actual	string	Actual value
previous	string	Previous value
currency	string	Associated currency

news.eventClicked

type NewsEventClickedMessage = {
  name: "news.eventClicked";
  data: {
    event: NewsEvent;
    similarDetails: object | null;
  };
};

similarDetails is implementation-specific metadata for similar-events flows. Treat it as opaque unless you inspect a live payload and need to use it.

news.selectedEventPayloads

type NewsSelectedEventPayloadsMessage = {
  name: "news.selectedEventPayloads";
  data: NewsEvent[];
};

Back and lifecycle messages

type NewsBackMessage = {
  name: "news.back";
  data: null;
};

type NewsBackToSimilarEventsMessage = {
  name: "news.backToSimilarEvents";
  data: null;
};

type NewsIframeReadyMessage = {
  name: "news.iframeReady";
  data: null;
};

type NewsAnalyzeImpactMessage = {
  name: "news.analyzeImpact";
  data: null;
};

Pattern-selection types

Pattern payloads are not yet fully normalized beyond the outer message envelope. The host usually only needs the compared time range, so treat pattern as an opaque object until you map its live fields.

Classic/common pattern

type ClassicPatternSelectedMessage = {
  name: "pattern.classicPatternSelected";
  data: {
    pattern: object;
  };
};

type ClearClassicPatternSelectedMessage = {
  name: "pattern.clearClassicPatternSelected";
  data: null;
};

Tracked pattern

type CustomPatternSelectedMessage = {
  name: "pattern.custom_pattern_selected";
  data: {
    pattern: object;
  };
};

type ClearCustomPatternSelectedMessage = {
  name: "pattern.clear_custom_pattern_selected";
  data: null;
};

Parent-to-embed types

type ParentOriginMessage = {
  type: "parent-origin";
  origin: string;
};

type PaymentSuccessMessage = {
  type: "payment-success";
};

Envelope type

If you want one broad parser shape before narrowing into specific messages:

type EmbedMessageEnvelope = {
  name?: string;
  data?: unknown;
  pattern?: unknown;
};

Next

See Window messages for the full routing catalog and integration guidance.