API 参考

基础 URL：https://embed-iccandle-app.iccandle.ai

入站消息务必校验 event.origin === "https://embed-iccandle-app.iccandle.ai"。父页面向嵌入端发送消息时，将该 origin 用作 targetOrigin。

完整消息目录见窗口消息，共享载荷定义见数据类型。

语言

代码	语言
`en`	English（默认）
`zh`	中文
`vi`	越南语
`th`	泰语
`ko`	韩语
`ja`	日语
`mn`	蒙古语
`ru`	俄语

URL 形态：https://embed-iccandle-app.iccandle.ai/{locale}/…?…

路由

路径	用途
`/{locale}`	扫描结果（需登录）。存在扫描参数时调用 `/search`。
`/{locale}/pattern`	形态标签（`?tab=tracked-pattern` \| `common-pattern`）
`/{locale}/pattern/[type]`	形态类型详情。当前仅 `flagbull` 与 `flagbear` 可激活；其他类型会重定向到 `?tab=common-pattern`
`/{locale}/news`	事件日历
`/{locale}/news/[date]`	某日新闻
`/{locale}/news/similar-events/[id]`	相似事件详情
`/{locale}/sign-in`	登录（及 OAuth 返回）
`/{locale}/sign-up`	注册
`/{locale}/forgot-password`、`/reset-password`、`/confirm`	认证恢复
`/{locale}/payment/success`	非嵌入场景下的 Stripe 成功页

未认证访问 (app) 路由会重定向到登录。

扫描查询参数（`/{locale}`）

完整的扫描查询参数参考、示例、默认值与时间戳规则见搜索参数。

其他常用查询参数

参数	位置	作用
`header`	应用页	`false` 隐藏嵌入顶栏及其分隔线
`bg_dark` / `bg_light`	应用页	深色 / 浅色主题的十六进制页面背景。见搜索参数。
`model`	`/{locale}`	AI 结果模型：`light`（默认） \| `pro`
`temperature`	`/{locale}`	AI 结果温度：`0.5` \| `1`（默认） \| `1.5`
`tab`	`/pattern`	`tracked-pattern` \| `common-pattern`
`id`	形态追踪	详情形态 id
`pricing=true`	应用页	打开定价弹窗
`referral`	登录 / 注册	推荐码
`lang`	`/news`	存为宿主 widget 语言提示

通用形态类型

类型 slug	形态	可激活
`flagbull`	看涨旗形	是
`flagbear`	看跌旗形	是
`dd_bot`	双底	否（UI 禁用；深链会重定向）
`dd_top`	双顶	否（UI 禁用；深链会重定向）
`has_bull`	看涨头肩	否（UI 禁用；深链会重定向）
`has_bear`	看跌头肩	否（UI 禁用；深链会重定向）

`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 }]
}

将响应中的 id 用作 cid。无非空 cid（以及 symbol、res、ref_res）时，嵌入端不会调用 /search。

认证与存储

键 / 概念	位置	用途
NextAuth 会话 cookie	嵌入端（iframe）	门控应用路由；第三方 iframe 使用 `SameSite=None; Secure`
`auth.signIn` → `data.idToken`	父页面 `localStorage` 的 `iccandle_token`	`cacheCandle` 与宿主 API 的 Bearer
`iccandle_parent_origin`	嵌入端 `localStorage`	Stripe `return_url` 基址（来自 `parent-origin` 或 `document.referrer`）

OAuth 提供方发送 X-Frame-Options: DENY，因此 Google / Cognito 登录会打开弹窗，再把 token 回传给 iframe。

Stripe 返回（嵌入场景）

父页面发送 { type: "parent-origin", origin }。
结账成功 URL 在父页面：/?payment=success&session_id=…&lookup_key=…。
父页面向 iframe 发送 { type: "payment-success" }，以刷新积分 / 订阅。

postMessage — 父页面 → 嵌入端

类型	载荷	用途
`parent-origin`	`{ type, origin }`	存储父 origin 供 Stripe 返回
`payment-success`	`{ type: "payment-success" }`	结账后刷新订阅 / 积分
`cognito-oauth-tokens`	`{ type, payload: { id_token, access_token, refresh_token? } }`	内部 OAuth 弹窗 → iframe（同源）

postMessage — 嵌入端 → 父页面（`name`）

消息可能是普通对象或 JSON.stringify 字符串，请相应解析。

类型	载荷	用途
`loading`	`{ type, payload: boolean }`	扫描 / AI 准备加载
`auth.signIn`	`{ name: "auth.signIn", data: { idToken } }`	持久化宿主 token
`chart.play`	`{ name: "chart.play", data: { isReplay: true, predictCandles?: Candle[] \| null, playEndTimestamp: number \| null, selectedCandles: Candle[] \| null } }`	回放 / 生成播放中的 K 线
`chart.stop`	`{ name: "chart.stop", data: { isReplay: false, predictCandles?: Candle[] \| null, playEndTimestamp: null, selectedCandles: null } }` 或 `{ name: "chart.stop", data: null }`	清除回放 K 线与播放叠加层
`selector.closeResult`	`{ name: "selector.closeResult", data: null }`	关闭结果 / 清除播放状态
`nav.click`	`{ name: "nav.click", data: { href: string } }`	嵌入端头部导航切换
`news.eventClicked`	`{ name: "news.eventClicked", data: { event: NewsEvent, similarDetails: object \| null } }`	选中一个日历 / 经济事件
`news.selectedEventPayloads`	`{ name: "news.selectedEventPayloads", data: NewsEvent[] }`	选中扫描器新闻事件
`news.back`	`{ name: "news.back", data: null }`	离开新闻详情
`news.backToSimilarEvents`	`{ name: "news.backToSimilarEvents", data: null }`	在相似事件流程内返回
`news.iframeReady`	`{ name: "news.iframeReady", data: null }`	相似事件 iframe 完成初始加载
`news.analyzeImpact`	`{ name: "news.analyzeImpact", data: null }`	请求新闻影响分析
`pattern.classicPatternSelected`	`{ name: "pattern.classicPatternSelected", data: { pattern: object } }`	高亮经典 / 通用形态区间
`pattern.clearClassicPatternSelected`	`{ name: "pattern.clearClassicPatternSelected", data: null }`	清除该高亮
`pattern.custom_pattern_selected`	`{ name: "pattern.custom_pattern_selected", data: { pattern: object } }`	高亮追踪形态区间
`pattern.clear_custom_pattern_selected`	`{ name: "pattern.clear_custom_pattern_selected", data: null }`	清除追踪形态高亮

消息可能是普通对象或 JSON.stringify 字符串，请相应解析。

所选新闻事件（原始数组）

扫描器新闻选择也可能发送一个原始 JSON 数组（没有 type 包装）：

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

需要绘制时间轴标记的宿主可存储该数组（React 组件使用 tv:selected-news-events）。

嵌入约束

嵌入应用未设置会阻止合作方 iframe 的 X-Frame-Options / frame-ancestors。
请允许 OAuth 弹窗以及 Stripe 的顶层导航。
在自有 CSP 的 frame-src（或等价配置）中包含 https://embed-iccandle-app.iccandle.ai。
当宿主自行提供导航、希望结果面板无顶栏时，传入 header=false。

语言​

路由​

扫描查询参数（/{locale}）​

其他常用查询参数​

通用形态类型​

cacheCandle​

认证与存储​

Stripe 返回（嵌入场景）​

postMessage — 父页面 → 嵌入端​

postMessage — 嵌入端 → 父页面（name）​

所选新闻事件（原始数组）​

嵌入约束​

语言

路由