# Korea Crypto Arbitrage Tracker (Kimchi Premium) (`gochujang/kimchi-premium-tracker`) Actor Track real-time price differences between Korean crypto exchanges (Upbit, Bithumb) and Binance. Automatically calculates Kimchi Premium % for 170+ KRW-listed tokens. Detect arbitrage opportunities, monitor cross-exchange spreads, and get ranked results by premium percentage. - **URL**: https://apify.com/gochujang/kimchi-premium-tracker.md - **Developed by:** [Hojun Lee](https://apify.com/gochujang) (community) - **Categories:** Developer tools, Automation, Other - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Korea Crypto Arbitrage Tracker (Kimchi Premium) > Real-time price comparison between Korean crypto exchanges (Upbit, Bithumb) and Binance — calculates the **Kimchi Premium %** for 170+ KRW-listed tokens automatically. If you trade crypto and want to know whether Korean exchanges are pricing assets higher or lower than global markets, this Actor gives you a full snapshot in seconds — no API key required. ### What is the Kimchi Premium? The **Kimchi Premium** is the price difference between South Korean crypto exchanges and global ones. Korean retail demand, capital controls, and limited arbitrage pathways cause BTC, ETH, and altcoins to trade at a persistent premium (or occasional discount) on Upbit and Bithumb compared to Binance. Traders and quants track this metric to: - Detect arbitrage opportunities before they close - Gauge Korean retail sentiment (high premium = FOMO, low/negative = fear) - Monitor cross-exchange inefficiencies for specific tokens - Build trading signals based on premium divergence ### Features - **170+ tokens tracked** — auto-detects all KRW-listed coins on Upbit, no manual list needed - **Upbit + Bithumb** — both major Korean exchanges in one run - **Binance comparison** — with CoinGecko fallback if Binance is rate-limited - **USD/KRW rate** — auto-fetched from open.er-api.com with fallback - **Reverse premium detection** — flags tokens where Korean price is *below* global (rare, high signal) - **Upbit-Bithumb spread** — internal Korean exchange comparison - **Threshold filter** — show only tokens above a minimum premium % - **Sort options** — by premium (high/low) or alphabetically - **No API key needed** — all public APIs ### Input | Field | Type | Default | Description | |-------|------|---------|-------------| | `autoDetectAll` | boolean | `true` | Track all KRW-listed coins on Upbit automatically | | `symbols` | string[] | `[]` | Specific tokens only (used when autoDetectAll is off) | | `includeUpbit` | boolean | `true` | Include Upbit exchange | | `includeBithumb` | boolean | `true` | Include Bithumb exchange | | `premiumThreshold` | number | `0` | Minimum absolute premium % to include in results | | `sortBy` | string | `premium_desc` | `premium_desc`, `premium_asc`, or `symbol_asc` | **Minimal input** (track everything): ```json {} ```` **Custom input** (only show tokens with 2%+ premium, sorted): ```json { "premiumThreshold": 2.0, "sortBy": "premium_desc" } ``` ### Output Each item in the dataset: ```json { "symbol": "BERA", "binance_usdt": 0.404, "binance_krw_equivalent": 610, "upbit_krw": 687.0, "upbit_premium_pct": 12.61, "upbit_is_reverse": false, "bithumb_krw": 616.0, "bithumb_premium_pct": 0.98, "bithumb_is_reverse": false, "upbit_bithumb_spread_pct": 11.53, "usd_krw_rate": 1510.03, "timestamp": "2026-04-05T05:53:50Z" } ``` A `SUMMARY` record is also saved to the Key-Value Store with aggregate stats: ```json { "total_tokens": 177, "avg_upbit_premium_pct": 0.43, "tokens_with_premium": 112, "tokens_with_reverse": 24, "top_5_upbit": ["BERA", "STX", "STRAX", "BREV", "BONK"], "usd_krw_rate": 1510.03, "timestamp": "2026-04-05T05:53:50Z" } ``` ### Real Sample Output (April 2026) | Token | Upbit (KRW) | Binance (USD) | Upbit Premium | Bithumb Premium | |-------|------------|---------------|--------------|----------------| | BERA | ₩687 | $0.404 | **+12.61%** | +0.98% | | STX | ₩328 | $0.2121 | +2.41% | +0.54% | | STRAX | ₩20.1 | $0.01307 | +1.84% | +0.73% | | BTC | ₩119,700,000 | $79,300 | +0.12% | -0.04% | | ETH | ₩1,870,000 | $1,240 | +0.08% | +0.21% | *Data from live run, April 5, 2026. USD/KRW rate: 1,510* ### Use Cases #### 1. Arbitrage Signal Detection Run every 10-15 minutes via Apify Scheduler. When `upbit_premium_pct` spikes above your threshold, it may indicate a cross-exchange opportunity. #### 2. Korean Market Sentiment Index The average Kimchi Premium across all tokens is a well-known leading indicator of Korean retail activity. When it rises sharply, a local pump often follows. #### 3. Token-Specific Monitoring Some tokens show persistent Korean premiums (strong local demand). Others show reverse premiums (local selling pressure). Use `premiumThreshold` + `sortBy` to isolate these. #### 4. Quantitative Research & Backtesting Combine with historical price data to test whether premium spikes predict short-term price movements. #### 5. Alert System Pipe the dataset output into a Telegram/Slack webhook to get alerted when premium crosses a threshold. ### Pricing Pay-Per-Event (PPE): - **$0.003 per token tracked** (~$0.51 per full run of 170 tokens) - Apify platform usage included free Cheaper than any crypto data API for this specific use case. ### API Access You can also query the Actor output via Apify API after each run: ```bash curl "https://api.apify.com/v2/datasets/{datasetId}/items?token=YOUR_TOKEN" ``` Or trigger runs programmatically: ```bash curl -X POST "https://api.apify.com/v2/acts/gochujang~kimchi-premium-tracker/runs?token=YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"premiumThreshold": 1.5}' ``` ### Schedule Example Run every 15 minutes automatically via Apify Scheduler: ``` */15 * * * * ``` ### Notes - Bithumb maintenance: KST 01:00–08:00 daily. Bithumb data will be missing during this window. - Tokens with premium > ±15% are excluded (likely symbol mismatches, e.g., different assets with same ticker) - Exchange rate updated at runtime from open.er-api.com (fallback: exchangerate-api.com) - All APIs are public — no keys required to run ### Disclaimer Unofficial. Not affiliated with Upbit, Bithumb, or Binance. For informational purposes only. Not financial advice. # Actor input Schema ## `autoDetectAll` (type: `boolean`): Automatically detect and track all KRW-listed coins on Upbit (~240 tokens). Overrides the symbols list below. ## `symbols` (type: `array`): Specific token symbols to track (e.g., BTC, ETH, XRP). Only used when 'Track All Coins' is off. ## `includeUpbit` (type: `boolean`): Include Upbit exchange in comparison. ## `includeBithumb` (type: `boolean`): Include Bithumb exchange in comparison. ## `premiumThreshold` (type: `number`): Only include tokens with absolute premium above this threshold. Set to 0 to include all. ## `sortBy` (type: `string`): Sort results by premium percentage. ## Actor input object example ```json { "autoDetectAll": true, "symbols": [ "BTC", "ETH", "XRP", "SOL", "DOGE" ], "includeUpbit": true, "includeBithumb": true, "premiumThreshold": 0, "sortBy": "premium_desc" } ``` # Actor output Schema ## `results` (type: `string`): No description ## `summary` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "symbols": [ "BTC", "ETH", "XRP", "SOL", "DOGE" ] }; // Run the Actor and wait for it to finish const run = await client.actor("gochujang/kimchi-premium-tracker").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "symbols": [ "BTC", "ETH", "XRP", "SOL", "DOGE", ] } # Run the Actor and wait for it to finish run = client.actor("gochujang/kimchi-premium-tracker").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "symbols": [ "BTC", "ETH", "XRP", "SOL", "DOGE" ] }' | apify call gochujang/kimchi-premium-tracker --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=gochujang/kimchi-premium-tracker", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Korea Crypto Arbitrage Tracker (Kimchi Premium)", "description": "Track real-time price differences between Korean crypto exchanges (Upbit, Bithumb) and Binance. Automatically calculates Kimchi Premium % for 170+ KRW-listed tokens. Detect arbitrage opportunities, monitor cross-exchange spreads, and get ranked results by premium percentage.", "version": "0.1", "x-build-id": "BwQgZ1Oo7ALFkjhlM" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/gochujang~kimchi-premium-tracker/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-gochujang-kimchi-premium-tracker", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/gochujang~kimchi-premium-tracker/runs": { "post": { "operationId": "runs-sync-gochujang-kimchi-premium-tracker", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/gochujang~kimchi-premium-tracker/run-sync": { "post": { "operationId": "run-sync-gochujang-kimchi-premium-tracker", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "autoDetectAll": { "title": "Track All Coins", "type": "boolean", "description": "Automatically detect and track all KRW-listed coins on Upbit (~240 tokens). Overrides the symbols list below.", "default": true }, "symbols": { "title": "Token Symbols (if Track All Coins is off)", "type": "array", "description": "Specific token symbols to track (e.g., BTC, ETH, XRP). Only used when 'Track All Coins' is off.", "default": [], "items": { "type": "string" } }, "includeUpbit": { "title": "Include Upbit", "type": "boolean", "description": "Include Upbit exchange in comparison.", "default": true }, "includeBithumb": { "title": "Include Bithumb", "type": "boolean", "description": "Include Bithumb exchange in comparison.", "default": true }, "premiumThreshold": { "title": "Premium Threshold (%)", "minimum": 0, "maximum": 100, "type": "number", "description": "Only include tokens with absolute premium above this threshold. Set to 0 to include all.", "default": 0 }, "sortBy": { "title": "Sort By", "enum": [ "premium_desc", "premium_asc", "symbol_asc" ], "type": "string", "description": "Sort results by premium percentage.", "default": "premium_desc" } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```