Update log
April 02, 2022
- add account bill interface
/followerOrder
add field openMargin
February 25, 2022
- Add Take Profit and Stop Loss order to place an order based on quantity
size
optional - Get all transaction details and add
lastEndId
query pagination
February 12, 2022
- add new interface get symbol supported leverage get symbol supported leverage
- Get transaction details Support query all details Check Transaction Details
January 05, 2022【Modification of frequency limit rules to add a new domain name】
- Removed domain name https://capi.bitgetapi.com
add new domain name https://api.bitget.com
- Modification of frequency limit rules
Request Url | Rule |
---|---|
/api/mix/v1/account/setLeverage | 5c/1s |
/api/mix/v1/account/setMargin | 5c/1s |
/api/mix/v1/account/setMarginMode | 5c/1s |
/api/mix/v1/account/setPositionMode | 5c/1s |
/api/mix/v1/position/allPosition | 5c/1s |
December 08, 2021【WebSocket Private Channel 】
- WebSocket Private Channel Online
October 26, 2021
- Follower view and documentary interface added
- The interface for traders to view the information of closing and copy trading pairs
- Traders set up the copy trading pair interface
- Golang SDK is online
- NodeJs SDK is online
September 26, 2021【WebSocket Public Channel 】
- WebSocket Public Channel Online
- The position interface adds a field for liquidation price
/singlePosition
/allPosition
September 08, 2021【Contract List and Ticker Quotes】
- Get the list of all contracts and get all the ticker quotations interface requires the
productType
parameter to be passed in to support simulated trading
September 06, 2021【New account list query】
- Account interface New account list query, query all account information according to prodcut type
- New unrealized profit and loss field in position interface
July 27, 2021 [New Quanto Swap Contract V1 Document]
- New V1 document
- Error message support in Chinese/English
Introduction
API Introduction
Welcome to Bitget Developer document!
This document is the only official document of Bitget API. We will constantly update the functionalities of Bitget API here. Please pay attention to it regularly.
You can switch to access different business APIs by clicking the upper menu, and you can switch the document language by clicking the language button on the upper right.
On the right side of the document is an example of request parameters and response results.
Market Cooperation/Quantitative Market Maker
Users with excellent maker strategies and large trading volumes are welcome to participate in long-term market maker projects. Please provide the following information and send an email to:
- API@bitget.com Contract market maker application.
- Provide UID (UID that is without any affiliate commission rebate);
- Provide other trading platform maker trading volume screenshot proof (for example, trading volume within 30 days);
- Please briefly describe the market making method, no need to give specific details.
Updates
Regarding API additions, updates, and offline information, Bitget will issue announcements in advance to notify you. It is recommended that you follow and subscribe to our announcements to obtain relevant information in time.
You can click here to subscribe to announcements.
Contact Us
If you have any questions or suggestions, you can contact us here:
- Send an email to API@bitget.com.
- Telegram Join
FAQ
Q1: Why can't traders close positions?
A : Traders should use Trader close position interface
Q2: Order parameter
Symbol
What should I pass? For example, BTCUSDT_UMCBL or BTCUSDT ?A : BTCUSDT_UMCBL
Q3 : What does the WebSocket parameter
instId
pass? For example, BTCUSDT_UMCBL or BTCUSDT ?A : BTCUSDT
Q4: Is the parameter
symbol
case sensitive?A : Yes
Quick Start
Access Preparation
If you need to use the API, please log in to the web page first, complete the API key application and permission configuration, and then develop and trade according to the details of this document.
You can click here to create an API Key.
Each user can create 10 sets of Api Keys, and each Api Key can set two permissions for reading and trading.
The permissions are described as follows:
Read permission: Read permission is used to query data, such as market data.
Trading permission: Trading permission is used for the interface of placing and canceling orders.
After the creation is successful, please remember the following information:
API Key
The identity of API transactions, generated by a random algorithm.Private Key
The private key is randomly generated by the system and used for signature generation.Passphrase
The password is set by the user. It should be noted that if you forgot the Passphrase, it cannot be retrieved back, and the APIKey needs to be recreated.
SDK/Code Example
open SDK(Recommended)
Java | Python | GoLang | NodeJs | PHP
Interface Type
This chapter mainly divides the interface types into the following two aspects:
- Public Interface
- Private Interface
Public Interface
The public interface can be used to obtain configuration information and market data. Public requests can be used without authentication.
Private Interface
The private interface can be used for order management and account management. Every private request must be signed using a canonical form of verification.
The private interface needs to be verified with your APIKey.
Access Restriction
This chapter mainly focuses on access restrictions:
- Rest API will return 429 status when the access exceeds the frequency limit: the request is too frequent.
Rest API
If the APIKey is valid, you can use the APIKey to limit the speed; if not, use the public network IP to limit the speed.
Speed limit rules: There are separate instructions on each interface. If there is no general interface, the speed limit is 10 times per second.
Special note: When placing orders in batches, if 4 currency pairs are placed, 10 orders per currency pair will be counted as one request.
API Public Parameters
Side(Trade Direction)
Name | Description |
---|---|
open_long | Open long position |
open_short | Open short position |
close_long | Close long position |
close_short | Close short position |
orderType(Trading Type)
Name | Description |
---|---|
limit | Limit order |
market | Market order |
timeInForceValue(Order Validity Period)
Name | Description |
---|---|
normal | Normal order |
post_only | The order will remain valid until it is traded or cancelled |
Ioc | The part that cannot be traded immediately has been cancelled |
fok | Cannot be cancelled immediately |
triggerType(Trigger Type)
Words | Description |
---|---|
fill_price | Triggered by strike price |
market_price | Triggered by mark price |
planType(Limit Order Type)
Words | Description |
---|---|
normal_plan | Normal limit |
profit_plan | Take profit price |
loss_plan | Stop loss price |
holdSide(Position Directon)
Words | Description |
---|---|
long | Long position |
short | Short position |
marginMode(Position Mode)
Words | Description |
---|---|
fixed | Isolated margin |
crossed | Cross margin |
holdMode(Position Mode)
Words | Description |
---|---|
single_hold | One-way position |
double_hold | Two-way position |
status(Limit Order Status)
Words | Description |
---|---|
no_trigger | Not triggered |
triggered | Triggered |
fail_trigger | Triggered failed |
cancel | Cancelled |
productType(Product Type )
Words | Description |
---|---|
umcbl | USDT Unified Contract |
dmcbl | Quanto Swap Contract |
sumcbl | USDT Unified Contract Analog disk |
sdmcbl | Quanto Swap Contract Analog disk |
state(order status)
Words | Description |
---|---|
new | new order |
partially_filled | Partially Filled |
filled | Filled |
canceled | Canceled |
isPlan
Words | Description |
---|---|
plan | plan order |
profit_loss | Tpsl order |
granularity(candles interval)
- 60(1minute)
- 300(5minute)
- 900(15minute)
- 1800(30minute)
- 3600(1hour)
- 14400(4hour)
- 43200(12hour)
- 86400(1day)
- 604800(1week)
API Domain Name
You can use the Rest API access method to operate by yourself.
Domain Name | REST API | Recommended To Use |
---|---|---|
Domain 1 | https://api.bitget.com | Main Domain name |
Domain 1 | https://capi.bitget.com | backup |
API Verification
Initiate a request
The header of all REST requests must contain the following key:
- ACCESS-KEY:API KEY as a string
- ACCESS-SIGN:Use base64 encoding to sign (see Signing messages).
- ACCESS-TIMESTAMP:Timestamp of your request
- ACCESS-PASSPHRASE:The password you set when creating the API KEY.
- Content-Type:Unified setting to application/json
- Locale: Support multiple languages, such as: Chinese (zh-CN), English (en-US)
Signature
The request header of ACCESS-SIGN is to timestamp + method.toUpperCase() + requestPath + "?" + queryString + body string (+ means string connection) encrypted with HMAC SHA256 method, passed* BASE64* encoded output.
Description of each field of the signature
- timestamp:Same as ACCESS-TIMESTAMP request header.
- method:Request method (POST/GET), all uppercase letters.
- requestPath:Request interface path.
- queryString:The query string in the request URL (the request parameter after the ?).
- body:The string corresponding to the request body. If the request has no body (usually a GET request), the body can be omitted.
The queryString as empty, signature format
timestamp + method.toUpperCase() + requestPath + body
The queryString not empty, signature format
timestamp + method.toUpperCase() + requestPath + "?" + queryString + body
For example
Get contract depth information, take cmt_btcusdt as an example:
- Timestamp = 16273667805456
- Method = "GET"
- requestPath = "/api/mix/V1/market/depth"
- queryString= "?symbol=BTCUSDT_UMCBL&limit=20"
Generate the string to be signed:
'16273667805456GET/api/mix/v1/market/depth?symbol=BTCUSDT_UMCBL&limit=20'
Contract order, take cmt_btcusdt as an example:
- Timestamp = 16273667805456
- Method = "POST"
- requestPath = "/api/mix/v1/order/placeOrder"
- body = {"symbol":"BTCUSDT_UMCBL","size":"8","side":"open_long","orderType":"limit","client_oid":"bitget#123456"}
Generate the string to be signed:
'16273667805456POST/api/mix/v1/order/placeOrder{"symbol":"BTCUSDT_UMCBL","size":"8","side":"open_long","order_type":"limit","client_oid":"bitget#123456"}'
Steps to generate the final signature
Step 1. Use the private key secretkey to encrypt the string to be signed with hmac sha256
Signature = hmac_sha256(secretkey, Message)
The second step is to base64 encode the Signature
Signature = base64.encode(Signature)
Request Interaction
All requests are based on the Https protocol, and the Content-Type in the request header information needs to be all set to:'application/json'.
Request Interaction Description
- Request parameters: Encapsulate parameters according to the interface request parameters.
- Submit request parameters: Submit the encapsulated request parameters to the server through GET/POST.
- Server Response:The server first performs parameter security verification on the user request data, and returns the response data to the user in JSON format according to the business logic after passing the verification.
- Data processing:Process the server response data.
Success
HTTP status code 200 indicates a successful response and may contain content. If the response contains content, it will be displayed in the corresponding return content.
Common Error Codes
- 400 Bad Request – Invalid request format
- 401 Unauthorized – Invalid API Key
- 403 Forbidden – You do not have access to the requested resource
- 404 Not Found – No request found
- 429 Too Many Requests – Requests are too frequent and are limited by the system
- 500 Internal Server Error – We had a problem with our server
- If it fails, the body has an error description
Standard Specification
Timestamp
The unit of ACCESS-TIMESTAMP in the request signature is milliseconds. The timestamp of the request must be within 30 seconds of the API service time, otherwise the request will be considered expired and rejected. If there is a large deviation between the local server time and the API server time, we recommend that you update the http header by querying the API server time.
Frequency Limiting Rules
If the request is too frequent, the system will automatically limit the request and return the 429 too many requests status code in the http header.
- Public interface:For the market information interface, the unified frequency limit is a maximum of 20 requests per second.
- Authorization interface:Use apikey to restrict the calling of authorized interfaces, refer to the frequency restriction rules of each interface for frequency restriction。
Request Format
There are currently only two request methods in formats: GET and POST
- GET: The parameters are transmitted to the server in the path through queryString.
- POST: The parameters are sent to the server by sending the body in json format.
RestAPI
Market
Get All Symbols
Limit rule: 20 times/1s (IP)
HTTP Request
- GET /api/mix/v1/market/contracts
Request Parameter(Request Param)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
productType | String | Yes | product type |
Response
{
"code":"00000",
"data":[
{
"symbol":"BTCUSDT_UMCBL",
"symbolName":"BTCUSDT",
"makerFeeRate":"0.0004",
"takerFeeRate":"0.0006",
"feeRateUpRatio":"0.1",
"openCostUpRatio":"0.1",
"quoteCoin":"USDT",
"baseCoin":"BTC",
"buyLimitPriceRatio":"0.1",
"sellLimitPriceRatio":"0.1",
"supportMarginCoins":[
"USDT"
],
"minTradeNum":"0.0001",
"priceEndStep":"1",
"volumePlace":"4",
"pricePlace":"1"
}
],
"msg":"success",
"requestTime":1627114525850
}
Response Description
Parameter | Description |
---|---|
symbol | product Id |
symbolName | product name |
baseCoin | Base currency |
quoteCoin | Quote currency |
buyLimitPriceRatio | Buy price limit ratio 1% |
sellLimitPriceRatio | Sell price limit ratio 1% |
feeRateUpRatio | Rate of increase in handling fee% |
makerFeeRate | Market fee rate% |
takerFeeRate | Taker fee rate% |
openCostUpRatio | Percentage of increase in opening cost% |
supportMarginCoins | Support margin currency |
minTradeNum | Minimum number of openings |
priceEndStep | Price step |
volumePlace | Number of decimal places |
pricePlace | Price decimal places |
Get Depth
Limit rule: 20 times/1s (IP)
HTTP Request
- GET /api/mix/v1/market/depth
Request Parameter(Request Param)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
limit | String | No | Depth gear 5,15,50,100 default 100 |
Response
{
"code":"00000",
"data":{
"asks":[
[
"30002",
"0.2300000000000000"
],
[
"30002.5",
"0.91"
],
[
"30003",
"0.18"
]
],
"bids":[
[
"29987",
"0.28"
],
[
"300",
"0.3333000000000000"
]
],
"timestamp":"1627115809358"
},
"msg":"success",
"requestTime":1627115809358
}
Get Single Symbol Ticker
Limit rule: 20 times/1s (IP)
HTTP Request
- GET /api/mix/v1/market/ticker
Request Parameter(Request Param)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
Response
{
"code":"00000",
"data":{
"symbol":"BTCUSDT_UMCBL",
"last":"30002",
"bestAsk":"30000.5",
"bestBid":"30000",
"high24h":"30002",
"low24h":"30002",
"timestamp":"1627115973334",
"priceChangePercent":"0.15392308",
"baseVolume":"68.4427",
"quoteVolume":"1806816.7596",
"usdtVolume":"1806816.7596"
},
"msg":"success",
"requestTime":1627115973334
}
Response Description
Parameter | Description |
---|---|
symbol | Currency pair name |
last | Latest price |
bestAsk | Ask price |
bestBid | Bid price |
high24h | Highest price in 24 hours |
low24h | Lowest price in 24 hours |
timestamp | Timestamp (milliseconds) |
priceChangePercent | Price change (24 hours) |
baseVolume | Base currency trading volume |
quoteVolume | Quote currency trading volume |
usdtVolume | USDT transaction volume |
Get All Symbol Ticker
Limit rule: 20 times/1s (IP)
HTTP Request
- GET /api/mix/v1/market/tickers
Request Parameter(Request Param)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
productType | String | Yes | product type |
Response
{
"code":"00000",
"data":[
{
"symbol":"BTCUSDT_UMCBL",
"last":"29990.5",
"bestAsk":"30000.5",
"bestBid":"30000",
"high24h":"30007",
"low24h":"30007",
"timestamp":"1627116888108",
"priceChangePercent":"0.15348077",
"baseVolume":"73.4114",
"quoteVolume":"1978178.35205",
"usdtVolume":"1978178.35205"
}
],
"msg":"success",
"requestTime":1627116888119
}
Response Description
Parameter | Description |
---|---|
symbol | Currency pair name |
last | Latest price |
bestAsk | Ask price |
bestBid | Bid price |
high24h | Highest price in 24 hours |
low24h | Lowest price in 24 hours |
timestamp | Timestamp (milliseconds) |
priceChangePercent | Price change (24 hours) |
baseVolume | Base currency trading volume |
quoteVolume | Quote currency trading volume |
usdtVolume | USDT transaction volume |
Get Fills
Limit rule: 20 times/1s (IP)
HTTP Request
- GET /api/mix/v1/market/fills
Request Parameter(Request Param)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
limit | String | No | Default number of rows is 100 |
Response Data
{
"code":"00000",
"data":[
{
"tradeId":"802751431994691585",
"price":"29990.5",
"size":"0.0166",
"side":"sell",
"timestamp":"1627116776464",
"symbol":"BTCUSDT_UMCBL"
},
{
"tradeId":"802750695521046529",
"price":"30007.0",
"size":"0.0166",
"side":"buy",
"timestamp":"1627116600875",
"symbol":"BTCUSDT_UMCBL"
}
],
"msg":"success",
"requestTime":1627116936176
}
Get Candle Data
Limit rule: 20 times/1s (IP)
HTTP Request
- GET /api/mix/v1/market/candles
Request Parameter(Request Param)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
granularity | String | Yes | Types of candlestick |
startTime | String | Yes | Start time (Timestamp ms) |
endTime | String | Yes | End time (Timestamp ms) |
Response
[
[
"1627008780000",
"24016.0000000000000000",
"24016.0000000000000000",
"24016.0000000000000000",
"24016.0000000000000000",
"0.000000000000",
"0.000000000000"
],
[
"1627008840000",
"24016.0000000000000000",
"24016.0000000000000000",
"24016.0000000000000000",
"24016.0000000000000000",
"0.000000000000",
"0.000000000000"
]
]
Response Description
Parameter |
---|
Timestamp |
Opening price |
Highest price |
Lowest price |
Closing price |
Base currency trading volume |
Quote currency trading volume |
Get Symbol Index Price
Limit rule: 20 times/1s (IP)
HTTP Request
- GET /api/mix/v1/market/index
Request Parameter(Request Param)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
Response
{
"code":"00000",
"data":{
"symbol":"BTCUSDT_UMCBL",
"index":"35000",
"timestamp":"1627291836179"
},
"msg":"success",
"requestTime":1627291836179
}
Response Description
Parameter | Description |
---|---|
symbol | Currency pair name (Must be capitalized) |
index | Index price |
timestamp | Timestamp |
Get Symbol Next Funding Time
Limit rule: 20 times/1s (IP)
HTTP Request
- GET /api/mix/v1/market/funding-time
Request Parameter(Request Param)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
Response
{
"code":"00000",
"data":{
"symbol":"BTCUSDT_UMCBL",
"fundingTime":"1627311600000"
},
"msg":"success",
"requestTime":1627291915767
}
Response Description
Parameter | Description |
---|---|
symbol | Currency pair name |
fundingTime | Next settlement time |
Get History Funding Rate
Limit rule: 20 times/1s (IP)
HTTP Request
- GET /api/mix/v1/market/history-fundRate
Request Parameter(Request Param)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
pageSize | int | No | Page Size Default 20 |
pageNo | int | No | Page No |
nextPage | Boolean | No | Whether to query the next page default false |
Response
{
"code":"00000",
"data":[
{
"symbol":"BTCUSDT",
"fundingRate":"0",
"settleTime":"1627369200000"
}
],
"msg":"success",
"requestTime":1627389063463
}
Response Description
Parameter | Description |
---|---|
symbol | Currency pair name |
fundingRate | Current funding rate |
settleTime | Settlement time |
Get Current Funding Rate
Limit rule: 20 times/1s (IP)
HTTP Request
- GET /api/mix/v1/market/current-fundRate
Request Parameter(Request Param)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
Response
{
"code":"00000",
"data":{
"symbol":"BTCUSDT_UMCBL",
"fundingRate":"0.0002"
},
"msg":"success",
"requestTime":1627291969594
}
Response Description
Parameter | Description |
---|---|
symbol | Currency pair name |
fundingRate | Current funding rate |
Get Open Interest
Limit rule: 20 times/1s (IP)
HTTP Request
- GET /api/mix/v1/market/open-interest
Request Parameter(Request Param)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
Response
{
"code":"00000",
"data":{
"symbol":"BTCUSDT_UMCBL",
"amount":"757.8338",
"timestamp":"1627292005913"
},
"msg":"success",
"requestTime":1627292005913
}
Response Description
Parameter | Description |
---|---|
symbol | Currency pair name |
amount | Total platform position |
timsetamp | Timestamp (milliseconds) |
Get Symbol Mark Price
Limit rule: 20 times/1s (IP)
HTTP Request
- GET /api/mix/v1/market/mark-price
Request Parameter(Request Param)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
Response
{
"code":"00000",
"data":{
"symbol":"BTCUSDT_UMCBL",
"markPrice":"35000",
"timestamp":"1627292076687"
},
"msg":"success",
"requestTime":1627292076687
}
Response Description
Parameter | Description |
---|---|
symbol | Currency pair name |
markPrice | Mark price |
timsetamp | Timestamp (milliseconds) |
Get Symbol Leverage
Limit rule: 20次/1s (IP)
HTTP Request
- GET /api/mix/v1/market/symbol-leverage
Request Parameter(Request Param)
Parameter | type | required | description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
Success Response
{
"code":"00000",
"data":{
"symbol":"BTCUSDT_UMCBL",
"minLeverage":"1",
"maxLeverage":"125"
},
"msg":"success",
"requestTime":1627292076687
}
Response Description
Parameter | Description |
---|---|
symbol | symbol id |
minLeverage | min leverage |
maxLeverage | max leverage |
Account
Get Single Account
Limit rule: 20 times/2s (uid)
HTTP Request
- GET /api/mix/v1/account/account
Request Parameter
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
marginCoin | String | Yes | Margin currency |
Response
{
"code":"00000",
"data":{
"marginCoin":"USDT",
"locked":0,
"available":13168.86110692,
"crossMaxAvailable":13168.86110692,
"fixedMaxAvailable":13168.86110692,
"maxTransferOut":13168.86110692,
"equity":13178.86110692,
"usdtEquity":13178.861106922,
"btcEquity":0.344746495477,
"crossRiskRate":0,
"crossMarginLeverage":20,
"fixedLongLeverage":20,
"fixedShortLeverage":20,
"marginMode":"crossed",
"holdMode":"double_hold"
},
"msg":"success",
"requestTime":1627292199523
}
Response Description
Parameter | Description |
---|---|
marginCoin | Margin currency |
locked | Locked amount (margin currency) |
available | Number of accounts available |
crossMaxAvailable | The maximum open position balance available for the whole position (margin currency) |
fixedMaxAvailable | The maximum isolated margin can be used to open a position (margin currency) |
maxTransferOut | Maximum transferable |
equity | Account equity (margin currency) |
usdtEquity | Convert USDT account equity |
btcEquity | Convert BTC account equity |
crossRiskRate | Risk ratio at full position |
crossMarginLeverage | Leverage level for full position |
fixedLongLeverage | Long leverage with isolated margin |
fixedShortLeverage | Short leverage with isolated margin |
marginMode | Margin mode |
holdMode | Hold position mode |
Get Account List
Limit rule: 20 times/2s (uid)
HTTP Request
- GET /api/mix/v1/account/accounts
Request Parameter
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
productType | String | Yes | product type |
Response
{
"code":"00000",
"data":[
{
"marginCoin":"USDT",
"locked":"0.31876482",
"available":"10575.26735771",
"crossMaxAvailable":"10580.56434289",
"fixedMaxAvailable":"10580.56434289",
"maxTransferOut":"10572.92904289",
"equity":"10582.90265771",
"usdtEquity":"10582.902657719473",
"btcEquity":"0.204885807029"
}
],
"msg":"success",
"requestTime":1630901215622
}
Response Description
Parameter | Description |
---|---|
marginCoin | Margin currency |
locked | Locked amount (margin currency) |
available | Number of accounts available |
crossMaxAvailable | The maximum open position balance available for the whole position (margin currency) |
fixedMaxAvailable | The maximum isolated margin can be used to open a position (margin currency) |
maxTransferOut | Maximum transferable |
equity | Account equity (margin currency) |
usdtEquity | Convert USDT account equity |
btcEquity | Convert BTC account equity |
Get Open Count
Limit rule: 20 times/1s (IP)
This interface is only used to calculate the maximum number of positions that can be opened when the user does not hold a position by default. The result does not represent the actual number of positions opened.
HTTP Request
- POST /api/mix/v1/account/open-count
Request Parameter(Request Body)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
marginCoin | String | Yes | Margin currency (Must be capitalized) |
openPrice | BigDecimal | Yes | Opening price |
leverage | BigDecimal | No | Default leverage is 20 |
openAmount | BigDecimal | Yes | Opening amount |
Response
{
"code":"00000",
"data":{
"openCount":"2000"
},
"msg":"success",
"requestTime":1627293049406
}
Change Leverage
Limit rule: 5 times/2s (uid)
HTTP Request
- POST /api/mix/v1/account/setLeverage
Request Parameter(Request Body)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
marginCoin | String | Yes | Margin currency (Must be capitalized) |
leverage | String | Yes | Leverage |
holdSide | String | No | Position direction (the whole position is not transmitted) |
Response
{
"code":"00000",
"data":{
"symbol":"BTCUSDT_UMCBL",
"marginCoin":"USDT",
"longLeverage":25,
"shortLeverage":20,
"marginMode":"crossed"
},
"msg":"success",
"requestTime":1627293049406
}
Response Description
Parameter | Description |
---|---|
symbol | Currency pair name |
marginCoin | Margin currency |
longLeverage | Long leverage |
shortLeveage | Short leverage |
marginMode | Margin Mode |
Change Margin
Limit rule: 5 times/2s (uid)
HTTP Request
- POST /api/mix/v1/account/setMargin
Request Parameter(Request Body)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
marginCoin | String | Yes | Margin currency (Must be capitalized) |
amount | String | Yes | margin amount |
holdSide | String | No | Position direction (the whole position is not transmitted |
Response
{
"code":"00000",
"data":{
"result":true
},
"msg":"success",
"requestTime":1627293357336
}
Change Margin Mode
Limit rule: 5 times/2s (uid)
HTTP Request
- POST /api/mix/v1/account/setMarginMode
Request Parameter(Request Body)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
marginCoin | String | Yes | Margin currency (Must be capitalized) |
marginMode | String | Yes | Margin mode |
Response
{
"code":"00000",
"data":{
"symbol":"BTCUSDT_UMCBL",
"marginCoin":"USDT",
"longLeverage":25,
"shortLeverage":20,
"marginMode":"corssed"
},
"msg":"success",
"requestTime":1627293445916
}
Response Description
Parameter | Description |
---|---|
symbol | Currency pair name |
marginCoin | Margin currency |
longLeverage | Long leverage |
shortLeveage | Short leverage |
marginMode | Margin mode |
Get Symbol Position
Limit rule: 20 times/2s (uid)
HTTP Request
- GET /api/mix/v1/position/singlePosition
Request Parameter(Request Param)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
marginCoin | String | No | Margin currency (Must be capitalized) |
Response
{
"code":"00000",
"data":[
{
"marginCoin":"USDT",
"symbol":"BTCUSDT_UMCBL",
"holdSide":"long",
"openDelegateCount":"0",
"margin":"10",
"available":"0",
"locked":"0",
"total":"0",
"leverage":25,
"achievedProfits":"0",
"averageOpenPrice":"0",
"marginMode":"fixed",
"holdMode":"double_hold",
"unrealizedPL":"0",
"keepMarginRate":"0.015",
"ctime":"1626232130664"
}
],
"msg":"success",
"requestTime":1627293612502
}
Response Description
Parameter | Description |
---|---|
symbol | Currency pair name |
marginCoin | Margin currency |
holdSide | Position direction |
openDelegateCount | Number of positions opened (trading currency) |
margin | Margin quantity (margin currency) |
available | Position available (Quote currency) |
locked | Position freeze (Quote currency) |
total | Total position (available + locked) |
leverage | Leverage |
achievedProfits | Realized profit and loss |
averageOpenPrice | Average opening price |
marginMode | Margin mode |
holdMode | Position mode |
unrealizedPL | Unrealized profit and loss |
keepMarginRate | keep margin rate |
cTime | Last update time Timestamp milliseconds |
Get All Position
Limit rule: 5 times/2s (uid)
HTTP Request
- GET /api/mix/v1/position/allPosition
Request Parameter(Request Param)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
productType | String | Yes | Product type |
marginCoin | String | No | Margin currency (Must be capitalized) |
Response
{
"code":"00000",
"data":[
{
"marginCoin":"USDT",
"symbol":"BTCUSDT_UMCBL",
"holdSide":"long",
"openDelegateCount":"0",
"margin":"10",
"available":"0",
"locked":"0",
"total":"0",
"leverage":25,
"achievedProfits":"0",
"averageOpenPrice":"0",
"marginMode":"fixed",
"holdMode":"double_hold",
"unrealizedPL":"0",
"keepMarginRate":"0",
"ctime":"1626232130664"
}
],
"msg":"success",
"requestTime":1627293612502
}
Response Description
Parameter | Description |
---|---|
symbol | Currency pair name |
marginCoin | Margin currency |
holdSide | Position direction |
openDelegateCount | Number of positions opened (trading currency) |
margin | Margin quantity (margin currency) |
available | Position available (Quote currency) |
locked | Position freeze (Quote currency) |
total | Total position (available + locked) |
leverage | Leverage |
achievedProfits | Realized profit and loss |
averageOpenPrice | Average opening price |
marginMode | Margin mode |
holdMode | Position mode |
unrealizedPL | Unrealized profit and loss |
keepMarginRate | keep margin rate |
cTime | Last update time Timestamp milliseconds |
Get Account Bill
Limit rule: 10次/1s (uid)
HTTP Request
- GET /api/mix/v1/account/accountBill
Request (Request Param)
Parameter | type | required | description |
---|---|---|---|
symbol | String | Yes | Symbol Id |
marginCoin | String | Yes | margin coin |
startTime | String | Yes | Start Time (timestamp mills) |
endTime | String | Yes | end time (timestamp mills) |
pageSize | int | No | page size, default 20, max is 100 |
lastEndId | String | No | last end id |
next | boolean | No | Is query next page? default false |
Response
{
"code": "00000",
"msg": "success",
"data": {
"result": [
{
"id": "892962903462432768",
"symbol": "ETHUSDT_UMCBL",
"marginCoin": "USDT",
"amount": "0",
"fee": "-0.1765104",
"feeByCoupon": "",
"feeCoin": "USDT",
"business": "open_long",
"ctime": "1648624867354"
}
],
"endId": "885353495773458432",
"nextFlag": false,
"preFlag": false
}
}
Response params
Parameter | Description |
---|---|
id | record no |
symbol | Symbol Id |
marginCoin | margin Coin |
amount | change amount |
fee | fee |
feeByCoupon | fee deduction coupon |
feeCoin | fee coin |
business | type |
cTime | create time |
lastEndId | last end id |
- business
- open_long
- open_short
- close_long
- close_short
- trans_from_exchange transfer in from spot account
- trans_to_exchange transfer out to spot account
Trade
Place Order
Limit rule: 10 times/1s (uid)
HTTP Request
- POST /api/mix/v1/order/placeOrder
Request Parameter(Request Body)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | product Id |
marginCoin | String | Yes | Margin currency |
size | String | Yes | Order quantity (not transmitted at market price) |
price | String | No | Order price (not transmitted at market price) |
side | String | Yes | Order direction |
orderType | String | Yes | Order type |
timeInForceValue | String | No | Order validity period |
clientOid | String | No | Client ID is unique |
presetTakeProfitPrice | String | No | Preset take profit price |
presetStopLossPrice | String | No | Preset stop loss price |
Response Data
{
"code":"00000",
"data":{
"orderId":"1627293504612",
"clientOid":"BITGET#1627293504612"
},
"msg":"success",
"requestTime":1627293504612
}
Response Description
Parameter | Description |
---|---|
orderId | Order Id |
clientOid | Client custom Id |
Batch Order
Limit rule: 10 times/1s (uid)
HTTP Request
- POST /api/mix/v1/order/batch-orders
Request Parameter(Request Body)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
marginCoin | String | Yes | Margin currency (Must be capitalized) |
orderDataList | List | Yes | Order data list |
orderDataList
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
size | String | Yes | Order quantity |
price | String | No | Order price |
side | String | Yes | Order direction |
orderType | String | Yes | Order type |
timeInForceValue | String | No | Order validity period |
clientOid | String | No | Client ID is unique |
Response
{
"code": "00000",
"data": {
"orderInfo": [
{
"orderId": "1627293504612",
"clientOid": "BITGET#1627293504612"
}
]
},
"msg": "success",
"requestTime": 1627293504612
}
Response Description
Parameter | Description |
---|---|
orderId | Order Id |
clientOid | Client custom Id |
Cancel Order
Limit rule: 10 times/1s (uid)
HTTP Request
- POST /api/mix/v1/order/cancel-order
Request Parameter(Request Body)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
marginCoin | String | Yes | Margin currency (Must be capitalized) |
orderId | String | Yes | Order Id |
Response
{
"code":"00000",
"data":{
"orderId":"1627293504612",
"clientOid":"BITGET#1627293504612"
},
"msg":"success",
"requestTime":1627293504612
}
Response Description
Parameter | Description |
---|---|
orderId | Order Id |
clientOid | Client custom Id |
Batch Cancel Order
Limit rule: 10 times/1s (uid)
HTTP Request
- POST /api/mix/v1/order/cancel-batch-orders
Request Parameter(Request Body)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
marginCoin | String | Yes | Margin currency (Must be capitalized) |
orderIds | List | Yes | Order Id list |
Response
{
"code": "00000",
"data": {
"symbol": "BTCUSDT_UMCBL",
"order_ids": [
"1627293504612"
],
"fail_infos": [
{
"order_id": "",
"err_code": "",
"err_msg": ""
}
]
},
"msg": "success",
"requestTime": 1627293504612
}
Response Description
Parameter | Description |
---|---|
orderId | Order Id |
clientOid | Client custom Id |
Get Open Order
Limit rule: 20 times/2s (uid)
HTTP Request
- GET /api/mix/v1/order/current
Request Parameter(Request Param)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
Response
{
"code":"00000",
"data":{
[
{
"symbol":"BTCUSDT_UMCBL",
"size":1,
"orderId":"802382049422487552",
"clientOid":"RFIut#1627028708738",
"filledQty":0,
"fee":0,
"price":23999.3,
"state":"canceled",
"side":"open_long",
"timeInForce":"normal",
"totalProfits":0,
"posSide":"long",
"marginCoin":"USDT",
"ctime":1627028708807
}
]
},
"msg":"success"
}
Response Description
Parameter | Description |
---|---|
symbol | Trading pair name |
size | Order size |
orderId | Order Id |
clientOid | Client custom id |
filledQty | Transaction volume |
fee | Transaction fee |
price | Order price |
state | Order status |
side | Order direction |
timeInForce | Order validity period |
totalProfits | Total profit and loss |
posSide | Position direction |
marginCoin | Margin currency |
cTime | Last update time |
Get History Orders
Limit rule: 20 times/2s (uid)
HTTP Request
- GET /api/mix/v1/order/history
Request Parameter(Request Param)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
startTime | String | Yes | Start time (timestamp) |
endTime | String | Yes | End time (time stamp) |
pageSize | String | Yes | Number of queries |
lastEndId | String | No | Last query orderId |
isPre | Boolean | No | Whether to query the previous page (default false) |
Response
{
"code":"00000",
"data":{
[
{
"symbol":"BTCUSDT_UMCBL",
"size":1,
"orderId":"802382049422487552",
"clientOid":"RFIut#1627028708738",
"filledQty":0,
"fee":0,
"price":23999.3,
"state":"canceled",
"side":"open_long",
"timeInForce":"normal",
"totalProfits":0,
"posSide":"long",
"marginCoin":"USDT",
"ctime":1627028708807
}
]
},
"msg":"success"
}
Response Description
Parameter | Description |
---|---|
symbol | Trading pair name |
size | Order size |
orderId | Order Id |
clientOid | Client custom id |
filledQty | Transaction volume |
fee | Transaction fee |
price | Order price |
state | Order status |
side | Order direction |
timeInForce | Order validity period |
totalProfits | Total profit and loss |
posSide | Position direction |
marginCoin | Margin currency |
cTime | Last update time |
Get Order Details
Limit rule: 20 times/2s (uid)
HTTP Request
- GET /api/mix/v1/order/detail
Request Parameter (Request Param)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
orderId | String | Yes | Order Id |
Response
{
"code":"00000",
"data":{
"symbol":"BTCUSDT_UMCBL",
"size":1,
"orderId":"802382049422487552",
"clientOid":"RFIut#1627028708738",
"filledQty":0,
"priceAvg":0,
"fee":0,
"price":23999.3,
"state":"canceled",
"side":"open_long",
"timeInForce":"normal",
"totalProfits":0,
"posSide":"long",
"marginCoin":"USDT",
"presetTakeProfitPrice":69582.5,
"presetStopLossPrice":21432.5,
"filledAmount":45838,
"orderType":"limit",
"cTime":1627028708807,
"uTime":1627028717807
},
"msg":"success",
"requestTime":1627300098776
}
Response Description
Parameter | Description |
---|---|
symbol | Trading pair name |
size | Order size |
orderId | Order Id |
clientOid | Client custom id |
filledQty | Transaction volume |
priceAvg | Transaction price |
fee | Transaction fee |
price | Order price |
state | Order status |
side | Order direction |
timeInForce | Order validity period |
totalProfits | Total profit and loss |
posSide | Position direction |
marginCoin | Margin currency |
cTime | create time |
presetTakeProfitPrice | Preset take profit price |
Get Order fill detail
Limit rule: 20 times/2s (uid)
HTTP Request
- GET /api/mix/v1/order/fills
Request Parameter (Request Param)
Parameter | Type | Required | Description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
orderId | String | No | Order Id |
startTime | String | No | Start time (timestamp in milliseconds) This field is required if querying all details |
endTime | String | No | End time (timestamp in milliseconds) This field is required if querying all details |
lastEndId | String | No | Query the data after this tradeId |
Response Data
{
"code":"00000",
"data":[
{
"tradeId":"802377534023585793",
"symbol":"BTCUSDT_UMCBL",
"orderId":"802377533381816325",
"price":"0",
"sizeQty":"0.3247",
"fee":"0E-8",
"side":"burst_close_long",
"ctime":"1627027632241"
}
],
"msg":"success",
"requestTime":1627386245672
}
Response Description
Parameter | Description |
---|---|
tradeId | Trade Id |
symbol | Trading pair name |
orderId | Order Id |
price | Transaction price |
sizeQty | Transaction volume |
fee | Transaction fee |
side | Trade type |
cTime | Trade time |
Place Plan order
Limit rule: 10 times/1s (uid)
HTTP Request
- POST /api/mix/v1/plan/placePlan
Request Parameter (Request Body)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
marginCoin | String | Yes | Margin currency (Must be capitalized) |
size | String | Yes | Order quantity (not transmitted at market price) |
executePrice | String | No | Strike price |
triggerPrice | String | Yes | Trigger price |
side | String | Yes | Order Side |
orderType | String | Yes | Order Type |
triggerType | String | Yes | Trigger type |
clientOid | String | No | Client ID is unique within 24 hours |
presetTakeProfitPrice | String | No | Preset take profit price |
presetStopLossPrice | String | No | Preset stop price |
Response
{
"code":"00000",
"data":{
"clientOid":"RFIut#1627300490884",
"orderId":"803521986049314816"
},
"msg":"success",
"requestTime":1627300490899
}
Response Description
Parameter | Description |
---|---|
clientOid | Client custom Id |
orderId | Order Id |
Modify Plan Order
Limit rule: 10 times/1s (uid)
HTTP Request
- POST /api/mix/v1/plan/modifyPlan
Request Parameter (Request Body)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
orderId | String | Yes | Limit order Id |
marginCoin | String | Yes | Margin currency |
symbol | String | Yes | Currency pair name |
executePrice | String | No | Strike price |
triggerPrice | String | Yes | Trigger price |
triggerType | String | Yes | Trigger type |
orderType | String | Yes | Trading Type |
Response
{
"code":"00000",
"data":{
"clientOid":"RFIut#1627300490884",
"orderId":"803521986049314816"
},
"msg":"success",
"requestTime":1627300490899
}
Response Description
Parameter | Description |
---|---|
clientOid | Client custom Id |
orderId | Order Id |
Modify Plan Order TPSL
Limit rule: 10 times/1s (uid)
HTTP Request
- POST /api/mix/v1/plan/modifyPlanPreset
Request Parameter (Request Body)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
orderId | String | Yes | Limit order Id |
marginCoin | String | Yes | Margin currency (Must be capitalized) |
symbol | String | Yes | product Id (Must be capitalized) |
presetTakeProfitPrice | String | No | Take profit price If it is empty, cancel and take profit |
presetStopLossPrice | String | No | Stop loss price If it is empty, cancel the stop loss |
Response
{
"code":"00000",
"data":{
"clientOid":"RFIut#1627300490884",
"orderId":"803521986049314816"
},
"msg":"success",
"requestTime":1627300490899
}
Response Description
Parameter | Description |
---|---|
clientOid | Client custom Id |
orderId | Order Id |
Place Stop Order
Limit rule: 10 times/1s (uid)
At present, take-profit and stop-loss orders are only supported at market price, and the trigger type is transaction trigger price
HTTP Request
- POST /api/mix/v1/plan/placeTPSL
Request Parameter(Request Body)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
marginCoin | String | Yes | Margin currency (Must be capitalized) |
symbol | String | Yes | product Id (Must be capitalized) |
planType | String | Yes | Take-profit and stop-loss type |
triggerPrice | String | No | Trigger price |
holdSide | String | No | Whether this position is long or short |
size | String | No | Order Quantity Default Position Quantity |
Response
{
"code":"00000",
"data":{
"clientOid":"RFIut#1627300490884",
"orderId":"803521986049314816"
},
"msg":"success",
"requestTime":1627300490899
}
Response Description
Parameter | Description |
---|---|
clientOid | Client custom Id |
orderId | Order Id |
Modify Stop Order
Limit rule: 10 times/1s (uid)
HTTP Request
- POST /api/mix/v1/plan/modifyTPSLPlan
Request Parameter(Request Body)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
orderId | String | Yes | Take-profit and stop-loss order Id |
marginCoin | String | Yes | Margin currency (Must be capitalized) |
symbol | String | Yes | product Id (Must be capitalized) |
triggerPrice | String | No | Trigger price |
Response
{
"code":"00000",
"data":{
"clientOid":"RFIut#1627300490884",
"orderId":"803521986049314816"
},
"msg":"success",
"requestTime":1627300490899
}
Response Description
Parameter | Description |
---|---|
clientOid | Client custom Id |
orderId | Order Id |
Cancel Plan Order (TPSL)
Limit rule: 10 times/1s (uid)
HTTP Request
- POST /api/mix/v1/plan/cancelPlan
Request Parameter(Request Body)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
orderId | String | Yes | Limit order Id |
symbol | String | Yes | product Id (Must be capitalized) |
planType | String | Yes | Cancellation type |
Response
{
"code":"00000",
"data":{
"clientOid":"RFIut#1627300490884",
"orderId":"803521986049314816"
},
"msg":"success",
"requestTime":1627300490899
}
Response Description
Parameter | Description |
---|---|
clientOid | Client custom Id |
orderId | Order Id |
Get Plan Order (TPSL) List
Limit rule: 20 times/2s (uid)
HTTP Request
- GET /api/mix/v1/plan/currentPlan
Request Parameter(Request Param)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
isPlan | String | No | Query type |
Response
{
"code":"00000",
"data":[
{
"orderId":"803521986049314816",
"symbol":"BTCUSDT_UMCBL",
"marginCoin":"USDT",
"size":"1",
"executePrice":"38923.1",
"triggerPrice":"45000.3",
"status":"not_trigger",
"orderType":"limit",
"planType":"normal_plan",
"side":"open_long",
"triggerType":"fill_price",
"presetTakeProfitPrice":"0",
"presetTakeLossPrice":"0",
"ctime":"1627300490867"
}
],
"msg":"success",
"requestTime":1627354109502
}
Response Description
Parameter | Description |
---|---|
orderId | Order Id |
symbol | Currency pair name |
marginCoin | Margin currency |
size | Order size |
executePrice | Order price |
triggerPrice | Trigger price |
status | Order status |
orderType | Trade type |
planType | Order type |
side | Order direction |
triggerType | Trigger type |
presetTakeProfitPrice | Preset take profit price |
presetTakeLossPrice | Preset stop loss price |
ctime | Order creation time |
Get History Plan Orders (TPSL)
Limit rule: 20 times/2s (uid)
HTTP Request
- GET /api/mix/v1/plan/historyPlan
Request Parameter (Request Param)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
startTime | String | Yes | Start time |
endTime | String | Yes | End time |
pageSize | Integer | No | Number of queries default 100 |
isPre | boolean | No | Whether to query the previous page |
isPlan | String | No | Query type |
Response
{
"code":"00000",
"data":[
{
"orderId":"803521986049314816",
"executeOrderId":"84271931884910",
"symbol":"BTCUSDT_UMCBL",
"marginCoin":"USDT",
"size":"1",
"executePrice":"38923.1",
"triggerPrice":"45000.3",
"status":"not_trigger",
"orderType":"limit",
"planType":"normal_plan",
"side":"open_long",
"triggerType":"fill_price",
"presetTakeProfitPrice":"0",
"presetTakeLossPrice":"0",
"ctime":"1627300490867"
}
],
"msg":"success",
"requestTime":1627354109502
}
Response Description
Parameter | Description |
---|---|
orderId | Order Id |
executeOrderId | Execute success Order Id |
symbol | Currency pair name |
marginCoin | Margin currency |
size | Order size |
executeSize | execute Size |
executePrice | Order price |
triggerPrice | Trigger price |
status | Order status |
orderType | Trade type |
planType | Order type |
side | Order direction |
triggerType | Trigger type |
CopyTrade
Get Trader Open order
Limit rule 20 times/2s (uid)
HTTP Request
- GET /api/mix/v1/trace/currentTrack
Request Parameter(Request Param)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
productType | String | Yes | product type |
pageSize | int | Yes | Number of queries |
pageNo | int | Yes | Current page number |
Response
{
"code":"00000",
"data":[
{
"symbol":"BTCUSDT_UMCBL",
"trackingNo":"699848017573842632",
"openOrderId":"4839999132328",
"holdSide":"long",
"openLeverage":20,
"avgOpenPrice":11451.5,
"openTime":1602582690614,
"openDealCount":"10",
"stopProfitPrice":"123.14",
"stopLossPrice":"20.52"
}
],
"msg":"success",
"requestTime":1627354109502
}
Response Description
Parameter | Description |
---|---|
trackingNo | Tracking order number |
openOrderId | Trader’s order number This order number cannot be used when the trader closes a position, and a tracking order number is required |
symbol | Trading pair name |
holdSide | Current position direction |
openLeverage | Opening leverage |
avgOpenPrice | Average opening price |
openTime | Position opening time (milliseconds) |
openDealCount | Number of positions opened |
stopProfitPrice | Take profit price |
stopLossPrice | Stop price |
Get Followers Open Order
Limit rule 20 times/2s (uid)
HTTP Request
- GET /api/mix/v1/trace/followerOrder
Request Parameter(Request Param)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
productType | String | Yes | product type |
pageSize | int | Yes | Number of queries |
pageNo | int | Yes | Current page number |
Response
{
"code":"00000",
"data":[
{
"trackingNo":"804641389214179330",
"openOrderId":"804641382428463106",
"closeOrderId":"",
"symbol":"BTCUSDT_UMCBL",
"holdSide":"short",
"openLeverage":47,
"openAvgPrice":39827,
"openTime":1627567376984,
"openDealCount":"0.0010000000000000",
"openMargin":"21",
"averageClosePrice":0,
"closeDealCount":"0.0000000000000000",
"closeTime":0
}
],
"msg":"success",
"requestTime":1634107646972
}
Response Description
Parameter | Description |
---|---|
trackingNo | Tracking order number |
openOrderId | Open Position Order Id |
closeOrderId | Close Position Order Id |
symbol | Trading pair name |
holdSide | Current position direction |
openLeverage | Opening leverage |
openAvgPrice | Average opening price |
openTime | Position opening time (milliseconds) |
openDealCount | Number of positions opened |
openMargin | Open |
averageClosePrice | Average Close Price |
closeDealCount | Close Count |
closeTime | Close Position Time (milliseconds) |
Trader Close Position
Limit rule 10 times/1s (uid)
HTTP Request
- POST /api/mix/v1/trace/closeTrackOrder
Request Parameter (Request Body)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | product Id (Must be capitalized) |
trackingNo | String | Yes | Order Id From the /currentTrack "trackingNo" field |
Response
{
"code":"00000",
"data":{
"trackingNo":6258224712558517,
"result":true
},
"msg":"success",
"requestTime":1627354109502
}
Response Description
Parameter | Description |
---|---|
trackingNo | Tracking order number |
result | Tracking order number |
Get Traders History Orders
Limit rule 20 times/2s (uid)
HTTP Request
- GET /api/mix/v1/trace/historyTrack
Request Parameter (Request Param)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
startTime | String | Yes | Start time timestamp (milliseconds) |
endTime | String | Yes | End time timestamp (milliseconds) |
pageSize | int | Yes | Number of queries |
pageNo | int | Yes | Current page number |
Response
{
"code":"00000",
"data":[
{
"symbol":"BTCUSDT_UMCBL",
"trackingNo":"682799071840175632",
"holdSide":"long",
"openLevel":20,
"openAvgPrice":"11366.50",
"openTime":1627356444000,
"closeDealCount":"10",
"closeTime":1626838044000,
"closeAvgPrice":"11272.00",
"stopType":"profit",
"achievedProfits":"-0.07650000",
"openFee":"-0.00680910",
"closeFee":"0.000000"
}
],
"msg":"success",
"requestTime":1627354109502
}
Response Description
Parameter | Description |
---|---|
trackingNo | Tracking order number |
symbol | Trading pair name |
holdSide | Current position direction |
openLeverage | Opening leverage |
openAvgPrice | Average opening price |
openTime | Position opening time (milliseconds) |
close | Closing time (milliseconds) |
closeAvgPrice | Average closing price |
stopType | Closing type |
achievedProfits | Realized profit and loss |
openFee | Opening fee |
closeFee | Closing fee |
closeDealCount | Number of closed Positions |
Get Trader Profit Summary
Limit rule 20 times/2s (uid) HTTP Request
- GET /api/mix/v1/trace/summary
Response
{
"code":"00000",
"data":{
"yesterdaySplitProfit":"0",
"sumProfit":"0",
"waitProfit":"0",
"yesterdayTimeStamp":"1627354109502"
},
"msg":"success",
"requestTime":1627354109502
}
Response Description
Parameter | Description |
---|---|
yesterdaySplitProfit | Yesterday's Profit Sharing (Trader) |
yesterdayTimeStamp | Yesterday's profit sharing time (milliseconds) |
sumProfit | Cumulative profit |
waitProfit | Profits to be shared |
Get Trader History Profit Summary (according to settlement currency)
Limit rule 20 times/2s (uid)
HTTP Request
- GET /api/mix/v1/trace/profitSettleTokenIdGroup
Response
{
"code":"00000",
"data":[
{
"settleTokenId":"usdt",
"profit":"0"
}
],
"msg":"success",
"requestTime":1627354109502
}
Response Description
Parameter | Description |
---|---|
settleTokenId | Settlement currency |
profit | Profit |
Get Trader History Profit Summary (according to settlement currency and date)
Limit rule 20 times/2s (uid)
HTTP Request
- GET /api/mix/v1/trace/profitDateGroupList
Response
{
"code":"00000",
"data":[
{
"settleTokenId":"usdt",
"profit":"0",
"date":1627354109502
}
],
"msg":"success",
"requestTime":1627354109502
}
Response Description
Parameter | Description |
---|---|
settleTokenId | Settlement currency |
profit | Porfit |
date | Margin time (milliseconds) |
Get Trader Histroy Profit Detail
Limit rule 20 times/2s (uid)
HTTP Request
- GET /api/mix/v1/trace/profitDateList
Request Parameter(Request Param)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
marginCoin | String | Yes | Margin currency |
date | String | Yes | Profit sharing time |
pageSize | int | Yes | Number of queries |
pageNo | int | Yes | Current page number |
Response
{
"code":"00000",
"data":[
{
"settleTokenId":"usdt",
"profit":"0",
"nickName":"bitget"
}
],
"msg":"success",
"requestTime":1627354109502
}
Response Description
Parameter | Description |
---|---|
settleTokenId | Settlement currency |
profit | Profit has been shared |
nickName | Nickname |
Get Trader Profits Details
Limit rule 20 times/2s (uid)
HTTP Request
- GET /api/mix/v1/trace/waitProfitDateList
Request Parameter(Request Param)
Parameter Name | Parameter Type | Required? | Description |
---|---|---|---|
pageSize | int | Yes | Number of queries |
pageNo | int | Yes | Current page number |
Response
{
"code":"00000",
"data":[
{
"settleTokenId":"usdt",
"profit":"0",
"nickName":"bitget"
}
],
"msg":"success",
"requestTime":1627354109502
}
Response Description
Parameter | Description |
---|---|
settleTokenId | Settlement currency |
profit | Profit |
nickName | Nickname |
Get CopyTrade Symbols
Limit rule 20 Times/2s (uid)
HTTP Request
- GET /api/mix/v1/trace/traderSymbols
Response
{
"code":"00000",
"data":[
{
"symbol":"BTCUSDT",
"openTrader":true
},
"symbol":"BTCUSD",
"openTrader":false
}
],
"msg":"success",
"requestTime":1634723284625
}
Response Description
Parameter | Description |
---|---|
symbolId | Symbol Id |
openTrade | Whether to open copy trade |
Trader Change CopyTrade symbol
Limit rule 10 Times/1s (uid)
HTTP Request
- POST /api/mix/v1/trace/setUpCopySymbols
Request Param(Request Body)
Parameter name | Type | Required | Desciption |
---|---|---|---|
symbol | String | Yes | Symbol Id /contracts symbol |
operation | String | Yes | Add or delete add delete |
返回数据
{
"code":"00000",
"data":"",
"msg":"success",
"requestTime":1627354109502
}
WebSocketAPI
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.
It is strongly recommended that developers use WebSocket API to obtain market information and transaction depth.
domain | WebSocket API | Recommended to use |
---|---|---|
domain 1 | wss://ws.bitget.com/mix/v1/stream | internationality |
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
If there’s a network problem, the system will automatically disable the connection.
The connection will break automatically if the subscription is not established or data has not been pushed for more than 30 seconds.
To keep the connection stable:
- Set a timer of N seconds whenever a response message is received, where N is less than 30.
- If the timer is triggered, which means that no new message is received within N seconds, send the String 'ping'.
- Expect a 'pong' as a response. If the response message is not received within N seconds, please raise an error or reconnect.
Login
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'+'/user/verify', secretKey))
method: always 'GET'.
requestPath : always '/user/verify'
The request will expire 30 seconds after the timestamp. If your server time differs from the API server time, we recommended using the REST API to query the API server time and then set the timestamp.
For the description of the signature method, refer to the verification section in the API overview
Steps to generate the final signature:
Step 1. Use the private key secretkey to encrypt the string to be signed with hmac sha256
Signature = hmac_sha256(secretkey, Message)
The second step is to base64 encode the Signature
Signature = base64.encode(Signature)
If login fails, it will automatically disconnect
Request format description
{
"op":"login",
"args":[
{
"apiKey":"<api_key>",
"passphrase":"<passphrase>",
"timestamp":"<timestamp>",
"sign":"<sign>"
}
]
}
Request Example
{
"op":"login",
"args":[
{
"apiKey":"bg_573af5eca856acd91c230da294ce2105",
"passphrase":"123456",
"timestamp":"1538054050",
"sign":"8RCOqCJAhhEh4PWcZB/96QojLDqMAg4qNynIixFzS3E="
}
]
}
Successful Response Example
{
"event":"login",
"code":"0",
"msg":""
}
Failure Response Example
{
"event":"error",
"code":"30005",
"msg":"error"
}
Subscribe
Subscription Instructions
Request format description
{
"op": "subscribe",
"args": ["<SubscriptionTopic>"]
}
WebSocket channels : public
.
Public channels
-- include tickers channel, K-Line channel, limit price channel, order book channel, and mark price channel, etc -- do not require log in.
instId
from /contractssymbolName
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":[
{
"instType":"mc",
"channel":"ticker",
"instId":"BTCUSDT"
},
{
"instType":"mc",
"channel":"candle5m",
"instId":"BTCUSDT"
}
]
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation, subscribe |
args | Array | Yes | List of subscribed channels |
> instType | String | No | Instrument Type MC:Public |
> channel | String | Yes | Channel name |
> instId | String | No | Instrument ID |
Example response
{ "event": "subscribe", "arg": { {"instType":"SP","channel":"ticker", "instId":"BTCUSDT" }}
Return parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Event, subscribe error |
arg | Object | No | Subscribed channel |
> instType | String | No | Instrument Type MC:Public |
> channel | String | Yes | Channel name |
> 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":[
{
"instType":"mc",
"channel":"ticker",
"instId":"BTCUSDT"
},
{
"instType":"mc",
"channel":"candle1m",
"instId":"BTCUSDT"
}
]
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation, unsubscribe |
args | Array | Yes | List of channels to unsubscribe from |
> instType | String | Yes | Instrument Type MC:Public |
> channel | String | Yes | Channel name |
> instId | String | Yes | Instrument ID |
Example response
{
"op":"unsubscribe",
"args":[
{
"instType":"mc",
"channel":"ticker",
"instId":"BTCUSDT"
},
{
"instType":"mc",
"channel":"candle1m",
"instId":"BTCUSDT"
}
]
}
Return parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Event, unsubscribe error |
arg | Object | Yes | Unsubscribed channel |
> instType | String | Yes | Instrument Type |
> channel | String | Yes | Channel name |
> instId | String | Yes | 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 amount. If the amount is 0, delete this depth data. If the amount 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 amount in an ask or a bid), and then calculate the CRC32 value (32-bit signed integer).
Calculate Checksum
1. More than 25 levels of bid and ask
A full load of market depth (only 2 levels of data are shown here, while 25 levels of data should actually be intercepted):
"bids": [
[ 43231.1, 4 ],
[ 43231, 6 ]
]
"asks": [
[ 43230.8, 9 ],
[ 43230.7, 8 ]
]
Check string:
"43231.1:4:43231:6:43230.8:9:43230.7: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:amount]
:ask[price:amount]
:bid[price:amount]
:ask[price:amount]
... - When the bid or ask depth data is less than 25 levels, the missing depth data will be ignored.
Such as:
bid[price:amount]
:ask[price:amount]
:asks[price:amount]
:asks[price:amount]
...
Public Channels
Tickers Channel
Retrieve the last traded price, bid price, ask price and 24-hour trading volume of instruments. Data will be pushed every 100 ms.
Request Example
{
"op":"subscribe",
"args":[
{
"instType":"mc",
"channel":"ticker",
"instId":"BTCUSDT"
}
]
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation, subscribe unsubscribe |
args | Array | Yes | List of subscribed channels |
> instType | String | Yes | Instrument Type MC Public Channel |
> channel | String | Yes | Channel name, tickers |
> instId | String | Yes | Instrument ID |
Successful Response Example
{ "event": "subscribe", "arg": { "instType":"mc","channel": "ticker", "instId": “BTCUSDT"} }
Failure Response Example
{ "event": "error", "code": "30001", "msg": "Unrecognized request: {\"op\": \"subscribe\", \"arg\":[ \"instType\":"\mc\",\"channel\" : \"ticker\", \"instId\" : \"BTCUSDT\"}]}" }
Response parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Event, subscribe unsubscribe error |
arg | Object | No | Subscribed channel |
> instType | String | Yes | Instrument type |
> channel | String | Yes | Channel name |
> instId | String | Yes | Instrument ID |
code | String | No | Error Code |
msg | String | No | Error Message |
Push data Example
{
"action":"snapshot",
"arg":{
"instType":"mc",
"channel":"ticker",
"instId":"BTCUSDT"
},
"data":[
{
"instId":"BTCUSDT",
"last":"44962.00",
"bestAsk":"44962",
"bestBid":"44961",
"high24h":"45136.50",
"low24h":"43620.00",
"priceChangePercent":"0.02",
"capitalRate":"-0.00010",
"nextSettleTime":1632495600000,
"systemTime":1632470889087,
"markPrice":"44936.21",
"indexPrice":"44959.23",
"holding":"1825.822",
"baseVolume":"39746.470",
"quoteVolume":"1760329683.834"
}
]
}
Push data parameters
Paramter | Type | Description |
---|---|---|
arg | Object | Successfully subscribed channel |
> instType | String | Instrument Type |
> channel | String | Channel name |
> instId | String | Instrument Name |
action | String | Push data action, incremental push data or full push data snapshot : full update : incremental |
data | Array | Subscribed data |
> instId | String | Instrument Name |
> last | String | Last traded price |
>bestAsk | String | Best ask price |
>bestBid | String | Best bid price |
>high24h | String | Highest price in the past 24 hours |
>low24h | String | Lowest price in the past 24 hours |
>priceCahngePercent | String | Price change int the past 24 hours |
>capitalRate | String | Funding rate |
>nextSettleTime | String | The next fund rate settlement time timestamp milliseconds |
>systemTime | String | system time |
>marketPrice | String | Mark price |
>indexPrice | String | Index price |
>holding | String | Open interest |
>baseVolume | String | 24h trading volume, with a unit of base . |
>quoteVolume | String | 24h trading volume, with a unit of quote |
Candlesticks Channel
Retrieve the candlesticks data of an instrument. Data will be pushed every 500 ms.
Request Example
{
"op":"subscribe",
"args":[
{
"instType":"mc",
"channel":"candle1m",
"instId":"BTCUSDT"
}
]
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation, subscribe unsubscribe |
args | Array | Yes | List of subscribed channels |
> instType | String | Yes | Instrument Type MC Public Channel |
> channel | String | Yes | Channel Name,candle1W candle1D candle12H candle4H candle1H candle30m candle15m candle5m candle1m |
> instId | String | Yes | Instrument ID |
Successful Response Example
{
"event":"subscribe",
"arg":{
"instType":"mc",
"channel":"candle1D",
"instId":"BTCUSDT"
}
}
Failure Response Example
{
"event":"error",
"code":30003,
"instType":"mc",
"channel":"candle1D",
"instId":"BTC-USDT Symbol not exists"
}
Response parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Event, subscribe unsubscribe error |
arg | Object | No | Subscribed channel |
> instType | String | Yes | Instrument Type |
> channel | String | Yes | channel name |
> instId | String | Yes | Instrument ID |
code | String | No | Error Code |
msg | String | No | Error Message |
Push Data Example
{
"arg":{
"instType":"mc",
"channel":"candle1D",
"instId":"BTCUSDT"
},
"data":[
[
"1597026383085",
"8533.02",
"8553.74",
"8527.17",
"8548.26",
"45247"
]
]
}
Push data parameters
Parameter | Type | Description |
---|---|---|
arg | Object | Successfully subscribed channel |
> instType | String | Instrument Type |
> channel | String | Channel name |
> instId | String | Instrument ID |
data | Array | Subscribed data |
> ts | String | Data generation time, Unix timestamp format in milliseconds |
> o | String | Open price |
> h | String | highest price |
> l | String | Lowest price |
> c | String | Close price |
baseVol | String | Trading volume, with a unit of contact . |
Order Book Channel
Retrieve order book data.
Use books
for snapshot data, book5
for 5 depth levels, book15
for 15 depth levels
books
: Push the full snapshot data for the first time, push incrementally later, and push incrementally later, that is, if there is a change in depth, the data that has changed once is pushed.books5
: 5 depth levels will be pushed every time. Data will be pushed every 200 ms when there is change in order book.books15
: 15 depth levels will be pushed every time. Data will be pushed every 200 ms when there is change in order book.
Request Example
{
"op":"subscribe",
"args":[
{
"instType":"mc",
"channel":"books5",
"instId":"BTCUSDT"
}
]
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation, subscribe unsubscribe |
args | Array | Yes | List of subscribed channels |
> instType | String | Yes | Instrument type MC : Hybrid contract public channel, UMCBL : Professional contract private channel, DMCBL : Hybrid contract private channel |
> channel | String | Yes | Channel name, books books5 |
> instId | String | Yes | Instrument ID |
Example Response
{
"event":"subscribe",
"arg":{
"instType":"mc",
"channel":"books5",
"instId":"BTCUSDT"
}
}
Failure example
{
"event":"error",
"code":30003,
"msg":"",
"instType":"mc",
"channel":"books5",
"instId":"BTC-USDT Symbol not exists"
}
Response parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Event,subscribe unsubscribe error |
arg | Object | No | Subscribed channel |
> instType | String | Yes | Instrument Type |
> channel | String | Yes | Channel name |
> instId | String | Yes | Instrument ID |
msg | String | No | Error Message |
code | String | No | Error Code |
Push data parameters
Parameter | Type | Description |
---|---|---|
arg | Object | Successfully subscribed channel |
> instType | String | Instrument Type |
> channel | String | Channel name |
> instId | String | Instrument ID |
action | String | Push data action, incremental push data or full push data snapshot : full update : incremental |
data | Array | Subscribed data |
> asks | Array | Order book on sell side |
> bids | Array | Order book on buy side |
> ts | String | Order book generation time, Unix timestamp format in milliseconds |
> checksum | Integer | Checksum |
An example of the array of asks and bids values: ["411.8", "10", "1", "4"] "411.8" is the depth price, "10" is the size
Trades Channel
Retrieve the recent trades data. Data will be pushed whenever there is a trade.
Request Example
{
"op":"subscribe",
"args":[
{
"instType":"mc",
"channel":"trade",
"instId":"BTCUSDT"
}
]
}
Request parameters
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation, subscribe unsubscribe |
args | Array | Yes | List of subscribed channels |
> instType | String | Yes | Instrument type MC : Hybrid contract public channel, UMCBL : Professional contract private channel, DMCBL : Hybrid contract private channel |
> channel | String | Yes | Channel Name,trade |
> instId | String | Yes | Instrument ID |
Successful Response Example
{
"event":"subscribe",
"arg":[
{
"instType":"mc",
"channel":"trade",
"instId":"BTCUSDT"
}
]
}
Failure Response Example
{
"event":"error",
"code":30003,
"msg":"",
"instType":"mc",
"channel":"books5",
"instId":"BTC-USDT Symbol not exists"
}
Response parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Event,subscribe unsubscribe error |
arg | Object | No | Subscribed channel |
> instType | String | Yes | InstrumentType |
> channel | String | Yes | Channel Name |
> instId | String | Yes | Instrument ID |
code | String | No | Error Code |
msg | String | No | Error Message |
Push data parameters
Parameter | Type | Description |
---|---|---|
arg | Object | Successfully subscribed channel |
> instType | String | Instrument Type |
> channel | String | Channel Name |
> instId | String | Instrument ID |
data | Array | Subscribed data |
> ts | String | Filled time, Unix timestamp format in milliseconds |
> px | String | Trade price |
> sz | String | Trade size |
> side | String | Trade direction, buy , sell |
Private Channels
Account Channel
Retrieve account information. Data will be pushed when triggered by events such as placing/canceling order, and will also be pushed in regular interval according to subscription granularity.
Request Example
{
"op": "subscribe",
"args": [{
"instType": "UMCBL",
"channel": "account",
"instId": "default"
}]
}
Request Paramter
Paramter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation,subscribe unsubscribe |
args | Array | Yes | Subscribed channel |
> instType | String | Yes | Instrument Type UMCBL:USDT Private Channel DMCBL:Mix Private Channel |
> channel | String | Yes | Channel name account |
> instId | String | Yes | Coin, All is default |
Successful Response Example
{
"event":"subscribe",
"arg":{
"instType":"UMCBL",
"channel":"account",
"instId":"default"
}
}
Failure Response Example
{
"event": "error",
"code": 30003,
"msg": "instType:UMCBL,channel:ticker,instId:BTC-USDT Symbol not exists"
}
Response parameters
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Operation,subscribe unsubscribe error |
arg | Object | No | Subscribed channel |
> instType | String | Yes | Instrument Type |
> channel | String | Yes | Channel Name |
> instId | String | No | Coin |
code | String | No | Error code |
msg | String | No | Error messgae |
Push Data Parameter
Parameter | Type | Description |
---|---|---|
arg | Object | Subscribed channel |
> instType | String | Instrument Type |
> channel | String | Channel Name |
> instId | String | Coin |
data | Array | Subscribed Data |
marginCoin | String | Margin Coin |
locked | String | Lock balance |
available | String | Available balance |
crossMaxAvailable | String | Cross Liabilities of the currency |
fixedMaxAvailable | String | Isolated Liabilities of the currency |
maxTransferOut | String | Max transfer out |
equity | String | Equity of the currency |
usdtEquity | String | Equity of the currency USD |
First push: full push.
Incremental push: push transaction changes
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
{
"op": "subscribe",
"args": [{
"instType": "UMCBL",
"channel": "positions",
"instId": "default"
}]
}
Request Parameter
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation ,subscribe unsubscribe |
args | Array | Yes | Subscribed channel List |
> channel | String | Yes | Channel Name,positions |
> instType | String | Yes | Instrument Type UMCBL:USDT Private Channel DMCBL:Mix Private Channel |
> instId | String | No | Symbol Name |
Response Parameter
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Event ,subscribe unsubscribe errror |
arg | Object | No | Subscribed channel |
> channel | String | Yes | Channel Name |
> instType | String | Yes | Instrument Type |
> instId | String | No | Symbol Name |
code | String | No | Error Code |
msg | String | No | Error Message |
Push Data Parameter
Parameter | Type | Description |
---|---|---|
arg | Object | Subscribed channel |
> channel | String | Channel Name |
> instType | String | Instrument Type |
> instId | String | Instrument ID |
data | Array | Subscribed Data |
> posId | String | Position Id |
> instId | String | Symbol Name |
> instName | String | Symbol Name |
> marginCoin | String | Margin Coin |
> margin | String | Margin, can be added or reduced |
>marginMode | String | Margin mode, cross fixed |
> holdSide | String | Position sidelong short |
> holdMode | String | hold Mode single_hold , double_hold |
> total | String | Quantity of positions |
> available | String | Position that can be closed |
> locked | String | Frozen quantity |
>averageOpenPrice | String | Average open price |
> leverage | String | Leverage |
> achievedProfits | String | Realized profit and loss |
> upl | String | Unrealized profit and loss |
> uplRate | String | Unrealized profit and loss ratio |
> liqPx | String | Estimated liquidation price |
> keepMarginRate | String | Maintenance margin requirement Ratio |
> fixedMarginRate | String | Margin requirement Ratio fixed |
> fixedRiskRate | String | Risk rate. fixed |
> cTime | String | Creation time, Unix timestamp format in milliseconds |
> uTime | String | Latest time position was adjusted, Unix timestamp format in milliseconds |
When multiple orders are being executed at the same time, the changes of position data will be aggregated into one as much as possible.
Order Channel
Retrieve order information. Data will not be pushed when first subscribed. Data will only be pushed when triggered by events such as placing/canceling order.
Request Example
{
"op": "subscribe",
"args": [{
"channel": "orders",
"instType": "UMCBL",
"instId": "default"
}]
}
Request Parameter
Parameter | Type | Required | Description |
---|---|---|---|
op | String | Yes | Operation ,subscribe unsubscribe |
args | Array | Yes | Request Subscribed channel List |
> channel | String | Yes | Channel Name, orders |
> instType | String | Yes | Instrument Type UMCBL:USDT Private Channel DMCBL:Mix Private Channel |
> instId | String | No | Currently only supports default all trading pair orders |
Success Response Example
{
"event": "subscribe",
"arg": {
"channel": "orders",
"instType": "UMCBL",
"instId": "default"
}
}
Failure Response Example
{
"event": "error",
"code": 30003,
"msg": "instType:UMCBL,channel:orders,instId:BTC-USDT Symbol not exists"
}
Response Parameter
Parameter | Type | Required | Description |
---|---|---|---|
event | String | Yes | Event ,subscribe unsubscribe errror |
arg | Object | No | Subscribed channel |
> channel | String | Yes | Channel Name |
> instType | String | Yes | Instrument Type |
> instId | String | No | Instrument Id |
code | String | No | Error Code |
msg | String | No | Error Message |
Push Data Parameter
Parameter | Type | Description |
---|---|---|
arg | Object | Subscribed channel |
> channel | String | Channel Name |
> instType | String | Instrument Type |
> instId | String | Instrument Id |
data | Array | Subscribed Data |
> instId | String | Instrument Id |
> ordId | String | Order Id |
> clOrdId | String | Client-supplied order ID |
> px | String | Order price |
> sz | String | The original order quantity, in the unit of currency |
> notionalUsd | String | Estimated national value in USD of order |
> ordType | String | Order Type market limit |
> force | String | Order Force normal : normal order post_only : Post-only orderfok : Fill-or-kill orderioc : Immediate-or-cancel order |
> side | String | Order side, buy sell |
> posSide | String | Position side long or short |
> tdMode | String | Trade mode, cross : cross fixed : fixed |
> tgtCcy | String | Margin Coin |
> fillPx | String | Last filled price |
> tradeId | String | Last trade ID |
> fillSz | String | Last filled quantity |
> fillTime | String | Last filled time |
> fillFee | String | last filled fee |
> fillFeeCcy | String | last filled fee currency |
> execType | String | Order flow type, T: taker M: maker |
> accFillSz | String | Accumulated fill quantity |
> fillNotionalUsd | String | Filled notional value in USD of order |
> avgPx | String | Average filled price. If none is filled, it will return 0 . |
> status | String | Order Status new partial-fill full-fill cancelled |
> lever | String | Leverage |
>orderFee | Array | |
>> feeCcy | String | Fee currency |
>> fee | String | FeeNegative number represents the user transaction fee charged by the platform.Positive number represents rebate. |
> pnl | String | Profit and loss |
> uTime | String | Update time, Unix timestamp format in milliseconds |
> cTime | String | Creation time, Unix timestamp format in milliseconds |
RestAPI error codes
Error message | Error code | http status code |
---|---|---|
The request header "ACCESS_KEY" cannot be empty | 40001 | 400 |
The request header "ACCESS_SIGN" cannot be empty | 40002 | 400 |
The request header "ACCESS_TIMESTAMP" cannot be empty | 40003 | 400 |
Invalid ACCESS_TIMESTAMP | 40005 | 400 |
Invalid ACCESS_KEY | 40006 | 400 |
Invalid Content_Type, please use the "application/json" format | 40007 | 400 |
Request timestamp expired | 40008 | 400 |
Api verification failed | 40009 | 400 |
Request too frequent | 429 | 429 |
The request header "ACCESS_PASSPHRASE" cannot be empty | 40011 | 400 |
apikey/passphrase is incorrect | 40012 | 400 |
User is frozen | 40013 | 400 |
Incorrect permissions | 40014 | 400 |
System error | 40015 | 400 |
The user must bind a mobile phone or Google | 40016 | 400 |
Parameter verification failed | 40017 | 400 |
Illegal ip request | 40018 | 400 |
Take profit price needs to be > current price | 43013 | 400 |
Take profit price needs to be > current price | 43014 | 400 |
Stop loss price needs to be <current price | 43015 | 400 |
Stop loss price needs to be <current price | 43016 | 400 |
You are currently a trader and currently do not support liquidation through limit orders | 43001 | 400 |
Take profit and stop loss order does not exist | 43020 | 400 |
The take-profit and stop-loss order has been closed | 43021 | 400 |
Failed to trigger the default stop loss | 43022 | 429 |
Insufficient position, can not set take profit or stop loss | 43023 | 400 |
Take profit/stop loss in an existing order, please change it after canceling all | 43024 | 400 |
Limit order does not exist | 43025 | 400 |
The limit order has been closed | 43026 | 400 |
You are currently a trader, please close the position under the current order | 40728 | 400 |
WebSocket error codes
Error Message | Error Code |
---|---|
Channel does not exist | 30001 |
Illegal request | 30002 |
Invalid op | 30003 |
User needs to log in | 30004 |
Login failed | 30005 |
Invalid ACCESS_KEY | 30011 |
Invalid ACCESS_PASSPHRASE | 30012 |
Invalid ACCESS_TIMESTAMP | 30013 |
Request timestamp expired | 30014 |
Invalid signature | 30015 |