API reference

Base URL: https://embed-iccandle-app.iccandle.ai

Always verify event.origin === "https://embed-iccandle-app.iccandle.ai" on inbound messages. Parent → embed messages should use that origin as targetOrigin.

See Window messages for the full message catalog and Data types for shared payload definitions.

Locales

Code	Language
en	English (default)
zh	Chinese
vi	Vietnamese
th	Thai
ko	Korean
ja	Japanese
mn	Mongolian
ru	Russian

URL shape: https://embed-iccandle-app.iccandle.ai/{locale}/…?…

Routes

Path	Purpose
/{locale}	Selector(scan) results (auth required). Runs /search when scan params are present.
/{locale}/pattern	Pattern tabs (?tab=tracked-pattern | common-pattern)
/{locale}/pattern/[type]	Pattern type detail. Only flagbull and flagbear are activatable; other types redirect to ?tab=common-pattern
/{locale}/news	Event calendar
/{locale}/news/[date]	News for a date
/{locale}/news/similar-events/[id]	Similar events detail
/{locale}/sign-in	Sign in (and OAuth return)
/{locale}/sign-up	Sign up
/{locale}/forgot-password, /reset-password, /confirm	Auth recovery
/{locale}/payment/success	Stripe success when not embedded

Unauthenticated access to (app) routes redirects to sign-in.

Scan query parameters (/{locale})

See Search params for the full scanner query-parameter reference, examples, defaults, and timestamp rules.

Other useful query params

Param	Where	Role
header	app pages	false hides the embed header and divider
bg_dark / bg_light	app pages	Hex page background for the dark / light theme. See Search params.
model	/{locale}	AI results model: light (default) | pro
temperature	/{locale}	AI results temperature: 0.5 | 1 (default) | 1.5
tab	/pattern	tracked-pattern | common-pattern
id	pattern tracker	Detail pattern id
pricing=true	app pages	Opens pricing modal
referral	sign-in / sign-up	Referral code
lang	/news	Stored as host widget language hint

Common pattern types

Type slug	Pattern	Activatable
flagbull	Bullish Flag	Yes
flagbear	Bearish Flag	Yes
dd_bot	Double Bottom	No (disabled in UI; deep link redirects)
dd_top	Double Top	No (disabled in UI; deep link redirects)
has_bull	Bullish Head & Shoulders	No (disabled in UI; deep link redirects)
has_bear	Bearish Head & Shoulders	No (disabled in UI; deep link redirects)

cacheCandle

POST https://scan-service.iccandle.ai/cacheCandle
Authorization: Bearer <iccandle_token>
Content-Type: application/json

{
  "candles": [{ "o": 0, "h": 0, "l": 0, "c": 0, "timestamp": 0 }]
}

Use the response id as cid. The embed will not call /search without a non-empty cid (plus symbol, res, and ref_res).

Auth and storage

Key / concept	Where	Purpose
NextAuth session cookies	Embed (iframe)	Gate app routes; SameSite=None; Secure for third-party iframes
auth.signIn → data.idToken	Parent localStorage as iccandle_token	Bearer for cacheCandle and host APIs
iccandle_parent_origin	Embed localStorage	Stripe return_url base (from parent-origin or document.referrer)

OAuth providers send X-Frame-Options: DENY, so Google / Cognito sign-in opens a popup, then posts tokens back into the iframe.

Stripe return (embedded)

1. Parent sends { type: "parent-origin", origin }.
2. Checkout success URL on the parent: /?payment=success&session_id=…&lookup_key=….
3. Parent posts { type: "payment-success" } into the iframe so credits / subscription refresh.

postMessage — parent → embed

Type	Payload	Purpose
parent-origin	{ type, origin }	Store parent origin for Stripe return
payment-success	{ type: "payment-success" }	Refresh subscription / credits after checkout
cognito-oauth-tokens	{ type, payload: { id_token, access_token, refresh_token? } }	Internal OAuth popup → iframe (same origin)

postMessage — embed → parent (name)

Messages may be plain objects or JSON.stringify’d. Parse accordingly.

Type	Payload	Purpose
loading	{ type, payload: boolean }	Scan / AI prep loading
auth.signIn	{ name: "auth.signIn", data: { idToken } }	Persist host token
chart.play	{ name: "chart.play", data: { isReplay: true, predictCandles?: Candle[] | null, playEndTimestamp: number | null, selectedCandles: Candle[] | null } }	Replay / generated candles during playback
chart.stop	{ name: "chart.stop", data: { isReplay: false, predictCandles?: Candle[] | null, playEndTimestamp: null, selectedCandles: null } } or { name: "chart.stop", data: null }	Clear replay candles and playback overlays
close-result	{ type: "close-result" }	Close results / clear play state
pattern_selected	{ type, pattern }	Draw common-pattern range
clear_pattern_selected	{ type, id: null }	Clear that range
custom_pattern_selected	{ type, pattern } or { type, id }	Draw tracked pattern (full object includes compared_pattern)
clear_custom_pattern_selected	{ type, id: null }	Clear tracked pattern range

postMessage — embed → parent (action)

Action	Payload	Purpose
nav-click	{ action, data: { href } }	Header navigation in the embed
eventClicked	{ action, data: { event, similarDetails } }	Calendar event selected
replay	{ action, data: { isReplay, predictCandles, playEndTimestamp, selectedCandles } }	News event replay
back	{ action, data: null }	Leave news detail / similar events
back-to-similar-events	{ action, data: null }	Back within news flow

Also emitted (optional for hosts): analyze, iframe-ready, symbolChanged, intervalChanged.

Selected news events (raw array)

Scanner news selection may post a JSON array (no type wrapper) of:

{
  timestamp: number;
  event_name: string;
  metric: string;
  id: string;
  forecast: string;
  actual: string;
  previous: string;
  currency: string;
}

Hosts that draw timescale marks can store this array (the React widget uses tv:selected-news-events).

Embedding constraints

• The embed app does not set X-Frame-Options / frame-ancestors that block partner iframes.
• Allow popups for OAuth and top-level navigation for Stripe.
• Restrict your own CSP frame-src (or equivalent) to include https://embed-iccandle-app.iccandle.ai.
• Pass header=false when the host supplies its own navigation and you want a chrome-less results panel.