Search params

Use query parameters on https://embed-iccandle-app.iccandle.ai/{locale} to open the iframe on a specific scan result, theme, or filtered view.

For a basic embed URL and host wiring, see Get started. For routes outside the home scanner page, see API reference.

Base shape

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

The home scanner page only runs /search when symbol, res, ref_res, and cid are present.

Required for a home scan

Param	Description	Example
`symbol`	Symbol to search	`EURUSD`
`res`	Match resolution / timeframe	`60`
`ref_res`	Reference resolution for the selected candle window	`60`
`cid`	Candle cache id returned by `cacheCandle`	`9d2b...`

Without these four params, the embed loads but skips the scanner search request.

Optional scan params

Param	Default	Description
`tk`	`10`	Number of matches (`top_k`)
`fs`	—	Comma-separated symbol filter, for example `EURUSD,GBPUSD`
`period`	—	Unix seconds; when `> 0`, filters results to `end_timestamp >= period`
`from`	—	Range start in milliseconds; mainly used by news-related flows
`to`	—	Range end in milliseconds; mainly used by news-related flows
`theme`	—	Visual theme: `light`, `dark`, or `system`
`bg_dark`	embed default	Page background when the theme is dark. Hex, `#` optional.
`bg_light`	embed default	Page background when the theme is light. Hex, `#` optional.
`header`	shown	Set to `false` to hide the embed app header (and its divider)
`model`	`light`	AI generation model for the results UI: `light` or `pro`
`temperature`	`1`	AI generation temperature: `0.5`, `1`, or `1.5`

Param details

`symbol`

Instrument symbol passed into the scanner request. Use the symbol catalog's display_name value.

`res`

Match resolution / timeframe used for the scanner request. Pass the same interval your host chart uses for the matches list.

`ref_res`

Reference resolution for the selected candle window that was cached. Often the same as res, but can differ when the host searches across resolutions.

`cid`

The candle cache id returned by:

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

Use the ID token emitted by the iframe's auth.signIn postMessage as 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);
  }
});

That token can then be sent as the Bearer token when your host calls the cache API:

Example:

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

Use the response id as cid in the iframe URL.

The iframe does not call /search without a non-empty cid.

`tk`

Controls how many similar patterns to request. If omitted, the embed uses 10.

`fs`

Optional comma-separated filter of symbols the scanner should consider. Use display_name values from the symbol catalog.

fs=EURUSD,GBPUSD,S&P500

Available symbols (from display_name):

Forex

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

Commodities

XAUUSD
BCOUSD
XAGUSD
XCUUSD

Indices

S&P500
NASDAQ100
US30

Crypto

BTCUSDT
ETHUSDT
XRPUSDT
SOLUSDT
ADAUSDT
AVAUSDT
AVAXUSDT
BNBUSDT
DOGEUSDT
DOTUSDT
TRXUSDT

Stocks

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

`period`

Optional unix-seconds cutoff used to filter matches by end time. When present and greater than zero, results are filtered to end_timestamp >= period.

`from` and `to`

Optional range helpers in milliseconds. These are mainly useful when you want the embed's news and selected-range flows to align with the host chart window.

`theme`

Controls iframe theme:

Value	Behavior
`light`	Always render light theme
`dark`	Always render dark theme
`system`	Follow the embed app's system-theme behavior

`bg_dark` and `bg_light`

Page background for the embed (--background on the document root), one color per theme.

Param	Applied when
`bg_dark`	Resolved theme is dark
`bg_light`	Resolved theme is light

Hex only: #RGB, #RRGGBB, or #RRGGBBAA. The # may be omitted. Any other string is ignored. Aliases dark_bg / bg-dark and light_bg / bg-light are accepted; bg_dark and bg_light are the names the React widget emits.

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

A valid color is stored in the embed. Later loads that omit bg_* keep the last stored color for that theme. With neither a query param nor a stored color, the embed uses its default background.

With @iccandle/reactjs-widget or @iccandle/vuejs-widget, pass the same values as bg_dark and bg_light. The widget appends them on scan, news, and pricing URLs. Put them on the initial iframe src yourself.

`header`

Controls whether the embed renders its top app header:

Value	Behavior
omitted / any value other than `false`	Show the header (default)
`false`	Hide the header and header divider

Use header=false when the host already provides navigation chrome and you want the iframe to show results only. Footer and in-page UI still render. With the header hidden, nav.click messages from header tabs will not fire.

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

`model`

AI model hint used by the redesigned search-results / AI-movements UI after a scan.

Value	Behavior
`light`	Default lighter model (also used when the param is omitted or unrecognized)
`pro`	Pro model

This does not change the /search request itself; it is consumed by the results UI when generating AI movements.

`temperature`

AI generation temperature for the results UI.

Value	Behavior
`0.5`	Lower creativity
`1`	Default (also used when omitted or unrecognized)
`1.5`	Higher creativity

Same as model: applied by the results UI after scan, not by the /search call.

Example: build scan params

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/en?${params}`;

Example: pattern and utility params on other routes

Some query params are used outside the home scanner route:

Param	Route	Purpose
`header`	App pages	`false` hides the embed header
`tab`	`/{locale}/pattern`	Selects `tracked-pattern` or `common-pattern`
`id`	Pattern detail routes	Pattern id
`pricing=true`	App pages	Opens the pricing modal
`referral`	Sign-in / sign-up	Prefills referral context
`lang`	`/news`	Host widget language hint

Common pattern availability

On /{locale}/pattern?tab=common-pattern, only Bullish Flag (flagbull) and Bearish Flag (flagbear) can be activated today. Other listed common patterns (double top/bottom, head & shoulders) stay visible but disabled. Opening a disabled type such as /{locale}/pattern/dd_bot redirects back to /{locale}/pattern?tab=common-pattern.

Those route-specific params are documented in API reference.

See Get started for the full embed flow and API reference for routes, auth, and protocol details.

Base shape​

Required for a home scan​

Optional scan params​

Param details​

symbol​

res​

ref_res​

cid​

tk​

fs​

period​

from and to​

theme​

bg_dark and bg_light​

header​

model​

temperature​

Example: build scan params​

Example: pattern and utility params on other routes​

Common pattern availability​

Next​