NAV
English 中文
Java Python Go C++

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:

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:

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",
          "disEq": "134",
          "availBal": "",
          "frozenBal": "14",
          "ordFrozen": "12",
          "upl": "124",
          "uplLiab": "0",
          "mgnRatio": "",
          "interest": "12",
          "liab": "1"
        },
        {
          "ccy": "ETH",
          "eq": "223",
          "isoEq": "",
          "availEq": "2234",
          "disEq": "234",
          "availBal": "",
          "frozenBal": "141",
          "ordFrozen": "12",
          "upl": "124",
          "uplLiab": "0",
          "mgnRatio": "",
          "interest": "0",
          "liab": "0"
        }
      ]
    }
  ]
}
Response Parameters
Parameters Types Description
uTime String Update 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 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
> disEq String discount equity of the currency in USD level. It is expected to go online on March 5
> 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
> uplLib String Liabilities due to Unrealized loss of the currency
Applicable to 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 Single-currency margin Multi-currency margin
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
> disEq Yes Yes Yes
> availBal Yes
> frozenBal Yes Yes Yes
> ordFrozen Yes Yes Yes
> liab Yes
> upl Yes Yes
> uplLib 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 type
MARGIN
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 mode
cross
isolated
posId String Position ID
posSide String Position side
long
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
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 type
SPOT
MARGIN
SWAP
FUTURES
OPTION
ccy String No Currency
mgnMode String No Margin mode
isolated
cross
ctType String No Contract type
linear
inverse
Only applicable to FUTURES/SWAP
type String No Bill type
1: 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 subtype
1: 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 mode
isolated 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 account
1: SPOT 3: FUTURES 5: MARGIN 6: FUNDING 9: SWAP 12: OPTION 18: Portfolio Margin
When bill type is not transfer, the field returns "".
to String The beneficiary account
1: SPOT 3: FUTURES 5: MARGIN 6: FUNDING 9: SWAP 12: OPTION 18: Portfolio Margin
When 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 type
SPOT
MARGIN
SWAP
FUTURES
OPTION
ccy String No Currency
mgnMode String No Margin mode
isolated
cross
ctType String No Contract type
linear
inverse
Only applicable to FUTURES/SWAP
type String No Bill type
1: 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 subtype
1: 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 mode
isolated 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 account
1: SPOT 3: FUTURES 5: MARGIN 6: FUNDING 9: SWAP 12: OPTION 18: Portfolio Margin
When bill type is not transfer, the field returns "".
to String The beneficiary account
1: SPOT 3: FUTURES 5: MARGIN 6: FUNDING 9: SWAP 12: OPTION 18: Portfolio Margin
When 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 2: Single-currency margin 3: Multi-currency margin
posMode String Position mode
long_short_mode: long/short, only applicable to FUTURES/SWAP
net_mode: net
autoLoan Boolean Whether to borrow coins automatically
true: borrow coins automatically false: not borrow coins automatically
greeksType String Current display type of Greeks
PA: 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 mode
long_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 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 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 mode
isolated cross
Only can be cross if ccy is passed.
posSide String Optional Position side
long 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 mode
cross 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 mode
cross 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 buy
FUTURES/SWAP/OPTIONS: The maximum number of contracts that you can buy
maxSell String SPOT: The maximum number of coins that you can sell
FUTURES/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 mode
cross 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 Type
add 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 mode
cross 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 side
long
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 instrument

Rate Limit: 20 requests per 2 seconds

HTTP Request

GET /api/v5/account/max-loan

Request Example

Max loan of isolated `MARGIN` in `Single-currency margin`
GET  /api/v5/account/max-loan?instId=BTC-USDT&mgnMode=isolated

Max loan of cross `MARGIN` in `Single-currency margin` (Margin Currency is BTC)
GET  /api/v5/account/max-loan?instId=BTC-USDT&mgnMode=cross&mgnCcy=BTC

Max loan of cross `MARGIN` in `Multi-currency margin`
GET  /api/v5/account/max-loan?instId=BTC-USDT&mgnMode=cross

Request Parameters

Parameter Type Required Description
instId String Yes Instrument ID
mgnMode String Yes Margin mode
isolated cross
mgnCcy String Optional Margin currency
Only applicable to cross MARGIN in Single-currency margin

Example Response

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "instId": "BTC-USDT",
      "mgnMode": "isolated",
      "mgnCcy": "",
      "maxLoan": "0.1",
      "ccy": "BTC",
      "side": "sell"
    },
    {
      "instId": "BTC-USDT",
      "mgnMode": "isolated",
      "mgnCcy": "",
      "maxLoan": "0.2",
      "ccy": "USDT",
      "side": "buy"
    }
  ]
}

Response Parameters

Parameter Type Description
instId String Instrument ID
mgnMode String Margin mode
mgnCcy String Margin currency
Only applicable to cross MARGIN in Single-currency margin, if not return ""
maxLoan String Max loan
ccy String Currency
side String Order side
buy sell

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 type
SPOT
MARGIN
SWAP
FUTURES
OPTION
instId String Optional Instrument ID, e.g. BTC-USDT
only applicable toFUTURES/SWAP/OPTION
uly String Optional Underlying, e.g. BTC-USD
only applicable toFUTURES/SWAP/OPTION
category String Optional Fee Schedule
1: Tier 1
2: Tier 2
3: Tier 3
4: 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 mode
cross 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 coins
BS: 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 type
0: transfer within account
1: master account to sub-account
2: sub-account to master account
the default is 0
from String Yes The remitting account
1: SPOT 3: FUTURES 5: MARGIN 6: FUNDING 9: SWAP 12: OPTION 18: Portfolio Margin
to String Yes The beneficiary account
1: 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 address
3: OKEx
4: Digital currency address
68: Coinall
69: OKGAEX
71: OCNEX
75: Bbang
89: TOKR
90: AAAAEX
108: 99EX
113: EthEx.com
125: PICKCOIN
136: Fintechonex
141: iEx
142: Exipfs
147: VitBlock
152: xFutures
153: Float SV
158: LXG
161: BITAIEX
163: Boomex
172: 66ex
173: VVcoin
175: JIAMIX
178: 73ex
180: Newbit
185: UnicornX
186: GazuaX
187: ETF.Pro
188: EGEMoney
189: 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 shares
redempt: 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 type
1: Deposit
2: Withdrawal
13: Canceled withdrawal
18: Transfer to futures
19: Transfer from futures
20: Transfer to Sub account
21: Transfer from Sub account
28: Claim
33: Transfer to margin
34: Transfer from margin
37: Transfer to spot
38: Transfer from spot
41: Trading fees settled by loyalty points
42: Loyalty points purchase
47: System reversal
48: Received from activities
49: Given away to activities
50: Received from appointments
51: Deducted from appointments
52: Red packet sent
53: Red packet snatched
54: Red packet refunded
55: Transfer to perpetual
56: Transfer from perpetual
59: Transfer from hedging account
60: Transfer to hedging account
61: Conversion
63: Transfer to options
62: Transfer from options
68: Claim rebate card
69: Distribute rebate card
72: Token received
73: Token given away
74: Token refunded
75: Subscription to savings
76: Redemption to savings
77: Distribute
78: Lock up
79: Node voting
80: Staking
81: Vote redemption
82: Staking redemption
83: Staking yield
84: Violation fee
85: PoW mining yield
86: Cloud mining pay
87: Cloud mining yield
88: Subsidy
89: Staking
90: Staking subscription
91: staking redemption
92: Add collateral
93: Redeem collateral
94: Investment
95: Borrower borrows
96: Principal transferred in
97: Borrower transferred loan out
98: Borrower transferred interest out
99: Investor transferred interest in
102: Prepayment penalty transferred in
103: Prepayment penalty transferred out
104: Fee transferred in
105: Fee transferred out
106: Overdue fee transferred in
107: Overdue fee transferred out
108: Overdue interest transferred out
109: Overdue interest transferred in
110: Collateral for closed position transferred in
111: Collateral for closed position transferred out
112: Collateral for liquidation transferred in
113: Collateral for liquidation transferred out
114: Insurance fund transferred in
115: Insurance fund transferred out
116: Place an order
117: Fulfill an order
118: Cancel an order
119: Merchants unlock deposit
120: Merchants add deposit
121: FiatGateway Place an order
122: FiatGateway Cancel an order
123: FiatGateway Fulfill an order
124: Jumpstart unlocking
125: Manual deposit
126: Interest deposit
127: Investment fee transferred in
128: Investment fee transferred out
129: Rewards transferred in
130: Transferred from unified account
131: 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 type
SPOT
SWAP
FUTURES
OPTION
uly String No Underlying, e.g. BTC-USD
Only applicable toFUTURES/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 400, e.g. 400 bids + 400 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 side
buy
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 type
SPOT
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: put
Only 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 type
linear: linear contract
inverse: inverse contract
Only applicable to FUTURES/SWAP
alias String Alias
this_week
next_week
quarter
next_quarter
Only applicable to FUTURES
state String Instrument status
live
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 type
FUTURES
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 type
SWAP
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 type
SWAP
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 type
SWAP
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 type
OPTION
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 type
FUTURES
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 level 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",
      "discountLv": "1"
    }
  ]
}

Response Parameters

Parameter Type Description
ccy String Currency
amt String Interest-free quota
discountLv String Discount rate level
Discount rate level intruduction

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 type
MARGIN
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 type
MARGIN
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 type
MARGIN
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 not
true 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 fails
false true, the default is false.
ordId String Optional Order ID
Either ordId or clOrdIdis 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 mode
cross 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 type
SPOT
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 type
market: market order
limit: limit order
post_only: Post-only order
fok: Fill-or-kill order
ioc: 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 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 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 type
SPOT
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 State
live
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 type
market: market order
limit: limit order
post_only: Post-only order
fok: Fill-or-kill order
ioc: 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 State
live
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 type
SPOT
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 State
canceled
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 type
market: market order
limit: limit order
post_only: Post-only order
fok: Fill-or-kill order
ioc: 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 type
SPOT
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 State
canceled
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 type
market: market order
limit: limit order
post_only: Post-only order
fok: Fill-or-kill order
ioc: 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 type
SPOT
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 side
long 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 order
trigger: 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 type
SPOT
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 order
trigger: 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 order
trigger: 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 State
effective
canceled
order_failed
Either state or algoId is requied
algoId String Optional Algo ID
Either state or algoId is required.
instType String No Instrument type
SPOT
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 order
trigger: 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 order
trigger: 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

SubAccount

The API endpoints of SubAccount require authentication.

Query detailed balance info of Trading Account of a sub-account via the master account (applies to master accounts only)

Rate limit：2 requests per 2 seconds

HTTP request

GET /api/v5/account/subaccount/balances

Request sample

GET /api/v5/account/subaccount/balances ?subAcct=test1

Request parameters

Parameter name Type If required Description
subAcct String Yes Sub-account name

Returned result

{
  "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",
          "disEq": "134",
          "availBal": "",
          "frozenBal": "14",
          "ordFrozen": "12",
          "upl": "124",
          "uplLiab": "0",
          "mgnRatio": "",
          "interest": "12",
          "liab": "1"
        },
        {
          "ccy": "ETH",
          "eq": "223",
          "isoEq": "",
          "availEq": "2234",
          "disEq": "234",
          "availBal": "",
          "frozenBal": "141",
          "ordFrozen": "12",
          "upl": "124",
          "uplLiab": "0",
          "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
> disEq String discount equity of the currency in USD level
> 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
> uplLib String Liabilities due to Unrealized loss of the currency
Applicable to 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

View sub-account list(applies to master accounts only)

Rate limit：6 requests per second

HTTP request

GET /api/v5/asset/subaccount/bills

Request sample

GET /api/v5/asset/subaccount/bills

Request parameters

Parameter name Type If required Description
ccy String No Currency, such as BTC
type String No 0: Transfers from master account to sub-account ；1 : Transfers from sub-account to master account.
subAcct String No Sub-account name
after String No If you query the data prior to the requested bill ID, the value will be a Unix timestamp in millisecond format.
before String No If you query the data after the requested bill ID, the value will be a Unix timestamp in millisecond format.
limit String No Number of results per request. The maximum is 100. The default is 100.

Returned results

{
    "code": "0",
    "msg": "",
    "data": [{
                "billId": "12344",
                "type":"1",
        "ccy": "BTC",
                "amt":"2",
                "subAcct":"test-1",
                "ts":"1597026383085"
    }]
}

Response parameters

Parameter name Type Description
billId String Bill ID
ccy String Account balance currency
amt String Transfer amount
type String Bill type
subAcct String Sub-account name
ts String Sub-account creation time with Unix timestamp in millisecond format,1597026383085 e.g., 1597026383085

Delete the APIkey of sub-accounts (applies to master accounts only)

Rate limit：1 request per second

HTTP request

POST /api/v5/users/subaccount/delete-apikey

Request sample

POST /api/v5/users/subaccount/delete-apikey

Request parameters

Parameter name Type If required Description
pwd String Yes Funds password of the master account
subAcct String Yes Sub-account name
apiKey String Yes APIkey note

Returned results

{
    "code": "0",
    "msg": "",
    "data": [{
        "subAcct": "test-1"
    }]
}

Response parameters

Parameter name Type Description
subAcct String Sub-account name

Reset the APIkey of a sub-account(applies to master accounts only)

Rate limit：1 request per second

HTTP request

POST /api/v5/users/subaccount/modify-apikey

Request sample

POST /api/v5/users/subaccount/modify-apikey

Request parameters

Parameter name Type If required Description
pwd String Yes Funds password of the master account
subAcct String Yes Sub-account name
label String Yes APIkey note
apiKey String Yes APIkey note
perm String Yes APIkey access read_only：Read only ；trade ：Trade
ip String No Link IP addresses, separate with commas if more than one. Support up to 5 IP addresses.

Returned results

{
    "code": "0",
    "msg": "",
    "data": [{
        "subAcct": "test-1",
        "subUid": "99999",
        "label": "v5",
        "apiKey": "arg13sdfgs",
        "perm": "read,trade",
        "ip": "1.1.1.1,2.2.2.2",
        "ts": "1597026383085"
    }]
}

Response parameters

Parameter name Type Description
subAcct String Sub-account name
label String APIkey note
apiKey String API public key
perm String APIkey access read_only：Read only ；trade ：Trade
ip String IP address that linked with APIkey
ts String Creation time

Create an APIkey for a sub-account(applies to master accounts only)

Rate limit：1 request per second

HTTP request

POST /api/v5/users/subaccount/apikey

Request sample

POST /api/v5/users/subaccount/apikey

Request parameters

Parameter name Type If required Description
pwd String Yes Funding password of the master account
subAcct String Yes Sub-account name
label String Yes APIkey note
Passphrase String Yes APIkey password， supports 6 to 32 characters that include numbers and letters (case sensitive, space symbol is not supported).
perm String No APIkey access read_only：Read only ；trade ：Trade
ip String No Link IP addresses, separate with commas if more than one. Support up to 5 addresses.

Returned result

{
    "code": "0",
    "msg": "",
    "data": [{
        "subAcct": "test-1",
        "label": "v5",
        "apiKey": "arg13sdfgs",
        "secretKey": "arg13sdfgs",
        "passphrase": "123678",
        "perm": "read_only,trade",
        "ip": "1.1.1.1,2.2.2.2",
        "ts": "1597026383085"
    }]
}

Response parameters

Parameter name Type Description
subAcct String Sub-account name
label String APIkey note
apiKey String API public key
secretKey String API private key
Passphrase String APIkey password
perm String APIkey access read_only：Read only ；trade ：Trade
ip String IP address that linked with APIkey
ts String Creation time

View sub-account list(applies to master accounts only)

Rate limit：2 requests per 2 seconds

HTTP request

GET /api/v5/users/subaccount/list

Request sample

GET /api/v5/users/subaccount/list

Request parameters

Parameter name Type If required Description
enable String No Sub-account status，true: Normal ; false: Frozen
subAcct String No Sub-account name
after String No If you query the data prior to the requested creation time ID, the value will be a Unix timestamp in millisecond format.
before String No If you query the data after the requested creation time ID, the value will be a Unix timestamp in millisecond format.
limit String No Number of results per request. The maximum is 100. The default is 100.

Returned results

{
    "code":"0",
    "msg":"",
    "data":[
                   {
                      "enable":true,
                      "subAcct":"test-1",
                      "label":"trade futures",
                      "mobile":"1818181",
                      "gAuth":true,
                      "ts":"1597026383085"
                   },
                   {
                      "enable":false,
                      "subAcct":"test-2",
                      "label":"trade spot",
                      "mobile":"1818199",
                      "gAuth":true,
                      "ts":"1597026383082"
                   }

    ]
}

Response parameters

Parameter name Type Description
enable String Sub-account status true: Normal ; false:Frozen
subAcct String Sub-account name
label String Sub-account note
mobile String Mobile number that linked with the sub-account.
gAuth String If the sub-account switches on the Google Authenticator for login authentication. true: On ; false: Off
ts String Sub-account creation time with Unix timestamp in millisecond format. e.g., 1597026383085

Master accounts manage the transfers between sub-accounts(applies to master accounts only)

Rate limit：1 request per second

HTTP request

POST /api/v5/asset/subaccount/transfer

Request sample

POST /api/v5/asset/subaccount/transfer
{"ccy":"USDT","amt":"1.5","from":"0","to":"0","fromSubAccount":"test-1","toSubAccount":"test-2"}

Request parameters

Parameter name Type If required Description
ccy String Yes Currency
amt String Yes Transfer amount
form String Yes 6：Funding Account 18:Unified Account
to String Yes 6：Funding Account 18:Unified Account
fromSubAccount String Yes Sub-account name of the account that transfers funds out.
toSubAccount String Yes Sub-account name of the account that transfers funds in.

Returned results

{
    "code":"0",
    "msg":"",
    "data":[
                   {
                      "transId":12345,
                   }

    ]
}

Response parameters

Parameter name Type Description
transId String Transfer ID

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:

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 type
SPOT
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 type
SPOT
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 type
SPOT
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 type
SPOT
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.

  1. 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.

  2. 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 type
SPOT
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 type
SPOT
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: Put
Only 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 Alias
this_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 name
candle1Y
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 type
FUTURES
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 name
mark-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 name
index-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",
          "disEq": "234",
          "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",
          "disEq": "234",
          "availBal": "1415",
          "frozenBal": "14",
          "ordFrozen": "12",
          "upl": "124",
          "mgnRatio": "124",
          "interest": "12",
          "liab": "1"
        },
        {
          "ccy": "ETH",
          "eq": "223",
          "availEq": "2234",
          "disEq": "234",
          "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 Update 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 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 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 and Multi-currency margin
>> availEq String Available equity of the currency
Applicable to Single-currency margin and Multi-currency margin
>> disEq String discount equity of the currency in USD level. It is expected to go online on March 5
>> 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 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 type
MARGIN
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 type
OPTION
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 side
long
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
> 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.

Balance and Position Channel

Retrieve account balance and position information. Data will be pushed when triggered by events such as filled order, funding transfer. It is expected to go online on March 5.

Request Example 

{
    "op": "subscribe",
    "args": [{
        "channel": "balance_and_position"
    }]
}

Request parameters

Parameter Type Required Description
op String Yes Operation, subscribe unsubscribe
args Array Yes List of subscribed channels
> channel String Yes Channel name，balance_and_position

Response Example 

{
    "event": "subscribe",
    "arg": {
        "channel": "balance_and_position"
    }
}

Failure Response Example

{
    "event": "error",
    "code": "60012",
    "msg": "Unrecognized request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"balance_and_position\"}]}"
}

Response parameters

Parameter Type Required Description
event String Yes Operation，subscribe unsubscribe error
arg Object No List of subscribed channels
> channel String Yes Channel name，balance_and_position
code String No Error code
msg String No Error message

Push Data Example

{
    "arg": {
        "channel": "balance_and_position"
    },
    "data": [{
        "pTime": "1597026383085",
        "eventType": "snapshot",
        "balData": [{
            "ccy": "BTC",
            "cashBal": "1",
            "uTime": "1597026383085"
        }],
        "posData": [{
            "posId": "1111111111",
            "tradeId": "2",
            "instId": "BTC-USD-191018",
            "instType": "FUTURES",
            "mgnMode": "cross",
            "posSide": "long",
            "pos": "10",
            "ccy": "BTC",
            "posCcy": "",
            "avgPx": "3320",
            "uTIme": "1597026383085"
        }]
    }]
}

Push data parameters

Parameter Type Description
arg Object Channel to subscribe to
> channel String Channel name
data Array Subscribed data
> pTime String Push time of both balance and position information, millisecond format of Unix timestamp, e.g. 1597026383085
> eventType String Event Type, snapshot、delivered 、exercised、transferred、filled, partial_liquidation, full_liquidation, adl, funding_fee,adjust_margin, set_leverage
> balData String Balance data
>> ccy String Currency
>> cashBal String Cash Balance
>> uTime String Update time, Unix timestamp format in milliseconds, e.g. 1597026383085
> posData String Position data
>> posId String Position ID
>> tradeId String Last trade ID
>> instId String Instrument ID, e.g BTC-USD-180213
>> instType String Instrument type
>> mgnMode String Margin mode, isolated, cross
>> avgPx String Average open price
>> ccy String Currency used for margin
>> posSide String Position side：long, short, net
>> pos String Quantity of positions
>> posCcy String Position currency, only applicable to MARGIN positions.
>> uTime String Update time, 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 type
SPOT
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 type
SPOT
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.
> 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 type
market: market order
limit: limit order
post_only: Post-only order
fok: Fill-or-kill order
ioc: 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 currency
SPOT/MARGIN: If you buy, you will receive BTC; if you sell, you will receive USDT
FUTURES/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 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
> 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: failure
0: success
1: 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 type
SPOT
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 type
SPOT
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.
> 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 type
conditional: One-way stop order
oco: One-cancels-the-other order
trigger: Trigger 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
> lever String Leverage, from 0.01 to 125.
Only applicable to MARGIN/FUTURES/SWAP
> state String Order status
live: to be effective
effective: effective
canceled: canceled
order_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.
> 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 mode
It 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.
> 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 mode
It 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
System error. 500 50026
The account is restricted from trading. 200 50027

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
Account assets are abnormal, please deal with negative assets before transferring. 200 58117
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
Only the APIKey of the main account has permission. 200 59500
Only 50 APIKeys can be created per account. 200 59501
Note name cannot be duplicate with the currently created APIKey note name. 200 59502
Each APIKey can bind up to 5 IP addresses. 200 59503
The sub account does not support the withdrawal function. 200 59504
The passphrase format is incorrect. 200 59505
APIKey does not exist. 200 59506
The two accounts involved in a transfer must be two different sub accounts under the same parent account. 200 59507
The sub account of {0} is suspended. 200 59508

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

2021-02-05

1.Due to the conversion rate calculation changes, the interface（/api/v5/public/discount-rate-interest-free-quota）used to acquire the interest-free limit and conversion rates will return parameters of discount level（discountLv）instead of discount rate（discount). For more info, please refer to Discount level introduction.

response before: { "code":"0", "msg":"", "data":[ { "ccy":"BTC", "amt" :"2" , "discount" :"0.8" } ] } response after: { "code":"0", "msg":"", "data":[ { "ccy":"BTC", "amt" :"2" , "discountLv" :"1" } ] }

2.The interface Get Balance(/api/v5/account/balance) add a new response parameter：uplLiab(Liabilities due to Unrealized loss of the currency).

2021-02-26

1.The interface Get Balance(/api/v5/account/balance) add a new response parameter: disEq (discount equity of the currency in USD level). Expected launch: March 5

2021-03-02

1.Newly added push channel : balance and position channel. Expected launch: March 5

Java Python Go C++