Kimchi Premium Tracker

Monitor the crypto kimchi premium between Korean KRW exchanges and global USD/USDT reference markets.

This Apify Actor compares public prices from Upbit, Bithumb, a resilient global USD/USDT reference feed (Coinbase, Bybit, Kraken, with Binance fallback), and USD/KRW FX data, then saves one dataset row for each token and Korean exchange pair.

What does Kimchi Premium Tracker do?

Kimchi Premium Tracker calculates the percentage gap between a Korean KRW crypto price and a global USD price converted into KRW.

It helps answer questions like:

• Is BTC trading higher on Upbit than on a global USD/USDT reference after FX conversion?
• Which Korean venue has the largest premium or discount right now?
• Did a monitored token cross my alert threshold?
• Which source failed if a data point is incomplete?

Who is it for?

Crypto traders, market-monitoring teams, analysts, and quant researchers use this Actor when they need current Korea-vs-global price gap signals.

Typical personas:

• Arbitrage researchers checking cross-market spreads
• Risk teams monitoring Korea-specific market stress
• Crypto dashboards that need normalized premium rows
• Journalists and analysts tracking Korean retail demand
• Data engineers feeding recurring market snapshots into warehouses

Why use it?

Kimchi premium calculations are simple in theory but annoying in production.

You need to fetch Korean KRW prices, fetch global USD prices, fetch USD/KRW FX, normalize timestamps, handle unavailable markets, and keep a repeatable output schema.

This Actor wraps that workflow into one run.

Data sources

The Actor uses public HTTP APIs:

• Upbit ticker endpoint for KRW markets
• Bithumb ticker endpoint for KRW markets
• Coinbase, Bybit, Kraken, and Binance public spot ticker endpoints for USD/USDT markets
• Frankfurter FX endpoint for USD/KRW conversion

No login, browser automation, cookies, or exchange account is required.

Data output table

Each dataset item contains:

Field	Description
token	Crypto ticker symbol such as BTC or ETH
koreanExchange	Upbit or Bithumb
globalExchange	Actual global source used (coinbase, bybit, kraken, or binance)
krwPrice	Korean exchange price in KRW
globalUsdPrice	Global USD/USDT reference price
fxRateUsdKrw	USD to KRW rate
globalKrwPrice	Global USD price converted to KRW
premiumPct	Kimchi premium percentage
premiumDirection	premium, discount, flat, or unknown
thresholdMatched	Whether the configured threshold was reached
status	ok, partial, or error
errors	Source-level failure messages
koreanSourceUrl	URL used for Korean exchange data
globalSourceUrl	URL used for global exchange data
fxSourceUrl	URL used for FX data
checkedAt	Time the row was generated

How much does it cost to track kimchi premium data?

The Actor uses pay-per-event pricing.

• A small start event is charged once per run.
• A result event is charged for each token/exchange comparison row saved.
• You control costs with tokens, koreanExchanges, and maxPairs.

For example, four tokens across two Korean exchanges produce up to eight comparison rows.

Quick start

1. Open the Actor on Apify.
2. Keep the default tokens or enter your own symbols.
3. Select Upbit, Bithumb, or both.
4. Choose a premium threshold.
5. Run the Actor.
6. Export the dataset as JSON, CSV, Excel, or through the API.

Input configuration

tokens

A list of crypto symbols to monitor.

Examples:

• BTC
• ETH
• XRP
• SOL
• DOGE
• ADA

koreanExchanges

Choose one or both supported Korean exchanges.

Supported values:

• upbit
• bithumb

globalExchange

The recommended auto mode tries multiple public global price sources in this order: Coinbase, Bybit, Kraken, then Binance. This keeps default runs useful when one upstream API is unavailable from a cloud runtime location.

Supported values:

• auto
• coinbase
• bybit
• kraken
• binance

minPremiumPct

Sets the absolute threshold for thresholdMatched.

Use 1 to mark rows where the premium or discount is at least 1%.

includeAllRows

When enabled, every comparison row is saved.

When disabled, the Actor saves threshold matches and rows with partial/error status.

maxPairs

A safety cap for saved rows.

Each token multiplied by each Korean exchange counts as one pair.

Output example

{
  "token": "BTC",
  "koreanExchange": "upbit",
  "globalExchange": "coinbase",
  "krwPrice": 150000000,
  "globalUsdPrice": 108000,
  "fxRateUsdKrw": 1360.5,
  "globalKrwPrice": 146934000,
  "premiumPct": 2.086,
  "premiumDirection": "premium",
  "thresholdMatched": true,
  "status": "ok",
  "errors": [],
  "checkedAt": "2026-07-03T00:00:00.000Z"
}

Tips for best results

• Use liquid symbols that exist on Korean exchanges and at least one supported global source.
• Keep includeAllRows enabled for monitoring dashboards.
• Use minPremiumPct for alert filtering.
• Use maxPairs to bound large token lists.
• Treat partial rows as useful diagnostics rather than silent failures.

Handling unavailable markets

Not every token exists on every venue.

If a token is missing from Upbit, Bithumb, or every selected global source, the Actor still saves a row with:

• status set to partial or error
• null price fields where needed
• an explanation in errors

This makes recurring jobs easier to debug.

Integrations

Use the output with:

• Trading dashboards
• Google Sheets exports
• Data warehouses
• Alerting pipelines
• Quant notebooks
• Internal monitoring jobs

API usage with Node.js

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/kimchi-premium-tracker').call({
  tokens: ['BTC', 'ETH', 'XRP'],
  koreanExchanges: ['upbit', 'bithumb'],
  minPremiumPct: 1,
});

console.log(run.defaultDatasetId);

API usage with Python

from apify_client import ApifyClient

client = ApifyClient('MY-APIFY-TOKEN')
run = client.actor('automation-lab/kimchi-premium-tracker').call(run_input={
    'tokens': ['BTC', 'ETH', 'XRP'],
    'koreanExchanges': ['upbit', 'bithumb'],
    'minPremiumPct': 1,
})
print(run['defaultDatasetId'])

API usage with cURL

curl -X POST 'https://api.apify.com/v2/acts/automation-lab~kimchi-premium-tracker/runs?token=MY-APIFY-TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"tokens":["BTC","ETH"],"koreanExchanges":["upbit","bithumb"],"minPremiumPct":1}'

MCP usage

Connect the Actor to Claude via Apify MCP:

https://mcp.apify.com/?tools=automation-lab/kimchi-premium-tracker

Claude Code setup:

$claude mcp add apify https://mcp.apify.com/?tools=automation-lab/kimchi-premium-tracker

Claude Desktop JSON configuration:

{
  "mcpServers": {
    "apify-kimchi-premium-tracker": {
      "url": "https://mcp.apify.com/?tools=automation-lab/kimchi-premium-tracker"
    }
  }
}

Example prompts:

• Run the kimchi premium tracker for BTC, ETH, and XRP.
• Show me Korean crypto premium rows where the premium is above 2%.
• Export current Upbit and Bithumb premium data to a table.

Scheduling

You can schedule the Actor on Apify to create recurring market snapshots.

Common cadences:

• Every 15 minutes for dashboards
• Hourly for market monitoring
• Daily for historical research snapshots

Legality

This Actor uses public market data APIs.

You are responsible for complying with exchange API terms, local laws, and your organization's market-data policies.

The Actor does not place trades, manage accounts, or provide financial advice.

FAQ

Is this a trading bot?

No. It only fetches public market data and calculates premium rows. It does not place trades or manage exchange accounts.

Does it require Korean exchange API keys?

No. The current implementation uses public ticker endpoints and does not require login credentials.

Troubleshooting

Why is a row partial?

A row is partial when one source failed or a symbol does not exist on a venue.

Check the errors field and source URLs.

Why is the premium null?

The premium is null when either the Korean price, global price, or FX rate could not be calculated.

Why do I see discounts?

A negative premium means the Korean KRW price is below the FX-adjusted global reference price.

Related scrapers and monitors

Other automation-lab actors that may fit adjacent workflows:

• https://apify.com/automation-lab/cex-perp-funding-aggregator
• https://apify.com/automation-lab/token-unlock-calendar

Reliability notes

The Actor retries transient request failures with backoff.

It avoids browser automation and proxies because the data sources are public API endpoints.

Changelog

Initial version tracks Upbit and Bithumb KRW markets against resilient global USD/USDT prices with USD/KRW FX conversion.

Support

If you need additional exchanges, output fields, or alert formats, open an issue on the Apify Actor page.