Introduction

Korbit provides a RESTful API for developers.

API call rate limit

To ensure the quality and reliability of our API service, the API calls are limited to a certain rate threshold. Creating / refreshing access token calls are limited to 60 calls per 60 minutes; Ticker calls are limited to 60 calls per 60 seconds; All except AccessToken and Ticker, Cancel order calls combined, are limited to 12 calls per 1 second.

Authentication

Implement user authentication to receive and refresh access tokens, which must be included in API requests for user-specific actions.

Introduction

Prior to using Korbit API, you need to authenticate a user. As Korbit API provides OAuth 2.0 interface, you get an access token after a successful authentication. For each API request, you need to set Authorization HTTP header with the access token.

API Keys and Secrets

You need to request an API key and secret to use Korbit API. All Korbit users can get the API key through the Korbit website. You can sign in into your Korbit account by direct authentication API call, which requires username and password in the body of the POST request to get an access token (and a refresh token). In this document, <CLIENT ID> denotes an API key, and <CLIENT SECRET> denotes a corresponding API secret.

Access Token

Instead of passing username and password for each API request, you pass the access token you got after the successful authentication. Before sending the API request to the server, you need to set the Authorization HTTP header with the access token in the following format.

Bearer 12094519051ewhdsofhsoy2ghewekfhse

Because the access token is expired in an hour, you need to refresh it using the refresh token you got after the successful authentication.

Scope

Access Token have Scopes which are permissions for API functions. Scope types include VIEW, TRADE and WITHDRAWAL, and one access token can have multiple scopes. All APIs except public APIs verify scope of the Access Token, and it can be executed if the Access Token has the scope required by the API. The scope of the Access Token is derived from the scope of the API key used to issue the access token; this can be set when creating an API key through the Korbit website.

Nonce

APIs that start with v1/user access or modify resource of a user on the server. So you need to provide an access token and nonce for each request. You can get the access token after a successful authentication. For the nonce, you can specify a monotonously increasing number to it. To allow only one client to send API requests and to process a request only once, Korbit API server processes clients' requests only if the nonce value monotonously increases. For GET requests, you don't need to provide a nonce. For POST requests, you can provide the nonce in the body with the other parameters.
NOTICE: Nonce can be omitted with “buy order”, “sell order”, and “cancel order request”. If omitted, it is considered as a new request.

Direct Authentication

Direct authentication embeds API Key and Secret issued from Korbit website.

Access Token, Refresh Token

Request

curl -D - -X POST -d "client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&grant_type=client_credentials" https://api.korbit.co.kr/v1/oauth2/access_token

Response

{
  "token_type":"Bearer",
  "access_token":"1t1LgTslDrGznxPxhYz7RldsNVIbnEK",
  "expires_in":3600,
  "scope": "VIEW,TRADE",
  "refresh_token":"vn5xoOf4PzckgnqjQSL9Sb3KxWJvYtm"
}

POST https://api.korbit.co.kr/v1/oauth2/access_token

You can get both access token and refresh token after setting grant_type with 'client_credentials' and POST request to v1/oauth2/access_token. The grant_type 'password' is no longer supported after May 3, 2021.

Refreshing Access Token

Request

curl -D - -X POST -d "client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&refresh_token=$REFRESH_TOKEN&grant_type=refresh_token" https://api.korbit.co.kr/v1/oauth2/access_token

Response

{
  "token_type":"Bearer",
  "access_token":"IuqEWTK09eCLThRCZZSALA0oXC8EI7s",
  "expires_in":3600,
  "scope": "VIEW,TRADE",
  "refresh_token":"vn5xoOf4Pzckgn4jQSL9Sb3KxWJvYtm"
}

POST https://api.korbit.co.kr/v1/oauth2/access_token

Because the access token is expired within an hour, you need to refresh your access token before the expiration using the refresh token. In this case you can POST a request to v1/oauth2/access_token after setting grant_type to 'refresh_token'.

OAuth 2.0 References

The Korbit API complies with the OAuth 2.0 specification. The following are some OAuth 2.0 resources.

Explanation of OAuth 2.0

Explanation of OAuth 2.0 Video 1

Explanation of OAuth 2.0 Video 2

Explanation of OAuth 2.0 Video 3

Explanation of OAuth 2.0 Video 4

Using OAuth2.0 as a web service consumer

(Google) OAuth 2.0 Overview

(Google) Example of OAuth 2.0 in a mobile app

Using OAuth2.0 as a web service provider

(Book) Getting Started with OAuth 2.0 - Ryan Boyd

(Google I/O 2012) OAuth 2.0 for Identity and Data Access - Ryan Boyd

Public

Check the current status of the market by listing open and filled orders.

Ticker

Request

curl -D - "https://api.korbit.co.kr/v1/ticker?currency_pair=$CURRENCY_PAIR"

Response

{
  "timestamp": 1389678052000,
  "last": "569000"
}

`GET https://api.korbit.co.kr/v1/ticker

PARAMETERS

Parameter	Default	Description
currency_pair	btc_krw	The type of trading currency pair of which information you want to query for. We support currency pair that exists in [Constants], but the others.

ATTRIBUTES

Name	Description
timestamp	Unix timestamp in milliseconds of the last filled order.
last	Price of the last filled order.

Detailed Ticker

Request

curl -D - "https://api.korbit.co.kr/v1/ticker/detailed?currency_pair=$CURRENCY_PAIR"

Response

{
  "timestamp": 1558590089274,
  "last": "9198500",
  "open": "9500000",
  "bid": "9192500",
  "ask": "9198000",
  "low": "9171500",
  "high": "9599000",
  "volume": "1539.18571988",
  "change": "-301500",
  "changePercent": "-3.17"
}

GET https://api.korbit.co.kr/v1/ticker/detailed

PARAMETERS

Parameter	Default	Description
currency_pair	btc_krw	The type of trading currency pair of which information you want to query for. We support currency pair that exists in [Constants], but the others.

ATTRIBUTES

Name	Description
timestamp	Unix timestamp in milliseconds of the last filled order.
last	Price of the last filled order.
open	First price in 24 hours.
bid	Best bid price.
ask	Best ask price.
low	Lowest price within the last 24 hours.
high	Highest price within the last 24 hours.
volume	Transaction volume within the last 24 hours.
change	The change in the last price from the oepn price.
changePercent	The rate of change in the last price from the open price.

Detailed Ticker of All Market

Request

curl -D - "https://api.korbit.co.kr/v1/ticker/detailed/all"

Response

{
  "bch_krw": {
    "timestamp": 1559285555322,
    "last": "513000",
    "open": "523900",
    "bid": "512100",
    "ask": "513350",
    "low": "476200",
    "high": "540900",
    "volume": "4477.20611753",
    "change": "-10900",
    "changePercent": "-2.08"
  },
  "fet_krw": {
    "timestamp": 1559285607258,
    ...
  },
  ...
}

GET https://api.korbit.co.kr/v1/ticker/detailed/all

ATTRIBUTES

Name	Description
currency_pair	The type of trading currency pair of Exchange. (btc_krw, eth_krw, ...)
timestamp	Unix timestamp in milliseconds of the last filled order.
last	Price of the last filled order.
open	First price in 24 hours.
bid	Best bid price.
ask	Best ask price.
low	Lowest price within the last 24 hours.
high	Highest price within the last 24 hours.
volume	Transaction volume within the last 24 hours.
change	The change in the last price from the oepn price.
changePercent	The rate of change in the last price from the open price.

Orderbook

Request

curl -D - "https://api.korbit.co.kr/v1/orderbook?currency_pair=$CURRENCY_PAIR"

Response

{
  "timestamp" : 1386135077000,
  "bids" : [["1100000", "0.0103918", "1"], ["1000000", "0.01000000", "1"], ... ],
  "asks" : [["569000", "0.50000000", "1"], ["568500", "2.00000000", "1"], ... ]
}

GET https://api.korbit.co.kr/v1/orderbook

PARAMETERS

Parameter	Default	Description
currency_pair	btc_krw	The type of trading currency pair of which information you want to query for. We support currency pair that exists in [Constants], but the others.

ATTRIBUTES

Name	Description
timestamp	Unix timestamp in milliseconds of the last placed order.
asks	An array containing a list of bid prices. Each order has two elements: price and the unfilled amount. The third element is deprecated and is always 1.
bids	An array containing a list of ask prices. Each order has two elements: price and the unfilled amount. The third element is deprecated and is always 1.

List of Filled Orders

Request

curl -D - "https://api.korbit.co.kr/v1/transactions?currency_pair=$CURRENCY_PAIR"

Response

[
  {"timestamp" : 1389678052000, "tid" : "22546", "price" : "569000", "amount" : "0.01000000", "type" : "buy"},
  {"timestamp" : 1389678017000, "tid" : "22545", "price" : "580000", "amount" : "0.01000000", "type" : "sell"},
  {"timestamp" : 1389462921000, "tid" : "22544", "price" : "569000", "amount" : "0.16348000", "type" : "buy"},
  {"timestamp" : 1389462921000, "tid" : "22543", "price" : "570000", "amount" : "0.20000000", "type" : "sell"},
  {"timestamp" : 1389462920000, "tid" : "22542", "price" : "578000", "amount" : "0.33652000", "type" : "sell"},
  ...
]

GET https://api.korbit.co.kr/v1/transactions

PARAMETERS

Parameter	Default	Description
currency_pair	btc_krw	The type of trading currency pair of which information you want to query for. We support currency pair that exists in [Constants], but the others.
time	hour	The time period you want to query. If this parameter is specified as minute, it queries data within the last minute, hour means the last hour, day means the last 24 hours.

ATTRIBUTES

Name	Description
timestamp	Timestamp of last filled order.
tid	Unique ID that identifies the transaction.
price	Transaction price.
amount	Transaction amount.
type	Side of the order that is filled by the taker.

Constants (Deprecated)

Request

curl -D - "https://api.korbit.co.kr/v1/constants"

Response

{
  "exchange": {
    "btc_krw": {
      "tick_size": 500,
      "min_price": 1000,
      "max_price": 100000000,
      "order_min_size": 0.00100000,
      "order_max_size": 100.00000000
    },
    "eth_krw": {
      "tick_size": 50,
      "min_price": 1000,
      "max_price": 100000000,
      "order_min_size": 0.01000000,
      "order_max_size": 1000.00000000
    },
    ...
  }
}

GET https://api.korbit.co.kr/v1/constants

You can get constant values such as tick_size rates and minimum amount to trade, etc. The API is no longer supported after April 28, 2021.

• For detailed information on Tick Size and Max./Min. Order Quantity, please follow our FAQ link given below : [link]
• For detailed information on Deposit/Withdrawal Fees and Min. Withdrawal Amount, please follow our FAQ link given below : [link]

ATTRIBUTES

Name	Description
exchange	Exchange constants
currency_pair	The type of trading currency pair of Exchange. (btc_krw, eth_krw, ...)
tick_size	order unit size.
min_price	Minimum price for an order.
max_price	Maximum price for an order.
order_min_size	Minimum amount for placing an order.
order_max_size	Maximum amount for placing an order.

Public - Websocket

Websocket Push Server : You can subscribe and get data such as Ticker, Orderbook, Transaction

Connect

Connect to the pushserver.
If your connect request is closed from the server with Blacklist IP CloseReason warning message, Please ask this issue to info@korbit.co.kr. If duplicate error requests are accumulated, the client IP might be registered in the blacklist.

Request

wscat -c  "wss://ws2.korbit.co.kr/v1/user/push"

Response

{
  "accessToken": null,
  "timestamp": 1558590089274,
  "event": "korbit:connected",
  "data": {}
}

WS CONNECT wss://ws2.korbit.co.kr/v1/user/push

Close

Close the connection to the pushserver.
If you have any channel subscribed, all channels would be unsubscribed automatically from the server when closing socket.

Request

wscat -c  "wss://ws2.korbit.co.kr/v1/user/push"

CTRL + C to close

Response

CloseReason.Codes.NORMAL(1000) | "client socket is closed..."

WS CLOSE wss://ws2.korbit.co.kr/v1/user/push

Subscribe

Subscribe to channels(topic[:coin]) of the pushserver to receive data such as Ticker, Orderbook, Transaction

Request

wscat -c  "wss://ws2.korbit.co.kr/v1/user/push"

{
  "accessToken": null,
  "timestamp": 1558590089274,
  "event": "korbit:subscribe",
  "data": {
      "channels": ["ticker:btc_krw,eth_krw,xrp_krw", "orderbook:btc_krw,eth_krw,xrp_krw", "transaction:btc_krw,eth_krw,xrp_krw"]
  }
}

Response

(echo subscription request message as response in success)

{
  "accessToken": null,
  "timestamp": 1558590089274,
  "event": "korbit:subscribe",
  "data": {
      "channels": ["ticker:btc_krw,eth_krw,xrp_krw", "orderbook:btc_krw,eth_krw,xrp_krw", "transaction:btc_krw,eth_krw,xrp_krw"]
  }
}

(return error response message in failure)
If duplicate error requests are accumulated, the client IP might be registered in the blacklist. In this case, understand that you might not receive any response from the server.

{
  "accessToken": null,
  "timestamp": 1558590089274,
  "event": "korbit:error",
  "data": {
      "request_event": "korbit:subscribe",
      "err_message": "subscription channels info is not valid | unknown topic error : xxx"
  }
}

WS REQUEST wss://ws2.korbit.co.kr/v1/user/push

MESSAGE

Field Name	Example Value	Description
accessToken	null	Authentication Token String value
timestamp	1389678052000	UTC LocalDateTime Timestamp Long value
event	"korbit:subscribe"	Requesst event String value (subscribe, unsubscribe)
data	channels	Request meta data like channels or push data object value

Unsubscribe

Unsubscribe to channels(topic[:coin]) of the pushserver to receive data such as Ticker, Orderbook, Transaction
If you want to release a socket session after an unsubscription request, wait and close the client socket until receiving the unsubscription success response from the server.

Request

wscat -c  "wss://ws2.korbit.co.kr/v1/user/push"

{
  "accessToken": null,
  "timestamp": 1558590089274,
  "event": "korbit:unsubscribe",
  "data": {
      "channels": ["ticker:btc_krw,eth_krw,xrp_krw", "orderbook:btc_krw,eth_krw,xrp_krw", "transaction:btc_krw,eth_krw,xrp_krw"]
  }
}

Response

(echo unsubscription request message as response in success)

{
  "accessToken": null,
  "timestamp": 1558590089274,
  "event": "korbit:unsubscribe",
  "data": {
      "channels": ["ticker:btc_krw,eth_krw,xrp_krw", "orderbook:btc_krw,eth_krw,xrp_krw", "transaction:btc_krw,eth_krw,xrp_krw"]
  }
}

(return error response message in failure)
If duplicate error requests are accumulated, the client IP might be registered in the blacklist. In this case, understand that you might not receive any response from the server.

{
  "accessToken": null,
  "timestamp": 1558590089274,
  "event": "korbit:error",
  "data": {
      "request_event": "korbit:unsubscribe",
      "err_message": "subscription channels info is not valid | unknown topic error : xxx"
  }
}

WS REQUEST wss://ws2.korbit.co.kr/v1/user/push

MESSAGE

Field Name	Example Value	Description
accessToken	null	Authentication Token String value
timestamp	1389678052000	UTC LocalDateTime Timestamp Long value
event	"korbit:unsubscribe"	Requesst event String value (subscribe, unsubscribe)
data	channels	Request meta data like channels or push data object value

Channel List

Response

ticker

{
  "accessToken": null,
  "event": "korbit:push-ticker",
  "timestamp" : 1389678052000,
  "data":
    {
      "channel": "ticker",
      "currency_pair": "btc_krw",
      "timestamp": 1558590089274,
      "last": "9198500.1235789"
      "open": "9500000.3445783",
      "bid": "9192500.4578344",
      "ask": "9198000.32148556",
      "low": "9171500.23785685",
      "high": "9599000.34876458",
      "volume": "1539.18571988",
      "change": "-301500.234578934"
  }
}

orderbook

{
  "accessToken": null,
  "event": "korbit:push-orderbook",
  "timestamp" : 1389678052000,
  "data":
  {
    "channel": "orderbook",
    "currency_pair": "btc_krw",
    "timestamp" : 1386135077000,
    "bids" : [{"price": "1100000,2375876", "amount": "0.0103918"}, {"price": "1000000.3478764", "amount": "0.012"}],
    "asks" : [{"price": "569000.3467895", "amount": "0.50000000"}, {"price": "568500.7658432", "amount": "2.003"}]

  }
}

transaction

{
  "accessToken": null,
  "event": "korbit:push-transaction",
  "timestamp" : 1389678052000,
  "data":
  {
    "channel": "transaction",
    "currency_pair": "btc_krw",
    "timestamp" : 1389678052000,
    "price" : "569000.7654835",
    "amount" : "0.01000001",
    "taker" : "buy"
  }
}

Channel names are case sensitive.

Name	Description
ticker	Market status
orderbook	Orderbook
transaction	Transactions

Common	Description
accessToken	Access Token
event	Channel ID
timestamp	Timestamp of the requested time

ticker.data	Description
channel	Subscribe channel info
currency_pair	Currency pair
timestamp	Timestamp when the data was created
last	Closing price
open	Opening price
bid	Last bid price
ask	Last ask price
low	Low price
high	High price
volume	Trading volume
change	Change price

orderbook.data	Description
channel	Subscribe channel info
currency_pair	Currency pair
timestamp	Timestamp when the data was created
bids	Bid prices
asks	Ask Prices

transaction.data	Description
channel	Subscribe channel info
currency_pair	Currency pair
timestamp	Timestamp when the data was created
price	Trade price
amount	Trade asset amounts
taker	Sell/Buy

Request Format: channel_name[:currency_pair,...],channel_name[:currency_pair,...],...

If currency_pair parameter is ommitted, you can receive data for all currency pairs.

Ping

Most of modern web socket libraries support rfc6455 protocol. Please refer to the document of the library you’re using. The pushserver could send websocket Ping message frame(rfc6455) to clients for connection heartbeat check and client also could send to the server for heartbeat check : A ping is just a regular frame, but it's a control frame. Pings have an opcode of 0x9.

Ping message reference URL	rfc6455
Ping message reference URL	rfc6455

Request

wscat -c  "wss://ws2.korbit.co.kr/v1/user/push"

rfc6455 websocket ping message frame

Response

rfc6455 websocket pong message frame

WS REQUEST wss://ws2.korbit.co.kr/v1/user/push

MESSAGE

Ping message frame(rfc6455)

Pong

Most of modern web socket libraries support rfc6455 protocol. Please refer to the document of the library you’re using. The client should send Pong message frame(rfc6455) when receiving Ping message frame from the server and the server will send Pong message frame when it receives Ping message frame from clients : A pong is just a regular frame, but it's a control frame. Pongs have an opcode of 0xA.

Pong message reference URL	rfc6455
Pong message reference URL	rfc6455

Request

wscat -c  "wss://ws2.korbit.co.kr/v1/user/push"

rfc6455 websocket pong message frame

Response

none

WS REQUEST wss://ws2.korbit.co.kr/v1/user/push

MESSAGE

Pong message frame(rfc6455)

Private - General

Query user informations or balances, etc.

User Balances

Request

curl -D - -H "Authorization: Bearer $ACCESS_TOKEN" https://api.korbit.co.kr/v1/user/balances

Response

{
  "krw" : {
      "available" : "123000",
      "trade_in_use" : "13000",
      "withdrawal_in_use" : "0"
  },
  "btc" : {
      "available" : "1.50200000",
      "trade_in_use" : "0.42000000",
      "withdrawal_in_use" : "0.50280000",
      "avg_price": "7115500",
      "avg_price_updated_at": 1528944850000
  },
  "eth" : {
      "available" : "4.80200000",
      "trade_in_use" : "1.23238000",
      "withdrawal_in_use" : "0.00000000",
      "avg_price": "529000",
      "avg_price_updated_at": 1528944250000
  },
  "etc" : {
      "available" : "10.00000000",
      "trade_in_use" : "2.00000000",
      "withdrawal_in_use" : "0.00000000",
      "avg_price": "14770",
      "avg_price_updated_at": 1528945850000
  },
  "xrp" : {
      "available" : "134524.657899",
      "trade_in_use" : "2332.000000",
      "withdrawal_in_use" : "0.000000",
      "avg_price": "594",
      "avg_price_updated_at": 1528944340000
  }
  ...
}

GET https://api.korbit.co.kr/v1/user/balances

You can retrieve the balances and stats for each currency. This API endpoint requires the VIEW scope.

ATTRIBUTES

Name	Description
available	The amount of funds you can use.
trade_in_use	The amount of funds that are being used in trade.
withdrawal_in_use	The amount of funds that are being processed for withdrawal.
avg_price	The break even price in krw for coin.
avg_price_updated_at	The timestamp that the break even price is updated.

Transfer Account Info

Request

curl -D - -H "Authorization: Bearer $ACCESS_TOKEN" https://api.korbit.co.kr/v1/user/accounts

Response

{
  "deposit": {
    "btc": {
      "address" :"3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy"
    },
    "etc": {
      "address" :"0x123f681646d4a755815f9cb19e1acc8565a0c2aa"
    },
    "eth": {
      "address" :"0x123f681646d4a755815f9cb19e1acc8565a0c2ac"
    },
    "xrp": {
      "address" : "rMmTCjGFRWPz8S2zAUUoNVSQHxtRQD4eCx",
      "destination_tag" : "100022001"
    },
    "ltc": {
      "address": "MBRQmAR24h4RXZwMXmVjDBDdQZhQ2LAnjH"
    },
    ...
  },
  "withdrawal": {
    ...
  }
}

GET https://api.korbit.co.kr/v1/user/accounts

This API endpoint requires the VIEW scope.

ATTRIBUTES

Name	Description
address	The address of your wallet.
destination_tag	Destination tag used in XRP, XLM, EOS transactions. Only shows if exist.

Trading Volume and Fees

Request

curl -D - -H "Authorization: Bearer $ACCESS_TOKEN" "https://api.korbit.co.kr/v1/user/volume?currency_pair=$CURRENCY_PAIR"

Response

{
  "btc_krw": {
    "volume" : "17570000",
    "maker_fee" : "0.00100000",
    "taker_fee" : "0.00200000"
  },
  "eth_krw": {
    "volume" : "0",
    "maker_fee" : "0.00100000",
    "taker_fee" : "0.00200000"
  },
  "etc_krw": {
    "volume" : "6570000",
    "maker_fee" : "0.00100000",
    "taker_fee" : "0.00200000"
  },
  "total_volume" : "24140000",
  "timestamp" : 1386418990000
}

GET https://api.korbit.co.kr/v1/user/volume

To act in line with our newly adopted trading fee policy, we are going to provide API for trading volumes of users in BTC, ETH, ETC, XRP, BCH exchanges. Trading volumes and fee rates are calculated at an every exact 24 hour interval. This API endpoint requires the VIEW scope.

PARAMETERS

Parameter	Default	Description
currency_pair	all	The type of exchange of which trading volume and trading fee rates you want to query for. You can specify name of currency pair or all in the parameter and each indicates requesting for trading volumes and trading fee rates in exchanges.

ATTRIBUTES

Name	Description
currency_pair	The type of currency corresponding to the trading volume and trading fee rates.
volume	User's trading volume in the corresponding exchange during the last 30 days in KRW.
maker_fee	The rate of trading fee for maker in basis points(BPS).
taker_fee	The rate of trading fee for taker in basis points(BPS).
total_volume	User's total trading volume of all exchanges in KRW.
timestamp	Unix timestamp in milliseconds of the last time when trading volume and fees are calculated on an hourly basis.

Private - Trading

Place an order. List user's open and filled orders.

Place a Bid Order

Request

curl -D - -X POST -H "Authorization: Bearer $ACCESS_TOKEN" -d "currency_pair=$CURRENCY_PAIR&type=$TYPE&price=$PRICE&coin_amount=$COIN_AMOUNT&nonce=$NONCE&post_only=true" https://api.korbit.co.kr/v1/user/orders/buy

Request (Without nonce)

curl -D - -X POST -H "Authorization: Bearer $ACCESS_TOKEN" -d "currency_pair=$CURRENCY_PAIR&type=$TYPE&price=$PRICE&coin_amount=$COIN_AMOUNT&post_only=true" https://api.korbit.co.kr/v1/user/orders/buy

Response

{
  "orderId":"58738",
  "status":"success",
  "currency_pair":"btc_krw"
}

POST https://api.korbit.co.kr/v1/user/orders/buy

This API endpoint requires the TRADE scope.

PARAMETERS

Parameter	Description
currency_pair	The type of trading currency pair of which information you want to query for. We support currency pair that exists in [Constants], but the others.
type	The type of order. Specify 'limit' to place an order with a specific price you want. Specify 'market' to place an order to fill with the market price.
price	The price. This parameter is valid only for 'limit' order. Should be set with reference in [Constants].
coin_amount	The amount of trading currency you want to buy. When the order type is 'limit' order, it will place a buy order with a price specified in the 'price' parameter. When the order type is ‘market' order, 'price' and 'coin_amount' parameters should not be used.
fiat_amount	The amount you want to spend to buy the trading currency at market price. This parameter is only valid when the order type is 'market' order; When placing market bid orders, 'fiat_amount' should be used instead of 'price' and 'coin_amount' parameters.
nonce	[optional] in order to avoid duplicated request. When requested without nonce, the request is considered a new request.
post_only	If true, the requested order will canceled immediately once it matches the taker order.

ATTRIBUTES

Name	Description
orderId	After a successful placement of order, you get the ID of the one you placed.
status	'success' if it was successful. An error symbol shown below if any error happened.
currency_pair	The type of currency that the order was processed in.

Error Symbols

Error Name	Description
name_unchecked	In case the user who did not run the name validation process by using a cell phone in Korea.
not_enough_krw	In case the user does not have enough balance in the wallet to place the bid order.
too_many_orders	In case the maximum number of orders limit hit.
save_failure	This is an internal error. Usually it should not happen.

Place an Ask Order

Request

curl -D - -X POST -H "Authorization: Bearer $ACCESS_TOKEN" -d "currency_pair=$CURRENCY_PAIR&type=$TYPE&price=$PRICE&coin_amount=$COIN_AMOUNT&nonce=$NONCE&post_only=true" https://api.korbit.co.kr/v1/user/orders/sell

Request (Without nonce)

curl -D - -X POST -H "Authorization: Bearer $ACCESS_TOKEN" -d "currency_pair=$CURRENCY_PAIR&type=$TYPE&price=$PRICE&coin_amount=$COIN_AMOUNT&post_only=true" https://api.korbit.co.kr/v1/user/orders/sell

Response

{
  "orderId":"12513",
  "status":"success",
  "currency_pair":"btc_krw"
}

POST https://api.korbit.co.kr/v1/user/orders/sell

This API endpoint requires the TRADE scope.

PARAMETERS

Parameter	Description
currency_pair	The type of trading currency pair of which information you want to query for. We support currency pair that exists in [Constants], but the others.
type	The type of order. Specify 'limit' to place an order with a specific price you want. Specify 'market' to place an order to fill with the market price.
price	The price. This parameter is valid only for 'limit' order. Should be set with reference in [Constants].
coin_amount	The amount of the trading currency you want to sell.
nonce	[optional] in order to avoid duplicated request. When requested without nonce, the request is considered a new request.
post_only	If true, the requested order will canceled immediately once it matches the taker order.

ATTRIBUTES

Name	Description
orderId	After a successful placement of order, you get the ID of the one you placed.
status	"success" if it was successful. An error symbol shown below if any error happened.
currency_pair	The type of currency that the order was processed in.

Error Symbols

Error Name	Description
name_unchecked	In case the user who did not run the name validation process by using a cell phone in Korea.
not_enough_btc	In case the user does not have enough balance in the wallet to place the ask order.
too_many_orders	In case the maximum number of orders limit hit.
save_failure	This is an internal error. Usually it should not happen.

Cancel Open Orders

Request

curl -D - -X POST -H "Authorization: Bearer $ACCESS_TOKEN" -d "currency_pair=$CURRENCY_PAIR&id=$ID&nonce=$NONCE" https://api.korbit.co.kr/v1/user/orders/cancel

Request (Without nonce)

curl -D - -X POST -H "Authorization: Bearer $ACCESS_TOKEN" -d "currency_pair=$CURRENCY_PAIR&id=$ID" https://api.korbit.co.kr/v1/user/orders/cancel

Response : For each order, you have a status. The following example response shows that the cancellation of the orders with ID 1000 and 1002 were successful, but the cancellation of the order with ID 1001 was failed because that order does not exist.

[
  {"orderId":"1000","status":"success"},
  {"orderId":"1001","status":"not_found"},
  {"orderId":"1002","status":"success"}
]

POST https://api.korbit.co.kr/v1/user/orders/cancel

This API endpoint requires the TRADE scope.

PARAMETERS

Parameter	Description
currency_pair	The type of trading currency pair of which information you want to query for. We support currency pair that exists in [Constants], but the others.
id	The ID of order to cancel. You can repeat this parameter to cancel multiple orders at the same time (ex. id=1000&id=1001&id=1002). The ID of order is the id field on the response of v1/user/orders/open, or orderId field on the response of v1/user/orders/buy and v1/user/orders/sell.
nonce	[optional] in order to avoid duplicated request. When requested without nonce, the request is considered a new request.

ATTRIBUTES

Name	Description
orderId	The ID of order that were passed to the 'id' parameter.
status	'success' if the order was successfully canceled. An error symbol shown below otherwise.

Error Symbols

Error Name	Description
not_found	The order does not exist. This happens if you specify an ID that does not exist.
not_authorized	You tried to cancel an order placed by another user.
already_filled	The order was fully filled, without any remaining amount before the trial to cancel it.
already_canceled	The order is already canceled.
rate_limited	Same cancel order ID is requested more than 10 time within 1 second.
cannot_cancel_status	The error message "cannot_cancel_status" is displayed when the server has received an order request but the order is momentarily still processing the acceptance. This means that only orders that have been accepted can be cancelled, indicating a situation where the user is unable to cancel the order. Once the acceptance is complete and if the user attempts to cancel again, they will receive one of the following three statuses instead of "cannot_cancel_status": - success - already_canceled (either the user has already canceled the order or it was automatically canceled due to insufficient available balance) - already_filled (the order has already been filled)

List Open Orders

Request

curl -D - -H "Authorization: Bearer $ACCESS_TOKEN" https://api.korbit.co.kr/v1/user/orders/open?currency_pair=$CURRENCY_PAIR

Response

[
  {
    "timestamp": 1389173297000,
    "id": "58726",
    "type": "ask",
    "price": {"currency":"krw", "value": "800000"},
    "total": {"currency":"btc", "value": "1.00000000"},
    "open": {"currency":"btc", "value": "0.75000000"}
  },
  {"timestamp":1386419377000,"id":"37499","type":"bid","price":{"currency":"krw","value":"700000"},
  "total":{"currency":"btc","value":"1.50000000"},"open":{"currency":"btc","value":"0.41200000"}},
  ...
]

GET https://api.korbit.co.kr/v1/user/orders/open

This API endpoint requires the TRADE or VIEW scope.

PARAMETERS

Parameter	Description
currency_pair	The type of trading currency pair of which information you want to query for. We support currency pair that exists in [Constants], but the others.
offset/limit	Offset and limit for pagination of the orders. You can specify the 'offset', which is 0-based, to get list of orders starting from the offset. You can also provide the 'limit' to specify the number of open orders you want to get. The default value of 'offset' is 0 and 'limit' is 10.

ATTRIBUTES

Name	Description
timestamp	Unix timestamp in milliseconds by the time the order was placed.
id	The unique identifier of the order.
type	The type of order. 'bid' for the bid orders, 'ask' for the ask orders.
price	The price is set to price.value. price.currency is currency used for the transaction.
total	The amount in your initial order. You have two sub-fields under this field. One is 'currency', which is set to target currency, another is 'value', which is set to the amount.
open	The amount that are not filled yet. You have two sub-fields under this field. One is 'currency', which is set to target currency, another is 'value', which is set to the amount.

View Exchange Orders

Request

curl -D - -H "Authorization: Bearer $ACCESS_TOKEN" https://api.korbit.co.kr/v1/user/orders

Response

[
  {
    "id": "89999",
    "currency_pair": "btc_krw",
    "side": "bid",
    "avg_price": "2900000",
    "price": "3000000",
    "order_amount": "0.81140000",
    "filled_amount": "0.33122200",
    "order_total": "2434200",
    "filled_total": "960543",
    "created_at": "1500033942638",
    "last_filled_at": "1500533946947",
    "status": "partially_filled",
    "fee": "0.00000500"
  },
  {
    "id": "90002",
    "currency_pair": "btc_krw",
    "side": "ask",
    "avg_price": "0",
    "price": "5000000",
    "order_amount": "0.71140000",
    "filled_amount": "0",
    "order_total": "3557000",
    "filled_total": "0",
    "created_at": "1500533946947",
    "status": "unfilled"
  },
  {
    "id": "90003",
    "currency_pair": "btc_krw",
    "side": "bid",
    "avg_price": "3000000",
    "price": "3000000",
    "order_amount": "0.81140000",
    "filled_amount": "0.81140000",
    "order_total": "2434200",
    "filled_total": "2434200",
    "created_at": 1400533933748,
    "last_filled_at": "1500510381038",
    "status": "filled",
    "fee": "0.00001000"
  },
  ...
]

GET https://api.korbit.co.kr/v1/user/orders

This API endpoint requires the TRADE or VIEW scope.

PARAMETERS

Parameter	Description
currency_pair	The type of trading currency pair of which information you want to query for. We support currency pair that exists in [Constants], but the others.
status	Optional parameter for filtering by order status. Default is all statuses. Order status can be one of the following: 'unfilled', 'partially_filled', or 'filled'. These parameters can be chained in order to query for multiple status, for instance, status=unfilled&status=partially_filled to get all open orders.
id	Optional parameter for querying by order id. Default is all ids. ID query can be chained in order to query for multiple IDs, for instance, id=93038&id=93484
offset	Optional parameter for pagination. You can get the list of transactions starting from the 0-based offset index. Default is 0.
limit	Optional parameter for pagination. You can set the maximum number of transactions you want to get with this parameter. Default is 10, Max is 40.

ATTRIBUTES

Name	Description
id	The unique identifier of the order.
currency_pair	The type of currency that the order was processed in.
side	The type of the order. 'bid' for bid orders, 'ask' for ask orders.
avg_price	The weighted average of the price the currency was traded at.
price	The price that the user has set the limit to. 0 if the order was a market order.
order_amount	The amount of the trading currency you ordered. Both in bid(i.e. KRW => BTC) and ask(i.e. BTC => KRW) orders, the amount is displayed in the non-fiat currency(i.e. BTC).
filled_amount	The amount of the trading currency that has been partially filled. When filledAmount is equal to orderAmount, the order is complete. Shows only if limit trade.
order_total	The total amount of the placed order, described in KRW. If the order is a market ask order, this field is not included in the response.
filled_total	The filled amount of the order, described in KRW.
created_at	Unix timestamp in milliseconds by the time the order was placed.
last_filled_at	Unix timestamp in milliseconds when the order was last filled, either partially or fully. Does not show if not filled at all.
status	Current status of the order. Can be one of the following: 'unfilled', 'partially_filled', or 'filled'.
fee	The amount of the fee charged. The fee is charged at the quote currency. When the order is a bid order(i.e. KRW => BTC), the fee is charged in BTC. When the order is an ask order(i.e. BTC => KRW), the fee is charged in KRW. Doesn't show up if the order is unfilled at all.

Transaction History - Order Fills

Request

curl -D - -H "Authorization: Bearer $ACCESS_TOKEN" https://api.korbit.co.kr/v1/user/transactions?currency_pair=$CURRENCY_PAIR

Response

[
  {
    "timestamp": 1383707746000,
    "completedAt": 1383797746000,
    "id": "599",
    "type": "sell",
    "fee":{"currency":"krw","value":"0"},
    "fillsDetail":{
      "price": {"currency": "krw", "value": "1000000"},
      "amount": {"currency": "btc", "value": "1"},
      "native_amount": {"currency": "krw", "value": "1000000"},
      "orderId":"1002"
    },
    "isMaker": true
  },
  {
    "timestamp": 1383705741000,
    "completedAt": 1383797746200,
    "id": "597",
    "type": "buy",
    "fee":{"currency":"btc","value":"0.0015"},
    "fillsDetail":{
      "price": {"currency": "krw", "value": "1000000"},
      "amount": {"currency": "btc", "value": "1"},
      "native_amount": {"currency": "krw", "value": "1000000"},
      "orderId":"1002"
    },
    "isMaker": false
  }
]

GET https://api.korbit.co.kr/v1/user/transactions

This API call is separated into two new enhanced calls (View Exchange Orders and View Transfers. Although this call will still remain in limited functionality for existing users' convenience, the category parameter will be limited to 'fills', and 'balance' field will be removed from the call response. Hence, using the updated calls is strongly recommended.

This API endpoint requires the TRADE or VIEW scope.

PARAMETERS

Parameter	Description
currency_pair	The type of trading currency pair of which information you want to query for. We support currency pair that exists in [Constants], but the others.
offset/limit	Offset and limit for pagination of transactions. You can specify the 'offset', which is 0-based, to get the list of transactions starting from the offset. You can also provide the 'limit' to specify the number of transactions you want to get. The default value of 'offset' is 0 and 'limit' is 10. Limit's Max is 40.

Common Fields : These fields are common for all categories

Name	Description
timestamp	Unix timestamp in milliseconds specifying the time that the transaction happened.
completedAt	Unix timestamp in milliseconds specifying the time the transaction was completed. For 'fills' category this field is always set. For deposits and withdrawals of BTC and KRW, you have this field only if it is successfully completed. Any pending deposits or withdrawals do not have this field set.
id	The unique identifier of the transaction. The ID is unique within the category boundary. For example, the 'id' field is unique within 'fills' category, but the same ID can be used in 'krw' or 'btc' category.
type	The type of transaction. See the list of Transaction Types shown below.
fee	In case category is 'fills', you have the fee paid by user in this field. The fee paid by buyer comes with 'btc' currency, and the fee paid by seller comes with 'krw' currency. In case category is 'fiats' and type is 'fiat-out', you have the fee paid for KRW withdrawal. In case category is 'coins' and type is 'coin-out', you have the fee paid for BTC withdrawal. In other cases, you don't have this field in the response.
isMaker	Maker order execution is applied or not.

Transaction type

This is the list of transaction types you get in the 'type' field on the response. The string within the parenthesis denotes the category parameter you specify. The transaction type can come only if you specify the given category. For each category you get a detailed transaction type. For example, for 'fills' category, you get order fills happened either by your bidding order(type=0) or your asking order(type=1).

Name	Description
buy	(fills) Order fills - Bidding order.
sell	(fills) Order fills - Asking order.

Sub-fields(fillsDetail)

You have following sub-fields under 'fillsDetail' field, which comes only if the category is 'fills'.

Name	Description
price	The price of an order fill. You have two sub-fields. One is 'currency', which is always set to 'krw' for now. Another is 'value', which is set to the filled price.
amount	The amount of selected currency in the order fill. You have two sub-fields. One is 'currency', which is set to one currency you selected in currency_pair field among 'btc', 'etc' or 'eth'. Another is 'value', which is set to the filled amount of that selected currency.
native_amount	The calculated amount of the order represented in KRW, based on the filled price.
orderId	The ID of the filled order. This is the ID of order you placed.

Private - Wallet

Request or cancel Crypto Currency withdrawals. Query transfer details.

Request Crypto Currency Withdrawal (New)

Request

curl -D - -X POST -H "Authorization: Bearer $ACCESS_TOKEN" -d "currency=$CURRENCY&amount=$AMOUNT&address=$ADDRESS&secondary_address=$SECONDARY_ADDRESS&nonce=$NONCE" https://api.korbit.co.kr/v2/user/coins/out

Response

{
  "transferId":"21591",
  "status":"success"
}

POST https://api.korbit.co.kr/v2/user/coins/out

This API endpoint requires the WITHDRAWAL scope.

[How to register for Open API]
To be updated

PARAMETERS

Parameter	Description
currency	A mandatory parameter. You need to set currency.
amount	The amount to withdraw.
address	The address to sent.
secondary_address	To use if the coin have a secondary address. It is also compatible with the existing destination_tag but is not recommended.

ATTRIBUTES

Name	Description
transferId	The unique ID of the withdrawal request. You can use this ID to cancel a withdrawal request or get the status of it.
status	'success' if the withdrawal was successful, an error symbol otherwise.

Error Symbols

Error Name	Description
another_transfer_in_progress	An on-going withdrawal request exists. It takes less than 10 seconds for a withdrawal request to finish. You can create a withdrawal request only if the previous request was successfully finished, or you canceled it.
exceeds_api_daily_limit	The user tried to withdraw more than the maximum limit per day.
exceeds_available_size	The user tried to transfer more than the available amount.
save_failure	This is an internal error. Usually it should not happen.
bad_request	Bad request error
unavailable_service	Travelrule error
internal_error	Internal server error

Cancel Transfer Request

Request

curl -D - -X POST -H "Authorization: Bearer $ACCESS_TOKEN" -d "currency=$CURRENCY&id=$ID&nonce=$NONCE" https://api.korbit.co.kr/v1/user/coins/out/cancel

Response

{
  "transferId":"21591",
  "status":"success"
}

POST https://api.korbit.co.kr/v1/user/coins/out/cancel

You can cancel a transfer request by using following API. In case the transfer is being processed by an administrator, or it is completed, you get an error code. This API endpoint requires the WITHDRAWAL scope.

PARAMETERS

Parameter	Description
id	The unique ID of the withdrawal request.

ATTRIBUTES

Name	Description
id	The unique ID of the withdrawal request specified on the 'id' parameter.
status	'success' if it was successfully canceled, an error symbol otherwise.

Error Symbols

Error Name	Description
not_found	The withdrawal request does not exist. If a wrong value is specified on the 'id' parameter , you can get this error symbol.
not_found	The user tried to cancel a withdrawal request created by another user.
transfer_locked	The withdrawal process has already been started, so it is impossible to cancel it.
already_filled	The withdrawal process has already been completed, so it is impossible to cancel it.

View Transfers

Request

curl -D - -H "Authorization: Bearer $ACCESS_TOKEN" https://api.korbit.co.kr/v1/user/transfers

Response

[
  {
    "id": "270",
    "type": "deposit",
    "currency": "btc",
    "amount": "0.81140000",
    "completed_at": 11750020020,
    "updated_at": 11550050080,
    "created_at": 11550020020,
    "status": "filled",
    "details": {
      "transaction_id": "2d84855aa9c...",
      "address": "1F1zAaz5x1HUXrCNLbtMDqcw6o5GNx4xqX"
    }
  },
  {
    "id": "280",
    "type": "withdrawal",
    "currency": "btc",
    "amount": "0.81140000",
    "updated_at": 11550050080,
    "created_at": 11550020020,
    "status": "requested",
    "details": {
      "transaction_id": "2d84855aa9c...",
      "address": "1F1zAaz5x1HUXrCNLbtMDqcw6o5GNx4xqX"
    }
  },
  {
    "id": "380",
    "type": "deposit",
    "currency": "krw",
    "amount": "1100000",
    "completed_at": 12550020020,
    "updated_at": 11550020020,
    "created_at": 11233223233,
    "status": "filled"
  },
  {
    "id": "480",
    "timestamp": 12983983983,
    "type": "withdrawal",
    "currency": "krw",
    "amount": "1200000",
    "completed_at": 12550020020,
    "updated_at": 11550020020,
    "created_at": 11233223233,
    "status": "filled",
    "fee": "1800"
  }
]

GET https://api.korbit.co.kr/v1/user/transfers

This API endpoint requires the WITHDRAWAL or VIEW scope.

PARAMETERS

Parameter	Description
currency	The type of currency you want to query for. Supports KRW, BTC, ETH, ETC XRP and etc.
type	Optional parameter for filtering. You can filter by type of transfer, which is either 'deposit' or 'withdrawal'. Default is 'all' transfers.
offset	Optional parameter for pagination. You can get the list of transactions starting from the 0-based offset index. Default is 0.
limit	Optional parameter for pagination. You can set the maximum number of transactions you want to get with this parameter. Default and Max is 40.

Common Fields : These fields are common for all categories

Name	Description
id	The unique identifier of the order.
type	The type of the transfer, which is either deposit or withdrawal.
currency	The currency that the transfer was made in.
amount	The amount of the deposit/withdrawal.
completed_at	Unix timestamp in milliseconds when the transfer order is complete. Shows only when the order is complete.
updated_at	Unix timestamp in milliseconds when the transfer order was last updated. The transfers are ordered by this field, most recently updated transfer showing at the top.
created_at	Unix timestamp in milliseconds by the time the transfer order was initiated.
status	Current status of the order.
fee	The amount of the fee that was charged for withdrawal. Shows only for filled withdrawals that a fee was incurred. The currency is equivalent to the currency of the withdrawal.

Sub-fields (For coin deposit/withdrawal)

Name	Description
details.transaction_id	Transaction ID of the coin deposit/withdrawal.
details.address	Destination address of the coin.
details.destination_tag	Destination tag that shows up only when the currency have secondly address like XRP, EOS, XLM.

Query Status of Deposit and Withdrawal

Request

curl -D - -H "Authorization: Bearer $ACCESS_TOKEN" https://api.korbit.co.kr/v1/user/coins/status

Response : A completed Deposit

[
  {
    "timestamp": 1392620446000,
    "id": "5180",
    "type": "coin-in",
    "amount": { "currency": "btc", "value": "0.01"},
    "in": "1anjg6B2XbpjHx8LFw8mXHATH54vrxs2F",
    "completedAt": 1392620446100
  }
]

GET https://api.korbit.co.kr/v1/user/coins/status

Response : A pending withdrawal request

[
  {
    "timestamp": 1392620446000,
    "id": "5180",
    "type": "coin-out",
    "amount": { "currency": "btc", "value": "0.01"},
    "out": "1anjg6B2XbpjHh8LFw8xXHATH54vrxs2F"
  }
]

Response : A completed withdrawal request

[
  {
    "timestamp": 1392620446000,
    "id": "5180",
    "type": "coin-out",
    "amount": { "currency": "btc", "value": "0.01"},
    "out": "1anjg6B2XbpjHh8LFw8xXHATH54vrxs2F",
    "completedAt": 1392620946300
  }
]

You can query status of deposits and transfers by using the following API. This API endpoint requires the WITHDRAWAL or VIEW scope.

PARAMETERS

Parameter	Description
currency	A mandatory parameter. You need to set currency.
id	The unique ID of the withdrawal request. If this parameter is not specified, the API responds with a pending withdrawal request if any.

ATTRIBUTES

Name	Description
timestamp	Unix timestamp in milliseconds by the time the deposit or withdrawal request was created.
id	The unique ID deposit or withdrawal request.
type	"coin-in" if it is a deposit request, "coin-out" if it is a withdrawal request.
amount	The amount to deposit or withdraw. The value field in it has the amount of deposit or withdrawal. The currency field set target currency.
in	The user's address assigned in Korbit system to receive. This field comes only if type is 'coin-in'.
out	The user's address to where was sent. this field comes only if type is 'coin-out'.
completedAt	Unix timestamp in milliseconds by the time the deposit or withdrawal was completed. If it is pending, this field is not included in the response.

Assign Crypto Currency Address

Request

curl -D - -X POST -H "Authorization: Bearer $ACCESS_TOKEN" -d "currency=$CURRENCY&nonce=$NONCE" https://api.korbit.co.kr/v1/user/coins/address/assign

Response

{
  "address":"1F1xAaz5x1HUXrCNLbtMDqcw6o5GNn4xqX",
  "status":"success"
}

POST https://api.korbit.co.kr/v1/user/coins/address/assign

Since within Korbit are made internally, a address does not need to be assigned to every user. However, to receive from an outside source to your Korbit account, you can set up your receiving address by using the following API. This API endpoint requires the WITHDRAWAL scope.

PARAMETERS

Parameter	Description
currency	A mandatory parameter. You need to set currency.

ATTRIBUTES

Name	Description
address	The newly assigned address. Korbit has the private key of the address to process withdrawal request on behalf of the user. If the address is already assigned to the user the existing one is set to this field.
status	'success', if a new address was assigned, an error symbol otherwise.

Error Symbols

Error Name	Description
already_assigned	The user already has a address assigned.
no_more_address	No address is available in Korbit system. Korbit system administrator needs to allocate more addresses.
save_failure	This is an internal error. Usually it should not happen.

Getting API Keys

Receive an API key at the following URL : https://www.korbit.co.kr/my/api