Korbit Trading API
The Trading API from Korbit — 4 operation(s) for trading.
OpenAPI Specification
openapi: 3.1.0
info:
title: Korbit Open API v2 Asset Trading API
version: 2.0.0
description: 'REST API for the Korbit cryptocurrency exchange (Korea''s first virtual-asset exchange). Covers market data (quotation), trading, balances, crypto deposits and withdrawals, and KRW deposit/withdrawal push notifications.
All responses use the envelope `{"success": true, "data": ...}`; errors use `{"success": false, "error": {"message": "<CODE>"}}`.
Private endpoints require the `X-KAPI-KEY` header plus `timestamp` and `signature` parameters. Signatures are HMAC-SHA256 (hex) or ED25519 (Base64, URL-encoded) over the exact encoded request string. See the timestamp-window rules: `recvWindow` defaults to 5000 ms, maximum 60000 ms, and the future bound is a fixed +1000 ms.
This document was generated by the API Evangelist enrichment pipeline from Korbit''s own published agent documentation bundle (https://docs.korbit.co.kr/llms-full.txt). Korbit does not publish an OpenAPI document; this is a faithful transcription of the published reference, not an official artifact.'
contact:
name: Korbit Developers
url: https://developers.korbit.co.kr
x-generated-by: API Evangelist enrichment pipeline
x-source: https://docs.korbit.co.kr/llms-full.txt
servers:
- url: https://api.korbit.co.kr
description: Production
- url: http://127.0.0.1:9999
description: Local sandbox (korbit-sandbox.mjs) — mock, not the production server
tags:
- name: Trading
paths:
/v2/orders:
get:
operationId: getOrders
summary: Get Order
description: 'Use either `orderId` or `clientOrderId` to query the status of an individual order.
However, orders with the statuses `expired` or `canceled` cannot be retrieved approximately 3 days after they have been closed.'
tags:
- Trading
parameters:
- name: symbol
in: query
required: true
description: Trading pair.
schema:
type: string
examples:
- btc_krw
- name: accountSeq
in: query
description: Account sequence number. Defaults to 1 (main account).
schema:
type: number
examples:
- 1
- name: orderId
in: query
description: Enter `orderID` (responsed by POST /v2/orders). Enter one of `orderID` or `clientOrderId`.
schema:
type: number
examples:
- 1234
- name: clientOrderId
in: query
description: Enter `clientOrderId` (requested by POST /v2/orders). Enter one of `orderID` or `clientOrderId`.
schema:
type: string
examples:
- 20141231-155959-abcdef
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
examples:
- true
data:
type: object
properties:
orderId:
type: number
description: Order ID generated by the server.
examples:
- 1234
clientOrderId:
type: string
description: '`clientOrderId` submitted from the user by POST /v2/orders.'
examples:
- 20141231-155959-abcdef
symbol:
type: string
description: symbol.
examples:
- btc_krw
orderType:
type: string
enum:
- limit
- market
- best
description: '`limit` — limit order / `market` — market order / `best` — best bid/offer'
side:
type: string
enum:
- buy
- sell
timeInForce:
type: string
enum:
- gtc
- ioc
- fok
- po
description: 'Time in Force strategies. Default: - limit order: `gtc` - market order: `ioc` - best bid/offer: no default(Bad Request error if omitted) For market orders, only `ioc` can be entered. `gtc` — Good-Till-Canceled. The order will remain valid until terminated (fully executed or canceled) / `ioc` — Immediate-Or-Cancel. The order will be filled immediately, if can not then will be canceled. (Taker-Only) / `fok` — Fill-Or-Kill. The order will be filled fully, if can not then will be canceled. (Taker-Only) / `po` — Post-Only. If the order would be filled immediately, then will be canceled. (Maker-Only)'
price:
type: string
description: Order price (limit/BBO order only. no price for market order. For BBO orders it's set after the price is determined).
examples:
- '5000'
qty:
type: string
description: Order quantity (limit/BBO order or sell-side market order only. For BBO orders it's set after the quantity is determined).
examples:
- '10'
amt:
type: string
description: Purchase amount in counter/quote asset like KRW. (buy-side market/BBO order only).
examples:
- '50000'
filledQty:
type: string
description: Filled quantity.
examples:
- '10'
filledAmt:
type: string
description: Filled amount in counter/quote asset like KRW.
examples:
- '50000'
avgPrice:
type: string
description: Average execution price.
examples:
- '5000'
createdAt:
type: number
description: Order timestamp (ms).
examples:
- 1700000000000
lastFilledAt:
type: number
description: Last execution timestamp (ms).
examples:
- 1700000000000
triggeredAt:
type: number
description: Stop-limit order trigged timestamp.
examples:
- 1700000000000
status:
type: string
enum:
- pending
- open
- filled
- canceled
- partiallyFilled
- partiallyFilledCanceled
- expired
description: Order status `pending` — Order pending. When the balance is insufficient or timeInForce condition is triggered, the order may fail and change to the `expired` status. / `open` — Fully unfilled / `filled` — Execution closed. An order whose unfilled remainder is returned instead of resting on the book (e.g. an `ioc` order, or a price-protected (`pp`) order trimmed by the protection range) also closes as `filled` even when less than the requested quantity executed. Confirm the executed amount with `filledQty`/`filledAmt`. / `canceled` — Fully canceled / `partiallyFilled` — Partially filled / `partiallyFilledCanceled` — Partially filled and remaining amount canceled / `expired` — Order submission failed (due to insufficient balance or timeInForce conditions)
required:
- orderId
- symbol
- orderType
- side
- filledQty
- filledAmt
- createdAt
- status
required:
- success
example:
success: true
data:
orderId: 1234
clientOrderId: 20141231-155959-abcdef
symbol: btc_krw
orderType: limit
side: buy
timeInForce: gtc
avgPrice: '5000'
price: '5000'
qty: '10'
filledQty: '1'
filledAmt: '5000'
createdAt: 1700000000000
lastFilledAt: 1700000000000
status: partiallyFilled
'400':
description: Bad request — see the error envelope and error codes.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Missing or invalid API key / signature.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: API key lacks the required permission or the IP is not allowlisted.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded. Honor `Retry-After` / the `Ratelimit` reset window.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- KorbitApiKey: []
x-korbit-permission: readOrders
post:
operationId: createOrders
summary: Place Order
description: Place a new order.
tags:
- Trading
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
symbol:
type: string
description: Trading pair.
examples:
- btc_krw
accountSeq:
type: number
description: Account sequence number. Defaults to 1 (main account).
examples:
- 1
side:
type: string
enum:
- buy
- sell
price:
type: string
description: order price for a limit order. omit for a market/BBO order.
examples:
- '250000'
qty:
type: string
description: order quantity for a limit order and a market/BBO sell order. omit for a market/BBO buy order.
examples:
- '10'
amt:
type: string
description: order amount (purchase amount) for a market/BBO buy order. omit for a limit order and a market/BBO sell order.
examples:
- '250000'
orderType:
type: string
enum:
- limit
- market
- best
description: '`limit` — limit order / `market` — market order / `best` — best bid/offer. The `timeInForce` and `bestNth` parameters must be set.'
bestNth:
type: number
description: 'Selects the order''s price when orderType=`best`. For other types, this parameter must be omitted. - when timeInForce is one of `gtc`,`ioc`,`fok`: Opponent N price level where N is 1 ~ 5. - when timeInForce is `po`: Queue N price level where N is 1 ~ 5.'
examples:
- 1
timeInForce:
type: string
enum:
- gtc
- ioc
- fok
- po
description: 'Time in Force strategies. Default: - limit order: `gtc` - market order: `ioc` - best bid/offer: no default(Bad Request error if omitted) For market orders, only `ioc` can be entered. `gtc` — Good-Till-Canceled. The order will remain valid until terminated (fully executed or canceled) / `ioc` — Immediate-Or-Cancel. The order will be filled immediately, if can not then will be canceled. (Taker-Only) / `fok` — Fill-Or-Kill. The order will be filled fully, if can not then will be canceled. (Taker-Only) / `po` — Post-Only. If the order would be filled immediately, then will be canceled. (Maker-Only)'
clientOrderId:
type: string
description: 'User-defined order ID. Even if multiple requests are made with the same `clientOrderId`, it will be processed only once. You can search for the order using `clientOrderId` with the `GET /v2/orders`. Only strings matching the following regex pattern are allowed: `[0-9a-zA-Z.:_-]{1,36}` However, orders with the statuses `expired` or `canceled` cannot be searched by `clientOrderId` or same `clientOrderId` can be reused approximately three days after they have been closed.'
examples:
- 20141231-155959-abcdef
pp:
type: string
description: Price protection. Set to `true` to enable the price protection feature. This order will only be executed within the price protection range when matched as a taker. Use the `ppPercent` parameter to change the threshold.
ppPercent:
type: string
description: Threshold(in percent) for the price protection feature. Set an integer between 1 and 100. If the price protection threshold is set to 5, this order will only be executed within 5% of the midpoint price (between the best ask and best bid) when matched as a taker order. Any unfilled quantity will be canceled. If you enable price protection but do not set ppPercent, the default (5) will be used.
required:
- symbol
- side
- orderType
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
examples:
- true
data:
type: object
properties:
orderId:
type: number
description: order ID.
examples:
- 1234
required:
- orderId
required:
- success
example:
success: true
data:
orderId: 1234
'400':
description: Bad request — see the error envelope and error codes.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Missing or invalid API key / signature.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: API key lacks the required permission or the IP is not allowlisted.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded. Honor `Retry-After` / the `Ratelimit` reset window.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- KorbitApiKey: []
x-korbit-permission: writeOrders
x-korbit-error-codes:
- code: DUPLICATE_CLIENT_ORDER_ID
message: Request rejected due to duplicate `clientOrderId`.
- code: INVALID_CURRENCY_PAIR
message: Invalid symbol.
- code: INVALID_USER_STATUS
message: Trading has been temporarily restricted according to Korbit's policy.
- code: BAD_REQUEST
message: Bad request.
- code: NO_BALANCE
message: Insufficient balance.
- code: ONLY_SELL_LIMIT_ORDERS_ALLOWED
message: Only limit sell orders are allowed during the initial listing period.
- code: ORDER_VALUE_TOO_LARGE
message: Order exceeds the maximum amount. Please adjust the `qty` * `price` to be 1 billion KRW or less.
- code: ORDER_VALUE_TOO_SMALL
message: Order does not meet the minimum amount. Please adjust the `qty` * `price` to be at least 5,000 KRW.
- code: PRICE_OVER_UPPER_BOUND
message: Above the upper price limit during the initial listing period.
- code: PRICE_UNDER_LOWER_BOUND
message: Below the lower price limit during the initial listing period.
- code: PRICE_TICK_SIZE_INVALID
message: Invalid tick size.
- code: TOO_MANY_OPEN_ORDERS
message: Order quantity limit exceeded.
delete:
operationId: deleteOrders
summary: Cancel Order
description: 'Requests to cancel an open order.
If the API call is successful, the cancel request is accepted and the order will be canceled soon.
If the error code is one of `ORDER_ALREADY_CANCELED`, `ORDER_ALREADY_FILLED`, or `ORDER_ALREADY_EXPIRED`, it means the order has been already been closed.'
tags:
- Trading
parameters:
- name: symbol
in: query
required: true
description: Trading pair.
schema:
type: string
examples:
- btc_krw
- name: accountSeq
in: query
description: Account sequence number. Defaults to 1 (main account).
schema:
type: number
examples:
- 1
- name: orderId
in: query
description: '`orderId` responsed in `POST /v2/orders`. You must choose to enter either `orderId` or `clientOrderId`.'
schema:
type: number
examples:
- 1234
- name: clientOrderId
in: query
description: '`clientOrderId` which is a user-defined order ID requested in `POST /v2/orders`. You must choose to enter either `orderId` or `clientOrderId`.'
schema:
type: string
examples:
- 20141231-155959-abcdef
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
examples:
- true
required:
- success
example:
success: true
'400':
description: Bad request — see the error envelope and error codes.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Missing or invalid API key / signature.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: API key lacks the required permission or the IP is not allowlisted.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded. Honor `Retry-After` / the `Ratelimit` reset window.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- KorbitApiKey: []
x-korbit-permission: writeOrders
x-korbit-error-codes:
- code: ORDER_NOT_FOUND
message: Not found order
- code: ORDER_ALREADY_CANCELED
message: Already canceled order
- code: ORDER_ALREADY_FILLED
message: Already filled order
- code: ORDER_ALREADY_EXPIRED
message: Already expired order
- code: TRY_AGAIN
message: The order is currently being processed. Please try again in a few moments later.
/v2/openOrders:
get:
operationId: getOpenOrders
summary: Get Open Orders
description: Query the list of open orders for a single trading pair. Only orders with the status `open` or `partiallyFilled` are queried.
tags:
- Trading
parameters:
- name: symbol
in: query
required: true
description: Trading pair.
schema:
type: string
examples:
- btc_krw
- name: accountSeq
in: query
description: Account sequence number. Defaults to 1 (main account).
schema:
type: number
examples:
- 1
- name: limit
in: query
description: 'Number of queries (range: 1 to 1000). Default is 500.'
schema:
type: number
examples:
- 100
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
examples:
- true
data:
type: array
items:
type: object
properties:
orderId:
type: number
description: Order ID generated by the server.
examples:
- 1234
clientOrderId:
type: string
description: '`clientOrderId` submitted from the user by POST /v2/orders.'
examples:
- 20141231-155959-abcdef
orderType:
type: string
enum:
- limit
- market
- best
description: '`limit` — limit order / `market` — market order / `best` — best bid/offer'
side:
type: string
enum:
- buy
- sell
price:
type: string
description: Order price (limit/BBO order only. no price for market order. For BBO orders it's set after the price is determined).
examples:
- '5000'
qty:
type: string
description: Order quantity (limit/BBO order or sell-side market order only. For BBO orders it's set after the quantity is determined).
examples:
- '10'
amt:
type: string
description: Purchase amount in counter/quote asset like KRW. (buy-side market/BBO order only).
examples:
- '50000'
filledQty:
type: string
description: Filled quantity.
examples:
- '10'
filledAmt:
type: string
description: Filled amount in counter/quote asset like KRW.
examples:
- '50000'
avgPrice:
type: string
description: Average execution price.
examples:
- '5000'
createdAt:
type: number
description: Order timestamp (ms).
examples:
- 1700000000000
lastFilledAt:
type: number
description: Last execution timestamp (ms).
examples:
- 1700000000000
status:
type: string
enum:
- pending
- open
- filled
- canceled
- partiallyFilled
- partiallyFilledCanceled
- expired
description: Order status `pending` — Order pending. When the balance is insufficient or timeInForce condition is triggered, the order may fail and change to the `expired` status. / `open` — Fully unfilled / `filled` — Execution closed. An order whose unfilled remainder is returned instead of resting on the book (e.g. an `ioc` order, or a price-protected (`pp`) order trimmed by the protection range) also closes as `filled` even when less than the requested quantity executed. Confirm the executed amount with `filledQty`/`filledAmt`. / `canceled` — Fully canceled / `partiallyFilled` — Partially filled / `partiallyFilledCanceled` — Partially filled and remaining amount canceled / `expired` — Order submission failed (due to insufficient balance or timeInForce conditions)
required:
- orderId
- orderType
- side
- filledQty
- filledAmt
- createdAt
- status
required:
- success
example:
success: true
data:
- orderId: 1234
orderType: limit
side: buy
avgPrice: '5000'
price: '5000'
qty: '10'
filledQty: '1'
filledAmt: '5000'
createdAt: 1700000000000
lastFilledAt: 1700000000000
status: partiallyFilled
- orderId: 1235
orderType: limit
side: sell
price: '5000'
qty: '10'
filledQty: '0'
filledAmt: '0'
createdAt: 1700000000000
status: open
'400':
description: Bad request — see the error envelope and error codes.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Missing or invalid API key / signature.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: API key lacks the required permission or the IP is not allowlisted.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded. Honor `Retry-After` / the `Ratelimit` reset window.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- KorbitApiKey: []
x-korbit-permission: readOrders
/v2/allOrders:
get:
operationId: getAllOrders
summary: Get All Orders
description: 'Query the recent order list for a single trading pair. Only orders created within 36 hours can be queried.
This API is for checking order history, and the information provided may have a delay of a few seconds.
If you need current information without delay, please use the `/v2/openOrders` or `/v2/orders` API.'
tags:
- Trading
parameters:
- name: symbol
in: query
required: true
description: Trading pair.
schema:
type: string
examples:
- btc_krw
- name: accountSeq
in: query
description: Account sequence number. Defaults to 1 (main account).
schema:
type: number
examples:
- 1
- name: startTime
in: query
description: 'Query start time. Inclusive: a record at exactly this time is returned. Only data up to 36 hours prior to the current time can be queried. If not set, the query will retrieve data from 36 hours ago by default.'
schema:
type: number
- name: endTime
in: query
description: 'Query end time. Exclusive: a record at exactly this time is not returned. If not set, data is retrieved up to the current time. Results are newest-first and capped at limit; to retrieve more, narrow the range with startTime/endTime.'
schema:
type: number
- name: limit
in: query
description: 'Maximum number of queries (range: 1 to 1000). Default is 500.'
schema:
type: number
examples:
- 100
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
examples:
- true
data:
type: array
items:
type: object
properties:
orderId:
type: number
description: Order ID generated by the server.
examples:
- 1234
clientOrderId:
type: string
description: '`clientOrderId` submitted from the user by POST /v2/orders.'
examples:
- 20141231-155959-abcdef
symbol:
type: string
description: symbol.
examples:
- btc_krw
orderType:
type: string
enum:
- limit
- market
- best
description: '`limit` — limit order / `market` — market order / `best` — best bid/offer'
side:
type: string
enum:
- buy
- sell
timeInForce:
type: string
enum:
- gtc
- ioc
- fok
- po
description: 'Time in Force strategies. Default: - limit order: `gtc` - market order: `ioc` - best bid/offer: no default(Bad Request error if omitted) For market orders, only `ioc` can be entered. `gtc` — Good-Till-Canceled. The order will remain valid until terminated (fully executed or canceled) / `ioc` — Immediate-Or-Cancel. The order will be filled immediately, if can not then will be canceled. (Taker-Only) / `fok` — Fill-Or-Kill. The order will be filled fully, if can not then will be canceled. (Taker-Only) / `po` — Post-Only. If the order would be filled immediately, then will be canceled. (Mak
# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/korbit/refs/heads/main/openapi/korbit-trading-api-openapi.yml