NAV
中文
Java Python Go C++

Market Maker Program

High-caliber trading teams are welcomed to work with OKEx as market makers in providing a liquid, fair, and orderly platform to all users. OKEx market makers could enjoy favourable fees in return for meeting the market making obligations.。

Prerequisites (Satisfy any condition):

Interested parties could drop us an email at mmcorporate@okex.com with the below details:

Remarks:

Market making obligations and trading fees will be shared to successful parties only.

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.

Production Trading Services

The Production Trading URL:

AWS URL:

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:

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.

Http Header 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 website before signing any requests. After creating an APIKey, keep the following information safe:

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

Making Requests

All private REST requests must contain the following headers:

OK-ACCESS-KEY The APIKey as a String.

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

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

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

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

Signature

Signing Messages

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

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

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

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

The requestPath is the path of requesting an endpoint.

Example: /api/v5/account/balance

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

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

The SecretKey is generated when you create an APIKey.

Example: 22582BD0CFF14C41EDBF1AB98506286D

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

Derivatives rate limit rule: UserID +(instrument_type、underlying)

Spot margin rate limit rule: UserID +(instrument_type、instrumentID)

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, all numbers, or all letters 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 Yes 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: market order
limit: limit order
post_only: Post-only order
fok: Fill-or-kill order
ioc: Immediate-or-cancel order
optimal_limit_ioc :Market order with immediate-or-cancel order (applicable only to Futures and Perpetual swap).
sz String Yes Quantity to buy or sell.
px String Optional Order price. Only applicable to limit,post_only,fok,ioc order.
reduceOnly Boolean No Whether to reduce position only or not, true false, the default is false.
Only applicable to MARGIN orders
tgtCcy String No Quantity type
base_ccy:Base currency ;quote_ccy:Quote currency
Only applicable to SPOT traded with Market order

Example Response

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "clOrdId": "oktswap6",
      "ordId": "312269865356374016",
      "tag": "",
      "sCode": "0",
      "sMsg": ""
    }
  ]
}

Response Parameters

Parameter Type Description
ordId String Order ID
clOrdId String Client-supplied order ID
tag String Order tag
sCode String The code of the event execution result, 0 means success.
sMsg String Message shown when the event execution fails.

Place Multiple Orders

Place orders in batches. Maximum 20 orders can be placed at a time. Request parameters should be passed in the form of an array.

Rate Limit: 300 requests per 2 seconds

Derivatives rate limit rule: UserID +(instrument_type、underlying)

Spot margin rate limit rule: UserID +(instrument_type、instrumentID)

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, all numbers, or all letters 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 Yes 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: market order
limit: limit order
post_only: Post-only order
fok: Fill-or-kill order
ioc: Immediate-or-cancel order
optimal_limit_ioc :Market order with immediate-or-cancel order (applicable only to Futures and Perpetual swap).
sz String Yes Quantity to buy or sell
px String No Order price. Only applicable to limit,post_only,fok,ioc order.
reduceOnly Boolean No Whether reduce position only or not
true false, the default is false.
tgtCcy String No Quantity type
base_ccy:Base currency ;quote_ccy:Quote currency
Only applicable to SPOT

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

Derivatives rate limit rule: UserID +(instrument_type、underlying)

Spot margin rate limit rule: UserID +(instrument_type、instrumentID)

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

Derivatives rate limit rule: UserID +(instrument_type、underlying)

Spot margin rate limit rule: UserID +(instrument_type、instrumentID)

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

Derivatives rate limit rule: UserID +(instrument_type、underlying)

Spot margin rate limit rule: UserID +(instrument_type、instrumentID)

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

Spot margin rate limit rule: UserID +(instrument_type、instrumentID)

HTTP Request

POST /api/v5/trade/amend-batch-orders

Request Example

POST /api/v5/trade/amend-batch-orders
body
[
    {
        "ordId":"2510789768709120",
        "newSz":"2",
        "instId":"BTC-USDT"
    },
    {
        "ordId":"2510789768709121",
        "newSz":"2",
        "instId":"BTC-USDT"
    }
]

Request Parameters

Parameter Type Required Description
instId String Yes Instrument ID
cxlOnFail Boolean No Whether the order needs to be automatically canceled when the order amendment fails
false true, the default is false.
ordId String Optional Order ID
Either ordId or clOrdIdis required, if both are passed, ordId will be used.
clOrdId String Optional Client-supplied order ID
reqId String No Client-supplied request ID
A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
newSz String Optional New quantity after amendment. Either newSz or newPx is required. When amending a partially-filled order, the newSz should include the amount that has been filled.
newPx String Optional New price after amendment.

Example Response

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

Response Parameters

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

Close Positions

Close all positions of an instrument via a market order.

Rate Limit: 20 requests per 2 seconds

Derivatives rate limit rule: UserID +(instrument_type、underlying)

Spot margin rate limit rule: UserID +(instrument_type、instrumentID)

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

Derivatives rate limit rule: UserID +(instrument_type、underlying)

Spot margin rate limit rule: UserID +(instrument_type、instrumentID)

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": "312269865356374016",
      "clOrdId": "b1",
      "tag": "",
      "px": "999",
      "sz": "3",
      "pnl": "5",
      "ordType": "limit",
      "side": "buy",
      "posSide": "long",
      "tdMode": "isolated",
      "accFillSz": "0",
      "fillPx": "0",
      "tradeId": "0",
      "fillSz": "0",
      "fillTime": "0",
      "state": "live",
      "avgPx": "0",
      "lever": "20",
      "tpTriggerPx": "",
      "tpOrdPx": "",
      "slTriggerPx": "",
      "slOrdPx": "",
      "feeCcy": "",
      "fee": "",
      "rebateCcy": "",
      "rebate": "",
      "tgtCcy":"",
      "category": "",
      "uTime": "1597026383085",
      "cTime": "1597026383085"
    }
  ]
}

Response Parameters

Parameter Type Description
instType String Instrument type
SPOT
MARGIN
SWAP
FUTURES
OPTION
instId String Instrument ID
tgtCcy String Quantity type
base_ccy:Base currency ;quote_ccy:Quote currency
Only applicable to SPOT
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
optimal_limit_ioc :Market order with 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
Negative number represents the user transaction fee charged by the platform.
Positive number represents rebate.
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
delivery
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

Rate limit rule: UserID

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: market order
limit: limit order
post_only: Post-only order
fok: Fill-or-kill order
ioc: Immediate-or-cancel order
Optimal_limit_ioc :Market order with immediate-or-cancel order
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": [
        {
            "accFillSz": "0",
            "avgPx": "",
            "cTime": "1618235248028",
            "category": "normal",
            "ccy": "",
            "clOrdId": "",
            "fee": "0",
            "feeCcy": "BTC",
            "fillPx": "",
            "fillSz": "0",
            "fillTime": "",
            "instId": "BTC-USDT",
            "instType": "SPOT",
            "lever": "5.6",
            "ordId": "301835739059335168",
            "ordType": "limit",
            "pnl": "0",
            "posSide": "net",
            "px": "59200",
            "rebate": "0",
            "rebateCcy": "USDT",
            "side": "buy",
            "slOrdPx": "",
            "slTriggerPx": "",
            "state": "live",
            "sz": "1",
            "tag": "",
            "tgtCcy": "",
            "tdMode": "cross",
            "tpOrdPx": "",
            "tpTriggerPx": "",
            "tradeId": "",
            "uTime": "1618235248028"
        }
    ]
}

Response Parameters

Parameter Type Description
instType String Instrument type
instId String Instrument ID
tgtCcy String Quantity type
base_ccy:Base currency ;quote_ccy:Quote currency
Only applicable to SPOT
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
optimal_limit_ioc :Market order with 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
Negative number represents the user transaction fee charged by the platform.
Positive number represents rebate.
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
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

Rate limit rule: UserID

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: market order
limit: limit order
post_only: Post-only order
fok: Fill-or-kill order
ioc: Immediate-or-cancel order
optimal_limit_ioc :Market order with immediate-or-cancel order
state String No State
canceled
filled
category String No Category
twap
adl
full_liquidation
partial_liquidation
delivery
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": "312269865356374016",
      "clOrdId": "b1",
      "tag": "",
      "px": "999",
      "sz": "3",
      "ordType": "limit",
      "side": "buy",
      "posSide": "long",
      "tdMode": "isolated",
      "accFillSz": "0",
      "fillPx": "0",
      "tradeId": "0",
      "fillSz": "0",
      "fillTime": "0",
      "state": "filled",
      "avgPx": "0",
      "lever": "20",
      "tpTriggerPx": "",
      "tpOrdPx": "",
      "slTriggerPx": "",
      "slOrdPx": "",
      "feeCcy": "",
      "fee": "",
      "rebateCcy": "",
      "rebate": "",
      "tgtCcy":"",
      "pnl": "",
      "category": "",
      "uTime": "1597026383085",
      "cTime": "1597026383085"
    }
  ]
}

Response Parameters

Parameter Type Description
instType String Instrument type
instId String Instrument ID
tgtCcy String Quantity type
base_ccy:Base currency ;quote_ccy:Quote currency
Only applicable to SPOT
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
optimal_limit_ioc :Market order with 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 The order transaction fee refers to the fee charged by our platform to users, and it is deducted as a negative number.
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
delivery
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

Rate limit rule: UserID

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: market order
limit: limit order
post_only: Post-only order
fok: Fill-or-kill order
ioc: Immediate-or-cancel order
optimal_limit_ioc :Market order with immediate-or-cancel order
state String No State
canceled
filled
category String No Category
twap
adl
full_liquidation
partial_liquidation
delivery
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": "312269865356374016",
      "clOrdId": "b1",
      "tag": "",
      "px": "999",
      "sz": "3",
      "ordType": "limit",
      "side": "buy",
      "posSide": "long",
      "tdMode": "isolated",
      "accFillSz": "0",
      "fillPx": "0",
      "tradeId": "0",
      "fillSz": "0",
      "fillTime": "0",
      "state": "filled",
      "avgPx": "0",
      "lever": "20",
      "tpTriggerPx": "",
      "tpOrdPx": "",
      "slTriggerPx": "",
      "slOrdPx": "",
      "feeCcy": "",
      "fee": "",
      "rebateCcy": "",
      "rebate": "",
      "tgtCcy":"",
      "pnl": "",
      "category": "",
      "uTime": "1597026383085",
      "cTime": "1597026383085"
    }
  ]
}

Response Parameters

Parameter Type Description
instType String Instrument type
instId String Instrument ID
tgtCcy String Quantity type
base_ccy:Base currency ;quote_ccy:Quote currency
Only applicable to SPOT
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
optimal_limit_ioc :Market order with 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
delivery
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 (last 3 days)

Retrieve recently-filled transaction details in the last 3 day.

Rate Limit: 60 requests per 2 seconds

Rate limit rule: UserID

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",
            "clOrdId": "b16",
            "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",
            "clOrdId": "b16",
            "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
clOrdId String Client-supplied order ID
billId String Bill ID
tag String Order tag
fillPx String Last filled price
fillSz String Last filled quantity
side String Order side, buy sell
posSide String Position side
long short
it returns net innet mode.
execType String Order flow type, T: taker M: maker
feeCcy String Fee currency
fee String Fee
ts String Data generation time, Unix timestamp format in milliseconds, e.g. 1597026383085.

Get Transaction Details (last 3 months)

Retrieve recently-filled transaction details in the last 3 months.

Rate Limit: 10 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/trade/fills-history

Request Example

GET /api/v5/trade/fills-history

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
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",
            "clOrdId": "b16",
            "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",
            "clOrdId": "b16",
            "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
clOrdId String Client-supplied order ID
billId String Bill ID
tag String Order tag
fillPx String Last filled price
fillSz String Last filled quantity
side String Order side, buy sell
posSide String Position side
long short
it returns net innet mode.
execType String Order flow type, T: taker M: maker
feeCcy String Fee currency
fee String Fee
ts String Data generation time, Unix timestamp format in milliseconds, e.g. 1597026383085.

Place Algo Order

The algo order includes trigger order, oco order, conditional order,iceberg order and twap order.

Rate Limit: 20 requests per 2 seconds

Derivatives rate limit rule: UserID +(instrument_type、underlying)

Spot margin rate limit rule: UserID +(instrument_type、instrumentID)

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
iceberg: Iceberg order
twap: TWAP order
sz String Yes Quantity to buy or sell
reduceOnly Boolean No Whether reduce position only or not, true false
tgtCcy String No Quantity type
base_ccy:Base currency ;quote_ccy:Quote currency
Only applicable to SPOT

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
If the price is -1, the order will be executed at the market price.

Iceberg Order

Parameter Type Required Description
pxVar String Optional Price variance
Either pxVar or pxSpread is allowed to be passed.
pxSpread String Optional Price ratio
szLimit String Yes Average amount
pxLimit String Yes Price Limit

TWAP Order

Parameter Type Required Description
pxVar String Optional Price variance
Either pxVar or pxSpread is allowed to be passed.
pxSpread String Optional Price ratio
szLimit String Yes Average amount
pxLimit String Yes Price Limit
timeInterval String Yes Time interval

learn more about Iceberg Order & TWAP Order

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(trigger order, oco order, conditional order). A maximum of 10 orders can be canceled at a time. Request parameters should be passed in the form of an array.

Rate Limit: 20 requests per 2 seconds

Derivatives rate limit rule: UserID +(instrument_type、underlying)

Spot margin rate limit rule: UserID +(instrument_type、instrumentID)

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.

Cancel Advance Algo Order

Cancel unfilled algo orders(iceberg order and twap order). A maximum of 10 orders can be canceled at a time. Request parameters should be passed in the form of an array.

Rate Limit: 20 requests per 2 seconds

Derivatives rate limit rule: UserID +(instrument_type、underlying)

Spot margin rate limit rule: UserID +(instrument_type、instrumentID)

HTTP Request

POST /api/v5/trade/cancel-advance-algos

Request Example

POST /api/v5/trade/cancel-advance-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

Rate limit rule: UserID

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
iceberg: Iceberg order
twap: TWAP 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": "312269865356374016",
      "ccy": "BTC",
      "algoId": "1234",
      "sz": "999",
      "ordType": "oco",
      "side": "buy",
      "posSide": "long",
      "tdMode": "cross",
      "tgtCcy": "",
      "state": "1",
      "lever": "20",
      "tpTriggerPx": "",
      "tpOrdPx": "",
      "slTriggerPx": "",
      "triggerPx": "99",
      "ordPx": "12",
      "actualSz": "",
      "actualPx": "",
      "actualSide": "",
      "pxVar":"",
      "pxSpread":"",
      "pxLimit":"",
      "szLimit":"",
      "timeInterval":"",
      "triggerTime": "1597026383085",
      "cTime": "1597026383000"
    },
    {
      "instType": "FUTURES",
      "instId": "BTC-USD-200329",
      "ordId": "312269865356374016",
      "ccy": "BTC",
      "algoId": "1234",
      "sz": "999",
      "ordType": "oco",
      "side": "buy",
      "posSide": "long",
      "tdMode": "cross",
      "tgtCcy": "",
      "state": "1",
      "lever": "20",
      "tpTriggerPx": "",
      "tpOrdPx": "",
      "slTriggerPx": "",
      "triggerPx": "99",
      "ordPx": "12",
      "actualSz": "",
      "actualPx": "",
      "actualSide": "",
      "pxVar":"",
      "pxSpread":"",
      "pxLimit":"",
      "szLimit":"",
      "timeInterval":"",
      "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
side String Order side
posSide String Position side
tdMode String Trade mode
tgtCcy String Quantity type
base_ccy:Base currency ;quote_ccy:Quote currency
Only applicable to SPOT
state String State,live pause partially_effective
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
pxVar String Price variance
Only applicable to iceberg order or twap order
Only released on demo trading
pxSpread String Price Ratio
Only applicable to iceberg order or twap order
Only released on demo trading
szLimit String Average amount
Only applicable to iceberg order or twap order
Only released on demo trading
pxLimit String Price Limit
Only applicable to iceberg order or twap order
Only released on demo trading
timeInterval String Time interval
Only applicable to twap order
Only released on demo trading
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 in the last 3 months.

Rate Limit: 20 requests per 2 seconds

Rate limit rule: UserID

HTTP Request

GET /api/v5/trade/orders-algo-history

Request Example

GET /api/v5/trade/orders-algo-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
iceberg: Iceberg order
twap: TWAP 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":"SPOT",
            "instId":"BTC-USDT",
            "ordId":"123445",
            "ccy":"BTC",
            "algoId":"1234",
            "sz":"999",
            "ordType":"oco",
            "side":"buy",
            "posSide":"long",
            "tdMode":"cross",
            "tgtCcy": "",
            "state":"effective",
            "lever":"20",
            "tpTriggerPx":"",
            "tpOrdPx":"",
            "slTriggerPx":"",
            "triggerPx":"99",
            "ordPx":"12",
            "actualSz":"",
            "actualPx":"",
            "actualSide":"",
            "pxVar":"",
            "pxSpread":"",
            "pxLimit":"",
            "szLimit":"",
            "timeInterval":"",
            "triggerTime":"1597026383085",
            "cTime":"1597026383000"
        },
        {
            "instType":"SPOT",
            "instId":"BTC-USDT",
            "ordId":"123445",
            "ccy":"BTC",
            "algoId":"1234",
            "sz":"999",
            "ordType":"oco",
            "side":"buy",
            "posSide":"long",
            "tdMode":"cross",
            "tgtCcy": "",
            "state":"effective",
            "lever":"20",
            "tpTriggerPx":"",
            "tpOrdPx":"",
            "slTriggerPx":"",
            "triggerPx":"99",
            "ordPx":"12",
            "actualSz":"",
            "actualPx":"",
            "actualSide":"",
            "pxVar":"",
            "pxSpread":"",
            "pxLimit":"",
            "szLimit":"",
            "timeInterval":"",
            "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
side String Order side
posSide String Position side
tdMode String Trade mode
tgtCcy String Quantity type
base_ccy:Base currency ;quote_ccy:Quote currency
Only applicable to SPOT
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
pxVar String Price variance
Only applicable to iceberg order or twap order
Only released on demo trading
pxSpread String Price Ratio
Only applicable to iceberg order or twap order
Only released on demo trading
szLimit String Average amount
Only applicable to iceberg order or twap order
Only released on demo trading
pxLimit String Price Limit
Only applicable to iceberg order or twap order
Only released on demo trading
timeInterval String Time interval
Only applicable to twap order
Only released on demo trading
cTime String Creation time Unix timestamp format in milliseconds, e.g. 1597026383085

Funding

The API endpoints of Funding require authentication.

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-Omni
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

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: 1 requests per second

HTTP Request

POST /api/v5/asset/transfer

Request Example

Transfer 1.5 USDT from funding account to Unified account 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 Unified account 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 Unified account to SPOT account BTC-USDT when current account is master-account
POST /api/v5/asset/transfer
body 
{
    "ccy":"USDT",
    "amt":"2",
    "from":"18",
    "to":"5",
    "toInstId":"BTC-USDT"
}

Request Parameters

Parameter Type Required Description
ccy String Yes Currency, e.g. USDT
amt String Yes Amount to be transferred
type String No Transfer type
0: transfer within account
1: master account to sub-account
2: sub-account to master account
the default is 0
from String Yes The remitting account
1: SPOT 3: FUTURES 5: MARGIN 6: FUNDING 9: SWAP 12: OPTION 18: Unified account
to String Yes The beneficiary account
1: SPOT 3: FUTURES 5: MARGIN 6: FUNDING 9: SWAP 12: OPTION 18: Unified account
subAcct String Optional Name of the sub-account
When type is 1 or 2, 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

Asset Bills Details

Query the billing record, you can get the latest 1 month historical data

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 No Currency
type String No Bill type
1: Deposit
2: Withdrawal
13: Canceled withdrawal
18: Transfer to futures
19: Transfer from futures
20: Transfer to Sub account
21: Transfer from Sub account
28: Claim
33: Transfer to margin
34: Transfer from margin
37: Transfer to spot
38: Transfer from spot
41: Trading fees settled by loyalty points
42: Loyalty points purchase
47: System reversal
48: Received from activities
49: Given away to activities
50: Received from appointments
51: Deducted from appointments
52: Red packet sent
53: Red packet snatched
54: Red packet refunded
55: Transfer to perpetual
56: Transfer from perpetual
59: Transfer from hedging account
60: Transfer to hedging account
61: Conversion
63: Transfer to options
62: Transfer from options
68: Claim rebate card
69: Distribute rebate card
72: Token received
73: Token given away
74: Token refunded
75: Subscription to savings
76: Redemption to savings
77: Distribute
78: Lock up
79: Node voting
80: Staking
81: Vote redemption
82: Staking redemption
83: Staking yield
84: Violation fee
85: PoW mining yield
86: Cloud mining pay
87: Cloud mining yield
88: Subsidy
89: Staking
90: Staking subscription
91: staking redemption
92: Add collateral
93: Redeem collateral
94: Investment
95: Borrower borrows
96: Principal transferred in
97: Borrower transferred loan out
98: Borrower transferred interest out
99: Investor transferred interest in
102: Prepayment penalty transferred in
103: Prepayment penalty transferred out
104: Fee transferred in
105: Fee transferred out
106: Overdue fee transferred in
107: Overdue fee transferred out
108: Overdue interest transferred out
109: Overdue interest transferred in
110: Collateral for closed position transferred in
111: Collateral for closed position transferred out
112: Collateral for liquidation transferred in
113: Collateral for liquidation transferred out
114: Insurance fund transferred in
115: Insurance fund transferred out
116: Place an order
117: Fulfill an order
118: Cancel an order
119: Merchants unlock deposit
120: Merchants add deposit
121: FiatGateway Place an order
122: FiatGateway Cancel an order
123: FiatGateway Fulfill an order
124: Jumpstart unlocking
125: Manual deposit
126: Interest deposit
127: Investment fee transferred in
128: Investment fee transferred out
129: Rewards transferred in
130: Transferred from unified account
131: Transferred to unified account
after String No Pagination of data to return records earlier than the requested ts, Unix timestamp format in milliseconds, e.g. 1597026383085
before String No Pagination of data to return records newer than the requested ts, Unix timestamp format in milliseconds, e.g. 1597026383085
limit String No Number of results per request. The maximum is 100; the default is 100.

Example Response

{
    "code": "0",
    "msg": "",
    "data": [{
        "billId": "12344",
        "ccy": "BTC",
        "balChg": "2",
        "bal": "12",
        "type": "1",
        "ts": "1597026383085"
    }]
}

Response Parameters

Parameter Type Description
billId String Bill ID
ccy String Account balance currency
balChg String Change in balance at the account level
bal String Balance at the account level
type String Bill type
ts String Creation time, Unix timestamp format in milliseconds, e.g.1597026383085

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",
    "data": [
        {
            "chain": "BTC-Bitcoin",
            "ctAddr": "",
            "ccy": "BTC",
            "to": "6",
            "addr": "39XNxK1Ryqgg3Bsyn6HzoqV4Xji25pNkv6",
            "selected": true
        },
        {
            "chain": "BTC-OKExChain",
            "ctAddr": "",
            "ccy": "BTC",
            "to": "6",
            "addr": "0x66d0edc2e63b6b992381ee668fbcb01f20ae0428",
            "selected": true
        },
        {
            "chain": "BTC-ERC20",
            "ctAddr": "5807cf",
            "ccy": "BTC",
            "to": "6",
            "addr": "0x66d0edc2e63b6b992381ee668fbcb01f20ae0428",
            "selected": true
        }
    ],
    "msg": ""
}

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
chain String Chain name, e.g. USDT-ERC20, USDT-TRC20, USDT-Omni
to String The beneficiary account
1: SPOT 3: FUTURES 6: FUNDING 9: SWAP 12: OPTION 18: Unified account
selected Boolean Return true if current deposit address selected by website page
ctAddr String Last 6 digits of contract address

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
txId String No Hash record of the deposit
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",
      "chain":"BTC-Bitcoin",
      "from": "13801825426",
      "to": "",
      "ts": "1597026383085",
      "state": "2",
      "depId": "4703879"
    }
  ]
}

Response Parameters

Parameter Type Description
ccy String Currency
chain String Chain name
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 8: Pending due to temporary deposit suspension on this crypto currency
depId String Deposit ID

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",
    "chain":"BTC-Bitcoin",
    "toAddr":"17DKe3kkkkiiiiTvAKKi2vMPbm1Bz3CMKw"
}

Request Parameters

Parameter Type Required Description
ccy String Yes Currency, e.g. USDT
chain String OPTIONAL Chain name
There are multiple chains under some currencies, such as USDT has USDT-ERC20, USDT-TRC20, and USDT-Omni.
If this parameter is not filled in because it is not available, it will default to the main chain.
amt String Yes Withdrawal amount
dest String Yes Withdrawal destination address
3: OKEx
4: Digital currency address
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",
        "chain": "BTC-Bitcoin"
    }]
}

Response Parameters

Parameter Type Description
ccy String Currency
chain String Chain name, e.g. USDT-ERC20, USDT-TRC20, USDT-Omni
amt String Withdrawal amount
wdId String Withdrawal 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
txId String No Hash record of the deposit
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": [
    {
      "chain": "ETH-Ethereum",
      "fee": "0.007",
      "ccy": "ETH",
      "amt": "0.029809",
      "txId": "0x35c******b360a174d",
      "from": "156****359",
      "to": "0xa30d1fab********7CF18C7B6C579",
      "state": "2",
      "ts": "1622******2000",
      "wdId": "15447421"
    }
  ]
}

Response Parameters

Parameter Type Description
ccy String Currency
chain String Chain name, e.g. USDT-ERC20, USDT-TRC20, USDT-Omni
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

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

Get PiggyBank Balance

Rate Limit: 6 requests per second

HTTP Request

GET /api/v5/asset/piggy-balance

Request Example

GET /api/v5/asset/piggy-balance?ccy=USDT

Request Parameters

Parameters Types Required Description
ccy String No Currency, e.g. BTC

Example Response

{
    "code": "0",
    "msg":"",
    "data": [
        {
            "earnings": "0.0000000000000000",
            "ccy": "USDT",
            "amt": "1.0000000064666295"
        }
    ]
}

Response Parameters

Parameter Type Description
ccy String Currency
amt String Currency amount
earnings String Currency earnings

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: 10 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",
    "data": [
        {
            "adjEq": "10679688.0460531643092577",
            "details": [
                {
                    "availBal": "",
                    "availEq": "9930359.9998",
                    "cashBal": "9930359.9998",
                    "ccy": "USDT",
                    "crossLiab": "0",
                    "disEq": "9439737.0772999514",
                    "eq": "9930359.9998",
                    "eqUsd": "9933041.196999946",
                    "frozenBal": "0",
                    "interest": "0",
                    "isoEq": "0",
                    "isoLiab": "0",
                    "isoUpl":"0",
                    "liab": "0",
                    "maxLoan": "10000",
                    "mgnRatio": "",
                    "notionalLever": "",
                    "ordFrozen": "0",
                    "twap": "0",
                    "uTime": "1620722938250",
                    "upl": "0",
                    "uplLiab": "0",
                    "stgyEq":"0"
                },
                {
                    "availBal": "",
                    "availEq": "33.6799714158199414",
                    "cashBal": "33.2009985",
                    "ccy": "BTC",
                    "crossLiab": "0",
                    "disEq": "1239950.9687532129092577",
                    "eq": "33.771820625136023",
                    "eqUsd": "1239950.9687532129092577",
                    "frozenBal": "0.0918492093160816",
                    "interest": "0",
                    "isoEq": "0",
                    "isoLiab": "0",
                    "isoUpl":"0",
                    "liab": "0",
                    "maxLoan": "1453.92289531493594",
                    "mgnRatio": "",
                    "notionalLever": "",
                    "ordFrozen": "0",
                    "twap": "0",
                    "uTime": "1620722938250",
                    "upl": "0.570822125136023",
                    "uplLiab": "0",
                    "stgyEq":"0"
                }
            ],
            "imr": "3372.2942371050594217",
            "isoEq": "0",
            "mgnRatio": "70375.35408747017",
            "mmr": "134.8917694842024",
            "notionalUsd": "33722.9423710505978888",
            "ordFroz": "0",
            "totalEq": "11172992.1657531589092577",
            "uTime": "1623392334718"
        }
    ],
    "msg": ""
}
Response Parameters
Parameters Types Description
uTime String Update time of account information, millisecond format of Unix timestamp, e.g. 1597026383085
totalEq String Total equity in USD level
isoEq String Isolated margin equity in USD level
Applicable to Single-currency margin and Multi-currency margin
adjEq String Adjusted/Effective equity in USD level
Applicable to Multi-currency margin
ordFroz String Margin frozen for pending orders 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
notionalUsd String Quantity of positions usd
Applicable to Multi-currency margin
details Array Detailed asset information in all currencies
> ccy String Currency
> eq String Equity of the currency
> cashBal String Cash Balance
> uTime String Update time, Unix timestamp format in milliseconds, e.g. 1597026383085
> isoEq String Isolated margin equity of the currency
Applicable to Single-currency margin and Multi-currency margin
> availEq String Available equity of the currency
Applicable to Single-currency margin and Multi-currency margin
> disEq String discount equity of the currency in USD level. It is expected to go online on March 5
> availBal String Available balance of the currency
Applicable to Simple
> frozenBal String Frozen balance of the currency
> ordFrozen String Margin frozen for open orders
> liab String Liabilities of the currency
Applicable to Multi-currency margin
> upl String Unrealized profit and loss of the currency
Applicable to Single-currency margin and Multi-currency margin
> uplLib String Liabilities due to Unrealized loss of the currency
Applicable to Multi-currency margin
> crossLiab String Cross Liabilities of the currency
Applicable to Multi-currency margin
> isoLiab String Isolated Liabilities of the currency
Applicable to Multi-currency margin
> mgnRatio String Margin ratio of the currency
Applicable to Single-currency margin
> interest String Interest of the currency
Applicable to Multi-currency margin
> twap String System's forced repayment() indicator
Divided into 5 levels, from 1 to 5, the smaller the number, the weaker the TWAP intensity.
Applicable to Multi-currency margin
> maxLoan String Max loan of the currency
Applicable to Multi-currency margin
> eqUsd String Equity usd of the currency
> notionalLever String Leverage of the currency
Applicable to Single-currency margin
> stgyEq String strategy equity
> isoUpl String Isolated unrealized profit and loss of the currency
Applicable to Single-currency margin and Multi-currency margin

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

Parameters Simple Single-currency margin Multi-currency margin
uTime Yes Yes Yes
totalEq Yes Yes Yes
isoEq Yes Yes
adjEq Yes
ordFroz Yes
imr Yes
mmr Yes
mgnRatio Yes
notionalUsd Yes
details
> ccy Yes Yes Yes
> eq Yes Yes Yes
> cashBal Yes Yes Yes
> uTime Yes Yes Yes
> isoEq Yes Yes
> availEq Yes Yes
> disEq Yes Yes Yes
> availBal Yes
> frozenBal Yes Yes Yes
> ordFrozen Yes Yes Yes
> liab Yes
> upl Yes Yes
> uplLib Yes
> crossLiab Yes
> isoLiab Yes
> mgnRatio Yes
> interest Yes
> twap Yes
> maxLoan Yes
> eqUsd Yes Yes Yes
> notionalLever Yes
> stgyEq Yes Yes Yes
> isoUpl Yes 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: 10 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.Single instrument ID or multiple instrument IDs (no more than 10) separated with comma
posId String No Single position ID or multiple position IDs (no more than 20) separated with comma

Example Response

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "adl":"1",
      "availPos":"1",
      "avgPx":"2566.31",
      "cTime":"1619507758793",
      "ccy":"ETH",
      "deltaBS":"",
      "deltaPA":"",
      "gammaBS":"",
      "gammaPA":"",
      "imr":"",
      "instId":"ETH-USD-210430",
      "instType":"FUTURES",
      "interest":"0",
      "last":"2566.22",
      "lever":"10",
      "liab":"",
      "liabCcy":"",
      "liqPx":"2352.8496681818233",
      "margin":"0.0003896645377994",
      "mgnMode":"isolated",
      "mgnRatio":"11.731726509588816",
      "mmr":"0.0000311811092368",
      "notionalUsd":"2276.2546609009605",
      "optVal":"",
      "pTime":"1619507761462",
      "pos":"1",
      "posCcy":"",
      "posId":"307173036051017730",
      "posSide":"long",
      "thetaBS":"",
      "thetaPA":"",
      "tradeId":"109844",
      "uTime":"1619507761462",
      "upl":"-0.0000009932766034",
      "uplRatio":"-0.0025490556801078",
      "vegaBS":"",
      "vegaPA":""
    }
  ]
}
Response 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 OPTION
imr String Initial margin requirement, only applicable to cross.
margin String Margin, can be added or reduced. Only applicable to isolated.
mgnRatio String Margin ratio
mmr String Maintenance margin requirement
liab String Liabilities, only applicable to MARGIN.
liabCcy String Liabilities currency, only applicable to MARGIN.
interest String Interest. Interest that has been incurred.
tradeId String Last trade ID
optVal String Option Value, only applicable to OPTION.
notionalUsd String Quantity of positions usd
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
deltaBS String delta:Black-Scholes Greeks in dollars,only applicable to OPTION
deltaPA String delta:Greeks in coins,only applicable to OPTION
gammaBS String gamma:Black-Scholes Greeks in dollars,only applicable to OPTION
gammaPA String gamma:Greeks in coins,only applicable to OPTION
thetaBS String theta:Black-Scholes Greeks in dollars,only applicable to OPTION
thetaPA String theta:Greeks in coins,only applicable to OPTION
vegaBS String vega:Black-Scholes Greeks in dollars,only applicable to OPTION `
vegaPA String vega:Greeks in coins,only applicable to OPTION
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 account and position risk

Get account and position risk

Rate Limit: 10 requests per 2 seconds

HTTP Requests

GET /api/v5/account/account-position-risk

Request Example

GET /api/v5/account/account-position-risk

Request Parameters
Parameter Type Required Description
instType String No Instrument type
MARGIN
SWAP
FUTURES
OPTION

Example Response

{
    "code":"0",
    "data":[
        {
            "adjEq":"174238.6793649711331679",
            "balData":[
                {
                    "ccy":"BTC",
                    "disEq":"78846.7803721021362242",
                    "eq":"1.3863533369419636"
                },
                {
                    "ccy":"USDT",
                    "disEq":"73417.2495112863300127",
                    "eq":"73323.395564963177146"
                }
            ],
            "posData":[
                {
                    "ccy":"USDT",
                    "instId":"BTC-USDT-210507",
                    "instType":"FUTURES",
                    "mgnMode":"cross",
                    "notionalCcy":"0.98",
                    "notionalUsd":"55806.8814912",
                    "pos":"98",
                    "posCcy":"",
                    "posId":"310423695953113090",
                    "posSide":"net"
                }
            ],
            "ts":"1620282889345"
        }
    ],
    "msg":""
}
Response Parameters
Parameters Types Description
ts String Update time of account information, millisecond format of Unix timestamp, e.g. 1597026383085
adjEq String Adjusted/Effective equity in USD level
Applicable to Multi-currency margin
balData Array Detailed asset information in all currencies
> ccy String Currency
> eq String Equity of the currency
> disEq String discount equity of the currency in USD level. It is expected to go online on March 5
posData Array Detailed position information in all currencies
> instType String Instrument type
> mgnMode String Margin mode
cross
isolated
> posId String Position ID
> instId String Instrument ID, e.g. BTC-USD-180216
> pos String Quantity of positions contract
> 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.)
> posCcy String Position currency, only applicable to MARGIN positions.
> ccy String Currency used for margin
> notionalCcy String Quantity of positions coin
> notionalUsd String Quantity of positions usd

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: Auto token conversion 5: Liquidation 6: Margin transfer 7: Interest deduction 8: Funding fee 9: ADL 10: Clawback 11: System token conversion 12: Strategy transfer
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: Auto buy 111: Auto sell 118: System token conversion transfer in 119: System token conversion transfer out 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 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 174: Funding fee income 200:System transfer in 201: Manually transfer in 202: System transfer out 203: Manually transfer out
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": [{
            "bal": "0.0000819307998198",
            "balChg": "-664.2679586599999802",
            "billId": "310394313544966151",
            "ccy": "USDT",
            "fee": "0",
            "from": "",
            "instId": "LTC-USDT",
            "instType": "SPOT",
            "mgnMode": "cross",
            "notes": "",
            "ordId": "310394313519800320",
            "pnl": "0",
            "posBal": "0",
            "posBalChg": "0",
            "subType": "2",
            "sz": "664.26795866",
            "to": "",
            "ts": "1620275771196",
            "type": "2"
        }
    ]
}

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: Unified account
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: Unified account
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: Auto token conversion 5: Liquidation 6: Margin transfer 7: Interest deduction 8: Funding fee 9: ADL 10: Clawback 11: System token conversion 12: Strategy transfer
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: Auto buy 111: Auto sell 118: System token conversion transfer in 119: System token conversion transfer out 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 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 174: Funding fee income 200:System transfer in 201: Manually transfer in 202: System transfer out 203: Manually transfer out
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": [{
            "bal": "0.0000819307998198",
            "balChg": "-664.2679586599999802",
            "billId": "310394313544966151",
            "ccy": "USDT",
            "fee": "0",
            "from": "",
            "instId": "LTC-USDT",
            "instType": "SPOT",
            "mgnMode": "cross",
            "notes": "",
            "ordId": "310394313519800320",
            "pnl": "0",
            "posBal": "0",
            "posBalChg": "0",
            "subType": "2",
            "sz": "664.26795866",
            "to": "",
            "ts": "1620275771196",
            "type": "2"
        }
    ]
}

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: Unified account
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: Unified account
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": "",
  "data": [
    {
      "uid": "43812",
      "acctLv": "2",
      "posMode": "long_short_mode",
      "autoLoan": true,
      "level": "lv1",
      "levelTmp": "",
      "greeksType": "BS"
    }
  ]
}

Response Parameters

Parameter Type Description
uid String Account ID
acctLv String Account level
1: Simple 2: Single-currency margin 3: Multi-currency margin
posMode String Position mode
long_short_mode: long/short, only applicable to FUTURES/SWAP
net_mode: net
autoLoan Boolean Whether to borrow coins automatically
true: borrow coins automatically false: not borrow coins automatically
greeksType String Current display type of Greeks
PA: Greeks in coins BS: Black-Scholes Greeks in dollars
level String The user level of the current real trading volume on the platform, e.g lv1
levelTmp String Temporary experience user level of special users, e.g lv3

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
body 
{
    "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: 20 requests per 2 seconds

HTTP Request

POST /api/v5/account/set-leverage

Request Example

set leverage for isolated `MARGIN` at pairs level
POST /api/v5/account/set-leverage
body
{
    "instId":"BTC-USDT",
    "lever":"5",
    "mgnMode":"isolated"
}

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

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

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

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

Request Parameters

Parameter Type Required Description
instId String Optional Instrument ID
Either instId or ccy is required; if both are passed, instId will be used by default.
ccy String Optional Currency used for margin
Only applicable to cross MARGIN of Multi-currency margin
lever String Yes Leverage
mgnMode String Yes Margin mode
isolated cross
Only can be cross if ccy is passed.
posSide String Optional Position side
long short net
Required in long/short mode and when margin mode is isolated, only long or short can be passed.
Only net can be passed in other cases.
Only applicable to FUTURES/SWAP

Example Response

{
  "code": "0",
  "msg": "",
  "data": [
    {
      "lever": "30",
      "mgnMode": "isolated",
      "instId": "BTC-USDT-SWAP",
      "posSide": "long"
    }
  ]
}

Response Parameters

Parameter Type Description
lever String Leverage
mgnMode String Margin mode
cross isolated
instId String Instrument ID
posSide String Position side

Get maximum buy/sell amount or open amount

Rate Limit: 20 requests per 2 seconds

HTTP Request

GET /api/v5/account/max-size

Request Example

GET /api/v5/account/max-size?instId=BTC-USDT&tdMode=isolated

Request Parameters

Parameter Type Required Description
instId String Yes Single instrument or multiple instruments (no more than 5) separated with comma, e.g. BTC-USDT-200802,ETH-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 specified, it will be calculated according to the last traded price.
The parameter will be ignored when multiple instruments are specified.

Example Response

{
    "code": "0",
    "msg": "",
    "data": [{
        "ccy": "BTC",
        "instId": "BTC-USDT",
        "maxBuy": "0.0500695098559788",
        "maxSell": "64.4798671570072269"
  }]
}

Response Parameters

Parameter Type Description
instId String Instrument ID
ccy String Currency used for margin
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
Single instrument ID or multiple instrument IDs (no more than 20) separated with comma
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
In long/short mode, the leverage in both directions long short will be returned.
lever String Leverage

Get the maximum loan of instrument

Rate Limit: 20 requests per 2 seconds

HTTP Request

GET /api/v5/account/max-loan

Request Example

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

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

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

Request Parameters

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

Example Response

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

Response Parameters

Parameter Type Description
instId String Instrument ID
mgnMode String Margin mode
mgnCcy String Margin currency
maxLoan String Max loan
ccy String Currency
side String Order side
buy sell

Get Fee Rates

Rate Limit: 5 requests per 2 seconds

HTTP Request

GET /api/v5/account/trade-fee

Request Example

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

Query trade fee rate in Class A
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 SPOT/MARGIN
uly String Optional Underlying, e.g. BTC-USD
only applicable to FUTURES/SWAP/OPTION
category String Optional Fee Schedule
1: Class A
2: Class B
3: Class C
4: Class D

Example Response

{
    "code": "0",
    "msg": "",
    "data": [{
            "category": "1",
            "delivery": "",
            "exercise": "",
            "instType": "SPOT",
            "level": "lv1",
            "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",
            "interestRate": "0.00001",
            "liab": "2",
            "interest": "0.02",
            "ts": "1597026383085"
        },
        {
            "instId": "BTC-USDT",
            "ccy": "USDT",
            "mgnMode": "cross",
            "interestRate": "0.00001",
            "liab": "2",
            "interest": "0.02",
            "ts": "1597026383085"
        }
    ]
}

Response Parameters

Parameter Type Description
instId String Instrument ID
ccy String Currency
mgnMode String Margin mode
interest String Interest
interestRate String Interest Rate
liab String Liabilities amount
ts String Interest calculation time, Unix timestamp format in milliseconds, e.g. 1597026383085

Get interest rate

Get the user's current leveraged currency borrowing interest rate

Rate Limit: 5 requests per 2 seconds

HTTP Requests

GET /api/v5/account/interest-rate

Request Example

GET /api/v5/account/interest-rate
Request Parameters
Parameters Types Required Description
ccy String No Single currency or multiple currencies
{
    "code":"0",
    "msg":"",
    "data":[
        {
            "ccy":"BTC",
            "interestRate":"0.0001"
        },
        {
            "ccy":"LTC",
            "interestRate":"0.0003"
        }
    ]
}

Response Parameters

Parameter Type Description
interestRate String interest rate
ccy String currency

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

SubAccount

The API endpoints of SubAccount require authentication.

View sub-account list

applies to master accounts only

Rate limit:2 requests per 2 seconds

HTTP request

GET /api/v5/users/subaccount/list

Request sample

GET /api/v5/users/subaccount/list

Request parameters

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

Returned results

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

    ]
}

Response parameters

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

Create an APIKey for a sub-account

applies to master accounts only

Rate limit:1 request per second

HTTP request

POST /api/v5/users/subaccount/apikey

Request sample

POST /api/v5/users/subaccount/apikey

Request parameters

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

Returned result

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

Response parameters

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

Query the APIKey of a sub-account

applies to master accounts only

Rate limit:1 request per second

HTTP request

get /api/v5/users/subaccount/apikey

Request sample

get /api/v5/users/subaccount/apikey

Request parameters

Parameter name Type If required Description
subAcct String Yes Sub-account name
apiKey String Yes API public key

Returned results

    "code":"0",
    "msg":"",
    "data":[
        {
            "label":"v5",
            "apiKey":"arg13sdfgs",
            "perm":"read_only,trade",
            "ip":"1.1.1.1,2.2.2.2",
            "ts":"1597026383085"
        },
        {
            "label":"v5.1",
            "apiKey":"arg13sdfgs",
            "perm":"read_only",
            "ip":"1.1.1.1,2.2.2.2",
            "ts":"1597026383085"
        }
    ]
}

Response parameters

Parameter name Type Description
label String APIKey note
apiKey String API public key
perm String APIKey access read_only:Read only ;trade :Trade
ip String IP address that linked with APIKey
ts String Creation time

Reset the APIKey of a sub-account

applies to master accounts only

Rate limit:1 request per second

HTTP request

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

Request sample

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

Request parameters

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

Returned results

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

Response parameters

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

Delete the APIKey of sub-accounts

applies to master accounts only

Rate limit:1 request per second

HTTP request

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

Request sample

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

Request parameters

Parameter name Type If required Description
pwd String Yes Funds password of the master account
subAcct String Yes Sub-account name
apiKey String Yes API public key

Returned results

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

Response parameters

Parameter name Type Description
subAcct String Sub-account name

Get Sub-account Balance

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

Rate limit:2 requests per 2 seconds

HTTP request

GET /api/v5/account/subaccount/balances

Request sample

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

Request parameters

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

Returned result

{
    "code": "0",
    "data": [
        {
            "adjEq": "10679688.0460531643092577",
            "details": [
                {
                    "availBal": "",
                    "availEq": "9930359.9998",
                    "cashBal": "9930359.9998",
                    "ccy": "USDT",
                    "crossLiab": "0",
                    "disEq": "9439737.0772999514",
                    "eq": "9930359.9998",
                    "eqUsd": "9933041.196999946",
                    "frozenBal": "0",
                    "interest": "0",
                    "isoEq": "0",
                    "isoLiab": "0",
                    "liab": "0",
                    "maxLoan": "10000",
                    "mgnRatio": "",
                    "notionalLever": "",
                    "ordFrozen": "0",
                    "twap": "0",
                    "uTime": "1620722938250",
                    "upl": "0",
                    "uplLiab": "0"
                },
                {
                    "availBal": "",
                    "availEq": "33.6799714158199414",
                    "cashBal": "33.2009985",
                    "ccy": "BTC",
                    "crossLiab": "0",
                    "disEq": "1239950.9687532129092577",
                    "eq": "33.771820625136023",
                    "eqUsd": "1239950.9687532129092577",
                    "frozenBal": "0.0918492093160816",
                    "interest": "0",
                    "isoEq": "0",
                    "isoLiab": "0",
                    "liab": "0",
                    "maxLoan": "1453.92289531493594",
                    "mgnRatio": "",
                    "notionalLever": "",
                    "ordFrozen": "0",
                    "twap": "0",
                    "uTime": "1620722938250",
                    "upl": "0.570822125136023",
                    "uplLiab": "0"
                }
            ],
            "imr": "3372.2942371050594217",
            "isoEq": "0",
            "mgnRatio": "70375.35408747017",
            "mmr": "134.8917694842024",
            "notionalUsd": "33722.9423710505978888",
            "ordFroz": "0",
            "totalEq": "11172992.1657531589092577",
            "uTime": "1623392334718"
        }
    ],
    "msg": ""
}

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
ordFroz String Margin frozen for pending orders 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
notionalUsd String Quantity of positions usd
Applicable to Multi-currency margin
details Array Detailed asset information in all currencies
> ccy String Currency
> eq String Equity of the currency
> cashBal String Cash Balance
> uTime String Update time, Unix timestamp format in milliseconds, e.g. 1597026383085
> isoEq String Isolated margin equity of the currency
Applicable to Single-currency margin and Multi-currency margin
> availEq String Available equity of the currency
Applicable to Single-currency margin and Multi-currency margin
> disEq String discount equity of the currency in USD level
> availBal String Available balance of the currency
Applicable to Simple
> frozenBal String Frozen balance of the currency
> ordFrozen String Margin frozen for open orders
> liab String Liabilities of the currency
Applicable to Multi-currency margin
> upl String Unrealized profit and loss of the currency
Applicable to Single-currency margin and Multi-currency margin
> uplLib String Liabilities due to Unrealized loss of the currency
Applicable to Multi-currency margin
> crossLiab String Cross Liabilities of the currency
Applicable to Multi-currency margin
> isoLiab String Isolated Liabilities of the currency
Applicable to Multi-currency margin
> mgnRatio String Margin ratio of the currency
Applicable to Single-currency margin
> interest String Interest of the currency
Applicable to Multi-currency margin
> twap String System's forced repayment(TWAP) indicator
Divided into 5 levels, from 1 to 5, the smaller the number, the weaker the TWAP intensity.
Applicable to Multi-currency margin
> maxLoan String Max loan of the currency
Applicable to Multi-currency margin
> eqUsd String Equity usd of the currency
> notionalLever String Leverage of the currency
Applicable to Single-currency margin

History of sub-account transfer

applies to master accounts only

Rate limit:6 requests per second

HTTP request

GET /api/v5/asset/subaccount/bills

Request sample

GET /api/v5/asset/subaccount/bills

Request parameters

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

Returned results

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

Response parameters

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

Master accounts manage the transfers between sub-accounts

applies to master accounts only

Rate limit:1 request per second

HTTP request

POST /api/v5/asset/subaccount/transfer

Request sample

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

Request parameters

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

Returned results

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

Response parameters

Parameter name Type Description
transId String Transfer ID

Market Data

The API endpoints of Market Data do not require authentication.

Get Tickers

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

Rate Limit: 20 requests per 2 seconds

HTTP Request

GET /api/v5/market/tickers

Request Example

GET /api/v5/market/tickers?instType=SWAP

Request Parameters

Parameter Type Required Description
instType String Yes Instrument type
SPOT
SWAP
FUTURES
OPTION
uly String No Underlying, e.g. BTC-USD
Only applicable toFUTURES/SWAP/OPTION

Example Response

{
    "code":"0",
    "msg":"",
    "data":[
     {
        "instType":"SWAP",
        "instId":"LTC-USD-SWAP",
        "last":"9999.99",
        "lastSz":"0.1",
        "askPx":"9999.99",
        "askSz":"11",
        "bidPx":"8888.88",
        "bidSz":"5",
        "open24h":"9000",
        "high24h":"10000",
        "low24h":"8888.88",
        "volCcy24h":"2222",
        "vol24h":"2222",
        "sodUtc0":"0.1",
        "sodUtc8":"0.1",
        "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":"0.1",
        "sodUtc8":"0.1",
        "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 24h trading volume, with a unit of currency.
If it is a derivatives contract, the value is the number of settlement currency.
If it is SPOT/MARGIN, the value is the number of quote currency.
vol24h String 24h trading volume, with a unit of contact.
If it is a derivatives contract, the value is the number of contracts.
If it is SPOT/MARGIN, the value is the amount of trading currency.
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 24h trading volume, with a unit of currency.
If it is a derivatives contract, the value is the number of settlement currency.
If it is SPOT/MARGIN, the value is the number of quote currency.
vol24h String 24h trading volume, with a unit of contact.
If it is a derivatives contract, the value is the number of contracts.
If it is SPOT/MARGIN, the value is the amount of trading currency.
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 is 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-USDT

Request Parameters

Parameter Type Required Description
instId String Yes Instrument ID, e.g. BTC-USDT
sz String No Order book depth per side. Maximum 400, e.g. 400 bids + 400 asks
Default returns to 1 depth data

Example Response

{
    "code": "0",
    "msg": "",
    "data": [
        {
            "asks": [
                [
                    "41006.8",
                    "0.60038921",
                    "0",
                    "1"
                ]
            ],
            "bids": [
                [
                    "41006.3",
                    "0.30178218",
                    "0",
                    "2"
                ]
            ],
            "ts": "1629966436396"
        }
    ]
}

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 highest price
l String Lowest price
c String Close price
vol String Trading volume, with a unit of contact.
If it is a derivatives contract, the value is the number of contracts.
If it is SPOT/MARGIN, the value is the amount of trading currency.
volCcy String Trading volume, with a unit of currency.
If it is a derivatives contract, the value is the number of settlement currency.
If it is SPOT/MARGIN, the value is the number of quote currency.

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, with a unit of contact.
If it is a derivatives contract, the value is the number of contracts.
If it is SPOT/MARGIN, the value is the amount of trading currency.
volCcy String Trading volume, with a unit of currency.
If it is a derivatives contract, the value is the number of settlement currency.
If it is SPOT/MARGIN, the value is the number of quote currency.

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 highest 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 highest 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-USDT
limit String No Number of results per request. The maximum is 500; 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.

Get 24H Total Volume

The 24-hour trading volume is calculated on a rolling basis, using USD as the pricing unit.

Rate Limit: 2 requests per 2 seconds

Rate limit rule: IP

HTTP Request

GET /api/v5/market/platform-24-volume

Request Example

GET /api/v5/market/platform-24-volume

Example Response

{
    "code":"0",
    "msg":"",
    "data":[
     {
        "volUsd":"2222",
        "volCny":"14220.8",
     }
  ]
}

Response Parameters

Parameter Type Description
volUsd String 24-hour total trading volume on the platform ,"USD"
volCny String 24-hour total trading volume on the platform ,"CNY"
ts String Data return time, Unix timestamp format in milliseconds, e.g. 1597026383085

Get Oracle

Get the crypto price of signing using Open Oracle smart contract.

Rate Limit: 1 requests per 5 seconds

HTTP Request

GET /api/v5/market/open-oracle

Request Example

GET /api/v5/market/open-oracle

Example Response

{
    "code":"0",
    "msg":"",
    "data":{
        "messages":[
            "0x00000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000060d98cc000000000000000000000000000000000000000000000000000000000000000c0000000000000000000000000000000000000000000000000000000081a06ed800000000000000000000000000000000000000000000000000000000000000006707269636573000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000034254430000000000000000000000000000000000000000000000000000000000"
        ],
        "prices":{
            "BTC":"34796.4"
        },
        "signatures":[
            "0xa8124d0dd7a6cd46aafc752272d2e67b09f0abb0f759c55712cf0c100e5ed6ad25853d97fd691c47539eac08d7e7b0ce3f6d1e8f6fa15850d8099718d37af376000000000000000000000000000000000000000000000000000000000000001c"
        ],
        "timestamp":"1624870080"
    }
}

Response Parameters

Parameter Type Description
messages String abi-encoded values [kind, timestamp, key, value], where kind equals 'prices', timestamp is the time when price was obtained, key is the asset ticker (e.g. btc) and value is the asset price.
price String readable asset prices
signatures String Ethereum-compatible ECDSA signatures for each message
timestamp String time of latest datapoint

Get index components

Get the index component information data on the market

Rate Limit: 20 requests per 2 seconds

HTTP Request

GET /api/v5/market/index-components

Request Example

GET /api/v5/market/index-components?index=BTC-USD

Request Parameters

Parameter Type Required Description
index String Yes index,e.g BTC-USDT

Example Response

{
    "code": "0",
    "msg": "",
    "data": {
        "components": [
            {
                "symbol": "BTC/USDT",
                "symPx": "52733.2",
                "wgt": "0.250",
                "cnvPx": "52733.2",
                "exch": "OKEx"
            },
            {
                "symbol": "BTC/USDT",
                "symPx": "52739.87000000",
                "wgt": "0.250",
                "cnvPx": "52739.87000000",
                "exch": "Binance"
            },
            {
                "symbol": "BTC/USDT",
                "symPx": "52729.1",
                "wgt": "0.250",
                "cnvPx": "52729.1",
                "exch": "Huobi"
            },
            {
                "symbol": "BTC/USDT",
                "symPx": "52739.47929397",
                "wgt": "0.250",
                "cnvPx": "52739.47929397",
                "exch": "Poloniex"
            }
        ],
        "last": "52735.4123234925",
        "index": "BTC-USDT",
        "ts": "1630985335599"
    }
}

Response Parameters

Parameter Type Description
index String Index
last String Latest Index Price
ts String Data generation time, Unix timestamp format in milliseconds, e.g. 1597026383085
exch String Name of Exchange
symbol String Name of Exchange Trading Pairs
symPx String Price of Exchange Trading Pairs
wgt String Weights
cnvPx String Convert to Price

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
MARGIN
SWAP
FUTURES
OPTION
uly String Optional Underlying
Only applicable to FUTURES/SWAP/OPTION. Required for OPTION.
instId String No Instrument ID

Example Response

{
    "code":"0",
    "msg":"",
    "data":[
    {
        "instType":"SWAP",
        "instId":"LTC-USD-SWAP",
        "uly":"LTC-USD",
        "category":"1",
        "baseCcy":"",
        "quoteCcy":"",
        "settleCcy":"LTC",
        "ctVal":"10",
        "ctMult":"1",
        "ctValCcy":"USD",
        "optType":"C",
        "stk":"",
        "listTime":"1597026383085",
        "expTime":"1597026383085",
        "lever":"10",
        "tickSz":"0.01",
        "lotSz":"1",
        "minSz":"1",
        "ctType":"linear",
        "alias":"this_week",
        "state":"live"
    }
  ]
}

Response Parameters

Parameter Type Description
instType String Instrument type
instId String Instrument ID, e.g. BTC-USD-SWAP
uly String Underlying, e.g. BTC-USD
Only applicable to FUTURES/SWAP/OPTION
category String Fee schedule
baseCcy String Base currency, e.g. BTC inBTC-USDT
Only applicable to SPOT
quoteCcy String Quote currency, e.g. USDT in BTC-USDT
Only applicable to SPOT
settleCcy String Settlement and margin currency, e.g. BTC
Only applicable to FUTURES/SWAP/OPTION
ctVal String Contract value
Only applicable to FUTURES/SWAP/OPTION
ctMult String Contract multiplier
Only applicable to FUTURES/SWAP/OPTION
ctValCcy String Contract value currency
Only applicable to FUTURES/SWAP/OPTION
optType String Option type, C: Call P: put
Only applicable to OPTION
stk String Strike price
Only applicable to OPTION
listTime String Listing time, Unix timestamp format in milliseconds, e.g. 1597026383085
expTime String Expiry time, Unix timestamp format in milliseconds, e.g. 1597026383085
Only applicable to FUTURES/OPTION
lever String Max Leverage,
Not applicable to SPOT、OPTION
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",
                    "instId":"BTC-USD-190927",
                    "px":"0.016"
                }
            ]
        },
        {
            "ts":"1597026383085",
            "details":[
                {
                    "instId":"BTC-USD-200529-6000-C",
                    "type":"exercised",
                    "px":"0.016"
                },
                {
                    "instId":"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
> instId 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
instId String Instrument ID
oi String Open interest (cont)
oiCcy String Open interest (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",
    "data": [
        {
            "fundingRate": "0.0001515",
            "fundingTime": "1622822400000",
            "instId": "BTC-USD-SWAP",
            "instType": "SWAP",
            "nextFundingRate": "0.00029",
            "nextFundingTime": "1622851200000"
        }
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
instType String Instrument type SWAP
instId 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
nextFundingTime String Forecast funding time for the next period , 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 fundingTime
before String No Pagination of data to return records earlier than the requested fundingTime
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
instId 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-USDT-SWAP

Request Parameters

Parameter Type Required Description
instId String Yes Instrument ID, e.g. BTC-USDT-SWAP
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
instId String Instrument ID, e.g. BTC-USDT-SWAP
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
instId String Instrument ID, e.g. BTC-USD-200103-5500-C
uly String Underlying
delta String Sensitivity of option price to uly price
gamma String The delta's sensitivity to uly price
vega String Sensitivity of option price to implied volatility
theta String Sensitivity of option price to remaining maturity
deltaBS String Sensitivity of option price to uly price in BS mode
gammaBS String The delta's sensitivity to uly price in BS mode
vegaBS String Sensitivity of option price to implied volatility in BS mode
thetaBS String Sensitivity of option price to remaining maturity in BS mode
lever String Leverage
markVol String Mark volatility
bidVol String Bid volatility
askVol String Ask volatility
realVol String Realized volatility (not currently used)
ts String Data return time, Unix timestamp format in milliseconds, e.g. 1597026383085

Get Estimated Delivery/Excercise Price

Retrieve the estimated delivery price which will only have a return value one hour before the delivery/exercise.

Rate Limit: 10 requests per 2 seconds

HTTP Request

GET /api/v5/public/estimated-price

Request Example

GET /api/v5/public/estimated-price?instId=BTC-USDT-191227

Request Parameters

Parameter Type Required Description
instId String Yes Instrument ID, e.g. BTC-USD-200214
only applicable to FUTURES/OPTION

Example Response

{
    "code":"0",
    "msg":"",
    "data":[
    {
        "instType":"SWAP",
        "instId":"BTC-USDT-201227",
        "settlePx":"200",
        "ts":"1597026383085"
    }
  ]
}

Response Parameters

Parameter Type Description
instType String Instrument type
FUTURES
OPTION
instId String Instrument ID, e.g. BTC-USD-180216
settlePx String Estimated delivery price
ts String Data return time, Unix timestamp format in milliseconds, e.g. 1597026383085

Get Discount Rate And Interest-Free Quota

Retrieve discount rate level and interest-free quota.

Rate Limit: 2 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
discountLv String No Discount level
1:level 1
2:level 2
3:level 3
4:level 4
5:level 5

Example Response

{
  "code": "0",
  "msg": "",
  "data": [
    {
            "amt": "1",
            "ccy": "LTC",
            "discountInfo": [
                {
                    "discountRate": "0.95",
                    "maxAmt": "2000000",
                    "minAmt": "0"
                },
                {
                    "discountRate": "0.85",
                    "maxAmt": "4000000",
                    "minAmt": "2000000"
                },
                {
                    "discountRate": "0.5",
                    "maxAmt": "8000000",
                    "minAmt": "4000000"
                },
                {
                    "discountRate": "0",
                    "maxAmt": "",
                    "minAmt": "8000000"
                }
            ],
            "discountLv": "2"
        }
  ]
}

Response Parameters

Parameter Type Description
ccy String Currency
amt String Interest-free quota
discountLv String Discount rate level
Discount rate level intruduction
discountInfo Array Discount details
> discountRate String Discount rate
> maxAmt String Tier -upper bound
> minAmt String Tier -lower bound

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

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 No State
unfilled
filled
unfilled by default
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",
    "data": [
        {
            "details": [
                {
                    "bkLoss": "0",
                    "bkPx": "",
                    "ccy": "USDT",
                    "posSide": "",
                    "side": "",
                    "sz": "989.9123170781309932",
                    "ts": "1629962347000"
                },
                {
                    "bkLoss": "0",
                    "bkPx": "",
                    "ccy": "USDT",
                    "posSide": "",
                    "side": "",
                    "sz": "10.1066764750370217",
                    "ts": "1629961447000"
                }
            ],
            "instId": "BTC-USDT",
            "instType": "MARGIN",
            "totalLoss": "0",
            "uly": ""
        }
    ],
    "msg": ""
}

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
instId 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

Get Position Tiers

Position information,Maximum leverage depends on your borrowings and margin ratio.

Rate Limit: 10 requests per 2 seconds

HTTP Request

GET /api/v5/public/position-tiers

Request Example

GET /api/v5/public/position-tiers

Request Parameters

Parameter Type Required Description
instType String YES Instrument type
MARGIN
SWAP
FUTURES
OPTION
uly String Optional Underlying
Required and only applicable to MARGIN,SWAP,FUTURES,OPTION
instId String Optional Instrument ID, e.g. BTC-USD-190927-5000-C
Required and only applicable to MARGIN
tdMode String YES Trade mode
Margin mode cross isolated
tier String NO Tiers

Example Response

{
    "code":"0",
    "msg":"",
    "data":[
    {
            "baseMaxLoan": "50",
            "imr": "0.1",
            "instId": "BTC-USDT",
            "maxLever": "10",
            "maxSz": "50",
            "minSz": "0",
            "mmr": "0.03",
            "optMgnFactor": "0",
            "quoteMaxLoan": "500000",
            "tier": "1",
            "uly": ""
        }
  ]
}

Response Parameters

Parameter Type Description
uly String Underlying
instId String Instrument ID
tier String Tiers
minSz String The minimum position of this gear is only applicable to options/perpetual/delivery, the minimum position is 0 by default
maxSz String The maximum number of positions held in this position is only applicable to options/perpetual/delivery
mmr String Maintenance margin requirement in USD level
imr String Initial margin requirement in USD level
maxLever String Maximum available leverage
optMgnFactor String Option Margin Coefficient (only applicable to options)
quoteMaxLoan String Quote currency borrowing amount (only applicable to leverage)
baseMaxLoan String Base currency borrowing amount (only applicable to leverage)

Get Interest Rate and Loan Quota

Get margin interest rate

Rate Limit: 2 requests per 2 seconds

HTTP Request

GET /api/v5/public/interest-rate-loan-quota

Request Example

GET /api/v5/public/interest-rate-loan-quota

Example Response

{
    "code": "0",
    "data": [
        {
            "basic": [
                {
                    "ccy": "USDT",
                    "quota": "300000",
                    "rate": "0.00024984"
                }
            ],
            "vip": [
                {
                    "irDiscount": "0.7",
                    "loanQuotaCoef": 6,
                    "level": "VIP1"
                },
                {
                    "irDiscount": "0.65",
                    "loanQuotaCoef": 7,
                    "level": "VIP2"
                }
            ],
            "regular": [
                {
                    "irDiscount": "1",
                    "loanQuotaCoef": 1,
                    "level": "Lv1"
                },
                {
                    "irDiscount": "0.95",
                    "loanQuotaCoef": 2,
                    "level": "Lv2"
                }
            ]
        }
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
basic Array basic
> ccy String currency
> rate String Daily rate
> quota String Max borrow
vip Array vip users
> level String level
> loanQuotaCoef String loan quota coef
> irDiscount String interest rate discount
regular Array regular users
> level String level
> loanQuotaCoef String loan quota coef
> irDiscount String interest rate discount

Get Underlying

Rate Limit: 20 requests per 2 seconds

HTTP Request

GET /api/v5/public/underlying

Request Example

GET /api/v5/public/underlying?instType=FUTURES

Request Parameters

Parameter Type Required Description
instType String Yes Instrument type
SWAP
FUTURES
OPTION

Example Response

{
    "code":"0",
    "msg":"",
    "data":[
        [
            "LTC-USDT",
            "BTC-USDT",
            "ETC-USDT"
        ]
    ]
}

Response Parameters

Parameter Type Description
uly array Underlying

Trading Data

The API endpoints of Trading Data do not require authentication.

Get support coin

Get the currency supported by the transaction big data interface

Rate Limit: 5 requests per 2 seconds

Rate limit rule: IP

HTTP Request

GET /api/v5/rubik/stat/trading-data/support-coin

Request Example

GET /api/v5/rubik/stat/trading-data/support-coin

Example Response

{
    "code": "0",
    "data": {
        "contract": [
            "ADA",
            "BTC",
        ],
        "option": [
            "BTC"
        ],
        "spot": [
            "ADA",
            "BTC",
        ]
    },
    "msg": ""
}

Response Parameters

Parameter Type Description
contract String Currency supported by derivatives trading data
option String Currency supported by option trading data
spot String Currency supported by spot trading data

Get taker volume

This is the taker volume for both buyers and sellers. This shows the influx and exit of funds in and out of {coin}.

Rate Limit: 5 requests per 2 seconds

Rate limit rule: IP

HTTP Request

GET /api/v5/rubik/stat/taker-volume

Request Example

GET /api/v5/rubik/stat/taker-volume?ccy=BTC&instType=SPOT

Request Parameters

Parameter Type Required Description
ccy String Yes currency
instType String Yes Instrument type,"SPOT" , "CONTRACTS"
begin String No begin,e.g:1597026383085
end String N0 end,e.g:1597026383011
period String No period,the default is 5m. e.g:[5m/1H/1D]
5m granularity can only query data within two days at most
1H granularity can only query data within 30 days at most
1D granularity can only query data within 180 days at most

Example Response

{
    "code": "0",
    "data": [
        [
            "1630425600000",
            "7596.2651",
            "7149.4855"
        ],
        [
            "1630339200000",
            "5312.7876",
            "7002.7541"
        ]
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
ts String Timestamp
sellVol String Sell volume
buyVol String Buy volume

Get Margin lending ratio

This indicator shows the ratio of cumulative data value between currency pair leverage quote currency and underlying asset over a given period of time.

Rate Limit: 5 requests per 2 seconds

Rate limit rule: IP

HTTP Request

GET /api/v5/rubik/stat/margin/loan-ratio

Request Example

GET /api/v5/rubik/stat/margin/loan-ratio?ccy=BTC

Request Parameters

Parameter Type Required Description
ccy String Yes currency
begin String No begin,e.g:1597026383085
end String No end,e.g:1597026383085
period String No period,the default is 5m. e.g:[5m/1H/1D]
5mgranularity can only query data within two days at most
1H granularity can only query data within 30 days at most
1D granularity can only query data within 180 days at most

Example Response

{
    "code": "0",
    "data": [
        [
            "1630492800000",
            "0.4614"
        ],
        [
            "1630492500000",
            "0.5767"
        ]
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
ts String Timestamp
ratio String Margin lending ratio

Get Long/Short ratio

This is the ratio of users with net long vs short positions. It includes data from futures and perpetual swaps.

Rate Limit: 5 requests per 2 seconds

Rate limit rule: IP

HTTP Request

GET /api/v5/rubik/stat/contracts/long-short-account-ratio

Request Example

GET /api/v5/rubik/stat/contracts/long-short-account-ratio?ccy=BTC

Request Parameters

Parameter Type Required Description
ccy String Yes currency
begin String No begin,e.g:1597026383085
end String No end,e.g:1597026383011
period String No period,the default is 5m. e.g:[5m/1H/1D]
5m granularity can only query data within two days at most
1H granularity can only query data within 30 days at most
1D granularity can only query data within 180 days at most

Example Response

{
    "code": "0",
    "data": [
        [
            "1630502100000",
            "1.25"
        ]
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
ts String Timestamp
ratio String Long/Short ratio

Get contracts open interest and volume

Open interest is the sum of all long and short futures and perpetual swap positions.

Rate Limit: 5 requests per 2 seconds

Rate limit rule: IP

HTTP Request

GET /api/v5/rubik/stat/contracts/open-interest-volume

Request Example

GET /api/v5/rubik/stat/contracts/open-interest-volume?ccy=BTC

Request Parameters

Parameter Type Required Description
ccy String Yes currency
begin String No begin,e.g:1597026383085
end String No end,e.g:1597026383011
period String No period,the default is 5m. e.g:[5m/1H/1D]
5m granularity can only query data within two days at most
1H granularity can only query data within 30 days at most
1D granularity can only query data within 180 days at most

Example Response

{
    "code": "0",
    "data": [
        [
            "1630502400000",
            "1713028741.6898",
            "39800873.554"
        ]
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
ts String Timestamp
oi String open interest(USD)
vol String volume(USD)

Get Options open interest and volume

This shows the sum of all open positions and how much total trading volume has taken place.

Rate Limit: 5 requests per 2 seconds

Rate limit rule: IP

HTTP Request

GET /api/v5/rubik/stat/option/open-interest-volume

Request Example

GET /api/v5/rubik/stat/option/open-interest-volume?ccy=BTC

Request Parameters

Parameter Type Required Description
ccy String Yes currency
period String No period,the default is 8H. e.g:[8H/1D]
Each granularity can only query 72 pieces of data at the earliest

Example Response

{
    "code": "0",
    "data": [
        [
            "1630368000000",
            "3458.1000",
            "78.8000"
        ]
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
ts String Timestamp
oi String open interest(coin as the unit)
vol String volume(coin as the unit)

Get Put/Call ratio

This shows the relative buy/sell volume for calls and puts. It shows whether traders are bullish or bearish on price and volatility.

Rate Limit: 5 requests per 2 seconds

Rate limit rule: IP

HTTP Request

GET /api/v5/rubik/stat/option/open-interest-volume-ratio

Request Example

GET /api/v5/rubik/stat/option/open-interest-volume-ratio?ccy=BTC

Request Parameters

Parameter Type Required Description
ccy String Yes currency
period String No period,the default is 8H. e.g:[8H/1D]
Each granularity can only query 72 pieces of data at the earliest

Example Response

{
    "code": "0",
    "data": [
        [
            "1630512000000",
            "2.7261",
            "2.3447"
        ],
        [
            "1630425600000",
            "2.8101",
            "2.3438"
        ]
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
ts String Timestamp
oiRatio String open interest ratio
volRatio String volume ratio

Get open interest and volume (expiry)

This shows the volume and open interest for each upcoming expiration. You can use this to see which expirations are currently the most popular to trade.

Rate Limit: 5 requests per 2 seconds

Rate limit rule: IP

HTTP Request

GET /api/v5/rubik/stat/option/open-interest-volume-expiry

Request Example

GET /api/v5/rubik/stat/option/open-interest-volume-expiry?ccy=BTC

Request Parameters

Parameter Type Required Description
ccy String Yes currency
period String No period,the default is 8H. e.g:[8H/1D]
Each granularity can only query 72 pieces of data at the earliest

Example Response

{
    "code": "0",
    "data": [
        [
            "1630540800000",
            "20210902",
            "6.4",
            "18.4",
            "0.7",
            "0.4"
        ],
        [
            "1630540800000",
            "20210903",
            "47",
            "36.6",
            "1",
            "10.7"
        ]
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
ts String Timestamp
expTime String expiry time (Format: YYYYMMdd, for example: "20210623")
callOI String call open interest (coin as the unit)
putOI String put open interest (coin as the unit)
callVol String call Volume (coin as the unit)
putVol String put Volume (coin as the unit)

Get open interest and volume (strike)

This shows what option strikes are the most popular for each expiration.

Rate Limit: 5 requests per 2 seconds

Rate limit rule: IP

HTTP Request

GET /api/v5/rubik/stat/option/open-interest-volume-strike

Request Example

GET /api/v5/rubik/stat/option/open-interest-volume-strike?ccy=BTC&expTime=20210901

Request Parameters

Parameter Type Required Description
ccy String Yes currency
expTime String Yes expiry time (Format: YYYYMMdd, for example: "20210623")
period String No period,the default is 8H. e.g:[8H/1D]
Each granularity can only query 72 pieces of data at the earliest

Example Response

{
    "code": "0",
    "data": [
        [
            "1630540800000",
            "10000",
            "0",
            "0.5",
            "0",
            "0"
        ],
        [
            "1630540800000",
            "14000",
            "0",
            "5.2",
            "0",
            "0"
        ]
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
ts String Timestamp
strike String strike
callOI String call open interest (coin as the unit)
putOI String put open interest (coin as the unit)
callVol String call Volume (coin as the unit)
putVol String put Volume (coin as the unit)

Get Taker flow

This shows the relative buy/sell volume for calls and puts. It shows whether traders are bullish or bearish on price and volatility.

Rate Limit: 5 requests per 2 seconds

Rate limit rule: IP

HTTP Request

GET /api/v5/rubik/stat/option/taker-block-volume

Request Example

GET /api/v5/rubik/stat/option/taker-block-volume?ccy=BTC

Request Parameters

Parameter Type Required Description
ccy String Yes currency
period String No period,the default is 8H. e.g:[8H/1D]
Each granularity can only query 72 pieces of data at the earliest

Example Response

{
    "code": "0",
    "data": [
        "1630512000000",
        "8.55",
        "67.3",
        "16.05",
        "16.3",
        "126.4",
        "40.7"
    ],
    "msg": ""
}

Response Parameters

Parameter Type Description
ts String Timestamp
callBuyVol String call option buy volume, settlement currency unit
callSellVol String call option sell volume, settlement currency unit
putBuyVol String put option buy volume, settlement currency unit
putSellVol String put option sell volume, settlement currency unit
callBlockVol String call block volume
putBlockVol String put block volume

Status

Get event status of system upgrade

Rate Limit: 1 requests per 5 seconds

HTTP Requests

GET /api/v5/system/status

Request Example

GET /api/v5/system/status

GET /api/v5/system/status?state=canceled

Request Parameters

Parameters Types Required Description
state String No System maintenance status,scheduled: waiting; ongoing: processing; completed: completed ;canceled: canceled .
If this parameter is not filled, the data with status scheduled and ongoing will be returned by default

Example Response

{
    "code": "0",
    "msg": "",
    "data": [{
        "title": "Spot System Upgrade",
        "state": "scheduled",
        "begin": "1620723600000",
        "end": "1620724200000",
        "href": "",
        "serviceType": "1",
        "system": "classic",
        "scheDesc": ""       
    }]
}

Response Parameters

Parameters Types Description
title String The title of system maintenance instructions
state String System maintenance status
begin String Begin time of system maintenance, Unix timestamp format in milliseconds, e.g. 1617788463867
end String End time of system maintenance, Unix timestamp format in milliseconds, e.g. 1617788463867
href String Hyperlink for system maintenance details, if there is no return value, the default value will be empty. e.g. “”
serviceType String Service type, 0:WebSocket ; 1:Spot/Margin ; 2:Futures ; 3:Perpetual ; 4:Options ; 5:Trading service
system String System, classic:Classic account, unified:Unified account
scheDesc String Rescheduled description,e.g. Rescheduled from 2021-01-26T16:30:00.000Z to 2021-01-28T16:30:00.000Z

WebSocket API

Overview

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

Connect

Connection instructions:

Connection limit: 1 time per second

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

Subscription limit: 240 times per hour

Login

Request format description

{
  "op": "login",
  "args": [
    {
      "apiKey": "<api_key>",
      "passphrase": "<passphrase>",
      "timestamp": "<timestamp>",
      "sign": "<sign>"
    }
  ]
}

Request Example

{
  "op": "login",
  "args": [
    {
      "apiKey": "985d5b66-57ce-40fb-b714-afc0b9787083",
      "passphrase": "123456",
      "timestamp": "1538054050",
      "sign": "7L+zFQ+CEgGu5rzCj4+BdV2/uUHGqddA9pI6ztsRRPs="
    }
  ]
}

Successful Response Example

{
  "event": "login",
  "code": "0",
  "msg": ""
}

Failure Response Example

{
  "event": "error",
  "code": "60008",
  "msg": "Login is not supported for public channels."
}

api_key: Unique identification for invoking API. Requires user to apply one manually.

passphrase: APIKey password

timestamp: the Unix Epoch time, the unit is seconds

sign: signature string, the signature algorithm is as follows:

First concatenate timestamp, method, requestPath, and body strings, then use HMAC SHA256 method to encrypt the concatenated string with SecretKey, and then perform Base64 encoding.

secretKey: The security key generated when the user applies for APIKey, e.g. : 22582BD0CFF14C41EDBF1AB98506286D

Example of timestamp: const timestamp ='' + Date.now() / 1000

Among sign example: sign=CryptoJS.enc.Base64.Stringify(CryptoJS.HmacSHA256(timestamp +'GET'+'/users/self/verify', secretKey))

method: always 'GET'.

requestPath : always '/users/self/verify'

Subscribe

Subscription Instructions

Request format description

{
  "op": "subscribe",
  "args": ["<SubscriptionTopic>"]
}

WebSocket channels are divided into two categories: public and private channels.

Public channels -- include tickers channel, K-Line channel, limit price channel, order book channel, and mark price channel, etc -- do not require log in.

Private channels -- including account channel, order channel, and position channel, etc -- require log in.

Users can choose to subscribe to one or more channels, and the total length of multiple channels cannot exceed 4096 bytes.

Request Example

{
  "op": "subscribe",
  "args": [
    {
      "channel": "tickers",
      "instId": "LTC-USD-200327"
    },
    {
      "channel": "candle1m",
      "instId": "LTC-USD-200327"
    }
  ]
}

Request parameters

Parameter Type Required Description
op String Yes Operation, subscribe
args Array Yes List of subscribed channels
> channel String Yes Channel name
> instType String No Instrument type
SPOT
MARGIN
SWAP
FUTURES
OPTION
ANY
> uly String No Underlying
> instId String No Instrument ID

Example response

{
  "event": "subscribe",
  "arg": {
    "channel": "tickers",
    "instId": "LTC-USD-200327"
  }
}

Return parameters

Parameter Type Required Description
event String Yes Event, subscribe error
arg Object No Subscribed channel
> channel String Yes Channel name
> instType String No Instrument type
SPOT
MARGIN
SWAP
FUTURES
OPTION
ANY
> uly String No Underlying
> instId String No Instrument ID
code String No Error code
msg String No Error message

Unsubscribe

Unsubscribe from one or more channels.

Request format description

{
  "op": "unsubscribe",
  "args": ["< SubscriptionTopic> "]
}

Request Example

{
  "op": "unsubscribe",
  "args": [
    {
      "channel": "tickers",
      "instId": "LTC-USD-200327"
    },
    {
      "channel": "candle1m",
      "instId": "LTC-USD-200327"
    }
  ]
}

Request parameters

Parameter Type Required Description
op String Yes Operation, unsubscribe
args Array Yes List of channels to unsubscribe from
> channel String Yes Channel name
> instType String No Instrument type
SPOT
MARGIN
SWAP
FUTURES
OPTION
ANY
> uly String No Underlying
> instId String No Instrument ID

Example response

{
  "event": "unsubscribe",
  "arg": {
    "channel": "tickers",
    "instId": "LTC-USD-200327"
  }
}

Return parameters

Parameter Type Required Description
event String Yes Event, unsubscribe error
arg Object No Unsubscribed channel
> channel String Yes Channel name
> instType String No Instrument type
SPOT
MARGIN
SWAP
FUTURES
OPTION
> uly String No Underlying
> instId String No Instrument ID
code String No Error code
msg String No Error message

Checksum

This mechanism can assist users in checking the accuracy of depth data.

Merging incremental data into full data

After subscribing to the incremental load push (such as books 400 levels) of Order Book Channel, users first receive the initial full load of market depth. After the incremental load is subsequently received, update the local full load.

  1. If there is the same price, compare the amount. If the amount is 0, delete this depth data. If the amount changes, replace the original data.
  2. If there is no same price, sort by price (bid in descending order, ask in ascending order), and insert the depth information into the full load.

Calculate Checksum

Use the first 25 bids and asks in the full load to form a string (where a colon connects the price and amount in an ask or a bid), and then calculate the CRC32 value (32-bit signed integer).

Calculate Checksum

1. More than 25 levels of bid and ask
A full load of market depth (only 2 levels of data are shown here, while 25 levels of data should actually be intercepted):
"bids": [
  [ 3366.1, 7, 0, 3 ],
  [ 3366  , 6, 3, 4 ]
]
"asks": [
  [ 3366.8, 9, 10, 3 ],
  [ 3368  , 8,  3, 4 ]
]
Check string:
"3366.1:7:3366.8:9:3366:6:3368:8"

2. Less than 25 levels of bid or ask
A full load of market depth:
"bids": [
  [ 3366.1, 7, 0, 3 ]
]
"asks": [
  [ 3366.8, 9, 10, 3 ],
  [ 3368  , 8,  3, 4 ],
  [ 3372  , 8,  3, 4 ]
]

Check string:
"3366.1:7:3366.8:9:3368:8:3372:8"
  1. When the bid and ask depth data exceeds 25 levels, each of them will intercept 25 levels of data, and the string to be checked is queued in a way that the bid and ask depth data are alternately arranged.
    Such as: bid[price:amount]:ask[price:amount]:bid[price:amount]:ask[price:amount]...
  2. When the bid or ask depth data is less than 25 levels, the missing depth data will be ignored.
    Such as: bid[price:amount]:ask[price:amount]:asks[price:amount]:asks[price:amount]...

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": "100"
    }
  ]
}

Request Parameters

Parameter Type Required Description
id String Yes Unique identifier of the message
Provided by client. It will be returned in response message for identifying the corresponding request.
A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.
op String Yes Operation, e.g. order
args Array Yes Request parameters
> instId String Yes Instrument ID,e.g. BTC-USD-190927-5000-C
> tdMode String Yes Trade mode
Margin mode isolated cross
Non-Margin mode cash
> ccy String No Margin currency
Only applicable to cross MARGIN orders in Single-currency margin.
> clOrdId String No Client-supplied order ID
A combination of case-sensitive alphanumerics, all numbers, or all letters 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: market order
limit: limit order
post_only: Post-only order
fok: Fill-or-kill order
ioc: Immediate-or-cancel order
optimal_limit_ioc :Market order with immediate-or-cancel order
> sz String Yes Quantity to buy or sell.
> px String No Price
Only applicable to limit,post_only,fok,ioc order.
> reduceOnly Boolean No Whether to reduce positions only, true false, and the default is false.
Only applicable to MARGIN.
> tgtCcy String No Quantity type
base_ccy:Base currency ;quote_ccy:Quote currency
Only applicable to SPOT
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": "cash",
      "ordType": "market",
      "sz": "100"
    },
    {
      "side": "buy",
      "instId": "LTC-USDT",
      "tdMode": "cash",
      "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. batch-orders
args Array Yes Request Parameters
> instId String Yes Instrument ID, e.g. BTC-USDT
> tdMode String Yes Trade mode
Margin mode isolated cross
Non-Margin mode cash
> ccy String No Margin currency
Only applicable to cross MARGIN orders in Single-currency margin.
> clOrdId String No Client-supplied order ID
A combination of case-sensitive alphanumerics, all numbers, or all letters 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: market order
limit: limit order
post_only: Post-only order
fok: Fill-or-kill order
ioc: Immediate-or-cancel order
optimal_limit_ioc :Market order with immediate-or-cancel order (applicable only to Futures and Perpetual swap).
> sz String Yes The number of transactions indicates the quantity to be bought or sold.
> px String No Price
Only applicable to limit,post_only,fok,ioc order.
> reduceOnly Boolean No Whether to reduce positions only, true false, and the default is false.
Only applicable to MARGIN.
> tgtCcy String No Quantity type
base_ccy:Base currency ;quote_ccy:Quote currency
Only applicable to SPOT

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",
      "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
A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.

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",
      "ordId": "2517748157541376"
    },
    {
      "instId": "LTC-USDT",
      "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
A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters.

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",
      "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",
      "ordId": "12345689",
      "newSz": "2"
    },
    {
      "instId": "BTC-USDT",
      "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

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",
      "ordFroz": "0",
      "imr": "4162.33",
      "mmr": "4",
      "notionalUsd": "",
      "mgnRatio": "41624.32",
      "details": [
        {
          "availBal": "",
          "availEq": "1",
          "ccy": "BTC",
          "cashBal": "1",
          "uTime": "1617279471503",
          "disEq": "50559.01",
          "eq": "1",
          "eqUsd": "45078.3790756226851775",
          "frozenBal": "0",
          "interest": "0",
          "isoEq": "0",
          "liab": "0",
          "maxLoan": "",
          "mgnRatio": "",
          "notionalLever": "0.0022195262185864",
          "ordFrozen": "0",
          "upl": "0",
          "uplLiab": "0",
          "crossLiab": "0",
          "isoLiab": "0",
          "coinUsdPrice": "60000",
          "stgyEq":"0",
          "isoUpl":""
        }
      ]
    }
  ]
}

Push Data Example

{
  "arg": {
    "channel": "account"
  },
  "data": [
    {
      "uTime": "1614846244194",
      "totalEq": "91884.8502560037982063",
      "adjEq": "91884.8502560037982063",
      "isoEq": "0",
      "ordFroz": "0",
      "imr": "0",
      "mmr": "0",
      "notionalUsd": "",
      "mgnRatio": "100000",
      "details": [{
          "availBal": "",
          "availEq": "1",
          "ccy": "BTC",
          "cashBal": "1",
          "uTime": "1617279471503",
          "disEq": "50559.01",
          "eq": "1",
          "eqUsd": "45078.3790756226851775",
          "frozenBal": "0",
          "interest": "0",
          "isoEq": "0",
          "liab": "0",
          "maxLoan": "",
          "mgnRatio": "",
          "notionalLever": "0.0022195262185864",
          "ordFrozen": "0",
          "upl": "0",
          "uplLiab": "0",
          "crossLiab": "0",
          "isoLiab": "0",
          "coinUsdPrice": "60000",
          "stgyEq":"0",
          "isoUpl":""
        },
        {
          "availBal": "",
          "availEq": "41307.251992607125",
          "ccy": "USDT",
          "cashBal": "41307.251992607125",
          "uTime": "1617279471503",
          "disEq": "41325.8402560037982063",
          "eq": "41307.251992607125",
          "eqUsd": "45078.3790756226851775",
          "frozenBal": "0",
          "interest": "0",
          "isoEq": "0",
          "liab": "0",
          "maxLoan": "",
          "mgnRatio": "",
          "notionalLever": "0.0022195262185864",
          "ordFrozen": "0",
          "upl": "0",
          "uplLiab": "0",
          "crossLiab": "0",
          "isoLiab": "0",
          "coinUsdPrice": "1.00007",
          "stgyEq":"0",
          "isoUpl":""
        }
      ]
    }
  ]
}

Push data 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
ordFroz String Margin frozen for pending orders 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
notionalUsd String Quantity of positions usd
Applicable to Multi-currency margin
details Array Detailed asset information in all currencies
> ccy String Currency
> eq String Equity of the currency
> cashBal String Cash Balance
> uTime String Update time, Unix timestamp format in milliseconds, e.g. 1597026383085
> isoEq String Isolated margin equity of the currency
Applicable to Single-currency margin and Multi-currency margin
> availEq String Available equity of the currency
Applicable to Single-currency margin and Multi-currency margin
> disEq String discount equity of the currency in USD level
> availBal String Available balance of the currency
Applicable to Simple
> frozenBal String Frozen balance of the currency
> ordFrozen String Margin frozen for open orders
> liab String Liabilities of the currency
Applicable to Multi-currency margin
> upl String Unrealized profit and loss of the currency
Applicable to Single-currency margin and Multi-currency margin
> uplLib String Liabilities due to Unrealized loss of the currency
Applicable to Multi-currency margin
> crossLiab String Cross Liabilities of the currency
Applicable to Multi-currency margin
> isoLiab String Isolated Liabilities of the currency
Applicable to Multi-currency margin
> mgnRatio String Margin ratio of the currency
Applicable to Single-currency margin
> interest String Interest of the currency
Applicable to Multi-currency margin
> twap String System's forced repayment(TWAP) indicator
Divided into 5 levels, from 1 to 5, the smaller the number, the weaker the TWAP intensity.
Applicable to Multi-currency margin
> maxLoan String Max loan of the currency
Applicable to Multi-currency margin
> eqUsd String Equity usd of the currency
> notionalLever String Leverage of the currency
Applicable to Single-currency margin
> coinUsdPrice String Price index usd of the currency
> stgyEq String strategy equity
> isoUpl String Isolated unrealized profit and loss of the currency
Applicable to Single-currency margin and Multi-currency margin

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"
    },
    "data":[
        {
            "adl":"1",
            "availPos":"1",
            "avgPx":"2566.31",
            "cTime":"1619507758793",
            "ccy":"ETH",
            "deltaBS":"",
            "deltaPA":"",
            "gammaBS":"",
            "gammaPA":"",
            "imr":"",
            "instId":"ETH-USD-210430",
            "instType":"FUTURES",
            "interest":"0",
            "last":"2566.22",
            "lever":"10",
            "liab":"",
            "liabCcy":"",
            "liqPx":"2352.8496681818233",
            "margin":"0.0003896645377994",
            "mgnMode":"isolated",
            "mgnRatio":"11.731726509588816",
            "mmr":"0.0000311811092368",
            "notionalUsd":"2276.2546609009605",
            "optVal":"",
            "pTime":"1619507761462",
            "pos":"1",
            "posCcy":"",
            "posId":"307173036051017730",
            "posSide":"long",
            "thetaBS":"",
            "thetaPA":"",
            "tradeId":"109844",
            "uTime":"1619507761462",
            "upl":"-0.0000009932766034",
            "uplRatio":"-0.0025490556801078",
            "vegaBS":"",
            "vegaPA":""
        }
    ]
}

Push Data Example

{
    "arg": {
        "channel": "positions",
        "instType": "ANY"
    },
    "data": [{
    "adl":"1",
    "availPos":"1",
    "avgPx":"2566.31",
    "cTime":"1619507758793",
    "ccy":"ETH",
    "deltaBS":"",
    "deltaPA":"",
    "gammaBS":"",
    "gammaPA":"",
    "imr":"",
    "instId":"ETH-USD-210430",
    "instType":"FUTURES",
    "interest":"0",
    "last":"2566.22",
    "lever":"10",
    "liab":"",
    "liabCcy":"",
    "liqPx":"2352.8496681818233",
    "margin":"0.0003896645377994",
    "mgnMode":"isolated",
    "mgnRatio":"11.731726509588816",
    "mmr":"0.0000311811092368",
    "notionalUsd":"2276.2546609009605",
    "optVal":"",
    "pTime":"1619507761462",
    "pos":"1",
    "posCcy":"",
    "posId":"307173036051017730",
    "posSide":"long",
    "thetaBS":"",
    "thetaPA":"",
    "tradeId":"109844",
    "uTime":"1619507761462",
    "upl":"-0.0000009932766034",
    "uplRatio":"-0.0025490556801078",
    "vegaBS":"",
    "vegaPA":""
}, {
    "adl":"1",
    "availPos":"1",
    "avgPx":"2566.31",
    "cTime":"1619507758793",
    "ccy":"ETH",
    "deltaBS":"",
    "deltaPA":"",
    "gammaBS":"",
    "gammaPA":"",
    "imr":"",
    "instId":"ETH-USD-SWAP",
    "instType":"SWAP",
    "interest":"0",
    "last":"2566.22",
    "lever":"10",
    "liab":"",
    "liabCcy":"",
    "liqPx":"2352.8496681818233",
    "margin":"0.0003896645377994",
    "mgnMode":"isolated",
    "mgnRatio":"11.731726509588816",
    "mmr":"0.0000311811092368",
    "notionalUsd":"2276.2546609009605",
    "optVal":"",
    "pTime":"1619507761462",
    "pos":"1",
    "posCcy":"",
    "posId":"307173036051017730",
    "posSide":"long",
    "thetaBS":"",
    "thetaPA":"",
    "tradeId":"109844",
    "uTime":"1619507761462",
    "upl":"-0.0000009932766034",
    "uplRatio":"-0.0025490556801078",
    "vegaBS":"",
    "vegaPA":""
}]
}

Push data parameters

Parameter Type Description
arg Object Successfully subscribed channel
> channel String Channel name
> instType String Instrument type
> uly String Underlying
> instId String Instrument ID
data Array Subscribed data
> instType String Instrument type
> mgnMode String Margin mode, cross isolated
> posSide String Position side
long
short
net (FUTURES/SWAP/OPTION: positive pos means long position and negative pos means short position. MARGIN: posCcy being base currency means long position, posCcy being quote currency means short position.)
> pos String Quantity of positions
> posCcy String Position currency, only applicable to MARGIN positions
> availPos String Position that can be closed
Only applicable to MARGIN, FUTURES/SWAP in the long-short mode, OPTION in Simple and isolated OPTION in margin Account.
> avgPx String Average open price
> upl String Unrealized profit and loss
> uplRatio String Unrealized profit and loss ratio
> instId String Instrument ID, e.g. BTC-USD-180216
> lever String Leverage, not applicable to OPTION seller
> liqPx String Estimated liquidation price
Not applicable to OPTION
> imr String Initial margin requirement, only applicable to cross
> margin String Margin, can be added or reduced. Only applicable to isolated Margin.
> mgnRatio String Margin ratio
> mmr String Maintenance margin requirement
> liab String Liabilities, only applicable to MARGIN.
> liabCcy String Liabilities currency, only applicable to MARGIN.
> interest String Interest. Interest that has been incurred.
> tradeId String Last trade ID
> notionalUsd String Quantity of positions usd
> 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
> deltaBS String delta:Black-Scholes Greeks in dollars,only applicable to OPTION
> deltaPA String delta:Greeks in coins,only applicable to OPTION
> gammaBS String gamma:Black-Scholes Greeks in dollars,only applicable to OPTION
> gammaPA String gamma:Greeks in coins,only applicable to OPTION
> thetaBS String theta:Black-Scholes Greeks in dollars,only applicable to OPTION
> thetaPA String theta:Greeks in coins,only applicable to OPTION
> vegaBS String vega:Black-Scholes Greeks in dollars,only applicable to OPTION `
> vegaPA String vega:Greeks in coins,only applicable to OPTION
> cTime String Creation time, Unix timestamp format in milliseconds, e.g. 1597026383085.
> uTime String Latest time position was adjusted, Unix timestamp format in milliseconds, e.g. 1597026383085.
> pTime String Push time of positions information, Unix timestamp format in milliseconds, e.g. 1597026383085.

Balance and Position Channel

Retrieve account balance and position information. Data will be pushed when triggered by events such as filled order, funding transfer.

Request Example

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

Request parameters

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

Response Example

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

Failure Response Example

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

Response parameters

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

Push Data Example

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

Push data parameters

Parameter Type Description
arg Object Channel to subscribe to
> channel String Channel name
data Array Subscribed data
> pTime String Push time of both balance and position information, millisecond format of Unix timestamp, e.g. 1597026383085
> eventType String Event Type, Enum:snapshot
delivered,exercised,transferred,filled, liquidation, claw_back, adl, funding_fee,adjust_margin, set_leverage,interest_deduction
> balData String Balance data
>> ccy String Currency
>> cashBal String Cash Balance
>> uTime String Update time, Unix timestamp format in milliseconds, e.g. 1597026383085
> posData String Position data
>> posId String Position ID
>> tradeId String Last trade ID
>> instId String Instrument ID, e.g BTC-USD-180213
>> instType String Instrument type
>> mgnMode String Margin mode, isolated, cross
>> avgPx String Average open price
>> ccy String Currency used for margin
>> posSide String Position side:long, short, net
>> pos String Quantity of positions
>> posCcy String Position currency, only applicable to MARGIN positions.
>> uTime String Update time, Unix timestamp format in milliseconds, e.g. 1597026383085

Order Channel

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

Request Example : single

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

Request Example

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

Request parameters

Parameter Type Required Description
op String Yes Operation, subscribe unsubscribe
args Array Yes List of subscribed channels
> channel String Yes Channel name, orders
> instType String Yes Instrument type
SPOT
MARGIN
SWAP
FUTURES
OPTION
ANY
> uly String No Underlying
> instId String No Instrument ID

Successful Response Example : single

{
  "event": "subscribe",
  "arg": {
    "channel": "orders",
    "instType": "FUTURES",
    "uly": "BTC-USD"
  }
}

Successful Response Example

{
  "event": "subscribe",
  "arg": {
    "channel": "orders",
    "instType": "FUTURES",
    "uly": "BTC-USD"
  }
}

Failure Response Example

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

Response parameters

Parameter Type Required Description
event String Yes Event, subscribe unsubscribe errror
arg Object No Subscribed channel
> channel String Yes Channel name
> instType String Yes Instrument type
SPOT
MARGIN
SWAP
FUTURES
OPTION
ANY
> uly String No Underlying
> instId String No Instrument ID
code String No Error code
msg String No Error message

Push Data Example: single

{
  "arg": {
    "channel": "orders",
    "instType": "FUTURES",
    "instId": "BTC-USD-200329"
  },
  "data": [
    {
      "instType": "FUTURES",
      "instId": "BTC-USD-200329",
      "ccy": "BTC",
      "ordId": "312269865356374016",
      "clOrdId": "b1",
      "tag": "",
      "px": "999",
      "sz": "333",
      "notionalUsd": "",
      "ordType": "limit",
      "side": "buy",
      "posSide": "long",
      "tdMode": "cross",
      "tgtCcy": "",
      "fillSz": "0",
      "fillPx": "long",
      "tradeId": "0",
      "accFillSz": "323",
      "fillNotionalUsd": "",
      "fillTime": "0",
      "fillFee": "0.0001",
      "fillFeeCcy": "BTC",
      "execType": "T",
      "state": "canceled",
      "avgPx": "0",
      "lever": "20",
      "tpTriggerPx": "0",
      "tpOrdPx": "20",
      "slTriggerPx": "0",
      "slOrdPx": "20",
      "feeCcy": "",
      "fee": "",
      "rebateCcy": "",
      "rebate": "",
      "tgtCcy":"",
      "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
>tgtCcy String Quantity type
base_ccy:Base currency ;quote_ccy:Quote currency
Only applicable to SPOT
> ccy String Margin currency
Only applicable to cross MARGIN orders in Single-currency margin.
> ordId String Order ID
> clOrdId String Client-supplied order ID
> tag String Order tag
> px String Order price
> sz String The original order quantity, SPOT/MARGIN, in the unit of currency; FUTURES/SWAP/OPTION, in the unit of contract
> notionalUsd String Estimated national value in USD of order
> 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
optimal_limit_ioc :Market order with immediate-or-cancel order (applicable only to Futures and Perpetual swap).
> 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
> fillFee String last filled fee
> fillFeeCcy String last filled fee currency
> execType String Order flow type, T: taker M: maker
> accFillSz String Accumulated fill quantity
> fillNotionalUsd String Filled notional value in USD of order
> 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
Negative number represents the user transaction fee charged by the platform.
Positive number represents rebate.
> 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 (includes trigger order, oco order, conditional order). 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, orders-algo
> 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": "312269865356374016",
        "ccy": "BTC",
        "algoId": "1234",
        "px": "999",
        "sz": "3",
        "tdMode": "cross",
        "tgtCcy": "",
        "notionalUsd": "",
        "ordType": "trigger",
        "side": "buy",
        "posSide": "long",
        "state": "live",
        "lever": "20",
        "tpTriggerPx": "",
        "tpOrdPx": "",
        "slTriggerPx": "",
        "triggerPx": "99",
        "ordPx": "12",
        "actualSz": "",
        "actualPx": "",
        "actualSide": "",
        "triggerTime": "1597026383085",
        "cTime": "1597026383000"
    }]
}

Response parameters when data is pushed.

Parameter Type Description
arg Object Successfully subscribed channel
> channel String Channel name
> instType String Instrument type
> uly String Underlying
> instId String Instrument ID
data Array Subscribed data
> instType String Instrument type
> instId String Instrument ID
> ccy String Margin currency
Only applicable to cross MARGIN orders in Single-currency margin.
> ordId String Order ID, the order ID associated with the algo order.
> algoId String Algo ID
> sz String Quantity to buy or sell. SPOT/MARGIN: in the unit of currency. FUTURES/SWAP/OPTION: in the unit of contract.
> ordType String Order type
conditional: One-way stop order
oco: One-cancels-the-other order
trigger: Trigger order
> side String Order side, buy sell
> posSide String Position side
net
long or short Only applicable to FUTURES/SWAP
> tdMode String Trade mode, cross: cross isolated: isolated cash: cash
>tgtCcy String Quantity type
base_ccy:Base currency ;quote_ccy:Quote currency
Only applicable to SPOT
> 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
> notionalUsd String Estimated national value in USD of order
> 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

Advance Algo Orders Channel

Retrieve advance algo orders (includes iceberg order and twap order). Data will be pushed when first subscribed. Data will be pushed when triggered by events such as placing/canceling order.

Request Example : single

{
  "op": "subscribe",
  "args": [
    {
      "channel": "algo-advance",
      "instType": "SPOT",
      "instId": "BTC-USDT"
    }
  ]
}

Request Example

{
  "op": "subscribe",
  "args": [
    {
      "channel": "algo-advance",
      "instType": "SPOT",
    }
  ]
}

Request parameters

Parameter Type Required Description
op String Yes Operation, subscribe unsubscribe
args Array Yes List of subscribed channels
> channel String Yes Channel name, algo-advance
> instType String Yes Instrument type
SPOT
MARGIN
SWAP
FUTURES
ANY
> instId String No Instrument ID
> algoId String No Algo Order ID

Successful Response Example : single

{
  "event": "subscribe",
  "arg": {
    "channel": "algo-advance",
    "instType": "SPOT",
    "instId": "BTC-USDT"
  }
}

Successful Response Example

{
  "event": "subscribe",
  "arg": {
    "channel": "algo-advance",
    "instType": "SPOT"
  }
}

Failure Response Example

{
  "event": "error",
  "code": "60012",
  "msg": "Unrecognized request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"algo-advance\", \"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
> instId String No Instrument ID
> algoId String No Algo Order ID
code String No Error code
msg String No Error message

Push Data Example: single

{
    "arg":{
        "channel":"algo-advance",
        "instType":"SPOT",
        "instId":"BTC-USDT"
    },
    "data":[
        {
            "actualPx":"",
            "actualSide":"",
            "actualSz":"0",
            "algoId":"355056228680335360",
            "cTime":"1630924001545",
            "ccy":"",
            "count":"1",
            "instId":"BTC-USDT",
            "instType":"SPOT",
            "lever":"0",
            "notionalUsd":"",
            "ordPx":"",
            "ordType":"iceberg",
            "pTime":"1630924295204",
            "posSide":"net",
            "pxLimit":"10",
            "pxSpread":"1",
            "pxVar":"",
            "side":"buy",
            "slOrdPx":"",
            "slTriggerPx":"",
            "state":"pause",
            "sz":"0.1",
            "szLimit":"0.1",
            "tdMode":"cash",
            "timeInterval":"",
            "tpOrdPx":"",
            "tpTriggerPx":"",
            "triggerPx":"",
            "triggerTime":""
        }
    ]
}

Response parameters when data is pushed.

Parameter Type Description
arg Object Successfully subscribed channel
> channel String Channel name
> instType String Instrument type
> instId String Instrument ID
> algoId String Algo Order ID
data Array Subscribed data
> instType String Instrument type
> instId String Instrument ID
> ccy String Margin currency
Only applicable to cross MARGIN orders in Single-currency margin.
> ordId String Order ID, the order ID associated with the algo order.
> algoId String Algo ID
> sz String Quantity to buy or sell. SPOT/MARGIN: in the unit of currency. FUTURES/SWAP/OPTION: in the unit of contract.
> ordType String Order type
iceberg: Iceberg order
twap: TWAP 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
> tgtCcy String Quantity type
base_ccy:Base currency ;quote_ccy:Quote currency
Only applicable to SPOT
> 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
> notionalUsd String Estimated national value in USD of order
> 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
> pxVar String Price variance
Only applicable to iceberg order or twap order
> pxSpread String Price ratio
Only applicable to iceberg order or twap order
> szLimit String Average amount
Only applicable to iceberg order or twap order
> pxLimit String Price limit
Only applicable to iceberg order or twap order
> timeInterval String Time interval
Only applicable to twap order
> count String Algo Order count
Only applicable to iceberg order or twap order
> pTime String Push time of algo order information, millisecond format of Unix timestamp, e.g. 1597026383085

Public Channels

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/SWAP/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 24h trading volume, with a unit of currency.
If it is a derivatives contract, the value is the number of settlement currency.
If it is SPOT/MARGIN, the value is the number of quote currency.
> vol24h String 24h trading volume, with a unit of contact.
If it is a derivatives contract, the value is the number of contracts.
If it is SPOT/MARGIN, the value is the amount of trading currency.
>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 highest price
> l String Lowest price
> c String Close price
vol String Trading volume, with a unit of contact.
If it is a derivatives contract, the value is the number of contracts.
If it is SPOT/MARGIN, the value is the amount of trading currency.
volCcy String Trading volume, with a unit of currency.
If it is a derivatives contract, the value is the number of settlement currency.
If it is SPOT/MARGIN, the value is the number of quote currency.

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

{
  "event": "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-USDT"
  },
  "data": [
    {
      "instId": "BTC-USDT",
      "tradeId": "130639474",
      "px": "42219.9",
      "sz": "0.12060306",
      "side": "buy",
      "ts": "1630048897897"
    }
  ]
}

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 OPTIONAL Underlying
Either uly or instId is required
> instId String OPTIONAL 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": "BTC-USDT"
    }
  ]
}

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": "BTC-USDT"
  }
}

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": "mark-price",
    "instId": "BTC-USDT"
  },
  "data": [
    {
      "instType": "MARGIN",
      "instId": "BTC-USDT",
      "markPx": "42310.6",
      "ts": "1630049139746"
    }
  ]
}

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-USDT
> 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, books50-l2-tbt tick-by-tick 50 depth levels, and books-l2-tbt for tick-by-tick 400 depth levels.

Request Example

{
  "op": "subscribe",
  "args": [
    {
      "channel": "books",
      "instId": "BTC-USDT"
    }
  ]
}

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 books50-l2-tbt books-l2-tbt
> instId String Yes Instrument ID

Example Response

{
  "event": "subscribe",
  "arg": {
    "channel": "books",
    "instId": "BTC-USDT"
  }
}

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-USDT"
  },
  "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