REST API#

REST 요청 규칙#

• 공개(public) 엔드포인트(주로 시세 API)는 API 키가 필요 없습니다.
• 비공개(private) 엔드포인트는 X-KAPI-KEY 헤더, timestamp 파라미터, signature 파라미터가 필요합니다.
• GET/DELETE: 입력 값을 URL query string으로 보냅니다.
• POST: 입력 값을 application/x-www-form-urlencoded 본문으로 보내고 Content-Type: application/x-www-form-urlencoded 헤더를 포함합니다.
• 파라미터 순서는 무관하지만, 서명 대상 문자열은 실제로 전송되는 인코딩된 문자열(서명 자체 제외)과 정확히 일치해야 하며, 마지막에 signature를 덧붙입니다.
• query와 body 모두에 파라미터가 있다면 두 문자열을 그대로 이어붙여(queryString + bodyString, 중간에 & 추가 없이) 서명합니다. 가능하면 서명 대상 파라미터를 한 쪽에 모아두세요.

서명 입력 예시 (query + body 결합):

timestamp=1719232467910symbol=btc_krw

Rate Limit#

응답 헤더로 잔여 quota를 추적합니다.

• Ratelimit: limit=50, remaining=48, reset=1
• Ratelimit-Policy: 50;w=1
• HTTP 429과 함께 Retry-After가 반환될 수 있습니다.

HTTP 429를 받으면 Retry-After 또는 Ratelimit reset 시점까지 기다린 뒤 재시도합니다.

Timestamp 검증 윈도우#

비공개 요청에는 다음을 포함합니다.

• timestamp: 현재 Unix 시각(ms).
• recvWindow: 선택값. 유효 윈도우(ms). 기본 5000, 최대 60000.

서버는 다음 조건을 만족할 때에만 요청을 수락합니다.

serverTime - timestamp <= recvWindow
timestamp < serverTime + 1000

클라이언트 시각이 어긋나면 EXCEED_TIME_WINDOW 오류가 반환됩니다. 이 윈도우는 비대칭입니다 — recvWindow는 과거 방향만 넓히고, 미래 경계는 recvWindow로 넓힐 수 없는 고정 +1000 ms입니다 — 따라서 시각이 서버보다 조금이라도 앞서면 모든 서명 요청이 실패하며 recvWindow를 키워도 소용이 없습니다. 원시 호스트 시각이 아니라 Korbit 서버 시각(GET /v2/time)을 기준으로 서명하세요. 복원력 recipe 6을 참고하세요.

HMAC-SHA256 헬퍼#

Node.js 예제. 실제로 전송할 URLSearchParams를 그대로 서명한 뒤 signature를 덧붙입니다.

import crypto from "node:crypto";

const BASE_URL = "https://api.korbit.co.kr";
const apiKey = process.env.KORBIT_API_KEY;
const apiSecret = process.env.KORBIT_API_SECRET;

function signHmac(encodedParams) {
  return crypto.createHmac("sha256", apiSecret).update(encodedParams, "utf8").digest("hex");
}

async function korbitPrivate(method, path, params = {}) {
  const clean = Object.fromEntries(
    Object.entries(params).filter(([, v]) => v !== undefined && v !== null && v !== "")
  );
  const p = new URLSearchParams({ ...clean, timestamp: String(Date.now()) });
  const signature = signHmac(p.toString());
  p.append("signature", signature);

  const headers = { "X-KAPI-KEY": apiKey };
  let url = `${BASE_URL}${path}`;
  const init = { method, headers };
  if (method === "GET" || method === "DELETE") {
    url += `?${p.toString()}`;
  } else {
    headers["Content-Type"] = "application/x-www-form-urlencoded";
    init.body = p.toString();
  }

  const res = await fetch(url, init);
  const json = await res.json().catch(() => ({}));
  if (!res.ok || json.success === false) {
    const err = new Error(`Korbit API error ${res.status}`);
    err.status = res.status;              // 숫자 HTTP 상태 코드
    err.code = json?.error?.message;      // 심볼릭 코드, 예: "DUPLICATE_CLIENT_ORDER_ID"
    err.body = json;
    throw err;
  }
  return json.data ?? json;
}

실패 시 Korbit은 { "success": false, "error": { "code": <httpStatus>, "message": "<symbolic code>" } }를 반환합니다. 분기 판단에 쓰는 심볼릭 코드(EXCEED_TIME_WINDOW, DUPLICATE_CLIENT_ORDER_ID, NO_BALANCE 등)는 error.message이며, error.code가 아닙니다 — error.code는 숫자 HTTP 상태 코드가 반복된 값입니다. 최상위에는 심볼릭 값이 없습니다. 위 헬퍼는 이 심볼릭 코드를 err.code로 노출하므로 호출부는 그 값으로 분기하면 됩니다.

ED25519 헬퍼#

개인키는 PEM 문자열로 소스 외부에 보관합니다.

import crypto from "node:crypto";

const apiKey = process.env.KORBIT_API_KEY;
const privateKeyPem = process.env.KORBIT_ED25519_PRIVATE_KEY;

function signEd25519(encodedParams) {
  const sig = crypto.sign(null, Buffer.from(encodedParams), privateKeyPem);
  return sig.toString("base64");
}

URLSearchParams에 Base64 서명을 append 하면 URL 인코딩이 자동으로 적용됩니다.

주문 넣기#

POST /v2/orders에 symbol, side(buy/sell), orderType을 보냅니다. 주문 크기를 지정하는 필드는 주문 유형에 따라 다르며, 이 부분이 가장 흔한 실수 지점이므로 정확히 맞춰야 합니다:

즉, btc_krw를 50,000 KRW어치 시장가 매수할 때는 amt=50000을 보내고 qty와 price는 보내지 않습니다. amt는 해당 페어의 상대자산 단위입니다. 0.01 BTC 시장가 매도는 qty=0.01만 보내고 amt/price는 생략합니다. best(BBO) 주문은 추가로 timeInForce와 bestNth가 필요합니다.

clientOrderId([0-9a-zA-Z.:_-]{1,36} 형식)를 넣으면 멱등성이 보장됩니다. 같은 clientOrderId로 여러 번 요청해도 한 번만 처리되며, 이후 GET /v2/orders?clientOrderId=...로 조회할 수 있습니다. 주문이 성공하면 부여된 orderId가 반환되며, 주문의 나머지 상태는 후속 GET /v2/orders로 읽습니다(아래 참고). clientOrderId는 사실상 해제되지 않으므로, 서로 다른 주문에 같은 ID를 재사용하지 말고 신청마다 충돌에 강한 ID를 새로 발급해 영속화하세요 — 리질리언스 #1 참고.

주문 및 체결 읽기#

GET /v2/orders(orderId 또는 clientOrderId로 조회)는 체결 상태를 포함한 주문 정보를 반환합니다. 금액 필드는 문자열이므로 문자열/decimal로 유지하세요.

체결을 안전하게 다루려면 avgPrice가 없을 수 있다고 보고(필요하고 없을 때는 filledAmt / filledQty를 decimal로 계산해 도출하며, "미체결"은 평균가 없음으로 처리 — 절대 NaN이 되지 않게), 미체결 잔량은 qty - filledQty로 계산하되 음수가 되지 않게 합니다. partiallyFilled 주문은 filledQty가 qty보다 작으므로, 후속 동작은 원래 요청 수량이 아니라 filledQty/filledAmt 기준으로 사이징하세요.

잔고#

GET /v2/balance(선택적으로 currencies=btc,eth)는 자산별 객체 배열을 반환합니다. 모든 수량은 문자열입니다:

신규 주문은 balance가 아니라 available 기준으로 사이징하세요 — 그 차이는 이미 미체결 주문이나 출금에 묶여 있습니다.

REST 엔드포인트#

아래 표는 YAML 스펙의 그룹 순서대로 정리되어 있습니다. 각 엔드포인트의 필수 파라미터와 응답 스키마는 본 문서 하단에 링크된 그룹별 레퍼런스 파일에서 확인하세요.

시세#

주문#

자산#

가상자산 입금#

가상자산 출금#

원화 입출금#

기타#

주문 상태#

오류 코드#