API

Introduction

About Open API

This is the API reference for Korbit's old WebSocket API. This API is scheduled to be removed in June 2025, so please consider migrating to the latest API, which can be found here.

The new API is mostly compatible with the old version, with those differences:

  • Separate endpoints for Public and Private types.
  • The MyAsset type which provides real-time updates on your balances.
  • Additional information in MyOrder and MyTrade types.
  • Messages are never dropped for Private types.

WebSocket API (Old)

Open a Connection

The WebSocket API is a WebSocket connection interface designed for bidirectional communication between the Korbit server and user clients. Using the WebSocket API allows you to receive real-time information from the Korbit cryptocurrency exchange at the fastest possible speed.

With the REST API, users must send an HTTP request to receive a response and retrieve information. However, with the WebSocket API, a persistent, bidirectional connection is maintained between the Korbit server and user client. As a result, when events such as price changes or order executions occur, information is continuously delivered from the Korbit server to the user client in real-time. Therefore, if you aim to receive real-time information on prices, orders, and trades quickly and conveniently, we recommend using the WebSocket API over the REST API.

Data provided by the WebSocket API is classified into Public and Private types, depending on whether it is public information or specific to individual users. Public type data can be received without any authentication. However, to receive Private type data, authentication with Korbit Open API keys is required when establishing the WebSocket connection.

For Public type data, sending a subscription request via WebSocket immediately provides the latest data at the time of the request as snapshot data. (Snapshot data is not real-time.) All non-snapshot data is real-time.

Quotation: Public Type


  • Get Tickers ticker : Provides snapshots and real-time current prices for a specified trading pair.
  • Get Orderbook orderbook : Provides snapshots and real-time order book data for a specified trading pair.
  • Get Trades trade : Provides snapshots and real-time trade history for a specified trading pair.

Trade: Private Type


  • My Orders myOrder : Provides real-time status updates on your orders.
  • My Trades myTrade : Provides real-time execution updates on your trades.

Base URL

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

Authentication

Public type data (Ticker, Orderbook, Trade) can be received simply by connecting to the WebSocket and sending a subscription message, without any authentication. However, to receive Private type data (My Order, My Trade), authentication using Korbit Open API keys is required upon establishing the WebSocket connection.

For authentication, as with the REST API, you need to send a request with an X-KAPI-KEY header and a signature generated using either HMAC-SHA256 or ED25519 during the WebSocket connection. Specifically, include the X-KAPI-KEY in the request header, and add timestamp and signature information to the URL query string.

Please refer to the Sign API Requests section and the attached example code for more details.

HMAC-SHA256 Signature Example (Node.js)

// Node.js, npm i ws
import crypto from "crypto";
import WebSocket from "ws";

const apiKey = "XyAZ_apaUv9pg4ZyGzNHTxabfIDrWIRpPBgk5-olIuM"; // API Key
const apiSecret = "ZwKS2evdxj9j3Neir2s0UHAmpNFfo4a0iHawEElGCBs"; // HMAC-SHA256 Secret Key

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

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

const timestamp = Date.now(); // Timestamp (ms)

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

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

// Add Signature to params
params.append("signature", signature);

// Add API Key to the header, Open a WebSocket connection
const ws = new WebSocket(`${wsUrl}?${params.toString()}`, [], {
  headers: {
    "X-KAPI-KEY": apiKey,
  }
});

ws.on("open", () => {
  console.log("connected!");
  // Send messages to subscribe
  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!");
});

Send Requests

After the WebSocket connection is established, you must send a request indicating which type of data you wish to subscribe to. In the WebSocket API, subscription request messages are sent in JSON format, with method, type, and symbols specified accordingly.

Since multiple messages can be included at once, even when sending a single request message, it must be enclosed in square brackets []. (Please note that case sensitivity applies.)

[{"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"]}]]
# Using wscat in a Node.js environment
$ npm install -g wscat
$ wscat -c wss://ws-api.korbit.co.kr/v2
connected (press CTRL+C to quit)

# Once the WebSocket connection is established, send a data subscription request
> [{"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}}

In the example, a subscription request is sent to receive current price (ticker) information for the Bitcoin (btc_krw) and Ethereum (eth_krw) trading pairs. First, snapshot data is received, followed by a continuous stream of real-time data. If you want to receive information for multiple trading pairs, enclose the pairs in square brackets [] and separate them with commas ,, as shown in the example above.

To subscribe, set method to subscribe; to stop receiving a specific type of data, set method to unsubscribe to cancel the subscription.

Refer below for example subscription request and response messages for each type.

Ticker

Streams latest pricing information for a symbol.

Request Parameters

method string Mandatory

Set to subscribe or unsubscribe

type string Mandatory

Set to ticker

symbols array of strings Mandatory

Enter the symbols of the trading pairs you want to query.

Example

["btc_krw","eth_krw"]

Response

type string Mandatory

Fixed value ticker

timestamp number Mandatory

Server time (unix timestamp, in milliseconds)

Example

1700000000000

symbol string Mandatory

Trading pair symbol

Example

btc_krw

snapshot boolean

Whether the data is a snapshot or a real-time data.
true - The data is a latest snapshot and not a real-time data. Sent as the first message on subscription.
false or null - The data is from a real-time trade.

data object Mandatory
open string Mandatory

Open price (24H)

Example

361922.23

high string Mandatory

High price (24H)

Example

361922.23

low string Mandatory

Low price (24H)

Example

361922.23

close string Mandatory

Last price (24H)

Example

361922.23

prevClose string Mandatory

Previous close price (24H)

Example

261922.23

priceChange string Mandatory

changed price. prevClose - close

Example

261922.23

priceChangePercent string Mandatory

changed price percent. 100 * (prevClose - close) / prevClose

Example

10

volume string Mandatory

Trading volume (Base, 24H)

Example

100

quoteVolume string Mandatory

Trading volume (Quote/Counter, 24H)

Example

1000000000

bestBidPrice string Mandatory

Best bid price

Example

5000

bestAskPrice string Mandatory

Best ask price

Example

6000

lastTradedAt number Mandatory

Last traded timestamp (unix timestamp, in milliseconds)

Example

1700000000000

Request

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

Response

{
  "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

Streams orderbook data for a symbol. Up to 30 prices are available for each side.

Request Parameters

method string Mandatory

Set to subscribe or unsubscribe

type string Mandatory

Set to orderbook

symbols array of strings Mandatory

Enter the symbols of the trading pairs you want to query.

Example

["btc_krw","eth_krw"]

Response

type string Mandatory

Fixed value orderbook

timestamp number Mandatory

Server time (unix timestamp, in milliseconds)

Example

1700000000000

symbol string Mandatory

Trading pair symbol

Example

btc_krw

snapshot boolean

Whether the data is a snapshot or a real-time data.
true - The data is a latest snapshot and not a real-time data. Sent as the first message on subscription.
false or null - The data is from a real-time trade.

data object Mandatory
timestamp number Mandatory

Timestamp of the orderbook data (unix timestamp, in milliseconds)

Example

1700000000000

bids array of object Mandatory

bids

price string Mandatory

price

Example

250000

qty string Mandatory

quantity

Example

10

asks array of object Mandatory

asks

price string Mandatory

price

Example

250000

qty string Mandatory

quantity

Example

10

Request

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

Response

{
  "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

Streams real-time trades.

Request Parameters

method string Mandatory

Set to subscribe or unsubscribe

type string Mandatory

Set to trade

symbols array of strings Mandatory

Enter the symbols of the trading pairs you want to query.

Example

["btc_krw","eth_krw"]

Response

type string Mandatory

Fixed value trade

timestamp number Mandatory

Server time (unix timestamp, in milliseconds)

Example

1700000000000

symbol string Mandatory

Trading pair symbol

Example

btc_krw

snapshot boolean

Whether the data is a snapshot or a real-time data.
true - The data is a latest snapshot and not a real-time data. Sent as the first message on subscription.
false or null - The data is from a real-time trade.

data array of object Mandatory
timestamp number Mandatory

Time of the trade (unix timestamp, in milliseconds)

Example

1700000000000

price string Mandatory

trade price

Example

250000

qty string Mandatory

trade quantity

Example

10

isBuyerTaker boolean Mandatory

whether the taker is the buyer.

Example

true

tradeId number Mandatory

trade ID (unique for each currency pair)

Example

1234

Request

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

Response

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

My Order

Streams the changes in my orders.

Required Permissions

Read Orders

Request Parameters

method string Mandatory

Set to subscribe or unsubscribe

type string Mandatory

Set to myOrder

symbols array of strings Mandatory

Enter the symbols of the trading pairs you want to query.

Example

["btc_krw","eth_krw"]

Response

type string Mandatory

Fixed value myOrder

timestamp number Mandatory

Server time (unix timestamp, in milliseconds)

Example

1700000000000

symbol string Mandatory

Trading pair symbol

Example

btc_krw

snapshot boolean

Whether the data is a snapshot or a real-time data.
true - The data is a latest snapshot and not a real-time data. Sent as the first message on subscription.
false or null - The data is from a real-time trade.

data array of object Mandatory
orderId number Mandatory

order ID

Example

1234

status string Mandatory

Order status

  • pending Order pending. If the balance is insufficient, the order may fail and change to the expired status.
  • open Fully unfilled
  • filled Fully executed
  • canceled Fully canceled
  • partiallyFilled Partially filled
  • partiallyFilledCanceled Partially filled and remaining amount canceled
  • expired Order submission failed
Example

partiallyFilled

side string Mandatory
  • buy
  • sell
Example

buy

price string

Order price (limit order only. no price for market order.)

Example

5000

openQty string Mandatory

open quantity

Example

10

filledQty string Mandatory

filled quantity

Example

10

Request

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

Response

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

My Trade

Streams trades on my orders.

Required Permissions

Read Orders

Request Parameters

method string Mandatory

Set to subscribe or unsubscribe

type string Mandatory

Set to myTrades

symbols array of strings Mandatory

Enter the symbols of the trading pairs you want to query.

Example

["btc_krw","eth_krw"]

Response

type string Mandatory

Fixed value myTrades

timestamp number Mandatory

Server time (unix timestamp, in milliseconds)

Example

1700000000000

symbol string Mandatory

Trading pair symbol

Example

btc_krw

snapshot boolean

Whether the data is a snapshot or a real-time data.
true - The data is a latest snapshot and not a real-time data. Sent as the first message on subscription.
false or null - The data is from a real-time trade.

data array of object Mandatory
tradeId number Mandatory

trade ID

Example

1234

orderId number Mandatory

order ID

Example

1234

side string Mandatory
  • buy
  • sell
Example

buy

price string Mandatory

price

Example

5000

qty string Mandatory

quantity

Example

10

isTaker boolean Mandatory

taker=true, maker=false

Example

true

Request

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

Response

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