English
NAV Navbar
console

Changelog

March 24, 2021【Add v3 trader profit document】

1、trader profit summary

2、summary of historical distribution by settlement currency

3、statistics of historical distribution by day and settlement currency

4、historical profit sharing details

5、list of details to be shared

December 1, 2020 【Added WebsocketApi menu bar】

1 User's current plan to delegate channel

2 User history plan commissioned channel

3 Public-ticker channel

4 Public-k line channel

November 10, 2020 【New fields in account interface】

1 Query all contract account information

November 3, 2020【Modify k-line interface and position information】

1 Get k-line data

2 Get contract position information

October 26, 2020【New contract documentary interface】

1、Place an order to close a warehouse

2、Get the trader's current list of orders

3、Get a list of historical tapes

4、Place an order

10.10 October【Added multiple interface return values】

1、Get all ticker information and add "24-hour trading volume" field

2、Get the information of a single ticker and add the "24-hour volume" field

3、Get the position information of all contracts and add the "unrealized profit and loss" field

4、Get position information of a single contract and add "unrealized profit and loss" field

5、Get the platform's total holdings and add multiple fields

September 16, 2020【New return value of contract information port】

1、Contract Information

September 14, 2020 [New contract supports full position]

1、Modify user account mode

September 7, 2020 [New Interface]

1、Get contract historical funding rate

2、Get order history commission

3、Get the current order of the order

June 9, 2020 [Add v3 contract document]

October 26, 2020【New contract documentary interface】

1、Place an order to close a warehouse

2、Get the trader's current list of orders

3、Get a list of historical tapes

4、Place an order

INTRODUCTION

API INTRODUCTION

Welcome to Bitget API！

This is the official Bitget API document, this data is available and updates in real-time. Please follow us to get latest news.

You can switch to different API business in the top menu, and switch to different language by clicking the button in the top right.

The example of request and response is showing in the right-hand side.

Market Maker Program

Bitget welcome making /liquidity providing with good market making strategy and large trading volume. Please provide the information as below and email to:

  1. Please provide UID (This account is not allow to link to any rebate program account)；
  2. Screenshot of trading volume in other transaction platform (such as trading volume within 30 days)；
  3. A brief description of your market-making strategy。

Subscription

Bitget will publish API announcement in advance for any API change, please subscribe our announcements so that you can get latest update.

You can click Here to subscribe the announcements.Here subscribe。

contact us

You can contact us at bd.overseas@bitget.com if any issue or suggestions

Quick Start

Preparation

Before you use API, you need to login the website to create API Key with proper permissions.

You can manage your API Key. Here create API Key。

Every user account can create at most 10 API Key, each of them has two permissions:

Permission ： - Read permission: It is used to query the data, such as order query, trade query. - Trade permission: It is used to create order, cancel order and transfer, etc.

Please remember below information after creation:

SDK and Demo

SDK (Suggested)

Java | Python | Node

CCXT is our authorized SDK provider and you may access the Bitget API through CCXT. For more information, please visit: https://ccxt.trade.

Interface Type

This chapter mainly divides the following two aspects into interface types：

Public APIs

The public interface can be used to get configuration information and market data. Public requests can be invoked without authentication.

Private APIs __

The private interface can be used for order management and account management. Each private request must be signed using a canonical form of validation.

The private interface needs to be validated using your APIKey.

Restriction of visit

This chapter is mainly for access restrictions:

When access exceeds the frequency limit, a status of 429 is returned: requests are too frequent.

Rest API

If a valid APIKey is passed in, limit the speed with APIKey; If not, then take the public IP speed limit.

Speed limit rules: there are separate instructions for each interface. If there is no general interface, the speed limit is 10 times/second.

Special note: When placing bulk orders, if 4 coin pairs are placed and each coin pair is 10 orders, it will be counted as one request.

API Domain

You can use the Rest API access method to operate by yourself.

Domain REST API Suggestion
Domain1 https://capi.bitget.com International
Domain2 https://capi.bitgetapi.com CHINA

API Authentication

Making Requests

All REST request headers must contain the following keys:

The signature

ACCESS-SIGN The request header is correct timestamp + method.toUpperCase() + requestPath + "?" + queryString + body String (+ represents string concatenation) is used HMAC SHA256 Method encrypt and pass*BASE64* Produced by encoding the output.

Signature field description

When the queryString is empty, the signature format

timestamp + method.toUpperCase() + requestPath + body

Signature format when queryString is not null

timestamp + method.toUpperCase() + requestPath + "?" + queryString + body

For example

Get the depth information of the contract. Take cmt_btcusdt as an example:

Generate the string to be signed:

'1591089508404GET/api/swap/v1/market/depth?symbol=cmt_btcusdt&limit=20'

Order by contract, take cmt_btcusdt as an example:

Generate the string to be signed:

'1561022985382POST/api/swap/v3/order/placeOrder{"symbol":"cmt_btcusdt","size":"8","type":"1","match_price":"1","order_type":"1","client_oid":"bitget#123456"}'

The steps to generate the final signature

In step 1, the string to be signed is encrypted using the private key secretkey for HMAC Sha256

Signature = hmac_sha256(secretkey, Message)

Step 2: Base64 encoding for Signature

Signature = base64.encode(Signature)

Request interaction

All requests are based on Https protocol, and the content-type in the request header should be uniformly set to 'Application/JSON'.

Request interaction specification

successful

The HTTP status code 200 indicates a successful response and may contain content. If the response contains content, it is displayed in the corresponding return content.

Common error code

Standard specification

The time stamp

The access-Timestamp in the request signature is in 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 local server time and API server time, we recommend that you update the HTTP header by querying API server time.

Limited frequency rules

The system automatically limits requests if they are too frequent, and returns the 429 Too many Requests status code in the HTTP header.

The request format

There are currently only two format request methods: GET and POST

RestAPI

Contract Trading interface

Gets the server time

Rate Limit：20 requests per 2 seconds

HTTP Request Time to return to server

Response:

{
    "epoch":"1591099099.896",
    "iso":"2020-06-02T11:58:19.896Z",
    "timestamp":1591099099896
}

Response

Parameters Description
epoch Unix timestamp in seconds
iso ISO8601 standard time format
timestamp Unix timestamp in milliseconds

Contract Information

Rate Limit：20 requests per 2 seconds

HTTP Requests Get market data.

Response:

[
  {
    "symbol":"cmt_btcusdt",   //Contract name
    "coin":"USDT",     // Margin currency
    "contract_val":"0.0001",   //Contract value 
    "delivery":[   // Settlement time
         "07:00:00",
         "15:00:00",
         "23:00:00"
     ], 
    "forwardContractFlag":true,   // (true or false) , forward contract or not
    "priceEndStep":5,    //Prices' Last Digit in Cents
    "quote_currency":"USDT",   //Denominated currency
    "size_increment":"0",    //Quantity accuracy
    "tick_size":"1",    //Price accuracy  
    "underlying_index":"BTC"   //Contract currency
    "minLeverage":1 // minimum  leverage
    "maxLeverage":100 //maximum leverage
  }
]

Response

Parameters Description
symbol Contract name
coin Margin currency
contract_val Contract value
delivery Settlement time
forwardContractFlag (true or false) , forward contract or not
priceEndStep Prices' Last Digit in Cents
quote_currency Denominated currency
size_increment Quantity accuracy
tick_size Price accuracy
underlying_index Contract currency
minLeverage minimum leverage
maxLeverage maximum leverage

Get depth data

Rate Limit：20 requests per 2 seconds

HTTP Requests Get depth data

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name
'limit' Integer Yes Number of results per request

Response:

{
   "asks":[
         [
            "8858.0",   //price
            "19299",   //amount
              2.0     //Obsolete field
        ]   
     ],
   "bids":[
         [
            "7466.0",   //price
            "499",     //amount
             1.0       //Obsolete field
        ],
         [
            "4995.0",
            "12500",
              2.0
        ]
     ],
   "timestamp":"1591237821479" 
}

Response

Parameters Description
asks Sell side depth
bids Buy side depth
timestamp Timestamp

get all ticker information

Rate Limit：20 requests per 2 seconds

HTTP Requests get all ticker information

Response:


[
    {
        "symbol":"cmt_bchusdt",    //Contract name 
        "best_ask":"332.00",      //Best ask price 
        "best_bid":"203.00",      //Best bid price
        "high_24h":"394",        //Highest price in the past 24 hours 
        "last":"332",           //Last traded price 
        "low_24h":"332",        //Lowest price in the past 24 hours 
        "timestamp":"1591240033936",  //System timestamp
        "volume_24h":"0",    //Trading volume of past 24 hours
        "priceChangePercent": "-0.63"  //24-hour price change percentage
 }
]

Response

Parameters Description
symbol Contract name
best_ask Best ask price
best_bid best bid price
high_24h Highest price in the past 24 hours
last Last traded price
low_24h Lowest price in the past 24 hours
timestamp System timestamp
volume_24h Trading volume of past 24 hours
priceChangePercent 24-hour price change percentage

get one ticker information

Rate Limit：20 requests per 2 seconds

HTTP Requests get one ticker information

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name

Response:

{
    "symbol":"cmt_btcusdt",   //Contract name 
    "best_ask":"8858.0",     //Best ask price
    "best_bid":"7466.0",    //Best bid price   
    "high_24h":"8858",     //Highest price in the past 24 hours
    "last":"8858",        //Last traded price  
    "low_24h":"8858",    //Lowest price in the past 24 hours
    "timestamp":"1591252726275",  //System Timestamp
    "volume_24h":"0",   //Trading volume of past 24 hours
    "priceChangePercent": "-0.63"  //24-hour price change percentage
}

Response

Parameters Description
symbol Contract name
best_ask Best ask price
best_bid Best bid price
high_24h Highest price in the past 24 hours
last Last traded price
low_24h Lowest price in the past 24 hours
timestamp System Timestamp
volume_24h Trading volume of past 24 hours
priceChangePercent 24-hour price change percentage

Filled Orders

Rate Limit：20 requests per 2 seconds

HTTP Requests

Filled Orders

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name
'limit' String Yes Number of results per request

Response:

[
  {
      "symbol":"cmt_btcusdt",    //Contract name
      "price":"7844.00",        //Deal price
      "side":"buy",            //Transaction direction: sell, buy
      "size":"48",            //The number of transactions
      "timestamp":"1591111746879",    //Transaction timestamp
      "trade_id":"651735392382353615"   //Transaction id
 }
]

Response

Parameters Description
symbol Contract name
price Deal price
side Transaction direction: sell, buy
size The number of transactions
timestamp Transaction timestamp
trade_id Transaction id

Market Data

Rate Limit：20 requests per 2 seconds

HTTP Requests Retrieve the candlestick charts of the trading pairs.

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name
start String Yes Start time，in ISO 8601 format; Mark obsolete
end String Yes End time，in ISO 8601 format; Mark obsolete
startTime Long Yes Start time (time stamp)
endTime Long Yes End time (time stamp)
granularity String Yes Bar size in seconds, default 60, must be one of [60/180/300/900/1800/3600/7200/14400/21600/43200/86400/604800] or returns error

Response:

[
    "1556687460000",    //System timestamp
    "5315.5",          //Open price
    "5315.5",         //Higest price
    "5315.5",        //Lowest price
    "5315.5",       //Closing price
    "342",         //Transaction volume (converted by Zhang)
    "0.064340137494"   //Transaction volume (converted by currency)
]

Response

Parameters Description
timestamp System timestamp
open Open price
high Higest price
low Lowest price
close Closing price
volume Transaction volume (converted by Zhang)
currency_volume Transaction volume (converted by currency)

Indices

Rate Limit：20 requests per 2 seconds

HTTP Requests Retrieve indices of tokens. This is publicly accessible without account authentication.

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name

Response:

{
    "symbol":"cmt_btcusdt",   //Contract name
    "index":"9654.1",        //Index price
    "timestamp":"1591256590003"  //System Timestamp
}

Response

Parameters Description
symbol Contract name
index Index price
timestamp System Timestamp

Open Interests

Rate Limit：20 requests per 2 seconds

HTTP Requests Retrieve the total open interest of a contract on Bitget. This is publicly accessible without account authentication.

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name

Response:

{
    "symbol": "cmt_btcusdt",//Contract  name
    "amount": "4097696",//Total holdings
    "base_volume": "4097.696",//Total holdings,left coin vol
    "target_volume": "47124323.5392",//Total holdings,right coin vol
    "timestamp": "1603109860796",// System Timestamp
    "forwardContractFlag": true //Is it a forward contract
}

Response

Parameters Description
symbol Contract name
amount Total holdings
forwardContractFlag Is it a forward contract
timestamp System Timestamp
base_volume Total holdings,left coin vol
target_volume Total holdings,right coin vol

Current Price Limits

Rate Limit：20 requests per 2 seconds

HTTP Requests Retrieve the ceiling of the buy price and floor of sell price of the contract. This is publicly accessible without account authentication.

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name

Response:

{
     "symbol":"cmt_btcusdt",    //Contract name
     "forwardContractFlag":true,  //Is it a forward contract
     "highest":"14474.5",        //Ceiling of buying price
     "lowest":"4824.5",         //Floor of selling price
     "timestamp":"1591257126461"   //System Timestamp
 }

Response

Parameters Description
symbol Contract name
forwardContractFlag Is it a forward contract
highest Ceiling of buying price
lowest Floor of selling price
timestamp System Timestamp

Next Settlement Time

Rate Limit：20 requests per 2 seconds

HTTP Requests Get the time of next settlement.

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name

Response:

 {
     "symbol":"cmt_btcusdt",     //Contract name
     "forwardContractFlag":false,     //Is it a forward contract
     "funding_time":"1591282800000"  //time of current funding
 }

Response

Parameters Description
symbol Contract name
forwardContractFlag Is it a forward contract
funding_time time of current funding

Funding Rate History

Rate Limit：20 requests per 2 seconds

HTTP Requests Get Funding Rate History

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name
pageIndex String Yes Page number, empty default first page, starting from 1
pageSize String Yes Number of data per page

Response:

 {
     "symbol":"cmt_btcusdt",       //Contract name
     "funding_rate":"0.001",      //current funding rate
     "funding_time":"19238271212"    //Settlement time
 }

Response

Parameters Description
symbol Contract name
funding_rate current funding rate
funding_time Settlement time

Mark Price

Rate Limit：20 requests per 2 seconds

HTTP Requests Get the tag price. This is a public endpoint, no identity verification is needed.

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name

Response:

 {
     "symbol":"cmt_btcusdt",       //Contract name
     "mark_price":"8047.87",      //Specify the margin price
     "timestamp":"1591264230941"   //System Timestamp
 }

Response

Parameters Description
symbol Contract name
mark_price Specify the margin price
timestamp System Timestamp

Gets the openable number

Rate Limit：20 requests per 2 seconds

HTTP Requests Gets the openable number

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name
amount BigDecimal Yes The total amount of the opening
openPrice BigDecimal Yes Open price
leverage BigDecimal No The default leverage is 20 times

Response:

{
   "openCount":"199999"     //Number of openings
 }

Response

Parameters Description
openCount Number of openings

Contract account interface

all contract account information

Rate Limit：1 requests per 1 seconds

HTTP Requests Retrieve information from all tokens in the perpetual swap account

Response:

[ 
  {
   "symbol":"cmt_btcusdt",      //Contract name
   "equity":"0.00000000",      //Equity of the account
   "fixed_balance":"0.00000000",      //Obsolete field
   "total_avail_balance":"0.00000000",   //Available Balance
   "margin":"0",                        //Used margin
   "realized_pnl":"0",                 //Realized profits and losses
   "unrealized_pnl":"0",              //Unrealized profits and losses
   "longMarginRatio":"0",            //Margin rate for multiple positions
   "shortMarginRatio": "0",         //Margin rate for short positions
   "marginRatio": "0",             //Whole position margin rate
   "margin_frozen":"0",              //Freeze margin for opening positions
   "timestamp":"1658098718494",     //Creation time
   "margin_mode":"fixed",          //Margin Mode: crossed / fixed
   "forwardContractFlag":true     //Is it a forward contract
 }
]

Response

Parameters Description
symbol Contract name
equity Equity of the account
fixed_balance Available balance by warehouse
total_avail_balance Available Balance
margin Used margin
realized_pnl Realized profits and losses
unrealized_pnl Unrealized profits and losses
longMarginRatio Margin rate for multiple positions
shortMarginRatio Margin rate for short positions
marginRatio Whole position margin rate
margin_frozen Freeze margin for opening positions
timestamp Creation time
margin_mode Margin Mode: crossed / fixed
forwardContractFlag Is it a forward contract

Perpetual Swap Account of a Currency

Rate Limit：5 requests per second

HTTP Requests Retrieve the perpetual swap account information of a single trading pair.

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name

Response:

{
     "symbol":"cmt_btcusdt",      //Contract name
     "equity":"0.00000000",      //Equity of the account
     "fixed_balance":"0.00000000",      //Obsolete field
     "total_avail_balance":"0.00000000",   //Available Balance
     "margin":"0",                        //Used margin
     "realized_pnl":"0",                 //Realized profits and losses
     "unrealized_pnl":"0",              //Unrealized profits and losses
     "longMarginRatio":"0",            //Margin rate for multiple positions
     "shortMarginRatio": "0",         //Margin rate for short positions
     "marginRatio": "0",             //Whole position margin rate
     "margin_frozen":"0",              //Freeze margin for opening positions
     "timestamp":"1658098718494",     //Creation time
     "margin_mode":"fixed",          //Margin Mode: crossed / fixed
     "forwardContractFlag":true     //Is it a forward contract
 }

Response

Parameters Description
symbol Contract name
equity Equity of the account
fixed_balance Available balance by warehouse
total_avail_balance Available Balance
margin Used margin
realized_pnl Realized profits and losses
unrealized_pnl Unrealized profits and losses
longMarginRatio Margin rate for multiple positions
shortMarginRatio Margin rate for short positions
marginRatio Whole position margin rate
margin_frozen Freeze margin for opening positions
timestamp Creation time
margin_mode Margin Mode: crossed / fixed
forwardContractFlag Is it a forward contract

Get Swap Leverage

Rate Limit：5 requests per second

HTTP Requests Retrieve the leverage ratio and margin mode of a perpetual swap.

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name

Response:

 {
   "symbol":"cmt_btcusdt",        //Contract name
   "long_leverage":"100",        //Leverage level for long positions
   "margin_mode":"fixed",       //Margin Mode: crossed / fixed
   "short_leverage":"2",       //Leverage level for short positions
   "forwardContractFlag":true     //Is it a forward contract
 }

Response

Parameters Description
symbol Contract name
long_leverage Leverage level for long positions
margin_mode Margin Mode: crossed / fixed
short_leverage Leverage level for short positions
forwardContractFlag Is it a forward contract

Set Swap Leverage

Rate Limit：5 requests per second

HTTP Requests 调整杠杆

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name
leverage Integer Yes New leverage level from 1-100
side Integer Yes Position direction (1-long position, 2-short position) Mark obsolete
holdSide Integer Yes Position direction (1-long position, 2-short position) crossed mode the holdSide field does not need to be passed

Response:

{
   "symbol":"cmt_btcusdt",           //Contract name
   "long_leverage":"100",           //Leverage level for long positions
   "margin_mode":"fixed",          //Margin mode: crossed / fixed
   "short_leverage":"2",          //Leverage level for short positions
   "forwardContractFlag":true    //Is it a forward contract
 }

Response

Parameters Description
symbol Contract name
long_leverage Leverage level for long positions
margin_mode Margin mode: crossed / fixed
short_leverage Leverage level for short positions
forwardContractFlag Is it a forward contract

Adjust margin

Rate Limit：20 requests per 2 seconds

HTTP Requests adjust margin

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name
amount String Yes adjust amount
positionType Integer Yes Direction 0 Long 1 Short
type Integer Yes Type 1 Increase 2 Reduce

Response:

 {
    "result":true,      //result
    "orderNo":"527252921197264814"   //Order ID
 }

Response

Parameters Description
result Result
orderNo Order ID

Auto Margin Replenishment (AMR)

Rate Limit：5 requests per second

HTTP Requests Auto Margin Replenishment (AMR)

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name
side Integer Yes Position direction 1 Long 2 Short Mark obsolete
holdSide Integer Yes Position direction 1 Long 2 Short
append_type Integer Yes Adjust margin type 0 Manually 1 Automatic

Response:

 {
     "result":true,       //Setting result
     "append_type":1     //Current setting: 0 Manually 1 Automatic
 }

Response

Parameters Description
result Setting result
append_type Current setting: 0 Manually 1 Automatic

Get all contract position information

Rate Limit：5 requests per second

HTTP Requests get all contract position information

Response:

 [
 {
    "margin_mode":"fixed",       //Margin mode: crossed / fixed
    "holding":[
           {
              "symbol":"cmt_btcusdt",      //Contract name
              "liquidation_price":"0.00",    //Estimated liquidation price
              "position":"0",               //Position Margi(the margin for holding current positions)
              "avail_position":"0",        //Available position
              "avg_cost":"0.00",          //Transaction average price
              "leverage":"2",            //Leverage
              "realized_pnl":"0.00000000",      //Realized Profit and loss
              "keepMarginRate":"0.005",        //Maintenance margin rate
              "side":"1",                      // Position Direction Long or short     Mark obsolete
              "holdSide":"1",                      //Position Direction Long or short
              "timestamp":"1557571623963",    //System timestamp
              "margin":"0.0000000000000000"  //Used margin
              "unrealized_pnl":"0.00000000" //Unrealized profit and loss
       }
     ]
 }
]

Response

Parameters Description
symbol Contract name
margin_mode Margin mode: crossed / fixed
liquidation_price Estimated liquidation price
position Position Margi(the margin for holding current positions)
avail_position Available position
avg_cost Transaction average price
leverage Leverage
realized_pnl Realized Profit and loss
keepMarginRate Maintenance margin rate
side Direction Long or short
holdSide Position Direction Long or short
timestamp System timestamp
margin Used margin
unrealized_pnl Unrealized profit and loss

Get one of the Margin mode information

Rate Limit：10 requests per second

HTTP Requests Retrieve information on your positions of a single contract.

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name

Response:

{
    "margin_mode":"fixed",       //Margin mode: crossed / fixed
    "holding":[
           {
              "symbol":"cmt_btcusdt",       //Contract name
              "liquidation_price":"0.00",  //Estimated liquidation price
              "position":"0",             //Position Margi(the margin for holding current positions)
              "avail_position":"0",      //Available position
              "avg_cost":"0.00",        //Transaction average price
              "leverage":"2",          //Leverage
              "realized_pnl":"0.00000000",    //Realized Profit and loss
              "keepMarginRate":"0.005",      //Maintenance margin rate
              "side":"1",                    //Position Direction Long or short     Mark obsolete
              "holdSide":"1",                    //Position Direction Long or short
              "timestamp":"1557571623963",  // System timestamp
              "margin":"0.0000000000000000"   //Used margin
              "unrealized_pnl":"0.00000000" //Unrealized profit and loss
       }
     ]
 }

Response

Parameters Description
symbol Contract name
margin_mode Margin mode: crossed / fixed
liquidation_price Estimated liquidation price
position Position Margi(the margin for holding current positions)
avail_position Available position
avg_cost Transaction average price
leverage Leverage
realized_pnl Realized Profit and loss
keepMarginRate Maintenance margin rate
side Direction: Long or short
timestamp System timestamp
margin Used margin
unrealized_pnl Unrealized profit and loss

Modify the user's account mode

Rate Limit：20 requests per second

HTTP Requests Modify the user's account mode

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name
holdModel Integer Yes account mode (1 position by position 2 full position)

Response:

 {
    "symbol":"cmt_btcusdt",     //Contract name
    "resultHoldMode":1,        //Return to the account mode 1 position by position 2 full position
    "switchSuccess":true      //Whether the modification is successful true success false failure
}

Response

Parameters Description
symbol Contract name
resultHoldMode Return to the account mode 1 position by position 2 full position
switchSuccess Whether the modification is successful true success false failure

Contract trading endpoints

Place order

Rate Limit：10 requests per second

HTTP Requests Place order

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name
client_oid String Yes Custom order number (not more than 40 characters, and cannot be special characters, such as Martian characters, etc.), can not be repeated in the pending order. If vacant, the system will automatically assign value
size String Yes Quantity to buy or sell (value not equal to 0 or negative)
type String Yes 1 Open long 2Open short 3 Close long 4 Close short
order_type String Yes 0: Normal order (Unfilled and 0 imply normal limit order) 1: Post only 2: Fill or Kill 3: Immediate Or Cancel
match_price String Yes 0 Limit price 1 market price
price String No Price of each contract
presetTakeProfitPrice BigDecimal No Preset take profit price
presetStopLossPrice BigDecimal No Preset stop price

Response:

{
    "client_oid":"bitget#123456",      //Client  ID 
    "order_id":"513466539039522813"   //Order ID 
}

Response

Parameters Description
client_oid Client ID 
order_id Order ID 

Batch order

Rate Limit：10 requests per second

HTTP Requests batch order

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name
orderDataList List Yes Object attributes, e.g (price=5,size=2,type=1,match_price=1,order_type=1,client_oid="abc"),The fields refer to the [Contract trading] endpoints, and can only process up to 20 orders in batch

Response:

{
    "result":true,  
    "order_info":[
        {
            "result":true,         //Result of an Order
            "client_oid":"dxdanzi",     //Client  ID
            "order_id":"513468410013679613"   //Order ID
        },
        {
            "result":true,
            "client_oid":"dxdanzi",
            "order_id":"513468410001096713"
        }
    ]
}

Response

Parameters Description
result Result of an Order
client_oid Client ID
order_id Order ID

Cancel order

Rate Limit：10 requests per second

HTTP Requests Cancel order

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name
orderId String Yes order id

Response:

{
   "symbol":"cmt_btcusdt",          //Contract name
   "order_id":"513468410013679613",   //Order ID
   "client_oid":"bitget#123456",     //Client ID
   "result":true                    //Cancellation status
}

Response

Parameters Description
symbol Contract name
order_id Order ID
client_oid Client ID
result Cancellation status

Cancel orders in batch

Rate Limit：10 requests per seconds

HTTP Requests request to cancel order in batch

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name
ids List Yes Order ID combination

Response:

{
   "symbol":"cmt_btcusdt",      //Contract name
   "result":true,              //processing result
   "order_ids":[
          "258414711",   //Successful id
          "478585558"
    ],
   "fail_infos":[
          {
        "order_id":"258414711",   //Failed id
        "err_code":"401",        //Error code
        "err_msg":""            //Error message
     }
  ]
}

Response

Parameters Description
symbol Contract name
result processing result
order_ids Orders
order_id Order ID
err_code Error code
err_msg Error message

Get the Order Details of an Order

Rate Limit：10 requests per second

HTTP Requests get the order details of an order

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name
orderId String Yes Order ID

Response:

{
     "symbol":"cmt_btcusdt",    //Contract name
     "size":"12",              //The amount in this order
     "timestamp":"15582271175271",     //Obsolete field
     "client_oid":"cmdtde",           //Client ID
     "createTime":"1698475585258",   //Creation time
     "filled_qty":"0",              //The amount which has been filled
     "fee":"0",                    //Transaction fee
     "order_id":"513468410013679613",    //Order ID
     "price":"12",                      //The limit price of limit order 
     "price_avg":"0",                  //Average filled price
     "status":"-1",                   //Order status
     "type":"1",                     //Commission type
     "order_type":"0",              //Order type
     "totalProfits":"253"          //Total profit and loss          
}

Response

Parameters Description
symbol Contract name
size The amount in this order
timestamp System time
client_oid Client ID
createTime Creation time
filled_qty The amount which has been filled
fee Transaction fee
order_id Order ID
price The limit price of limit order
price_avg Average filled price
status Order status -1 Cancelled successful 0 submitted 1partial-filled 2filled
type Commission type, 1,Open long 2 Open short 3 Close long 4 Close short 5 Buy limit 6Sell limit 7.Long close agreement 8. Short close agreement 9. Forced liquidity long 10 Forced liquidity short
order_type Order Type 0. Normal limit order 1. Only be Maker (Post only)"2 Fill or Kill (FOK) 3. Immediate or Cancel (IOC)
totalProfits Total profit and loss

Get order history commission

Rate Limit：10 requests per second

HTTP Requests Get order history commission

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name
pageIndex String Yes Page number, empty default first page, starting from 1
pageSize String Yes Number of data per page
createDate Integer Yes Number of days (the number of days must be less than or equal to 90, cannot be a negative number)

Response:

[
   {
          "symbol":"cmt_btcusdt",    //Contract name
          "size":"12",              //The amount in this order
          "client_oid":"cmdtde",           //Client ID
          "createTime":"1698475585258",   //Creation time
          "filled_qty":"0",              //The amount which has been filled
          "fee":"0",                    //Transaction fee
          "order_id":"513468410013679613",    //Order ID
          "price":"12",                      //The limit price of limit order 
          "price_avg":"0",                  //Average filled price
          "status":"-1",                   //Order status
          "type":"1",                     //Commission type
          "order_type":"0",              //Order type
          "totalProfits":"253"          //Total profit and loss    
 }
]

Response

Parameters Description
symbol Contract name
size The amount in this order
client_oid Client ID
createTime Creation time
filled_qty The amount which has been filled
fee Transaction fee
order_id Order ID
price The limit price of limit order
price_avg Average filled price
status Order status -1 Cancelled successful 0 submitted 1partial-filled 2filled
type Commission type, 1,Open long 2 Open short 3 Close long 4 Close short 5 Buy limit 6Sell limit 7.Long close agreement 8. Short close agreement 9. Forced liquidity long 10 Forced liquidity short
order_type Order Type 0. Normal limit order 1. Only be Maker (Post only)"2 Fill or Kill (FOK) 3. Immediate or Cancel (IOC)
totalProfits Total profit and loss

Get the current order of the order

Rate Limit：10 requests per second

HTTP Requests Get the current order of the order

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name

Response:

[
   {
          "symbol":"cmt_btcusdt",    //Contract name
          "size":"12",              //The amount in this order
          "client_oid":"cmdtde",           //Client ID
          "createTime":"1698475585258",   //Creation time
          "filled_qty":"0",              //The amount which has been filled
          "fee":"0",                    //Transaction fee
          "order_id":"513468410013679613",    //Order ID
          "price":"12",                      //The limit price of limit order 
          "price_avg":"0",                  //Average filled price
          "status":"-1",                   //Order status
          "type":"1",                     //Commission type
          "order_type":"0",              //Order type
          "totalProfits":"253"          //Total profit and loss    
 }
]

Response

Parameters Description
symbol Contract name
size The amount in this order
client_oid Client ID
createTime Creation time
filled_qty The amount which has been filled
fee Transaction fee
order_id Order ID
price The limit price of limit order
price_avg Average filled price
status Order status -1 Cancelled successful 0 submitted 1partial-filled 2filled
type Commission type, 1,Open long 2 Open short 3 Close long 4 Close short 5 Buy limit 6Sell limit 7.Long close agreement 8. Short close agreement 9. Forced liquidity long 10 Forced liquidity short
order_type Order Type 0. Normal limit order 1. Only be Maker (Post only)"2 Fill or Kill (FOK) 3. Immediate or Cancel (IOC)
totalProfits Total profit and loss

Get Transaction Details

Rate Limit：10 requests per second

HTTP Requests get transaction details

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name
orderId String Yes Order ID

Response:

[
  {
      "symbol":"cmt_btcusdt",    //Contract name
      "trade_id":"6667390",     //trade Id
      "order_id":"525946425993854915",   //order id
      "price":"9839.00",      //deal price
      "order_qty":"3466",    //Quantity
      "fee":"-0.0000528407360000",    //transaction fee
      "timestamp":"1561121514442",   //Creation time
      "exec_type":"M",              //Liquidity direction   Taker or maker (T or M)
      "side":"3",                 //Commission type    Mark obsolete
      "delegateType":"3"          //Commission type
}
]

Response

Parameters Description
symbol Contract name
trade_id trade Id
order_id order id
price deal price
order_qty Quantity
fee transaction fee
timestamp Creation time
exec_type Liquidity direction Taker or maker (T or M)
side Side of the order 1,Open long 2 Open short 3 Close long 4 Close short 5 Buy limit 6Sell limit 7.Long close agreement 8. Short close agreement 9. Forced liquidity long 10 Forced liquidity short

Place order with Stop limit

Rate Limit：10 requests per second

HTTP Requests place order with Stop limit

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name
client_oid String Yes Custom order number (not more than 40 characters, and cannot be special characters, such as Martian characters, etc.), can not be repeated in the pending order. If vacant, the system will automatically assign value
size String Yes Quantity to buy or sell (value not equal to 0 or negative)
type String Yes Type 1 Open position 2 Close position
side String Yes Position Direction 1 Long 2 Short Mark obsolete
holdSide String Yes Position Direction 1 Long 2 Short
match_type String Yes Order Type 0 Limit 1 Market
execute_price String Yes Stop price (execute price)
trigger_price String Yes Limit price (trigger price)

Response:

{
      "client_oid":"bitget#123456",       //Client ID
      "order_id":"589579827556646928"    //plan Order ID 
}

Response

Parameters Description
client_oid Client ID
order_id plan Order ID

Close position with Stop limit

Rate Limit：10 requests per second

HTTP Requests close position with Stop limit

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name
orderId String Yes Order ID

Response:

 {
     "order_id":"5895798275566469458",      //Order ID
     "client_oid":"bitget#123456",         //Client ID
     "result":false,                      //Status of cancellation
     "err_code":"403",                   //code of cancellation 
     "err_msg":"order not exist"        //reason of cancellation
}

Response

Parameters Description
order_id Order ID
client_oid Client ID
result Status of cancellation
err_code code of cancellation
err_msg reason of cancellation

Check Stop limit status

Rate Limit：10 requests per second

HTTP Requests check stop limit status

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name
side String Yes Commission type 1 Open long 2 Open short 3 Close long 4 Close short Mark obsolete
delegateType String Yes Commission type 1 Open long 2 Open short 3 Close long 4 Close short
pageIndex String Yes Current page (1-200)
pageSize String Yes Number per page(1-100)
startTime String No Query start time
endTime String No Query stop time

Response:

{
      "list":[
              {
                 "symbol":"cmt_btcusdt",     //Contract name
                 "execute_count":"0",       //amount of Stop
                 "delegate_count":"1222222",     //amount of Limit
                 "create_time":1576294708136,   //Created time
                 "update_time":1576294708136,  //Updated time
                 "direction":1,               //Direction
                 "direction_desc":"开多",     //Description of direction
                 "trigger_price":"22222210.0",       //Stop price 
                 "execute_price":"7490.0",          //limit price (execute price) 
                 "order_id":"589588227514433528",  //Order ID
                 "order_type":0,                  //Order Type
                 "status":1,                     //status
                 "status_desc":"status",        //Description of status
                 "create_trade_price":"7490"   //Executed price of stop limit
           }
         ],
    "nextPage":false   //Next page 
}

Response

Parameters Description
symbol Contract name
nextPage Next page
execute_count amount of Stop
delegate_count amount of Limit
create_time Created time
update_time Updated time
direction Direction 1.Open long 2.Open short 3 Close long 4 Close short
direction_desc Description of direction 1.Open long 2.Open short 3 Close long 4 Close short
trigger_price Stop price
execute_price limit price (execute price)
order_id Order ID
order_type Order Type 0 Limit 1 Market
status status 1: waiting to order 2: order placing 3: failed status 4 under cancellation
status_desc Description of status 1: waiting to order 2: order placing 3: failed status 4 under cancellation
create_trade_price Executed price of stop limit

Get the history of Stop limit

Rate Limit：10 requests per second

HTTP Requests Get the history of Stop limit

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name
side String Yes Commission type 1 Open long 2 Open short 3 Close long 4 Close short Mark obsolete
delegateType String Yes Commission type 1 Open long 2 Open short 3 Close long 4 Close short
pageIndex String Yes current page(1-200)
pageSize String Yes Number per page(1-100)
startTime String No Query start time
endTime String No Query end time

Response:

{
        "list":[
                    {
                       "symbol":"cmt_btcusdt",     //Contract name
                       "execute_count":"0",       //amount of Stop
                       "delegate_count":"1222222",     //amount of Limit
                       "create_time":1576294708136,   //Created time
                       "update_time":1576294708136,  //Updated time
                       "direction":1,               //Direction
                       "direction_desc":"开多",     //Description of direction
                       "trigger_price":"22222210.0",       //Stop price 
                       "execute_price":"7490.0",          //limit price (execute price) 
                       "order_id":"589588227514433528",  //Order ID
                       "order_type":0,                  //Order Type
                       "status":1,                     //status
                       "status_desc":"status",        //Description of status
                       "create_trade_price":"7490"   //Executed price of stop limit
                 }
               ],
          "nextPage":false   //Next page 
}

Response

Parameters Description
symbol Contract name
nextPage Next page
execute_count amount of limit
delegate_count amount of stop
create_time Creation time
update_time Update time
direction Direction 1.Open long 2.Open short 3 Close long 4 Close short
direction_desc Description of direction 1.Open long 2.Open short 3 Close long 4 Close short
trigger_price trigger price
execute_price execute price
order_id Order ID
order_type Order Type 0 Limit 1 Market
status status 1: waiting to order 2: order placing 3: failed status 4 under cancellation
status_desc description of 1: waiting to order 2: order placing 3: failed status 4 under cancellation
create_trade_price Executed price of stop limit

Copy trading interface

Get the current list

Rate Limit：20 requests per second

HTTP Requests

Get the current list

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name
pageIndex String Yes Page number, empty default first page, starting from 1
pageSize String Yes Number per page (1-100 integer)

Response:

[
  {

     "symbol":"cmt_btcusdt", //Contract name
     "orderNo":"699848017573842632",  //order number
     "holdSide":1, //Position direction  1 Long position 2 Short position
     "openLeverage":20,   //Opening leverage
     "averageOpenPrice":11451.50000,  //Average opening price
     "openTime":1602582690614,  //Opening time
     "openDealCount":"10",    //Number of positions (number of transactions opened)
     "stopProfitPrice":"123.14",    //Take Profit Price
     "stopLossPrice":"20.52"     //Stop price
 }
]

Close a position with a single order

Rate Limit：1 requests per second

HTTP Requests

Close a position with a single order

Request Parameter

Parameters Type Required Description
symbol String Yes Contract name
trackingNo Long Yes Tracking order number get '/api/swap/v3/trace/currentTrack' interface return result orderNo

Response:

{
     "trackingNo":6258224712558517, //Document number
     "result":true                 //Copy result
}

Get a list of historical tapes

Rate Limit：20 requests per second

HTTP Requests Get a list of historical tapes

Request Parameter

Parameters Type Required Description
pageIndex String Yes Page number, empty default first page, starting from 1
pageSize String Yes Number per page (1-100 integer)
createDate Integer Yes The number of days to query forward from the current time (the number of days must be less than or equal to 90, cannot be a negative number)

Response:

{
     "symbol":"cmt_btcusdt", //Contract name
     "orderNo": "682799071840175632",  //order number
     "holdSide":1,             //Position direction  1 Long position 0 Short position
     "openLevel": 20,        //Opening leverage
     "openAvgPrice" :"11366.50",     //Average opening price
     "openTime": 1598517905197,    //Opening time
     "closeDealCount": "10",           //Number of closed trades
     "closeTime":1599135145368,          //Position closing trigger time
     "closeAvgPrice": "11272.00",        //Average closing price
     "stopType": "1",                   //0 common 1 stop profit 2 stop loss (closed position type)
     "achievedProfits": "-0.07650000", //Realized profit and loss
     "openFee": "-0.00680910",  // Cumulative fees for opening positions
     "closeFee": "0.000000"    //Cumulative handling fee for liquidation
}

trader profit summary

Rate Limit：20 requests per second

HTTP Requests trader profit summary

Response:

{
     "yesterdaySplitProfit":"0", //yesterday profit
     "sumProfit": "0",  //total profit
     "waitProfit":"0"  //wait profit
}

summary of historical distribution by settlement currency

Rate Limit：20 requests per second

HTTP Requests summary of historical distribution by settlement currency

Response:

{
     "settleTokenId":"usdt", //settle token
     "profit": "0"  //profit
}

statistics of historical distribution by day and settlement currency

Rate Limit：20 requests per second

HTTP Requests statistics of historical distribution by day and settlement currency

Request Parameter

Parameters Type Required Description
pageIndex String Yes Page number, empty default first page, starting from 1
pageSize String Yes Number per page (1-100 integer)

Response:

{
     "settleTokenId":"usdt", //settle token
     "profit": "0",  //profit
     "date": "1616487216598" //date
}

historical profit sharing details

Rate Limit：20 requests per second

HTTP Requests historical profit sharing details

Request Parameter

Parameters Type Required Description
pageIndex String Yes Page number, empty default first page, starting from 1
pageSize String Yes Number per page (1-100 integer)
settleTokenId String Yes settle token("USDT", "ETH", "BTC", "BCH")
date Long Yes statistical interface of historical distribution by day and settlement currency response date(1616487216598)

Response:

{
     "settleTokenId":"usdt", //settle token
     "profit": "0",  //profit
     "nickName": "" //nickName
}

list of details to be shared

Rate Limit：20 requests per second

HTTP Requests list of details to be shared

Request Parameter

Parameters Type Required Description
pageIndex String Yes Page number, empty default first page, starting from 1
pageSize String Yes Number per page (1-100 integer)

Response:

{
     "settleTokenId":"usdt", //settle token
     "profit": "0",  //profit
     "nickName": "" //nickName
}

WebSocketAPI

Perpetual contract

The following is the perpetual contract v3 WebSocketAPI

Brief Introduction

WebSocket is a HTML5 new Protocol. It implements full-duplex communication between the client and the server, allowing data to be quickly propagated in both directions. A simple handshake can establish a connection between the client and the server, and the server can actively push information to the client according to business rules. The advantages are as follows:

Strongly recommend developer to use WebSocket API to obtain market info and bid/ask market depth info etc.

Domain name WebSocket API Recommended to use
Domain name 1 wss://csocketapi.bitget.com/ws/v1 International
Domain name 2 wss://csocketapi.bitgetapi.com/ws/v1 China area

Connection instruction

System will auto-disconnect while subscription has been done within 30sec or no ping command sent by user after 30sec after ws is connected

Order format

Request format

{"op": "value", "args": ["value1","value2"]}

op value is: 1--subscribe ； 2-- unsubscribe；3--login

args: value is channel name, can define 1 or more channel

Successful response format

{"event": "value","channel":"value"}

{"table":"channel","data":"[{"value1","value2"}]"}

Failed response format

{"event":"error","message":"error_message","errorCode":""}

Trading pair format

Reverse contract (example)

btcusd、ethusd、ltcusd、xrpusd、bchusd、eosusd

Forward contract (example)

cmt_bnbusdt、cmt_btcusdt

Simulation contract (example)

sbtcusd（Reverse contract simulation）、cmt_btcsusdt（Forward contract simulation）

Subscribe

User has the opinion to subscribe 1 or more channels, total length of multiple channel can not exceeds 4096 bytes.

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

Note: op value is subscribe

args array content is channel name

channelname is consist of business/channel

Perpetual push business is swap, channel is the particular name under such business, if the channel name can not be differentiate by alphabet, then they can use " _ " to connect.

Example:

"swap/ticker:btcusd" or "swap/price_range:btcusd"

filter is filterable data, refer to channel for detailed instruction

Example:

send: {"op": "subscribe", "args": ["swap/ticker:btcusd", "swap/candle60s:btcusd"]}

response:

{"event": subscribe,"channel":"swap/ticker:btcusd"} {"event": subscribe,"channel":"swap/candle60s:btcusd"}

{"table":"swap/ticker","data":[{"high_24h":"3369","instrument_id":"btcusd","last":"3299", "low_24h":"3112","timestamp":"2018-12-09T08:12:04.659Z","volume_24h":"8389225"}]}

{"table":"swap/candle60s","data":[{"instrument_id":"btcusd","candle":["2018-12-09T08:12:00.000Z", "3299.8","3299.8","3299","3299","82","2.4854"]}]}

Cancel subscription

Can cancel 1 or more channels

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

Example:

Request:

{"op": "unsubscribe", "args": ["swap/ticker:btcusd", "swap/candle60s:btcusd"]}

return:

{"event":"unsubscribe","channel":"swap/ticker:btcusd"} {"event":"unsubscribe","channel":"swap/candle60s:btcusd"}

Login

For the description of the signature method, refer to the verification section in the API overview

Login subscription format:

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

Response：

{"event":"login","success":true}

Example:

{"op":"login","args":["bg_573af5eca856acd91c230da294ce2105","123456","1538054050", "8RCOqCJAhhEh4PWcZB/96QojLDqMAg4qNynIixFzS3E="]}

api_key: APIKey applied for for the user

passphrase: It is filled in when applying for v3 api, if there is no password, then pass in an empty string ("")

timestamp: is the timestamp is the Unix Epoch time, the unit is seconds, the timestamp will expire after 30 seconds

sign: is the signature string, the signature rules are as follows：

The Message is (string to be signed): timestamp+method+requestPath

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

The method always defaults to'GET'

requestPath always defaults to'/user/verify'

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

Connection limit

Connection limit：1 time/s

Subscription limit：240 times/hr

If no data returned after connecting to ws, connection will auto-disconnect after 30s, suggest user to follow below instruction:

Channel description

Channels are not required to log in: Market channel, Candlestick chart channel, Trading data channel, Fund fees channel, Price limit range channel, Market depth data channel, Price tag channel.

Channels are required to log in：User account channel, User trade channel, User position channel

Name of Channels are not required to log in：

swap/ticker // ticker data channel

swap/candle60s // 1min Candlestick chart data channel

swap/candle300s // 5min Candlestick chart data channel

swap/candle900s // 15min Candlestick chart data channel

swap/candle1800s // 30min Candlestick chart data channel

swap/candle3600s // 1h Candlestick chart data channel

swap/candle14400s // 4h Candlestick chart data channel

swap/candle43200s // 12h Candlestick chart data channel

swap/candle86400s // 1day Candlestick chart data channel

swap/candle604800s // 1week Candlestick chart data channel

swap/trade // Trade info channel

swap/funding_rate// Fund fees channel

swap/price_range// Price limit range channel

swap/depth // Market depth data channel,first 200 range, subsequent one is increment

swap/depth5 // Market depth data channel, return to first 5 range everytime

swap/mark_price// Price tag channel

Channels are required for login：

swap/account // User account info channel

swap/position // User position info channel

swap/order // User trade data channel

User position channel

Require user to login to obtain user position info

Send example

{"op": "subscribe", "args": ["swap/position:btcusd"]}

swap / position is channel name, btcusd is instrument_id

Response:

{
   "table": "swap/position",
   "data": [{
   "holding": [{
   "avail_position": "1",
   "avg_cost": "0.2985",
   "leverage": "5",
   "liquidation_price": "0.0136",
   "margin": "6.8129",
   "position": "1",
   "realized_pnl": "-0.0239",
   "unrealized_pnl": "0.0001",
   "side": "long",
   "timestamp": "1559544244016"
   }, {
   "avail_position": "1",
   "avg_cost": "0.2935",
   "leverage": "5",
   "liquidation_price": "0.0136",
   "margin": "6.8129",
   "position": "1",
   "realized_pnl": "-0.0239",
   "unrealized_pnl": "0.0001",
   "side": "short",
   "timestamp": "1559544244016"
   }],
   "instrument_id": "xrpusd",
   "margin_mode": "crossed"
   }]
}

Request Parameter

Parameter name Parameter type Description
iquidation_price String Estimated stopped-out price
position String Position cont
avail_position String Close position cont
avg_cost String Open position avg price
instrument_id String Contract name
leverage String Leveraging
realized_pnl String Realized P/L
unrealized_pnl String Unrealized P/L
side String Direction (long/short)
timestamp String Creation time
margin String Margin
margin_mode String fixed: Isolated margin crossed: Cross margin

User account channel

Need user to log in to obtain account info

Send example

{"op": "subscribe", "args": ["swap/account:btcusd"]}

swap/account is channel name, btcusd is instrument id

Response:

{
   "table": "swap/account",
   "data": [{
   "equity": "21.9334",
   "fixed_balance": "0.0000",
   "instrument_id": "xrpusd",
   "margin": "6.8129",
   "margin_frozen": "6.8143",
   "margin_mode": "crossed",
   "realized_pnl": "0.0000",
   "timestamp": "1559544244016",
   "total_avail_balance": "22.0043",
   "unrealized_pnl": "-0.0710"
   }]
}

Request Parameter

Parameter name Parameter type Description
equity String Account privilege
instrument_id String Contract name
margin String Used margin
margin_frozen String Freeze margin for open a position
realized_pnl String Realized P/L
timestamp String Creation time
total_avail_balance String Account balance
unrealized_pnl String Unrealized P/L
fixed_balance String Isolated margin account balance
margin_mode String Account type: Isolated margin fixed Cross margin crossed

User trade channel

Need user to log in to obtain user trade data

Send example:

{"op": "subscribe", "args": ["swap/order:btcusd"]}

swap/account is channel name, btcusd is instrument id

Response:

{
   "table": "swap/order",
   "data": [{
   "last_fill_time": "1559544244016",
   "filled_qty": "0",
   "fee": "0.000000",
   "client_oid": "",
   "last_fill_qty": "0",
   "price_avg": "0.0000",
   "type": "2",
   "instrument_id": "xrpusd",
   "last_fill_px": "0",
   "size": "1",
   "price": "0.2935",
   "error_code": "0",
   "contract_val": "10",
   "state": "0",
   "order_id": "6c-a-625f6f638-0",
   "order_type": "0",
   "status": "0",
   "timestamp": "1559544244016"
   }]
}

Request Parameter

Parameter name Parameter type Description
instrument_id String Contract name, e.g. btcusd
size String Order cont
timestamp String Creation time
filled_qty String Deal cont
fee String Fees
order_id String Order ID
client_oid String Order ID set by user
price String Order price
price_avg String Deal avg price
type String 1:Open long position 2:Open short position 3:Close long position 4.Close short position
contract_val String Contract value
order_type String 0:Plain order 1:Only Maker(Post only) 2: Fill or Kill (FOK) 3:Deal immediately and cancel the rests (IOC)
last_fill_time String Last deal time
state String Order status(“1”: New order, “2”Partial order, “3”:Completely deal,”5”:Cancel,”6”:Cancal by risk triggered)

User's current plan to delegate channel

To obtain the user’s current plan entrusted data, user login is required

Send example:

{"op": "subscribe", "args": ["swap/current_plans:btcusd"]}

swap/current_plans is channel name, btcusd is instrument id

Response:

{
    "table": "swap/current_plans",
       "data": [{
           "id": "513468410013679613",
           "contractId": "btcusd",
           "amount": "12",
           "direction": "1",
           "done": "0",
           "forcePrice": "24",
           "price": "12",
           "status": "1",
           "time": "1606553787494",
           "forceTime": "1606553777494"       
     }]
}

Request Parameter

Parameter name Parameter type Description
id String Record number
contractId String product code
amount String Number of entrusted sheets
direction String Order type 1: open long 2: open short 3: close long 4: close short 5: close long 6: close short 7: close long by agreement 8: close short by agreement 9: close long by liquidation 10: close short by liquidation
done String Number of deals
forcePrice String Trigger mandatory price
price String Commission price
status String Order status (-1: Successful cancellation 0: Waiting for deal 1: Partial deal 2: Completed deal)
time String time
forceTime String Time to trigger forcing

User history plan delegate channel

Obtain user's historical plan delegate data, user login is required

Send example:

{"op": "subscribe", "args": ["swap/history_plans:btcusd"]}

swap/history_plans is channel name, btcusd is instrument id

Response:

{
       "table": "swap/history_plans",
       "data": [{
            "id": "513468410013679613",
            "arvPrice": "32",
            "amount": "12",
            "contractId": "btcusd",
            "time": "1606554020500",
            "dealCount": "12",
            "delegatePrice": "120.00",
            "direction": "1",
            "forcePrice": "24",
            "forceTime": "1606554010500",
            "orderType": "1",
            "pnl": "2541.21",
            "status": "1",
            "totalProfits": "1422.32"
     }]
}

Request Parameter

Parameter name Parameter type Description
id String Record number
arvPrice String Average transaction price
amount String Number of orders
contractId String product code
time String time
dealCount String The number of transactions
delegatePrice String Commission price
direction String Order type 1: open long 2: open short 3: close long 4: close short 5: close long 6: close short 7: close long by agreement 8: close short by agreement 9: close long by liquidation 10: close short by liquidation
forcePrice String Trigger mandatory price
forceTime String Time to trigger forcing
orderType String Order type 0 limit price 1 market price
pnl String Realized profit and loss
status String Order status (-1: Successful cancellation 0: Waiting for deal 1: Partial deal 2: Completed deal)
totalProfits String totalProfits

Public-Ticker channel

Obtain all perpetual contracts latest market price, best bidding price, best asking price and 24h trading volume

Send example:

{"op": "subscribe", "args": ["swap/ticker:btcusd"]}

swap/account is channel name, btcusd is instrument id

Response:

{
   "table": "swap/ticker",
   "data": [{
   "best_ask": "5603.5",
   "best_bid": "5600.1",
   "high_24h": "5773.7",
   "instrument_id": "btcusd",
   "last": "5603.3",
   "low_24h": "5566",
   "timestamp": "1559544244016",
   "volume_24h": "1538076",
   "holding": "1555450.000000",
   "volume_token_24h":"17955.2439",
   "volume_usdt_24h": "179556.2439" 
   }]
}

Request Parameter

Parameter name Parameter type Description
instrument_id String Contact name, e.g. btcusd
best_bid String Best bidding price
best_ask String Best asking price
last String Last deal price
high_24h String Highest price in 24h
low_24h String Lowest price in 24h
volume_24h String 24h volume
holding String Open interest
volume_token_24h String 24-hour trading volume in (coin)
volume_usdt_24h String 24-hour usdt
timestamp String System timestamp

Public- Candlestick chart

Public-cand Channel Public-cand

Obtain contract Candlestick chart data

Channel list：

swap/candle60s // 1min Candlestick chart data channel

swap/candle300s // 5min Candlestick chart data channel

swap/candle900s // 15min Candlestick chart data channel

swap/candle1800s // 30min Candlestick chart data channel

swap/candle3600s // 1h Candlestick chart data channel

swap/candle14400s // 4h Candlestick chart data channel

swap/candle43200s // 12h Candlestick chart data channel

swap/candle86400s // 1day Candlestick chart data channel

swap/candle604800s // 1week Candlestick chart data channel

Send example:

{"op": "subscribe", "args":["swap/candle60s:btcusd"]}

swap/account is channel name, btcusd is instrument id

Response:

{
   "table": "swap/candle60s",
   "data": [{
   "instrument_id": "btcusd",
   "candle": ["1559544244016", "5613", "5611.9", "5611.9", "1218", "21.7009","21.7009"]
   }]
}

Request Parameter

Parameter name Parameter type Description
timestamp String Start time
open String Opening price
high String Highest price
low String Lowest price
close String Closing price
volume String rading volume (cont)
currency_volume String Transaction volume (coins)
instrument_id String Contract btcusd

Public- Trading channel

Obtain recent trading data

Send example:

{"op": "subscribe", "args": ["swap/trade:btcusd"]}

swap/account is channel name, btcusd is instrument id

Response:

{
   "table": "swap/trade",
   "data": [{
   "instrument_id": "btcusd",
   "price": "5611.9",
   "side": "buy",
   "size": "2",
   "timestamp": "1559544244016",
   }]
}

Request Parameter

Parameter name Parameter type Description
price String Deal price
size String Deal QTY
side String Direction (buy or sell)
timestamp String Deal time
instrument_id String btcusd

Public – Fund fees channel

Obtain contract fees

Send example:

{"op": "subscribe", "args": ["swap/funding_rate:btcusd"]}

swap/account is channel name, btcusd is instrument id

Response:

{
   "table": "swap/funding_rate",
   "data": [{
   "funding_rate": "-0.00067",
   "funding_time": "1559544244016",
   "instrument_id": "btcusd",
   }]
}

Request Parameter

Parameter name Parameter type Description
instrument_id String Contact name, e.g. btcusd
funding_time String Next settlement time
funding_rate String Current fees

Public - Price limit channel

Obtain the best bidding and asking price for contact current position

Send example

{"op": "subscribe", "args": ["swap/price_range:btcusd"]}

swap/account is channel name, btcusd is instrument id

Response:

{
   "table": "swap/price_range",
   "data": [{
   "highest": "5665.9",
   "instrument_id": "btcusd",
   "lowest": "5553.6",
   "timestamp": "1559544244016"
   }]
}

Request Parameter

Parameter name Parameter type Description
timestamp String System timestamp
lowest String Best asking price
instrument_id String Contract name, e.g. btcusd
highest String Best bidding price

Public – Market depth 5 channel

Return first 5 range market depth data every time

Send example:

{"op": "subscribe", "args": ["swap/depth5:btcusd"]}

swap/account is channel name, btcusd is instrument id

Response:

{
   "table": "swap/depth5",
   "data": [{
   "asks": [
   ["5621.7", "58"],
   ["5621.8", "125"],
   ["5622", "84"],
   ["5622.5", "6"],
   ["5623", "1"]
   ],
   "bids": [
   ["5621.3", "287"],
   ["5621.2", "41"],
   ["5621.1", "2"],
   ["5621", "26"],
   ["5620.9", "640"]
   ],
   "instrument_id": "btcusd",
   "timestamp": "1559544244016"
   }]
}

Request Parameter

Parameter name Parameter type Description
asks String Asking market depth
bids String Bidding market depth
timestamp String Timestamp
instrument_id String Contract ID

["411.8","6"] [String,String] 411.8 is market depth price, 10 is QTY of this price

Public- Market depth channel

Return first 200 range for the first time, subsequent one is increment

Send example:

{"op": "subscribe", "args": ["swap/depth:btcusd"]}

swap/account is channel name, btcusd is instrument id

Response:

{
   "table": "swap/depth",
   "action": "(partial/update)",
   "data": [{
   "asks": [
   ["5621.7", "58"],
   ["5621.8", "125"],
   ["5622", "84"],
   ["5622.5", "6"],
   ["5623", "1"]
   ],
   "bids": [
   ["5621.3", "287"],
   ["5621.2", "41"],
   ["5621.1", "2"],
   ["5621", "26"],
   ["5620.9", "640"]
   ],
   "instrument_id": "btcusd",
   "timestamp": "1559544244016"
   }]
}

Request Parameter

Parameter name Parameter type Description
asks String Asking market depth
bids String Bidding market depth
action String Full amount increment tag
timestamp String Timestamp
instrument_id String Contract ID

["411.8","6"] [String,String] 411.8 is market depth price, 10 is QTY of this price

Public – Price tag channel

Obtain price tag

Send example:

{"op": "subscribe", "args": ["swap/mark_price:btcusd"]}

swap/account is channel name, btcusd is instrument id

Response:

{
     "table": "swap/mark_price",
     "data": [{
     "instrument_id": "btcusd",
     "mark_price": "5620.9",
     "timestamp": "1559544244016"
     }]             
 }

Request Parameter

Parameter name Parameter type Description
instrument_id String Contact name, e.g. btcusd
mark_price String Tag price
timestamp String System timestamp

WebSocketAPI error Code

Error message Error code
Invalid ACCESS_PASSPHRASE 30001
Invalid ACCESS_TIMESTAMP 30002
Invalid ACCESS_KEY 30003
Timestamp request expired 30004
Invalid sign 30005
Login failure 30006
Unrecognized request 30007
Channel doesn't exist 30008
User not logged in/User must be logged in 30009
Symbol not exists 30010
Symbol not open 30011

RestAPI error code

## Public error code

Error message error code http status code
ACCESS_KEY header is required 40001 400
ACCESS_SIGN header is required 40002 400
ACCESS_TIMESTAMP header is required 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 authentication failed 40009 400
Request too frequently 429 429
ACCESS_PASSPHRASE header is required 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

Contract error code

Error message error code http status code
The contract configuration does not exist, please check the parameters 40102 400
Can't find the order data, please confirm the order number 40109 400
Server upgrade, please try again later 40200 400
No permission to use it yet, if you need to use it, please contact customer service 40301 400
Can only query up to 20,000 data 40303 400
client_oid length is not greater than 40, and cannot be Martian characters 40305 400
Batch processing orders can only process up to 50 40306 400
The contract is temporarily maintained 40308 400
The contract has been removed 40309 400
Status check abnormal 40400 400
The operation cannot be performed 40401 400
The query direction is not the direction of the plan commission 40407 400
Range error 40408 400
wrong format 40409 400
Only check the data of the last three months 40704 400
The start and end time cannot exceed 90 days 40705 400
Start time is greater than end time 40707 400
There is no position in this position, and automatic margin call cannot be set 40709 400
Abnormal account status 40710 400
Insufficient contract account balance 40711 400
Insufficient margin 40712 400
Cannot exceed the maximum transferable margin amount 40713 400
The position is zero and direct margin call is not allowed 40714 400
The number of orders is greater than the maximum number that can be opened 40715 400
The trading pair does not support full position mode 40716 400
The number of closed positions cannot exceed the number of holdings 40717 400
The commission price for closing long positions is not allowed to be lower than the liquidation price 40718 400
The short order price is not allowed to be higher than the liquidation price 40719 400
Contract opponent depth does not exist 40720 400
Currently not allowed to list market orders 40721 400
Due to excessive price fluctuations and insufficient market price commission costs, the position opening commission failed 40722 400
The total number of unfilled orders is too high 40723 400
Parameter is empty 40724 400
contract service return an error 40725 400
Full position mode does not support automatic margin call 40726 400
Whole position mode does not support margin adjustment 40727 400
You are currently a trader, please close the position under the current order 40728 400
Failed to adjust the position, the current position or order or plan order 40729 400
There is currently a commission or a planned commission, and the leverage cannot be adjusted 40730 400
This product does not support copy trading 40731 400
Not currently a trader 40732 400
The order closing has been processed 40733 400
Failed to place an order, the minimum number of trader open positions %s 40734 400
Long position take profit price should be greater than the average opening price 40735 400
Long position take profit price is greater than the current price 40736 400
The short position take profit price should be less than the average opening price 40737 400
The short position take profit price should be less than the current price 40738 400
The stop loss price of a long position should be less than the average opening price 40739 400
The stop loss price of a long position should be less than the current price 40740 400
The stop loss price of a short position should be greater than the average opening price 40741 400
The stop loss price of the short position should be greater than the current price 40742 400
The order is being closed and cannot be closed again 40743 400
The tracking order status is wrong 40744 400
This order is being commissioned, and liquidation is not supported temporarily 40745 400
At present, the maximum number of positions that can be closed is %s. For the excess number, please go to the current order to close the position
40746 400
The bonus is not allowed to hold two-way positions 40747 400
The commission price is higher than the highest bid price 40748 400
The commission price is lower than the lowest selling price 40749 400
The plan commission for this contract has reached the upper limit 40750 400
The contract's stop profit and stop loss order has reached the upper limit 40751 400
console