Kimchi Premium Tracker

Kimchi Premium Tracker (Upbit × Binance)

Track the kimchi premium — the gap between Korean (Upbit KRW) prices and global (Binance USDT) prices — per token, with the KRW/USD rate taken from the market's own KRW-USDT pair. Each run returns one live record per token with both price legs, the implied USD price, the FX rate and the premium percentage. Built for traders, quant hobbyists and bot builders who schedule runs and pipe the JSON into dashboards, alerts or models. No account or API key is needed.

Data only, not financial advice.

Use cases

• Premium dashboards: a live board of the premium on the most traded Korean markets, refreshed every few minutes or hourly.
• Korean retail-flow monitoring: a rising premium across many tokens is a classic sign of strong local demand.
• Arbitrage research: compare both price legs per token and spot outliers and discounts, with Upbit's own caution flags alongside.
• Model features: store snapshots and use the premium and KRW turnover as inputs in your own research.

Quick start

1. Open the Actor and click Start. The form is prefilled with the top 40 Upbit KRW markets by 24-hour turnover.
2. Read the rows in the Output tab, or export them as JSON, CSV or Excel.

For a fixed watchlist:

{"tokens": ["BTC", "ETH", "XRP", "SOL"]}

An empty input ({}) runs the same default board: the top 40 KRW markets by 24-hour turnover. Watchlist entries that match no Upbit KRW market produce no rows and are listed in the run warnings; an all-unmatched watchlist finishes successfully with an empty dataset.

Input

Name	Type	Default	Meaning
tokens	array	[]	Optional token watchlist of up to 100 entries, case-insensitive ("BTC" or "KRW-BTC" both work). Empty tracks the top KRW markets by 24h turnover.
topTokens	integer	40	Board size when no watchlist is given (10–100).
alertPremiumPct	number	3	Tokens whose premium magnitude reaches this percent (0–100) go into the Telegram digest. The threshold is symmetric, so deep discounts count too.
telegramChatId	string	empty	Chat for the digest; requires the TELEGRAM_BOT_TOKEN secret environment variable, so it suits your own copy of the Actor.
requestDelaySecs	number	0.25	Pause between requests on whole-board runs (0–10 seconds).
maxPlausiblePremiumPct	number	50	Suppress premiums whose absolute value exceeds this percent (1–1000). Both price legs are kept. Known symbol collisions are always suppressed, regardless of this setting.

A misspelt input field stops the run with an error that names it.

What it returns

One dataset row per token:

Field	Meaning
recordKey	Stable key, kimchi:{SYMBOL}.
source, kind	Record source and type.
token, upbitMarket, koreanName	Token symbol, Upbit market and Korean display name.
upbitPriceKrw	Upbit last trade price in KRW.
upbitPriceUsdImplied	The KRW price converted at the run's FX rate.
upbitVolume24hKrw	24-hour KRW turnover used for ranking.
upbitTradeAt	Timestamp of the Upbit trade.
binanceSymbol, binancePriceUsdt	Binance pair and price in USDT, or null for a Korea-only token.
usdtKrwRate	The KRW/USD rate used.
premiumPct	The kimchi premium in percent, rounded to 4 decimal places; null when unavailable or suppressed.
premiumWarning	Reason a computed premium was suppressed, or null.
marketWarning, priceFluctuations	Boolean Upbit market-warning and price-fluctuation caution flags.
sourceUrl, binanceUrl	Public links to the two price sources.
collectedAt	UTC time the snapshot was taken.

The run summary (OUTPUT) reports coverage counters, the alert digest and warnings such as Korea-only tokens with no global pair.

Matching ticker symbols do not guarantee the same asset on both exchanges. Known symbol collisions and price gaps beyond maxPlausiblePremiumPct (default 50% in either direction) get premiumPct: null with a premiumWarning. Both prices are kept for inspection. These checks are safeguards, not proof of asset identity; verify the asset and transfer network before acting. Upbit market warnings remain visible in marketWarning and priceFluctuations.

Output example

Illustrative snapshot (example values; real runs return the live figures):

{"recordKey":"kimchi:BTC","source":"upbit-binance","kind":"kimchi_premium","token":"BTC","upbitMarket":"KRW-BTC","koreanName":"비트코인","upbitPriceKrw":135200000,"upbitPriceUsdImplied":97203.2496944424,"upbitVolume24hKrw":81234567890.0,"upbitTradeAt":"2026-09-06T09:12:45+00:00","binanceSymbol":"BTCUSDT","binancePriceUsdt":96430.1,"usdtKrwRate":1390.9,"premiumPct":0.8018,"premiumWarning":null,"marketWarning":false,"priceFluctuations":false,"sourceUrl":"https://upbit.com/exchange?code=CRIX.UPBIT.KRW-BTC","binanceUrl":"https://www.binance.com/en/trade/BTC_USDT","collectedAt":"2026-09-06T09:12:47Z"}

Pricing

• $0.003 per result delivered (one token).
• $0.005 per run start. The run-start event is charged per GB of memory; the default 512 MB run is one start event. The start is charged even if the run saves no results.

Platform usage is included in these prices.

Worked cost: the default 40-token board is $0.005 + 40 × $0.003 = $0.125. A 4-token watchlist is $0.017. A run every hour on the default board is about $3 a day; a small watchlist keeps frequent schedules cheap.

Scheduling and monitoring

• Schedule a watchlist run every 5–15 minutes, or the full board hourly. recordKey is stable per token (kimchi:{SYMBOL}); key your history on recordKey plus collectedAt.
• For alert-only use, set alertPremiumPct with telegramChatId in your own copy of the Actor. A failed or skipped send is a warning in OUTPUT, never a failed run.

FAQ

How is the premium computed? ((upbitPriceKrw / usdtKrwRate) / binancePriceUsdt − 1) × 100, with the KRW/USD rate anchored on the market's own KRW-USDT pair rather than a third-party FX feed.

What about tokens listed only in Korea? They keep their Upbit-side record with premiumPct as an explicit null, never guessed, and are named in the run warnings.

How many tokens can I track? Up to 100 watchlist entries, or the top 40 KRW markets by turnover (configurable with topTokens).

Are both spikes and discounts alerted? Yes — the threshold is symmetric, so a deep negative premium alerts exactly like a spike.

Can I get the Telegram digest? Set telegramChatId and provide the TELEGRAM_BOT_TOKEN secret. Without them, the run still collects the board; a failed or skipped send is a warning, not a failed run.

How fresh is the data? Each run reads both exchanges' live prices at run time; nothing is cached between runs.

Export formats? JSON, CSV, Excel, XML or RSS from the dataset, or read it through the Apify API in your own pipeline.

Limits

• Upbit KRW markets against Binance USDT pairs only.
• One snapshot per run; no price history.
• A matching ticker symbol on both exchanges doesn't prove it's the same asset (see above).

For support, contact Apify support and include the Actor run ID.