Overview
Welcome to our V5 API documentation. We offer complete REST and WebSocket APIs to suit your trading needs.
The V5 API is only applicable to the Unified account.
Demo Trading Services
At present, the V5 API works for Demo Trading and users can request all APIs except the Funding withdrawal
, transfer
and purchase/redemption
.
The Demo Trading URL:
REST: https://www.okex.com
Public WebSocket: wss://ws.okex.com:8443/ws/v5/public?brokerId=9999
Private WebSocket: wss://ws.okex.com:8443/ws/v5/private?brokerId=9999
OKEx account can be used for login on Dmo Trading. If you already have an OKEx account, you can log in directly.
Start API Demo Trading by the following steps:
Login OKEx —> Assets —> Start Demo Trading —> Personal Center —> Demo Trading API -> Create Demo Trading V5 APIKey —> Start your Demo Trading
Note: x-simulated-trading: 1
needs to be added to the header of the Demo Trading request.
Example:
Content-Type: application/json
OK-ACCESS-KEY: 37c541a1-*--***-10fe7a038418
OK-ACCESS-SIGN: leaVRETrtaoEQ3yI9qEtI1CZ82ikZ4xSG5Kj8gnl3uw=
OK-ACCESS-PASSPHRASE: 1****6
OK-ACCESS-TIMESTAMP: 2020-03-28T12:21:41.274Z
x-simulated-trading: 1
REST API
Authentication
Generating an APIKey
Create an APIKey on the OKEx website before signing any requests. After creating an APIKey, keep the following information safe:
- APIKey
- SecretKey
- Passphrase
We will provide randomly-generated APIKeys and SecretKeys. You will provide the Passphrase to further secure your API access. We store the salted hash of your Passphrase for authentication, but we cannot recover the Passphrase if you lose it.
Making Requests
All private REST requests must contain the following headers:
OK-ACCESS-KEY
The APIKey as a String.
OK-ACCESS-SIGN
The Base64-encoded signature (see Signing Messages subsection for details).
OK-ACCESS-TIMESTAMP
The timestamp of your request.e.g : 2020-12-08T09:08:57.715Z
OK-ACCESS-PASSPHRASE
The passphrase you specified when creating the APIKey.
Request bodies should have content type application/json
and be in valid JSON format.
Signature
Signing Messages
The OK-ACCESS-SIGN
header is generated as follows:
- Create a prehash string of timestamp + method + requestPath + body (where + represents String concatenation).
- Prepare the SecretKey.
- Sign the prehash string with the SecretKey using the HMAC SHA256.
- Encode the signature in the Base64 format.
Example: sign=CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA256(timestamp + 'GET' + '/users/self/verify', SecretKey))
The timestamp
value is the same as the OK-ACCESS-TIMESTAMP
header with millisecond format of ISO, e.g. 2020-12-08T09:08:57.715Z
.
The request method should be in UPPERCASE: e.g. GET
and POST
.
The requestPath
is the path of requesting an endpoint.
Example: /api/v5/account/balance
The body
refers to the String of the request body. It can be omitted if there is no request body (frequently the case for GET
requests).
Example: {"instId":"BTC-USDT","lever":"5","mgnMode":"isolated"}
The SecretKey is generated when you create an APIKey.
Example: 22582BD0CFF14C41EDBF1AB98506286D
Account
The API endpoints of Account
require authentication.
Get Balance
Retrieve a list of assets (with non-zero balance), remaining balance, and available amount in the account.
Rate Limit: 20 requests per 2 seconds
HTTP Requests
GET /api/v5/account/balance
Request Example
Get the balance of all assets in the account
GET /api/v5/account/balance
Get the balance of BTC and ETH assets in the account
GET /api/v5/account/balance?ccy=BTC,ETH
Request Parameters
Parameters | Types | Required | Description |
---|---|---|---|
ccy | String | No | Single currency or multiple currencies (no more than 20) separated with comma, e.g. BTC or BTC,ETH . |
Example Response
{
"code": "0",
"msg": "",
"data": [
{
"uTime": "1597026383085",
"totalEq": "41624.32",
"isoEq": "3624.32",
"adjEq": "41624.32",
"imr": "4162.33",
"mmr": "4",
"mgnRatio": "41624.32",
"details": [
{
"ccy": "BTC",
"eq": "123",
"isoEq": "",
"availEq": "1234",
"availBal": "",
"frozenBal": "14",
"ordFrozen": "12",
"upl": "124",
"mgnRatio": "",
"interest": "12",
"liab": "1"
},
{
"ccy": "ETH",
"eq": "223",
"isoEq": "",
"availEq": "2234",
"availBal": "",
"frozenBal": "141",
"ordFrozen": "12",
"upl": "124",
"mgnRatio": "",
"interest": "0",
"liab": "0"
}
]
}
]
}
Response Parameters
Parameters | Types | Description |
---|---|---|
uTime | String | The latest time to get account information, millisecond format of Unix timestamp, e.g. 1597026383085 |
totalEq | String | Total equity in USD level |
isoEq | String | Isolated margin equity in USD level Applicable to Single-currency margin and Multi-currency margin |
adjEq | String | Adjusted/Effective equity in USD level Applicable to Multi-currency margin |
imr | String | Initial margin requirement in USD level Applicable to Multi-currency margin |
mmr | String | Maintenance margin requirement in USD level Applicable to Multi-currency margin |
mgnRatio | String | Margin ratio in USD level Applicable to Multi-currency margin |
details | Array | Detailed asset information in all currencies |
> ccy | String | Currency |
> eq | String | Equity of the currency |
> isoEq | String | Isolated margin equity of the currency Applicable to Single-currency margin and Multi-currency margin |
> availEq | String | Available equity of the currency Applicable to Single-currency margin and Multi-currency margin |
> availBal | String | Available balance of the currency Applicable to Simple |
> frozenBal | String | Frozen balance of the currency |
> ordFrozen | String | Margin frozen for open orders |
> liab | String | Liabilities of the currency Applicable to Multi-currency margin |
> upl | String | Unrealized profit and loss of the currency Applicable to Single-currency margin and Multi-currency margin |
> mgnRatio | String | Margin ratio of the currency Applicable to Single-currency margin |
> interest | String | Interest of the currency Applicable to Multi-currency margin |
Distribution of applicable fields under each account level are as follows:
Parameters | Simple account | Single-currency margin account | Multi-currency margin account |
---|---|---|---|
uTime | Yes | Yes | Yes |
totalEq | Yes | Yes | Yes |
isoEq | Yes | Yes | |
adjEq | Yes | ||
imr | Yes | ||
mmr | Yes | ||
mgnRatio | Yes | ||
details | |||
> ccy | Yes | Yes | Yes |
> eq | Yes | Yes | Yes |
> isoEq | Yes | Yes | |
> availEq | Yes | Yes | |
> availBal | Yes | ||
> frozenBal | Yes | Yes | Yes |
> ordFrozen | Yes | Yes | Yes |
> liab | Yes | ||
> upl | Yes | Yes | |
> mgnRatio | Yes | ||
> interest | Yes |
Get Positions
Retrieve information on your positions. When the account is in net
mode, net
positions will be displayed, and when the account is in long/short
mode, long
or short
positions will be displayed.
Rate Limit: 20 requests per 2 seconds
HTTP Request
GET /api/v5/account/positions
Request Example
Query BTC-USDT position information
GET /api/v5/account/positions?instId=BTC-USDT
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instType | String | No | Instrument typeMARGIN SWAP FUTURES OPTION instId will be checked against instType when both parameters are passed, and the position information of the instId will be returned. |
instId | String | No | Instrument ID, e.g. BTC-USD-190927-5000-C |
posId | String | No | Single position ID or multiple position IDs (no more than 20) separated with comma |
Example Response
{
"code": "0",
"msg": "",
"data": [
{
"instId": "BTC-USDT",
"instType": "MARGIN",
"mgnMode": "cross",
"posId": "1111234112",
"posSide": "net",
"pos": "10",
"ccy": "BTC",
"posCcy": "BTC",
"availPos": "2",
"avgPx": "3320",
"upl": "0.00020928",
"uplRatio": "0.00020928",
"lever": "2",
"liqPx": "0.00020928",
"imr": "2",
"margin": "",
"mgnRatio": "",
"mmr": "2",
"liab": "0.00020928",
"liabCcy": "USDT",
"interest": "2",
"tradeId": "2",
"optVal": "",
"adl": "2",
"last": "12353.5",
"cTime": "1597026383085",
"uTime": "1597026383085"
}
]
}
Request Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument type |
mgnMode | String | Margin modecross isolated |
posId | String | Position ID |
posSide | String | Position sidelong short net (FUTURES/SWAP/OPTION : positive pos means long position and negative pos means short position. MARGIN : posCcy being base currency means long position, posCcy being quote currency means short position.) |
pos | String | Quantity of positions |
posCcy | String | Position currency, only applicable to MARGIN positions. |
availPos | String | Position that can be closed Only applicable to MARGIN , FUTURES/SWAP in the long-short mode, OPTION in Simple and isolated OPTION in margin Account. |
avgPx | String | Average open price |
upl | String | Unrealized profit and loss |
uplRatio | String | Unrealized profit and loss ratio |
instId | String | Instrument ID, e.g. BTC-USD-180216 |
lever | String | Leverage, not applicable to OPTION seller |
liqPx | String | Estimated liquidation price Not applicable to cross FUTURES/SWAP in Multi-currency margin Not applicable to OPTION |
imr | String | Initial margin requirement, only applicable to cross . |
margin | String | Margin, can be added or reduced. Only applicable to isolated Margin . |
mgnRatio | String | Margin ratio, only applicable to isolated . |
mmr | String | Maintenance margin requirement |
liab | String | Liabilities, only applicable to MARGIN . |
liabCcy | String | Liabilities currency, only applicable to MARGIN . |
interest | String | Interest. Interest that has been incurred. |
tradeId | String | Last trade ID |
optVal | String | Option Value, only applicable to OPTION . |
adl | String | Auto-deleveraging (ADL) indicator Divided into 5 levels, from 1 to 5, the smaller the number, the weaker the adl intensity. |
ccy | String | Currency used for margin |
last | String | Latest traded price |
cTime | String | Creation time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
uTime | String | Latest time position was adjusted, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Get Bills Details (last 7 days)
Retrieve the bills of the account. The bill refers to all transaction records that result in changing the balance of an account. Pagination is supported, and the response is sorted with the most recent first. This endpoint can retrieve data from the last 7 days.
Rate Limit: 6 requests per second
HTTP Request
GET /api/v5/account/bills
Request Example
GET /api/v5/account/bills
GET /api/v5/account/bills?instType=MARGIN
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instType | String | No | Instrument typeSPOT MARGIN SWAP FUTURES OPTION |
ccy | String | No | Currency |
mgnMode | String | No | Margin modeisolated cross |
ctType | String | No | Contract typelinear inverse Only applicable to FUTURES/SWAP |
type | String | No | Bill type1 : Transfer 2 : Trade 3 : Delivery 4 : Forced token conversion 5 : Liquidation 6 : Margin transfer 7 : Interest deduction 8 : Funding rate 9 : ADL 10 : Clawback |
subType | String | No | Bill subtype1 : Buy 2 : Sell 3 : Open long 4 : Open short 5 : Close long 6 : Close short 9 : Interest deduction 11 : Transfer in 12 : Transfer out 160 : Manual margin increase 161 : Manual margin decrease 162 : Auto margin increase 110 : Forced buy 111 : Forced sell 100 : Partial liquidation close long 101 : Partial liquidation close short 102 : Partial liquidation buy 103 : Partial liquidation sell 104 : Liquidation long 105 : Liquidation short 106 : Liquidation buy 107 : Liquidation sell 109 : Liquidation fees 110 : Liquidation transfer in 111 : Liquidation transfer out 125 : ADL close long 126 : ADL close short 127 : ADL buy 128 : ADL sell 170 : Exercised 171 : Counterparty exercised 172 : Expired OTM 112 : Delivery long 113 : Delivery short 117 : Delivery/Exercise clawback |
after | String | No | Pagination of data to return records earlier than the requested bill ID. |
before | String | No | Pagination of data to return records newer than the requested bill ID. |
limit | String | No | Number of results per request. The maximum is 100 . The default is 100 . |
Example Response
{
"code": "0",
"msg": "",
"data": [{
"instType": "FUTURES",
"instId": "BTC-USD-180216",
"billId": "1234",
"type": "1",
"subType": "1",
"balChg": "0.2",
"bal": "0.3",
"sz": "0.23",
"ccy": "BTC",
"mgnMode": "isolated",
"pnl": "1",
"fee": "0.01",
"ts": "1597026383085",
"ordId": "332233",
"from": "",
"to": "",
"notes": ""
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument type |
billId | String | Bill ID |
type | String | Bill type |
subType | String | Bill subtype |
ts | String | Creation time, Unix timestamp format in milliseconds, e.g.1597026383085 |
balChg | String | Change in balance amount at the account level |
posBalChg | String | Change in balance amount at the position level |
bal | String | Balance at the account level |
posBal | String | Balance at the position level |
sz | String | Quantity |
ccy | String | Account balance currency |
pnl | String | Profit and loss |
fee | String | Fee Negative number represents the user transaction fee charged by the platform. Positive number represents rebate. |
mgnMode | String | Margin modeisolated cross When bills are not generated by position changes, the field returns "" |
instId | String | Instrument ID, e.g. BTC-USD-190927-5000-C |
ordId | String | Order ID When bill type is not trade , the field returns "" |
from | String | The remitting account1 : SPOT 3 : FUTURES 5 : MARGIN 6 : FUNDING 9 : SWAP 12 : OPTION 18 : Portfolio MarginWhen bill type is not transfer , the field returns "". |
to | String | The beneficiary account1 : SPOT 3 : FUTURES 5 : MARGIN 6 : FUNDING 9 : SWAP 12 : OPTION 18 : Portfolio MarginWhen bill type is not transfer , the field returns "". |
notes | String | Notes When bill type is not transfer , the field returns "". |
Get Bills Details (last 3 months)
Retrieve the account’s bills. The bill refers to all transaction records that result in changing the balance of an account. Pagination is supported, and the response is sorted with most recent first. This endpoint can retrieve data from the last 3 months.
Rate Limit: 6 requests per second
HTTP Request
GET /api/v5/account/bills-archive
Request Example
GET /api/v5/account/bills-archive
GET /api/v5/account/bills-archive?instType=MARGIN
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instType | String | No | Instrument typeSPOT MARGIN SWAP FUTURES OPTION |
ccy | String | No | Currency |
mgnMode | String | No | Margin modeisolated cross |
ctType | String | No | Contract typelinear inverse Only applicable to FUTURES/SWAP |
type | String | No | Bill type1 : Transfer 2 : Trade 3 : Delivery 4 : Forced token conversion 5 : Liquidation 6 : Margin transfer 7 : Interest deduction 8 : Funding rate 9 : ADL 10 : Clawback |
subType | String | No | Bill subtype1 : Buy 2 : Sell 3 : Open long 4 : Open short 5 : Close long 6 : Close short 9 : Interest deduction 11 : Transfer in 12 : Transfer out 160 : Manual margin increase 161 : Manual margin decrease 162 : Auto margin increase 110 : Forced buy 111 : Forced sell 100 : Partial liquidation close long 101 : Partial liquidation close short 102 : Partial liquidation buy 103 : Partial liquidation sell 104 : Liquidation long 105 : Liquidation short 106 : Liquidation buy 107 : Liquidation sell 109 : Liquidation fees 110 : Liquidation transfer in 111 : Liquidation transfer out 125 : ADL close long 126 : ADL close short 127 : ADL buy 128 : ADL sell 170 : Exercised 171 : Counterparty exercised 172 : Expired OTM 112 : Delivery long 113 : Delivery short 117 : Delivery/Exercise clawback 173 : Funding fee expense 173 : Funding fee income |
after | String | No | Pagination of data to return records earlier than the requested bill ID. |
before | String | No | Pagination of data to return records newer than the requested bill ID. |
limit | String | No | Number of results per request. The maximum is 100 . The default is 100 . |
Example Response
{
"code": "0",
"msg": "",
"data": [{
"instType": "FUTURES",
"instId": "BTC-USD-180216",
"billId": "1234",
"type": "1",
"subType": "1",
"balChg": "0.2",
"bal": "0.3",
"sz": "0.23",
"ccy": "BTC",
"mgnMode": "isolated",
"pnl": "1",
"fee": "0.01",
"ts": "1597026383085",
"ordId": "332233",
"from": "",
"to": "",
"notes": ""
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument type |
billId | String | Bill ID |
type | String | Bill type |
subType | String | Bill subtype |
ts | String | Creation time, Unix timestamp format in milliseconds, e.g.1597026383085 |
balChg | String | Change in balance amount at the account level |
posBalChg | String | Change in balance amount at the position level |
bal | String | Balance at the account level |
posBalChg | String | Balance at the position level |
sz | String | The number |
ccy | String | Account balance currency |
pnl | String | Profit and loss |
fee | String | Fee Negative number represents the user transaction fee charged by the platform. Positive number represents rebate. |
mgnMode | String | Margin modeisolated cross When bills are not generated by position changes, the field returns "" |
instId | String | Instrument ID, e.g. BTC-USD-190927-5000-C |
ordId | String | Order ID When bill type is not trade , the field returns "" |
from | String | The remitting account1 : SPOT 3 : FUTURES 5 : MARGIN 6 : FUNDING 9 : SWAP 12 : OPTION 18 : Portfolio MarginWhen bill type is not transfer , the field returns "". |
to | String | The beneficiary account1 : SPOT 3 : FUTURES 5 : MARGIN 6 : FUNDING 9 : SWAP 12 : OPTION 18 : Portfolio MarginWhen bill type is not transfer , the field returns "". |
notes | String | Notes When bill type is not transfer , the field returns "". |
Get Account Configuration
Retrieve current account configuration.
Rate Limit: 5 requests per 2 seconds
HTTP Request
GET /api/v5/account/config
Request Example
GET /api/v5/account/config
Request Parameters
none
Example Response
{
"code": "0",
"msg": "",
"date": [{
"uid": "43812",
"acctLv": "2",
"posMode": "long_short_mode",
"autoLoan": true,
"greeksType": "BS"
}]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
uid | String | Account ID |
acctLv | String | Account level 1 : Simple account 2 : Single-currency margin account 3 : Multi-currency margin account |
posMode | String | Position modelong_short_mode : long/short, only applicable to FUTURES/SWAP net_mode : net |
autoLoan | Boolean | Whether to borrow coins automaticallytrue : borrow coins automatically false : not borrow coins automatically |
greeksType | String | Current display type of GreeksPA : Greeks in coins BS : Black-Scholes Greeks in dollars |
Set Position mode
FUTURES
and SWAP
support both long/short
mode and net
mode. In net
mode, users can only have positions in one direction; In long/short
mode, users can hold positions in long and short directions.
Rate Limit: 5 requests per 2 seconds
HTTP Request
POST /api/v5/account/set-position-mode
Request Example
POST /api/v5/account/set-position-mode
{"posMode":"long_short_mode"}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
posMode | String | Yes | Position modelong_short_mode : long/short, only applicable to FUTURES/SWAP net_mode : net |
Example Response
{
"code": "0",
"msg": "",
"data": [{
"posMode": "long_short_mode"
}]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
posMode | String | Position mode |
Set Leverage
The following are the setting leverage cases for an instrument:
Set leverage for isolated MARGIN at pairs level.
Set leverage for cross
MARGIN
in Single-currency margin
at pairs level.
Set leverage for cross
MARGIN
in Multi-currency margin
at currency level.
Set leverage for cross/isolated
FUTURES/SWAP
at underlying/contract level.
Rate Limit: 5 requests per 2 seconds
HTTP Request
POST /api/v5/account/set-leverage
Request Example
set leverage for isolated `MARGIN` at pairs level
POST /api/v5/account/set-leverage
body {"instId":"BTC-USDT","lever":"5","mgnMode":"isolated"}
set leverage for cross `MARGIN` in Single-currency margin account at pairs level
POST /api/v5/account/set-leverage
body {"instId":"BTC-USDT","lever":"5","mgnMode":"cross"}
set leverage for cross `MARGIN` in Multi-currency margin account at currency level
POST /api/v5/account/set-leverage
body {"ccy":"BTC","lever":"5","mgnMode":"cross"}
set leverage on long BTC-USDT-200802 for isolated `FUTURES`
POST /api/v5/account/set-leverage
body {"instId":"BTC-USDT-200802","lever":"5","posSide":"long","mgnMode":"isolated"}
set leverage for cross `FUTURES/SWAP` at underlying level
POST /api/v5/account/set-leverage
body {"instId":"BTC-USDT-200802","lever":"5","mgnMode":"cross"}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instId | String | Optional | Instrument ID Either instId or ccy is required; if both are passed, instId will be used by default. |
ccy | String | Optional | Currency used for margin Only applicable to cross MARGIN of Multi-currency margin |
lever | String | Yes | Leverage |
mgnMode | String | Yes | Margin modeisolated cross Only can be cross if ccy is passed. |
posSide | String | Optional | Position sidelong short net Required in long/short mode and when margin mode is isolated , only long or short can be passed.Only net can be passed in other cases.Only applicable to FUTURES/SWAP |
Example Response
{
"code": "0",
"msg": "",
"data": [
{
"lever": "30",
"mgnMode": "isolated",
"instId": "BTC-USDT-SWAP",
"posSide": "long"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
lever | String | Leverage |
mgnMode | String | Margin modecross isolated |
instId | String | Instrument ID |
posSide | String | Position side |
Get maximum buy/sell amount or open amount
Rate Limit: 20 requests per 2 seconds
HTTP Request
GET /api/v5/account/max-size
Request Example
GET /api/v5/account/max-size?instId=BTC-USDT&mgnMode=isolated
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instId | String | Yes | Instrument ID, e.g. BTC-USDT-200802 |
tdMode | String | Yes | Trade modecross isolated cash |
ccy | String | Optional | Currency used for margin Only applicable to MARGIN of Single-currency margin . |
px | String | No | Price When the price is not passed, it will be calculated according to the last traded price. |
Example Response
{
"code": "0",
"msg": "",
"data": [
{
"instId": "BTC-USDT-200802",
"maxBuy": "1",
"maxSell": "1"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instId | String | Instrument ID |
maxBuy | String | SPOT : The maximum number of coins that you can buyFUTURES /SWAP /OPTIONS : The maximum number of contracts that you can buy |
maxSell | String | SPOT : The maximum number of coins that you can sellFUTURES /SWAP /OPTIONS : The maximum number of contracts that you can sell |
Get Maximum Available Tradable Amount
Rate Limit: 20 requests per 2 seconds
HTTP Request
GET /api/v5/account/max-avail-size
Request Example
Query maximum available transaction amount when cross MARGIN BTC-USDT use BTC as margin
GET /api/v5/account/max-avail-size?instId=BTC-USDT&tdMode=cross&ccy=BTC
Query maximum available transaction amount for SPOT BTC-USDT
GET /api/v5/account/max-avail-size?instId=BTC-USDT&tdMode=cash
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instId | String | Yes | Instrument ID, e.g. BTC-USDT-200802 |
ccy | String | Optional | Currency used for margin Only applicable to cross MARGIN of Single-currency margin . |
tdMode | String | Yes | Trade modecross isolated cash |
reduceOnly | Boolean | No | Whether to reduce position only Only applicable to MARGIN |
Example Response
{
"code": "0",
"msg": "",
"data": [
{
"instId": "BTC-USDT-200802",
"availBuy": "1",
"availSell": "1"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instId | String | Instrument ID |
availBuy | String | Amount available to buy |
availSell | String | Amount available to sell |
Increase/Decrease margin
Increase or decrease the margin of the isolated position.
Rate Limit: 20 requests per 2 seconds
HTTP Request
POST /api/v5/account/position/margin-balance
Request Example
POST /api/v5/account/position/margin-balance
body {"instId":"BTC-USDT-200626","posSide":"short","type":"add","amt":"1"}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instId | String | Yes | Instrument ID |
posSide | String | Yes | Position side, the default is net long short net |
type | String | Yes | Typeadd reduce |
amt | String | Yes | Amount to be increased or decreased. |
Example Response
{
"code": "0",
"msg": "",
"data": [{
"instId": "BTC-USDT-200626",
"posSide": "short",
"amt": "1",
"type": "add"
}]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instId | String | Instrument ID |
posSide | String | Position side, long short |
amt | String | Amount to be increase or decrease |
type | String | Type |
Get Leverage
Rate Limit: 20 requests per 2 seconds
HTTP Request
GET /api/v5/account/leverage-info
Request Example
GET /api/v5/account/leverage-info?instId=BTC-USDT-200626&mgnMode=cross
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instId | String | Yes | Instrument ID |
mgnMode | String | Yes | Margin modecross isolated |
Example Response
{
"code": "0",
"msg": "",
"data": [{
"instId": "BTC-USDT-200626",
"mgnMode": "cross",
"posSide": "long",
"lever": "10"
},{
"instId": "BTC-USDT-200626",
"mgnMode": "cross",
"posSide": "short",
"lever": "10"
}]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instId | String | Instrument ID |
mgnMode | String | Margin mode |
posSide | String | Position sidelong short net Only applicable to FUTURES/SWAP In long/short mode, the leverage in both directions long short will be returned. |
lever | String | Leverage |
Get the maximum loan of isolated MARGIN
Rate Limit: 20 requests per 2 seconds
HTTP Request
GET /api/v5/account/max-loan
Request Example
GET /api/v5/account/max-loan?instId=BTC-USDT
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instId | String | Yes | Instrument ID Only applicable to MARGIN |
Example Response
{
"code": "0",
"msg": "",
"data": [{
"instId": "BTC-USDT",
"maxLoan": "0.1",
"ccy": "BTC"
},
{
"instId": "BTC-USDT",
"maxLoan": "0.2",
"ccy": "USDT"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instId | String | Instrument ID |
maxLoan | String | Max loan |
ccy | String | Currency |
Get Fee Rates
Rate Limit: 5 requests per 2 seconds
HTTP Request
GET /api/v5/account/trade-fee
Request Example
Query trade fee rate of SPOT BTC-USDT
GET /api/v5/account/trade-fee?instType=SPOT&instId=BTC-USDT
Query trade fee rate in Tier 1
GET /api/v5/account/trade-fee?instType=SWAP&category=1
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instType | String | Yes | Instrument typeSPOT MARGIN SWAP FUTURES OPTION |
instId | String | Optional | Instrument ID, e.g. BTC-USDT only applicable to FUTURES/SWAP/OPTION |
uly | String | Optional | Underlying, e.g. BTC-USD only applicable to FUTURES/SWAP/OPTION |
category | String | Optional | Fee Schedule1 : Tier 12 : Tier 2 3 : Tier 34 : Tier 4 |
Example Response
{
"code": "0",
"msg": "",
"data": [{
"category": "1",
"delivery": "",
"exercise": "",
"instType": "SPOT",
"level": "101",
"maker": "-0.001",
"taker": "-0.0015",
"ts": "1608623351857"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
category | String | Fee Schedule |
taker | String | Taker fee rate |
maker | String | Maker fee rate |
delivery | String | Delivery fee rate |
exercise | String | Fee rate for exercising the option |
level | String | Fee rate Level |
instType | String | Instrument type |
ts | String | Data return time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Get interest-accrued
Rate Limit: 5 requests per 2 seconds
HTTP Request
GET /api/v5/account/interest-accrued
Request Example
GET /api/v5/account/interest-accrued
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instId | String | No | Instrument ID, e.g. BTC-USDT Only applicable to MARGIN |
ccy | String | No | Currency, e.g. BTC |
mgnMode | String | No | Margin modecross isolated |
after | String | No | Pagination of data to return records earlier than the requested ts, Unix timestamp format in milliseconds, e.g. 1597026383085 |
before | String | No | Pagination of data to return records newer than the requested ts, Unix timestamp format in milliseconds, e.g. 1597026383085 |
limit | String | No | Number of results per request. The maximum is 100 ; The default is 100 |
Example Response
{
"code": "0",
"msg": "",
"data": [{
"instId": "BTC-USDT",
"ccy": "USDT",
"mgnMode": "cross",
"interest": "0.02",
"ts": "1597026383085"
},
{
"instId": "BTC-USDT",
"ccy": "USDT",
"mgnMode": "cross",
"interest": "0.02",
"ts": "1597026383085"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instId | String | Instrument ID |
ccy | String | Currency |
mgnMode | String | Margin mode |
interest | String | Interest |
ts | String | Interest calculation time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Set Greeks (PA/BS)
Set the display type of Greeks.
Rate Limit: 5 requests per 2 seconds
HTTP Request
POST /api/v5/account/set-greeks
Request Example
POST /api/v5/account/set-greeks
body {"greeksType":"PA"}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
greeksType | String | Yes | Display type of Greeks.PA : Greeks in coinsBS : Black-Scholes Greeks in dollars |
Example Response
{
"code": "0",
"msg": "",
"data": [{
"greeksType": "PA"
}]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
greeksType | String | Display type of Greeks. |
Get Maximum Withdrawals
Retrieve the maximum transferable amount.
Rate Limit: 20 requests per 2 seconds
HTTP Request
GET /api/v5/account/max-withdrawal
Request Example
GET /api/v5/account/max-withdrawal
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ccy | String | No | Currency, e.g. BTC |
Example Response
{
"code": "0",
"msg": "",
"data": [{
"ccy": "BTC",
"maxWd": "124"
},
{
"ccy": "ETH",
"maxWd": "10"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
maxWd | String | Max withdrawal |
ccy | String | Currency |
Funding
The API endpoints of Funding
require authentication.
Get Deposit Address
Retrieve the deposit addresses of currencies, including previously-used addresses.
Rate Limit: 6 requests per second
HTTP Request
GET /api/v5/asset/deposit-address
Request Example
GET /api/v5/asset/deposit-address?ccy=BTC
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ccy | String | Yes | Currency, e.g. BTC |
Example Response
{
"code": "0",
"msg": "",
"data": [{
"addr": "okbtothemoon",
"memo": "971668",
"ccy": "BTC",
"to": "6"
}]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
addr | String | Deposit address |
tag | String | Deposit tag (This will not be returned if the currency does not require a tag for deposit) |
memo | String | Deposit memo (This will not be returned if the currency does not require a payment_id for deposit) |
pmtId | String | Deposit payment ID (This will not be returned if the currency does not require a payment_id for deposit) |
ccy | String | Currency, e.g. BTC |
to | String | The beneficiary account 1 : SPOT 3 : FUTURES 6 : FUNDING 9 : SWAP 12 : OPTION 18 : Portfolio Margin |
Get Balance
Retrieve the balances of all the assets, and the amount that is available or on hold.
Rate Limit: 6 requests per second
HTTP Request
GET /api/v5/asset/balances
Request Example
GET /api/v5/asset/balances
Request Parameters
Parameters | Types | Required | Description |
---|---|---|---|
ccy | String | No | Single currency or multiple currencies (no more than 20) separated with comma, e.g. BTC or BTC,ETH . |
Example Response
{
"code": "0",
"msg": "",
"data": [{
"availBal": "37.11827078",
"bal": "37.11827078",
"ccy": "ETH",
"frozenBal": "0"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ccy | String | Currency |
bal | String | Balance |
frozenBal | String | Frozen balance |
availBal | String | Available balance |
Funds Transfer
This endpoint supports the transfer of funds between your funding account and trading account, and from the master account to sub-accounts. Direct transfers between sub-accounts are not allowed.
Rate Limit: 6 requests per second
HTTP Request
POST /api/v5/asset/transfer
Request Example
Transfer 1.5 USDT from funding account to Portfolio Margin when current account is master-account
POST /api/v5/asset/transfer
body {"ccy":"USDT","amt":"1.5","from":"6","to":"18"}
Transfer 1.5 USDT from funding account to subAccount when current account is master-account
POST /api/v5/asset/transfer
body {"ccy":"USDT","type":"1","amt":"1.5","from":"6","to":"6","subAcct":"mini"}
Transfer 2 USDT from Portfolio Margin to FUTURES account BTC-USDT when current account is master-account
POST /api/v5/asset/transfer
body {"ccy":"USDT","amt":"2","from":"18","to":"3","toInstId":"BTC-USD"}
Transfer 2 USDT from Portfolio Margin to SPOT account BTC-USDT when current account is master-account
POST /api/v5/asset/transfer
body {"ccy":"USDT","amt":"2","from":"18","to":"5","toInstId":"BTC-USDT"}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ccy | String | Yes | Currency, e.g. USDT |
amt | String | Yes | Amount to be transferred |
type | String | No | Transfer type0 : between accounts in the master account1 : master account to sub-account2 : sub-account to master accountthe default is 0 |
from | String | Yes | The remitting account1 : SPOT 3 : FUTURES 5 : MARGIN 6 : FUNDING 9 : SWAP 12 : OPTION 18 : Portfolio Margin |
to | String | Yes | The beneficiary account1 : SPOT 3 : FUTURES 5 : MARGIN 6 : FUNDING 9 : SWAP 12 : OPTION 18 : Portfolio Margin |
subAcct | String | Optional | Name of the sub-account When type is 1, sub-account is required. |
instId | String | Optional | MARGIN trading pair (e.g. BTC-USDT ) or contract underlying (e.g. BTC-USD ) to be transferred out. |
toInstId | String | Optional | MARGIN trading pair (e.g. BTC-USDT ) or contract underlying (e.g. BTC-USD ) to be transferred in. |
Example Response
{
"code": "0",
"msg": "",
"data": [{
"transId": "754147",
"ccy": "USDT",
"from": "6",
"amt": "0.1",
"to": "18"
}]
}
Response Parameters
Example Response
Parameter | Type | Description |
---|---|---|
transId | String | TransferID |
ccy | String | Currency |
from | String | The remitting account |
amt | String | Transfer amount |
to | String | The beneficiary account |
Withdrawal
Withdrawal of tokens.
Rate Limit: 6 requests per second
HTTP Request
POST /api/v5/asset/withdrawal
Request Example
POST /api/v5/asset/withdrawal
body {"amt":"1","fee":"0.0005","pwd":"123456","dest":"4","ccy":"BTC","toAddr":"17DKe3kkkkiiiiTvAKKi2vMPbm1Bz3CMKw"}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ccy | String | Yes | Currency, e.g. USDT |
amt | String | Yes | Withdrawal amount |
dest | String | Yes | Withdrawal destination address3 : OKEx4 : Digital currency address68 : Coinall69 : OKGAEX71 : OCNEX75 : Bbang89 : TOKR90 : AAAAEX108 : 99EX113 : EthEx.com125 : PICKCOIN136 : Fintechonex141 : iEx142 : Exipfs147 : VitBlock152 : xFutures153 : Float SV158 : LXG161 : BITAIEX163 : Boomex172 : 66ex 173 : VVcoin175 : JIAMIX178 : 73ex180 : Newbit185 : UnicornX186 : GazuaX187 : ETF.Pro188 : EGEMoney189 : WaterCoin |
toAddr | String | Yes | Verified digital currency address, email or mobile number. Some digital currency addresses are formatted as 'address+tag' , e.g. 'ARDOR-7JF3-8F2E-QUWZ-CAN7F:123456' |
pwd | String | Yes | Trade password |
fee | String | Yes | Transaction fee |
Example Response
{
"code": "0",
"msg": "",
"data": [{
"amt": "0.1",
"wdId": "67485",
"ccy": "BTC"
}]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ccy | String | Currency |
amt | String | Withdrawal amount |
wdId | String | Withdrawal ID |
Get Deposit History
Retrieve the deposit history of all currencies, up to 100 recent records in a year.
Rate Limit: 6 requests per second
HTTP Request
GET /api/v5/asset/deposit-history
Request Example
GET /api/v5/asset/deposit-history
Query deposit history from 2018-09-29 to 2018-10-30
GET /api/v5/asset/deposit-history?ccy=BTC&after=1597026383085&before=1597026383085
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ccy | String | No | Currency, e.g. BTC |
state | String | No | Status of deposit 0 : waiting for confirmation 1 : deposit credited 2 : deposit successful |
after | String | No | Pagination of data to return records earlier than the requested ts, Unix timestamp format in milliseconds, e.g. 1597026383085 |
before | String | No | Pagination of data to return records newer than the requested ts, Unix timestamp format in milliseconds, e.g. 1597026383085 |
limit | string | No | Number of results per request. The maximum is 100 ; The default is 100 |
Example Response
{
"code": "0",
"msg": "",
"data": [{
"amt": "0.01044408",
"txId": "1915737_3_0_0_asset",
"ccy": "BTC",
"from": "13801825426",
"to": "",
"ts": "1597026383085",
"state": "2",
"depId": "4703879"
},
{
"amt": "491.6784211",
"txId": "1744594_3_184_0_asset",
"ccy": "OKB",
"from": "",
"to": "",
"ts": "1597026383085",
"state": "2",
"depId": "4703809"
},
{
"amt": "223.18782496",
"txId": "6d892c669225b1092c780bf0da0c6f912fc7dc8f6b8cc53b003288624c",
"ccy": "USDT",
"from": "",
"to": "39kK4XvgEuM7rX9frgyHoZkWqx4iKu1spD",
"ts": "1597026383085",
"state": "2",
"depId": "4703779"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ccy | String | Currency |
amt | String | Deposit amount |
from | String | Only the internal OKEx account is returned, not the address on the blockchain. |
to | String | Deposit address |
txId | String | Hash record of the deposit |
ts | String | Time that the deposit is credited, Unix timestamp format in milliseconds, e.g. 1597026383085 |
state | String | Status of deposit 0 : waiting for confirmation 1 : deposit credited 2 : deposit successful |
depId | String | Deposit ID |
Get Withdrawal History
Retrieve the withdrawal records according to the currency, withdrawal status, and time range in reverse chronological order. The 100 most recent records are returned by default.
Rate Limit: 6 requests per second
HTTP Request
GET /api/v5/asset/withdrawal-history
Request Example
GET /api/v5/asset/withdrawal-history
Query withdrawal history from 2018-09-29 to 2018-10-30
GET /api/v5/asset/withdrawal-history?ccy=BTC&after=1597026383085&before=1597026383085
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ccy | String | No | Currency, e.g. BTC |
state | String | No | Status of withdrawal-3 : pending cancel -2 : canceled -1 : failed 0 : pending 1 :sending 2 : sent 3 : awaiting email verification 4 : awaiting manual verification 5 : awaiting identity verification |
after | String | No | Pagination of data to return records earlier than the requested ts, Unix timestamp format in milliseconds, e.g. 1597026383085 |
before | String | No | Pagination of data to return records newer than the requested ts, Unix timestamp format in milliseconds, e.g. 1597026383085 |
limit | String | No | Number of results per request. The maximum is 100 ; The default is 100 |
Example Response
{
"code": "0",
"msg": "",
"data": [{
"amt": "0.094",
"wdId": "4703879",
"fee": "0.01000000eth",
"txId": "0x62477bac6509a04512819bb1455e923a60dea5966c7caeaa0b24eb8fb0432b85",
"ccy": "ETH",
"from": "13426335357",
"to": "0xA41446125D0B5b6785f6898c9D67874D763A1519",
"ts": "1597026383085",
"state": "2"
},
{
"amt": "0.01",
"wdId": "4703879",
"fee": "0.00000000btc",
"txId": "",
"ccy": "BTC",
"from": "13426335357",
"to": "13426335357",
"ts": "1597026383085",
"state": "2"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ccy | String | Currency |
amt | String | Token amount |
ts | String | Time the withdrawal request was submitted, Unix timestamp format in milliseconds, e.g. 1597026383085 . |
from | String | Remitting address User account ID will be shown for OKEx addresses. |
to | String | Receiving address |
tag | String | Some currencies require a tag for withdrawals. This is not returned if not required. |
pmtId | String | Some currencies require a payment ID for withdrawals. This is not returned if not required. |
memo | String | Some currencies require this parameter for withdrawals. This is not returned if not required. |
txId | String | Hash record of the withdrawal. This parameter will not be returned for internal transfers. |
fee | String | Withdrawal fee |
state | String | Status of withdrawal |
wdId | String | Withdrawal ID |
Get Currencies
Retrieve a list of all currencies. Not all currencies can be traded. Currencies that have not been defined in ISO 4217 may use a custom symbol.
Rate Limit: 6 requests per second
HTTP Request
GET /api/v5/asset/currencies
Request Example
GET /api/v5/asset/currencies
Request Parameters
none
Example Response
{
"code": "0",
"msg": "",
"data": [{
"ccy": "BTC",
"chain":"",
"name": "",
"canDep": true,
"canWd": true,
"canInternal": true,
"minWd": "0.01",
"maxFee":"0.02",
"minFee":"0.0005"
},
{
"ccy": "USDT",
"chain":"USDT-ERC20",
"name": "",
"canDep": true,
"canWd": true,
"minWd": "0.1",
"maxFee":"0.2",
"minFee":"0.01"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ccy | String | Currency, e.g. BTC |
name | String | Currency |
chain | String | Chain name, e.g. USDT-ERC20 , USDT-TRC20 , USDT-OMIN |
canDep | Boolean | Availability to deposit from chain.false : not available true : available |
canWd | Boolean | Availability to withdraw to chain.false : not available true : available |
canInternal | Boolean | Availability to internal transfer.false : not available true : available |
minWd | String | Minimum withdrawal threshold |
minFee | String | Minimum withdrawal fee |
maxFee | String | Maximum withdrawal fee |
PiggyBank Purchase/Redemption
Rate Limit: 6 requests per second
HTTP Request
POST /api/v5/asset/purchase_redempt
Request Example
POST /api/v5/asset/purchase_redempt
body {"ccy":"BTC","amt":"1","side":"purchase"}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ccy | String | Yes | Currency, e.g. BTC |
amt | String | Yes | Purchase/redemption amount |
side | String | Yes | Action type.purchase : purchase PiggyBank sharesredempt : redeem PiggyBank shares |
Example Response
{
"code":"0",
"msg":"",
"data":[
{
"ccy":"BTC",
"amt":"1",
"side":"purchase"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ccy | String | Currency |
amt | String | Purchase/redemption amount |
side | String | Action type |
Asset Bills Details
Rate Limit: 6 Requests per second
HTTP Request
GET /api/v5/asset/bills
Request Example
GET /api/v5/asset/bills
GET /api/v5/asset/bills?type=1
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ccy | String | Yes | Currency |
type | String | No | Bill type1 : Deposit2 : Withdrawal13 : Canceled withdrawal18 : Transfer to futures19 : Transfer from futures20 : Transfer to Sub account21 : Transfer from Sub account28 : Claim33 : Transfer to margin34 : Transfer from margin41 : Trading fees settled by loyalty points42 : Loyalty points purchase47 : System reversal48 : Received from activities49 : Given away to activities50 : Received from appointments51 : Deducted from appointments52 : Red packet sent53 : Red packet snatched54 : Red packet refunded55 : Transfer to perpetual56 : Transfer from perpetual59 : Transfer from hedging account60 : Transfer to hedging account61 : Conversion63 : Transfer to options62 : Transfer from options68 : Claim rebate card69 : Distribute rebate card72 : Token received73 : Token given away74 : Token refunded75 : Subscription to savings76 : Redemption to savings77 : Distribute78 : Lock up79 : Node voting80 : Staking81 : Vote redemption82 : Staking redemption83 : Staking yield84 : Violation fee85 : PoW mining yield86 : Cloud mining pay87 : Cloud mining yield88 : Subsidy89 : Staking90 : Staking subscription91 : staking redemption92 : Add collateral93 : Redeem collateral94 : Investment95 : Borrower borrows96 : Principal transferred in97 : Borrower transferred loan out98 : Borrower transferred interest out99 : Investor transferred interest in102 : Prepayment penalty transferred in103 : Prepayment penalty transferred out104 : Fee transferred in105 : Fee transferred out106 : Overdue fee transferred in107 : Overdue fee transferred out108 : Overdue interest transferred out109 : Overdue interest transferred in110 : Collateral for closed position transferred in111 : Collateral for closed position transferred out112 : Collateral for liquidation transferred in113 : Collateral for liquidation transferred out114 : Insurance fund transferred in115 : Insurance fund transferred out 116 : Place an order117 : Fulfill an order118 : Cancel an order119 : Merchants unlock deposit120 : Merchants add deposit121 : FiatGateway Place an order122 : FiatGateway Cancel an order123 : FiatGateway Fulfill an order124 : Jumpstart unlocking125 : Manual deposit126 : Interest deposit127 : Investment fee transferred in128 : Investment fee transferred out129 : Rewards transferred in130 : Transferred from unified account131 : Transferred to unified account |
after | String | No | Pagination of data to return records earlier than the requested ts, Unix timestamp format in milliseconds, e.g. 1597026383085 |
before | String | No | Pagination of data to return records newer than the requested ts, Unix timestamp format in milliseconds, e.g. 1597026383085 |
limit | String | No | Number of results per request. The maximum is 100 ; the default is 100 . |
Example Response
{
"code": "0",
"msg": "",
"data": [{
"billId": "12344",
"ccy": "BTC",
"balChg": "2",
"bal": "12",
"type": "1",
"ts": "1597026383085"
}]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
billId | String | Bill ID |
ccy | String | Account balance currency |
balChg | String | Change in balance at the account level |
bal | String | Balance at the account level |
type | String | Bill type |
ts | String | Creation time, Unix timestamp format in milliseconds, e.g.1597026383085 |
Market Data
The API endpoints of Market Data
do not require authentication.
Get Tickers
Retrieve the latest price snapshot, best bid/ask price, and trading volume in the last 24 hours.
Rate Limit: 20 requests per 2 seconds
HTTP Request
GET /api/v5/market/tickers
Request Example
GET /api/v5/market/tickers?instType=SWAP
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instType | String | Yes | Instrument typeSPOT SWAP FUTURES OPTION |
uly | String | No | Underlying, e.g. BTC-USD Only applicable to FUTURES/SWAP/OPTION |
Example Response
{
"code":"0",
"msg":"",
"data":[
{
"instType":"SWAP",
"instId":"LTC-USD-SWAP",
"last":"9999.99",
"lastSz":"0.1",
"askPx":"9999.99",
"askSz":"11",
"bidPx":"8888.88",
"bidSz":"5",
"open24h":"9000",
"high24h":"10000",
"low24h":"8888.88",
"volCcy24h":"2222",
"vol24h":"2222",
"sodUtc0":"2222",
"sodUtc8":"2222",
"ts":"1597026383085"
},
{
"instType":"SWAP",
"instId":"BTC-USD-SWAP",
"last":"9999.99",
"lastSz":"0.1",
"askPx":"9999.99",
"askSz":"11",
"bidPx":"8888.88",
"bidSz":"5",
"open24h":"9000",
"high24h":"10000",
"low24h":"8888.88",
"volCcy24h":"2222",
"vol24h":"2222",
"sodUtc0":"2222",
"sodUtc8":"2222",
"ts":"1597026383085"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument type |
instId | String | Instrument ID |
last | String | Last traded price |
lastSz | String | Last traded size |
askPx | String | Best ask price |
askSz | String | Best ask size |
bidPx | String | Best bid price |
bidSz | String | Best bid size |
open24h | String | Open price in the past 24 hours |
high24h | String | Highest price in the past 24 hours |
low24h | String | Lowest price in the past 24 hours |
volCcy24h | String | Trading volume in the past 24 hours |
vol24h | String | Trading volume in the past 24 hours |
sodUtc0 | String | Open price in the UTC 0 |
sodUtc8 | String | Open price in the UTC 8 |
ts | String | Ticker data generation time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Get Ticker
Retrieve the latest price snapshot, best bid/ask price, and trading volume in the last 24 hours.
Rate Limit: 20 requests per 2 seconds
HTTP Request
GET /api/v5/market/ticker
Request Example
GET /api/v5/market/ticker?instId=BTC-USD-SWAP
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instId | String | Yes | Instrument ID, e.g. BTC-USD-SWAP |
Example Response
{
"code":"0",
"msg":"",
"data":[
{
"instType":"SWAP",
"instId":"BTC-USD-SWAP",
"last":"9999.99",
"lastSz":"0.1",
"askPx":"9999.99",
"askSz":"11",
"bidPx":"8888.88",
"bidSz":"5",
"open24h":"9000",
"high24h":"10000",
"low24h":"8888.88",
"volCcy24h":"2222",
"vol24h":"2222",
"sodUtc0":"2222",
"sodUtc8":"2222",
"ts":"1597026383085"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument type |
instId | String | Instrument ID |
last | String | Last traded price |
lastSz | String | Last traded size |
askPx | String | Best ask price |
askSz | String | Best ask size |
bidPx | String | Best bid price |
bidSz | String | Best bid size |
open24h | String | Open price in the past 24 hours |
high24h | String | Highest price in the past 24 hours |
low24h | String | Lowest price in the past 24 hours |
volCcy24h | String | Trading volume in the past 24 hours |
vol24h | String | Trading volume in the past 24 hours |
sodUtc0 | String | Open price in the UTC 0 |
sodUtc8 | String | Open price in the UTC 8 |
ts | String | Ticker data generation time, Unix timestamp format in milliseconds, e.g. 1597026383085 . |
Get Index Tickers
Retrieve index tickers.
Rate Limit: 20 requests per 2 seconds
HTTP Request
GET /api/v5/market/index-tickers
Request Example
GET /api/v5/market/index-tickers?quoteCcy=BTC
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
quoteCcy | String | Optional | Quote currency Currently there is only an index with USD/USDT/BTC as the quote currency. |
instId | String | Optional | Index, e.g. BTC-USD Either quoteCcy or instId is required. |
Example Response
{
"code":"0",
"msg":"",
"data":[
{
"instId":"BTC-USDT",
"idxPx":"0.1",
"high24h":"0.5",
"low24h":"0.1",
"open24h":"0.1",
"sodUtc0":"2222",
"sodUtc8":"2222",
"ts":"1597026383085"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instId | String | Index |
idxPx | String | Latest index price |
high24h | String | Highest price in the past 24 hours |
low24h | String | Lowest price in the past 24 hours |
open24h | String | Open price in the past 24 hours |
sodUtc0 | String | Open price in the UTC 0 |
sodUtc8 | String | Open price in the UTC 8 |
ts | String | Update time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Get Order Book
Retrieve a instrument's order book.
Rate Limit: 20 requests per 2 seconds
HTTP Request
GET /api/v5/market/books
Request Example
GET /api/v5/market/books?instId=BTC-USD-SWAP
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instId | String | Yes | Instrument ID, e.g. BTC-USD-190927-5000-C |
sz | String | No | Order book depth per side. Maximum 200, e.g. 200 bids + 200 asks Default returns to 1 depth data |
Example Response
{
"code":"0",
"msg":"",
"data":[
{
"asks":[
[
"411.8","10","0","8"
],
[
"1","2","3","6"
]
],
"bids":[
[
"1","2","3","6"
],
[
"1","2","3","6"
]
],
"ts":"1597026383085"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
asks | Array | Order book on sell side |
bids | Array | Order book on buy side |
ts | String | Order book generation time |
Get Candlesticks
Retrieve the candlestick charts. This endpoint can retrieve the latest 1,440 data entries. Charts are returned in groups based on the requested bar.
Rate Limit: 20 requests per 2 seconds
HTTP Request
GET /api/v5/market/candles
Request Example
GET /api/v5/market/candles?instId=BTC-USD-190927-5000-C
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instId | String | Yes | Instrument ID, e.g. BTC-USD-190927-5000-C |
after | String | No | Pagination of data to return records earlier than the requested ts |
before | String | No | Pagination of data to return records newer than the requested ts |
bar | String | No | Bar size, the default is 1m e.g. [1m/3m/5m/15m/30m/1H/2H/4H/6H/12H/1D/1W/1M/3M/6M/1Y] |
limit | String | No | Number of results per request. The maximum is 100 ; The default is 100 . |
Example Response
{
"code":"0",
"msg":"",
"data":[
[
"1597026383085",
"3.721",
"3.743",
"3.677",
"3.708",
"8422410",
"22698348.04828491"
],
[
"1597026383085",
"3.731",
"3.799",
"3.494",
"3.72",
"24912403",
"67632347.24399722"
]
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ts | String | Data generation time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
o | String | Open price |
h | String | Higest price |
l | String | Lowest price |
c | String | Close price |
vol | String | Trading volume (cont) |
volCcy | String | Trading volume (coin) |
Get Candlesticks History(top currencies only)
Retrieve history candlestick charts from recent years.
Rate Limit: 20 requests per 2 seconds
HTTP Request
GET /api/v5/market/history-candles
Request Example
GET /api/v5/market/history-candles?instId=BTC-USD-190927
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instId | String | Yes | Instrument ID, e.g. BTC-USD-200927 |
after | String | No | Pagination of data to return records earlier than the requested ts |
before | String | No | Pagination of data to return records newer than the requested ts |
bar | String | No | Bar size, the default is 1m e.g. [1m/3m/5m/15m/30m/1H/2H/4H/6H/12H/1D/1W/1M/3M/6M/1Y] |
limit | String | No | Number of results per request. The maximum is 100 ; the default is 100 . |
Example Response
{
"code":"0",
"msg":"",
"data":[
[
"1597026383085",
"3.721",
"3.743",
"3.677",
"3.708",
"8422410",
"22698348.04828491"
],
[
"1597026383085",
"3.731",
"3.799",
"3.494",
"3.72",
"24912403",
"67632347.24399722"
]
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ts | String | Data generation time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
o | String | Open price |
h | String | Highest price |
l | String | Lowest price |
c | String | Close price |
vol | String | Trading volume (cont) |
volCcy | String | Trading volume (coin) |
Get Index Candlesticks
Retrieve the candlestick charts of the index. This endpoint can retrieve the latest 1,440 data entries. Charts are returned in groups based on the requested bar.
Rate Limit: 20 requests per 2 seconds
HTTP Request
GET /api/v5/market/index-candles
Request Example
GET /api/v5/market/index-candles?instId=BTC-USD
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instId | String | Yes | Index, e.g. BTC-USD |
after | String | No | Pagination of data to return records earlier than the requested ts |
before | String | No | Pagination of data to return records newer than the requested ts |
bar | String | No | Bar size, the default is 1m e.g. [1m/3m/5m/15m/30m/1H/2H/4H/6H/12H/1D/1W/1M/3M/6M/1Y] |
limit | String | No | Number of results per request. The maximum is 100 ; The default is 100 |
Example Response
{
"code":"0",
"msg":"",
"data":[
[
"1597026383085",
"3.721",
"3.743",
"3.677",
"3.708"
],
[
"1597026383085",
"3.731",
"3.799",
"3.494",
"3.72"
]
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ts | String | Data generation time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
o | String | Open price |
h | String | Higest price |
l | String | Lowest price |
c | String | Close price |
Get Mark Price Candlesticks
Retrieve the candlestick charts of mark price. This endpoint can retrieve the latest 1,440 data entries. Charts are returned in groups based on the requested bar.
Rate Limit: 20 requests per 2 seconds
HTTP Request
GET /api/v5/market/mark-price-candles
Request Example
GET /api/v5/market/mark-price-candles?instId=BTC-USD-SWAP
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instId | String | Yes | Instrument ID, e.g. BTC-USD-SWAP |
after | String | No | Pagination of data to return records earlier than the requested ts |
before | String | No | Pagination of data to return records newer than the requested ts |
bar | String | No | Bar size, the default is 1m e.g. [1m/3m/5m/15m/30m/1H/2H/4H/6H/12H/1D/1W/1M/3M/6M/1Y] |
limit | String | No | Number of results per request. The maximum is 100 ; The default is 100 |
Example Response
{
"code":"0",
"msg":"",
"data":[
[
"1597026383085",
"3.721",
"3.743",
"3.677",
"3.708"
],
[
"1597026383085",
"3.731",
"3.799",
"3.494",
"3.72"
]
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ts | String | Data generation time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
o | String | Open price |
h | String | Higest price |
l | String | Lowest price |
c | String | Close price |
Get Trades
Retrieve the recent transactions of an instrument.
Rate Limit: 20 requests per 2 seconds
HTTP Request
GET /api/v5/market/trades
Request Example
GET /api/v5/market/trades?instId=BTC-USDT
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instId | String | Yes | Instrument ID, e.g. BTC-USD |
limit | String | No | Number of results per request. The maximum is 100 ; The default is 100 |
Example Response
{
"code":"0",
"msg":"",
"data":[
{
"instId":"BTC-USDT",
"tradeId":"9",
"px":"0.016",
"sz":"50",
"side":"buy",
"ts":"1597026383085"
},
{
"instId":"BTC-USDT",
"tradeId":"9",
"px":"0.016",
"sz":"50",
"side":"buy",
"ts":"1597026383085"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instId | String | Instrument ID |
tradeId | String | Trade ID |
px | String | Trade price |
sz | String | Trade quantity |
side | String | Trade sidebuy sell |
ts | String | Trade time, Unix timestamp format in milliseconds, e.g. 1597026383085 . |
Public Data
The API endpoints of Public Data
do not require authentication.
Get Instruments
Retrieve a list of instruments with open contracts.
Rate Limit: 20 requests per 2 seconds
HTTP Request
GET /api/v5/public/instruments
Request Example
GET /api/v5/public/instruments?instType=SPOT
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instType | String | Yes | Instrument typeSPOT SWAP FUTURES OPTION |
uly | String | Optional | Underlying Only applicable to FUTURES/SWAP/OPTION . Required for OPTION . |
instId | String | No | Instrument ID |
Example Response
{
"code":"0",
"msg":"",
"data":[
{
"instType":"SWAP",
"instId":"LTC-USD-SWAP",
"uly":"LTC-USD",
"category":"1",
"baseCcy":"",
"quoteCcy":"",
"settleCcy":"LTC",
"ctVal":"10",
"ctMult":"1",
"ctValCcy":"USD",
"optType":"C",
"stk":"",
"listTime":"1597026383085",
"expTime":"1597026383085",
"lever":"10",
"tickSz":"0.01",
"lotSz":"1",
"minSz":"1",
"ctType":"linear",
"alias":"this_week",
"state":"live"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument type |
instId | String | Instrument ID, e.g. BTC-USD-SWAP |
uly | String | Underlying, e.g. BTC-USD Only applicable to FUTURES/SWAP/OPTION |
category | String | Fee schedule |
baseCcy | String | Base currency, e.g. BTC inBTC-USDT Only applicable to SPOT |
quoteCcy | String | Quote currency, e.g. USDT in BTC-USDT Only applicable to SPOT |
settleCcy | String | Settlement and margin currency, e.g. BTC Only applicable to FUTURES/SWAP/OPTION |
ctVal | String | Contract value Only applicable to FUTURES/SWAP/OPTION |
ctMult | String | Contract multiplier Only applicable to FUTURES/SWAP/OPTION |
ctValCcy | String | Contract value currency Only applicable to FUTURES/SWAP/OPTION |
optType | String | Option type, C : Call P : putOnly applicable to OPTION |
stk | String | Strike price Only applicable to OPTION |
listTime | String | Listing time, Unix timestamp format in milliseconds, e.g. 1597026383085 Only applicable to FUTURES/OPTION |
expTime | String | Expiry time, Unix timestamp format in milliseconds, e.g. 1597026383085 Only applicable to FUTURES/OPTION |
lever | String | Leverage, Not applicable to SPOT , used to distinguish between MARGIN and SPOT . |
tickSz | String | Tick size, e.g. 0.0001 |
lotSz | String | Lot size, e.g. BTC-USDT-SWAP: 1 |
minSz | String | Minimum order size |
ctType | String | Contract typelinear : linear contractinverse : inverse contractOnly applicable to FUTURES/SWAP |
alias | String | Aliasthis_week next_week quarter next_quarter Only applicable to FUTURES |
state | String | Instrument statuslive suspend preopen |
Get Delivery/Exercise History
Retrieve the estimated delivery price, which will only have a return value one hour before the delivery/exercise.
Rate Limit: 40 requests per 2 seconds
HTTP Request
GET /api/v5/public/delivery-exercise-history
Request Example
GET /api/v5/public/delivery-exercise-history?instType=OPTION&Underlying=BTC-USD
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instType | String | Yes | Instrument typeFUTURES OPTION |
uly | String | Yes | Underlying, only applicable to FUTURES/OPTION |
after | String | No | Pagination of data to return records earlier than the requested ts |
before | String | No | Pagination of data to return records newer than the requested ts |
limit | String | No | Number of results per request. The maximum is 100 ; The default is 100 |
Example Response
{
"code":"0",
"msg":"",
"data":[
{
"ts":"1597026383085",
"details":[
{
"type":"delivery",
"insId":"BTC-USD-190927",
"px":"0.016"
}
]
},
{
"ts":"1597026383085",
"details":[
{
"insId":"BTC-USD-200529-6000-C",
"type":"exercised",
"px":"0.016"
},
{
"insId":"BTC-USD-200529-8000-C",
"type":"exercised",
"px":"0.016"
}
]
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ts | String | Delivery/exercise time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
details | String | Detailed |
> insId | String | Delivery/exercise contract ID |
> px | String | Delivery/exercise price |
> type | String | Type delivery exercised expired_otm |
Get Open Interest
Retrieve the total open interest for contracts on OKEx.
Rate Limit: 20 requests per 2 seconds
HTTP Request
GET /api/v5/public/open-interest
Request Example
GET /api/v5/public/open-interest?instType=SWAP
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instType | String | Yes | Instrument typeSWAP FUTURES OPTION |
uly | String | No | Underlying, only applicable to FUTURES/SWAP/OPTION . Required for OPTION . |
instId | String | No | Instrument ID, e.g. BTC-USD-180216 Only applicable to FUTURES/SWAP/OPTION |
Example Response
{
"code":"0",
"msg":"",
"data":[
{
"instType":"SWAP",
"instId":"BTC-USDT-SWAP",
"oi":"5000",
"oiCcy":"555.55",
"ts":"1597026383085"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument type |
insId | String | Instrument ID |
oi | String | Open InsteREST (cont) |
oiCcy | String | Open InsteREST (coin) |
ts | String | Data return time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Get Funding Rate
Retrieve funding rate.
Rate Limit: 20 requests per 2 seconds
HTTP Request
GET /api/v5/public/funding-rate
Request Example
GET /api/v5/public/funding-rate?instId=BTC-USD-SWAP
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instId | String | Yes | Instrument ID, e.g. BTC-USD-SWAP only applicable to SWAP |
Example Response
{
"code":"0",
"msg":"",
"data":[
{
"instType":"SWAP",
"instId":"BTC-USDT-SWAP",
"fundingRate":"0.018",
"nextFundingRate":"0.017",
"fundingTime":"1597026383085"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument type SWAP |
insId | String | Instrument ID, e.g. BTC-USD-SWAP |
fundingRate | String | Current funding rate |
nextFundingRate | String | Forecast funding rate for the next period |
fundingTime | String | Settlement time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Get Funding Rate History
Retrieve funding rate history. This endpoint can retrieve data from the last 3 months.
Rate Limit: 20 requests per 2 seconds
HTTP Request
GET /api/v5/public/funding-rate-history
Request Example
GET /api/v5/public/funding-rate-history?instId=BTC-USD-SWAP
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instId | String | Yes | Instrument ID, e.g. BTC-USD-SWAP only applicable to SWAP |
after | String | No | Pagination of data to return records newer than the requested ts |
before | String | No | Pagination of data to return records earlier than the requested ts |
limit | String | No | Number of results per request. The maximum is 100 ; The default is 100 |
Example Response
{
"code":"0",
"msg":"",
"data":[
{
"instType":"SWAP",
"instId":"BTC-USDT-SWAP",
"fundingRate":"0.018",
"realizedRate":"0.017",
"fundingTime":"1597026383085"
},
{
"instType":"SWAP",
"instId":"BTC-USDT-SWAP",
"fundingRate":"0.018",
"realizedRate":"0.017",
"fundingTime":"1597026383085"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument typeSWAP |
insId | String | Instrument ID, e.g. BTC-USD-SWAP |
fundingRate | String | Current funding rate |
realizedRate | String | Actual funding rate |
fundingTime | String | Settlement time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Get Limit Price
Retrieve the highest buy limit and lowest sell limit of the instrument.
Rate Limit: 20 requests per 2 seconds
HTTP Request
GET /api/v5/public/price-limit
Request Example
GET /api/v5/public/price-limit?instId=BTC-USD-180216
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instId | String | Yes | Instrument ID, e.g. BTC-USD-180216 only applicable to FUTURES/SWAP/OPTION |
Example Response
{
"code":"0",
"msg":"",
"data":[
{
"instType":"SWAP",
"instId":"BTC-USDT-SWAP",
"buyLmt":"200",
"sellLmt":"300",
"ts":"1597026383085"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument typeSWAP FUTURES OPTION |
insId | String | Instrument ID, e.g. BTC-USD-200214 |
buyLmt | String | Highest buy limit |
sellLmt | String | Lowest sell limit |
ts | String | Data return time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Get Option Market Data
Retrieve option market data.
Rate Limit: 20 requests per 2 seconds
HTTP Request
GET /api/v5/public/opt-summary
Request Example
GET /api/v5/public/opt-summary?uly=BTC-USD
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
uly | String | Yes | Underlying, only applicable to OPTION |
expTime | String | No | Contract expiry date, the format is "YYMMDD", e.g. "200527" |
Example Response
{
"code":"0",
"msg":"",
"data":[
{
"instType":"OPTION",
"instId":"BTC-USD-200103-5500-C",
"uly":"BTC-USD",
"delta":"0.7494223636",
"gamma":"-0.6765419039",
"theta":"-0.0000809873",
"vega":"0.0000077307",
"deltaBS":"0.7494223636",
"gammaBS":"-0.6765419039",
"thetaBS":"-0.0000809873",
"vegaBS":"0.0000077307",
"realVol":"0",
"bidVol":"",
"askVol":"1.5625",
"markVol":"0.9987",
"lever":"4.0342",
"ts":"1597026383085"
},
{
"instType":"OPTION",
"instId":"BTC-USD-200103-6500-C",
"uly":"BTC-USD",
"delta":"0.7494223636",
"gamma":"-0.6765419039",
"theta":"-0.0000809873",
"vega":"0.0000077307",
"deltaBS":"0.7494223636",
"gammaBS":"-0.6765419039",
"thetaBS":"-0.0000809873",
"vegaBS":"0.0000077307",
"realVol":"0",
"bidVol":"",
"askVol":"1.5625",
"markVol":"0.9987",
"lever":"4.0342",
"ts":"1597026383085"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument typeOPTION |
insId | String | Instrument ID, e.g. BTC-USD-200103-5500-C |
uly | String | Underlying |
delta | String | Sensitivity of option price to uly price |
gamma | String | The delta's sensitivity to uly price |
vega | String | Sensitivity of option price to implied volatility |
theta | String | Sensitivity of option price to remaining maturity |
deltaBS | String | Sensitivity of option price to uly price in BS mode |
gammaBS | String | The delta's sensitivity to uly price in BS mode |
vegaBS | String | Sensitivity of option price to implied volatility in BS mode |
thetaBS | String | Sensitivity of option price to remaining maturity in BS mode |
lever | String | Leverage |
markVol | String | Mark volatility |
bidVol | String | Bid volatility |
askVol | String | Ask volatility |
realVol | String | Realized volatility (not currently used) |
ts | String | Data return time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Get Estimated Delivery/Excercise Price
Retrieve the estimated delivery price which will only have a return value one hour before the delivery/exercise.
Rate Limit: 10 requests per 2 seconds
HTTP Request
GET /api/v5/public/estimated-price
Request Example
GET /api/v5/public/estimated-price?instId=BTC-USDT-191227
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instId | String | Yes | Instrument ID, e.g. BTC-USD-200214 only applicable to FUTURES/OPTION |
Example Response
{
"code":"0",
"msg":"",
"data":[
{
"instType":"SWAP",
"instId":"BTC-USDT-201227",
"settlePx":"200",
"ts":"1597026383085"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument typeFUTURES OPTION |
instId | String | Instrument ID, e.g. BTC-USD-180216 |
settlePx | String | Estimated delivery price |
ts | String | Data return time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Get Discount Rate And Interest-Free Quota
Retrieve discount rate and interest-free quota.
Rate Limit: 10 requests per 2 seconds
HTTP Request
GET /api/v5/public/discount-rate-interest-free-quota
Request Example
GET /api/v5/public/discount-rate-interest-free-quota?ccy=BTC
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ccy | String | No | Currency |
Example Response
{
"code":"0",
"msg":"",
"data":[
{
"ccy":"BTC",
"amt" :"2",
"discount" :"1"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ccy | String | Currency |
amt | String | Interest-free quota |
discount | String | Discount rate |
Get System Time
Retrieve API server time.
Rate Limit: 10 requests per 2 seconds
HTTP Request
GET /api/v5/public/time
Request Example
GET /api/v5/public/time
Example Response
{
"code":"0",
"msg":"",
"data":[
{
"ts":"1597026383085"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ts | String | System time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Get Liquidation Orders
Retrieve information on liquidation orders in the last 1 month.
Rate Limit: 40 requests per 2 seconds
HTTP Request
GET /api/v5/public/liquidation-orders
Request Example
GET /api/v5/public/liquidation-orders?instType=MARGIN
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instType | String | Yes | Instrument typeMARGIN SWAP FUTURES OPTION |
mgnMode | String | No | Margin mode isolated cross |
instId | String | No | Instrument ID, only applicable to MARGIN |
ccy | String | No | Liquidation currency, only applicable to cross MARGIN |
uly | String | Optional | Underlying Required for FUTURES/SWAP/OPTION |
alias | String | Optional | this_week next_week quarter next_quarter Required for FUTURES |
state | String | Optional | State unfilled filled Required for FUTURES/SWAP |
before | String | No | Pagination of data to return records newer than the requested ts |
after | String | No | Pagination of data to return records earlier than the requested ts |
limit | String | No | Number of results per request. The maximum is 100 ; The default is 100 |
Example Response
{
"code":"0",
"msg":"",
"data":[
{
"instType":"2",
"totalLoss":"123",
"instId":"btc",
"uly":"123",
"details":[
{
"side":"buy",
"posSide":"short",
"bkPx":"1234",
"sz":"1415",
"bkLoss":"14",
"ccy":"",
"ts":"1597026383085"
},
{
"side":"buy",
"posSide":"short",
"bkPx":"1234",
"sz":"1415",
"bkLoss":"14",
"ccy":"",
"ts":"1597026383085"
}
]
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument type |
totalLoss | String | Total loss in the current period under the current underlying , cleared at 16:00 (UTC+8) every day.The unit is USDT |
instId | String | Instrument ID, e.g. BTC-USD-SWAP |
uly | String | Underlying, only applicable to FUTURES/SWAP/OPTION |
details | Array | Details |
>side | String | Order side, buy sell |
>posSide | String | Position side,long short Combination of side and posSide ,sell/long : Close long ; buy/short:Close short |
>bkPx | String | Bankruptcy price |
>sz | String | Number of liquidations |
>bkLoss | String | Number of losses |
>ccy | String | Liquidation currency, only applicable to MARGIN |
>ts | String | Liquidation time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Get Mark Price
Retrieve mark price.
We set the mark price based on the SPOT index and at a reasonable basis to prevent individual users from manipulating the market and causing the contract price to fluctuate.
Rate Limit: 10 requests per 2 seconds
HTTP Request
GET /api/v5/public/mark-price
Request Example
GET /api/v5/public/mark-price?instType=SWAP
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instType | String | Yes | Instrument typeMARGIN SWAP FUTURES OPTION |
uly | String | No | Underlying |
instId | String | No | Instrument ID, e.g. BTC-USD-SWAP |
Example Response
{
"code":"0",
"msg":"",
"data":[
{
"instType":"SWAP",
"instId":"BTC-USDT-SWAP",
"markPx":"200",
"ts":"1597026383085"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument typeMARGIN SWAP FUTURES OPTION |
insId | String | Instrument ID, e.g. BTC-USD-200214 |
markPx | String | Mark price |
ts | String | Data return time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Trade
The API endpoints of Trade
require authentication.
Place Order
You can place an order only if you have sufficient funds.
Rate Limit: 60 requests per 2 seconds
HTTP Request
POST /api/v5/trade/order
Request Example
place order for SPOT
POST /api/v5/trade/order
body{"instId":"BTC-USDT","tdMode":"cash","clOrdId":"b15","side":"buy","ordType":"limit","px":"2.15","sz":"2"}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instId | String | Yes | Instrument ID, e.g. BTC-USD-190927-5000-C |
tdMode | String | Yes | Trade mode Margin mode cross isolated Non-Margin mode cash |
ccy | String | No | Margin currency Only applicable to cross MARGIN orders in Single-currency margin . |
clOrdId | String | No | Client-supplied order ID A combination of case-sensitive alphanumerics beginning with a letter, or alphabets of up to 32 characters. |
tag | String | No | Order tag A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 8 characters. |
side | String | Yes | Order side, buy sell |
posSide | String | Optional | Position side Required in the long/short mode, and can only be long or short . |
ordType | String | Yes | Order type market limit post_only fok ioc |
sz | String | Yes | Quantity to buy or sell. |
px | String | Optional | Order price. Only applicable to limit order. |
reduceOnly | Boolean | No | Whether to reduce position only or not, true false , the default is false .Only applicable to MARGIN orders |
Example Response
{
"code": "0",
"msg": "",
"data": [
{
"clOrdId": "oktswap6",
"ordId": "12345689",
"tag": "",
"sCode": "0",
"sMsg": ""
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ordId | String | Order ID |
clOrdId | String | Client-supplied order ID |
tag | String | Order tag |
sCode | String | The code of the event execution result, 0 means success. |
sMsg | String | Message shown when the event execution fails. |
Place Multiple Orders
Place orders in batches. Maximum 20 orders can be placed at a time. Request parameters should be passed in the form of an array.
Rate Limit: 300 requests per 2 seconds
HTTP Request
POST /api/v5/trade/batch-orders
Request Example
batch place order for SPOT
Post/api/v5/trade/batch-orders
body[{"instId":"BTC-USDT","tdMode":"cash","clOrdId":"b15","side":"buy","ordType":"limit","px":"2.15","sz":"2"},{"instId":"BTC-USDT","tdMode":"cash","clOrdId":"b15","side":"buy","ordType":"limit","px":"2.15","sz":"2"}]
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instId | String | Yes | Instrument ID, e.g. BTC-USD-190927-5000-C |
tdMode | String | Yes | Trade mode Margin mode cross isolated Non-Margin mode cash |
ccy | String | No | Margin currency Only applicable to cross MARGIN orders in Single-currency margin . |
clOrdId | String | No | Client-supplied order ID A combination of case-sensitive alphanumerics beginning with a letter, or alphabets of up to 32 characters. |
tag | String | No | Order tag A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 8 characters. |
side | String | Yes | Order side buy sell |
posSide | String | Optional | Position side Required in long/short mode, and can only be long or short . |
ordType | String | Yes | Order type market limit post_only fok ioc |
sz | String | Yes | Quantity to buy or sell |
px | String | No | Price |
reduceOnly | Boolean | No | Whether reduce position only or nottrue false , the default is false . |
Example Response
{
"code":"0",
"msg":"",
"data":[
{
"clOrdId":"oktswap6",
"ordId":"12345689",
"tag":"",
"sCode":"0",
"sMsg":""
},
{
"clOrdId":"oktswap7",
"ordId":"12344",
"tag":"",
"sCode":"0",
"sMsg":""
},
.......
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ordId | String | Order ID |
clOrdId | String | Client-supplied order ID |
tag | String | Order tag |
sCode | String | The code of the event execution result, 0 means success. |
sMsg | String | Message shown when the event execution fails. |
Cancel Order
Cancel an incomplete order.
Rate Limit: 60 requests per 2 seconds
HTTP Request
POST /api/v5/trade/cancel-order
Request Example
POST /api/v5/trade/cancel-order
body {"ordId":"2510789768709120","instId":"BTC-USD-190927"}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instId | String | Yes | Instrument ID, e.g. BTC-USD-190927 |
ordId | String | Optional | Order ID Either ordId or clOrdId is required. If both are passed, ordId will be used. |
clOrdId | String | Optional | Client-supplied order ID |
Example Response
{
"code":"0",
"msg":"",
"data":[
{
"clOrdId":"oktswap6",
"ordId":"12345689",
"sCode":"0",
"sMsg":""
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ordId | String | Order ID |
clOrdId | String | Client-supplied order ID |
sCode | String | The code of the event execution result, 0 means success. |
sMsg | String | Message shown when the event execution fails. |
Cancel Multiple Orders
Cancel incomplete orders in batches. Maximum 20 orders can be canceled at a time. Request parameters should be passed in the form of an array.
Rate Limit: 300 requests per 2 seconds
HTTP Request
POST /api/v5/trade/cancel-batch-orders
Request Example
POST /api/v5/trade/cancel-batch-orders
body [{"instId":"BTC-USDT","ordId":"12312"},{"instId":"BTC-USDT","ordId":"1212"}]
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instId | String | Yes | Instrument ID, e.g. BTC-USD-190927 |
ordId | String | Optional | Order ID Either ordId or clOrdId is required. If both are passed, ordId will be used. |
clOrdId | String | Optional | Client-supplied order ID |
Example Response
{
"code":"0",
"msg":"",
"data":[
{
"clOrdId":"oktswap6",
"ordId":"12345689",
"sCode":"0",
"sMsg":""
},
{
"clOrdId":"oktswap7",
"ordId":"12344",
"sCode":"0",
"sMsg":""
},
.......
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ordId | String | Order ID |
clOrdId | String | Client-supplied order ID |
sCode | String | The code of the event execution result, 0 means success. |
sMsg | String | Message shown when the event execution fails. |
Amend Order
Amend an incomplete order.
Rate Limit: 60 requests per 2 seconds
HTTP Request
POST /api/v5/trade/amend-order
Request Example
POST /api/v5/trade/amend-order
body {"ordId":"2510789768709120","newSz":"2","instId":"BTC-USDT"}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instId | String | Yes | Instrument ID |
cxlOnFail | Boolean | No | Whether the order needs to be automatically canceled when the order amendment fails false or true , the default is false . |
ordId | String | Optional | Order ID Either ordId or clOrdId is required. If both are passed, ordId will be used. |
clOrdId | String | Optional | Client-supplied order ID |
reqId | String | No | Client-supplied request ID A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. |
newSz | String | Optional | New quantity after amendment. Either newSz or newPx is required. When amending a partially-filled order, the newSz should include the amount that has been filled. |
newPx | String | Optional | New price after amendment. |
Example Response
{
"code":"0",
"msg":"",
"data":[
{
"clOrdId":"",
"ordId":"12344",
"reqId":"b12344",
"sCode":"0",
"sMsg":""
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ordId | String | Order ID |
clOrdId | String | Client-supplied order ID |
reqId | String | You can provide the request_id. If provided, the response will include the corresponding request_id to help you identify the request. |
sCode | String | The code of the event execution result, 0 means success. |
sMsg | String | Message shown when the event execution fails. |
Amend Multiple Orders
Amend incomplete orders in batches. Maximum 20 orders can be amended at a time. Request parameters should be passed in the form of an array.
Rate Limit: 300 requests per 2 seconds
HTTP Request
POST /api/v5/trade/amend-batch-orders
Request Example
POST /api/v5/trade/amend-batch-orders
body [{"ordId":"2510789768709120","newSz":"2","instId":"BTC-USDT"},{"ordId":"2510789768709121","newSz":"2","instId":"BTC-USDT"}]
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instId | String | Yes | Instrument ID |
cxlOnFail | Boolean | No | Whether the order needs to be automatically canceled when the order amendment failsfalse true , the default is false . |
ordId | String | Optional | Order ID Either ordId or clOrdId is required, if both are passed, ordId will be used. |
clOrdId | String | Optional | Client-supplied order ID |
reqId | String | No | Client-supplied request ID A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. |
newSz | String | Optional | New quantity after amendment. Either newSz or newPx is required. When amending a partially-filled order, the newSz should include the amount that has been filled. |
newPx | String | Optional | New price after amendment. |
Example Response
{
"code":"0",
"msg":"",
"data":[
{
"clOrdId":"oktswap6",
"ordId":"12345689",
"reqId":"b12344",
"sCode":"0",
"sMsg":""
},
{
"clOrdId":"oktswap7",
"ordId":"12344",
"reqId":"b12344",
"sCode":"0",
"sMsg":""
},
.......
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ordId | String | Order ID |
clOrdId | String | Client-supplied order ID |
reqId | String | You can provide the request_id. If provided, the response will include the corresponding request_id to help you identify the request. |
sCode | String | The code of the event execution result, 0 means success. |
sMsg | String | Message shown when the event execution fails. |
Close Positions
Close all positions of an instrument via a market order.
Rate Limit: 20 requests per 2 seconds
HTTP Request
POST /api/v5/trade/close-position
Request Example
POST /api/v5/trade/close-position
body {"instId":"BTC-USDT-SWAP","mgnMode":"cross"}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instId | String | Yes | Instrument ID |
posSide | String | Optional | Position side This parameter can be omitted in net mode, and the default value is net . You can only fill with net .This parameter must be filled in under the long/short mode. Fill in long for close-long and short for close-short. |
mgnMode | String | Yes | Margin modecross isolated |
ccy | String | Optional | Margin currency, required in the case of closing cross MARGIN position for Single-currency margin . |
Example Response
{
"code": "0",
"msg": "",
"data": [
{
"instId": "BTC-USDT-SWAP",
"posSide": "long"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instId | String | Instrument ID |
posSide | String | Position side |
Get Order Details
Retrieve order details.
Rate Limit: 60 requests per 2 seconds
HTTP Request
GET /api/v5/trade/order
Request Example
GET /api/v5/trade/order?ordId=2510789768709120&instId=BTC-USDT
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instId | String | Yes | Instrument ID, e.g. BTC-USD-190927 |
ordId | String | Optional | Order ID Either ordId or clOrdId is required, if both are passed, ordId will be the main one |
clOrdId | String | Optional | Client-supplied order ID |
Example Response
{
"code": "0",
"msg": "",
"data": [
{
"instType": "FUTURES",
"instId": "BTC-USD-200329",
"ccy": "",
"ordId": "123445",
"clOrdId": "b1",
"tag": "",
"px": "999",
"sz": "3",
"pnl": "5",
"ordType": "limit",
"side": "buy",
"posSide": "long",
"tdMode": "isolated",
"accFillSz": "isolated",
"fillPx": "0",
"tradeId": "0",
"fillSz": "0",
"fillTime": "0",
"state": "live",
"avgPx": "0",
"lever": "20",
"tpTriggerPx": "",
"tpOrdPx": "",
"slTriggerPx": "",
"slOrdPx": "",
"feeCcy": "",
"fee": "",
"rebateCcy": "",
"rebate": "",
"category": "",
"uTime": "1597026383085",
"cTime": "1597026383085"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument typeSPOT MARGIN SWAP FUTURES OPTION |
instId | String | Instrument ID |
ccy | String | Margin currency Only applicable to cross MARGIN orders in Single-currency margin . |
ordId | String | Order ID |
clOrdId | String | Client-supplied order ID |
tag | String | Order tag |
px | String | Price |
sz | String | Quantity to buy or sell |
pnl | String | Profit and loss |
ordType | String | Order typemarket : market orderlimit : limit orderpost_only : Post-only orderfok : Fill-or-kill orderioc : Immediate-or-cancel order |
side | String | Order side |
posSide | String | Position side |
tdMode | String | Trade mode |
accFillSz | String | Accumulated fill quantity |
fillPx | String | Last filled price. If none is filled, it will return 0 . |
tradeId | String | Last traded ID |
fillSz | String | Last filled quantity |
fillTime | String | Last filled time |
avgPx | String | Average filled price. If none is filled, it will return 0 . |
state | String | State canceled live partially_filled filled |
lever | String | Leverage, from 0.01 to 125 .Only applicable to MARGIN/FUTURES/SWAP |
tpTriggerPx | String | Take-profit trigger price. It must be between 0 and 1,000,000. |
tpOrdPx | String | Take-profit order price. It must be between 0 and 1,000,000. |
slTriggerPx | String | Stop-loss trigger price. It must be between 0 and 1,000,000. |
slOrdPx | String | Stop-loss order price. It must be between 0 and 1,000,000. |
feeCcy | String | Fee currency |
fee | String | Fee |
rebateCcy | String | Rebate currency |
rebate | String | Rebate amount, the reward of placing orders from the platform (rebate) given to user who has reached the specified trading level. If there is no rebate, this field is "". |
category | String | Categorynormal twap adl full_liquidation partial_liquidation |
uTime | String | Update time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
cTime | String | Creation time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Get Order List
Retrieve all incomplete orders under the current account.
Rate Limit: 20 requests per 2 seconds
HTTP Request
GET /api/v5/trade/orders-pending
Request Example
GET /api/v5/trade/orders-pending?ordType=post_only,fok,ioc&instType=SPOT
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instType | String | No | Instrument typeSPOT MARGIN SWAP FUTURES OPTION |
uly | String | No | Underlying |
instId | String | No | Instrument ID, e.g. BTC-USD-200927 |
ordType | String | No | Order type market limit post_only fok ioc |
state | String | No | Statelive partially_filled |
after | String | No | Pagination of data to return records earlier than the requested ordId |
before | String | No | Pagination of data to return records newer than the requested ordId |
limit | String | No | Number of results per request. The maximum is 100 ; The default is 100 |
Example Response
{
"code": "0",
"msg": "",
"data": [
{
"instType": "FUTURES",
"instId": "BTC-USD-200329",
"ccy": "",
"ordId": "123445",
"clOrdId": "b1",
"tag": "",
"px": "999",
"sz": "3",
"pnl": "5",
"ordType": "limit",
"side": "buy",
"posSide": "long",
"tdMode": "isolated",
"accFillSz": "isolated",
"fillPx": "0",
"tradeId": "0",
"fillSz": "0",
"fillTime": "0",
"state": "live",
"avgPx": "0",
"lever": "20",
"tpTriggerPx": "",
"tpOrdPx": "",
"slTriggerPx": "",
"slOrdPx": "",
"feeCcy": "",
"fee": "",
"rebateCcy": "",
"rebate": "",
"category": "",
"uTime": "1597026383085",
"cTime": "1597026383085"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument type |
instId | String | Instrument ID |
ccy | String | Margin currency Only applicable to cross MARGIN orders in Single-currency margin . |
ordId | String | Order ID |
clOrdId | String | Client-supplied order ID |
tag | String | Order tag |
px | String | Price |
sz | String | Quantity to buy or sell |
pnl | String | Profit and loss |
ordType | String | Order typemarket : market orderlimit : limit orderpost_only : Post-only orderfok : Fill-or-kill orderioc : Immediate-or-cancel order |
side | String | Order side |
posSide | String | Position side |
tdMode | String | Trade mode |
accFillSz | String | Accumulated fill quantity |
fillPx | String | Last filled price |
tradeId | String | Last trade ID |
fillSz | String | Last filled quantity |
fillTime | String | Last filled time |
avgPx | String | Average filled price. If none is filled, it will return 0 . |
state | String | Statelive partially_filled |
lever | String | Leverage, from 0.01 to 125 .Only applicable to MARGIN/FUTURES/SWAP |
tpTriggerPx | String | Take-profit trigger price. It must be between 0 and 1,000,000. |
tpOrdPx | String | Take-profit order price. It must be between 0 and 1,000,000. |
slTriggerPx | String | Stop-loss trigger price. It must be between 0 and 1,000,000. |
slOrdPx | String | Stop-loss order price. It must be between 0 and 1,000,000. |
feeCcy | String | Fee currency |
fee | String | Fee |
rebateCcy | String | Rebate currency |
rebate | String | Rebate amount, the reward of placing orders from the platform (rebate) given to user who has reached the specified trading level. If there is no rebate, this field is "". |
category | String | Category normal twap adl full_liquidation partial_liquidation |
uTime | String | Update time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
cTime | String | Creation time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Get Order History (last 7 days)
Retrieve the completed order data for the last 7 days, and the incomplete orders that have been cancelled are only reserved for 2 hours.
Rate Limit: 40 requests per 2 seconds
HTTP Request
GET /api/v5/trade/orders-history
Request Example
GET /api/v5/trade/orders-history?ordType=post_only,fok,ioc&instType=SPOT
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instType | String | yes | Instrument typeSPOT MARGIN SWAP FUTURES OPTION |
uly | String | No | Underlying |
instId | String | No | Instrument ID, e.g. BTC-USD-190927 |
ordType | String | No | Order type market limit post_only fok ioc |
state | String | No | Statecanceled filled |
after | String | No | Pagination of data to return records earlier than the requested ordId |
before | String | No | Pagination of data to return records newer than the requested ordId |
limit | String | No | Number of results per request. The maximum is 100 ; The default is 100 |
Example Response
{
"code": "0",
"msg": "",
"data": [
{
"instType": "FUTURES",
"instId": "BTC-USD-200329",
"ccy": "",
"ordId": "123445",
"clOrdId": "b1",
"tag": "",
"px": "999",
"sz": "3",
"ordType": "limit",
"side": "buy",
"posSide": "long",
"tdMode": "isolated",
"accFillSz": "isolated",
"fillPx": "0",
"tradeId": "0",
"fillSz": "0",
"fillTime": "0",
"state": "live",
"avgPx": "0",
"lever": "20",
"tpTriggerPx": "",
"tpOrdPx": "",
"slTriggerPx": "",
"slOrdPx": "",
"feeCcy": "",
"fee": "",
"rebateCcy": "",
"rebate": "",
"pnl": "",
"category": "",
"uTime": "1597026383085",
"cTime": "1597026383085"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument type |
instId | String | Instrument ID |
ccy | String | Margin currency Only applicable to cross MARGIN orders in Single-currency margin . |
ordId | String | Order ID |
clOrdId | String | Client-supplied order ID |
tag | String | Order tag |
px | String | Price |
sz | String | Quantity to buy or sell |
ordType | String | Order typemarket : market orderlimit : limit orderpost_only : Post-only orderfok : Fill-or-kill orderioc : Immediate-or-cancel order |
side | String | Order side |
posSide | String | Position side |
tdMode | String | Trade mode |
accFillSz | String | Accumulated fill quantity |
fillPx | String | Last filled price. If none is filled, it will return 0 . |
tradeId | String | Last trade ID |
fillSz | String | Last filled quantity |
fillTime | String | Last filled time |
avgPx | String | Average filled price. If none is filled, it will return 0 . |
state | String | State canceled filled |
lever | String | Leverage, from 0.01 to 125 .Only applicable to MARGIN/FUTURES/SWAP |
tpTriggerPx | String | Take-profit trigger price. It must be between 0 and 1,000,000. |
tpOrdPx | String | Take-profit order price. It must be between 0 and 1,000,000. |
slTriggerPx | String | Stop-loss trigger price. It must be between 0 and 1,000,000. |
slOrdPx | String | Stop-loss order price. It must be between 0 and 1,000,000. |
feeCcy | String | Fee currency |
fee | String | Fee |
rebateCcy | String | Rebate currency |
rebate | String | Rebate amount, the reward of placing orders from the platform (rebate) given to user who has reached the specified trading level. If there is no rebate, this field is "". |
pnl | String | Profit and loss |
category | String | Category normal twap |
uTime | String | Update time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
cTime | String | Creation time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Get Order History (last 3 months)
Retrieve the completed order data of the last 3 months, and the incomplete orders that have been canceled are only reserved for 2 hours.
Rate Limit: 20 requests per 2 seconds
HTTP Request
GET /api/v5/trade/orders-history-archive
Request Example
GET /api/v5/trade/orders-history-archive?ordType=post_only,fok,ioc&instType=SPOT
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instType | String | yes | Instrument typeSPOT MARGIN SWAP FUTURES OPTION |
uly | String | No | Underlying |
instId | String | No | Instrument ID, e.g. BTC-USD-200927 |
ordType | String | No | Order type market limit post_only fok ioc |
state | String | No | Statecanceled filled |
after | String | No | Pagination of data to return records earlier than the requested ordId |
before | String | No | Pagination of data to return records newer than the requested ordId |
limit | String | No | Number of results per request. The maximum is 100 ; The default is 100 |
Example Response
{
"code": "0",
"msg": "",
"data": [
{
"instType": "FUTURES",
"instId": "BTC-USD-200329",
"ccy": "",
"ordId": "123445",
"clOrdId": "b1",
"tag": "",
"px": "999",
"sz": "3",
"ordType": "limit",
"side": "buy",
"posSide": "long",
"tdMode": "isolated",
"accFillSz": "isolated",
"fillPx": "0",
"tradeId": "0",
"fillSz": "0",
"fillTime": "0",
"state": "live",
"avgPx": "0",
"lever": "20",
"tpTriggerPx": "",
"tpOrdPx": "",
"slTriggerPx": "",
"slOrdPx": "",
"feeCcy": "",
"fee": "",
"rebateCcy": "",
"rebate": "",
"pnl": "",
"category": "",
"uTime": "1597026383085",
"cTime": "1597026383085"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument type |
instId | String | Instrument ID |
ccy | String | Margin currency Only applicable to cross MARGIN orders in Single-currency margin . |
ordId | String | Order ID |
clOrdId | String | Client-supplied order ID |
tag | String | Order tag |
px | String | Price |
sz | String | Quantity to buy or sell |
ordType | String | Order typemarket : market orderlimit : limit orderpost_only : Post-only orderfok : Fill-or-kill orderioc : Immediate-or-cancel order |
side | String | Order side |
posSide | String | Position side |
tdMode | String | Trade mode |
accFillSz | String | Accumulated fill quantity |
fillPx | String | Last filled price. If none is filled, it will return 0 . |
tradeId | String | Last trade ID |
fillSz | String | Last filled quantity |
fillTime | String | Last filled time |
avgPx | String | Average filled price. If none is filled, it will returns 0 . |
state | String | State canceled filled |
lever | String | Leverage, from 0.01 to 125 .Only applicable to MARGIN/FUTURES/SWAP |
tpTriggerPx | String | Take-profit trigger price. It must be between 0 and 1,000,000. |
tpOrdPx | String | Take-profit order price. It must be between 0 and 1,000,000. |
slTriggerPx | String | Stop-loss trigger price. It must be between 0 and 1,000,000. |
slOrdPx | String | Stop-loss order price. It must be between 0 and 1,000,000. |
feeCcy | String | Fee currency |
fee | String | Fee |
rebateCcy | String | Rebate currency |
rebate | String | Rebate amount, the reward of placing orders from the platform (rebate) given to user who has reached the specified trading level. If there is no rebate, this field is "". |
pnl | String | Profit and loss |
category | String | Category normal twap adl full_liquidation partial_liquidation |
uTime | String | Update time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
cTime | String | Creation time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Get Transaction Details
Retrieve recently-filled transaction details.
Rate Limit: 60 requests per 2 seconds
HTTP Request
GET /api/v5/trade/fills
Request Example
GET /api/v5/trade/fills
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instType | String | No | Instrument typeSPOT MARGIN SWAP FUTURES OPTION |
uly | String | No | Underlying |
instId | String | No | Instrument ID, e.g. BTC-USD-190927 |
ordId | String | No | Order ID |
after | String | No | Pagination of data to return records earlier than the requested billId |
before | String | No | Pagination of data to return records newer than the requested billId |
limit | String | No | Number of results per request. The maximum is 100 ; The default is 100 |
Example Response
{
"code":"0",
"msg":"",
"data":[
{
"instType":"FUTURES",
"instId":"BTC-USD-200329",
"tradeId":"123",
"ordId":"123445",
"billId":"1111",
"tag":"",
"fillPx":"999",
"fillSz":"3",
"side":"buy",
"posSide":"long",
"execType":"M",
"feeCcy":"",
"fee":"",
"ts":"1597026383085"
},
{
"instType":"FUTURES",
"instId":"BTC-USD-200329",
"tradeId":"123",
"ordId":"123445",
"billId":"1111",
"tag":"",
"fillPx":"999",
"fillSz":"3",
"side":"buy",
"posSide":"long",
"execType":"M",
"feeCcy":"",
"fee":"",
"ts":"1597026383085"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument type |
instId | String | Instrument ID |
tradeId | String | Last trade ID |
ordId | String | Order ID |
billId | String | Bill ID |
tag | String | Order tag |
fillPx | String | Last filled price |
fillSz | String | Last filled quantity |
side | String | Order side, buy sell |
posSide | String | Position sidelong short it returns net innet mode. |
execType | String | Order flow type, T : taker M : maker |
feeCcy | String | Fee currency |
fee | String | Fee |
ts | String | Data generation time, Unix timestamp format in milliseconds, e.g. 1597026383085 . |
Place Algo Order
The algo order includes trigger
order, oco
order and conditional
order.
Rate Limit: 20 requests per 2 seconds
HTTP Request
POST /api/v5/trade/order-algo
Request Example
POST /api/v5/trade/order-algo
body {"instId":"BTC-USDT","tdMode":"cross","side":"buy","ordType":"conditional","sz":"2","tpTriggerPx":"15","tpOrdPx":"18"}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instId | String | Yes | Instrument ID, e.g. BTC-USD-190927-5000-C |
tdMode | String | Yes | Trade mode Margin mode cross isolated Non-Margin mode cash |
ccy | String | No | Margin currency Only applicable to cross MARGIN orders in Single-currency margin . |
side | String | Yes | Order side, buy sell |
posSide | String | Optional | Position side Required in long/short mode and only be long or short |
ordType | String | Yes | Order type conditional : One-way stop order oco : One-cancels-the-other ordertrigger : Trigger order |
sz | String | Yes | Quantity to buy or sell |
reduceOnly | Boolean | No | Whether reduce position only or not, true false |
Stop Order
Parameter | Type | Required | Description |
---|---|---|---|
tpTriggerPx | String | No | Take-profit trigger price Must be between 0 and 1,000,000. If you fill in this parameter, you should fill in the take-profit order price as well. |
tpOrdPx | String | No | Take-profit order price Must be between 0 and 1,000,000. If you fill in this parameter, you should fill in the take-profit trigger price as well. If the price is -1, take-profit will be executed at the market price. |
slTriggerPx | String | No | Stop-loss trigger price Must be between 0 and 1,000,000. If you fill in this parameter, you should fill in the stop-loss order price. |
slOrdPx | String | No | Stop-loss order price Must be between 0 and 1,000,000. If you fill in this parameter, you should fill in the stop-loss trigger price. If the price is -1, stop-loss will be executed at the market price. |
Trigger Order
Parameter | Type | Required | Description |
---|---|---|---|
triggerPx | String | No | Trigger price |
orderPx | String | No | Order Price |
Example Response
{
"code": "0",
"msg": "",
"data": [
{
"algoId": "12345689",
"sCode": "0",
"sMsg": ""
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
algoId | String | Algo ID |
sCode | String | The code of the event execution result, 0 means success. |
sMsg | String | Message shown when the event execution fails. |
Cancel Algo Order
Cancel unfilled algo orders. A maximum of 10 orders can be canceled at a time.
Rate Limit: 20 requests per 2 seconds
HTTP Request
POST /api/v5/trade/cancel-algos
Request Example
POST /api/v5/trade/cancel-algos
body [{"algoId":"198273485","instId":"BTC-USDT"},{"algoId":"198273485","instId":"BTC-USDT"}]
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
algoId | String | Yes | Algo ID |
instId | String | Yes | Instrument ID, e.g. BTC-USDT |
Example Response
{
"code":"0",
"msg":"",
"data":[
{
"algoId":"1234",
"sCode":"0",
"sMsg":""
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
algoId | String | Order ID |
sCode | String | The code of the event execution result, 0 means success. |
sMsg | String | Message shown when the event execution fails. |
Get Algo Order List
Retrieve a list of untriggered Algo orders under the current account.
Rate Limit: 20 requests per 2 seconds
HTTP Request
GET /api/v5/trade/orders-algo-pending
Request Example
GET /api/v5/trade/orders-algo-pending?ordType=conditional
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
algoId | String | Optional | Algo ID |
instType | String | No | Instrument typeSPOT SWAP FUTURES MARFIN |
instId | String | No | Instrument ID, e.g. BTC-USD-190927 |
ordType | String | Yes | Order type conditional : One-way stop order oco : One-cancels-the-other ordertrigger : Trigger order |
after | String | No | Pagination of data to return records earlier than the requested algoId . |
before | String | No | Pagination of data to return records newer than the requested algoId . |
limit | String | No | Number of results per request. The maximum is 100 ; The default is 100 |
Example Response
{
"code": "0",
"msg": "",
"data": [
{
"instType": "FUTURES",
"instId": "BTC-USD-200329",
"ordId": "123445",
"ccy": "BTC",
"algoId": "1234",
"sz": "999",
"ordType": "oco",
"side": "buy",
"posSide": "long",
"tdMode": "cross",
"state": "1",
"lever": "20",
"tpTriggerPx": "",
"tpOrdPx": "",
"slTriggerPx": "",
"triggerPx": "99",
"ordPx": "12",
"actualSz": "",
"actualPx": "",
"actualSide": "",
"triggerTime": "1597026383085",
"cTime": "1597026383000"
},
{
"instType": "FUTURES",
"instId": "BTC-USD-200329",
"ordId": "123445",
"ccy": "BTC",
"algoId": "1234",
"sz": "999",
"ordType": "oco",
"side": "buy",
"posSide": "long",
"tdMode": "cross",
"state": "1",
"lever": "20",
"tpTriggerPx": "",
"tpOrdPx": "",
"slTriggerPx": "",
"triggerPx": "99",
"ordPx": "12",
"actualSz": "",
"actualPx": "",
"actualSide": "",
"triggerTime": "1597026383085",
"cTime": "1597026383000"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument type |
instId | String | Instrument ID |
ccy | String | Margin currency Only applicable to cross MARGIN orders in Single-currency margin . |
ordId | String | Order ID |
algoId | String | Algo ID |
sz | String | Quantity to buy or sell |
ordType | String | Order type conditional : One-way stop order oco : One-cancels-the-other ordertrigger : Trigger order |
side | String | Order side |
posSide | String | Position side |
tdMode | String | Trade mode |
state | String | State, pending |
lever | String | Leverage, from 0.01 to 125 .Only applicable to MARGIN/FUTURES/SWAP |
tpTriggerPx | String | Take-profit trigger price, it must be between 0 and 1,000,000. |
tpOrdPx | String | Take-profit order price, it must be between 0 and 1,000,000. |
slTriggerPx | String | Stop-loss trigger price, it must be between 0 and 1,000,000. |
slOrdPx | String | Stop-loss order price, it must be between 0 and 1,000,000. |
triggerPx | String | Trigger price |
ordPx | String | Order price |
actualSz | String | Actual order quantity |
actualPx | String | Actual order price |
actualSide | String | Actual trigger side, tp : take profit sl : stop loss |
triggerTime | String | Trigger time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
cTime | String | Creation time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Get Algo Order History
Retrieve a list of all algo orders under the current account
Rate Limit: 20 requests per 2 seconds
HTTP Request
GET /api/v5/trade/orders-algo-history
Request Example
GET /api/v5/trade/order-algos-history?state=effective&ordType=conditional
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
state | String | Optional | Stateeffective canceled order_failed Either state or algoId is requied |
algoId | String | Optional | Algo ID Either state or algoId is required. |
instType | String | No | Instrument typeSPOT SWAP FUTURES MARGIN |
instId | String | No | Instrument ID, e.g. BTC-USD-190927 |
ordType | String | Yes | Order type conditional : One-way stop order oco : One-cancels-the-other ordertrigger : Trigger order |
after | String | No | Pagination of data to return records earlier than the requested algoId |
before | String | No | Pagination of data to return records new than the requested algoId |
limit | String | No | Number of results per request. The maximum is 100 ; The default is 100 |
Example Response
{
"code": "0",
"msg": "",
"data": [
{
"instType": "FUTURES",
"instId": "BTC-USD-200329",
"ordId": "123445",
"ccy": "BTC",
"algoId": "1234",
"sz": "999",
"ordType": "oco",
"side": "buy",
"posSide": "long",
"tdMode": "cross",
"state": "effective",
"lever": "20",
"tpRequired in `long/short` mode, and": "",
"tpOrdPx": "",
"slRequired in `long/short` mode, and": "",
"Required in `long/short` mode, and": "99",
"ordPx": "12",
"actualSz": "",
"actualPx": "",
"actualSide": "",
"triggerTime": "1597026383085",
"cTime": "1597026383000"
},
{
"instType": "FUTURES",
"instId": "BTC-USD-200329",
"ordId": "123445",
"ccy": "BTC",
"algoId": "1234",
"sz": "999",
"ordType": "oco",
"side": "buy",
"posSide": "long",
"tdMode": "cross",
"state": "effective",
"lever": "20",
"tpRequired in `long/short` mode, and": "",
"tpOrdPx": "",
"slRequired in `long/short` mode, and": "",
"Required in `long/short` mode, and": "99",
"ordPx": "12",
"actualSz": "",
"actualPx": "",
"actualSide": "",
"triggerTime": "1597026383085",
"cTime": "1597026383000"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument type |
instId | String | Instrument ID |
ccy | String | Margin currency Only applicable to cross MARGIN orders in Single-currency margin . |
ordId | String | Order ID |
algoId | String | Algo ID |
sz | String | Quantity to buy or sell |
ordType | String | Order type conditional : One-way stop order oco : One-cancels-the-other ordertrigger : Trigger order |
side | String | Order side |
posSide | String | Position side |
tdMode | String | Trade mode |
state | String | State effective canceled order_failed |
lever | String | Leverage, from 0.01 to 125 .Only applicable to MARGIN/FUTURES/SWAP |
tpTriggerPx | String | Take-profit trigger price. It must be between 0 and 1,000,000. |
tpOrdPx | String | Take-profit order price. It must be between 0 and 1,000,000. |
slTriggerPx | String | Stop-loss trigger price. It must be between 0 and 1,000,000. |
slOrdPx | String | Stop-loss order price. It must be between 0 and 1,000,000. |
ordPx | String | Order price |
actualSz | String | Actual order quantity |
actualPx | String | Actual order price |
actualSide | String | Actual trigger side, tp : take profit sl : stop loss |
triggerTime | String | Trigger time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
cTime | String | Creation time Unix timestamp format in milliseconds, e.g. 1597026383085 |
WebSocket API
Overview
WebSocket is a new HTML5 protocol that achieves full-duplex data transmission between the client and server, allowing data to be transferred effectively in both directions. A connection between the client and server can be established with just one handshake. The server will then be able to push data to the client according to preset rules. Its advantages include:
- The WebSocket request header size for data transmission between client and server is only 2 bytes.
- Either the client or server can initiate data transmission.
- There's no need to repeatedly create and delete TCP connections, saving resources on bandwidth and server.
Connect
Connection instructions:
Connection limit: 1 time per second
When subscribing to a public channel, use the address of the public service. When subscribing to a private channel, use the address of the private service
Subscription limit: 240 times per hour
Login
Request format description
{
"op": "login",
"args":
[
{
"apiKey" : "<api_key>",
"passphrase" :"<passphrase>",
"timestamp" :"<timestamp>",
"sign" :"<sign>"
}
]
}
Request Example
{
"op": "login",
"args":
[
{
"apiKey" : "985d5b66-57ce-40fb-b714-afc0b9787083",
"passphrase" :"123456" ,
"timestamp" :"1538054050" ,
"sign" :"7L+zFQ+CEgGu5rzCj4+BdV2/uUHGqddA9pI6ztsRRPs="
}
]
}
Successful Response Example
{
"event": "login",
"code": "0",
"msg": ""
}
Failure Response Example
{
"event": "error",
"code": "60008",
"msg": "Login is not supported for public channels."
}
api_key: Unique identification for invoking API. Requires user to apply one manually.
passphrase: API Key password
timestamp: the Unix Epoch time, the unit is seconds
sign: signature string, the signature algorithm is as follows:
First concatenate timestamp
, method
, requestPath
, and body
strings, then use HMAC SHA256 method to encrypt the concatenated string with SecretKey, and then perform Base64 encoding.
secretKey: The security key generated when the user applies for APIKey, e.g. : 22582BD0CFF14C41EDBF1AB98506286D
Example of timestamp: const timestamp ='' + Date.now() / 1000
Among sign example: sign=CryptoJS.enc.Base64.Stringify(CryptoJS.HmacSHA256(timestamp +'GET'+'/users/self/verify', secretKey))
method: always 'GET'.
requestPath : always '/users/self/verify'
Subscribe
Subscription Instructions
Request format description
{
"op": "subscribe",
"args": ["<SubscriptionTopic>"]
}
WebSocket channels are divided into two categories: public
and private
channels.
Public channels
-- include tickers channel, K-Line channel, limit price channel, order book channel, and mark price channel, etc -- do not require log in.
Private channels
-- including account channel, order channel, and position channel, etc -- require log in.
Users can choose to subscribe to one or more channels, and the total length of multiple channels cannot exceed 4096 bytes.
Request Example
{
"op": "subscribe",
"args":
[
{
"channel": "tickers",
"instId":"LTC-USD-200327"
},
{
"channel": "candle1m",
"instId":"LTC-USD-200327"
}
]
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation, subscribe |
args |
Array | Yes | List of subscribed channels |
> channel | String | Yes | Channel name |
> instType | String | No | Instrument typeSPOT MARGIN SWAP FUTURES OPTION ANY |
> uly | String | No | Underlying |
> instId | String | No | Instrument ID |
Example response
{
"event": "subscribe",
"arg": {
"channel": "tickers",
"instId": "LTC-USD-200327"
}
}
Return parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Event, subscribe error |
arg |
Object | No | Subscribed channel |
> channel | String | Yes | Channel name |
> instType | String | No | Instrument typeSPOT MARGIN SWAP FUTURES OPTION ANY |
> uly | String | No | Underlying |
> instId | String | No | Instrument ID |
code | String | No | Error code |
msg | String | No | Error message |
Unsubscribe
Unsubscribe from one or more channels.
Request format description
{
"op": "unsubscribe",
"args": ["< SubscriptionTopic> "]
}
Request Example
{
"op": "unsubscribe",
"args":
[
{
"channel": "tickers",
"instId":"LTC-USD-200327"
},
{
"channel": "candle1m",
"instId":"LTC-USD-200327"
}
]
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation, unsubscribe |
args |
Array | Yes | List of channels to unsubscribe from |
> channel | String | Yes | Channel name |
> instType | String | No | Instrument typeSPOT MARGIN SWAP FUTURES OPTION ANY |
> uly | String | No | Underlying |
> instId | String | No | Instrument ID |
Example response
{
"event": "unsubscribe",
"arg": {
"channel": "tickers",
"instId": "LTC-USD-200327"
}
}
Return parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Event, unsubscribe error |
arg |
Object | No | Unsubscribed channel |
> channel | String | Yes | Channel name |
> instType | String | No | Instrument typeSPOT MARGIN SWAP FUTURES OPTION |
> uly | String | No | Underlying |
> instId | String | No | Instrument ID |
code | String | No | Error code |
msg | String | No | Error message |
Checksum
This mechanism can help users verify the accuracy of depth data.
Verification Instructions
Data pushed from the order book channel includes a timestamp and checksum. Users can compare the received checksum against the one computed from the string aggregated from the first 25 bids and asks data, and resubscribe to the channel if they do not match.
Calculation description
The checksum string is a signed integer (32-bit) crc32 value, which is formed by concatenating the price and quantity in ask and bid with a colon
Order Book Aggregation Rule
After successfully subscribing to order book channel, user will first receive a full-snapshot data on all depth levels and then receive incremental data afterwards. Then traverse the first entry from the bids and asks list of the incremental data, and compare them with the first entry from the bids and asks list of full snapshot data.
If the price is the same, compare the quantity. If the quantity is different and is not 0, update the buy one or sell one in the total data. Otherwise, delete the buy one or sell one.
If the prices are not the same, sort them in order and insert buy one or sell one into the full data.
Example 1
{
"arg": {
"channel": "books",
"instId":"BTC-USD-191227"
},
"action":"snapshot",
"data": [
{
"asks": [[3366.8, 9, 10, 3],[ 3368,8,3,4 ]],
"bids": [[3366.1, 7, 0, 3],[ 3366,6,3,4 ]]],
"ts": "1597026383085",
"checksum": "-855196043"
}
]
}
Example 1: When bid and ask are aligned, the string to be verified is:bid[price:size]
:ask[price:size]
:bid[price:size]
:ask[price:size]
...
The checksum string corresponding to this example is: 3366.1
:7
:3366.8
:9
:3366
:6
:3368
:8
Example 2
{
"arg": {
"channel": "books",
"instId":"BTC-USD-191227"
},
"action":"update",
"data": [
{
"asks": [[3366.8, 9, 10, 3],[ 3368,8,3,4 ],[ 3372,8,3,4 ]],
"bids": [[3366.1, 7, 0, 3]],
"ts": "1597026383085",
"checksum": "-855196043"
}
]
}
Example 2: When bid and ask are not aligned, the string to be verified is:
bid[price:size]
:ask[price:size]
:ask[price:size]
:ask[price:size]
:...
The checksum string corresponding to this example is: 3366.1
:7
:3366.8
:9
:3368
:8
:3372
:8
Public Channel
Instruments Channel
The full instrument list will be pushed for the first time after subscription. Subsequently, the instruments will be pushed if there's any change to the instrument’s state (such as delivery of FUTURES, exercise of OPTION, listing of new contracts / trading pairs, trading suspension, etc.).
Request Example
{
"op": "subscribe",
"args": [
{
"channel": "instruments",
"instType": "FUTURES"
}
]
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation, subscribe unsubscribe |
args | Array | Yes | List of subscribed channels |
> channel | String | Yes | Channel name, instruments |
> instType | String | Yes | Instrument typeSPOT SWAP FUTURES OPTION |
Successful Response Example
{
"event": "subscribe",
"arg": {
"channel": "instruments",
"instType": "FUTURES"
}
}
Failure Response Example
{
"event": "error",
"code": "60012",
"msg": "Unrecognized request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"instruments\", \"instType\" : \"FUTURES\"}]}"
}
Response parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Event, subscribe unsubscribe error |
arg | Object | No | Subscribed channel |
> channel | String | Yes | Channel name |
> instType | String | Yes | Instrument typeSPOT SWAP FUTURES OPTION |
code | String | No | Error code |
msg | String | No | Error message |
Push Data Example
{
"arg": {
"channel": "instruments",
"instType": "FUTURES"
},
"data": [{
"instType": "FUTURES",
"instId": "BTC-USD-191115",
"uly": "BTC-USD",
"category":"1",
"baseCcy": "",
"quoteCcy": "",
"settleCcy": "BTC",
"ctVal": "10",
"ctMult": "1",
"ctValCcy": "USD",
"optType": "",
"stk": "",
"listTime": "",
"expTime": "",
"tickSz": "0.01",
"lotSz": "1",
"minSz": "1",
"ctType": "linear",
"alias": "this_week",
"state": "live"
}, {
"instType": "FUTURES",
"instId": "BTC-USD-201115",
"uly": "BTC-USD",
"category":"1",
"baseCcy": "",
"quoteCcy": "",
"settleCcy": "BTC",
"ctVal": "10",
"ctMult": "1",
"ctValCcy": "USD",
"optType": "",
"stk": "",
"listTime": "",
"expTime": "",
"tickSz": "0.01",
"lotSz": "1",
"minSz": "1",
"ctType": "linear",
"alias": "this_week",
"state": "live"
}]
}
Push data parameters
Parameter | Type | Description |
---|---|---|
arg | Object | Subscribed channel |
> channel | String | Channel name |
> instType | String | Instrument type |
data | Array | Subscribed data |
> instType | String | Instrument type |
> instId | String | Instrument ID, e.g. BTC-USD-SWAP |
> uly | String | Underlying, e.g. BTC-USD Only applicable to FUTURES/SWAP/OPTION |
> category | String | Fee Schedule |
> baseCcy | String | Base currency, e.g. BTC in BTC-USDT Only applicable to SPOT |
> quoteCcy | String | Quote currency, e.g. USDT in BTC-USDT Only applicable to SPOT |
> settleCcy | String | Settlement and margin currency, e.g. BTC Only applicable to FUTURES/SWAP/OPTION |
> ctVal | String | Contract value |
> ctMult | String | Contract multiplier |
> ctValCcy | String | Contract value currency |
> optType | String | Option type, C : Call P : PutOnly applicable to OPTION |
> stk | String | Strike price Only applicable to OPTION |
> listTime | String | Listing time Only applicable to FUTURES/OPTION |
> expTime | String | Expiry time Only applicable to FUTURES/OPTION |
> lever | String | Leverage Not applicable to SPOT , used to distinguish between MARGIN and SPOT . |
> tickSz | String | Tick size, e.g. 0.0001 |
> lotSz | String | Lot size,e.g. BTC-USDT-SWAP: 1 |
> minSz | String | Minimum order size |
> ctType | String | Contract type, linear : linear contract inverse : inverse contract |
> alias | String | Aliasthis_week next_week quarter next_quarter Only applicable to FUTURES |
> state | String | Instrument status live suspend expired preopen |
Tickers Channel
Retrieve the last traded price, bid price, ask price and 24-hour trading volume of instruments. Data will be pushed every 100 ms.
Request Example
{
"op": "subscribe",
"args": [{
"channel": "tickers",
"instId": "LTC-USD-200327"
}]
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation, subscribe unsubscribe |
args |
Array | Yes | List of subscribed channels |
> channel | String | Yes | Channel name, tickers |
> instId | String | Yes | Instrument ID |
Successful Response Example
{
"event": "subscribe",
"arg": {
"channel": "tickers",
"instId": "LTC-USD-200327"
}
}
Failure Response Example
{
"event": "error",
"code": "60012",
"msg": "Unrecognized request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"tickers\", \"instId\" : \"LTC-USD-200327\"}]}"
}
Response parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Event, subscribe unsubscribe error |
arg |
Object | No | Subscribed channel |
> channel | String | Yes | Channel name |
> instId | String | Yes | Instrument ID |
code | String | No | Error code |
msg | String | No | Error message |
Push Data Example
{
"arg": {
"channel": "tickers",
"instId": "LTC-USD-200327"
},
"data": [{
"instType": "SWAP",
"instId": "LTC-USD-SWAP",
"last": "9999.99",
"lastSz": "0.1",
"askPx": "9999.99",
"askSz": "11",
"bidPx": "8888.88",
"bidSz": "5",
"open24h": "9000",
"high24h": "10000",
"low24h": "8888.88",
"volCcy24h": "2222",
"vol24h": "2222",
"sodUtc0": "2222",
"sodUtc8": "2222",
"ts": "1597026383085"
}]
}
Push data parameters
Parameter | Type | Description |
---|---|---|
arg |
Object | Successfully subscribed channel |
> channel | String | Channel name |
> instId | String | Instrument ID |
data |
Array | Subscribed data |
> instType | String | Instrument type |
> instId | String | Instrument ID |
> last | String | Last traded price |
> lastSz | String | Last traded size |
> askPx | String | Best ask price |
> askSz | String | Best ask size |
> bidPx | String | Best bid price |
> bidSz | String | Best bid size |
> open24h | String | Open price in the past 24 hours |
> high24h | String | Highest price in the past 24 hours |
> low24h | String | Lowest price in the past 24 hours |
> volCcy24h | String | Trading volume in the past 24 hours |
> vol24h | String | Trading volume in the past 24 hours |
>sodUtc0 | String | Open price in the UTC 0 |
>sodUtc8 | String | Open price in the UTC 8 |
> ts | String | Ticker data generation time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Open interest Channel
Retrieve the open interest. Data will by pushed every 3 seconds.
Request Example
{
"op": "subscribe",
"args": [{
"channel": "open-interest",
"instId":"LTC-USD-SWAP"
}]
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation, subscribe unsubscribe |
args |
Array | Yes | List of subscribed channels |
> channel | String | Yes | Channel name, open-interest |
> instId | String | Yes | Instrument ID |
Successful Response Example
{
"event": "subscribe",
"arg": [{
"channel": "open-interest",
"instId": "LTC-USD-SWAP"
}]
}
Failure Response Example
{
"event": "error",
"code": "60012",
"msg": "Unrecognized request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"open-interest\", \"instId\" : \"LTC-USD-SWAP\"}]}"
}
Response parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Event, subscribe unsubscribe error |
arg |
Object | No | Subscribed channel |
> channel | String | Yes | Channel name |
> instId | String | Yes | Instrument ID |
code | String | No | Error code |
msg | String | No | Error message |
Push Data Example
{
"arg": {
"channel": "open-interest",
"instId": "LTC-USD-SWAP"
},
"data": [{
"instType": "SWAP",
"instId": "LTC-USD-SWAP",
"oi": "5000",
"oiCcy": "555.55",
"ts": "1597026383085"
}]
}
Push data parameters
Parameter | Type | Description |
---|---|---|
arg |
Object | Successfully subscribed channel |
channel | String | Channel name |
instId | String | Instrument ID |
data |
Array | Subscribed data |
instType | String | Instrument type |
instId | String | Instrument ID, e.g. BTC-USD-18021 |
oi | String | Open interest, in units of contracts. |
oiCcy | String | Open interest, in currency units |
ts | String | The time when the data was updated, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Candlesticks Channel
Retrieve the candlesticks data of an instrument. Data will be pushed every 500 ms.
Request Example
{
"op": "subscribe",
"args": [{
"channel": "candle1D",
"instId": "LTC-USD-200327"
}]
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation, subscribe unsubscribe |
args |
Array | Yes | List of subscribed channels |
channel | String | Yes | Channel namecandle1Y candle6M candle3M candle1M candle1W candle1D candle2D candle3D candle5D candle12H candle6H candle4H candle2H candle1H candle30m candle15m candle5m candle3m candle1m |
instId | String | Yes | Instrument ID |
Successful Response Example
{
"event": "subscribe",
"arg": {
"channel": "candle1D",
"instId": "BTC-USD-191227"
}
}
Failure Response Example
{
"event": "error",
"code": "60012",
"msg": "Unrecognized request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"candle1D\", \"instId\" : \"BTC-USD-191227\"}]}"
}
Response parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Event, subscribe unsubscribe error |
arg |
Object | No | Subscribed channel |
channel | String | yes | channel name |
instId | String | Yes | Instrument ID |
code | String | No | Error code |
msg | String | No | Error message |
Push Data Example
{
"arg": {
"channel": "candle1D",
"instId": "BTC-USD-191227"
},
"data": [
["1597026383085", "8533.02", "8553.74", "8527.17", "8548.26", "45247", "529.5858061"]
]
}
Push data parameters
Parameter | Type | Description |
---|---|---|
arg |
Object | Successfully subscribed channel |
> channel | String | Channel name |
> instId | String | Instrument ID |
data |
Array | Subscribed data |
> ts | String | Data generation time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
> o | String | Open price |
> h | String | Higest price |
> l | String | Lowest price |
> c | String | Close price |
> vol | String | Trading volume (cont) |
> volCcy | String | Trading volume (coin) |
Trades Channel
Retrieve the recent trades data. Data will be pushed whenever there is a trade.
Request Example
{
"op": "subscribe",
"args": [{
"channel": "trades",
"instId": "BTC-USD-191227"
}]
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation, subscribe unsubscribe |
args |
Array | Yes | List of subscribed channels |
> channel | String | Yes | Channel name, trades |
> instId | String | Yes | Instrument ID |
Successful Response Example
{
"op": "subscribe",
"args": [{
"channel": "trades",
"instId": "BTC-USD-191227"
}]
}
Failure Response Example
{
"event": "error",
"code": "60012",
"msg": "Unrecognized request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"trades\", \"instId\" : \"BTC-USD-191227\"}]}"
}
Response parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Event, subscribe unsubscribe error |
arg |
Object | No | Subscribed channel |
> channel | String | Yes | Channel name |
> instId | String | Yes | Instrument ID |
code | String | No | Error code |
msg | String | No | Error message |
Push Data Example
{
"arg": {
"channel": "trades",
"instId": "BTC-USD-191227"
},
"data": [{
"instId": "BTC-USD-191227",
"tradeId": "9",
"px": "0.016",
"sz": "50",
"side": "buy",
"ts": "1597026383085"
}]
}
Push data parameters
Parameter | Type | Description |
---|---|---|
arg |
Object | Successfully subscribed channel |
> channel | String | Channel name |
> instId | String | Instrument ID |
data |
Array | Subscribed data |
> instId | String | Instrument ID, e.g. BTC-USD-180216 |
> tradeId | String | Trade ID |
> px | String | Trade price |
> sz | String | Trade size |
> side | String | Trade direction, buy , sell |
> ts | String | Filled time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Estimated delivery/exercise Price Channel
Retrieve the estimated delivery/exercise price of FUTURES contracts and OPTION.
Only the estimated delivery/exercise price will be pushed an hour before delivery/exercise, and will be pushed if there is any price change.
Request Example
{
"op": "subscribe",
"args": [{
"channel": "estimated-price",
"instType": "FUTURES",
"uly": "BTC-USD"
}]
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation, subscribe unsubscribe |
args |
Array | Yes | List of subscribed channels |
> channel | String | Yes | Channel name, estimated-price |
> instType | String | Yes | Instrument type ANY OPTION FUTURES |
> uly | String | No | Underlying |
> instId | String | No | Instrument ID |
Successful Response Example
{
"event": "subscribe",
"arg": {
"channel": "estimated-price",
"instType": "FUTURES",
"uly": "BTC-USD"
}
}
Failure Response Example
{
"event": "error",
"code": "60012",
"msg": "Unrecognized request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"estimated-price\", \"instId\" : \"FUTURES\",\"uly\" :\"BTC-USD\"}]}"
}
Response parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Event, subscribe unsubscribe error |
arg |
Object | No | Subscribed channel |
> channel | String | Yes | Channel name |
> instType | String | Yes | Instrument type FUTURES OPTION |
> uly | String | No | Underlying |
> instId | String | No | Instrument ID |
code | String | No | Error code |
msg | String | No | Error message |
Push Data Example
{
"arg": {
"args": "estimated-price",
"instType": "FUTURES",
"uly": "BTC-USD"
},
"data": [{
"instType": "FUTURES",
"instId": "BTC-USD-170310",
"settlePx": "200",
"ts": "1597026383085"
}]
}
Push data parameters
Parameter | Type | Description |
---|---|---|
arg |
Object | Successfully subscribed channel |
> channel | String | Channel name |
> instType | String | Instrument typeFUTURES OPTION |
> uly | String | Underlying |
> instId | String | Instrument ID |
data |
Array | Subscribed data |
> instType | String | Instrument type |
> instId | String | Instrument ID, e.g. BTC-USD-170310 |
> settlePx | String | Estimated delivery/exercise price |
> ts | String | Data update time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Mark Price Channel
Retrieve the mark price. Data will be pushed every 200 ms when the mark price changes, and will be pushed every 10 seconds when the mark price does not change.
Request Example
{
"op": "subscribe",
"args": [{
"channel": "mark-price",
"instId": "LTC-USD-190628"
}]
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation, subscribe unsubscribe |
args |
Array | Yes | List of subscribed channels |
> channel | String | Yes | Channel name, mark-price |
> instId | String | Yes | Instrument ID |
Successful Response Example
{
"event": "subscribe",
"arg": {
"channel": "mark-price",
"instId": "LTC-USD-190628"
}
}
Failure Response Example
{
"event": "error",
"code": "60012",
"msg": "Unrecognized request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"mark-price\", \"instId\" : \"LTC-USD-190628\"}]}"
}
Response parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Event, subscribe unsubscribe error |
arg |
Object | No | Subscribed channel |
> channel | String | Yes | Channel name |
> instId | String | No | Instrument ID |
code | String | No | Error code |
msg | String | No | Error message |
Push Data Example
{
"arg": {
"channel": "mark-price",
"instId": "LTC-USD-190628"
},
"data": [{
"instType": "FUTURES",
"instId": "LTC-USD-190628",
"markPx": "0.1",
"ts": "1597026383085"
}]
}
Push data parameters
Parameter | Type | Description |
---|---|---|
arg |
Object | Successfully subscribed channel |
> channel | String | Channel name |
> instId | String | Instrument ID |
data |
Array | Subscribed data |
> instType | String | Instrument type |
> instId | String | Instrument ID |
> markPx | String | Mark price |
> ts | String | Price update time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Mark Price Candlesticks Channel
Retrieve the candlesticks data of the mark price. Data will be pushed every 500 ms.
Request Example
{
"op": "subscribe",
"args": [{
"channel": "mark-price-candle1D",
"instId": "BTC-USD-190628"
}]
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation, subscribe unsubscribe |
args |
Array | Yes | List of subscribed channels |
> channel | String | Yes | Channel namemark-price-candle1Y mark-price-candle6M mark-price-candle3M mark-price-candle1M mark-price-candle1W mark-price-candle1D mark-price-candle2D mark-price-candle3D mark-price-candle5D mark-price-candle12H mark-price-candle6H mark-price-candle4H mark-price-candle2H mark-price-candle1H mark-price-candle30m mark-price-candle15m mark-price-candle5m mark-price-candle3m mark-price-candle1m |
> instId | String | Yes | Instrument ID |
Successful Response Example
{
"event": "subscribe",
"arg": {
"channel": "mark-price-candle1D",
"instId": "BTC-USD-190628"
}
}
Failure Response Example
{
"event": "error",
"code": "60012",
"msg": "Unrecognized request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"mark-price-candle1D\", \"instId\" : \"BTC-USD-190628\"}]}"
}
Response parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Event, subscribe unsubscribe error |
arg |
Object | No | Subscribed channel |
> channel | String | Yes | Channel name |
> instId | String | Yes | Instrument ID |
code | String | No | Error code |
msg | String | No | Error message |
Push Data Example
{
"arg": {
"channel": "mark-price-candle1D",
"instId": "BTC-USD-190628"
},
"data": [
["1597026383085", "3.721", "3.743", "3.677", "3.708"],
["1597026383085", "3.731", "3.799", "3.494", "3.72"]
]
}
Push data parameters
Parameter | Type | Description |
---|---|---|
arg |
Object | Successfully subscribed channel |
> channel | String | Channel name |
> instId | String | Instrument ID |
data |
Array | Subscribed data |
> ts | String | Data generation time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
> o | String | Open price |
> h | String | Highest price |
> l | String | Lowest price |
> c | String | Close price |
Price Limit Channel
Retrieve the maximum buy price and minimum sell price of the instrument. Data will be pushed every 5 seconds when there are changes in limits, and will not be pushed when there is no changes on limit.
Request Example
{
"op": "subscribe",
"args": [{
"channel": "price-limit",
"instId": "LTC-USD-190628"
}]
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation, subscribe unsubscribe |
args |
Array | Yes | List of subscribed channels |
> channel | String | Yes | Channel name, price-limit |
> instId | String | Yes | Instrument ID |
Successful Response Example
{
"event": "subscribe",
"arg": {
"channel": "price-limit",
"instId": "LTC-USD-190628"
}
}
Failure Response Example
{
"event": "error",
"code": "60012",
"msg": "Unrecognized request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"price-limit\", \"instId\" : \"LTC-USD-190628\"}]}"
}
Response parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Event, subscribe unsubscribe error |
arg |
Object | No | Subscribed channel |
> channel | String | Yes | Channel name |
> instId | String | Yes | Instrument ID |
code | String | No | Error code |
msg | String | No | Error message |
Push Data Example
{
"arg": {
"channel": "price-limit",
"instId": "LTC-USD-190628"
},
"data": [{
"instId": "LTC-USD-190628",
"buyLmt": "200",
"sellLmt": "300",
"ts": "1597026383085"
}]
}
Push data parameters
Parameter | Type | Description |
---|---|---|
arg |
Object | Successfully subscribed channel |
> channel | String | Channel name |
> instId | String | Instrument ID |
data |
Array | Subscribed data |
> instType | String | Instrument type |
> instId | String | Instrument ID, e.g. BTC-USD-SWAP |
> buyLmt | String | Maximum buy price |
> sellLmt | String | Minimum sell price |
> ts | String | Price update time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Order Book Channel
Retrieve order book data.
Use books
for 400 depth levels, book5
for 5 depth levels, and books-l2-tbt
for tick-by-tick 400 depth levels.
books
: 400 depth levels will be pushed in the initial full snapshot. Incremental data will be pushed every 100 ms when there is change in order book.
books5
: 5 depth levels will be pushed every time. Data will be pushed every 100 ms when there is change in order book.
books-l2-tbt
: 400 depth levels will be pushed in the initial full snapshot. Incremental data will be pushed tick by tick, i.e. whenever there is change in order book.
Request Example
{
"op": "subscribe",
"args": [{
"channel": "books",
"instId": "BTC-USD-191227"
}]
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation, subscribe unsubscribe |
args |
Array | Yes | List of subscribed channels |
> channel | String | Yes | Channel name, books books5 books-l2-tbt |
> instId | String | Yes | Instrument ID |
Example Response
{
"event": "subscribe",
"arg": {
"channel": "books",
"instId": "BTC-USD-191227"
}
}
Failure example
{
"event": "error",
"code": "60012",
"msg": "Unrecognized request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"books\", \"instId\" : \"BTC-USD-191227\"}]}"
}
Response parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Event, subscribe unsubscribe error |
arg |
Object | No | Subscribed channel |
> channel | String | Yes | Channel name |
> instId | String | Yes | Instrument ID |
msg | String | No | Error message |
code | String | No | Error code |
Push Data Example: Full Snapshot
{
"arg": {
"channel": "books",
"instId": "BTC-USD-191227"
},
"action": "snapshot",
"data": [{
"asks": [
["8476.98", "415", "0", "13"],
["8477", "7", "0", "2"],
["8477.34", "85", "0", "1"],
["8477.56", "1", "0", "1"],
["8505.84", "8", "0", "1"],
["8506.37", "85", "0", "1"],
["8506.49", "2", "0", "1"],
["8506.96", "100", "0", "2"]
],
"bids": [
["8476.97", "256", "0", "12"],
["8475.55", "101", "0", "1"],
["8475.54", "100", "0", "1"],
["8475.3", "1", "0", "1"],
["8447.32", "6", "0", "1"],
["8447.02", "246", "0", "1"],
["8446.83", "24", "0", "1"],
["8446", "95", "0", "3"]
],
"ts": "1597026383085",
"checksum": "-855196043"
}]
}
Push Data Example: Incremental Data
{
"arg": {
"channel": "books",
"instId": "BTC-USD-191227"
},
"action": "update",
"data": [{
"asks": [
["8476.98", "415", "0", "13"],
["8477", "7", "0", "2"],
["8477.34", "85", "0", "1"],
["8477.56", "1", "0", "1"],
["8505.84", "8", "0", "1"],
["8506.37", "85", "0", "1"],
["8506.49", "2", "0", "1"],
["8506.96", "100", "0", "2"]
],
"bids": [
["8476.97", "256", "0", "12"],
["8475.55", "101", "0", "1"],
["8475.54", "100", "0", "1"],
["8475.3", "1", "0", "1"],
["8447.32", "6", "0", "1"],
["8447.02", "246", "0", "1"],
["8446.83", "24", "0", "1"],
["8446", "95", "0", "3"]
],
"ts": "1597026383085",
"checksum": "-855196043"
}]
}
Push data parameters
Parameter | Type | Description |
---|---|---|
arg |
Object | Successfully subscribed channel |
> channel | String | Channel name |
> instId | String | Instrument ID |
data |
Array | Subscribed data |
> asks | Array | Order book on sell side |
> bids | Array | Order book on buy side |
> action | String | Push data action, incremental data or full snapshot.snapshot : full update : incremental |
> ts | String | Order book generation time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
> checksum | String | Checksum |
OPTION Summary Channel
Retrieve detailed pricing information of all OPTION contracts. Data will be pushed at once.
Request Example
{
"op": "subscribe",
"args": [{
"channel": "opt-summary",
"uly": "BTC-USD"
}]
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation, subscribe unsubscribe |
args |
Array | Yes | List of subscribed channels |
> channel | String | Yes | Channel name, opt-summary |
> uly | String | Yes | Underlying |
Example Response
{
"event": "subscribe",
"arg": {
"channel": "opt-summary",
"uly": "BTC-USD"
}
}
Failure example
{
"event": "error",
"code": "60012",
"msg": "Unrecognized request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"opt-summary\", \"uly\" : \"BTC-USD\"}]}"
}
Response parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Event, subscribe unsubscribe error |
arg |
Object | No | Subscribed channel |
> channel | String | Yes | Channel name |
> uly | String | Yes | Underlying |
code | String | No | Error code |
msg | String | No | Error message |
Push Data Example
{
"arg": {
"channel": "opt-summary",
"uly": "BTC-USD"
},
"data": [{
"instType": "OPTION",
"instId": "BTC-USD-200103-5500-C",
"uly": "BTC-USD",
"delta": "0.7494223636",
"gamma": "-0.6765419039",
"theta": "-0.0000809873",
"vega": "0.0000077307",
"deltaBS": "0.7494223636",
"gammaBS": "-0.6765419039",
"thetaBS": "-0.0000809873",
"vegaBS": "0.0000077307",
"realVol": "0",
"bidVol": "",
"askVol": "1.5625",
"markVol": "0.9987",
"lever": "4.0342",
"ts": "1597026383085"
}]
}
Push data parameters
Parameter | Type | Description |
---|---|---|
arg |
Object | Successfully subscribed channel |
> channel | String | Channel name |
> uly | String | Underlying |
data |
Array | Subscribed data |
> instType | String | Instrument type, OPTION |
> instId | String | Instrument ID |
> uly | String | Underlying |
> delta | String | Sensitivity of option price to uly price |
> gamma | String | The delta's sensitivity to uly price |
> vega | String | Sensitivity of option price to implied volatility |
> theta | String | Sensitivity of option priceo remaining maturity |
> deltaBS | String | Sensitivity of option price to uly price in BS mode |
> gammaBS | String | The delta's sensitivity to uly price in BS mode |
> vegaBS | String | Sensitivity of option price to implied volatility in BS mode |
> thetaBS | String | Sensitivity of option price to remaining maturity in BS mode |
> lever | String | Leverage |
> markVol | String | Mark volatility |
> bidVol | String | Bid volatility |
> askVol | String | Ask Volatility |
> realVol | String | Realized volatility (not currently used) |
> ts | String | Price update time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Funding Rate Channel
Retrieve funding rate. Data will be pushed every minute.
Request Example
{
"op": "subscribe",
"args": [{
"channel": "funding-rate",
"instId": "BTC-USD-SWAP"
}]
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation, subscribe unsubscribe |
args |
Array | Yes | List of subscribed channels |
> channel | String | Yes | Channel name, funding-rate |
> instId | String | Yes | Instrument ID |
Successful Response Example
{
"event": "subscribe",
"arg": {
"channel": "funding-rate",
"instId": "BTC-USD-SWAP"
}
}
Failure Response Example
{
"event": "error",
"code": "60012",
"msg": "Unrecognized request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"funding-rate\", \"instId\" : \"BTC-USD-SWAP\"}]}"
}
Response parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Event, subscribe unsubscribe error |
arg |
Object | No | Subscribed channel |
> channel | String | yes | Channel name |
> instId | String | No | Instrument ID |
code | String | No | Error code |
msg | String | No | Error message |
Push Data Example
{
"arg": {
"channel": "funding-rate",
"instId": "BTC-USD-SWAP"
},
"data": [{
"instType": "SWAP",
"instId": "BTC-USD-SWAP",
"fundingRate": "0.018",
"nextFundingRate": "",
"fundingTime": "1597026383085"
}]
}
Push data parameters
Parameter | Type | Description |
---|---|---|
arg |
Object | Successfully subscribed channel |
> channel | String | Channel name |
> instId | String | Instrument ID |
data |
Array | Subscribed data |
> instType | String | Instrument type, SWAP |
> instId | String | Instrument ID, e.g. BTC-USD-SWAP |
> fundingRate | String | Current funding rate |
> nextFundingRate | String | Forecasted funding rate for the next period |
fundingTime | String | Funding time of the latest settlement, Unix timestamp format in milliseconds, e.g. 1597026383085 . |
Index Candlesticks Channel
Retrieve the candlesticks data of the index. Data will be pushed every 500 ms.
Request Example
{
"op": "subscribe",
"args": [{
"channel": "index-candle30m",
"instId": "BTC-USD"
}]
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation, subscribe unsubscribe |
args |
Array | Yes | List of subscribed channels |
> channel | String | Yes | Channel nameindex-candle1Y index-candle6M index-candle3M index-candle1M index-candle1W index-candle1D index-candle2D index-candle3D index-candle5D index-candle12H index-candle6H index-candle4H index -candle2H index-candle1H index-candle30m index-candle15m index-candle5m index-candle3m index-candle1m |
> instId | String | Yes | Instrument ID |
Successful Response Example
{
"event": "subscribe",
"arg": {
"channel": "index-candle30m",
"instId": "BTC-USD"
}
}
Failure Response Example
{
"event": "error",
"code": "60012",
"msg": "Unrecognized request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"index-candle30m\", \"instId\" : \"BTC-USD\"}]}"
}
Response parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | subscribe unsubscribe |
arg |
Object | No | Subscribed channel |
> channel | String | Yes | Channel name |
> instId | String | No | Instrument ID |
code | String | No | Error code |
msg | String | No | Error message |
Push Data Example
{
"arg": {
"channel": "index-candle30m",
"instId": "BTC-USD"
},
"data": [
["1597026383085", "3811.31", "3811.31", "3811.31", "3811.31"]
]
}
Push data parameters
Parameter | Type | Description |
---|---|---|
arg |
Object | Successfully subscribed channel |
> channel | String | Channel name |
> instId | String | Instrument ID |
data |
Array | Subscribed data |
> ts | String | Data generation time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
> o | String | Open price |
> h | String | Highest price |
> l | String | Lowest price |
> c | String | Close price |
Index Tickers Channel
Retrieve index tickers data
Request Example
{
"op": "subscribe",
"args": [{
"channel": "index-tickers",
"instId": "BTC-USDT"
}]
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | subscribe unsubscribe |
args |
Array | Yes | List of subscribed channels |
> channel | String | Yes | Channel name, index-tickers |
> instId | String | Yes | Index with USD, USDT, BTC as the quote currency, e.g. BTC-USDT |
Successful Response Example
{
"event": "subscribe",
"arg": {
"channel": "index-tickers",
"instId": "BTC-USDT"
}
}
Failure Response Example
{
"event": "error",
"code": "60012",
"msg": "Unrecognized request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"index-tickers\", \"instId\" : \"BTC-USDT\"}]}"
}
Response parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | subscribe unsubscribe error |
arg |
Object | No | Subscribed channel |
> channel | String | Yes | Channel name, index-tickers |
> instId | String | No | Instrument ID |
code | String | No | Error code |
msg | String | No | Error message |
Push Data Example
{
"arg": {
"channel": "index-tickers",
"instId": "BTC-USDT"
},
"data": [{
"instId": "BTC-USDT",
"idxPx": "0.1",
"high24h": "0.5",
"low24h": "0.1",
"open24h": "0.1",
"sodUtc0": "0.1",
"sodUtc8": "0.1",
"ts": "1597026383085"
}]
}
Push data parameters
Parameter | Type | Description |
---|---|---|
arg |
Object | Successfully subscribed channel |
> channel | String | Channel name |
> instId | String | Index with USD, USDT, or BTC as quote currency, e.g. BTC-USDT . |
data |
Array | Subscribed data |
> instId | String | Index |
> idxPx | String | Latest Index Price |
> open24h | String | Open price in the past 24 hours |
> high24h | String | Highest price in the past 24 hours |
> low24h | String | Lowest price in the past 24 hours |
> sodUtc0 | String | Open price in the UTC 0 |
> sodUtc8 | String | Open price in the UTC 8 |
> ts | String | Update time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Private Channel
Account Channel
Retrieve account information. Data will be pushed when triggered by events such as placing/canceling order, and will also be pushed in regular interval according to subscription granularity.
Request Example : single
{
"op": "subscribe",
"args": [{
"channel": "account",
"ccy": "BTC"
}]
}
Request Example
{
"op": "subscribe",
"args": [{
"channel": "account"
}]
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation, subscribe unsubscribe |
args |
Array | Yes | List of subscribed channels |
> channel | String | Yes | Channel name, account |
> ccy | String | No | Currency |
Successful Response Example : single
{
"event": "subscribe",
"arg": {
"channel": "account",
"ccy": "BTC"
}
}
Successful Response Example
{
"event": "subscribe",
"arg": {
"channel": "account"
}
}
Failure Response Example
{
"event": "error",
"code": "60012",
"msg": "Unrecognized request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"account\", \"ccy\" : \"BTC\"}]}"
}
Response parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Operation, subscribe unsubscribe error |
arg |
Object | No | Subscribed channel |
> channel | String | Yes | Channel name, account |
> ccy | String | No | Currency |
code | String | No | Error code |
msg | String | No | Error message |
Push Data Example: single
{
"arg": {
"channel": "account",
"ccy": "BTC"
},
"data": [{
"uTime": "1597026383085",
"totalEq": "41624.32",
"isoEq": "3624.32",
"adjEq": "41624.32",
"imr": "4162.33",
"mmr": "4",
"mgnRatio": "41624.32",
"details": [{
"ccy": "BTC",
"eq": "123",
"availEq": "1234",
"availBal": "1415",
"frozenBal": "14",
"ordFrozen": "12",
"upl": "124",
"mgnRatio": "124",
"interest": "12",
"liab": "1"
}]
}]
}
Push Data Example
{
"arg": {
"channel": "account"
},
"data": [{
"uTime": "1597026383085",
"totalEq": "41624.32",
"isoEq": "3624.32",
"adjEq": "41624.32",
"imr": "4162.33",
"mmr": "4",
"mgnRatio": "41624.32",
"details": [{
"ccy": "BTC",
"eq": "123",
"availEq": "1234",
"availBal": "1415",
"frozenBal": "14",
"ordFrozen": "12",
"upl": "124",
"mgnRatio": "124",
"interest": "12",
"liab": "1"
}, {
"ccy": "ETH",
"eq": "223",
"availEq": "2234",
"availBal": "415",
"frozenBal": "141",
"ordFrozen": "12",
"upl": "124",
"mgnRatio": "124",
"interest": "0",
"liab": "0"
}]
}]
}
Push data parameters
Parameter | Type | Description |
---|---|---|
arg |
Object | Channel to subscribe to |
> channel | String | Channel name |
> ccy | String | Currency |
data |
Array | Subscribed data |
> uTime | String | Push time of account information, millisecond format of Unix timestamp, e.g. 1597026383085 . |
> totalEq | String | Total equity in USD level |
> isoEq | String | Isolated margin equity in USD level Applicable to Single-currency margin account and Multi-currency margin account |
> adjEq | String | Adjusted/Effective equity in USD level Applicable to Multi-currency margin account |
> imr | String | Initial margin requirement in USD level Applicable to Multi-currency margin account |
> mmr | String | Maintenance margin requirement in USD level Applicable to Multi-currency margin account |
> mgnRatio | String | Margin ratio in USD level Applicable to Multi-currency margin account |
> details | Array | Currency level details |
>> ccy | String | Currency |
>> eq | String | Equity of the currency |
>> isoEq | String | Isolated margin equity of the currency Applicable to Single-currency margin account and Multi-currency margin account |
>> availEq | String | Available equity of the currency Applicable to Single-currency margin account and Multi-currency margin account |
>> availBal | String | Available balance of the currency Applicable to Simple account |
>> frozenBal | String | Frozen balance of the currency |
>> ordFrozen | String | Margin frozen for open orders |
>> liab | String | Liabilities of the currency Applicable to Multi-currency margin account |
>> upl | String | Unrealized profit and loss of the currency Applicable to Single-currency margin account and Multi-currency margin account |
>> mgnRatio | String | Margin ratio of the currency Applicable to Single-currency margin account |
>> interest | String | Interest of the currency Applicable to Multi-currency margin account |
Distribution of applicable fields under each account level are as follows:
Parameters | Simple account | Single-currency margin account | Multi-currency margin account |
---|---|---|---|
uTime | Yes | Yes | Yes |
totalEq | Yes | Yes | Yes |
isoEq | Yes | Yes | |
adjEq | Yes | ||
imr | Yes | ||
mmr | Yes | ||
mgnRatio | Yes | ||
details | |||
> ccy | Yes | Yes | Yes |
> eq | Yes | Yes | Yes |
> isoEq | Yes | Yes | |
> availEq | Yes | Yes | |
> availBal | Yes | ||
> frozenBal | Yes | Yes | Yes |
> ordFrozen | Yes | Yes | Yes |
> liab | Yes | ||
> upl | Yes | Yes | |
> mgnRatio | Yes | ||
> interest | Yes |
Positions Channel
Retrieve position information. Initial snapshot will be pushed according to subscription granularity. Data will be pushed when triggered by events such as placing/canceling order, and will also be pushed in regular interval according to subscription granularity.
Request Example : single
{
"op": "subscribe",
"args": [{
"channel": "positions",
"instType": "FUTURES",
"uly": "BTC-USD",
"instId": "BTC-USD-200329"
}]
}
Request Example
{
"op": "subscribe",
"args": [{
"channel": "positions",
"instType": "ANY"
}]
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation, subscribe unsubscribe |
args |
Array | Yes | List of subscribed channels |
> channel | String | Yes | Channel name, positions |
> instType | String | Yes | Instrument typeMARGIN SWAP FUTURES OPTION ANY |
> uly | String | No | Underlying |
> instId | String | No | Instrument ID |
Successful Response Example : single
{
"event": "subscribe",
"arg": {
"channel": "positions",
"instType": "FUTURES",
"uly": "BTC-USD",
"instId": "BTC-USD-200329"
}
}
Successful Response Example
{
"event": "subscribe",
"arg": {
"channel": "positions",
"instType": "ANY"
}
}
Failure Response Example
{
"event": "error",
"code": "60012",
"msg": "Unrecognized request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"positions\", \"instType\" : \"FUTURES\"}]}"
}
Response parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Event, subscribe unsubscribe errror |
arg |
Object | No | Subscribed channel |
> channel | String | Yes | Channel name |
> instType | String | Yes | Instrument typeOPTION FUTURES SWAP MARGIN ANY |
> uly | String | No | Underlying |
> instId | String | No | Instrument ID |
code | String | No | Error code |
msg | String | No | Error message |
Push Data Example: single
{
"arg": {
"channel": "positions",
"instType": "FUTURES",
"instId": "BTC-USD-200329"
},
"data": [{
"instId": "BTC-USD-200329",
"instType": "FUTURES",
"mgnMode": "cross",
"posSide": "long",
"pos": "10",
"ccy": "BTC",
"posCcy": "",
"availPos": "10",
"avgPx": "3320",
"upl": "0.00020928",
"uplRatio": "0.00020928",
"lever": "2",
"liqPx": "0.00020928",
"imr": "2",
"margin": "",
"mgnRatio": "",
"mmr": "2",
"liab": "0.00020928",
"liabCcy": "USDT",
"interest": "2",
"tradeId": "2",
"optVal": "",
"adl": "1",
"last": "13452.1",
"cTime": "1597026383085",
"uTime": "1597026383085",
"pTime": "1597026383085"
}]
}
Push Data Example
{
"arg": {
"channel": "positions",
"instType": "ANY"
},
"data": [{
"instId": "BTC-USD-200329",
"instType": "FUTURES",
"mgnMode": "cross",
"posSide": "long",
"pos": "10",
"ccy": "BTC",
"posCcy": "",
"availPos": "10",
"avgPx": "3320",
"upl": "0.00020928",
"uplRatio": "0.00020928",
"lever": "2",
"liqPx": "0.00020928",
"imr": "2",
"margin": "",
"mgnRatio": "",
"mmr": "2",
"liab": "0.00020928",
"liabCcy": "USDT",
"interest": "2",
"tradeId": "2",
"optVal": "",
"adl": "1",
"last": "13452.1",
"cTime": "1597026383085",
"uTime": "1597026383085",
"pTime": "1597026383085"
}, {
"instType": "SWAP",
"instId": "BTC-USD-SWAP",
"mgnMode": "cross",
"posSide": "long",
"pos": "10",
"ccy": "BTC",
"posCcy": "",
"availPos": "10",
"avgPx": "3320",
"upl": "0.00020928",
"uplRatio": "0.00020928",
"lever": "2",
"liqPx": "0.00020928",
"imr": "2",
"margin": "",
"mgnRatio": "",
"mmr": "2",
"liab": "0.00020928",
"liabCcy": "USDT",
"interest": "2",
"tradeId": "2",
"optVal": "",
"adl": "1",
"last": "1342.1",
"cTime": "1597026383085",
"uTime": "1597026383085",
"pTime": "1597026383085"
}]
}
Push data parameters
Parameter | Type | Description |
---|---|---|
arg |
Object | Successfully subscribed channel |
> channel | String | Channel name |
> instType | String | Instrument type |
> uly | String | Underlying |
> instId | String | Instrument ID |
data |
Array | Subscribed data |
> instType | String | Instrument type |
> mgnMode | String | Margin mode, cross isolated |
> posSide | String | Position sidelong short net (FUTURES/SWAP/OPTION : positive pos means long position and negative pos means short position. MARGIN : posCcy being base currency means long position, posCcy being quote currency means short position.) |
> pos | String | Quantity of positions |
> posCcy | String | Position currency, only applicable to MARGIN positions |
> availPos | String | Position that can be closed Only applicable to MARGIN , FUTURES/SWAP in the long-short mode, OPTION in Simple Account and isolated OPTION in margin Account. |
> avgPx | String | Average open price |
> upl | String | Unrealized profit and loss |
> uplRatio | String | Unrealized profit and loss ratio |
> instId | String | Instrument ID, e.g. BTC-USD-180216 |
> lever | String | Leverage, not applicable to OPTION seller |
> liqPx | String | Estimated liquidation price Not applicable to cross FUTURES/SWAP in Multi-currency margin account .Not applicable to OPTION |
> imr | String | Initial margin requirement, only applicable to cross |
> margin | String | Margin, can be added or reduced. Only applicable to isolated Margin . |
> mgnRatio | String | Margin ratio, only applicable toisolated . |
> mmr | String | Maintenance margin requirement |
> liab | String | Liabilities, only applicable to MARGIN . |
> liabCcy | String | Liabilities currency, only applicable to MARGIN . |
> interest | String | Interest. Interest that has been incurred. |
> tradeId | String | Last trade ID |
> optVal | String | Option Value, only applicable to OPTION . |
> adl | String | Auto decrease line, signal area Divided into 5 levels, from 1 to 5, the smaller the number, the weaker the adl intensity. |
> ccy | String | Currency used for margin |
> last | String | Latest traded price |
> cTime | String | Creation time, Unix timestamp format in milliseconds, e.g. 1597026383085 . |
> uTime | String | Latest time position was adjusted, Unix timestamp format in milliseconds, e.g. 1597026383085 . |
> pTime | String | Push time of positions information, Unix timestamp format in milliseconds, e.g. 1597026383085 . |
Order Channel
Retrieve order information. Data will not be pushed when first subscribed. Data will only be pushed when triggered by events such as placing/canceling order.
Request Example : single
{
"op": "subscribe",
"args": [{
"channel": "orders",
"instType": "FUTURES",
"uly": "BTC-USD",
"instId": "BTC-USD-200329"
}]
}
Request Example
{
"op": "subscribe",
"args": [{
"channel": "orders",
"instType": "FUTURES",
"uly": "BTC-USD"
}]
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation, subscribe unsubscribe |
args |
Array | Yes | List of subscribed channels |
> channel | String | Yes | Channel name, orders |
> instType | String | Yes | Instrument typeSPOT MARGIN SWAP FUTURES OPTION ANY |
> uly | String | No | Underlying |
> instId | String | No | Instrument ID |
Successful Response Example : single
{
"event": "subscribe",
"arg": {
"channel": "orders",
"instType": "FUTURES",
"uly": "BTC-USD"
}
}
Successful Response Example
{
"event": "subscribe",
"arg": {
"channel": "orders",
"instType": "FUTURES",
"uly": "BTC-USD"
}
}
Failure Response Example
{
"event": "error",
"code": "60012",
"msg": "Unrecognized request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"orders\", \"instType\" : \"FUTURES\"}]}"
}
Response parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Event, subscribe unsubscribe errror |
arg |
Object | No | Subscribed channel |
> channel | String | Yes | Channel name |
> instType | String | Yes | Instrument typeSPOT MARGIN SWAP FUTURES OPTION ANY |
> uly | String | No | Underlying |
> instId | String | No | Instrument ID |
code | String | No | Error code |
msg | String | No | Error message |
Push Data Example: single
{
"arg": {
"channel": "orders",
"instType": "FUTURES",
"instId": "BTC-USD-200329"
},
"data": [{
"instType": "FUTURES",
"instId": "BTC-USD-200329",
"ccy": "BTC",
"ordId": "123445",
"clOrdId": "b1",
"tag": "",
"px": "999",
"sz": "3",
"ordType": "limit",
"side": "buy",
"posSide": "long",
"tdMode": "cross",
"fillSz": "0",
"fillPx": "long",
"tradeId": "0",
"accFillSz": "323",
"fillTime": "0",
"state": "canceled",
"avgPx": "0",
"lever": "20",
"tpTriggerPx": "0",
"tpOrdPx": "20",
"slTriggerPx": "0",
"slOrdPx": "20",
"feeCcy": "",
"fee": "",
"rebateCcy": "",
"rebate": "",
"pnl": "",
"category": "",
"uTime": "1597026383085",
"cTime": "1597026383085",
"reqId": "",
"amendResult": "",
"code": "0",
"msg": ""
}]
}
Push Data Example
{
"arg": {
"channel": "orders",
"instType": "FUTURES",
"uly": "BTC-USD"
},
"data": [{
"instType": "FUTURES",
"instId": "BTC-USD-200329",
"ccy": "BTC",
"ordId": "123445",
"clOrdId": "b1",
"tag": "",
"px": "999",
"sz": "3",
"ordType": "limit",
"side": "buy",
"posSide": "long",
"tdMode": "cross",
"fillSz": "0",
"fillPx": "long",
"tradeId": "0",
"accFillSz": "323",
"fillTime": "0",
"state": "canceled",
"avgPx": "0",
"lever": "20",
"tpTriggerPx": "0",
"tpOrdPx": "20",
"slTriggerPx": "0",
"slOrdPx": "20",
"feeCcy": "",
"fee": "",
"rebateCcy": "",
"rebate": "",
"pnl": "",
"category": "",
"uTime": "1597026383085",
"cTime": "1597026383085",
"reqId": "",
"amendResult": "",
"code": "0",
"msg": ""
}, {
"instType": "FUTURES",
"instId": "BTC-USD-200829",
"ccy": "BTC",
"ordId": "123445",
"clOrdId": "b1",
"tag": "",
"px": "999",
"sz": "3",
"ordType": "limit",
"side": "buy",
"posSide": "long",
"tdMode": "cross",
"fillSz": "0",
"fillPx": "long",
"tradeId": "0",
"accFillSz": "323",
"fillTime": "0",
"state": "canceled",
"avgPx": "0",
"lever": "20",
"tpTriggerPx": "0",
"tpOrdPx": "20",
"slTriggerPx": "0",
"slOrdPx": "20",
"feeCcy": "",
"fee": "",
"rebateCcy": "",
"rebate": "",
"pnl": "",
"category": "",
"uTime": "1597026383085",
"cTime": "1597026383085",
"reqId": "",
"amendResult": "",
"code": "0",
"msg": ""
}]
}
Push data parameters
Parameter | Type | Description |
---|---|---|
arg |
Object | Successfully subscribed channel |
> channel | String | Channel name |
> instType | String | Instrument type |
> uly | String | Underlying |
> instId | String | Instrument ID |
data |
Array | Subscribed data |
> instType | String | Instrument type |
> instId | String | Instrument ID |
> ccy | String | Margin currency Only applicable to cross MARGIN orders in Single-currency margin account . |
> ordId | String | Order ID |
> clOrdId | String | Client-supplied order ID |
> tag | String | Order tag |
> px | String | Order price |
> sz | String | The original order quantity, SPOT/MARGIN , in the unit of currency; FUTURES/SWAP/OPTION , in the unit of contract |
> ordType | String | Order typemarket : market orderlimit : limit orderpost_only : Post-only orderfok : Fill-or-kill orderioc : Immediate-or-cancel order |
> side | String | Order side, buy sell |
> posSide | String | Position side net long or short Only applicable to FUTURES/SWAP |
> tdMode | String | Trade mode, cross : cross isolated : isolated cash : cash |
> fillPx | String | Last filled price |
> tradeId | String | Last trade ID |
> fillSz | String | Last filled quantity |
> fillTime | String | Last filled time |
> accFillSz | String | Accumulated fill quantity |
> avgPx | String | Average filled price. If none is filled, it will return 0 . |
> state | String | Order state canceled live partially_filled filled |
> lever | String | Leverage, from 0.01 to 125 .Only applicable to MARGIN/FUTURES/SWAP |
> tpTriggerPx | String | Take-profit trigger price, it must be between 0 and 1,000,000. |
> tpOrdPx | String | Take-profit order price, it must be between 0 and 1,000,000. |
> slTriggerPx | String | Stop-loss trigger price, it must be between 0 and 1,000,000. |
> slOrdPx | String | Stop-loss order price, it must be between 0 and 1,000,000. |
> feeCcy | String | Fee currencySPOT/MARGIN : If you buy, you will receive BTC; if you sell, you will receive USDTFUTURES/SWAP/OPTION What is charged is the margin |
> fee | String | Fee, transaction fee charged by the platform. |
> rebateCcy | String | Rebate currency, if there is no rebate, this field is "". |
> rebate | String | Rebate amount, the reward of placing orders from the platform (rebate) given to user who has reached the specified trading level. If there is no rebate, this field is "". |
> pnl | String | Profit and loss |
> category | String | Categorynormal twap adl full_liquidation partial_liquidation |
> uTime | String | Update time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
> cTime | String | Creation time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
> reqId | String | Client-supplied request ID for order amendment. "" will be returned if there is no order amendment. |
> amendResult | String | The result of amending the order-1 : failure0 : success1 : Automatic cancel (due to successful amendment) When amending the order through API and the amendment failed, -1 will be returned if cxlOnFail is set to false . Otherwise 1 will be returned if cxlOnFail is set to true . When amending the order through Web/APP and the amendment failed, -1 will be returned. |
> code | String | Error Code, the default is 0 |
> msg | String | Error Message, The default is "" |
Algo Orders Channel
Retrieve algo orders. Data will not be pushed when first subscribed. Data will only be pushed when triggered by events such as placing/canceling order.
Request Example : single
{
"op": "subscribe",
"args": [{
"channel": "orders-algo",
"instType": "FUTURES",
"uly": "BTC-USD",
"instId": "BTC-USD-200329"
}]
}
Request Example
{
"op": "subscribe",
"args": [{
"channel": "orders-algo",
"instType": "FUTURES",
"uly": "BTC-USD"
}]
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation, subscribe unsubscribe |
args |
Array | Yes | List of subscribed channels |
> channel | String | Yes | Channel name |
> instType | String | Yes | Instrument typeSPOT MARGIN SWAP FUTURES ANY |
> uly | String | No | Underlying |
> instId | String | No | Instrument ID |
Successful Response Example : single
{
"event": "subscribe",
"arg": {
"channel": "orders-algo",
"instType": "FUTURES",
"uly": "BTC-USD",
"instId": "BTC-USD-200329"
}
}
Successful Response Example
{
"event": "subscribe",
"arg": {
"channel": "orders-algo",
"instType": "FUTURES",
"uly": "BTC-USD"
}
}
Failure Response Example
{
"event": "error",
"code": "60012",
"msg": "Unrecognized request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"orders-algo\", \"instType\" : \"FUTURES\"}]}"
}
Response parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Event, subscribe unsubscribe errror |
arg |
Object | No | Subscribed channel |
> channel | String | Yes | Channel name |
> instType | String | Yes | Instrument typeSPOT MARGIN SWAP FUTURES ANY |
> uly | String | No | Underlying |
> instId | String | No | Instrument ID |
code | String | No | Error code |
msg | String | No | Error message |
Push Data Example: single
{
"arg": {
"channel": "orders-algo",
"instType": "FUTURES",
"instId": "BTC-USD-200329"
},
"data": [{
"instType": "FUTURES",
"instId": "BTC-USD-200329",
"ordId": "123445",
"ccy": "BTC",
"algoId": "1234",
"px": "999",
"sz": "3",
"ordType": "trigger",
"side": "buy",
"posSide": "long",
"state": "1",
"lever": "20",
"tpTriggerPx": "",
"tpOrdPx": "",
"slTriggerPx": "",
"triggerPx": "99",
"ordPx": "12",
"actualSz": "",
"actualPx": "",
"actualSide": "",
"triggerTime": "1597026383085",
"cTime": "1597026383000"
}]
}
Push Data Example
{
"arg": {
"channel": "orders-algo",
"instType": "FUTURES",
"uly": "BTC-USD"
},
"data": [{
"instType": "FUTURES",
"instId": "BTC-USD-200329",
"ordId": "123445",
"ccy": "BTC",
"algoId": "1234",
"px": "999",
"sz": "3",
"ordType": "trigger",
"side": "buy",
"posSide": "long",
"state": "1",
"lever": "20",
"tpTriggerPx": "",
"tpOrdPx": "",
"slTriggerPx": "",
"triggerPx": "99",
"ordPx": "12",
"actualSz": "",
"actualPx": "",
"actualSide": "",
"triggerTime": "1597026383085",
"cTime": "1597026383000"
}, {
"instType": "FUTURES",
"instId": "BTC-USD-200829",
"ordId": "123445",
"ccy": "BTC",
"algoId": "1234",
"px": "999",
"sz": "3",
"ordType": "trigger",
"side": "buy",
"posSide": "long",
"state": "1",
"lever": "20",
"tpTriggerPx": "",
"tpOrdPx": "",
"slTriggerPx": "",
"triggerPx": "99",
"ordPx": "12",
"actualSz": "",
"actualPx": "",
"actualSide": "",
"triggerTime": "1597026383085",
"cTime": "1597026383000"
}]
}
Response parameters when data is pushed.
Parameter | Type | Description |
---|---|---|
arg |
Object | Successfully subscribed channel |
> channel | String | Channel name |
> instType | String | Instrument type |
> uly | String | Underlying |
> instId | String | Instrument ID |
data |
Array | Subscribed data |
> instType | String | Instrument type |
> instId | String | Instrument ID |
> ccy | String | Margin currency Only applicable to cross MARGIN orders in Single-currency margin account . |
> ordId | String | Order ID, the order ID associated with the algo order. |
> algoId | String | Algo ID |
> sz | String | Quantity to buy or sell. SPOT/MARGIN : in the unit of currency. FUTURES/SWAP/OPTION : in the unit of contract. |
> ordType | String | Order typeconditional : One-way stop order oco : One-cancels-the-other ordertrigger : Trigger order |
> side | String | Order side, buy sell |
> posSide | String | Position sidenet long or short Only applicable to FUTURES/SWAP |
> tdMode | String | Trade mode, cross : cross isolated : isolated cash : cash |
> lever | String | Leverage, from 0.01 to 125 .Only applicable to MARGIN/FUTURES/SWAP |
> state | String | Order status live : to be effectiveeffective : effectivecanceled : canceledorder_failed : order failed |
> tpTriggerPx | String | Take-profit trigger price. It must be between 0 and 1,000,000. |
> tpOrdPx | String | Take-profit order price. It must be between 0 and 1,000,000. |
> slTriggerPx | String | Stop-loss trigger price. It must be between 0 and 1,000,000. |
> slOrdPx | String | Stop-loss order price. It must be between 0 and 1,000,000. |
> triggerPx | String | Trigger price |
> ordPx | String | Order price |
> actualSz | String | Actual order quantity |
> actualPx | String | Actual order price |
> actualSide | String | Actual trigger side |
> triggerTime | String | Trigger time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
> cTime | String | Creation time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Trade
The WebSocket Trade
APIs require authentication.
Place Order
You can place an order only if you have sufficient funds.
Rate Limit: 60 requests per 2 seconds
Request Example
{
"id": "1512",
"op": "order",
"args": [{
"side": "buy",
"instId": "BTC-USDT",
"tdMode": "isolated",
"ordType": "market",
"sz": "1"
}]
}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
id | String | Yes | Unique identifier of the message Provided by client. It will be returned in response message for identifying the corresponding request. A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. |
op | String | Yes | Operation, e.g. order |
args | Array | Yes | Request parameters |
> instId | String | Yes | Instrument ID,e.g. BTC-USD-190927-5000-C |
> tdMode | String | Yes | Trade mode Margin mode isolated cross Non-Margin mode cash |
> ccy | String | No | Margin currency Only applicable to cross MARGIN orders in Single-currency margin account . |
> clOrdId | String | No | Client-supplied order ID A combination of case-sensitive alphanumerics beginning with a letter, or alphabets of up to 32 characters. |
> tag | String | No | Order tag A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 8 characters. |
> side | String | Yes | Order side, buy sell |
> posSide | String | No | Position side The default is net in the net modeIt is required in the long/short mode, and can only be long or short .Only applicable to FUTURES/SWAP . |
> ordType | String | Yes | Order type market limit post_only fok ioc |
> sz | String | Yes | Quantity to buy or sell. |
> px | String | No | Price Only applicable to limit order. |
> reduceOnly | Boolean | No | Whether to reduce positions only, true false , and the default is false . Only applicable to MARGIN . |
Successful Response Example
{
"id": "1512",
"op": "order",
"data": [{
"clOrdId": "",
"ordId": "12345689",
"tag": "",
"sCode": "0",
"sMsg": ""
}],
"code": "0",
"msg": ""
}
Failure Response Example
{
"id": "1512",
"op": "order",
"data": [{
"clOrdId": "",
"ordId": "",
"tag": "",
"sCode": "5XXXX",
"sMsg": "not exist"
}],
"code": "1",
"msg": ""
}
Example Response When Format Error
{
"id": "1512",
"op": "order",
"data": [],
"code": "60013",
"msg": "Invalid args"
}
Response Parameters
Parameter | Type | Description |
---|---|---|
id | String | Unique identifier of the message |
op | String | Operation |
code | String | Error Code |
msg | String | Error message |
data | Array | Data |
> ordId | String | Order ID |
> clOrdId | String | Client-supplied order ID |
> tag | String | Order tag |
> sCode | String | Order status code, 0 means success |
> sMsg | String | Order status message |
Place Multiple Orders
Place orders in a batch. Maximum 20 orders can be placed at a time
Rate Limit: 300 requests per 2 seconds
Request Example
{
"id": "1513",
"op": "batch-orders",
"args": [{
"side": "buy",
"instId": "BTC-USDT",
"tdMode": "isolated",
"ordType": "limit",
"sz": "1"
}, {
"side": "buy",
"instId": "BTC-USD-200925",
"tdMode": "isolated",
"ordType": "limit",
"sz": "1"
}]
}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
id | String | Yes | Unique identifier of the message Provided by client. It will be returned in response message for identifying the corresponding request. A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. |
op | String | Yes | Operation, e.g. batch-orders |
args | Array | Yes | Request Parameters |
> instId | String | Yes | Instrument ID, e.g. BTC-USD-190927-5000-C |
> tdMode | String | Yes | Trade mode Margin mode isolated cross Non-Margin mode cash |
> ccy | String | No | Margin currency Only applicable to cross MARGIN orders in Single-currency margin account . |
> clOrdId | String | No | Client-supplied order ID A combination of case-sensitive alphanumerics beginning with a letter, or alphabets of up to 32 characters. |
> tag | String | No | Order tag A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 8 characters. |
> side | String | Yes | Order side, buy sell |
> posSide | String | No | Position side The default net in the net modeIt is required in the long/short mode, and only be long or short .Only applicable to FUTURES/SWAP . |
> ordType | String | Yes | Order type market limit post_only fok ioc |
> sz | String | Yes | The number of transactions indicates the quantity to be bought or sold. |
> px | String | No | Price Only applicable to limit order. |
> reduceOnly | Boolean | No | Whether to reduce positions only, true false , and the default is false . Only applicable to MARGIN . |
Example Response When All Succeed
{
"id": "1513",
"op": "batch-orders",
"data": [{
"clOrdId": "",
"ordId": "12345689",
"tag": "",
"sCode": "0",
"sMsg": ""
}, {
"clOrdId": "",
"ordId": "12344",
"tag": "",
"sCode": "0",
"sMsg": ""
}],
"code": "0",
"msg": ""
}
Example Response When Partially Successful
{
"id": "1513",
"op": "batch-orders",
"data": [{
"clOrdId": "",
"ordId": "12345689",
"tag": "",
"sCode": "0",
"sMsg": ""
}, {
"clOrdId": "",
"ordId": "",
"tag": "",
"sCode": "5XXXX",
"sMsg": "Insufficient margin"
}],
"code": "2",
"msg": ""
}
Example Response When All Failed
{
"id": "1513",
"op": "batch-orders",
"data": [{
"clOrdId": "oktswap6",
"ordId": "",
"tag": "",
"sCode": "5XXXX",
"sMsg": "Insufficient margin"
}, {
"clOrdId": "oktswap7",
"ordId": "",
"tag": "",
"sCode": "5XXXX",
"sMsg": "Insufficient margin"
}],
"code": "1",
"msg": ""
}
Example Response When Format Error
{
"id": "1513",
"op": "batch-orders",
"data": [],
"code": "60013",
"msg": "Invalid args"
}
Response Parameters
Parameter | Type | Description |
---|---|---|
id | String | Unique identifier of the message |
op | String | Operation |
code | String | Error Code |
msg | String | Error message |
data | Array | Data |
> ordId | String | Order ID |
> clOrdId | String | Client-supplied order ID |
> tag | String | Order tag |
> sCode | String | Order status code, 0 means success |
> sMsg | String | Order status message |
Cancel Order
Cancel an incomplete order
Rate Limit: 60 requests per 2 seconds
Request Example
{
"id": "1514",
"op": "cancel-order",
"args": [{
"instId": "BTC-USDT-200920",
"ordId": "2510789768709120"
}]
}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
id | String | Yes | Unique identifier of the message Provided by client. It will be returned in response message for identifying the corresponding request. A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. |
op | String | Yes | Operation, e.g. cancel-order |
args | Array | Yes | Request Parameters |
> instId | String | Yes | Instrument ID |
> ordId | String | Optional | Order ID Either ordId or clOrdId is required, if both are passed, ordId will be used |
> clOrdId | String | Optional | Client-supplied order ID Start with a letter, 1 to 32 letters and numbers |
Successful Response Example
{
"id": "1514",
"op": "cancel-order",
"data": [{
"clOrdId": "",
"ordId": "2510789768709120",
"sCode": "0",
"sMsg": ""
}],
"code": "0",
"msg": ""
}
Failure Response Example
{
"id": "1514",
"op": "cancel-order",
"data": [{
"clOrdId": "",
"ordId": "2510789768709120",
"sCode": "5XXXX",
"sMsg": "Order not exist"
}],
"code": "1",
"msg": ""
}
Example Response When Format Error
{
"id": "1514",
"op": "cancel-order",
"data": [],
"code": "60013",
"msg": "Invalid args"
}
Response Parameters
Parameter | Type | Description |
---|---|---|
id | String | Unique identifier of the message |
op | String | Operation |
code | String | Error Code |
msg | String | Error message |
data | Array | Data |
> ordId | String | Order ID |
> clOrdId | String | Client-supplied order ID |
> sCode | String | Order status code, 0 means success |
> sMsg | String | Order status message |
Cancel Multiple Orders
Cancel incomplete orders in batches. Maximum 20 orders can be canceled at a time.
Rate Limit: 300 requests per 2 seconds
Request Example
{
"id": "1515",
"op": "batch-cancel-orders",
"args": [{
"instId": "BTC-USDT-200920",
"ordId": "2517748157541376"
}, {
"instId": "LTC-USDT-200920",
"ordId": "2517748155771904"
}]
}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
id | String | Yes | Unique identifier of the message Provided by client. It will be returned in response message for identifying the corresponding request. A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. |
op | String | Yes | Operation, e.g. batch-cancel-orders |
args | Array | Yes | Request Parameters |
> instId | String | Yes | Instrument ID |
> ordId | String | Optional | Order ID Either ordId or clOrdId is required, if both are passed, ordId will be used |
> clOrdId | String | Optional | Client-supplied order ID Start with a letter, 1 to 32 letters and numbers |
Example Response When All Succeed
{
"id": "1515",
"op": "batch-cancel-orders",
"data": [{
"clOrdId": "oktswap6",
"ordId": "2517748157541376",
"sCode": "0",
"sMsg": ""
}, {
"clOrdId": "oktswap7",
"ordId": "2517748155771904",
"sCode": "0",
"sMsg": ""
}],
"code": "0",
"msg": ""
}
Example Response When partially successfully
{
"id": "1515",
"op": "batch-cancel-orders",
"data": [{
"clOrdId": "oktswap6",
"ordId": "2517748157541376",
"sCode": "0",
"sMsg": ""
}, {
"clOrdId": "oktswap7",
"ordId": "2517748155771904",
"sCode": "5XXXX",
"sMsg": "order not exist"
}],
"code": "2",
"msg": ""
}
Example Response When All Failed
{
"id": "1515",
"op": "batch-cancel-orders",
"data": [{
"clOrdId": "oktswap6",
"ordId": "2517748157541376",
"sCode": "5XXXX",
"sMsg": "order not exist"
}, {
"clOrdId": "oktswap7",
"ordId": "2517748155771904",
"sCode": "5XXXX",
"sMsg": "order not exist"
}],
"code": "1",
"msg": ""
}
Example Response When Format Error
{
"id": "1515",
"op": "batch-cancel-orders",
"data": [],
"code": "60013",
"msg": "Invalid args"
}
Response Parameters
Parameter | Type | Description |
---|---|---|
id | String | Unique identifier of the message |
op | String | Operation |
code | String | Error Code |
msg | String | Error message |
data | Array | Data |
> ordId | String | Order ID |
> clOrdId | String | Client-supplied order ID |
> sCode | String | Order status code, 0 means success |
> sMsg | String | Order status message |
Amend Order
Amend an incomplete order.
Rate Limit: 60 requests per 2 seconds
Request Example
{
"id": "1512",
"op": "amend-order",
"args": [{
"instId": "BTC-USDT-200920",
"ordId": "2510789768709120",
"newSz": "2"
}]
}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
id | String | Yes | Unique identifier of the message Provided by client. It will be returned in response message for identifying the corresponding request. A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. |
op | String | Yes | Operation, e.g. amend-order |
args | Array | Yes | Request Parameters |
> instId | String | Yes | Instrument ID |
> cxlOnFail | Boolean | No | Whether the order needs to be automatically canceled when amendment fails. false or true , the default is false . |
> ordId | String | Optional | Order ID Either ordId or clOrdId is required, if both are passed, ordId will be used. |
> clOrdId | String | Optional | Client-supplied order ID |
> reqId | String | No | Client-supplied request ID A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. |
> newSz | String | Optional | New quantity after amendment. Either newSz or newPx is required. When amending a partially-filled order, the newSz should include the amount that has been filled. |
> newPx | String | Optional | New price after amendment. |
Successful Response Example
{
"id": "1512",
"op": "amend-order",
"data": [{
"clOrdId": "",
"ordId": "2510789768709120",
"reqId": "b12344",
"sCode": "0",
"sMsg": ""
}],
"code": "0",
"msg": ""
}
Failure Response Example
{
"id": "1512",
"op": "amend-order",
"data": [{
"clOrdId": "",
"ordId": "2510789768709120",
"reqId": "b12344",
"sCode": "5XXXX",
"sMsg": "order not exist"
}],
"code": "1",
"msg": ""
}
Example Response When Format Error
{
"id": "1512",
"op": "amend-order",
"data": [],
"code": "60013",
"msg": "Invalid args"
}
Response Parameters
Parameter | Type | Description |
---|---|---|
id | String | Unique identifier of the message |
op | String | Operation |
code | String | Error Code |
msg | String | Error message |
data | Array | Data |
> ordId | String | Order ID |
> clOrdId | String | Client-supplied order ID |
> reqId | String | Client-supplied request ID |
> sCode | String | Order status code, 0 means success |
> sMsg | String | Order status message |
Amend Multiple Orders
Amend incomplete orders in batches. Maximum 20 orders can be amended at a time.
Rate Limit: 300 requests per 2 seconds
Request Example
{
"id": "1513",
"op": "batch-amend-orders",
"args": [{
"instId": "BTC-USDT-200920",
"ordId": "12345689",
"newSz": "2"
}, {
"instId": "BTC-USDT-200920",
"ordId": "12344",
"newSz": "2"
}]
}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
id | String | Yes | Unique identifier of the message Provided by client. It will be returned in response message for identifying the corresponding request. A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. |
op | String | Yes | Operation, e.g. batch-amend-orders |
args | Array | Yes | Request Parameters |
> instId | String | Yes | Instrument ID |
> cxlOnFail | Boolean | No | Whether the order needs to be automatically cancelled when the order amendment fails false true , the default is false |
> ordId | String | Optional | Order ID Either ordId or clOrdId is required, if both are passed, ordId will be used. |
> clOrdId | String | Optional | Client-supplied order ID |
> reqId | String | No | Client-supplied request ID A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. |
> newSz | String | Optional | New quantity after amendment. Either newSz or newPx is required. When amending a partially-filled order, the newSz should include the amount that has been filled. |
> newPx | String | Optional | New price after amendment. |
Example Response When All Succeed
{
"id": "1513",
"op": "batch-amend-orders",
"data": [{
"clOrdId": "oktswap6",
"ordId": "12345689",
"reqId": "b12344",
"sCode": "0",
"sMsg": ""
}, {
"clOrdId": "oktswap7",
"ordId": "12344",
"reqId": "b12344",
"sCode": "0",
"sMsg": ""
}],
"code": "0",
"msg": ""
}
Example Response When All Failed
{
"id": "1513",
"op": "batch-amend-orders",
"data": [{
"clOrdId": "",
"ordId": "12345689",
"reqId": "b12344",
"sCode": "5XXXX",
"sMsg": "order not exist"
}, {
"clOrdId": "oktswap7",
"ordId": "",
"reqId": "b12344",
"sCode": "5XXXX",
"sMsg": "order not exist"
}],
"code": "1",
"msg": ""
}
Example Response When Partially Successful
{
"id": "1513",
"op": "batch-amend-orders",
"data": [{
"clOrdId": "",
"ordId": "12345689",
"reqId": "b12344",
"sCode": "0",
"sMsg": ""
}, {
"clOrdId": "oktswap7",
"ordId": "",
"reqId": "b12344",
"sCode": "5XXXX",
"sMsg": "order not exist"
}],
"code": "2",
"msg": ""
}
Example Response When Format Error
{
"id": "1513",
"op": "batch-amend-orders",
"data": [],
"code": "60013",
"msg": "Invalid args"
}
Response Parameters
Parameter | Type | Description |
---|---|---|
id | String | Unique identifier of the message |
op | String | Operation |
code | String | Error Code |
msg | String | Error message |
data | Array | Data |
> ordId | String | Order ID |
> clOrdId | String | Client-supplied order ID |
> reqId | String | Client-supplied request ID If the user provides reqId in the request, the corresponding reqId will be returned |
> sCode | String | Order status code, 0 means success |
> sMsg | String | Order status message |
Error Code
Here is the REST API Error Code
REST
REST API Error Code is from 50000 to 59999.
Public
Error Code from 50000 to 53999
General Class
Error Message | HTTP Status Code | Error Code |
---|---|---|
Succeeded. | 200 | 0 |
Operation failed. | 200 | 1 |
Bulk operation partially succeeded. | 200 | 2 |
Body can not be empty. | 400 | 50000 |
Matching engine upgrading. Please try again later. | 503 | 50001 |
Json data format error. | 400 | 50002 |
Endpoint request timeout. | 400 | 50004 |
API is offline or unavailable. | 400 | 50005 |
Invalid Content_Type, please use "application/json" format. | 400 | 50006 |
Account blocked. | 200 | 50007 |
User does not exist. | 200 | 50008 |
Account is suspended due to ongoing liquidation. | 200 | 50009 |
User ID can not be empty. | 200 | 50010 |
Request too frequent. | 429 | 50011 |
Account status invalid. | 200 | 50012 |
System is busy, please try again later. | 429 | 50013 |
Parameter {0} can not be empty. | 400 | 50014 |
Either parameter {0} or {1} is required. | 400 | 50015 |
Parameter {0} does not match parameter {1}. | 400 | 50016 |
The position is frozen due to ADL. Operation restricted. | 200 | 50017 |
Currency {0} is frozen due to ADL. Operation restricted. | 200 | 50018 |
The account is frozen due to ADL. Operation restricted. | 200 | 50019 |
The position is frozen due to liquidation. Operation restricted. | 200 | 50020 |
Currency {0} is frozen due to liquidation. Operation restricted. | 200 | 50021 |
The account is frozen due to liquidation. Operation restricted. | 200 | 50022 |
Funding fee frozen. Operation restricted. | 200 | 50023 |
Parameter {0} and {1} can not exist at the same time. | 200 | 50024 |
Parameter {0} count exceeds the limit {1}. | 200 | 50025 |
API Class
Error Message | HTTP Status Code | Error Code |
---|---|---|
API frozen, please contact customer service. | 400 | 50100 |
Broker id of APIKey does not match current environment. | 401 | 50101 |
Timestamp request expired. | 401 | 50102 |
Request header "OK_ACCESS_KEY" can not be empty. | 401 | 50103 |
Request header "OK_ACCESS_PASSPHRASE" can not be empty. | 401 | 50104 |
Request header "OK_ACCESS_PASSPHRASE" incorrect. | 401 | 50105 |
Request header "OK_ACCESS_SIGN" can not be empty. | 401 | 50106 |
Request header "OK_ACCESS_TIMESTAMP" can not be empty. | 401 | 50107 |
Exchange ID does not exist. | 401 | 50108 |
Exchange domain does not exist. | 401 | 50109 |
Invalid IP. | 401 | 50110 |
Invalid OK_ACCESS_KEY. | 401 | 50111 |
Invalid OK_ACCESS_TIMESTAMP. | 401 | 50112 |
Invalid signature. | 401 | 50113 |
Invalid authorization. | 401 | 50114 |
Trade Class
Error Message | HTTP Status code | Error Code |
---|---|---|
Parameter {0} error. | 400 | 51000 |
Instrument ID does not exist. | 200 | 51001 |
Instrument ID does not match underlying index. | 200 | 51002 |
Either client order ID or order ID is required. | 200 | 51003 |
Order amount exceeds current tier limit. | 200 | 51004 |
Order amount exceeds the limit. | 200 | 51005 |
Order price out of the limit. | 200 | 51006 |
Order placement failed. Order amount should be at least 1 contract (showing up when placing an order with less than 1 contract). | 200 | 51007 |
Order placement failed due to insufficient balance. | 200 | 51008 |
Order placement function is blocked by the platform. | 200 | 51009 |
Account level too low. | 200 | 51010 |
Duplicated order ID. | 200 | 51011 |
Token does not exist. | 200 | 51012 |
Index does not exist. | 200 | 51014 |
Instrument ID does not match instrument type. | 200 | 51015 |
Duplicated client order ID. | 200 | 51016 |
Borrow amount exceeds the limit. | 200 | 51017 |
User with option account can not hold net short positions. | 200 | 51018 |
No net long positions can be held under isolated margin mode in options. | 200 | 51019 |
Order amount should be greater than the min available amount. | 200 | 51020 |
Contract to be listed. | 200 | 51021 |
Contract suspended. | 200 | 51022 |
Position does not exist. | 200 | 51023 |
Portfolio margin account blocked. | 200 | 51024 |
Order count exceeds the limit. | 200 | 51025 |
Instrument type does not match underlying index. | 200 | 51026 |
Contract expired. | 200 | 51027 |
Contract under delivery. | 200 | 51028 |
Contract is being settled. | 200 | 51029 |
Funding fee is being settled. | 200 | 51030 |
Trading amount does not meet the min tradable amount. | 200 | 51100 |
Entered amount exceeds the max pending order amount (Cont) per transaction. | 200 | 51101 |
Entered amount exceeds the max pending count. | 200 | 51102 |
Entered amount exceeds the max pending order count of the underlying asset. | 200 | 51103 |
Entered amount exceeds the max pending order amount (Cont) of the underlying asset. | 200 | 51104 |
Entered amount exceeds the max order amount (Cont) of the contract. | 200 | 51105 |
Entered amount exceeds the max order amount (Cont) of the underlying asset. | 200 | 51106 |
Entered amount exceeds the max holding amount (Cont). | 200 | 51107 |
Positions exceed the limit for closing out with the market price. | 200 | 51108 |
No available offer. | 200 | 51109 |
You can only place a limit order after Call Auction has started. | 200 | 51110 |
Maximum {0} orders can be placed in bulk. | 200 | 51111 |
Close order size exceeds your available size. | 200 | 51112 |
Market-price liquidation requests too frequent. | 429 | 51113 |
Cancel all pending close-orders before liquidation. | 200 | 51115 |
Order price or trigger price exceeds {0}. | 200 | 51116 |
Total amount should exceed the min amount per order. | 200 | 51118 |
Order placement failed due to insufficient balance. | 200 | 51119 |
Order quantity is less than {0}, please try again. | 200 | 51120 |
Order count should be the integer multiples of the lot size. | 200 | 51121 |
Order price should be higher than the min price {0}. | 200 | 51122 |
You can only place limit orders during call auction. | 200 | 51124 |
Currently there are reduce + reverse position pending orders in margin trading. Please cancel all reduce + reverse position pending orders and continue. | 200 | 51125 |
Currently there are reduce only pending orders in margin trading. | ||
Please cancel all reduce only pending orders and continue. | 200 | 51126 |
Available balance is 0. | 200 | 51127 |
Multi-currency margin account can not do cross-margin trading. | 200 | 51128 |
The value of the position and buy order has reached the position limit, and no further buying is allowed. | 200 | 51129 |
Fixed margin currency error. | 200 | 51130 |
Insufficient balance. | 200 | 51131 |
Your position amount is negative and less than the minimum trading amount. | 200 | 51132 |
Reduce-only feature is unavailable for the spot transactions by multi-currency margin account. | 200 | 51133 |
Closing failed. Please check your holdings and pending orders. | 200 | 51134 |
Your closing price has triggered the limit price, and the max buy price is {0}. | 200 | 51135 |
Your closing price has triggered the limit price, and the min sell price is {0}. | 200 | 51136 |
Your opening price has triggered the limit price, and the max buy price is {0}. | 200 | 51137 |
Your opening price has triggered the limit price, and the min sell price is {0}. | 200 | 51138 |
Reduce-only feature is unavailable for the spot transactions by simple account. | 200 | 51139 |
Value of per market order cannot exceed 100,000 USDT. | 200 | 51201 |
Market - order amount exceeds the max amount. | 200 | 51202 |
Order amount exceeds the limit {0}. | 200 | 51203 |
The price for the limit order can not be empty. | 200 | 51204 |
Reduce-Only is not available. | 200 | 51205 |
Algo order price is out of the available range. | 200 | 51250 |
Algo order type error (when user place an iceberg order). | 200 | 51251 |
Algo order price is out of the available range. | 200 | 51252 |
Average amount exceeds the limit of per iceberg order. | 200 | 51253 |
Iceberg average amount error (when user place an iceberg order). | 200 | 51254 |
Limit of per iceberg order: Total amount/1000 < x <= Total amount. | 200 | 51255 |
Iceberg order price variance error. | 200 | 51256 |
Trail order callback rate error. | 200 | 51257 |
Trail - order placement failed. The trigger price of a sell order should be higher than the last transaction price. | 200 | 51258 |
Trail - order placement failed. The trigger price of a buy order should be lower than the last transaction price. | 200 | 51259 |
Maximum {0} pending trail - orders can be held at the same time. | 200 | 51260 |
Each user can hold up to {0} pending stop - orders at the same time. | 200 | 51261 |
Maximum {0} pending iceberg orders can be held at the same time. | 200 | 51262 |
Maximum {0} pending time-weighted orders can be held at the same time. | 200 | 51263 |
Average amount exceeds the limit of per time-weighted order. | 200 | 51264 |
Time-weighted order limit error. | 200 | 51265 |
Time-weighted order strategy initiative rate error. | 200 | 51267 |
Time-weighted order strategy initiative range error. | 200 | 51268 |
Time-weighted order interval error, the interval should be {0}<= x<={1}. | 200 | 51269 |
The limit of time-weighted order price variance is 0 < x <= 1%. | 200 | 51270 |
Sweep ratio should be 0 < x <= 100%. | 200 | 51271 |
Price variance should be 0 < x <= 1%. | 200 | 51272 |
Total amount should be more than {0}. | 200 | 51273 |
Total quantity of time-weighted order must be larger than single order limit. | 200 | 51274 |
The amount of single stop-market order can not exceed the upper limit. | 200 | 51275 |
Stop - Market orders cannot specify a price. | 200 | 51276 |
TP trigger price can not be higher than the last price. | 200 | 51277 |
SL trigger price can not be lower than the last price. | 200 | 51278 |
TP trigger price can not be lower than the last price. | 200 | 51279 |
SL trigger price can not be higher than the last price. | 200 | 51280 |
Cancellation failed as the order does not exist. | 200 | 51400 |
Cancellation failed as the order is already canceled. | 200 | 51401 |
Cancellation failed as the order is already completed. | 200 | 51402 |
Cancellation failed as the order type does not support cancellation. | 200 | 51403 |
Order cancellation unavailable during the second phase of call auction. | 200 | 51404 |
Cancellation failed as you do not have any pending orders. | 200 | 51405 |
Canceled - order count exceeds the limit {0}. | 200 | 51406 |
Either order ID or client order ID is required. | 200 | 51407 |
Pair ID or name does not match the order info. | 200 | 51408 |
Either pair ID or pair name ID is required. | 200 | 51409 |
Cancellation failed as the order is already under cancelling status. | 200 | 51410 |
Either order price or amount is required. | 200 | 51500 |
Maximum {0} orders can be modified. | 200 | 51501 |
Order modification failed for insufficient margin. | 200 | 51502 |
Order modification failed as the order does not exist. | 200 | 51503 |
Order modification unavailable for the order type. | 200 | 51506 |
Orders are not allowed to be modified during the call auction. | 200 | 51508 |
Modification failed as the order has been canceled. | 200 | 51509 |
Modification failed as the order has been completed. | 200 | 51510 |
Modification failed as the order price did not meet the requirement for Post Only. | 200 | 51511 |
Status not found. | 200 | 51600 |
Order status and order ID cannot exist at the same time. | 200 | 51601 |
Either order status or order ID is required. | 200 | 51602 |
Order does not exist. | 200 | 51603 |
Data class
Error Message | HTTP Status Code | Error Code |
---|---|---|
No updates. | 200 | 52000 |
SPOT/MARGIN
Error Code from 54000 to 54999
Error Message | HTTP Status Code | Error Code |
---|---|---|
Margin transactions unavailable. | 200 | 54000 |
Only Multi-currency margin account can be set to borrow coins automatically. | 200 | 54001 |
FUTURES
No
SWAP
No
OPTION
No
FUNDING
Error Code from 58000 to 58999
Error Message | HTTP Status Code | Error Code |
---|---|---|
Account type {0} does not supported when getting the sub-account balance. | 200 | 58000 |
Incorrect trade password. | 200 | 58001 |
Please activate Savings Account first. | 200 | 58002 |
Currency type is not supported by Savings Account. | 200 | 58003 |
Account blocked (transfer & withdrawal endpoint: either end of the account does not authorize the transfer). | 200 | 58004 |
The redeemed amount must be no greater than {0}. | 200 | 58005 |
Service unavailable for token {0}. | 200 | 58006 |
Funds cannot be transferred in or out during option exercise or settlement. | 200 | 58100 |
Transfer suspended (transfer endpoint: either end of the account does not authorize the transfer). | 200 | 58101 |
Too frequent transfer (transfer too frequently). | 200 | 58102 |
Parent account user id does not match sub-account user id. | 200 | 58103 |
Since your P2P transaction is abnormal, you are restricted from making fund transfers. Please contact customer support to remove the restriction. | 200 | 58104 |
Since your P2P transaction is abnormal, you are restricted from making fund transfers. Please transfer funds on our website or app to complete identity verification. | 200 | 58105 |
Please enable the account for spot contract. | 200 | 58106 |
Please enable the account for futures contract. | 200 | 58107 |
Please enable the account for option contract. | 200 | 58108 |
Please enable the account for swap contract. | 200 | 58109 |
The contract triggers risk control, and the platform has suspended the fund transfer function of it. Please wait patiently. | 200 | 58110 |
Funds transfer unavailable as the perpetual contract is charging the funding fee. Please try again later. | 200 | 58111 |
Transfer amount must be more than 0. | 400 | 58114 |
Sub-account does not exist. | 200 | 58115 |
Transfer amount exceeds the limit. | 200 | 58116 |
Withdrawal from {0} to {1} is unavailable for this currency. | 200 | 58200 |
Withdrawal amount exceeds the daily limit. | 200 | 58201 |
The minimum withdrawal amount for NEO is 1, and the amount must be an integer. | 200 | 58202 |
Please add a withdrawal address. | 200 | 58203 |
Withdrawal suspended. | 200 | 58204 |
Withdrawal amount exceeds the upper limit. | 200 | 58205 |
Withdrawal amount is lower than the lower limit. | 200 | 58206 |
Withdrawal failed due to address error. | 200 | 58207 |
Withdrawal failed. Please link your email. | 200 | 58208 |
Withdrawal failed. Withdraw feature is not available for sub-accounts. | 200 | 58209 |
Withdrawal fee exceeds the upper limit. | 200 | 58210 |
Withdrawal fee is lower than the lower limit (withdrawal endpoint: incorrect fee). | 200 | 58211 |
Withdrawal fee should be {0}% of the withdrawal amount. | 200 | 58212 |
Please set trading password before withdrawal. | 200 | 58213 |
Deposit-address count exceeds the limit. | 200 | 58300 |
Insufficient balance. | 200 | 58350 |
Account
Error Code from 59000 to 59999
Error Message | HTTP Status Code | Error Code |
---|---|---|
Your settings failed as you have positions or open orders. | 200 | 59000 |
Switching unavailable as you have borrowings. | 200 | 59001 |
You have open positions. Please cancel all open positions before changing the leverage. | 200 | 59100 |
You have pending orders with isolated positions. Please cancel all the pending orders and adjust the leverage. | 200 | 59101 |
Leverage exceeds the maximum leverage. Please adjust the leverage. | 200 | 59102 |
Leverage is too low and no sufficient margin in your account. Please adjust the leverage. | 200 | 59103 |
The leverage is too high. The borrowed position has exceeded the maximum position of this leverage. Please adjust the leverage. | 200 | 59104 |
Leverage can not be less than {0}. Please adjust the leverage. | 400 | 59105 |
The max available margin corresponding to your order tier is {0}. Please adjust your margin and place a new order. | 200 | 59106 |
You have pending orders under the service, please modify the leverage after canceling all pending orders. | 200 | 59107 |
Low leverage and insufficient margin, please adjust the leverage. | 200 | 59108 |
Account equity less than the required margin amount after adjustment. Please adjust the leverage . | 200 | 59109 |
Insufficient account balance. | 200 | 59200 |
Negative account balance. | 200 | 59201 |
Margin call failed. Position does not exist. | 200 | 59300 |
Margin adjustment failed for exceeding the max limit. | 200 | 59301 |
Holdings already reached the limit. | 200 | 59401 |
WebSocket
Public
Error Code from 60000 to 63999
General Class
Error Message | Error Code |
---|---|
"OK_ACCESS_KEY" can not be empty. | 60001 |
"OK_ACCESS_SIGN" can not be empty. | 60002 |
"OK_ACCESS_PASSPHRASE" can not be empty. | 60003 |
Invalid OK_ACCESS_TIMESTAMP. | 60004 |
Invalid OK_ACCESS_KEY. | 60005 |
Timestamp request expired. | 60006 |
Invalid sign. | 60007 |
Login is not supported for public channels. | 60008 |
Login failed. | 60009 |
Already logged in. | 60010 |
Please log in. | 60011 |
Illegal request. | 60012 |
Invalid args. | 60013 |
Requests too frequent. | 60014 |
Connection closed as there was no data transmission in the last 30 seconds. | 60015 |
Buffer is full, cannot write data. | 60016 |
Invalid url path. | 60017 |
The {0} {1} {2} {3} {4} does not exist. | 60018 |
Invalid op {op} | 60019 |
Internal system error. | 63999 |
Log
Update log