搜索参数

在 https://embed-iccandle-app.iccandle.ai/{locale} 上使用查询参数，可以让 iframe 直接打开到指定扫描结果、主题或筛选视图。

基础嵌入 URL 与宿主接线方式见开始使用。主页扫描以外的路由见 API 参考。

基本形态

https://embed-iccandle-app.iccandle.ai/{locale}?symbol=EURUSD&res=60&ref_res=60&cid=<id>&tk=10&theme=light&header=false&model=light&temperature=1

首页扫描页面只有在同时提供 symbol、res、ref_res 和 cid 时才会执行 /search。

首页扫描必填参数

参数	说明	示例
`symbol`	要搜索的品种	`EURUSD`
`res`	匹配结果的周期 / 分辨率	`60`
`ref_res`	所选缓存 K 线窗口的参考周期	`60`
`cid`	`cacheCandle` 返回的 K 线缓存 id	`9d2b...`

缺少这四个参数时，iframe 仍可加载，但会跳过扫描请求。

可选扫描参数

参数	默认值	说明
`tk`	`10`	返回匹配数量（`top_k`）
`fs`	—	逗号分隔的品种过滤，如 `EURUSD,GBPUSD`
`period`	—	Unix 秒；大于 `0` 时过滤 `end_timestamp >= period`
`from`	—	区间起点，单位毫秒；主要用于新闻相关流程
`to`	—	区间终点，单位毫秒；主要用于新闻相关流程
`theme`	—	视觉主题：`light`、`dark` 或 `system`
`bg_dark`	嵌入默认	主题为深色时的页面背景。十六进制，`#` 可选。
`bg_light`	嵌入默认	主题为浅色时的页面背景。十六进制，`#` 可选。
`header`	显示	设为 `false` 可隐藏嵌入应用顶栏（及其分隔线）
`model`	`light`	结果页 AI 生成模型：`light` 或 `pro`
`temperature`	`1`	结果页 AI 生成温度：`0.5`、`1` 或 `1.5`

内部 /search 默认值还包括 percent: 90 与 analyze_window: 0。

参数详情

`symbol`

传给扫描请求的交易品种。请使用品种目录中的 display_name 值。

可用品种（来自 display_name）：

外汇

EURJPY
GBPJPY
AUDJPY
NZDJPY
CADJPY
CHFJPY
USDJPY
EURUSD
AUDUSD
NZDUSD
USDCHF
USDCAD
GBPAUD
GBPCAD
GBPCHF
GBPNZD
GBPUSD
NZDCAD
EURCAD
EURAUD

商品

XAUUSD
BCOUSD
XAGUSD
XCUUSD

指数

S&P500
NASDAQ100
US30

加密货币

BTCUSDT
ETHUSDT
XRPUSDT
SOLUSDT
ADAUSDT
AVAUSDT
AVAXUSDT
BNBUSDT
DOGEUSDT
DOTUSDT
TRXUSDT

股票

AAPL
AMZN
BRK.B
GOOGL
KO
META
MSFT
NFLX
NKE
NVDA
TME
TSLA

有些品种与其内部 ticker 值不同，例如：

SPX500_USD -> S&P500
NAS100_USD -> NASDAQ100
XAU_USD -> XAUUSD

如果同时传了 fs，请确保 symbol 也在允许的 display_name 列表中。

`res`

扫描匹配结果使用的周期 / 分辨率。应与宿主图表用于匹配列表的 interval 保持一致。

`ref_res`

所选已缓存 K 线窗口的参考周期。通常与 res 相同，但宿主跨周期搜索时可不同。

`cid`

由以下接口返回的 K 线缓存 id：

POST https://scan-service.iccandle.ai/cacheCandle

将 iframe 通过 auth.signIn postMessage 发出的 ID token 保存为 iccandle_token：

window.addEventListener("message", (event) => {
  if (event.origin !== "https://embed-iccandle-app.iccandle.ai") return;

  const message =
    typeof event.data === "string" ? JSON.parse(event.data) : event.data;

  if (message?.name === "auth.signIn") {
    const iccandleToken = message.data.idToken;
    localStorage.setItem("iccandle_token", iccandleToken);
  }
});

随后宿主即可将该 token 作为 Bearer token 调用缓存 API：

curl -X POST "https://scan-service.iccandle.ai/cacheCandle" \
  -H "Authorization: Bearer <iccandle_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "candles": [
      {
        "o": 1.08,
        "h": 1.09,
        "l": 1.07,
        "c": 1.085,
        "timestamp": 1719878400
      }
    ]
  }'

将响应中的 id 用作 iframe URL 里的 cid。

若 cid 为空，iframe 不会调用 /search。

`tk`

控制请求多少条匹配结果。不传时默认为 10。

`fs`

可选的逗号分隔过滤品种列表，使用与 symbol 相同的 display_name 值。它会缩小扫描器考虑的候选品种范围。

fs=EURUSD,GBPUSD,S&P500

`period`

可选的 unix 秒截止时间。存在且大于零时，只保留 end_timestamp >= period 的结果。

`from` 与 `to`

可选区间辅助参数，单位为毫秒。当你希望嵌入端的新闻与所选区间流程与宿主图表窗口对齐时，这两个参数特别有用。

`theme`

控制 iframe 主题：

值	行为
`light`	始终渲染浅色主题
`dark`	始终渲染深色主题
`system`	跟随嵌入应用的系统主题行为

`bg_dark` 与 `bg_light`

嵌入页背景（文档根节点上的 --background），每个主题一个颜色。

参数	生效时机
`bg_dark`	解析后的主题为深色
`bg_light`	解析后的主题为浅色

仅接受十六进制：#RGB、#RRGGBB 或 #RRGGBBAA。# 可省略。其他字符串会被忽略。别名 dark_bg / bg-dark 与 light_bg / bg-light 也可使用；React widget 发出的名称是 bg_dark 与 bg_light。

https://embed-iccandle-app.iccandle.ai/zh?theme=dark&header=false&bg_dark=131722&bg_light=ffffff

有效颜色会保存在嵌入端。之后省略 bg_* 的加载仍沿用该主题上次保存的颜色。既没有查询参数也没有已保存颜色时，嵌入端使用默认背景。

使用 @iccandle/reactjs-widget 或 @iccandle/vuejs-widget 时，把相同的值作为 bg_dark 与 bg_light 传入。组件会把它们追加到扫描、新闻与定价 URL 上。初始 iframe src 需要宿主自己带上。

`header`

控制是否渲染嵌入应用顶栏：

值	行为
省略 / 除 `false` 外的任意值	显示顶栏（默认）
`false`	隐藏顶栏及其分隔线

当宿主已提供导航栏、希望 iframe 只展示结果时，使用 header=false。页脚与页内 UI 仍会渲染。隐藏顶栏后，顶栏标签触发的 nav.click 消息不会发出。

https://embed-iccandle-app.iccandle.ai/zh?theme=light&header=false

`model`

扫描后的新版搜索结果 / AI 走势 UI 使用的模型提示。

值	行为
`light`	默认轻量模型（省略或无法识别时也使用）
`pro`	Pro 模型

该参数不改变 /search 请求本身，由结果 UI 在生成 AI 走势时消费。

`temperature`

结果 UI 的 AI 生成温度。

值	行为
`0.5`	更低创造性
`1`	默认（省略或无法识别时也使用）
`1.5`	更高创造性

与 model 相同：由扫描后的结果 UI 使用，而不是 /search 调用本身。

示例：构造扫描参数

const params = new URLSearchParams({
  symbol: "EURUSD",
  res: "60",
  ref_res: "60",
  cid: candleId,
  tk: "10",
  from: String(startTimestampSec * 1000),
  to: String(endTimestampSec * 1000),
  theme: "light",
  header: "false",
  bg_dark: "0F0F0F",
  bg_light: "ffffff",
  model: "light",
  temperature: "1",
});

iframe.src = `https://embed-iccandle-app.iccandle.ai/zh?${params}`;

示例：其他路由上的形态与工具参数

某些查询参数用于首页扫描路由之外的页面：

参数	路由	用途
`header`	应用页面	`false` 隐藏嵌入顶栏
`tab`	`/{locale}/pattern`	选择 `tracked-pattern` 或 `common-pattern`
`id`	形态详情路由	形态 id
`pricing=true`	应用页面	打开定价弹窗
`referral`	登录 / 注册	预填推荐上下文
`lang`	`/news`	宿主组件语言提示

通用形态可用性

在 /{locale}/pattern?tab=common-pattern 上，目前仅 看涨旗形（flagbull）与 看跌旗形（flagbear）可激活。其他列出的通用形态（双顶/双底、头肩）仍可见但已禁用。打开已禁用类型（例如 /{locale}/pattern/dd_bot）会重定向回 /{locale}/pattern?tab=common-pattern。

这些按路由划分的参数记录在 API 参考中。

下一步

参见开始使用了解完整嵌入流程，以及 API 参考了解路由、认证与协议细节。

基本形态​

首页扫描必填参数​

可选扫描参数​

参数详情​

symbol​

res​

ref_res​

cid​

tk​

fs​

period​

from 与 to​

theme​

bg_dark 与 bg_light​

header​

model​

temperature​

示例：构造扫描参数​

示例：其他路由上的形态与工具参数​

通用形态可用性​

下一步​