Market Maker Program
High-caliber trading teams are welcomed to work with OKX as market makers in providing a liquid, fair, and orderly platform to all users. OKX market makers could enjoy favourable fees in return for meeting the market making obligations.
Prerequisites (Satisfy any condition):
- VIP 2 or above on fee schedule
- Qualified Market Maker on other exchange
Interested parties could drop us an email at [email protected]
with the below details:
- Your account email
- Contact details (additional to your account email)
- A screenshot of your maker trading volume (such as 30 days trading volume or VIP status)
- Specify the product line you would like to provide liquidity for (you may choose more than one)
- Spot
- Futures
- Perpetual Swap
- Spot
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 Trading account.
Satisfaction Survey
Many thanks for using OKX V5 API service. We would appreciate if you could share with us your feedbacks and suggestions as we strive to enhance user experiences for V5 API. Your comments are very important to us and we look forward to hearing from you.
Please click this link V5 API Satisfaction Survey
Production Trading Services
The Production Trading URL:
- REST:
https://www.okx.com/
- Public WebSocket:
wss://ws.okx.com:8443/ws/v5/public
- Private WebSocket:
wss://ws.okx.com:8443/ws/v5/private
AWS URL:
- REST:
https://aws.okx.com
- Public WebSocket:
wss://wsaws.okx.com:8443/ws/v5/public
- Private WebSocket:
wss://wsaws.okx.com:8443/ws/v5/private
Original
REST:https://www.okex.com
Original
Public WebSocket:wss://ws.okex.com:8443/ws/v5/public
Original
Private WebSocket:wss://ws.okex.com:8443/ws/v5/private
Original AWS URL
:
- REST:
https://aws.okex.com
- Public WebSocket:
wss://wsaws.okex.com:8443/ws/v5/public
- Private WebSocket:
wss://wsaws.okex.com:8443/ws/v5/private
Demo Trading Services
At present, the V5 API works for Demo Trading and users can request all APIs except the withdrawal
, deposit
and purchase/redemption
.
The Demo Trading URL:
- REST:
https://www.okx.com
- Public WebSocket:
wss://wspap.okx.com:8443/ws/v5/public?brokerId=9999
- Private WebSocket:
wss://wspap.okx.com:8443/ws/v5/private?brokerId=9999
The original
Demo Trading URL:
- REST:
https://www.okex.com
- Public WebSocket:
wss://wspap.okex.com:8443/ws/v5/public?brokerId=9999
- Private WebSocket:
wss://wspap.okex.com:8443/ws/v5/private?brokerId=9999
OKX account can be used for login on Demo Trading. If you already have an OKX account, you can log in directly.
Start API Demo Trading by the following steps:
Login OKX —> Assets —> Start Demo Trading —> Personal Center —> Demo Trading API -> Create Demo Trading V5 APIKey —> Start your Demo Trading
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
General Info
The rules for placing orders at the exchange level are as follows:
The max number of pending limit orders (including advanced limit orders): 4000
The max number of pending algo orders:
- Trigger order: 5000
- Trailing order: 50
- Iceberg order: 100
- TWAP order: 20
Demo Trading Explorer
Get start
You should login first. The interface only requests the demo trading environment.
Clicking
Try it out
button in Parameters Pannel and editing request parameters.Clicking
Execute
button to send your request. You can check response in Responses panel.
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:
- APIKey
- SecretKey
- Passphrase
We will provide randomly-generated APIKeys and SecretKeys. You will provide the Passphrase to further secure your API access. We store the salted hash of your Passphrase for authentication, but we cannot recover the Passphrase if you lose it.
Making Requests
All private REST requests must contain the following headers:
OK-ACCESS-KEY
The APIKey as a String.OK-ACCESS-SIGN
The Base64-encoded signature (see Signing Messages subsection for details).OK-ACCESS-TIMESTAMP
The timestamp of your request.e.g : 2020-12-08T09:08:57.715ZOK-ACCESS-PASSPHRASE
The passphrase you specified when creating the APIKey.
Request bodies should have content type application/json
and be in valid JSON format.
Signature
Signing Messages
The OK-ACCESS-SIGN
header is generated as follows:
- Create a prehash string of timestamp + method + requestPath + body (where + represents String concatenation).
- Prepare the SecretKey.
- Sign the prehash string with the SecretKey using the HMAC SHA256.
- Encode the signature in the Base64 format.
Example: sign=CryptoJS.enc.Base64.stringify(CryptoJS.HmacSHA256(timestamp + 'GET' + '/users/self/verify', SecretKey))
The timestamp
value is the same as the OK-ACCESS-TIMESTAMP
header with millisecond format of ISO, e.g. 2020-12-08T09:08:57.715Z
.
The request method should be in UPPERCASE: e.g. GET
and POST
.
The requestPath
is the path of requesting an endpoint.
Example: /api/v5/account/balance
The body
refers to the String of the request body. It can be omitted if there is no request body (frequently the case for GET
requests).
Example: {"instId":"BTC-USDT","lever":"5","mgnMode":"isolated"}
The SecretKey is generated when you create an APIKey.
Example: 22582BD0CFF14C41EDBF1AB98506286D
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 +(instrumentType、underlying)
Spot & Margin rate limit rule: UserID +(instrumentType、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 16 characters. |
side | String | Yes | Order side, buy sell |
posSide | String | Optional | Position side The default is net in the net modeIt is required in the long/short mode, and can only be long or short .Only applicable to FUTURES/SWAP . |
ordType | String | Yes | Order typemarket : Market orderlimit : Limit orderpost_only : Post-only orderfok : Fill-or-kill orderioc : 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, and FUTURES/SWAP orders in net mode Only applicable to Single-currency margin and Multi-currency margin |
tgtCcy | String | No | Quantity typebase_ccy : Base currency ,quote_ccy : Quote currency Only applicable to SPOT traded with Market orderDefault is quote_ccy for buy, base_ccy for sell |
Response Example
{
"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 +(instrumentType、underlying)
Spot & Margin rate limit rule: UserID +(instrumentType、instrumentID)
How many elements the batch requests contains, the rate limit count will be increased by the same number. The total limit is 300 times/2s
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 16 characters. |
side | String | Yes | Order side buy sell |
posSide | String | Optional | Position side The default is net in the net modeIt is required in the long/short mode, and can only be long or short .Only applicable to FUTURES/SWAP . |
ordType | String | Yes | Order typemarket : market orderlimit : limit orderpost_only : Post-only orderfok : Fill-or-kill orderioc : 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 and FUTURES/SWAP of net mode Applicable to Single-currency margin and Multi-currency margin |
tgtCcy | String | No | Quantity typebase_ccy : Base currency ,quote_ccy : Quote currency Only applicable to SPOT traded with Market orderDefault is quote_ccy for buy, base_ccy for sell |
Response Example
{
"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 +(instrumentType、underlying)
Spot & Margin rate limit rule: UserID +(instrumentType、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 |
Response Example
{
"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 +(instrumentType、underlying)
Spot & Margin rate limit rule: UserID +(instrumentType、instrumentID)
How many elements the batch requests contains, the rate limit count will be increased by the same number. The total limit is 300 times/2s
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 |
Response Example
{
"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 +(instrumentType、underlying)
Spot & Margin rate limit rule: UserID +(instrumentType、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. |
Response Example
{
"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
Derivatives rate limit rule: UserID +(instrumentType、underlying)
Spot & Margin rate limit rule: UserID +(instrumentType、instrumentID)
How many elements the batch requests contains, the rate limit count will be increased by the same number. The total limit is 300 times/2s
HTTP Request
POST /api/v5/trade/amend-batch-orders
Request Example
POST /api/v5/trade/amend-batch-orders
body
[
{
"ordId":"2510789768709120",
"newSz":"2",
"instId":"BTC-USDT"
},
{
"ordId":"2510789768709121",
"newSz":"2",
"instId":"BTC-USDT"
}
]
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instId | String | Yes | Instrument ID |
cxlOnFail | Boolean | No | Whether the order needs to be automatically canceled when the order amendment failsfalse true , the default is false . |
ordId | String | Optional | Order ID Either ordId or clOrdId is required, if both are passed, ordId will be used. |
clOrdId | String | Optional | Client-supplied order ID |
reqId | String | No | Client-supplied request ID A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. |
newSz | String | Optional | New quantity after amendment. Either newSz or newPx is required. When amending a partially-filled order, the newSz should include the amount that has been filled. |
newPx | String | Optional | New price after amendment. |
Response Example
{
"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 +(instrumentType、underlying)
Spot & Margin rate limit rule: UserID +(instrumentType、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 modecross isolated |
ccy | String | Optional | Margin currency, required in the case of closing cross MARGIN position for Single-currency margin . |
autoCxl | Boolean | No | Whether any pending orders for closing out needs to be automatically canceled when close position via a market order.false or true , the default is false . |
Response Example
{
"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 +(instrumentType、underlying)
Spot & Margin rate limit rule: UserID +(instrumentType、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 |
Response Example
{
"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": "",
"tpTriggerPxType": "last",
"tpOrdPx": "",
"slTriggerPx": "",
"slTriggerPxType": "last",
"slOrdPx": "",
"feeCcy": "",
"fee": "",
"rebateCcy": "",
"rebate": "",
"tgtCcy":"",
"category": "",
"uTime": "1597026383085",
"cTime": "1597026383085"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument typeSPOT MARGIN SWAP FUTURES OPTION |
instId | String | Instrument ID |
tgtCcy | String | Quantity typebase_ccy : Base currency ,quote_ccy : Quote currency Only applicable to SPOT traded with Market order |
ccy | String | Margin currency Only applicable to cross MARGIN orders in Single-currency margin . |
ordId | String | Order ID |
clOrdId | String | Client-supplied order ID |
tag | String | Order tag |
px | String | Price |
sz | String | Quantity to buy or sell |
pnl | String | Profit and loss |
ordType | String | Order typemarket : Market orderlimit : Limit orderpost_only : Post-only orderfok : Fill-or-kill orderioc : Immediate-or-cancel order 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. |
tpTriggerPxType | String | Take-profit trigger price type. last : last priceindex : index pricemark : mark price |
tpOrdPx | String | Take-profit trigger price. |
slTriggerPx | String | Stop-loss trigger price. |
slTriggerPxType | String | Stop-loss trigger price type. last : last priceindex : index pricemark : mark price |
slOrdPx | String | Stop-loss order price. |
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 |
source | String | Order source 13 :The generated limit order after the strategy order is triggered |
rebate | String | Rebate amount, the reward of placing orders from the platform (rebate) given to user who has reached the specified trading level. If there is no rebate, this field is "". |
category | String | Categorynormal twap adl full_liquidation partial_liquidation delivery ddh |
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 typeSPOT MARGIN SWAP FUTURES OPTION |
uly | String | No | Underlying |
instId | String | No | Instrument ID, e.g. BTC-USD-200927 |
ordType | String | No | Order typemarket : Market orderlimit : Limit orderpost_only : Post-only orderfok : Fill-or-kill orderioc : Immediate-or-cancel order Optimal_limit_ioc :Market order with immediate-or-cancel order |
state | String | No | Statelive partially_filled |
after | String | No | Pagination of data to return records earlier than the requested ordId |
before | String | No | Pagination of data to return records newer than the requested ordId |
limit | String | No | Number of results per request. The maximum is 100 ; The default is 100 |
Response Example
{
"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": "",
"slTriggerPxType": "last",
"state": "live",
"sz": "1",
"tag": "",
"tgtCcy": "",
"tdMode": "cross",
"source":"",
"tpOrdPx": "",
"tpTriggerPx": "",
"tpTriggerPxType": "last",
"tradeId": "",
"uTime": "1618235248028"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument type |
instId | String | Instrument ID |
tgtCcy | String | Quantity typebase_ccy : Base currency ,quote_ccy : Quote currency Only applicable to SPOT traded with Market order |
ccy | String | Margin currency Only applicable to cross MARGIN orders in Single-currency margin . |
ordId | String | Order ID |
clOrdId | String | Client-supplied order ID |
tag | String | Order tag |
px | String | Price |
sz | String | Quantity to buy or sell |
pnl | String | Profit and loss |
ordType | String | Order typemarket : Market orderlimit : Limit orderpost_only : Post-only orderfok : Fill-or-kill orderioc : Immediate-or-cancel order 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 | Statelive partially_filled |
lever | String | Leverage, from 0.01 to 125 .Only applicable to MARGIN/FUTURES/SWAP |
tpTriggerPx | String | Take-profit trigger price. |
tpTriggerPxType | String | Take-profit trigger price type. last : last priceindex : index pricemark : mark price |
tpOrdPx | String | Take-profit trigger price. |
slTriggerPx | String | Stop-loss trigger price. |
slTriggerPxType | String | Stop-loss trigger price type. last : last priceindex : index pricemark : mark price |
slOrdPx | String | Stop-loss order price. |
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 |
source | String | Order source 13 :The generated limit order after the strategy order is triggered |
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 typeSPOT MARGIN SWAP FUTURES OPTION |
uly | String | No | Underlying |
instId | String | No | Instrument ID, e.g. BTC-USD-190927 |
ordType | String | No | Order typemarket : market orderlimit : limit orderpost_only : Post-only orderfok : Fill-or-kill orderioc : Immediate-or-cancel order optimal_limit_ioc :Market order with immediate-or-cancel order |
state | String | No | Statecanceled filled |
category | String | No | Category twap adl full_liquidation partial_liquidation delivery ddh |
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 |
Response Example
{
"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": "",
"tpTriggerPxType": "last",
"tpOrdPx": "",
"slTriggerPx": "",
"slTriggerPxType": "last",
"slOrdPx": "",
"feeCcy": "",
"fee": "",
"rebateCcy": "",
"source":"",
"rebate": "",
"tgtCcy":"",
"pnl": "",
"category": "",
"uTime": "1597026383085",
"cTime": "1597026383085"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument type |
instId | String | Instrument ID |
tgtCcy | String | Quantity typebase_ccy : Base currency ,quote_ccy : Quote currency Only applicable to SPOT traded with Market order |
ccy | String | Margin currency Only applicable to cross MARGIN orders in Single-currency margin . |
ordId | String | Order ID |
clOrdId | String | Client-supplied order ID |
tag | String | Order tag |
px | String | Price |
sz | String | Quantity to buy or sell |
ordType | String | Order typemarket : market orderlimit : limit orderpost_only : Post-only orderfok : Fill-or-kill orderioc : Immediate-or-cancel order 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. |
tpTriggerPxType | String | Take-profit trigger price type. last : last priceindex : index pricemark : mark price |
tpOrdPx | String | Take-profit trigger price. |
slTriggerPx | String | Stop-loss trigger price. |
slTriggerPxType | String | Stop-loss trigger price type. last : last priceindex : index pricemark : mark price |
slOrdPx | String | Stop-loss order price. |
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 |
source | String | Order source 13 :The generated limit order after the strategy order is triggered |
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 ddh |
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.
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 typeSPOT MARGIN SWAP FUTURES OPTION |
uly | String | No | Underlying |
instId | String | No | Instrument ID, e.g. BTC-USD-200927 |
ordType | String | No | Order typemarket : Market orderlimit : Limit orderpost_only : Post-only orderfok : Fill-or-kill orderioc : Immediate-or-cancel order optimal_limit_ioc :Market order with immediate-or-cancel order |
state | String | No | Statecanceled filled |
category | String | No | Category twap adl full_liquidation partial_liquidation delivery ddh |
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 |
Response Example
{
"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": "",
"tpTriggerPxType": "last",
"tpOrdPx": "",
"slTriggerPx": "",
"slTriggerPxType": "last",
"slOrdPx": "",
"feeCcy": "",
"fee": "",
"rebateCcy": "",
"source":"",
"rebate": "",
"tgtCcy":"",
"pnl": "",
"category": "",
"uTime": "1597026383085",
"cTime": "1597026383085"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument type |
instId | String | Instrument ID |
tgtCcy | String | Quantity typebase_ccy : Base currency ,quote_ccy : Quote currency Only applicable to SPOT traded with Market order |
ccy | String | Margin currency Only applicable to cross MARGIN orders in Single-currency margin . |
ordId | String | Order ID |
clOrdId | String | Client-supplied order ID |
tag | String | Order tag |
px | String | Price |
sz | String | Quantity to buy or sell |
ordType | String | Order typemarket : Market orderlimit : Limit orderpost_only : Post-only orderfok : Fill-or-kill orderioc : Immediate-or-cancel order 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. |
tpTriggerPxType | String | Take-profit trigger price type. last : last priceindex : index pricemark : mark price |
tpOrdPx | String | Take-profit trigger price. |
slTriggerPx | String | Stop-loss trigger price. |
slTriggerPxType | String | Stop-loss trigger price type. last : last priceindex : index pricemark : mark price |
slOrdPx | String | Stop-loss order price. |
feeCcy | String | Fee currency |
fee | String | Fee |
source | String | Order source 13 :The generated limit order after the strategy order is triggered |
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 ddh |
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 typeSPOT MARGIN SWAP FUTURES OPTION |
uly | String | No | Underlying |
instId | String | No | Instrument ID, e.g. BTC-USD-190927 |
ordId | String | No | Order ID |
after | String | No | Pagination of data to return records earlier than the requested billId |
before | String | No | Pagination of data to return records newer than the requested billId |
limit | String | No | Number of results per request. The maximum is 100 ; The default is 100 |
Response Example
{
"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 sidelong short it returns net innet mode. |
execType | String | Order flow type, T : taker M : maker |
feeCcy | String | Fee currency |
fee | String | Fee |
ts | String | Data generation time, Unix timestamp format in milliseconds, e.g. 1597026383085 . |
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 typeSPOT MARGIN SWAP FUTURES OPTION |
uly | String | No | Underlying |
instId | String | No | Instrument ID, e.g. BTC-USD-190927 |
ordId | String | No | Order ID |
after | String | No | Pagination of data to return records earlier than the requested billId |
before | String | No | Pagination of data to return records newer than the requested billId |
limit | String | No | Number of results per request. The maximum is 100 ; The default is 100 |
Response Example
{
"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 sidelong short it returns net innet mode. |
execType | String | Order flow type, T : taker M : maker |
feeCcy | String | Fee currency |
fee | String | Fee |
ts | String | Data generation time, Unix timestamp format in milliseconds, e.g. 1597026383085 . |
Place algo order
The algo order includes trigger
order, oco
order, conditional
order,iceberg
order, twap
order and trailing order.
Rate Limit: 20 requests per 2 seconds
Derivatives rate limit rule: UserID +(instrumentType、underlying)
Spot & Margin rate limit rule: UserID +(instrumentType、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 ordertrigger : Trigger ordermove_order_stop : Trailing ordericeberg : Iceberg ordertwap : TWAP order |
sz | String | Yes | Quantity to buy or sell |
tag | String | No | Order tag A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 16 characters. |
reduceOnly | Boolean | No | Whether reduce position only or not, true false |
tgtCcy | String | No | Quantity typebase_ccy : Base currency ,quote_ccy : Quote currency Only applicable to SPOT traded with Market buy conditional orderDefault is quote_ccy for buy, base_ccy for sell |
Stop Order
Parameter | Type | Required | Description |
---|---|---|---|
tpTriggerPx | String | No | Take-profit trigger price If you fill in this parameter, you should fill in the take-profit order price as well. |
tpTriggerPxType | String | No | Take-profit trigger price typelast : last priceindex : index pricemark : mark priceThe Default is last |
tpOrdPx | String | No | Take-profit order price 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 If you fill in this parameter, you should fill in the stop-loss order price. |
slTriggerPxType | String | No | Stop-loss trigger price typelast : last priceindex : index pricemark : mark priceThe Default is last |
slOrdPx | String | No | Stop-loss order price 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 |
triggerPxType | String | No | Trigger price typelast : last priceindex : index pricemark : mark priceThe Default is last |
orderPx | String | No | Order Price If the price is -1, the order will be executed at the market price. |
Trailing Stop Order
Parameter | Type | Required | Description |
---|---|---|---|
callbackRatio | String | Optional | Callback price ratio , e.g. 0.01 Either callbackRatio or callbackSpread is allowed to be passed. |
callbackSpread | String | Optional | Callback price variance |
activePx | String | No | Active price |
Iceberg Order
Parameter | Type | Required | Description |
---|---|---|---|
pxVar | String | Optional | Price ratio Either pxVar or pxSpread is allowed to be passed. |
pxSpread | String | Optional | Price variance |
szLimit | String | Yes | Average amount |
pxLimit | String | Yes | Price Limit |
TWAP Order
Parameter | Type | Required | Description |
---|---|---|---|
pxVar | String | Optional | Price ratio Either pxVar or pxSpread is allowed to be passed. |
pxSpread | String | Optional | Price variance |
szLimit | String | Yes | Average amount |
pxLimit | String | Yes | Price Limit |
timeInterval | String | Yes | Time interval |
learn more about Iceberg Order & TWAP Order
Response Example
{
"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 (not including Iceberg order, TWAP order, Trailing Stop 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 +(instrumentType、underlying)
Spot & Margin rate limit rule: UserID +(instrumentType、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 |
Response Example
{
"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 (including Iceberg order, TWAP order, Trailing Stop 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 +(instrumentType、underlying)
Spot & Margin rate limit rule: UserID +(instrumentType、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 |
Response Example
{
"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 |
---|---|---|---|
ordType | String | Yes | Order type conditional : One-way stop order oco : One-cancels-the-other ordertrigger : Trigger ordermove_order_stop : Trailing ordericeberg : Iceberg ordertwap : TWAP order |
algoId | String | Optional | Algo ID |
instType | String | No | Instrument typeSPOT SWAP FUTURES MARGIN |
instId | String | No | Instrument ID, e.g. BTC-USD-190927 |
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 |
Response Example
{
"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": "",
"tpTriggerPxType": "",
"tpOrdPx": "",
"slTriggerPx": "",
"slTriggerPxType": "",
"triggerPx": "99",
"triggerPxType": "last",
"ordPx": "12",
"actualSz": "",
"actualPx": "",
"actualSide": "",
"pxVar":"",
"pxSpread":"",
"pxLimit":"",
"szLimit":"",
"timeInterval":"",
"triggerTime": "1597026383085",
"callbackRatio":"",
"callbackSpread":"",
"activePx":"",
"moveTriggerPx":"",
"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": "",
"tpTriggerPxType": "",
"tpOrdPx": "",
"slTriggerPx": "",
"slTriggerPxType": "",
"triggerPx": "99",
"triggerPxType": "last",
"ordPx": "12",
"actualSz": "",
"actualPx": "",
"actualSide": "",
"pxVar":"",
"pxSpread":"",
"pxLimit":"",
"tag": "adadadadad",
"szLimit":"",
"timeInterval":"",
"triggerTime": "1597026383085",
"callbackRatio":"",
"callbackSpread":"",
"activePx":"",
"moveTriggerPx":"",
"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 typebase_ccy : Base currency ,quote_ccy : Quote currency Only applicable to SPOT traded with Market order |
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 |
tpTriggerPxType | String | Take-profit trigger price type. last : last priceindex : index pricemark : mark price |
tpOrdPx | String | Take-profit order price, it |
slTriggerPx | String | Stop-loss trigger price, it |
slTriggerPxType | String | Stop-loss trigger price type. last : last priceindex : index pricemark : mark price |
slOrdPx | String | Stop-loss order price, it |
triggerPx | String | Trigger price |
triggerPxType | String | Trigger price type. last : last priceindex : index pricemark : mark price |
ordPx | String | Order price |
actualSz | String | Actual order quantity |
tag | String | Order tag |
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 ratio Only applicable to iceberg order or twap order |
pxSpread | String | Price variance 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 |
callbackRatio | String | Callback price ratio Only applicable to move_order_stop order |
callbackSpread | String | Callback price variance Only applicable to move_order_stop order |
activePx | String | Active price Only applicable to move_order_stop order |
moveTriggerPx | String | Trigger price Only applicable to move_order_stop order |
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 |
---|---|---|---|
ordType | String | Yes | Order type conditional : One-way stop order oco : One-cancels-the-other ordertrigger : Trigger ordermove_order_stop : Trailing ordericeberg : Iceberg ordertwap : TWAP order |
state | String | Optional | Stateeffective canceled order_failed Either state or algoId is requied |
algoId | String | Optional | Algo ID Either state or algoId is required. |
instType | String | No | Instrument typeSPOT SWAP FUTURES MARGIN |
instId | String | No | Instrument ID, e.g. BTC-USD-190927 |
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 |
Response Example
{
"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":"",
"tpTriggerPxType":"",
"tpOrdPx":"",
"slTriggerPx":"",
"slTriggerPxType":"",
"triggerPx":"99",
"triggerPxType":"last",
"ordPx":"12",
"actualSz":"",
"actualPx":"",
"actualSide":"",
"pxVar":"",
"pxSpread":"",
"pxLimit":"",
"szLimit":"",
"timeInterval":"",
"callbackRatio":"",
"callbackSpread":"",
"activePx":"",
"moveTriggerPx":"",
"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":"",
"tpTriggerPxType":"",
"tpOrdPx":"",
"slTriggerPx":"",
"slTriggerPxType":"",
"triggerPx":"99",
"triggerPxType":"last",
"ordPx":"12",
"actualSz":"",
"actualPx":"",
"actualSide":"",
"pxVar":"",
"pxSpread":"",
"pxLimit":"",
"szLimit":"",
"tag": "adadadadad",
"timeInterval":"",
"callbackRatio":"",
"callbackSpread":"",
"activePx":"",
"moveTriggerPx":"",
"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 typebase_ccy : Base currency ,quote_ccy : Quote currency Only applicable to SPOT traded with Market order |
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. |
tpTriggerPxType | String | Take-profit trigger price type. last : last priceindex : index pricemark : mark price |
tpOrdPx | String | Take-profit trigger price. |
slTriggerPx | String | Stop-loss trigger price. |
slTriggerPxType | String | Stop-loss trigger price type. last : last priceindex : index pricemark : mark price |
slOrdPx | String | Stop-loss order price. |
triggerPx | String | trigger price. |
triggerPxType | String | trigger price type. last : last priceindex : index pricemark : mark price |
ordPx | String | Order price |
actualSz | String | Actual order quantity |
actualPx | String | Actual order price |
tag | String | Order tag |
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 ratio Only applicable to iceberg order or twap order |
pxSpread | String | Price variance 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 |
callbackRatio | String | Callback price ratio Only applicable to move_order_stop order |
callbackSpread | String | Callback price variance Only applicable to move_order_stop order |
activePx | String | Active price Only applicable to move_order_stop order |
moveTriggerPx | String | Trigger price Only applicable to move_order_stop order |
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.
Rate Limit: 6 requests per second
Rate limit rule: UserID
HTTP Request
GET /api/v5/asset/currencies
Request Example
GET /api/v5/asset/currencies
Request Parameters
none
Response Example
{
"code": "0",
"msg": "",
"data": [
{
"canDep": true,
"canInternal": true,
"canWd": true,
"ccy": "USDT",
"chain": "USDT-ERC20",
"logoLink": "https://static.coinall.ltd/cdn/announce/20200522/159014965610216037408-525c-4143-8eef-003e2edf6859.png",
"mainNet": false,
"maxFee": "18.6742688",
"maxWd": "21720100",
"minFee": "9.3371344",
"minWd": "2",
"name": "Tether",
"usedWdQuota": "0",
"wdQuota": "500",
"wdTickSz": "3"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ccy | String | Currency, e.g. BTC |
name | String | Chinese name of currency |
logoLink | String | Logo link of 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 amount of currency withdrawal in a single transaction |
maxWd | String | Maximum amount of currency withdrawal in a single transaction |
wdTickSz | String | Withdrawal precision, indicating the number of digits after the decimal point |
wdQuota | String | Withdrawal limit in the past 24 hours, unit in BTC |
usedWdQuota | String | Amount of currency withdrawal used in the past 24 hours, unit in BTC |
minFee | String | Minimum withdrawal fee |
maxFee | String | Maximum withdrawal fee |
mainNet | Boolean | If current chain is main net then return true , otherwise return false |
Get balance
Retrieve the balances of all the assets and the amount that is available or on hold.
Rate Limit: 6 requests per second
Rate limit rule: UserID
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 . |
Response Example
{
"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 |
Get account asset valuation
View account asset valuation
Rate Limit: 1 request 2 seconds
Rate limit rule: UserID
HTTP Request
GET /api/v5/asset/asset-valuation
Request Example
GET /api/v5/asset/asset-valuation
Request Parameters
Parameters | Types | Required | Description |
---|---|---|---|
ccy | String | No | Asset valuation calculation unit BTC 、USDT USD 、CNY 、JPY、KRW、RUB、EUR VND 、IDR 、INR、PHP、THB、TRY AUD 、SGD 、ARS、SAR、AED、IQD The default is the valuation in BTC |
Response Example
{
"code": "0",
"data": [
{
"details": {
"classic": "124.6",
"earn": "1122.73",
"funding": "0.09",
"trading": "2544.28"
},
"totalBal": "3790.09",
"ts": "1637566660769"
}
],
"msg": ""
}
Response Parameters
Parameter | Type | Description |
---|---|---|
totalBal | String | Valuation of total account assets |
ts | String | Unix timestamp format in milliseconds, e.g.1597026383085 |
details | Array | Asset valuation details for each account |
> funding | String | funding account |
> trading | String | Trading account |
> classic | String | classic account |
> earn | String | earn account |
Funds transfer
This endpoint supports the transfer of funds between your funding account and trading account, and from the master account to sub-accounts.
Sub-account can transfer out to master account by default. Need to call "Set Permission Of Transfer Out" to grant privilege first if you want sub-account transferring to another sub-account(subaccounts need to belong to same master account.)
Rate Limit: 1 requests per second
Rate limit rule: UserID + Currency
HTTP Request
POST /api/v5/asset/transfer
Request Example
Transfer 1.5 USDT from funding account to Trading 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 1.5 USDT from funding account to subAccount when current account is sub-account
POST /api/v5/asset/transfer
body
{
"ccy":"USDT",
"type":"4",
"amt":"1.5",
"from":"6",
"to":"6",
"subAcct":"mini"
}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ccy | String | Yes | Currency, e.g. USDT |
amt | String | Yes | Amount to be transferred |
from | String | Yes | The remitting account6 : Funding account, 18 : Trading account |
to | String | Yes | The beneficiary account6 : Funding account, 18 : Trading account |
subAcct | String | Optional | Name of the sub-account When type is 1 or 2, sub-account is required. |
type | String | No | Transfer type0 : transfer within account1 : master account to sub-account(Only applicable to APIKey from master account)2 : sub-account to master account(Only applicable to APIKey from master account)3 : sub-account to master account(Only applicable to APIKey from sub-account)4 : sub-account to sub-account(Only applicable to APIKey from sub-account, and target account needs to be another sub-account which belongs to same master account) |
loanTrans | Boolean | No | Allowing borrowed crypto transfer in/out under Multi-currency margin and Portfolio margin the default is false |
clientId | String | No | Client-supplied ID A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. |
Response Example
{
"code": "0",
"msg": "",
"data": [
{
"transId": "754147",
"ccy": "USDT",
"clientId": "",
"from": "6",
"amt": "0.1",
"to": "18"
}
]
}
Response Parameters
Response Example
Parameter | Type | Description |
---|---|---|
transId | String | TransferID |
clientId | String | Client-supplied order ID |
ccy | String | Currency |
from | String | The remitting account |
amt | String | Transfer amount |
to | String | The beneficiary account |
Get funds transfer state
Rate Limit: 1 requests per second
Rate limit rule: UserID
HTTP Request
GET /api/v5/asset/transfer-state
Request Example
GET /api/v5/asset/transfer-state?transId=1&type=1
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
transId | String | Optional | Transfer ID Either transId or clientId is required. If both are passed, transId will be used. |
clientId | String | Optional | Client-supplied ID A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. |
type | String | No | Transfer type0 : transfer within account1 : master account to sub-account2 : sub-account to master accountthe default is 0 |
Response Example
{
"code": "0",
"data": [
{
"amt": "1.5",
"ccy": "USDT",
"clientId": "",
"from": "18",
"instId": "",
"state": "success",
"subAcct": "test",
"to": "6",
"toInstId": "",
"transId": "1",
"type": "1"
}
],
"msg": ""
}
Response Parameters
Parameter | Type | Description |
---|---|---|
transId | String | Transfer ID |
clientId | String | Client-supplied order ID |
ccy | String | Currency, e.g. USDT |
amt | String | Amount to be transferred |
type | String | Transfer type0 : transfer within account1 : master account to sub-account2 : sub-account to master accountthe default is 0 |
from | String | The remitting account1 : SPOT 3 : FUTURES 5 : MARGIN 6 : FUNDING 9 : SWAP 12 : OPTION 18 : Trading account |
to | String | The beneficiary account1 : SPOT 3 : FUTURES 5 : MARGIN 6 : FUNDING 9 : SWAP 12 : OPTION 18 : Trading account |
subAcct | String | Name of the sub-account |
instId | String | MARGIN trading pair (e.g. BTC-USDT ) or contract underlying (e.g. BTC-USD ) to be transferred out. |
toInstId | String | MARGIN trading pair (e.g. BTC-USDT ) or contract underlying (e.g. BTC-USD ) to be transferred in. |
state | String | Transfer statesuccess pending failed |
Asset bills details
Query the billing record, you can get the latest 1 month historical data
Rate Limit: 6 Requests per second
Rate limit rule: UserID
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 type1 : Deposit2 : Withdrawal13 : Canceled withdrawal20 : Transfer to Sub account21 : Transfer from Sub account28 : Claim41 : Trading fees settled by loyalty points42 : Loyalty points purchase47 : System reversal48 : Received from activities49 : Given away to activities50 : Received from appointments51 : Deducted from appointments52 : Red packet sent53 : Red packet snatched54 : Red packet refunded59 : Transfer from hedging account60 : Transfer to hedging account61 : Conversion68 : Claim rebate card69 : Distribute rebate card72 : Token received73 : Token given away74 : Token refunded75 : Subscription to savings76 : Redemption to savings77 : Distribute78 : Lock up79 : Node voting80 : Staking81 : Vote redemption82 : Staking redemption83 : Staking yield84 : Violation fee85 : PoW mining yield86 : Cloud mining pay87 : Cloud mining yield88 : Subsidy89 : Staking90 : Staking subscription91 : staking redemption92 : Add collateral93 : Redeem collateral94 : Investment95 : Borrower borrows96 : Principal transferred in97 : Borrower transferred loan out98 : Borrower transferred interest out99 : Investor transferred interest in102 : Prepayment penalty transferred in103 : Prepayment penalty transferred out104 : Fee transferred in105 : Fee transferred out106 : Overdue fee transferred in107 : Overdue fee transferred out108 : Overdue interest transferred out109 : Overdue interest transferred in110 : Collateral for closed position transferred in111 : Collateral for closed position transferred out112 : Collateral for liquidation transferred in113 : Collateral for liquidation transferred out114 : Insurance fund transferred in115 : Insurance fund transferred out 116 : Place an order117 : Fulfill an order118 : Cancel an order119 : Merchants unlock deposit120 : Merchants add deposit121 : FiatGateway Place an order122 : FiatGateway Cancel an order123 : FiatGateway Fulfill an order124 : Jumpstart unlocking125 : Manual deposit126 : Interest deposit127 : Investment fee transferred in128 : Investment fee transferred out129 : Rewards transferred in130 : Transferred from Trading account131 : Transferred to Trading account150 : Affiliate commission151 : Referral reward198 : Decrease in invalid assets199 : Increase in valid assets |
clientId | String | No | Client-supplied ID A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. |
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 . |
Response Example
{
"code": "0",
"msg": "",
"data": [{
"billId": "12344",
"ccy": "BTC",
"clientId": "",
"balChg": "2",
"bal": "12",
"type": "1",
"ts": "1597026383085"
}]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
billId | String | Bill ID |
ccy | String | Account balance currency |
clientId | String | Client-supplied order ID |
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 |
Lightning deposits
Users can create up to 10 thousand different invoices within 24 hours.
Rate Limit: 2 requests per seconds
Rate limit rule: UserID
HTTP Request
GET /api/v5/asset/deposit-lightning
Request Example
GET /api/v5/asset/deposit-lightning
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ccy | String | Yes | Token symbol. Currently only "BTC" is supported. |
amt | String | Yes | Deposit amount between '0.000001' - '0.1' |
to | String | No | Receiving account '6':Funding account '18':Trading account |
Response Example
{
"code": "0",
"data": [
{
"cTime": "1631171307612",
"invoice": "lnbc100u1psnnvhtpp5yq2x3q5hhrzsuxpwx7ptphwzc4k4wk0j3stp0099968m44cyjg9sdqqcqzpgxqzjcsp5hzzdszuv6yv6yw5svctl8kc8uv6y77szv5kma2kuculj86tk3yys9qyyssqd8urqgcensh9l4zwlwr3lxlcdqrlflvvlwldutm6ljx486h7lylqmd06kky6scas7warx69sregzrx20ffmsr4sp865x3wasrjd8ttgqrlx3tr"
}
],
"msg": ""
}
Response Example
Parameter | Type | Description |
---|---|---|
invoice | String | Invoice text |
cTime | String | Invoice creation time, e.g. 2021-02-25T06:42:40.000Z |
Get deposit address
Retrieve the deposit addresses of currencies, including previously-used addresses.
Rate Limit: 6 requests per second
Rate limit rule: UserID
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 |
Response Example
{
"code": "0",
"data": [
{
"chain": "BTC-Bitcoin",
"ctAddr": "",
"ccy": "BTC",
"to": "6",
"addr": "39XNxK1Ryqgg3Bsyn6HzoqV4Xji25pNkv6",
"selected": true
},
{
"chain": "BTC-OKC",
"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) |
addrEx | Object |
Deposit address attachment (This will not be returned if the currency does not required) e.g. TONCOIN attached tag name is comment , the return will be {'comment':'123456'} |
ccy | String | Currency, e.g. BTC |
chain | String | Chain name, e.g. USDT-ERC20 , USDT-TRC20 , USDT-Omni |
to | String | The beneficiary account 6 : Funding account 18 : Trading 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 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
Rate limit rule: UserID
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 |
depId | String | No | Deposit ID |
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 |
Response Example
{
"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 OKX 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 confirmation1 : deposit credited 2 : deposit successful 8 : pending due to temporary deposit suspension on this crypto currency12 : account or deposit is frozen |
depId | String | Deposit ID |
Withdrawal
Withdrawal of tokens.
Rate Limit: 6 requests per second
Rate limit rule: UserID
HTTP Request
POST /api/v5/asset/withdrawal
Request Example
POST /api/v5/asset/withdrawal
body
{
"amt":"1",
"fee":"0.0005",
"dest":"4",
"ccy":"BTC",
"chain":"BTC-Bitcoin",
"toAddr":"17DKe3kkkkiiiiTvAKKi2vMPbm1Bz3CMKw"
}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ccy | String | Yes | Currency, e.g. USDT |
amt | String | Yes | Withdrawal amount |
dest | String | Yes | Withdrawal destination address3 : OKX 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' |
fee | String | Yes | Transaction fee |
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. |
clientId | String | No | Client-supplied ID A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. |
Response Example
{
"code": "0",
"msg": "",
"data": [{
"amt": "0.1",
"wdId": "67485",
"ccy": "BTC",
"clientId": "",
"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 |
clientId | String | Client-supplied ID A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. |
Lightning withdrawals
The maximum withdrawal amount is 0.1 BTC at a time, and 1 BTC in 24 hours. The minimum withdrawal amount is approximately 0.000001 BTC.
Rate Limit: 2 requests per seconds
Rate limit rule: UserID
HTTP Request
POST /api/v5/asset/withdrawal-lightning
Request Example
POST /api/v5/asset/withdrawal-lightning
body
{
"ccy":"BTC",
"invoice":"lnbc100u1psnnvhtpp5yq2x3q5hhrzsuxpwx7ptphwzc4k4wk0j3stp0099968m44cyjg9sdqqcqzpgxqzjcsp5hz"
}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ccy | String | Yes | Token symbol. Currently only BTC is supported. |
invoice | String | Yes | Invoice text |
memo | String | No | Lightning withdrawal memo |
Response Example
{
"code": "0",
"msg": "",
"data": [{
"wdId": "121212",
"cTime": "1597026383085"
}]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
wdId | String | Withdrawal ID |
cTime | String | Withdrawal ID creation time |
Cancel withdrawal
Cancle withdrawal of tokens.
Rate Limit: 6 requests per second
Rate limit rule: UserID
HTTP Request
POST /api/v5/asset/cancel-withdrawal
Request Example
POST /api/v5/asset/cancel-withdrawal
body {
"wdId":"1123456"
}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
wdId | String | Yes | Withdrawal ID |
Response Example
{
"code": "0",
"msg": "",
"data": [
{
"wdId": "1123456"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
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
Rate limit rule: UserID
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 |
wdId | String | No | Withdrawal ID |
clientId | String | No | Client-supplied ID A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters. |
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 |
Response Example
{
"code": "0",
"msg": "",
"data": [
{
"chain": "ETH-Ethereum",
"fee": "0.007",
"ccy": "ETH",
"clientId": "",
"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 OKX 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 |
clientId | String | Client-supplied ID |
Small assets convert
Convert small assets in funding account to OKB
. Only one convert is allowed within 24 hours.
Rate Limit: 1 requests per second
Rate limit rule: UserID
HTTP Request
POST /api/v5/asset/convert-dust-assets
Request Example
POST /api/v5/asset/convert-dust-assets
body {
"ccy":["BTC","USDT"]
}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ccy | Array | Yes | Small assets needed to be convert |
Response Example
{
"code": "0",
"data": [
{
"details": [
{
"amt": "1",
"ccy": "USDT",
"cnvAmt": "0.04771642808422",
"fee": "0.00097380465478"
}
],
"totalCnvAmt": "0.04771642"
}
],
"msg": ""
}
Response Parameters
Parameter | Type | Description |
---|---|---|
totalCnvAmt | String | Total quantity of OKB after conversion |
details | Array | Details of asset conversion |
> ccy | String | Currency, e.g. BTC |
> amt | String | Quantity of currency assets before conversion |
> cnvAmt | String | Quantity of OKB after conversion |
> fee | String | Fee for conversion, unit in OKB |
Get saving balance
Only the assets in the funding account can be used for saving.
Rate Limit: 6 requests per second
Rate limit rule: UserID
HTTP Request
GET /api/v5/asset/saving-balance
Request Example
GET /api/v5/asset/saving-balance?ccy=USDT
Request Parameters
Parameters | Types | Required | Description |
---|---|---|---|
ccy | String | No | Currency, e.g. BTC |
Response Example
{
"code": "0",
"msg":"",
"data": [
{
"earnings": "0.0010737388791526",
"redemptAmt": "0.0000000000000000",
"rate": "0.0100000000000000",
"ccy": "USDT",
"amt": "11.0010737453457821",
"loanAmt": "11.0010630707982819",
"pendingAmt": "0.0000106745475002"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ccy | String | Currency |
amt | String | Currency amount |
earnings | String | Currency earnings |
rate | String | Lending rate |
loanAmt | String | Lending amount |
pendingAmt | String | Pending amount |
redemptAmt | String | Redempting amount |
Savings purchase/redemption
Rate Limit: 6 requests per second
Rate limit rule: UserID
HTTP Request
POST /api/v5/asset/purchase_redempt
Request Example
POST /api/v5/asset/purchase_redempt
body
{
"ccy":"BTC",
"amt":"1",
"side":"purchase",
"rate":"0.01"
}
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 saving sharesredempt : redeem saving shares |
rate | String | Yes | Purchase rate Only applicable to purchase saving shares The interest rate of the new subscription will cover the interest rate of the last subscription The rate value range is between 1% and 365% |
Response Example
{
"code":"0",
"msg":"",
"data":[
{
"ccy":"BTC",
"amt":"1",
"side":"purchase",
"rate": "0.01"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ccy | String | Currency |
amt | String | Purchase/Redemption amount |
side | String | Action type |
rate | String | Purchase rate |
Set lending rate
Rate Limit: 6 requests per second
Rate limit rule: UserID
HTTP Request
POST /api/v5/asset/set-lending-rate
Request Example
POST /api/v5/asset/set-lending-rate
body
{
"ccy":"BTC",
"rate":"0.02"
}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ccy | String | Yes | Currency, e.g. BTC |
rate | String | Yes | Lending rate The rate value range is between 1% and 365% |
Response Example
{
"code": "0",
"msg": "",
"data": [{
"ccy": "BTC",
"rate": "0.02"
}]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ccy | String | Currency, e.g. BTC |
rate | String | Lending rate |
Get lending history
Rate Limit: 6 requests per second
Rate limit rule: UserID
HTTP Request
GET /api/v5/asset/lending-history
Request Example
GET /api/v5/asset/lending-history
Request Parameters
Parameters | Types | Required | Description |
---|---|---|---|
ccy | String | No | Currency, e.g. BTC |
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 . |
Response Example
{
"code": "0",
"msg": "",
"data": [{
"ccy": "BTC",
"amt": "0.01",
"earnings": "0.001",
"rate": "0.01",
"ts": "1597026383085"
},
{
"ccy": "ETH",
"amt": "0.2",
"earnings": "0.001",
"rate": "0.01",
"ts": "1597026383085"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ccy | String | Currency, e.g. BTC |
amt | String | Lending amount |
earnings | String | Currency earnings |
rate | String | Lending annual interest rate |
ts | String | Lending time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Get public borrow info (public)
Authentication is not required for this public endpoint.
Rate Limit: 6 requests per second
Rate limit rule: IP
HTTP Request
GET /api/v5/asset/lending-rate-summary
Request Example
GET /api/v5/asset/lending-rate-summary
Request Parameters
Parameters | Types | Required | Description |
---|---|---|---|
ccy | String | No | Currency, e.g. BTC |
Response Example
{
"code": "0",
"msg": "",
"data": [{
"ccy": "BTC",
"avgAmt": "10000",
"avgAmtUsd": "10000000000",
"avgRate": "0.03",
"preRate": "0.02",
"estRate": "0.01"
}]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ccy | String | Currency, e.g. BTC |
avgAmt | String | 24H average borrowings |
avgAmtUsd | String | 24H average borrowings in USD value |
avgRate | String | 24H average lending rate |
preRate | String | Last annual interest rate |
estRate | String | Next estimate annual interest rate |
Get public borrow history (public)
Authentication is not required for this public endpoint.
Rate Limit: 6 requests per second
Rate limit rule: IP
HTTP Request
GET /api/v5/asset/lending-rate-history
Request Example
GET /api/v5/asset/lending-rate-history
Request Parameters
Parameters | Types | Required | Description |
---|---|---|---|
ccy | String | No | Currency, e.g. BTC |
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 . |
Response Example
{
"code": "0",
"msg": "",
"data": [{
"ccy": "BTC",
"amt": "0.01",
"rate": "0.001",
"ts": "1597026383085"
}]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ccy | String | Currency, e.g. BTC |
amt | String | Borrow amount |
rate | String | Borrow annual interest rate |
ts | String | Time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Convert
The API endpoints of Convert
require authentication. Only the assets in the funding account can be used for convert.
Get convert currencies
Rate Limit: 6 requests per second
Rate limit rule: UserID
HTTP Request
GET /api/v5/asset/convert/currencies
Request Example
GET /api/v5/asset/convert/currencies
Request Parameters
none
Response Example
{
"code": "0",
"data": [
{
"min": "0.0001",
"max": "0.5",
"ccy": "BTC"
},
{
"min": "0.001",
"max": "10.0",
"ccy": "ETH"
}
],
"msg": ""
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ccy | String | Currency, e.g. BTC |
min | String | Minimum amount of convert |
max | String | Maximum amount of convert |
Get convert currency pair
Rate Limit: 6 requests per second
Rate limit rule: UserID
HTTP Request
GET /api/v5/asset/convert/currency-pair
Request Example
GET /api/v5/asset/convert/currency-pair?fromCcy=USDT&toCcy=BTC
Request Parameters
Parameters | Types | Required | Description |
---|---|---|---|
fromCcy | String | Yes | Consuming currency, e.g. USDT |
toCcy | String | Yes | Obtaining currency, e.g. BTC |
Response Example
{
"code": "0",
"data": [
{
"baseCcy": "BTC",
"baseCcyMax": "0.5",
"baseCcyMin": "0.0001",
"instId": "BTC-USDT",
"quoteCcy": "USDT",
"quoteCcyMax": "10000",
"quoteCcyMin": "1"
}
],
"msg": ""
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instId | String | Currency pair, e.g. BTC-USDT |
baseCcy | String | Base currency, e.g. BTC |
baseCcyMax | String | Maximum amount of base currency |
baseCcyMin | String | Minimum amount of base currency |
quoteCcy | String | Quote currency, e.g. USDT |
quoteCcyMax | String | Maximum amount of quote currency |
quoteCcyMin | String | Minimum amount of quote currency |
Estimate quote
Rate Limit: 2 requests per second
Rate limit rule: UserID
HTTP Request
POST /api/v5/asset/convert/estimate-quote
Request Example
POST /api/v5/asset/convert/estimate-quote
body
{
"baseCcy": "ETH",
"quoteCcy": "USDT",
"side": "buy",
"rfqSz": "30",
"rfqSzCcy": "USDT"
}
Request Parameters
Parameters | Types | Required | Description |
---|---|---|---|
baseCcy | String | Yes | Base currency, e.g. BTC |
quoteCcy | String | Yes | Quote currency, e.g. USDT |
side | String | Yes | Trade side based on baseCcy buy sell |
rfqSz | String | Yes | RFQ amount |
rfqSzCcy | String | Yes | RFQ currency |
clQReqId | 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 |
Response Example
{
"code": "0",
"data": [
{
"baseCcy": "ETH",
"baseSz": "0.01023052",
"clQReqId": "",
"cnvtPx": "2932.40104429",
"origRfqSz": "30",
"quoteCcy": "USDT",
"quoteId": "quoterETH-USDT16461885104612381",
"quoteSz": "30",
"quoteTime": "1646188510461",
"rfqSz": "30",
"rfqSzCcy": "USDT",
"side": "buy",
"ttlMs": "10000"
}
],
"msg": ""
}
Response Parameters
Parameter | Type | Description |
---|---|---|
quoteTime | String | Quotation generation time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
ttlMs | String | Validity period of quotation in milliseconds |
clQReqId | String | Client-supplied order ID |
quoteId | String | Quote ID |
baseCcy | String | Base currency, e.g. BTC |
quoteCcy | String | Quote currency, e.g. USDT |
side | String | Trade side based on baseCcy |
origRfqSz | String | Original RFQ amount |
rfqSz | String | Real RFQ amount |
rfqSzCcy | String | RFQ currency |
cnvtPx | String | Convert price based on quote currency |
baseSz | String | Convert amount of base currency |
quoteSz | String | Convert amount of quote currency |
Convert trade
Rate Limit: 2 requests per second
Rate limit rule: UserID
HTTP Request
POST /api/v5/asset/convert/trade
Request Example
POST /api/v5/asset/convert/trade
body
{
"baseCcy": "ETH",
"quoteCcy": "USDT",
"side": "buy",
"sz": "30",
"szCcy": "USDT",
"quoteId": "quoterETH-USDT16461885104612381"
}
Request Parameters
Parameters | Types | Required | Description |
---|---|---|---|
quoteId | String | Yes | Quote ID |
baseCcy | String | Yes | Base currency, e.g. BTC |
quoteCcy | String | Yes | Quote currency, e.g. USDT |
side | String | Yes | Trade side based on baseCcy buy sell |
sz | String | Yes | Quote amount The quote amount should no more then RFQ amount |
szCcy | String | Yes | Quote currency |
clTReqId | 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 |
Response Example
{
"code": "0",
"data": [
{
"baseCcy": "ETH",
"clTReqId": "",
"fillBaseSz": "0.01023052",
"fillPx": "2932.40104429",
"fillQuoteSz": "30",
"instId": "ETH-USDT",
"quoteCcy": "USDT",
"quoteId": "quoterETH-USDT16461885104612381",
"side": "buy",
"state": "fullyFilled",
"tradeId": "trader16461885203381437",
"ts": "1646188520338"
}
],
"msg": ""
}
Response Parameters
Parameter | Type | Description |
---|---|---|
tradeId | String | Trade ID |
quoteId | String | Quote ID |
clTReqId | String | Client-supplied order ID |
state | String | Trade statefullyFilled : success rejected : failed |
instId | String | Currency pair, e.g. BTC-USDT |
baseCcy | String | Base currency, e.g. BTC |
quoteCcy | String | Quote currency, e.g. USDT |
side | String | Trade side based on baseCcy buy sell |
fillPx | String | Filled price based on base currency |
fillBaseSz | String | Filled amount for base currency |
fillQuoteSz | String | Filled amount for quote currency |
ts | String | Convert trade time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Get convert history
Rate Limit: 6 requests per second
Rate limit rule: UserID
HTTP Request
GET /api/v5/asset/convert/history
Request Example
GET /api/v5/asset/convert/history
Request Parameters
Parameters | Types | Required | Description |
---|---|---|---|
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 . |
tag | String | No | Order tag |
Response Example
{
"code": "0",
"data": [
{
"instId": "ETH-USDT",
"side": "buy",
"fillPx": "2932.401044",
"baseCcy": "ETH",
"quoteCcy": "USDT",
"fillBaseSz": "0.01023052",
"state": "fullyFilled",
"tradeId": "trader16461885203381437",
"fillQuoteSz": "30",
"ts": "1646188520000"
}
],
"msg": ""
}
Response Parameters
Parameter | Type | Description |
---|---|---|
tradeId | String | Trade ID |
state | String | Trade statefullyFilled : success rejected : failed |
instId | String | Currency pair, e.g. BTC-USDT |
baseCcy | String | Base currency, e.g. BTC |
quoteCcy | String | Quote currency, e.g. USDT |
side | String | Trade side based on baseCcy buy sell |
fillPx | String | Filled price based on base currency |
fillBaseSz | String | Filled amount for base currency |
fillQuoteSz | String | Filled amount for quote currency |
ts | String | Convert trade time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
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 trading account.
Rate Limit: 10 requests per 2 seconds
Rate limit rule: UserID
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 . |
Response Example
{
"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 and Portfolio margin |
adjEq | String | Adjusted/Effective equity in USD level Applicable to Multi-currency margin and Portfolio margin |
ordFroz | String | Margin frozen for pending orders in USD level Applicable to Multi-currency margin and Portfolio margin |
imr | String | Frozen equity for open positions and pending orders in USD level Applicable to Multi-currency margin and Portfolio margin |
mmr | String | Maintenance margin requirement in USD level Applicable to Multi-currency margin and Portfolio margin |
mgnRatio | String | Margin ratio in USD level Applicable to Multi-currency margin and Portfolio margin |
notionalUsd | String | Quantity of positions usd Applicable to Multi-currency margin and Portfolio 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 and Portfolio margin |
> availEq | String | Available equity of the currency Applicable to Single-currency margin and Multi-currency margin and Portfolio 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 and Portfolio margin |
> upl | String | Unrealized profit and loss of the currency Applicable to Single-currency margin and Multi-currency margin and Portfolio margin |
> uplLib | String | Liabilities due to Unrealized loss of the currency Applicable to Multi-currency margin and Portfolio margin |
> crossLiab | String | Cross Liabilities of the currency Applicable to Multi-currency margin and Portfolio margin |
> isoLiab | String | Isolated Liabilities of the currency Applicable to Multi-currency margin and Portfolio margin |
> mgnRatio | String | Margin ratio of the currency Applicable to Single-currency margin |
> interest | String | Interest of the currency Applicable to Multi-currency margin and Portfolio margin |
> twap | String | System is 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 and Portfolio margin and Portfolio margin |
> maxLoan | String | Max loan of the currency Applicable to Multi-currency margin and Portfolio 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 and Portfolio 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
Rate limit rule: UserID
HTTP Request
GET /api/v5/account/positions
Request Example
Query BTC-USDT position information
GET /api/v5/account/positions?instId=BTC-USDT
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instType | String | No | Instrument typeMARGIN SWAP FUTURES OPTION instId will be checked against instType when both parameters are passed, and the position information of the instId will be returned. |
instId | String | No | Instrument ID, e.g. BTC-USD-190927-5000-C .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 |
Response Example
{
"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",
"usdPx":"",
"last":"2566.22",
"lever":"10",
"liab":"",
"liabCcy":"",
"liqPx":"2352.8496681818233",
"markPx":"2353.849",
"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 modecross isolated |
posId | String | Position ID |
posSide | String | Position sidelong short net (FUTURES/SWAP/OPTION : positive pos means long position and negative pos means short position. MARGIN : posCcy being base currency means long position, posCcy being quote currency means short position.) |
pos | String | Quantity of positions,In the mode of autonomous transfer from position to position, after the deposit is transferred, a position with pos of 0 will be generated |
baseBal | String | Base currency balance, only applicable to MARGIN (Manual transfers) |
quoteBal | String | Quote currency balance, only applicable to MARGIN (Manual transfers) |
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 |
markPx | String | Mark 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 |
usdPx | String | USD 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
Rate limit rule: UserID
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 |
Response Example
{
"code":"0",
"data":[
{
"adjEq":"174238.6793649711331679",
"balData":[
{
"ccy":"BTC",
"disEq":"78846.7803721021362242",
"eq":"1.3863533369419636"
},
{
"ccy":"USDT",
"disEq":"73417.2495112863300127",
"eq":"73323.395564963177146"
}
],
"posData":[
{
"baseBal": "0.4",
"ccy": "",
"instId": "BTC-USDT",
"instType": "MARGIN",
"mgnMode": "isolated",
"notionalCcy": "0",
"notionalUsd": "0",
"pos": "0",
"posCcy": "",
"posId": "310388685292318723",
"posSide": "net",
"quoteBal": "0"
}
],
"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 and Portfolio 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. |
posData | Array | Detailed position information in all currencies |
> instType | String | Instrument type |
> mgnMode | String | Margin modecross isolated |
> posId | String | Position ID |
> instId | String | Instrument ID, e.g. BTC-USD-180216 |
> pos | String | Quantity of positions contract ,In the mode of autonomous transfer from position to position, after the deposit is transferred, a position with pos of 0 will be generated |
> baseBal | String | Base currency balance, only applicable to MARGIN (Manual transfers) |
> quoteBal | String | Quote currency balance, only applicable to MARGIN (Manual transfers) |
> posSide | String | Position sidelong short net (FUTURES/SWAP/OPTION : positive pos means long position and negative pos means short position. MARGIN : posCcy being base currency means long position, posCcy being quote currency means short position.) |
> 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
Rate limit rule: UserID
HTTP Request
GET /api/v5/account/bills
Request Example
GET /api/v5/account/bills
GET /api/v5/account/bills?instType=MARGIN
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instType | String | No | Instrument typeSPOT MARGIN SWAP FUTURES OPTION |
ccy | String | No | Currency |
mgnMode | String | No | Margin modeisolated cross |
ctType | String | No | Contract typelinear inverse Only applicable to FUTURES/SWAP |
type | String | No | Bill type1 : Transfer 2 : Trade 3 : Delivery 4 : 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 13 : ddh |
subType | String | No | Bill subtype1 : Buy 2 : Sell 3 : Open long 4 : Open short 5 : Close long 6 : Close short 9 : Interest deduction for Market loans 11 : Transfer in 12 : Transfer out 14 : Interest deduction for VIP loans 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 131 : ddh buy 132 : ddh 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 . |
Response Example
{
"code": "0",
"msg": "",
"data": [{
"bal": "256.27611382",
"balChg": "256.27611382",
"billId": "374241568911437826",
"ccy": "GODS",
"execType": "",
"fee": "",
"from": "1",
"instId": "",
"instType": "",
"mgnMode": "",
"notes": "From 币币账户",
"ordId": "",
"pnl": "",
"posBal": "",
"posBalChg": "",
"subType": "11",
"sz": "256.27611382",
"to": "18",
"ts": "1635498143100",
"type": "1"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument type |
billId | String | Bill ID |
type | String | Bill type |
subType | String | Bill subtype |
ts | String | Creation time, Unix timestamp format in milliseconds, e.g.1597026383085 |
balChg | String | Change in balance amount at the account level |
posBalChg | String | Change in balance amount at the position level |
bal | String | Balance at the account level |
posBal | String | Balance at the position level |
sz | String | Quantity |
ccy | String | Account balance currency |
pnl | String | Profit and loss |
fee | String | Fee Negative number represents the user transaction fee charged by the platform. Positive number represents rebate. |
mgnMode | String | Margin modeisolated cross When bills are not generated by position changes, the field returns "" |
instId | String | Instrument ID, e.g. BTC-USD-190927-5000-C |
ordId | String | Order ID When bill type is not trade , the field returns "" |
execType | String | Order flow type, T :taker M :maker |
from | String | The remitting account6 : FUNDING 18 : Trading accountWhen bill type is not transfer , the field returns "". |
to | String | The beneficiary account6 : FUNDING 18 : Trading accountWhen 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
Rate limit rule: UserID
HTTP Request
GET /api/v5/account/bills-archive
Request Example
GET /api/v5/account/bills-archive
GET /api/v5/account/bills-archive?instType=MARGIN
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instType | String | No | Instrument typeSPOT MARGIN SWAP FUTURES OPTION |
ccy | String | No | Currency |
mgnMode | String | No | Margin modeisolated cross |
ctType | String | No | Contract typelinear inverse Only applicable to FUTURES/SWAP |
type | String | No | Bill type1 : Transfer 2 : Trade 3 : Delivery 4 : 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 13 : ddh |
subType | String | No | Bill subtype1 : Buy 2 : Sell 3 : Open long 4 : Open short 5 : Close long 6 : Close short 9 : Interest deduction for Market loans 11 : Transfer in 12 : Transfer out 14 : Interest deduction for VIP loans 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 131 : ddh buy 132 : ddh sell170 : 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 . |
Response Example
{
"code": "0",
"msg": "",
"data": [{
"bal": "256.27611382",
"balChg": "256.27611382",
"billId": "374241568911437826",
"ccy": "GODS",
"execType": "",
"fee": "",
"from": "1",
"instId": "",
"instType": "",
"mgnMode": "",
"notes": "From 币币账户",
"ordId": "",
"pnl": "",
"posBal": "",
"posBalChg": "",
"subType": "11",
"sz": "256.27611382",
"to": "18",
"ts": "1635498143100",
"type": "1"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument type |
billId | String | Bill ID |
type | String | Bill type |
subType | String | Bill subtype |
ts | String | Creation time, Unix timestamp format in milliseconds, e.g.1597026383085 |
balChg | String | Change in balance amount at the account level |
posBalChg | String | Change in balance amount at the position level |
bal | String | Balance at the account level |
posBalChg | String | Balance at the position level |
sz | String | The number |
ccy | String | Account balance currency |
pnl | String | Profit and loss |
fee | String | Fee Negative number represents the user transaction fee charged by the platform. Positive number represents rebate. |
mgnMode | String | Margin modeisolated cross When bills are not generated by position changes, the field returns "" |
instId | String | Instrument ID, e.g. BTC-USD-190927-5000-C |
ordId | String | Order ID When bill type is not trade , the field returns "" |
execType | String | Order flow type, T :taker M :maker |
from | String | The remitting account6 : FUNDING 18 : Trading accountWhen bill type is not transfer , the field returns "". |
to | String | The beneficiary account6 : FUNDING 18 : Trading accountWhen 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
Rate limit rule: UserID
HTTP Request
GET /api/v5/account/config
Request Example
GET /api/v5/account/config
Request Parameters
none
Response Example
{
"code": "0",
"data": [
{
"acctLv": "3",
"autoLoan": true,
"ctIsoMode": "automatic",
"greeksType": "PA",
"level": "Lv3",
"levelTmp": "",
"mgnIsoMode": "autonomy",
"posMode": "net_mode",
"uid": "781767883763712"
}
],
"msg": ""
}
Response Parameters
Parameter | Type | Description |
---|---|---|
uid | String | Account ID |
acctLv | String | Account level 1 : Simple 2 : Single-currency margin 3 : Multi-currency margin 4 :Portfolio margin |
posMode | String | Position modelong_short_mode : long/short, only applicable to FUTURES/SWAP net_mode : net |
autoLoan | Boolean | Whether to borrow coins automaticallytrue : borrow coins automatically false : not borrow coins automatically |
greeksType | String | Current display type of GreeksPA : Greeks in coins BS : Black-Scholes Greeks in dollars |
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 |
ctIsoMode | String | Contract isolated margin trading settingsautomatic :Auto transfers autonomy :Manual transfers |
mgnIsoMode | String | Margin isolated margin trading settingsautomatic :Auto transfers autonomy :Manual transfers |
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
Rate limit rule: UserID
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 modelong_short_mode : long/short, only applicable to FUTURES/SWAP net_mode : net |
Response Example
{
"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
Rate limit rule: UserID
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 Required when setting the leverage of automatic borrowing coin. |
lever | String | Yes | Leverage |
mgnMode | String | Yes | Margin modeisolated cross Only can be cross if ccy is passed. |
posSide | String | Optional | Position sidelong short net Only applicable to isolated margin mode of FUTURES/SWAP Required in long/short mode and when margin mode is isolated , only long or short can be passed, default is net . |
Response Example
{
"code": "0",
"msg": "",
"data": [
{
"lever": "30",
"mgnMode": "isolated",
"instId": "BTC-USDT-SWAP",
"posSide": "long"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
lever | String | Leverage |
mgnMode | String | Margin modecross isolated |
instId | String | Instrument ID |
posSide | String | Position side |
Get maximum buy/sell amount or open amount
Rate Limit: 20 requests per 2 seconds
Rate limit rule: UserID
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,ETH-USDT |
tdMode | String | Yes | Trade modecross isolated cash |
ccy | String | Optional | Currency used for margin Only applicable to MARGIN of Single-currency margin . |
px | String | No | Price When the price is not specified, it will be calculated according to the last traded price. The parameter will be ignored when multiple instruments are specified. |
leverage | String | No | Leverage for instrument The default is current leverage Only applicable to MARGIN/FUTURES/SWAP |
Response Example
{
"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/MARGIN : The maximum number of coins that you can buyThe cross margin order under Single-currency margin mode, number of coins is based on base currency.FUTURES /SWAP /OPTIONS : The maximum number of contracts that you can buy |
maxSell | String | SPOT/MARGIN : The maximum number of coins that you can sellThe cross margin order under Single-currency margin mode, number of coins is based on base currency.FUTURES /SWAP /OPTIONS : The maximum number of contracts that you can sell |
Get maximum available tradable amount
Rate Limit: 20 requests per 2 seconds
Rate limit rule: UserID
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 | Single instrument or multiple instruments (no more than 5) separated with comma, e.g. BTC-USDT,ETH-USDT |
ccy | String | Optional | Currency used for margin Only applicable to cross MARGIN of Single-currency margin . |
tdMode | String | Yes | Trade modecross isolated cash |
reduceOnly | Boolean | No | Whether to reduce position only Only applicable to MARGIN |
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. |
Response Example
{
"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. Margin reduction may result in the change of the actual leverage.
Rate Limit: 20 requests per 2 seconds
Rate limit rule: UserID
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 | add : add marginreduce : reduce margin |
amt | String | Yes | Amount to be increased or decreased. |
ccy | String | No | Currency, only applicable to MARGIN (Manual transfers) |
auto | Boolean | No | Automatic loan transfer out, true or false ,the default is false only applicable to MARGIN (Manual transfers) |
loanTrans | Boolean | No | Allowing borrowed crypto transfer in/out under Multi-currency margin and Portfolio margin the default is false |
Response Example
{
"code": "0",
"msg": "",
"data": [{
"amt": "0.3",
"ccy": "BTC",
"instId": "BTC-USDT",
"leverage": "",
"posSide": "net",
"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 | add : add marginreduce : reduce margin |
leverage | String | Real leverage after the margin adjustment |
ccy | String | Currency |
Get leverage
Rate Limit: 20 requests per 2 seconds
Rate limit rule: UserID
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 modecross isolated |
Response Example
{
"code": "0",
"msg": "",
"data": [{
"instId": "BTC-USDT-200626",
"mgnMode": "cross",
"posSide": "long",
"lever": "10"
},{
"instId": "BTC-USDT-200626",
"mgnMode": "cross",
"posSide": "short",
"lever": "10"
}]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instId | String | Instrument ID |
mgnMode | String | Margin mode |
posSide | String | Position sidelong short net 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
Rate limit rule: UserID
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 | Single instrument or multiple instruments (no more than 5) separated with comma, e.g. BTC-USDT,ETH-USDT |
mgnMode | String | Yes | Margin modeisolated cross |
mgnCcy | String | Optional | Margin currency Only applicable to cross MARGIN in Single-currency margin |
Response Example
{
"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 sidebuy sell |
Get fee rates
Rate Limit: 5 requests per 2 seconds
Rate limit rule: UserID
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
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instType | String | Yes | Instrument typeSPOT MARGIN SWAP FUTURES OPTION |
instId | String | No | Instrument ID, e.g. BTC-USDT only applicable to SPOT/MARGIN |
uly | String | No | Underlying, e.g. BTC-USD only applicable to FUTURES/SWAP/OPTION |
Response Example
{
"code": "0",
"msg": "",
"data": [{
"category": "1",
"delivery": "",
"exercise": "",
"instType": "SPOT",
"level": "lv1",
"maker": "-0.0008",
"makerU": "",
"taker": "-0.001",
"takerU": "",
"ts": "1608623351857"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
category | String | Fee Schedule |
taker | String | Taker fee rate. It is the fee rate of crypto-margined contracts for futrues and swap |
maker | String | Maker fee rate. It is the fee rate of crypto-margined contracts for futures and swap |
takerU | String | Taker fee rate of USDT-margined contracts, only applicable to FUTURES/SWAP |
makerU | String | Maker fee rate of USDT-margined contracts, only applicable to FUTURES/SWAP |
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 data
Rate Limit: 5 requests per 2 seconds
Rate limit rule: UserID
HTTP Request
GET /api/v5/account/interest-accrued
Request Example
GET /api/v5/account/interest-accrued
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
type | String | No | Loan type1 : VIP loans2 : Market loansDefault is Market loans |
ccy | String | No | Loan currency, e.g. BTC Only applicable to Market loans Only applicable to MARGIN |
instId | String | No | Instrument ID, e.g. BTC-USDT Only applicable to Market loans |
mgnMode | String | No | Margin modecross isolated Only applicable to Market loans |
after | String | No | Pagination of data to return records earlier than the requested timestamp, Unix timestamp format in milliseconds, e.g. 1597026383085 |
before | String | No | Pagination of data to return records newer than the requested, Unix timestamp format in milliseconds, e.g. 1597026383085 |
limit | String | No | Number of results per request. The maximum is 100 . The default is 100 . |
Response Example
{
"code": "0",
"data": [
{
"ccy": "USDT",
"instId": "",
"interest": "0.0003960833333334",
"interestRate": "0.0000040833333333",
"liab": "97",
"mgnMode": "",
"ts": "1637312400000",
"type": "1"
}
{
"ccy": "USDT",
"instId": "",
"interest": "0.0004083333333334",
"interestRate": "0.0000040833333333",
"liab": "100",
"mgnMode": "",
"ts": "1637049600000",
"type": "1"
}
],
"msg": ""
}
Response Parameters
Parameter | Type | Description |
---|---|---|
type | String | Loan type1 : VIP loans2 : Market loans |
ccy | String | Loan currency, e.g. BTC |
instId | String | Instrument ID, e.g. BTC-USDT Only applicable to Market loans |
mgnMode | String | Margin modecross isolated |
interest | String | Interest |
interestRate | String | Interest rate (in hour) |
liab | String | Liability |
ts | String | Timestamp for interest accured, 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
Rate limit rule: UserID
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 | Currency, e.g. BTC |
{
"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
Rate limit rule: UserID
HTTP Request
POST /api/v5/account/set-greeks
Request Example
POST /api/v5/account/set-greeks
body
{
"greeksType":"PA"
}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
greeksType | String | Yes | Display type of Greeks.PA : Greeks in coinsBS : Black-Scholes Greeks in dollars |
Response Example
{
"code": "0",
"msg": "",
"data": [{
"greeksType": "PA"
}]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
greeksType | String | Display type of Greeks. |
Isolated margin trading settings
You can set the currency margin and futures/perpetual Isolated margin trading mode
Rate Limit: 5 requests per 2 seconds
Rate limit rule: UserID
HTTP Request
POST /api/v5/account/set-isolated-mode
Request Example
POST /api/v5/account/set-isolated-mode
body
{
"isoMode":"automatic",
"type":"MARGIN"
}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
isoMode | String | Yes | Isolated margin trading settings automatic :Auto transfers autonomy :Manual transfers |
type | String | Yes | Instrument typeMARGIN CONTRACTS |
Response Example
{
"code": "0",
"data": [
{
"isoMode": "autonomy"
}
],
"msg": ""
}
Response Parameters
Parameter | Type | Description |
---|---|---|
isoMode | String | Isolated margin trading settings automatic :Auto transfers autonomy :Manual transfers |
Get maximum withdrawals
Retrieve the maximum transferable amount from trading account to funding account.
Rate Limit: 20 requests per 2 seconds
Rate limit rule: UserID
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 | Single currency or multiple currencies (no more than 20) separated with comma, e.g. BTC or BTC,ETH . |
Response Example
{
"code": "0",
"msg": "",
"data": [{
"ccy": "BTC",
"maxWd": "124",
"maxWdEx": "125"
},
{
"ccy": "ETH",
"maxWd": "10",
"maxWdEx": "12"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ccy | String | Currency |
maxWd | String | Max withdrawal (not allowing borrowed crypto transfer out under Multi-currency margin ) |
maxWdEx | String | Max withdrawal (allowing borrowed crypto transfer out under Multi-currency margin ) |
Get account risk state
Only applicable to Portfolio margin account
Rate Limit: 10 requests per 2 seconds
Rate limit rule: UserID
HTTP Requests
GET /api/v5/account/risk-state
Request Example
GET /api/v5/account/risk-state
Response Example
{
"code": "0",
"data": [
{
"atRisk": false,
"atRiskIdx": [],
"atRiskMgn": [],
"ts": "1635745078794"
}
],
"msg": ""
}
Response Parameters
Parameters | Types | Description |
---|---|---|
atRisk | String | Is the account currently at risk true ; false |
atRiskIdx | Array | derivatives risk unit list |
atRiskMgn | Array | margin risk unit list |
ts | String | Unix timestamp format in milliseconds, e.g.1597026383085 |
VIP loans borrow and repay
Rate Limit: 6 requests per second
Rate limit rule: UserID
HTTP Request
POST /api/v5/account/borrow-repay
Request Example
POST /api/v5/account/borrow-repay
body
{
"ccy":"USDT",
"side":"borrow",
"amt":"100"
}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ccy | String | Yes | Loan currency, e.g. BTC |
Response Example
{
"code": "0",
"data": [
{
"amt": "102",
"availLoan": "97",
"ccy": "USDT",
"loanQuota": "6000000",
"posLoan": "0",
"side": "repay",
"usedLoan": "97"
}
],
"msg": ""
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ccy | String | Loan currency, e.g. BTC |
side | String | borrow repay |
amt | String | borrow/repay amount |
loanQuota | String | Borrow limit |
posLoan | String | Frozen amount for current account |
availLoan | String | Available amount for current account |
usedLoan | String | Borrowed amount for current account |
Get borrow and repay history for VIP loans
Rate Limit: 5 requests per 2 seconds
Rate limit rule: UserID
HTTP Request
GET /api/v5/account/borrow-repay-history
Request Example
GET /api/v5/account/borrow-repay-history
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ccy | String | No | Loan currency, e.g. BTC |
after | String | No | Pagination of data to return records earlier than the requested timestamp, Unix timestamp format in milliseconds, e.g. 1597026383085 |
before | String | No | Pagination of data to return records newer than the requested, Unix timestamp format in milliseconds, e.g. 1597026383085 |
limit | String | No | Number of results per request. The maximum is 100 . The default is 100 . |
Response Example
{
"code": "0",
"data": [
{
"ccy": "USDT",
"tradedLoan": "102",
"ts": "1637310691470",
"type": "2",
"usedLoan": "97"
},
{
"ccy": "USDT",
"tradedLoan": "102",
"ts": "1637050435058",
"type": "2",
"usedLoan": "199"
}
],
"msg": ""
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ccy | String | Loan currency, e.g. BTC |
type | String | Type1 : borrow2 : repay3 : Loan reversed, lack of balance for interest |
tradedLoan | String | Borrow/Repay amount |
usedLoan | String | Borrowed amount for current account |
ts | String | Timestamp for Borrow/Repay |
Get borrow interest and limit
Rate Limit: 5 requests per 2 seconds
Rate limit rule: UserID
HTTP Request
GET /api/v5/account/interest-limits
Request Example
GET /api/v5/account/interest-limits?type=1&ccy=BTC
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
type | String | No | Loan type1 : VIP loans2 : Market loansDefault is Market loans |
ccy | String | No | Loan currency, e.g. BTC |
Response Example
{
"code": "0",
"data": [
{
"debt": "97.06402000000000000000000000000000",
"interest": "",
"nextDiscountTime": "1637312400000",
"nextInterestTime": "1637312400000",
"records": [
{
"availLoan": "0.0000000000000000",
"ccy": "BTC",
"interest": "",
"loanQuota": "120.0000000000000000",
"posLoan": "0",
"rate": "0.00199200",
"surplusLmt": "120.0000000000000000",
"usedLmt": "0",
"usedLoan": "0.0000000000000000"
}
]
}
],
"msg": ""
}
Response Parameters
Parameter | Type | Description |
---|---|---|
debt | String | Current debt in USDT |
interest | String | Current interest in USDT , unit is USDT Only applicable to Market loans |
nextDiscountTime | String | Next deduct time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
nextInterestTime | String | Next accrual time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
records | Array | Details for currencies |
> ccy | String | Loan currency, e.g. BTC |
> rate | String | Current daily rate |
> loanQuota | String | Borrow limit |
> surplusLmt | String | Available amount |
> usedLmt | String | Borrowed amount |
> interest | String | Interest to be deducted Only applicable to Market loans |
> posLoan | String | Frozon amount for current account Only applicable to VIP loans |
> availLoan | String | Available amount for current account Only applicable to VIP loans |
> usedLoan | String | Borrowed amount for current account Only applicable to VIP loans |
Position builder
Calculates portfolio margin information for simulated position or current position of the user.
You can add up to 200 simulated positions in one request.
Rate Limit: 2 requests per 2 seconds
Rate limit rule: UserID
HTTP Request
POST /api/v5/account/simulated_margin
Request Example
POST /api/v5/account/simulated_margin
body
{
"instType":"SWAP",
"inclRealPos":"true",
"simPos":[
{
"pos":"10",
"instId":"BTC-USDT-SWAP"
},
{
"pos":"10",
"instId":"LTC-USDT-SWAP"
}
]
}
Only existing real positions are calculated
POST /api/v5/account/simulated_margin
body
{
"inclRealPos":"true"
}
Only virtual positions are calculated
POST /api/v5/account/simulated_margin
body
{
"inclRealPos":"false",
"simPos":[
{
"pos":"10",
"instId":"BTC-USDT-SWAP"
},
{
"pos":"10",
"instId":"LTC-USDT-SWAP"
}
]
}
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instType | String | No | Instrument typeSWAP FUTURES OPTION |
inclRealPos | Boolean | No | Whether import existing positionstrue :Import existing positions and hedge with simulated ones false :Only use simulated positionsThe default is true |
simPos | Array | No | List of positions |
> instId | String | No | Instrument ID |
> pos | String | No | Quantity of positions |
Response Example
{
"code": "0",
"data": [
{
"imr": "0.005432310199023",
"mmr": "0.0041787001530946",
"mr1": "0.0041787001530946",
"mr2": "0.0000734347499275",
"mr3": "0",
"mr4": "0",
"mr5": "0",
"mr6": "0.0028031968471",
"mr7": "0.0022",
"posData": [
{
"delta": "-0.008926024905498",
"gamma": "-0.0707804093543001",
"instId": "BTC-USD-220325-50000-C",
"instType": "OPTION",
"notionalUsd": "3782.9800000000005",
"pos": "-1",
"theta": "0.000093015207115",
"vega": "-0.0000382697346669"
}
],
"riskUnit": "BTC-USD",
"ts": "1646639497536"
}
],
"msg": ""
}
Response Parameters
Parameters | Types | Description |
---|---|---|
riskUnit | String | risk unit |
ts | String | Unix timestamp format in milliseconds, e.g.1597026383085 |
mmr | String | Maintenance margin requirement of riskUnit dimension |
imr | String | Initial margin requirement of riskUnit dimension |
mr1 | String | spot & vol movements |
mr2 | String | theta decay |
mr3 | String | vega term-structure |
mr4 | String | basis risk |
mr5 | String | interest-rate risk |
mr6 | String | extreme market move |
mr7 | String | transaction cost & slippage |
posData | Array | List of positions |
> instId | String | Instrument ID, e.g. BTC-USD-180216 |
> instType | String | Instrument type |
> pos | String | Quantity of positions |
> notionalUsd | String | Quantity of positions usd |
> delta | String | Sensitivity of option price to uly price |
> gamma | String | The delta is sensitivity to uly price |
> vega | String | Sensitivity of option price to implied volatility |
> theta | String | Sensitivity of option price to remaining maturity |
Get Greeks
Retrieve a greeks list of all assets in the account.
Rate Limit: 10 requests per 2 seconds
Rate limit rule: UserID
HTTP Requests
GET /api/v5/account/greeks
Request Example
Get the greeks of all assets in the account
GET /api/v5/account/greeks
Get the greeks of BTC assets in the account
GET /api/v5/account/greeks?ccy=BTC
Request Parameters
Parameters | Types | Required | Description |
---|---|---|---|
ccy | String | No | Single currency, e.g. BTC . |
Response Example
{
"code":"0",
"data":[
{
"thetaBS": "",
"thetaPA":"",
"deltaBS":"",
"deltaPA":"",
"gammaBS":"",
"gammaPA":"",
"vegaBS":"",
"vegaPA":"",
"ccy":"BTC",
"ts":"1620282889345"
}
],
"msg":""
}
Response Parameters
Parameters | Types | Description |
---|---|---|
deltaBS | String | delta:Black-Scholes Greeks in dollars |
deltaPA | String | delta:Greeks in coins |
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 |
ccy | String | Currency |
ts | String | Data return time ,Unix timestamp format in milliseconds, e.g. 1597026383085 |
SubAccount
The API endpoints of SubAccount
require authentication.
View sub-account list
Applies to master accounts only
Rate limit:2 requests per 2 seconds
Rate limit rule: UserID
HTTP request
GET /api/v5/users/subaccount/list
Request sample
GET /api/v5/users/subaccount/list
Request parameters
Parameter | Type | 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",
"type":"1",
"label":"trade futures",
"mobile":"1818181",
"gAuth":true,
"canTransOut": true,
"ts":"1597026383085"
},
{
"enable":false,
"type":"1",
"subAcct":"test-2",
"label":"trade spot",
"mobile":"1818199",
"gAuth":true,
"canTransOut": false,
"ts":"1597026383082"
}
]
}
Response parameters
Parameter name | Type | Description |
---|---|---|
type | String | Sub-account type 1 :Standard sub-account 2 :Custody trading sub-account |
enable | Boolean | 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 |
canTransOut | Boolean | If can tranfer out, false : can not tranfer out, true : can transfer. |
ts | String | Sub-account creation time, Unix timestamp in millisecond format. e.g. 1597026383085 |
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
Rate limit rule: UserID
HTTP request
GET /api/v5/account/subaccount/balances
Request sample
GET /api/v5/account/subaccount/balances?subAcct=test1
Request parameters
Parameter | Type | 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 and Portfolio margin |
adjEq | String | Adjusted/Effective equity in USD level Applicable to Multi-currency margin and Portfolio margin |
ordFroz | String | Margin frozen for pending orders in USD level Applicable to Multi-currency margin and Portfolio margin |
imr | String | Frozen equity for open positions and pending orders in USD level Applicable to Multi-currency margin and Portfolio margin |
mmr | String | Maintenance margin requirement in USD level Applicable to Multi-currency margin and Portfolio margin |
mgnRatio | String | Margin ratio in USD level Applicable to Multi-currency margin and Portfolio margin |
notionalUsd | String | Quantity of positions usd Applicable to Multi-currency margin and Portfolio 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 and Portfolio margin |
> availEq | String | Available equity of the currency Applicable to Single-currency margin and Multi-currency margin and Portfolio 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 and Portfolio margin |
> upl | String | Unrealized profit and loss of the currency Applicable to Single-currency margin and Multi-currency margin and Portfolio margin |
> uplLib | String | Liabilities due to Unrealized loss of the currency Applicable to Multi-currency margin and Portfolio margin |
> crossLiab | String | Cross Liabilities of the currency Applicable to Multi-currency margin and Portfolio margin |
> isoLiab | String | Isolated Liabilities of the currency Applicable to Multi-currency margin and Portfolio 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 and Portfolio margin |
> maxLoan | String | Max loan of the currency Applicable to Multi-currency margin and Portfolio 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
Rate limit rule: UserID
HTTP request
GET /api/v5/asset/subaccount/bills
Request sample
GET /api/v5/asset/subaccount/bills
Request parameters
Parameter | Type | 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
Rate limit rule: UserID
HTTP request
POST /api/v5/asset/subaccount/transfer
Request sample
POST /api/v5/asset/subaccount/transfer
body
{
"ccy":"USDT",
"amt":"1.5",
"from":"6",
"to":"6",
"fromSubAccount":"test-1",
"toSubAccount":"test-2"
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
ccy | String | Yes | Currency |
amt | String | Yes | Transfer amount |
from | String | Yes | 6 :Funding Account 18 :Trading account |
to | String | Yes | 6 :Funding Account 18 :Trading 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. |
loanTrans | Boolean | No | Allowing borrowed crypto transfer in/out under Multi-currency margin and Portfolio margin the default is false |
Returned results
{
"code":"0",
"msg":"",
"data":[
{
"transId":"12345",
}
]
}
Response parameters
Parameter name | Type | Description |
---|---|---|
transId | String | Transfer ID |
Set Permission Of Transfer Out
Set permission of transfer out for sub-account(only applicable to master account). Sub-account can transfer out to master account by default.
Rate Limit: 1 requests per second
Rate limit rule: UserID
HTTP Request
POST /api/v5/users/subaccount/set-transfer-out
Request Example
POST /api/v5/users/subaccount/set-transfer-out
body
{
"subAcct":"test-1",
"canTransOut":true
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
subAcct | String | Yes | Name of the sub-account. Single sub-account or multiple sub-account (no more than 20) separated with comma. |
canTransOut | Boolean | No | If can tranfer out, false : can not tranfer out, true : can transfer. The default is true . |
Returned result
{
"code": "0",
"data": [
{
"subAcct": "test-1",
"canTransOut": true
}
],
"msg": ""
}
Response parameters
Parameter | Type | Description |
---|---|---|
subAcct | String | Name of the sub-account |
canTransOut | Boolean | If can tranfer out, false : can not tranfer out, true : can transfer. |
Get custody trading sub-account list
The trading team uses this interface to view the list of sub-accounts currently under escrow
Rate limit:1 request per second
Rate limit rule: UserID
HTTP request
GET /api/v5/users/entrust-subaccount-list
Request sample
GET /api/v5/users/entrust-subaccount-list
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
subAcct | String | No | Sub-account name |
Returned results
{
"code":"0",
"msg":"",
"data":[
{
"subAcct":"test-1"
},
{
"subAcct":"test-2"
}
]
}
Response parameters
Parameter name | Type | Description |
---|---|---|
subAcct | String | Sub-account name |
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
Rate limit rule: IP
HTTP Request
GET /api/v5/market/tickers
Request Example
GET /api/v5/market/tickers?instType=SWAP
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instType | String | Yes | Instrument typeSPOT SWAP FUTURES OPTION |
uly | String | No | Underlying, e.g. BTC-USD Only applicable to FUTURES/SWAP/OPTION |
Response Example
{
"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 base 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 base 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
Rate limit rule: IP
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 |
Response Example
{
"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 base 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 base 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
Rate limit rule: IP
HTTP Request
GET /api/v5/market/index-tickers
Request Example
GET /api/v5/market/index-tickers?instId=BTC-USDT
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. |
Response Example
{
"code": "0",
"msg": "",
"data": [
{
"instId": "BTC-USDT",
"idxPx": "43350",
"high24h": "43649.7",
"sodUtc0": "43444.1",
"open24h": "43640.8",
"low24h": "43261.9",
"sodUtc8": "43328.7",
"ts": "1649419644492"
}
]
}
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 order book of the instrument.
Rate Limit: 20 requests per 2 seconds
Rate limit rule: IP
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 |
Response Example
{
"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
Rate limit rule: IP
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 |
bar | String | No | Bar size, the default is 1m e.g. [1m/3m/5m/15m/30m/1H/2H/4H] Hong Kong time opening price k-line:[6H/12H/1D/2D/3D/1W/1M/3M/6M/1Y] UTC time opening price k-line:[/6Hutc/12Hutc/1Dutc/2Dutc/3Dutc/1Wutc/1Mutc/3Mutc/6Mutc/1Yutc] |
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 300 . The default is 100 . |
Response Example
{
"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 base currency. |
volCcy | String | Trading volume, with a unit of currency .If it is a derivatives contract, the value is the number of base currency.If it is SPOT/MARGIN , the value is the number of quote currency. |
Get candlesticks history
Retrieve history candlestick charts from recent years.
Rate Limit: 20 requests per 2 seconds
Rate limit rule: IP
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] Hong Kong time opening price k-line:[6H/12H/1D/2D/3D/1W/1M/3M/6M/1Y] UTC time opening price k-line:[6Hutc/12Hutc/1Dutc/2Dutc/3Dutc/1Wutc/1Mutc/3Mutc/6Mutc/1Yutc] |
limit | String | No | Number of results per request. The maximum is 100 . The default is 100 . |
Response Example
{
"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 base currency. |
volCcy | String | Trading volume, with a unit of currency .If it is a derivatives contract, the value is the number of base 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
Rate limit rule: IP
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] Hong Kong time opening price k-line:[6H/12H/1D/1W/1M/3M/6M/1Y] UTC time opening price k-line:[/6Hutc/12Hutc/1Dutc/1Wutc/1Mutc/3Mutc/6Mutc/1Yutc] |
limit | String | No | Number of results per request. The maximum is 100 ; The default is 100 |
Response Example
{
"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
Rate limit rule: IP
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] Hong Kong time opening price k-line:[6H/12H/1D/1W/1M/3M/6M/1Y] UTC time opening price k-line:[6Hutc/12Hutc/1Dutc/1Wutc/1Mutc/3Mutc/6Mutc/1Yutc] |
limit | String | No | Number of results per request. The maximum is 100 ; The default is 100 |
Response Example
{
"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
Rate limit rule: IP
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 |
Response Example
{
"code":"0",
"msg":"",
"data":[
{
"instId":"BTC-USDT",
"tradeId":"9",
"px":"0.016",
"sz":"50",
"side":"buy",
"ts":"1597026383085"
},
{
"instId":"BTC-USDT",
"tradeId":"9",
"px":"0.016",
"sz":"50",
"side":"buy",
"ts":"1597026383085"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instId | String | Instrument ID |
tradeId | String | Trade ID |
px | String | Trade price |
sz | String | Trade quantity |
side | String | Trade sidebuy sell |
ts | String | Trade time, Unix timestamp format in milliseconds, e.g. 1597026383085 . |
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
Response Example
{
"code":"0",
"msg":"",
"data":[
{
"volUsd":"2222",
"volCny":"14220.8",
"ts": "1597026383085"
}
]
}
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 request per 5 seconds
Rate limit rule: IP
HTTP Request
GET /api/v5/market/open-oracle
Request Example
GET /api/v5/market/open-oracle
Response Example
{
"code":"0",
"msg":"",
"data":[
{
"messages":[
"0x000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000616d3b1400000000000000000000000000000000000000000000000000000000000000c00000000000000000000000000000000000000000000000000000000e70528b800000000000000000000000000000000000000000000000000000000000000006707269636573000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000034254430000000000000000000000000000000000000000000000000000000000"
],
"prices":{
"BTC":"62014"
},
"signatures":[
"0xf18330e59eaf42373c2c40f1f9e24113ba21d4ed734dd3ed3bc1d12290fa74ba5623fca1113c5d245a1202dc065e333615b90f810f12132ce4a1ecacb8c6b24a000000000000000000000000000000000000000000000000000000000000001b"
],
"timestamp":"1634548500"
}
]
}
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,Unix timestamp, e.g. 1597026387 |
Get exchange rate
This interface provides the average exchange rate data for 2 weeks
Rate Limit: 1 request per 2 seconds
Rate limit rule: IP
HTTP Request
GET /api/v5/market/exchange-rate
Request Example
GET /api/v5/market/exchange-rate
Response Example
{
"code": "0",
"msg": "",
"data": [ {
"usdCny": "6.44"
}]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
usdCny | String | Exchange rate |
Get index components
Get the index component information data on the market
Rate Limit: 20 requests per 2 seconds
Rate limit rule: IP
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 |
Response Example
{
"code": "0",
"msg": "",
"data": {
"components": [
{
"symbol": "BTC/USDT",
"symPx": "52733.2",
"wgt": "0.250",
"cnvPx": "52733.2",
"exch": "OKX"
},
{
"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 |
components | String | components |
> 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
Rate limit rule: IP +instrumentType
HTTP Request
GET /api/v5/public/instruments
Request Example
GET /api/v5/public/instruments?instType=SPOT
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instType | String | Yes | Instrument typeSPOT MARGIN SWAP FUTURES OPTION |
uly | String | Optional | Underlying Only applicable to FUTURES/SWAP/OPTION . Required for OPTION . |
instId | String | No | Instrument ID |
Response Example
{
"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":"inverse",
"alias":"this_week",
"state":"live",
"maxLmtSz":"10000",
"maxMktSz":"99999",
"maxTwapSz":"99999",
"maxIcebergSz":"99999",
"maxTriggerSz":"9999",
"maxStopSz":"9999"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument type |
instId | String | Instrument ID, e.g. BTC-USD-SWAP |
uly | String | Underlying, e.g. BTC-USD Only applicable to FUTURES/SWAP/OPTION |
category | String | Fee schedule |
baseCcy | String | Base currency, e.g. BTC inBTC-USDT Only applicable to SPOT |
quoteCcy | String | Quote currency, e.g. USDT in BTC-USDT Only applicable to SPOT |
settleCcy | String | Settlement and margin currency, e.g. BTC Only applicable to FUTURES/SWAP/OPTION |
ctVal | String | Contract value Only applicable to FUTURES/SWAP/OPTION |
ctMult | String | Contract multiplier Only applicable to FUTURES/SWAP/OPTION |
ctValCcy | String | Contract value currency Only applicable to FUTURES/SWAP/OPTION |
optType | String | Option type, C : Call P : putOnly applicable to OPTION |
stk | String | Strike price Only applicable to OPTION |
listTime | String | Listing time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
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 typelinear : linear contractinverse : inverse contractOnly applicable to FUTURES/SWAP |
alias | String | Aliasthis_week next_week quarter next_quarter Only applicable to FUTURES |
state | String | Instrument statuslive suspend preopen settlement |
maxLmtSz | String | The maximum order quantity of the contract or spot limit order |
maxMktSz | String | The maximum order quantity of the contract or spot market order |
maxTwapSz | String | The maximum order quantity of the contract or spot twap order |
maxIcebergSz | String | The maximum order quantity of the contract or spot iceBerg order |
maxTriggerSz | String | The maximum order quantity of the contract or spot trigger order |
maxStopSz | String | The maximum order quantity of the contract or spot stop order |
Get delivery/exercise history
Retrieve the estimated delivery price of the last 3 months, which will only have a return value one hour before the delivery/exercise.
Rate Limit: 40 requests per 2 seconds
Rate limit rule: IP +(instrumentType、uly)
HTTP Request
GET /api/v5/public/delivery-exercise-history
Request Example
GET /api/v5/public/delivery-exercise-history?instType=OPTION&Underlying=BTC-USD
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instType | String | Yes | Instrument typeFUTURES OPTION |
uly | String | Yes | Underlying, only applicable to FUTURES/OPTION |
after | String | No | Pagination of data to return records earlier than the requested ts |
before | String | No | Pagination of data to return records newer than the requested ts |
limit | String | No | Number of results per request. The maximum is 100 ; The default is 100 |
Response Example
{
"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 | Delivery/exercise details |
> instId | String | Delivery/exercise contract ID |
> px | String | Delivery/exercise price |
> type | String | Type delivery exercised expired_otm :Out of the money |
Get open interest
Retrieve the total open interest for contracts on OKX.
Rate Limit: 20 requests per 2 seconds
Rate limit rule: IP +instrumentID
HTTP Request
GET /api/v5/public/open-interest
Request Example
GET /api/v5/public/open-interest?instType=SWAP
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instType | String | Yes | Instrument typeSWAP FUTURES OPTION |
uly | String | No | Underlying, only applicable to FUTURES/SWAP/OPTION . Required for OPTION . |
instId | String | No | Instrument ID, e.g. BTC-USD-180216 Only applicable to FUTURES/SWAP/OPTION |
Response Example
{
"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
Rate limit rule: IP +instrumentID
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 |
Response Example
{
"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
Rate limit rule: IP +instrumentID
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 |
before | String | No | Pagination of data to return records newer than the requested fundingTime |
after | 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 |
Response Example
{
"code":"0",
"msg":"",
"data":[
{
"instType":"SWAP",
"instId":"BTC-USDT-SWAP",
"fundingRate":"0.018",
"realizedRate":"0.017",
"fundingTime":"1597026383085"
},
{
"instType":"SWAP",
"instId":"BTC-USDT-SWAP",
"fundingRate":"0.018",
"realizedRate":"0.017",
"fundingTime":"1597026383085"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument typeSWAP |
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 |
Response Example
{
"code":"0",
"msg":"",
"data":[
{
"instType":"SWAP",
"instId":"BTC-USDT-SWAP",
"buyLmt":"200",
"sellLmt":"300",
"ts":"1597026383085"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument typeSWAP FUTURES OPTION |
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
Rate limit rule: IP +uly
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" |
Response Example
{
"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",
"fwdPx": "39016.8143629068452065",
"ts":"1597026383085"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument typeOPTION |
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 is 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 is 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) |
fwdPx | String | Forward price |
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
Rate limit rule: IP +instId
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 |
Response Example
{
"code":"0",
"msg":"",
"data":[
{
"instType":"FUTURES",
"instId":"BTC-USDT-201227",
"settlePx":"200",
"ts":"1597026383085"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument typeFUTURES OPTION |
instId | String | Instrument ID, e.g. BTC-USD-180216 |
settlePx | String | Estimated delivery price |
ts | String | Data return time, Unix timestamp format in milliseconds, e.g. 1597026383085 |
Get discount rate and interest-free quota
Retrieve discount rate level and interest-free quota.
Rate Limit: 2 requests per 2 seconds
Rate limit rule: IP
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 level1 :level 1 2 :level 2 3 :level 3 4 :level 4 5 :level 5 |
Response Example
{
"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
Rate limit rule: IP
HTTP Request
GET /api/v5/public/time
Request Example
GET /api/v5/public/time
Response Example
{
"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 day.
Rate Limit: 2 requests per 2 seconds
Rate limit rule: IP
HTTP Request
GET /api/v5/public/liquidation-orders
Request Example
GET /api/v5/public/liquidation-orders?instType=MARGIN
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instType | String | Yes | Instrument typeMARGIN SWAP FUTURES OPTION |
mgnMode | String | No | Margin mode isolated cross |
instId | String | No | Instrument ID, only applicable to MARGIN |
ccy | String | No | Liquidation currency, only applicable to cross MARGIN |
uly | String | Optional | Underlying Required for FUTURES/SWAP/OPTION |
alias | String | Optional | this_week next_week quarter next_quarter Required for FUTURES |
state | String | 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 |
Response Example
{
"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 | Liquidation 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. The price of the transaction with the system's liquidation account |
>sz | String | Quantity of liquidation |
>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
Rate limit rule: IP +instrumentID
HTTP Request
GET /api/v5/public/mark-price
Request Example
GET /api/v5/public/mark-price?instType=SWAP
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instType | String | Yes | Instrument typeMARGIN SWAP FUTURES OPTION |
uly | String | No | Underlying |
instId | String | No | Instrument ID, e.g. BTC-USD-SWAP |
Response Example
{
"code":"0",
"msg":"",
"data":[
{
"instType":"SWAP",
"instId":"BTC-USDT-SWAP",
"markPx":"200",
"ts":"1597026383085"
}
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
instType | String | Instrument typeMARGIN SWAP FUTURES OPTION |
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
Retrieve position tiers information,maximum leverage depends on your borrowings and margin ratio.
Rate Limit: 10 requests per 2 seconds
Rate limit rule: IP
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 typeMARGIN SWAP FUTURES OPTION |
tdMode | String | YES | Trade mode Margin mode cross isolated |
uly | String | Optional | Underlying Required when instType is one of SWAP ,FUTURES ,OPTION , ignore when instType is MARGIN |
instId | String | Optional | Instrument ID, e.g. BTC-USDT Required when instType is MARGIN , ignore when instType is one of SWAP ,FUTURES ,OPTION |
tier | String | NO | Tiers |
Response Example
{
"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
Retrieve interest rate
Rate Limit: 2 requests per 2 seconds
Rate limit rule: IP
HTTP Request
GET /api/v5/public/interest-rate-loan-quota
Request Example
GET /api/v5/public/interest-rate-loan-quota
Response Example
{
"code": "0",
"data": [
{
"basic": [
{
"ccy": "USDT",
"quota": "500000",
"rate": "0.00043728"
},
{
"ccy": "BTC",
"quota": "10",
"rate": "0.00019992"
}
],
"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 interest rate |
> ccy | String | Currency |
> rate | String | Daily rate |
> quota | String | Max borrow |
vip | Array | Interest info for vip users |
> level | String | VIP Level, e.g. VIP1 |
> loanQuotaCoef | String | Loan quota coefficient |
> irDiscount | String | Interest rate discount |
regular | Array | Interest info for regular users |
> level | String | Regular user Level, e.g. Lv1 |
> loanQuotaCoef | String | Loan quota coefficient |
> irDiscount | String | Interest rate discount |
Get interest rate and loan quota for VIP loans
Rate Limit: 2 requests per 2 seconds
Rate limit rule: IP
HTTP Request
GET /api/v5/public/vip-interest-rate-loan-quota
Request Example
GET /api/v5/public/vip-interest-rate-loan-quota
Response Example
{
"code": "0",
"data": [
{
"ccy": "ENJ",
"levelList": [
{
"level": "VIP5",
"loanQuota": "100000.00000000"
},
{
"level": "VIP6",
"loanQuota": "110000.00000000"
},
{
"level": "VIP7",
"loanQuota": "120000.00000000"
},
{
"level": "VIP8",
"loanQuota": "130000.00000000"
}
],
"quota": "10000.0000",
"rate": "0.00048000"
}
],
"msg": ""
}
Response Parameters
Parameter | Type | Description |
---|---|---|
ccy | String | Currency, e.g. BTC |
rate | String | Daily rate |
quota | String | Max borrow |
levelList | Array | Loan quota coef for all VIP level |
> level | String | VIP Level, e.g. VIP5 |
> loanQuota | String | Loan quota coef |
Get underlying
Rate Limit: 20 requests per 2 seconds
Rate limit rule: IP
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 typeSWAP FUTURES OPTION |
Response Example
{
"code":"0",
"msg":"",
"data":[
[
"LTC-USDT",
"BTC-USDT",
"ETC-USDT"
]
]
}
Response Parameters
Parameter | Type | Description |
---|---|---|
uly | Array | Underlying |
Get insurance fund
Get insurance fund balance information
Rate Limit: 10 requests per 2 seconds
Rate limit rule: IP
HTTP Request
GET /api/v5/public/insurance-fund
Request Example
GET /api/v5/public/insurance-fund?instType=SWAP&uly=BTC-USD
Request Parameters
Parameter | Type | Required | Description |
---|---|---|---|
instType | String | Yes | Instrument typeMARGIN SWAP FUTURES OPTION |
type | String | No | typeliquidation_balance_deposit bankruptcy_loss platform_revenue The default is all type |
uly | String | No | Underlying Required for FUTURES/SWAP/OPTION , Required for FUTURES/SWAP/OPTION . |
ccy | String | No | Currency, only applicable to MARGIN |
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 |
Response Example
{
"code": "0",
"data": [
{
"details": [
{
"amt": "0.2465",
"balance": "3228.0732",
"ccy": "BTC",
"ts": "1646726421082",
"type": "liquidation_balance_deposit"
}
],
"total": "883110357.6581"
}
],
"msg": ""
}
Response Parameters
Parameter | Type | Description |
---|---|---|
total | String | 平台风险准备金总计,单位为USD |
> balance | String | 风险准备金总量 |
> amt | String | 风险准备金更新数量 |
> ccy | String | 风险准备金总量对应的币种 |
> type | String | 风险准备金类型 |
> ts | String | 风险准备金更新时间,Unix时间戳的毫秒数格式,如 1597026383085 |
Trading data
The API endpoints of Trading Data
do not require authentication.
Get support coin
Retrieve the currencies supported by the trading data endpoints.
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
Response Example
{
"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
Retrieve the taker volume for both buyers and sellers.
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 typeSPOT ,CONTRACTS |
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 most1H granularity can only query data within 30 days at most 1D granularity can only query data within 180 days at most |
Response Example
{
"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
Retrieve the ratio of cumulative amount between currency margin quote currency and base currency.
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 ] 5m granularity can only query data within two days at most1H granularity can only query data within 30 days at most 1D granularity can only query data within 180 days at most |
Response Example
{
"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
Retrieve the ratio of users with net long vs net short positions for 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 most1H granularity can only query data within 30 days at most 1D granularity can only query data within 180 days at most |
Response Example
{
"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
Retrieve the open interest and trading volume for futures and perpetual swaps.
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 most1H granularity can only query data within 30 days at most 1D granularity can only query data within 180 days at most |
Response Example
{
"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
Retrieve the open interest and trading volume for options.
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 |
Response Example
{
"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
Retrieve the open interest ration and trading volume ratio of calls vs puts.
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 |
Response Example
{
"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)
Retrieve the open interest and trading volume of calls and puts for each upcoming expiration.
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 |
Response Example
{
"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 | Contract expiry date, the format is YYYYMMdd , e.g. 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)
Retrieve the taker volume for both buyers and sellers of calls and puts.
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 | Contract expiry date, the format is YYYYMMdd , e.g. 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 |
Response Example
{
"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 |
Response Example
{
"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, in settlement currency |
callSellVol | String | call option sell volume, in settlement currency |
putBuyVol | String | put option buy volume, in settlement currency |
putSellVol | String | put option sell volume, in settlement currency |
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 |
Response Example
{
"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 :Trading 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:
- The WebSocket request header size for data transmission between client and server is only 2 bytes.
- Either the client or server can initiate data transmission.
- There's no need to repeatedly create and delete TCP connections, saving resources on bandwidth and server.
Connect
Connection instructions:
Connection limit: 1 time per second
When subscribing to a public channel, use the address of the public service. When subscribing to a private channel, use the address of the private service
Subscription limit: 240 times per hour
Login
Rate Limit: 1 request per second Applicable to single-account login
Rate Limit: 1 request per 15 seconds Applicable to multi-account batch login
Request Example
{
"op": "login",
"args": [
{
"apiKey": "985d5b66-57ce-40fb-b714-afc0b9787083",
"passphrase": "123456",
"timestamp": "1538054050",
"sign": "7L+zFQ+CEgGu5rzCj4+BdV2/uUHGqddA9pI6ztsRRPs="
},
{
"apiKey" : "86126n98-57ce-40fb-b714-afc0b9787083",
"passphrase" :"123456" ,
"timestamp" :"1538054050" ,
"sign" :"7L+zFQ+CEgGu5rzCj4+BdV2/uUHGqddA9pI6ztsRRPs="
}
]
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation, login |
args | Array | Yes | List of account to login, the maximum is 100 |
> apiKey | String | Yes | APIKey |
> passphrase | String | Yes | APIKey password |
> timestamp | String | Yes | Unix Epoch time, the unit is seconds |
> sign | String | Yes | Signature string |
Successful Response Example
{
"event": "login",
"code": "0",
"msg": ""
}
Failure Response Example
{
"event": "error",
"code": "60009",
"msg": "Login failed."
}
Response Example When Partially Successful
{
"event": "login",
"code": "60022",
"msg": "Bulk login partially succeeded",
"data":[
{"apiKey": "86126n98-57ce-40fb-b714-afc0b9787083"}
]
}
Response parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Operation, login error |
code | String | No | Error code |
msg | String | No | Error message |
data | Object | No | List returned after login failure |
> apiKey | String | Yes | APIKey returned after login failure |
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 typeSPOT MARGIN SWAP FUTURES OPTION ANY |
> uly | String | No | Underlying |
> instId | String | No | Instrument ID |
Response Example
{
"event": "subscribe",
"arg": {
"channel": "tickers",
"instId": "LTC-USD-200327"
}
}
Return parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Event, subscribe error |
arg | Object | No | Subscribed channel |
> channel | String | Yes | Channel name |
> instType | String | No | Instrument typeSPOT MARGIN SWAP FUTURES OPTION ANY |
> uly | String | No | Underlying |
> instId | String | No | Instrument ID |
code | String | No | Error code |
msg | String | No | Error message |
Unsubscribe
Unsubscribe from one or more channels.
Request format description
{
"op": "unsubscribe",
"args": ["< SubscriptionTopic> "]
}
Request Example
{
"op": "unsubscribe",
"args": [
{
"channel": "tickers",
"instId": "LTC-USD-200327"
},
{
"channel": "candle1m",
"instId": "LTC-USD-200327"
}
]
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation, unsubscribe |
args | Array | Yes | List of channels to unsubscribe from |
> channel | String | Yes | Channel name |
> instType | String | No | Instrument typeSPOT MARGIN SWAP FUTURES OPTION ANY |
> uly | String | No | Underlying |
> instId | String | No | Instrument ID |
Response Example
{
"event": "unsubscribe",
"arg": {
"channel": "tickers",
"instId": "LTC-USD-200327"
}
}
Return parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Event, unsubscribe error |
arg | Object | No | Unsubscribed channel |
> channel | String | Yes | Channel name |
> instType | String | No | Instrument typeSPOT MARGIN SWAP FUTURES OPTION |
> uly | String | No | Underlying |
> instId | String | No | Instrument ID |
code | String | No | Error code |
msg | String | No | Error message |
Checksum
This mechanism can 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.
- If there is the same price, compare the size. If the size is 0, delete this depth data. If the size changes, replace the original data.
- 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 size 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"
- 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:size]
:ask[price:size]
:bid[price:size]
:ask[price:size]
... - When the bid or ask depth data is less than 25 levels, the missing depth data will be ignored.
Such as:bid[price:size]
:ask[price:size]
:asks[price:size]
:asks[price:size]
...
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
Derivatives rate limit rule: UserID +(instrumentType、underlying)
Spot & Margin rate limit rule: UserID +(instrumentType、instrumentID)
Share rate limit with restAPI
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 16 characters. |
> side | String | Yes | Order side, buy sell |
> posSide | String | Optional | Position side The default is net in the net modeIt is required in the long/short mode, and can only be long or short .Only applicable to FUTURES/SWAP . |
> ordType | String | Yes | Order typemarket : market orderlimit : limit orderpost_only : Post-only orderfok : Fill-or-kill orderioc : Immediate-or-cancel order optimal_limit_ioc :Market order with immediate-or-cancel order |
> sz | String | Yes | Quantity to buy or sell. |
> px | String | Optional | 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, and FUTURES/SWAP orders in net mode Only applicable to Single-currency margin and Multi-currency margin |
> tgtCcy | String | No | Quantity typebase_ccy : Base currency ,quote_ccy : Quote currency Only applicable to SPOT traded with Market orderDefault is quote_ccy for buy, base_ccy for sell |
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": ""
}
Response Example 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
Derivatives rate limit rule: UserID +(instrumentType、underlying)
Spot & Margin rate limit rule: UserID +(instrumentType、instrumentID)
Rate limit rule: How many elements the batch requests contains, the rate limit count will be increased by the same number.The total limit is 300 times/2s
Share rate limit with restAPI
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 16 characters. |
> side | String | Yes | Order side, buy sell |
> posSide | String | Optional | Position side The default net in the net modeIt is required in the long/short mode, and only be long or short .Only applicable to FUTURES/SWAP . |
> ordType | String | Yes | Order typemarket : market orderlimit : limit orderpost_only : Post-only orderfok : Fill-or-kill orderioc : 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 | Optional | 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, and FUTURES/SWAP orders in net mode Only applicable to Single-currency margin and Multi-currency margin |
> tgtCcy | String | No | Quantity typebase_ccy : Base currency ,quote_ccy : Quote currency Only applicable to SPOT traded with Market orderDefault is quote_ccy for buy, base_ccy for sell |
Response Example 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": ""
}
Response Example 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": ""
}
Response Example 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": ""
}
Response Example 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
Derivatives rate limit rule: UserID +(instrumentType、underlying)
Spot & Margin rate limit rule: UserID +(instrumentType、instrumentID)
Share rate limit with restAPI
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": ""
}
Response Example 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
Derivatives rate limit rule: UserID +(instrumentType、underlying)
Spot & Margin rate limit rule: UserID +(instrumentType、instrumentID)
Rate limit rule: How many elements the batch requests contains, the rate limit count will be increased by the same number.The total limit is 300 times/2s
Share rate limit with restAPI
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. |
Response Example 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": ""
}
Response Example 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": ""
}
Response Example 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": ""
}
Response Example 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
Derivatives rate limit rule: UserID +(instrumentType、underlying)
Spot & Margin rate limit rule: UserID +(instrumentType、instrumentID)
Share rate limit with restAPI
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": ""
}
Response Example 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
Derivatives rate limit rule: UserID +(instrumentType、underlying)
Spot & Margin rate limit rule: UserID +(instrumentType、instrumentID)
Rate limit rule: How many elements the batch requests contains, the rate limit count will be increased by the same number.The total limit is 300 times/2s
Share rate limit with restAPI
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. |
Response Example 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": ""
}
Response Example 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": ""
}
Response Example 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": ""
}
Response Example 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 order, canceling order, transaction execution, etc. It 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",
"uid": "77982378738415879"
},
"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 |
---|---|---|
arg | Object | Successfully subscribed channel |
> channel | String | Channel name |
> uid | String | User Identifier |
data | Array | Subscribed data |
> 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 and Portfolio margin |
> adjEq | String | Adjusted/Effective equity in USD level Applicable to Multi-currency margin and Portfolio margin |
> ordFroz | String | Margin frozen for pending orders in USD level Applicable to Multi-currency margin and Portfolio margin |
> imr | String | Frozen equity for open positions and pending orders in USD level Applicable to Multi-currency margin and Portfolio margin |
> mmr | String | Maintenance margin requirement in USD level Applicable to Multi-currency margin and Portfolio margin |
> mgnRatio | String | Margin ratio in USD level Applicable to Multi-currency margin and Portfolio margin |
> notionalUsd | String | Quantity of positions usd Applicable to Multi-currency margin and Portfolio 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 and Portfolio margin |
>> availEq | String | Available equity of the currency Applicable to Single-currency margin and Multi-currency margin and Portfolio 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 and Portfolio margin |
>> upl | String | Unrealized profit and loss of the currency Applicable to Single-currency margin and Multi-currency margin and Portfolio margin |
>> uplLib | String | Liabilities due to Unrealized loss of the currency Applicable to Multi-currency margin and Portfolio margin |
>> crossLiab | String | Cross Liabilities of the currency Applicable to Multi-currency margin and Portfolio margin |
>> isoLiab | String | Isolated Liabilities of the currency Applicable to Multi-currency margin and Portfolio margin |
>> mgnRatio | String | Margin ratio of the currency Applicable to Single-currency margin |
>> interest | String | Interest of the currency Applicable to Multi-currency margin and Portfolio margin |
>> twap | String | System is 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 and Portfolio margin and Portfolio margin |
>> maxLoan | String | Max loan of the currency Applicable to Multi-currency margin and Portfolio 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 and Portfolio 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 typeMARGIN SWAP FUTURES OPTION ANY |
> uly | String | No | Underlying |
> instId | String | No | Instrument ID |
Successful Response Example : single
{
"event": "subscribe",
"arg": {
"channel": "positions",
"instType": "FUTURES",
"uly": "BTC-USD",
"instId": "BTC-USD-200329"
}
}
Successful Response Example
{
"event": "subscribe",
"arg": {
"channel": "positions",
"instType": "ANY"
}
}
Failure Response Example
{
"event": "error",
"code": "60012",
"msg": "Unrecognized request: {\"op\": \"subscribe\", \"argss\":[{ \"channel\" : \"positions\", \"instType\" : \"FUTURES\"}]}"
}
Response parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Event, subscribe unsubscribe errror |
arg | Object | No | Subscribed channel |
> channel | String | Yes | Channel name |
> instType | String | Yes | Instrument typeOPTION FUTURES SWAP MARGIN ANY |
> uly | String | No | Underlying |
> instId | String | No | Instrument ID |
code | String | No | Error code |
msg | String | No | Error message |
Push Data Example: single
{
"arg":{
"channel":"positions",
"instType":"FUTURES"
},
"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",
"markPx":"2353.849",
"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",
"uid": "77982378738415879",
"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",
"usdPx":"",
"lever":"10",
"liab":"",
"liabCcy":"",
"liqPx":"2352.8496681818233",
"markPx":"2353.849",
"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",
"usdPx":"",
"lever":"10",
"liab":"",
"liabCcy":"",
"liqPx":"2352.8496681818233",
"markPx":"2353.849",
"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 |
> uid | String | User Identifier |
> instType | String | Instrument type |
> uly | String | Underlying |
> instId | String | Instrument ID |
data | Array | Subscribed data |
> instType | String | Instrument type |
> mgnMode | String | Margin mode, cross isolated |
> posSide | String | Position sidelong short net (FUTURES/SWAP/OPTION : positive pos means long position and negative pos means short position. MARGIN : posCcy being base currency means long position, posCcy being quote currency means short position.) |
> pos | String | Quantity of positions,In the mode of autonomous transfer from position to position, after the deposit is transferred, a position with pos of 0 will be generated |
> baseBal | String | Base currency balance, only applicable to MARGIN (Manual transfers) |
> quoteBal | String | Quote currency balance, only applicable to MARGIN (Manual transfers) |
> 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 |
> markPx | String | Mark price |
> 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 |
> usdPx | String | USD 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",
"uid": "77982378738415879"
},
"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":