# 암호화폐 통합 시세·김치프리미엄 국내외 주요 거래소의 실시간 시세를 한 번에 모아 주고, 원화 환산 기준가와 한국 시장 프리미엄(김치프리미엄)을 함께 계산합니다. 인증: Authorization: Bearer $APICK_API_KEY 본문 있는 REST 요청: multipart/form-data. GET 본문 및 MCP JSON-RPC 규격은 해당 명세를 따릅니다. 인증키는 서버에 보관하세요. 모든 예제는 정적 자료입니다. ## POST /rest/crypto_market 응답 필드 - `data` (object): 요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다. - `data.as_of` (string): 시세를 모은 시각입니다. 초 단위까지 포함한 국제표준시 표기입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. - `data.fx` (object): 환산 기준입니다. usdt_krw는 국내에서 거래되는 USDT의 원화 시세이며, 확인하지 못하면 null입니다. null 허용. - `data.fx.usdt_krw` (number): 'usdt_krw' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요. - `data.assets` (array): 요청한 심볼 순서대로 담긴 결과입니다. 심볼마다 국내 시세(domestic)·국외 시세(global)·프리미엄을 담습니다. - `data.assets[].symbol` (string): 코인 심볼입니다. 예: BTC 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. - `data.assets[].domestic` (array): 국내 거래소의 원화 시세 목록입니다. market(거래소), price_krw, change_percent_24h, volume_24h_krw, high_krw, low_krw를 담습니다. - `data.assets[].domestic[].market` (string): 'market' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다. - `data.assets[].domestic[].currency` (string): 가격의 통화 코드입니다. 예: KRW, USD. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. - `data.assets[].domestic[].price_krw` (integer): 'price_krw' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요. - `data.assets[].domestic[].change_percent_24h` (number): 'change_percent_24h' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요. - `data.assets[].domestic[].volume_24h_krw` (integer): 'volume_24h_krw' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요. - `data.assets[].domestic[].high_krw` (integer): 'high_krw' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요. - `data.assets[].domestic[].low_krw` (integer): 'low_krw' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요. - `data.assets[].global` (array): 국외 거래소의 USDT 시세 목록입니다. market, pair, price_usdt, change_percent_24h, volume_24h_usdt, high_usdt, low_usdt를 담습니다. - `data.assets[].global[].market` (string): 'market' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다. - `data.assets[].global[].pair` (string): 'pair' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다. - `data.assets[].global[].price_usdt` (number): 'price_usdt' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요. - `data.assets[].global[].change_percent_24h` (number): 'change_percent_24h' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요. - `data.assets[].global[].volume_24h_usdt` (integer): 'volume_24h_usdt' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요. - `data.assets[].global[].high_usdt` (number): 'high_usdt' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요. - `data.assets[].global[].low_usdt` (number): 'low_usdt' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요. - `data.assets[].reference_price_krw` (number): 국외 USDT 시세를 원화로 환산한 기준가입니다. 비교에 쓰는 값이며 실제 체결 가격이 아닙니다. null 허용. - `data.assets[].premium_percent` (number): 국내 원화 시세가 환산 기준가보다 몇 % 높은지입니다. 계산할 수 없으면 null입니다. null 허용. - `data.assets[].premium_source` (object): 프리미엄 계산에 쓴 시세 조합입니다. domestic_market과 global_market이 들어 있습니다. null 허용. - `data.assets[].premium_source.domestic_market` (string): 'domestic_market' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다. - `data.assets[].premium_source.global_market` (string): 'global_market' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다. - `data.summary` (object): 공고의 짧은 요약입니다. 본문 전체는 description_html에서 확인하세요. - `data.summary.requested` (integer): 'requested' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요. - `data.summary.domestic_markets` (integer): 'domestic_markets' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요. - `data.summary.premium_computed` (integer): 'premium_computed' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요. - `data.partial` (boolean): 일부 심볼이나 거래소의 시세가 빠졌으면 true입니다. true/false로 오며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 이 필드가 나타내는 조건이 성립한 경우, false = 성립하지 않은 경우입니다. 두 값 모두 정상 응답에 올 수 있으며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. - `data.warnings` (array): 빠진 값에 대한 안내 문구입니다. 모두 정상이면 빈 배열입니다. 각 항목의 구성은 서비스에 따라 다르며, 값이 없으면 빈 배열입니다. 항목 수와 순서를 함께 확인하세요. - `data.success` (integer): 업무 처리 결과 코드입니다. 1은 정상 결과, 0은 실패 또는 무료 응답입니다. 서비스에 따라 2·3처럼 추가 코드를 쓰므로 같은 응답의 status·msg·error 필드도 함께 확인하세요. - `data.error` (string): 오류 원인을 설명하는 문구입니다. 성공 응답에는 없거나 빈 문자열입니다. - `api` (object): API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다. - `api.success` (boolean): API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다. - `api.cost` (integer): 이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다. - `api.ms` (integer): 서버가 요청을 받아 응답 본문을 만들기까지 걸린 처리 시간(밀리초)입니다. 네트워크 왕복 시간과 클라이언트 대기 시간은 포함되지 않습니다. - `api.pl_id` (integer): 포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다. ## API 요청: POST /rest/crypto_market ### 입력 - `symbols` (string, 선택): 심볼을 쉼표로 구분 (예: BTC,ETH,XRP). 생략하면 BTC,ETH,XRP,SOL,DOGE ### 응답 명세 ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "as_of": { "type": "string", "description": "시세를 모은 시각입니다. 초 단위까지 포함한 국제표준시 표기입니다." }, "fx": { "type": "object", "properties": { "usdt_krw": { "type": "number" } }, "description": "환산 기준입니다. usdt_krw는 국내에서 거래되는 USDT의 원화 시세이며, 확인하지 못하면 null입니다.", "nullable": true }, "assets": { "type": "array", "items": { "type": "object", "properties": { "symbol": { "type": "string", "description": "코인 심볼입니다. 예: BTC" }, "domestic": { "type": "array", "items": { "type": "object", "properties": { "market": { "type": "string" }, "currency": { "type": "string" }, "price_krw": { "type": "integer" }, "change_percent_24h": { "type": "number" }, "volume_24h_krw": { "type": "integer" }, "high_krw": { "type": "integer" }, "low_krw": { "type": "integer" } } }, "description": "국내 거래소의 원화 시세 목록입니다. market(거래소), price_krw, change_percent_24h, volume_24h_krw, high_krw, low_krw를 담습니다." }, "global": { "type": "array", "items": { "type": "object", "properties": { "market": { "type": "string" }, "pair": { "type": "string" }, "price_usdt": { "type": "number" }, "change_percent_24h": { "type": "number" }, "volume_24h_usdt": { "type": "integer" }, "high_usdt": { "type": "number" }, "low_usdt": { "type": "number" } } }, "description": "국외 거래소의 USDT 시세 목록입니다. market, pair, price_usdt, change_percent_24h, volume_24h_usdt, high_usdt, low_usdt를 담습니다." }, "reference_price_krw": { "type": "number", "description": "국외 USDT 시세를 원화로 환산한 기준가입니다. 비교에 쓰는 값이며 실제 체결 가격이 아닙니다.", "nullable": true }, "premium_percent": { "type": "number", "description": "국내 원화 시세가 환산 기준가보다 몇 % 높은지입니다. 계산할 수 없으면 null입니다.", "nullable": true }, "premium_source": { "type": "object", "properties": { "domestic_market": { "type": "string" }, "global_market": { "type": "string" } }, "description": "프리미엄 계산에 쓴 시세 조합입니다. domestic_market과 global_market이 들어 있습니다.", "nullable": true } } }, "description": "요청한 심볼 순서대로 담긴 결과입니다. 심볼마다 국내 시세(domestic)·국외 시세(global)·프리미엄을 담습니다." }, "summary": { "type": "object", "properties": { "requested": { "type": "integer" }, "domestic_markets": { "type": "integer" }, "premium_computed": { "type": "integer" } }, "description": "요청 심볼 수(requested), 응답한 국내 거래소 수(domestic_markets), 프리미엄을 계산한 심볼 수(premium_computed)입니다." }, "partial": { "type": "boolean", "description": "일부 심볼이나 거래소의 시세가 빠졌으면 true입니다." }, "warnings": { "type": "array", "items": {}, "description": "빠진 값에 대한 안내 문구입니다. 모두 정상이면 빈 배열입니다." }, "success": { "type": "integer" }, "error": { "type": "string", "description": "실패 사유 문구입니다. 정상 응답에는 없으며, 값이 있으면 아래 오류 응답 표에서 원인과 조치를 확인하세요." } }, "description": "시세 결과 묶음입니다. 실패하면 아래 필드 대신 error 문구가 들어 있습니다." }, "api": { "type": "object", "properties": { "success": { "type": "boolean" }, "cost": { "type": "integer", "description": "이번 호출에서 차감된 포인트입니다. data.error가 있는 실패 응답은 0입니다." }, "ms": { "type": "integer", "description": "요청을 받아 응답을 만들기까지 걸린 시간(밀리초)입니다." }, "pl_id": { "type": "integer", "description": "포인트 차감 기록 번호입니다. 차감이 있었던 호출에만 값이 있습니다." } }, "description": "호출 공통 정보입니다. 처리 여부·차감 포인트·처리 시간·차감 기록 번호가 들어 있습니다." } } } ``` ### 정적 응답 예시 ```json { "data": { "as_of": "2026-11-01T07:21:04.512Z", "fx": { "usdt_krw": 1385.2 }, "assets": [ { "symbol": "BTC", "domestic": [ { "market": "upbit", "currency": "KRW", "price_krw": 132450000, "change_percent_24h": 1.24, "volume_24h_krw": 81234567890, "high_krw": 133100000, "low_krw": 130200000 } ], "global": [ { "market": "binance", "pair": "BTCUSDT", "price_usdt": 95120.4, "change_percent_24h": 1.08, "volume_24h_usdt": 2851234567, "high_usdt": 95800.2, "low_usdt": 93810.5 } ], "reference_price_krw": 131761829.28, "premium_percent": 0.52, "premium_source": { "domestic_market": "upbit", "global_market": "binance" } } ], "summary": { "requested": 3, "domestic_markets": 2, "premium_computed": 3 }, "partial": false, "warnings": [], "success": 1 }, "api": { "success": true, "cost": 30, "ms": 812, "pl_id": 50231 } } ``` ### curl ```curl curl --fail-with-body --request POST 'https://apick.app/rest/crypto_market' \ --header "Authorization: Bearer $APICK_API_KEY" \ --form-string 'symbols=BTC,ETH,XRP' ``` ### Node.js (서버 ESM) ```javascript const form = new FormData(); form.append("symbols", "BTC,ETH,XRP"); const response = await fetch("https://apick.app/rest/crypto_market", { method: "POST", headers: { Authorization: "Bearer " + process.env.APICK_API_KEY }, body: form, signal: AbortSignal.timeout(120_000), }); if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`); const result = await response.json(); console.log(result); ``` ### python ```python import os import requests parts = [ ("symbols", (None, "BTC,ETH,XRP")), ] response = requests.request("POST", "https://apick.app/rest/crypto_market", headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]}, files=parts, timeout=(10, 120)) response.raise_for_status() result = response.json() print(result) ``` ### php ```php 'BTC,ETH,XRP', ]; $curl = curl_init('https://apick.app/rest/crypto_market'); curl_setopt_array($curl, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => $headers, CURLOPT_POSTFIELDS => $form, CURLOPT_RETURNTRANSFER => true, CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120, ]); $body = curl_exec($curl); if ($body === false) { throw new RuntimeException(curl_error($curl)); } $status = curl_getinfo($curl, CURLINFO_HTTP_CODE); curl_close($curl); if ($status >= 400) { throw new RuntimeException($body); } $result = json_decode($body, true, 512, JSON_THROW_ON_ERROR); print_r($result); ``` ## 사용 예시 1. 주요 코인 시세와 프리미엄 한 번에 보기 대표 코인의 국내 원화 시세와 한국 시장 프리미엄을 한 번에 확인할 때 씁니다. ```bash curl --fail-with-body --request POST 'https://apick.app/rest/crypto_market' \ --header "Authorization: Bearer $APICK_API_KEY" \ --form-string 'symbols=BTC,ETH,XRP,SOL' ``` - `data.assets[]`는 보낸 심볼 순서대로 담기며, `premium_percent`가 양수면 국내 시세가 더 높습니다. - `data.partial`이 true이면 일부 거래소 시세가 빠진 것이므로 `data.warnings`를 함께 확인합니다. ## 사용 예시 2. 프리미엄이 큰 코인만 추리기 여러 코인을 한 번에 받아 프리미엄이 큰 순서로 정렬해 볼 때 씁니다. ```bash curl --fail-with-body --request POST 'https://apick.app/rest/crypto_market' \ --header "Authorization: Bearer $APICK_API_KEY" \ --form-string 'symbols=BTC,ETH,XRP,SOL,DOGE,ADA,TRX,AVAX' ``` - `premium_percent`가 null인 항목은 환산 기준가를 계산하지 못한 것이므로 비교에서 뺍니다. - `data.summary.premium_computed`로 계산된 코인 수를 확인합니다. ## 코드·오류 ### 업무 실패 응답 입력 오류·대상 없음·일시 실패는 data.error(사유)와 data.success=0으로 오며 api.cost는 0(과금 없음)입니다. HTTP 상태는 400·404·408·424 중 하나입니다. 입력 오류는 값을 고쳐 다시 요청하고, 408·424는 잠시 후 한 번 다시 시도하세요. ```json { "data": { "error": "입력값을 확인해 주세요.", "success": 0 }, "api": { "success": true, "cost": 0, "ms": 5 } } ``` ## 상세 기능·요금 제공 정보 코인 심볼을 쉼표로 구분해 보내면 국내 거래소의 원화 시세와 국외 거래소의 USDT 시세를 한 번에 돌려줍니다. 국내 USDT 원화 시세를 환산 기준으로 삼아 코인별 한국 시장 프리미엄(%)을 계산합니다. 별도의 환율 상품을 함께 호출하지 않아도 됩니다. 일부 거래소가 응답하지 않아도 나머지 시세로 응답하며 partial이 true가 됩니다. 계산할 수 없는 값은 null입니다. Method URL POST https://apick.app/rest/crypto_market ## 상세 요청 Header 이름 필수 설명 Authorization 필수 Bearer 인증키. 예: Authorization: Bearer 발급받은_API_키 ## 상세 응답 Body 필드 타입 설명 data Object 시세 결과 묶음입니다. 실패하면 아래 필드 대신 error 문구가 들어 있습니다. as_of String 시세를 모은 시각입니다. 초 단위까지 포함한 국제표준시 표기입니다. fx Object 환산 기준입니다. usdt_krw는 국내에서 거래되는 USDT의 원화 시세이며, 확인하지 못하면 null입니다. assets Array 요청한 심볼 순서대로 담긴 결과입니다. 심볼마다 국내 시세(domestic)·국외 시세(global)·프리미엄을 담습니다. assets[].symbol String 코인 심볼입니다. 예: BTC assets[].domestic Array 국내 거래소의 원화 시세 목록입니다. market(거래소), price_krw, change_percent_24h, volume_24h_krw, high_krw, low_krw를 담습니다. assets[].global Array 국외 거래소의 USDT 시세 목록입니다. market, pair, price_usdt, change_percent_24h, volume_24h_usdt, high_usdt, low_usdt를 담습니다. assets[].reference_price_krw Number | null 국외 USDT 시세를 원화로 환산한 기준가입니다. 비교에 쓰는 값이며 실제 체결 가격이 아닙니다. assets[].premium_percent Number | null 국내 원화 시세가 환산 기준가보다 몇 % 높은지입니다. 계산할 수 없으면 null입니다. assets[].premium_source Object | null 프리미엄 계산에 쓴 시세 조합입니다. domestic_market과 global_market이 들어 있습니다. summary Object 요청 심볼 수(requested), 응답한 국내 거래소 수(domestic_markets), 프리미엄을 계산한 심볼 수(premium_computed)입니다. partial Boolean 일부 심볼이나 거래소의 시세가 빠졌으면 true입니다. warnings Array 빠진 값에 대한 안내 문구입니다. 모두 정상이면 빈 배열입니다. error String 실패 사유 문구입니다. 정상 응답에는 없으며, 값이 있으면 아래 오류 응답 표에서 원인과 조치를 확인하세요. api Object 호출 공통 정보입니다. 처리 여부·차감 포인트·처리 시간·차감 기록 번호가 들어 있습니다. cost Integer 이번 호출에서 차감된 포인트입니다. data.error가 있는 실패 응답은 0입니다. ms Integer 요청을 받아 응답을 만들기까지 걸린 시간(밀리초)입니다. pl_id Integer 포인트 차감 기록 번호입니다. 차감이 있었던 호출에만 값이 있습니다. premium_percent가 2.5이면 국내 시세가 환산 기준가보다 2.5% 높다는 뜻입니다. 음수면 국내 시세가 더 낮습니다. 같은 심볼을 5초 안에 다시 요청하면 그 사이에 모은 결과를 그대로 씁니다. ## 상세 코드·정책 오류 응답 HTTP data.error 원인·조치 400 코인 심볼이 올바르지 않습니다. 쉼표로 구분해 2~10자 영문·숫자로 보내 주세요. 심볼 표기가 잘못됐습니다. 대문자 영문·숫자만 쓰며, 빈 값만 보내면 안 됩니다. 400 심볼은 한 번에 20개까지 조회할 수 있습니다. 한 번에 20개를 넘겨 보냈습니다. 나눠서 호출하세요. 424 시세를 가져오지 못했습니다. 잠시 후 다시 시도해 주세요. 모든 거래소에서 시세를 받지 못했습니다. 잠시 후 다시 요청하세요. 오류 응답은 data.success 0, api.cost 0이며 요금이 차감되지 않습니다. ## 상세 예제 요청 예시 form-data 전체 예제 보기 응답 예시 { "data": { "as_of": "2026-11-01T07:21:04.512Z", "fx": { "usdt_krw": 1385.2 }, "assets": [ { "symbol": "BTC", "domestic": [ { "market": "upbit", "currency": "KRW", "price_krw": 132450000, "change_percent_24h": 1.24, "volume_24h_krw": 81234567890, "high_krw": 133100000, "low_krw": 130200000 } ], "global": [ { "market": "binance", "pair": "BTCUSDT", "price_usdt": 95120.4, "change_percent_24h": 1.08, "volume_24h_usdt": 2851234567, "high_usdt": 95800.2, "low_usdt": 93810.5 } ], "reference_price_krw": 131761829.28, "premium_percent": 0.52, "premium_source": { "domestic_market": "upbit", "global_market": "binance" } } ], "summary": { "requested": 3, "domestic_markets": 2, "premium_computed": 3 }, "partial": false, "warnings": [], "success": 1 }, "api": { "success": true, "cost": 30, "ms": 812, "pl_id": 50231 } } 호출 예시 같은 요청을 JavaScript와 Python으로 옮긴 예시입니다. 키는 환경변수 APICK_API_KEY 에서 읽습니다. JavaScript 예시 form-data 전체 예제 보기 Python 예시 form-data 전체 예제 보기