Introduction

Open API 소개

이 문서는 코빗의 구 WebSocket API에 대해 설명하고 있습니다. 구 WebSocket API는 2025년 5월까지만 지원이 이루어지며 6월부터는 서비스가 종료될 예정이므로, 새로운 WebSocket API를 이용해 주시기를 부탁드립니다.

새로운 웹소켓 API는 구 웹소켓 API와 대부분 호환되나, 아래와 같은 차이점이 있습니다:

Public 타입과 Private 타입 메시지를 구독하는 웹소켓 분리
실시간으로 내 잔고의 변화를 확인할 수 있는 MyAsset 타입 추가
MyOrder, MyTrade 타입에 필드 추가
Private 타입 메시지 유실 방지

WebSocket API (Old)

웹소켓 연결하기

WebSocket API는 코빗 서버와 이용자 클라이언트 간의 양방향 통신을 위한 웹소켓 연결 인터페이스입니다. WebSocket API를 사용하면 코빗 가상자산 거래소의 실시간 정보를 가장 빠른 속도로 수신할 수 있습니다.

REST API를 사용할 경우에는 이용자가 HTTP 요청을 해서 응답을 받아야 비로소 정보를 알 수 있지만, WebSocket API를 사용할 경우에는 코빗 서버와 이용자 클라이언트 간 양방향 연결이 계속 이루어져 있어 시세 변동이나 주문 체결 등의 이벤트가 발생하면 코빗 서버에서 이용자 클라이언트로 실시간으로 정보를 지속적으로 제공합니다. 따라서, 시세나 주문, 체결 등의 실시간 정보를 빠르고 편리하게 수신하고자 한다면 REST API보다는 WebSocket API의 사용을 권장합니다.

WebSocket API에서 제공하는 데이터는 공개 정보인지, 개별 이용자만의 정보인지에 따라 Public 타입과 Private 타입으로 나눌 수 있으며, Public 타입 데이터는 별다른 인증 없이 수신할 수 있습니다. 반면, Private 타입 데이터를 수신하기 위해서는 웹소켓 연결 시 코빗 Open API 키 인증을 해야만 수신할 수 있습니다.

Public 타입 데이터는 웹소켓을 통한 데이터 구독 요청을 보내면, 요청 당시의 최신 데이터를 스냅샷 데이터로 바로 제공합니다. (스냅샷 데이터는 실시간 데이터가 아닙니다.) 스냅샷 데이터가 아닌 데이터는 모두 실시간 데이터입니다.

시세: Public 타입

현재가 ticker : 지정한 거래쌍의 스냅샷, 실시간 현재가를 제공합니다.
호가 orderbook : 지정한 거래쌍의 스냅샷, 실시간 호가를 제공합니다.
체결 trade : 지정한 거래쌍의 스냅샷, 실시간 체결 내역을 제공합니다.

주문: Private 타입

내 주문 myOrder : 내 주문에 관한 실시간 상태 변화 정보를 제공합니다.
내 체결 myTrade : 내 체결에 관한 실시간 체결 발생 정보를 제공합니다.

기본 URL

wss://ws-api.korbit.co.kr/v2/ws

인증하기

Public 타입 데이터(현재가, 호가, 체결)는 별다른 인증 없이 단순히 웹소켓 연결 후 구독 메시지를 보내는 것만으로 수신할 수 있습니다. 하지만, Private 타입 데이터(내 주문, 내 체결)는 웹소켓 연결 시 코빗 Open API 키를 이용한 인증을 거쳐야만 수신할 수 있습니다.

REST API의 인증 방법과 동일하게 웹소켓 연결 시 X-KAPI-KEY 헤더와 HMAC-SHA256 또는 ED25519 서명을 한 요청을 보내서 인증을 진행합니다. 즉, 요청 헤더에는 X-KAPI-KEY, URL 쿼리스트링에는 timestamp, signature 정보를 입력해야 합니다.

서명된 요청 보내기의 설명과 첨부하는 예시 코드를 참고해 주세요.

HMAC-SHA256 서명 구현 (Node.js)

// Node.js 구현 예제, 필요시 npm i ws 실행
import crypto from "crypto";
import WebSocket from "ws";

const apiKey = "XyAZ_apaUv9pg4ZyGzNHTxabfIDrWIRpPBgk5-olIuM"; // API 키
const apiSecret = "ZwKS2evdxj9j3Neir2s0UHAmpNFfo4a0iHawEElGCBs"; // HMAC-SHA256 비밀 키

const wsUrl = "wss://ws-api.korbit.co.kr/v2/ws"; // 기본 URL

// HMAC-SHA256 서명 생성
const createHmacSignature = (query) => {
  return crypto.createHmac("sha256", apiSecret).update(query, "utf-8").digest("hex");
};

const timestamp = Date.now(); // 현재 시각 타임스탬프(밀리세컨드)

const params = new URLSearchParams({
  timestamp: timestamp,
});

const signature = createHmacSignature(params.toString());

// 서명을 요청 변수에 추가
params.append("signature", signature);

// API 키를 요청 헤더에 추가하고 웹소켓 연결
const ws = new WebSocket(`${wsUrl}?${params.toString()}`, [], {
  headers: {
    "X-KAPI-KEY": apiKey,
  }
});

ws.on("open", () => {
  console.log("connected!");
  // 웹소켓 연결 후 메시지 구독 요청 전송
  ws.send(`[{"method":"subscribe","type":"ticker","symbols":["btc_krw","eth_krw"]}]`);
  ws.send(`[{"method":"subscribe","type":"myOrder","symbols":["btc_krw","eth_krw"]},{"method":"subscribe","type":"myTrade","symbols":["btc_krw","eth_krw"]}]`);
});

ws.on("error", (error) => {
  console.error(error);
});

ws.on("message", (event) => {
  const message = JSON.parse(event);
  console.log(message);
});

ws.on("close", () => {
  console.log("connection closed!");
});

요청 보내기

웹소켓이 연결된 후에는 어떤 타입의 데이터를 구독하겠다는 요청을 보내야만 합니다. WebSocket API에서는 구독 요청 메시지를 JSON 형식으로 전송하고, method, type, symbols를 각각 입력해야 합니다.

여러 개의 메시지를 한 번에 입력할 수 있으므로, 요청 메시지는 1개를 보낼 때에도 반드시 대괄호([])로 묶어서 보내야 합니다. (대소문자 구분에 유의해 주세요.)

[{"method":"subscribe","type":"ticker","symbols":["btc_krw","eth_krw"]}]
[{"method":"subscribe","type":"ticker","symbols":["btc_krw","eth_krw"]},[{"method":"subscribe","type":"orderbook","symbols":["btc_krw","eth_krw"]}]]

# 예시로 Node.js 환경에서 wscat을 사용합니다.
$ npm install -g wscat
$ wscat -c wss://ws-api.korbit.co.kr/v2
connected (press CTRL+C to quit)

# 웹소켓이 연결되면 데이터 구독 요청을 보냅니다.
> [{"method":"subscribe","type":"ticker","symbols":["btc_krw","eth_krw"]}]
< {"symbol":"btc_krw","timestamp":1730365099072,"type":"ticker","snapshot":true,"data":{"open":"100500000","high":"100651000","low":"100492000","close":"100650000","prevClose":"100497000","priceChange":"153000","priceChangePercent":"0.15","volume":"0.89102242","quoteVolume":"89632429.21566","bestAskPrice":"100651000","bestBidPrice":"100650000","lastTradedAt":1730356819663}}
< {"symbol":"eth_krw","timestamp":1730365099072,"type":"ticker","snapshot":true,"data":{"open":"4390000","high":"4390000","low":"4357000","close":"4357000","prevClose":"4456000","priceChange":"-99000","priceChangePercent":"-2.22","volume":"0.1702132","quoteVolume":"744416.83456","bestAskPrice":"4357000","bestBidPrice":"4324000","lastTradedAt":1730361789775}}
< {"symbol":"btc_krw","timestamp":1730365220489,"type":"ticker","data":{"open":"100501000","high":"100651000","low":"100501000","close":"100650000","prevClose":"100492000","priceChange":"158000","priceChangePercent":"0.16","volume":"0.81866504","quoteVolume":"82360867.25161","bestAskPrice":"100651000","bestBidPrice":"100650000","lastTradedAt":1730356819663}}

위 예시에서는 비트코인(btc_krw)과 이더리움(eth_krw) 거래쌍에 대해 현재가(ticker) 정보를 받고 싶다는 구독 요청을 보내면, 가장 먼저 스냅샷 데이터가 수신되고 이후 실시간 데이터가 계속해서 수신됨을 알 수 있습니다. 여러 거래쌍에 관한 정보를 받고 싶다면 위 예시와 같이 여러 거래쌍을 대괄호([])로 감싼 후 콤마(,)로 구분해 입력합니다.

구독할 때에는 method를 subscribe로, 해당 타입의 데이터를 더 이상 받고 싶지 않다면 method를 unsubscribe로 해서 구독을 해제할 수 있습니다.

각 타입마다의 구독 요청 메시지 및 응답 예시는 아래를 참조해 주세요.

현재가 (Ticker)

실시간 현재가 정보를 조회합니다.

요청 변수

method string 필수

고정 값 subscribe 또는 unsubscribe 입력

type string 필수

고정 값 ticker 입력

symbols array of strings 필수

조회하고자 하는 거래쌍의 심볼을 입력합니다.

예시

["btc_krw","eth_krw"]

응답

type string 필수

고정 값 ticker

timestamp number 필수

현재 서버 시간 (단위: Unix Timestamp (밀리초))

예시

1700000000000

symbol string 필수

거래쌍

예시

btc_krw

snapshot boolean

스냅샷 데이터 여부.
true - 구독 요청 직후 최초로 전송되는 메시지로서 요청 당시의 최신 정보를 전송합니다.
false 또는 null - 이벤트 발생에 따라 실시간으로 전송되는 메시지입니다.

data object 필수

open string 필수

최근 24시간 시가

예시

361922.23

high string 필수

최근 24시간 고가

예시

361922.23

low string 필수

최근 24시간 저가

예시

361922.23

close string 필수

최근 24시간 종가

예시

361922.23

prevClose string 필수

직전 24시간 종가

예시

261922.23

priceChange string 필수

직전 종가 대비 가격 변화량. prevClose - close으로 계산합니다.

예시

261922.23

priceChangePercent string 필수

직전 종가 대비 가격 변화율(단위: %). 100 * (prevClose - close) / prevClose으로 계산합니다.

예시

volume string 필수

최근 24시간 거래량(가상자산)

예시

100

quoteVolume string 필수

최근 24시간 거래대금(원화)

예시

1000000000

bestBidPrice string 필수

매수 1호가

예시

5000

bestAskPrice string 필수

매도 1호가

예시

6000

lastTradedAt number 필수

마지막 체결 시각 (단위: Unix Timestamp (밀리초))

예시

1700000000000

요청

[{"method":"subscribe","type":"ticker","symbols":["btc_krw","eth_krw"]}]

응답

{
  "type": "ticker",
  "timestamp": 1700000027754,
  "symbol": "btc_krw",
  "snapshot": true,
  "data": {
    "open": "94679000",
    "high": "111162000",
    "low": "93861000",
    "close": "99027000",
    "prevClose": "94679000",
    "priceChange": "4348000",
    "priceChangePercent": "4.59",
    "volume": "147.94385655",
    "quoteVolume": "14311735005.18033",
    "bestAskPrice": "99027000",
    "bestBidPrice": "99026000",
    "lastTradedAt": 1700000010022
  }
}

호가 (Orderbook)

호가 정보를 조회합니다. 최대 30호가까지 조회 가능합니다.

요청 변수

method string 필수

고정 값 subscribe 또는 unsubscribe 입력

type string 필수

고정 값 orderbook 입력

symbols array of strings 필수

조회하고자 하는 거래쌍의 심볼을 입력합니다.

예시

["btc_krw","eth_krw"]

응답

type string 필수

고정 값 orderbook

timestamp number 필수

현재 서버 시간 (단위: Unix Timestamp (밀리초))

예시

1700000000000

symbol string 필수

거래쌍

예시

btc_krw

snapshot boolean

data object 필수

timestamp number 필수

호가 정보의 기준 시각 (단위: Unix Timestamp (밀리초))

예시

1700000000000

bids array of object 필수

매수 호가 정보 (호가 내림차순 정렬)

price string 필수

매수호가

예시

250000

qty string 필수

매수잔량

예시

asks array of object 필수

매도 호가 정보 (호가 오름차순 정렬)

price string 필수

매도호가

예시

250000

qty string 필수

매도잔량

예시

요청

[{"method":"subscribe","type":"orderbook","symbols":["btc_krw"]}]

응답

{
  "type": "orderbook",
  "timestamp": 1700000006177,
  "symbol": "btc_krw",
  "snapshot": true,
  "data": {
    "timestamp": 1700000000234,
    "asks": [
      {
        "price": "99131000",
        "qty": "0.00456677"
      },
      {
        "price": "99132000",
        "qty": "0.00616665"
      },
      {
        "price": "99133000",
        "qty": "0.00808569"
      }
    ],
    "bids": [
      {
        "price": "99120000",
        "qty": "0.00363422"
      },
      {
        "price": "99119000",
        "qty": "0.00475577"
      },
      {
        "price": "99118000",
        "qty": "0.00389054"
      }
    ]
  }
}

체결 (Trade)

최근 체결 내역을 조회합니다.

요청 변수

method string 필수

고정 값 subscribe 또는 unsubscribe 입력

type string 필수

고정 값 trade 입력

symbols array of strings 필수

조회하고자 하는 거래쌍의 심볼을 입력합니다.

예시

["btc_krw","eth_krw"]

응답

type string 필수

고정 값 trade

timestamp number 필수

현재 서버 시간 (단위: Unix Timestamp (밀리초))

예시

1700000000000

symbol string 필수

거래쌍

예시

btc_krw

snapshot boolean

data array of object 필수

timestamp number 필수

체결 시각 (단위: Unix Timestamp (밀리초))

예시

1700000000000

price string 필수

체결 가격

예시

250000

qty string 필수

체결량

예시

isBuyerTaker boolean 필수

매수 주문으로 인해 발생한 체결인지 여부

예시

true

tradeId number 필수

거래 체결 ID (각 거래쌍마다 생성된 개별 거래 체결 건의 ID)

예시

1234

요청

[{"method":"subscribe","type":"trade","symbols":["btc_krw"]}]

응답

{
  "symbol": "btc_krw",
  "timestamp": 1700000005498,
  "type": "trade",
  "snapshot": true,
  "data": [
    {
      "timestamp": 1700000001239,
      "price": "98909000",
      "qty": "0.00146702",
      "isBuyerTaker": true,
      "tradeId": 123456
    }
  ]
}

내 주문 (MyOrder)

주문 상태 변화를 실시간으로 조회합니다.

필요 권한

주문 조회

요청 변수

method string 필수

고정 값 subscribe 또는 unsubscribe 입력

type string 필수

고정 값 myOrder 입력

symbols array of strings 필수

조회하고자 하는 거래쌍의 심볼을 입력합니다.

예시

["btc_krw","eth_krw"]

응답

type string 필수

고정 값 myOrder

timestamp number 필수

현재 서버 시간 (단위: Unix Timestamp (밀리초))

예시

1700000000000

symbol string 필수

거래쌍

예시

btc_krw

snapshot boolean

data array of object 필수

orderId number 필수

주문 ID

예시

1234

status string 필수

주문 상태

pending 주문 접수 대기중. 잔고가 부족한 경우 주문이 실패해 expired 상태로 전환될 수 있습니다.
open 전량 미체결
filled 전량 체결
canceled 전량 취소
partiallyFilled 부분 체결
partiallyFilledCanceled 부분 체결 후 잔량 취소
expired 주문 접수 실패

예시

partiallyFilled

side string 필수

매수, 매도 구분

buy 매수
sell 매도

예시

buy

price string

지정가 주문의 주문 가격(주문호가).
시장가 주문은 주문 가격이 표시되지 않습니다.

예시

5000

openQty string 필수

주문 잔량

예시

filledQty string 필수

체결량 (체결 수량)

예시

요청

[{"method":"subscribe","type":"myOrder","symbols":["btc_krw"]}]

응답

{
  "symbol": "btc_krw",
  "timestamp": 1700000000000,
  "type": "myOrder",
  "data": [
    {
      "orderId": 123456,
      "status": "partiallyFilled",
      "side": "buy",
      "price": "99017000",
      "openQty": "0.00206864",
      "filledQty": "0.53793136",
    }
  ]
}

내 체결 (MyTrade)

내 주문의 체결 내역을 실시간으로 조회힙니다.

필요 권한

주문 조회

요청 변수

method string 필수

고정 값 subscribe 또는 unsubscribe 입력

type string 필수

고정 값 myTrades 입력

symbols array of strings 필수

조회하고자 하는 거래쌍의 심볼을 입력합니다.

예시

["btc_krw","eth_krw"]

응답

type string 필수

고정 값 myTrades

timestamp number 필수

현재 서버 시간 (단위: Unix Timestamp (밀리초))

예시

1700000000000

symbol string 필수

거래쌍

예시

btc_krw

snapshot boolean

data array of object 필수

tradeId number 필수

거래 체결 ID (각 거래쌍마다 생성된 개별 거래 체결 건의 ID)

예시

1234

orderId number 필수

원주문 ID

예시

1234

side string 필수

매수, 매도 구분

buy 매수
sell 매도

예시

buy

price string 필수

체결 단가

예시

5000

qty string 필수

체결 수량

예시

isTaker boolean 필수

테이커(Taker) 체결 여부(Taker=true, Maker=false)

예시

true

요청

[{"method":"subscribe","type":"myTrade","symbols":["btc_krw"]}]

응답

{
  "symbol": "btc_krw",
  "timestamp": 1700000000000,
  "type": "myTrade",
  "data": [
    {
      "tradeId": 123456,
      "orderId": 456789,
      "side": "buy",
      "price": "99051000",
      "qty": "0.0013",
      "isTaker": true
    }
  ]
}