Overview

Welcome to our V5 API documentation. We offer complete REST and WebSocket APIs to suit your trading needs.
The V5 API is only applicable to the Unified account.

Demo Trading Services

At present, the V5 API works for Demo Trading and users can request all APIs except the Funding withdrawal, transfer and purchase/redemption.

The Demo Trading URL:

REST: https://www.okex.com

Public WebSocket: wss://ws.okex.com:8443/ws/v5/public?brokerId=9999

Private WebSocket: wss://ws.okex.com:8443/ws/v5/private?brokerId=9999

OKEx account can be used for login on Dmo Trading. If you already have an OKEx account, you can log in directly.

Start API Demo Trading by the following steps:

Login OKEx —> Assets —> Start Demo Trading —> Personal Center —> Demo Trading API -> Create Demo Trading V5 APIKey —> Start your Demo Trading

Note: x-simulated-trading: 1 needs to be added to the header of the Demo Trading request.

Example：

Content-Type: application/json

OK-ACCESS-KEY: 37c541a1-*--***-10fe7a038418

OK-ACCESS-SIGN: leaVRETrtaoEQ3yI9qEtI1CZ82ikZ4xSG5Kj8gnl3uw=

OK-ACCESS-PASSPHRASE: 1****6

OK-ACCESS-TIMESTAMP: 2020-03-28T12:21:41.274Z

x-simulated-trading: 1

REST API

Authentication

Generating an APIKey

Create an APIKey on the OKEx website before signing any requests. After creating an APIKey, keep the following information safe:

APIKey
SecretKey
Passphrase

We will provide randomly-generated APIKeys and SecretKeys. You will provide the Passphrase to further secure your API access. We store the salted hash of your Passphrase for authentication, but we cannot recover the Passphrase if you lose it.

Making Requests

All private REST requests must contain the following headers:

OK-ACCESS-KEY The APIKey as a String.

OK-ACCESS-SIGN The Base64-encoded signature (see Signing Messages subsection for details).

OK-ACCESS-TIMESTAMP The timestamp of your request.e.g : 2020-12-08T09:08:57.715Z

OK-ACCESS-PASSPHRASE The passphrase you specified when creating the APIKey.

Request bodies should have content type application/json and be in valid JSON format.

Signature

Signing Messages

The OK-ACCESS-SIGN header is generated as follows:

Create a prehash string of timestamp + method + requestPath + body (where + represents String concatenation).
Prepare the SecretKey.
Sign the prehash string with the SecretKey using the HMAC SHA256.
Encode the signature in the Base64 format.

Example: sign=CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA256(timestamp + 'GET' + '/users/self/verify', SecretKey))

The timestamp value is the same as the OK-ACCESS-TIMESTAMP header with millisecond format of ISO, e.g. 2020-12-08T09:08:57.715Z.

The request method should be in UPPERCASE: e.g. GET and POST.

The requestPath is the path of requesting an endpoint.

Example: /api/v5/account/balance

The body refers to the String of the request body. It can be omitted if there is no request body (frequently the case for GET requests).

Example: {"instId":"BTC-USDT","lever":"5","mgnMode":"isolated"}

The SecretKey is generated when you create an APIKey.

Example: 22582BD0CFF14C41EDBF1AB98506286D

Account

The API endpoints of Account require authentication.

Get Balance

Retrieve a list of assets (with non-zero balance), remaining balance, and available amount in the account.

Rate Limit: 20 requests per 2 seconds

HTTP Requests

GET /api/v5/account/balance

Request Example

Get the balance of all assets in the account
GET /api/v5/account/balance

Get the balance of BTC and ETH assets in the account
GET /api/v5/account/balance?ccy=BTC,ETH

Request Parameters

Parameters	Types	Required	Description
ccy	String	No	Single currency or multiple currencies (no more than 20) separated with comma, e.g. `BTC` or `BTC,ETH`.

Example Response

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "uTime": "1597026383085",
      "totalEq": "41624.32",
      "isoEq": "3624.32",
      "adjEq": "41624.32",
      "imr": "4162.33",
      "mmr": "4",
      "mgnRatio": "41624.32",
      "details": [
        {
          "ccy": "BTC",
          "eq": "123",
          "isoEq": "",
          "availEq": "1234",
          "availBal": "",
          "frozenBal": "14",
          "ordFrozen": "12",
          "upl": "124",
          "mgnRatio": "",
          "interest": "12",
          "liab": "1"
        },
        {
          "ccy": "ETH",
          "eq": "223",
          "isoEq": "",
          "availEq": "2234",
          "availBal": "",
          "frozenBal": "141",
          "ordFrozen": "12",
          "upl": "124",
          "mgnRatio": "",
          "interest": "0",
          "liab": "0"
        }
      ]
    }
  ]
}

Response Parameters

Parameters	Types	Description
uTime	String	The latest time to get account information, millisecond format of Unix timestamp, e.g. `1597026383085`
totalEq	String	Total equity in USD level
isoEq	String	Isolated margin equity in USD level Applicable to `Single-currency margin` and `Multi-currency margin`
adjEq	String	Adjusted/Effective equity in USD level Applicable to `Multi-currency margin`
imr	String	Initial margin requirement in USD level Applicable to `Multi-currency margin`
mmr	String	Maintenance margin requirement in USD level Applicable to `Multi-currency margin`
mgnRatio	String	Margin ratio in USD level Applicable to `Multi-currency margin`
details	Array	Detailed asset information in all currencies
> ccy	String	Currency
> eq	String	Equity of the currency
> isoEq	String	Isolated margin equity of the currency Applicable to `Single-currency margin` and `Multi-currency margin`
> availEq	String	Available equity of the currency Applicable to `Single-currency margin` and `Multi-currency margin`
> availBal	String	Available balance of the currency Applicable to `Simple`
> frozenBal	String	Frozen balance of the currency
> ordFrozen	String	Margin frozen for open orders
> liab	String	Liabilities of the currency Applicable to `Multi-currency margin`
> upl	String	Unrealized profit and loss of the currency Applicable to `Single-currency margin` and `Multi-currency margin`
> mgnRatio	String	Margin ratio of the currency Applicable to `Single-currency margin`
> interest	String	Interest of the currency Applicable to `Multi-currency margin`

Distribution of applicable fields under each account level are as follows:

Parameters	Simple account	Single-currency margin account	Multi-currency margin account
uTime	Yes	Yes	Yes
totalEq	Yes	Yes	Yes
isoEq		Yes	Yes
adjEq			Yes
imr			Yes
mmr			Yes
mgnRatio			Yes
details
> ccy	Yes	Yes	Yes
> eq	Yes	Yes	Yes
> isoEq		Yes	Yes
> availEq		Yes	Yes
> availBal	Yes
> frozenBal	Yes	Yes	Yes
> ordFrozen	Yes	Yes	Yes
> liab			Yes
> upl		Yes	Yes
> mgnRatio		Yes
> interest			Yes

Get Positions

Retrieve information on your positions. When the account is in net mode, net positions will be displayed, and when the account is in long/short mode, long or short positions will be displayed.

Rate Limit: 20 requests per 2 seconds

HTTP Request

GET /api/v5/account/positions

Request Example

Query BTC-USDT position information
GET /api/v5/account/positions?instId=BTC-USDT

Request Parameters

Parameter	Type	Required	Description
instType	String	No	Instrument 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, only applicable to `isolated`.
mmr	String	Maintenance margin requirement
liab	String	Liabilities, only applicable to `MARGIN`.
liabCcy	String	Liabilities currency, only applicable to `MARGIN`.
interest	String	Interest. Interest that has been incurred.
tradeId	String	Last trade ID
optVal	String	Option Value, only applicable to `OPTION`.
adl	String	Auto-deleveraging (ADL) indicator Divided into 5 levels, from 1 to 5, the smaller the number, the weaker the adl intensity.
ccy	String	Currency used for margin
last	String	Latest traded price
cTime	String	Creation time, Unix timestamp format in milliseconds, e.g. `1597026383085`
uTime	String	Latest time position was adjusted, Unix timestamp format in milliseconds, e.g. `1597026383085`

Get Bills Details (last 7 days)

Retrieve the bills of the account. The bill refers to all transaction records that result in changing the balance of an account. Pagination is supported, and the response is sorted with the most recent first. This endpoint can retrieve data from the last 7 days.

Rate Limit: 6 requests per second

HTTP Request

GET /api/v5/account/bills

Request Example

GET /api/v5/account/bills

GET /api/v5/account/bills?instType=MARGIN

Request Parameters

Parameter	Type	Required	Description
instType	String	No	Instrument 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 account `2`: Single-currency margin account `3`: Multi-currency margin account
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 account at pairs level
POST /api/v5/account/set-leverage
body {"instId":"BTC-USDT","lever":"5","mgnMode":"cross"}

set leverage for cross `MARGIN` in Multi-currency margin account at currency level
POST /api/v5/account/set-leverage
body {"ccy":"BTC","lever":"5","mgnMode":"cross"}

set leverage on long BTC-USDT-200802 for isolated `FUTURES`
POST /api/v5/account/set-leverage
body {"instId":"BTC-USDT-200802","lever":"5","posSide":"long","mgnMode":"isolated"}

set leverage for cross `FUTURES/SWAP` at underlying level
POST /api/v5/account/set-leverage
body {"instId":"BTC-USDT-200802","lever":"5","mgnMode":"cross"}

Request Parameters

Parameter	Type	Required	Description
instId	String	Optional	Instrument ID Either `instId` or `ccy` is required; if both are passed, `instId` will be used by default.
ccy	String	Optional	Currency used for margin Only applicable to `cross` `MARGIN` of `Multi-currency margin`
lever	String	Yes	Leverage
mgnMode	String	Yes	Margin 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 isolated MARGIN

Rate Limit: 20 requests per 2 seconds

HTTP Request

GET /api/v5/account/max-loan

Request Example

GET /api/v5/account/max-loan?instId=BTC-USDT

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Instrument ID Only applicable to `MARGIN`

Example Response

{
    "code": "0",
    "msg": "",
    "data": [{
            "instId": "BTC-USDT",
            "maxLoan": "0.1",
            "ccy": "BTC"
        },
        {
            "instId": "BTC-USDT",
            "maxLoan": "0.2",
            "ccy": "USDT"
        }
    ]
}

Response Parameters

Parameter	Type	Description
instId	String	Instrument ID
maxLoan	String	Max loan
ccy	String	Currency

Get Fee Rates

Rate Limit: 5 requests per 2 seconds

HTTP Request

GET /api/v5/account/trade-fee

Request Example

Query trade fee rate of SPOT BTC-USDT
GET /api/v5/account/trade-fee?instType=SPOT&instId=BTC-USDT

Query trade fee rate in Tier 1
GET /api/v5/account/trade-fee?instType=SWAP&category=1

Request Parameters

Parameter	Type	Required	Description
instType	String	Yes	Instrument type `SPOT` `MARGIN` `SWAP` `FUTURES` `OPTION`
instId	String	Optional	Instrument ID, e.g. `BTC-USDT` only applicable to`FUTURES/SWAP/OPTION`
uly	String	Optional	Underlying, e.g. `BTC-USD` only applicable to`FUTURES/SWAP/OPTION`
category	String	Optional	Fee 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`: between accounts in the master 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 `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 to`FUTURES/SWAP/OPTION`

Example Response

{
    "code":"0",
    "msg":"",
    "data":[
     {
        "instType":"SWAP",
        "instId":"LTC-USD-SWAP",
        "last":"9999.99",
        "lastSz":"0.1",
        "askPx":"9999.99",
        "askSz":"11",
        "bidPx":"8888.88",
        "bidSz":"5",
        "open24h":"9000",
        "high24h":"10000",
        "low24h":"8888.88",
        "volCcy24h":"2222",
        "vol24h":"2222",
        "sodUtc0":"2222",
        "sodUtc8":"2222",
        "ts":"1597026383085"
     },
     {
        "instType":"SWAP",
        "instId":"BTC-USD-SWAP",
        "last":"9999.99",
        "lastSz":"0.1",
        "askPx":"9999.99",
        "askSz":"11",
        "bidPx":"8888.88",
        "bidSz":"5",
        "open24h":"9000",
        "high24h":"10000",
        "low24h":"8888.88",
        "volCcy24h":"2222",
        "vol24h":"2222",
        "sodUtc0":"2222",
        "sodUtc8":"2222",
        "ts":"1597026383085"
    }
  ]
}

Response Parameters

Parameter	Type	Description
instType	String	Instrument type
instId	String	Instrument ID
last	String	Last traded price
lastSz	String	Last traded size
askPx	String	Best ask price
askSz	String	Best ask size
bidPx	String	Best bid price
bidSz	String	Best bid size
open24h	String	Open price in the past 24 hours
high24h	String	Highest price in the past 24 hours
low24h	String	Lowest price in the past 24 hours
volCcy24h	String	Trading volume in the past 24 hours
vol24h	String	Trading volume in the past 24 hours
sodUtc0	String	Open price in the UTC 0
sodUtc8	String	Open price in the UTC 8
ts	String	Ticker data generation time, Unix timestamp format in milliseconds, e.g. `1597026383085`

Get Ticker

Retrieve the latest price snapshot, best bid/ask price, and trading volume in the last 24 hours.

Rate Limit: 20 requests per 2 seconds

HTTP Request

GET /api/v5/market/ticker

Request Example

GET /api/v5/market/ticker?instId=BTC-USD-SWAP

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Instrument ID, e.g. `BTC-USD-SWAP`

Example Response

{
    "code":"0",
    "msg":"",
    "data":[
     {
        "instType":"SWAP",
        "instId":"BTC-USD-SWAP",
        "last":"9999.99",
        "lastSz":"0.1",
        "askPx":"9999.99",
        "askSz":"11",
        "bidPx":"8888.88",
        "bidSz":"5",
        "open24h":"9000",
        "high24h":"10000",
        "low24h":"8888.88",
        "volCcy24h":"2222",
        "vol24h":"2222",
        "sodUtc0":"2222",
        "sodUtc8":"2222",
        "ts":"1597026383085"
    }
  ]
}

Response Parameters

Parameter	Type	Description
instType	String	Instrument type
instId	String	Instrument ID
last	String	Last traded price
lastSz	String	Last traded size
askPx	String	Best ask price
askSz	String	Best ask size
bidPx	String	Best bid price
bidSz	String	Best bid size
open24h	String	Open price in the past 24 hours
high24h	String	Highest price in the past 24 hours
low24h	String	Lowest price in the past 24 hours
volCcy24h	String	Trading volume in the past 24 hours
vol24h	String	Trading volume in the past 24 hours
sodUtc0	String	Open price in the UTC 0
sodUtc8	String	Open price in the UTC 8
ts	String	Ticker data generation time, Unix timestamp format in milliseconds, e.g. `1597026383085`.

Get Index Tickers

Retrieve index tickers.

Rate Limit: 20 requests per 2 seconds

HTTP Request

GET /api/v5/market/index-tickers

Request Example

GET /api/v5/market/index-tickers?quoteCcy=BTC

Request Parameters

Parameter	Type	Required	Description
quoteCcy	String	Optional	Quote currency Currently there is only an index with `USD/USDT/BTC` as the quote currency.
instId	String	Optional	Index, e.g. `BTC-USD` Either `quoteCcy` or `instId` is required.

Example Response

{
    "code":"0",
    "msg":"",
    "data":[
    {
        "instId":"BTC-USDT",
        "idxPx":"0.1",
        "high24h":"0.5",
        "low24h":"0.1",
        "open24h":"0.1",
        "sodUtc0":"2222",
        "sodUtc8":"2222",
        "ts":"1597026383085"
    }
  ]
}

Response Parameters

Parameter	Type	Description
instId	String	Index
idxPx	String	Latest index price
high24h	String	Highest price in the past 24 hours
low24h	String	Lowest price in the past 24 hours
open24h	String	Open price in the past 24 hours
sodUtc0	String	Open price in the UTC 0
sodUtc8	String	Open price in the UTC 8
ts	String	Update time, Unix timestamp format in milliseconds, e.g. `1597026383085`

Get Order Book

Retrieve a instrument's order book.

Rate Limit: 20 requests per 2 seconds

HTTP Request

GET /api/v5/market/books

Request Example

GET /api/v5/market/books?instId=BTC-USD-SWAP

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Instrument ID, e.g. `BTC-USD-190927-5000-C`
sz	String	No	Order book depth per side. Maximum 200, e.g. 200 bids + 200 asks Default returns to `1` depth data

Example Response

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "asks":[
                [
                    "411.8","10","0","8" 
                ],
                [
                    "1","2","3","6"
                ]
            ],
            "bids":[
                [
                    "1","2","3","6"
                ],
                [
                    "1","2","3","6"
                ]
            ],
            "ts":"1597026383085"
        }
    ]
}

Response Parameters

Parameter	Type	Description
asks	Array	Order book on sell side
bids	Array	Order book on buy side
ts	String	Order book generation time

Get Candlesticks

Retrieve the candlestick charts. This endpoint can retrieve the latest 1,440 data entries. Charts are returned in groups based on the requested bar.

Rate Limit: 20 requests per 2 seconds

HTTP Request

GET /api/v5/market/candles

Request Example

GET /api/v5/market/candles?instId=BTC-USD-190927-5000-C

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Instrument ID, e.g. `BTC-USD-190927-5000-C`
after	String	No	Pagination of data to return records earlier than the requested `ts`
before	String	No	Pagination of data to return records newer than the requested `ts`
bar	String	No	Bar size, the default is `1m` e.g. [1m/3m/5m/15m/30m/1H/2H/4H/6H/12H/1D/1W/1M/3M/6M/1Y]
limit	String	No	Number of results per request. The maximum is `100`; The default is `100`.

Example Response

{
    "code":"0",
    "msg":"",
    "data":[
     [
        "1597026383085",
        "3.721",
        "3.743",
        "3.677",
        "3.708",
        "8422410",
        "22698348.04828491"
    ],
    [
        "1597026383085",
        "3.731",
        "3.799",
        "3.494",
        "3.72",
        "24912403",
        "67632347.24399722"
    ]
    ]
}

Response Parameters

Parameter	Type	Description
ts	String	Data generation time, Unix timestamp format in milliseconds, e.g. `1597026383085`
o	String	Open price
h	String	Higest price
l	String	Lowest price
c	String	Close price
vol	String	Trading volume (cont)
volCcy	String	Trading volume (coin)

Get Candlesticks History（top currencies only）

Retrieve history candlestick charts from recent years.

Rate Limit: 20 requests per 2 seconds

HTTP Request

GET /api/v5/market/history-candles

Request Example

GET /api/v5/market/history-candles?instId=BTC-USD-190927

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Instrument ID, e.g. `BTC-USD-200927`
after	String	No	Pagination of data to return records earlier than the requested `ts`
before	String	No	Pagination of data to return records newer than the requested `ts`
bar	String	No	Bar size, the default is `1m` e.g. [1m/3m/5m/15m/30m/1H/2H/4H/6H/12H/1D/1W/1M/3M/6M/1Y]
limit	String	No	Number of results per request. The maximum is `100`; the default is `100`.

Example Response

{
    "code":"0",
    "msg":"",
    "data":[
     [
        "1597026383085",
        "3.721",
        "3.743",
        "3.677",
        "3.708",
        "8422410",
        "22698348.04828491"
    ],
    [
        "1597026383085",
        "3.731",
        "3.799",
        "3.494",
        "3.72",
        "24912403",
        "67632347.24399722"
    ]
    ]
}

Response Parameters

Parameter	Type	Description
ts	String	Data generation time, Unix timestamp format in milliseconds, e.g. `1597026383085`
o	String	Open price
h	String	Highest price
l	String	Lowest price
c	String	Close price
vol	String	Trading volume (cont)
volCcy	String	Trading volume (coin)

Get Index Candlesticks

Retrieve the candlestick charts of the index. This endpoint can retrieve the latest 1,440 data entries. Charts are returned in groups based on the requested bar.

Rate Limit: 20 requests per 2 seconds

HTTP Request

GET /api/v5/market/index-candles

Request Example

GET /api/v5/market/index-candles?instId=BTC-USD

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Index, e.g. `BTC-USD`
after	String	No	Pagination of data to return records earlier than the requested `ts`
before	String	No	Pagination of data to return records newer than the requested `ts`
bar	String	No	Bar size, the default is `1m` e.g. [1m/3m/5m/15m/30m/1H/2H/4H/6H/12H/1D/1W/1M/3M/6M/1Y]
limit	String	No	Number of results per request. The maximum is `100`; The default is `100`

Example Response

{
    "code":"0",
    "msg":"",
    "data":[
     [
        "1597026383085",
        "3.721",
        "3.743",
        "3.677",
        "3.708"
    ],
    [
        "1597026383085",
        "3.731",
        "3.799",
        "3.494",
        "3.72"
    ]
    ]
}

Response Parameters

Parameter	Type	Description
ts	String	Data generation time, Unix timestamp format in milliseconds, e.g. `1597026383085`
o	String	Open price
h	String	Higest price
l	String	Lowest price
c	String	Close price

Get Mark Price Candlesticks

Retrieve the candlestick charts of mark price. This endpoint can retrieve the latest 1,440 data entries. Charts are returned in groups based on the requested bar.

Rate Limit: 20 requests per 2 seconds

HTTP Request

GET /api/v5/market/mark-price-candles

Request Example

GET /api/v5/market/mark-price-candles?instId=BTC-USD-SWAP

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Instrument ID, e.g. `BTC-USD-SWAP`
after	String	No	Pagination of data to return records earlier than the requested `ts`
before	String	No	Pagination of data to return records newer than the requested `ts`
bar	String	No	Bar size, the default is `1m` e.g. [1m/3m/5m/15m/30m/1H/2H/4H/6H/12H/1D/1W/1M/3M/6M/1Y]
limit	String	No	Number of results per request. The maximum is `100`; The default is `100`

Example Response

{
    "code":"0",
    "msg":"",
    "data":[
     [
        "1597026383085",
        "3.721",
        "3.743",
        "3.677",
        "3.708"
    ],
    [
        "1597026383085",
        "3.731",
        "3.799",
        "3.494",
        "3.72"
    ]
    ]
}

Response Parameters

Parameter	Type	Description
ts	String	Data generation time, Unix timestamp format in milliseconds, e.g. `1597026383085`
o	String	Open price
h	String	Higest price
l	String	Lowest price
c	String	Close price

Get Trades

Retrieve the recent transactions of an instrument.

Rate Limit: 20 requests per 2 seconds

HTTP Request

GET /api/v5/market/trades

Request Example

GET /api/v5/market/trades?instId=BTC-USDT

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Instrument ID, e.g. `BTC-USD`
limit	String	No	Number of results per request. The maximum is `100`; The default is `100`

Example Response

{
    "code":"0",
    "msg":"",
    "data":[
     {
        "instId":"BTC-USDT",
        "tradeId":"9",
        "px":"0.016",
        "sz":"50",
        "side":"buy",
        "ts":"1597026383085"
    },
    {
        "instId":"BTC-USDT",
        "tradeId":"9",
        "px":"0.016",
        "sz":"50",
        "side":"buy",
        "ts":"1597026383085"
    }
  ]
}

Response Parameters

Parameter	Type	Description
instId	String	Instrument ID
tradeId	String	Trade ID
px	String	Trade price
sz	String	Trade quantity
side	String	Trade 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` 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 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 and interest-free quota.

Rate Limit: 10 requests per 2 seconds

HTTP Request

GET /api/v5/public/discount-rate-interest-free-quota

Request Example

GET /api/v5/public/discount-rate-interest-free-quota?ccy=BTC

Request Parameters

Parameter	Type	Required	Description
ccy	String	No	Currency

Example Response

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "ccy":"BTC",
            "amt" :"2",
            "discount" :"1"
        }
    ]
}

Response Parameters

Parameter	Type	Description
ccy	String	Currency
amt	String	Interest-free quota
discount	String	Discount rate

Get System Time

Retrieve API server time.

Rate Limit: 10 requests per 2 seconds

HTTP Request

GET /api/v5/public/time

Request Example

GET /api/v5/public/time

Example Response

{
    "code":"0",
    "msg":"",
    "data":[
    {
        "ts":"1597026383085"
    }
  ]
}

Response Parameters

Parameter	Type	Description
ts	String	System time, Unix timestamp format in milliseconds, e.g. `1597026383085`

Get Liquidation Orders

Retrieve information on liquidation orders in the last 1 month.

Rate Limit: 40 requests per 2 seconds

HTTP Request

GET /api/v5/public/liquidation-orders

Request Example

GET /api/v5/public/liquidation-orders?instType=MARGIN

Request Parameters

Parameter	Type	Required	Description
instType	String	Yes	Instrument 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.

ordType
Order type. When creating a new order, you must specify the order type. The order type you specify will affect: 1) what order parameters are required, and 2) how the matching system executes your order. The following are valid order types:
Limit: Limit order, which requires specified sz and px.
Market: Market order
Post_only: Post-only order, which will only be a maker at the moment the order is placed. If any part of the order is filled by the current pending order, the order will be canceled.
Fok: Fill or kill order. If the order cannot be fully filled, the order will be canceled.
Ioc: Immediate or cancel order. Immediately execute the transaction at the order price, cancel the remaining uncompleted quantity of the order, and the order quantity will not be displayed in the order book.

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 `clOrdId`is required, if both are passed, `ordId` will be used.
clOrdId	String	Optional	Client-supplied order ID
reqId	String	No	Client-supplied request ID A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
newSz	String	Optional	New quantity after amendment. Either `newSz` or `newPx` is required. When amending a partially-filled order, the `newSz` should include the amount that has been filled.
newPx	String	Optional	New price after amendment.

Example Response

{
    "code":"0",
    "msg":"",
    "data":[
        {
            "clOrdId":"oktswap6",
            "ordId":"12345689",
            "reqId":"b12344",
            "sCode":"0",
            "sMsg":""
        },
        {
            "clOrdId":"oktswap7",
            "ordId":"12344",
            "reqId":"b12344",
            "sCode":"0",
            "sMsg":""
        },
     .......
    ]
}

Response Parameters

Parameter	Type	Description
ordId	String	Order ID
clOrdId	String	Client-supplied order ID
reqId	String	You can provide the request_id. If provided, the response will include the corresponding request_id to help you identify the request.
sCode	String	The code of the event execution result, `0` means success.
sMsg	String	Message shown when the event execution fails.

Close Positions

Close all positions of an instrument via a market order.

Rate Limit: 20 requests per 2 seconds

HTTP Request

POST /api/v5/trade/close-position

Request Example

POST /api/v5/trade/close-position
body {"instId":"BTC-USDT-SWAP","mgnMode":"cross"}

Request Parameters

Parameter	Type	Required	Description
instId	String	Yes	Instrument ID
posSide	String	Optional	Position side This parameter can be omitted in `net` mode, and the default value is `net`. You can only fill with `net`. This parameter must be filled in under the `long/short` mode. Fill in `long` for close-long and `short` for close-short.
mgnMode	String	Yes	Margin 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` in`net` 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`

WebSocket API

Overview

WebSocket is a new HTML5 protocol that achieves full-duplex data transmission between the client and server, allowing data to be transferred effectively in both directions. A connection between the client and server can be established with just one handshake. The server will then be able to push data to the client according to preset rules. Its advantages include:

The WebSocket request header size for data transmission between client and server is only 2 bytes.
Either the client or server can initiate data transmission.
There's no need to repeatedly create and delete TCP connections, saving resources on bandwidth and server.

Connect

Connection instructions:

Connection limit: 1 time per second

When subscribing to a public channel, use the address of the public service. When subscribing to a private channel, use the address of the private service

Subscription limit: 240 times per hour

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'

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.

If the price is the same, compare the quantity. If the quantity is different and is not 0, update the buy one or sell one in the total data. Otherwise, delete the buy one or sell one.
If the prices are not the same, sort them in order and insert buy one or sell one into the full data.

Example 1

{
 "arg": {
       "channel": "books",
       "instId":"BTC-USD-191227"
     },
 "action":"snapshot",
 "data": [
      {
        "asks": [[3366.8, 9, 10, 3],[ 3368,8,3,4 ]],
        "bids": [[3366.1, 7, 0, 3],[ 3366,6,3,4 ]]],
        "ts": "1597026383085",
        "checksum": "-855196043"
      }
  ]
}

Example 1: When bid and ask are aligned, the string to be verified is:
bid[price:size]:ask[price:size]:bid[price:size]:ask[price:size]...

The checksum string corresponding to this example is:
3366.1:7:3366.8:9:3366:6:3368:8

Example 2

{
 "arg": {
       "channel": "books",
       "instId":"BTC-USD-191227"
     },
 "action":"update",
 "data": [
      {
        "asks": [[3366.8, 9, 10, 3],[ 3368,8,3,4 ],[ 3372,8,3,4 ]],
        "bids": [[3366.1, 7, 0, 3]],
        "ts": "1597026383085",
        "checksum": "-855196043"
      }
  ]
}

Example 2: When bid and ask are not aligned, the string to be verified is:
bid[price:size]:ask[price:size]:ask[price:size]:ask[price:size]:...

The checksum string corresponding to this example is:
3366.1:7:3366.8:9:3368:8:3372:8

Public Channel

Instruments Channel

The full instrument list will be pushed for the first time after subscription. Subsequently, the instruments will be pushed if there's any change to the instrument’s state (such as delivery of FUTURES, exercise of OPTION, listing of new contracts / trading pairs, trading suspension, etc.).

Request Example

{
  "op": "subscribe",
  "args": [
    {
      "channel": "instruments",
      "instType": "FUTURES"
    }
  ]
}

Request parameters

Parameter	Type	Required	Description
op	String	Yes	Operation, `subscribe` `unsubscribe`
args	Array	Yes	List of subscribed channels
> channel	String	Yes	Channel name, `instruments`
> instType	String	Yes	Instrument 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",
            "availBal": "1415",
            "frozenBal": "14",
            "ordFrozen": "12",
            "upl": "124",
            "mgnRatio": "124",
            "interest": "12",
            "liab": "1"
        }]
    }]
}

Push Data Example

{
    "arg": {
        "channel": "account"
    },
    "data": [{
        "uTime": "1597026383085",
        "totalEq": "41624.32",
        "isoEq": "3624.32",
        "adjEq": "41624.32",
        "imr": "4162.33",
        "mmr": "4",
        "mgnRatio": "41624.32",
        "details": [{
            "ccy": "BTC",
            "eq": "123",
            "availEq": "1234",
            "availBal": "1415",
            "frozenBal": "14",
            "ordFrozen": "12",
            "upl": "124",
            "mgnRatio": "124",
            "interest": "12",
            "liab": "1"
        }, {
            "ccy": "ETH",
            "eq": "223",
            "availEq": "2234",
            "availBal": "415",
            "frozenBal": "141",
            "ordFrozen": "12",
            "upl": "124",
            "mgnRatio": "124",
            "interest": "0",
            "liab": "0"
        }]
    }]
}

Push data parameters

Parameter	Type	Description
`arg`	Object	Channel to subscribe to
> channel	String	Channel name
> ccy	String	Currency
`data`	Array	Subscribed data
> uTime	String	Push time of account information, millisecond format of Unix timestamp, e.g. `1597026383085`.
> totalEq	String	Total equity in USD level
> isoEq	String	Isolated margin equity in USD level Applicable to `Single-currency margin account` and `Multi-currency margin account`
> adjEq	String	Adjusted/Effective equity in USD level Applicable to `Multi-currency margin account`
> imr	String	Initial margin requirement in USD level Applicable to `Multi-currency margin account`
> mmr	String	Maintenance margin requirement in USD level Applicable to `Multi-currency margin account`
> mgnRatio	String	Margin ratio in USD level Applicable to `Multi-currency margin account`
> details	Array	Currency level details
>> ccy	String	Currency
>> eq	String	Equity of the currency
>> isoEq	String	Isolated margin equity of the currency Applicable to `Single-currency margin account` and `Multi-currency margin account`
>> availEq	String	Available equity of the currency Applicable to `Single-currency margin account` and `Multi-currency margin account`
>> availBal	String	Available balance of the currency Applicable to `Simple account`
>> frozenBal	String	Frozen balance of the currency
>> ordFrozen	String	Margin frozen for open orders
>> liab	String	Liabilities of the currency Applicable to `Multi-currency margin account`
>> upl	String	Unrealized profit and loss of the currency Applicable to `Single-currency margin account` and `Multi-currency margin account`
>> mgnRatio	String	Margin ratio of the currency Applicable to `Single-currency margin account`
>> interest	String	Interest of the currency Applicable to `Multi-currency margin account`

Distribution of applicable fields under each account level are as follows:

Parameters	Simple account	Single-currency margin account	Multi-currency margin account
uTime	Yes	Yes	Yes
totalEq	Yes	Yes	Yes
isoEq		Yes	Yes
adjEq			Yes
imr			Yes
mmr			Yes
mgnRatio			Yes
details
> ccy	Yes	Yes	Yes
> eq	Yes	Yes	Yes
> isoEq		Yes	Yes
> availEq		Yes	Yes
> availBal	Yes
> frozenBal	Yes	Yes	Yes
> ordFrozen	Yes	Yes	Yes
> liab			Yes
> upl		Yes	Yes
> mgnRatio		Yes
> interest			Yes

Positions Channel

Retrieve position information. Initial snapshot will be pushed according to subscription granularity. Data will be pushed when triggered by events such as placing/canceling order, and will also be pushed in regular interval according to subscription granularity.

Request Example : single

{
    "op": "subscribe",
    "args": [{
        "channel": "positions",
        "instType": "FUTURES",
        "uly": "BTC-USD",
        "instId": "BTC-USD-200329"
    }]
}

Request Example

{
    "op": "subscribe",
    "args": [{
        "channel": "positions",
        "instType": "ANY"
    }]
}

Request parameters

Parameter	Type	Required	Description
op	String	Yes	Operation, `subscribe` `unsubscribe`
`args`	Array	Yes	List of subscribed channels
> channel	String	Yes	Channel name, `positions`
> instType	String	Yes	Instrument 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 Account` and `isolated` `OPTION` in margin Account.
> avgPx	String	Average open price
> upl	String	Unrealized profit and loss
> uplRatio	String	Unrealized profit and loss ratio
> instId	String	Instrument ID, e.g. `BTC-USD-180216`
> lever	String	Leverage, not applicable to `OPTION` seller
> liqPx	String	Estimated liquidation price Not applicable to `cross` `FUTURES/SWAP` in `Multi-currency margin account`. Not applicable to `OPTION`
> imr	String	Initial margin requirement, only applicable to `cross`
> margin	String	Margin, can be added or reduced. Only applicable to `isolated` `Margin`.
> mgnRatio	String	Margin ratio, only applicable to`isolated`.
> mmr	String	Maintenance margin requirement
> liab	String	Liabilities, only applicable to `MARGIN`.
> liabCcy	String	Liabilities currency, only applicable to `MARGIN`.
> interest	String	Interest. Interest that has been incurred.
> tradeId	String	Last trade ID
> optVal	String	Option Value, only applicable to `OPTION`.
> adl	String	Auto decrease line, signal area Divided into 5 levels, from 1 to 5, the smaller the number, the weaker the adl intensity.
> ccy	String	Currency used for margin
> last	String	Latest traded price
> cTime	String	Creation time, Unix timestamp format in milliseconds, e.g. `1597026383085`.
> uTime	String	Latest time position was adjusted, Unix timestamp format in milliseconds, e.g. `1597026383085`.
> pTime	String	Push time of positions information, Unix timestamp format in milliseconds, e.g. `1597026383085`.

Order Channel

Retrieve order information. Data will not be pushed when first subscribed. Data will only be pushed when triggered by events such as placing/canceling order.

Request Example : single

{
    "op": "subscribe",
    "args": [{
        "channel": "orders",
        "instType": "FUTURES",
        "uly": "BTC-USD",
        "instId": "BTC-USD-200329"
    }]
}

Request Example

{
    "op": "subscribe",
    "args": [{
        "channel": "orders",
        "instType": "FUTURES",
        "uly": "BTC-USD"
    }]
}

Request parameters

Parameter	Type	Required	Description
op	String	Yes	Operation, `subscribe` `unsubscribe`
`args`	Array	Yes	List of subscribed channels
> channel	String	Yes	Channel name, `orders`
> instType	String	Yes	Instrument 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 account`.
> ordId	String	Order ID
> clOrdId	String	Client-supplied order ID
> tag	String	Order tag
> px	String	Order price
> sz	String	The original order quantity, `SPOT/MARGIN`, in the unit of currency; `FUTURES/SWAP/OPTION`, in the unit of contract
> ordType	String	Order 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 account`.
> ordId	String	Order ID, the order ID associated with the algo order.
> algoId	String	Algo ID
> sz	String	Quantity to buy or sell. `SPOT/MARGIN`: in the unit of currency. `FUTURES/SWAP/OPTION`: in the unit of contract.
> ordType	String	Order 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 account`.
> clOrdId	String	No	Client-supplied order ID A combination of case-sensitive alphanumerics beginning with a letter, or alphabets of up to 32 characters.
> tag	String	No	Order tag A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 8 characters.
> side	String	Yes	Order side, `buy` `sell`
> posSide	String	No	Position side The default is `net` in the `net` 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 account`.
> clOrdId	String	No	Client-supplied order ID A combination of case-sensitive alphanumerics beginning with a letter, or alphabets of up to 32 characters.
> tag	String	No	Order tag A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 8 characters.
> side	String	Yes	Order side, `buy` `sell`
> posSide	String	No	Position side The default `net` in the `net` 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

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

SWAP

OPTION

FUNDING

Error Code from 58000 to 58999

Error Message	HTTP Status Code	Error Code
Account type {0} does not supported when getting the sub-account balance.	200	58000
Incorrect trade password.	200	58001
Please activate Savings Account first.	200	58002
Currency type is not supported by Savings Account.	200	58003
Account blocked (transfer & withdrawal endpoint: either end of the account does not authorize the transfer).	200	58004
The redeemed amount must be no greater than {0}.	200	58005
Service unavailable for token {0}.	200	58006
Funds cannot be transferred in or out during option exercise or settlement.	200	58100
Transfer suspended (transfer endpoint: either end of the account does not authorize the transfer).	200	58101
Too frequent transfer (transfer too frequently).	200	58102
Parent account user id does not match sub-account user id.	200	58103
Since your P2P transaction is abnormal, you are restricted from making fund transfers. Please contact customer support to remove the restriction.	200	58104
Since your P2P transaction is abnormal, you are restricted from making fund transfers. Please transfer funds on our website or app to complete identity verification.	200	58105
Please enable the account for spot contract.	200	58106
Please enable the account for futures contract.	200	58107
Please enable the account for option contract.	200	58108
Please enable the account for swap contract.	200	58109
The contract triggers risk control, and the platform has suspended the fund transfer function of it. Please wait patiently.	200	58110
Funds transfer unavailable as the perpetual contract is charging the funding fee. Please try again later.	200	58111
Transfer amount must be more than 0.	400	58114
Sub-account does not exist.	200	58115
Transfer amount exceeds the limit.	200	58116
Withdrawal from {0} to {1} is unavailable for this currency.	200	58200
Withdrawal amount exceeds the daily limit.	200	58201
The minimum withdrawal amount for NEO is 1, and the amount must be an integer.	200	58202
Please add a withdrawal address.	200	58203
Withdrawal suspended.	200	58204
Withdrawal amount exceeds the upper limit.	200	58205
Withdrawal amount is lower than the lower limit.	200	58206
Withdrawal failed due to address error.	200	58207
Withdrawal failed. Please link your email.	200	58208
Withdrawal failed. Withdraw feature is not available for sub-accounts.	200	58209
Withdrawal fee exceeds the upper limit.	200	58210
Withdrawal fee is lower than the lower limit (withdrawal endpoint: incorrect fee).	200	58211
Withdrawal fee should be {0}% of the withdrawal amount.	200	58212
Please set trading password before withdrawal.	200	58213
Deposit-address count exceeds the limit.	200	58300
Insufficient balance.	200	58350

Account

Error Code from 59000 to 59999

Error Message	HTTP Status Code	Error Code
Your settings failed as you have positions or open orders.	200	59000
Switching unavailable as you have borrowings.	200	59001
You have open positions. Please cancel all open positions before changing the leverage.	200	59100
You have pending orders with isolated positions. Please cancel all the pending orders and adjust the leverage.	200	59101
Leverage exceeds the maximum leverage. Please adjust the leverage.	200	59102
Leverage is too low and no sufficient margin in your account. Please adjust the leverage.	200	59103
The leverage is too high. The borrowed position has exceeded the maximum position of this leverage. Please adjust the leverage.	200	59104
Leverage can not be less than {0}. Please adjust the leverage.	400	59105
The max available margin corresponding to your order tier is {0}. Please adjust your margin and place a new order.	200	59106
You have pending orders under the service, please modify the leverage after canceling all pending orders.	200	59107
Low leverage and insufficient margin, please adjust the leverage.	200	59108
Account equity less than the required margin amount after adjustment. Please adjust the leverage .	200	59109
Insufficient account balance.	200	59200
Negative account balance.	200	59201
Margin call failed. Position does not exist.	200	59300
Margin adjustment failed for exceeding the max limit.	200	59301
Holdings already reached the limit.	200	59401

WebSocket

Public

Error Code from 60000 to 63999

General Class

Error Message	Error Code
"OK_ACCESS_KEY" can not be empty.	60001
"OK_ACCESS_SIGN" can not be empty.	60002
"OK_ACCESS_PASSPHRASE" can not be empty.	60003
Invalid OK_ACCESS_TIMESTAMP.	60004
Invalid OK_ACCESS_KEY.	60005
Timestamp request expired.	60006
Invalid sign.	60007
Login is not supported for public channels.	60008
Login failed.	60009
Already logged in.	60010
Please log in.	60011
Illegal request.	60012
Invalid args.	60013
Requests too frequent.	60014
Connection closed as there was no data transmission in the last 30 seconds.	60015
Buffer is full, cannot write data.	60016
Invalid url path.	60017
The {0} {1} {2} {3} {4} does not exist.	60018
Invalid op {op}	60019
Internal system error.	63999

Log

Update log