English
NAV
console

Welcome

Welcome to Bitget ApiDoc! Click here for quick start

Update log

Jan 27, 2023

Jan 11, 2023

Dec 28, 2022

Dec, 21, 2022

Dec, 16, 2022

Dec, 07, 2022

Dec, 06, 2022

Nov, 23, 2022

Nov, 11, 2022

October, 27, 2022

October, 14, 2022

September, 15, 2022

September, 06, 2022

August, 29, 2022

August, 19, 2022

August, 16, 2022

August, 15, 2022

August, 08, 2022

August, 06, 2022

August, 01, 2022

July, 22, 2022

July, 21, 2022

July, 20 ,2022

July, 8 ,2022

June, 24 ,2022

June, 10 ,2022

April 02, 2022

February 25, 2022

February 12, 2022

January 05, 2022【Modification of frequency limit rules to add a new domain name】

add new domain name https://api.bitget.com

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 】

October 26, 2021

September 26, 2021【WebSocket Public Channel 】

September 08, 2021【Contract List and Ticker Quotes】

September 06, 2021【New account list query】

July 27, 2021 [New Quanto Swap Contract V1 Document]

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 APIs business line 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 usually displays 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:

  1. Provide UID (UID that is without any affiliate commission rebate);
  2. Provide other trading platform maker trading volume screenshot proof (for example, trading volume within 30 days）；
  3. 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 by:

FAQ

Quick Start

Access Preparation

If you need to use the API, please log in to the web page, then apply the API key application and complete the permission configuration, and then develop and trade according to the details of this document.

You can click here to create an API Key after login.

Each user can create 10 sets of Api Keys, and each Api Key can set permissions for reading and trading.

The permissions are described as follows:

After successfully created the API key, please remember the following information:

SDK/Code Example

open SDK（Recommended）

Java | Python | GoLang | NodeJs | PHP

PostMan（Demo） PostMan

You should first try to config the APIKey, Secretkey and Passphrase in the Environments tab on left of the PostMan

Interface Type

Interfaces are mainly divided into two types:

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.

The private interface will be verified from server side with your APIKey info.

Access Restriction

This chapter mainly focuses on access restrictions:

Rest API

If the APIKey is valid, we will use the APIKey to limit the frequency; if not, the public IP will be used to limit the frequency.

Frequency limit rules: There are separate instructions on each interface. If the limitation is not specified , the default frequency limit is 10 times per second.

Special note: When place orders in batch, 10 orders per currency pair will be counted as one request.

For example:

1~10 orders in a batch with ETHUSDT will be counted as one request

11~20 orders in a batch with BTCUSDT, then the rate-limit will count this batch order as 2 requests

21~30 orders in a batch with BTCUSDT, then the rate-limit will count this batch order as 3 requests

API Domain Name

You can use different domain as below Rest API.

Domain Name REST API Recommended To Use
Domain 1 https://api.bitget.com Main Domain
Domain 2 https://capi.bitget.com Old domain

API Verification

Initiate a request

The header of all REST requests must contain the following http headers：

//Java
Long timestamp = System.currentTimeMillis();

//python
import time
time.time_ns() / 1000000

//Golang
import (
  "time"
)
int64(time.Now().UnixNano()/1000000)

//Javascript
Math.round(new Date())

//PHP
microtime(true) * 1000;

Signature

The request header of ACCESS-SIGN is to encrypt timestamp + method.toUpperCase() + requestPath + "?" + queryString + body string (+ means string concat) by HMAC SHA256 algorithm with secretKey. and encode the encrypted result through BASE64.

Description of each parameter in the signature

If the queryString is empty, signature content

timestamp + method.toUpperCase() + requestPath + body

If the queryString not empty, signature content

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

For example

Get contract depth information, let's take BTCUSDT_UMCBL as an example:

Generate the content to be signed:

16273667805456GET/api/mix/v1/market/depth?symbol=BTCUSDT_UMCBL&limit=20

Contract order, take BTCUSDT_UMCBL as an example:

Generate the content 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 content with hmac sha256

String payload = hmac_sha256(secretkey, content);

The second step is to base64 encode the payload

String signature = base64.encode(payload);

Signature Code Demo

Java

public static String generate(String timestamp, String method, String requestPath,
                                  String queryString, String body, String secretKey)
            throws CloneNotSupportedException, InvalidKeyException, UnsupportedEncodingException {

        method = method.toUpperCase();
        body = StringUtils.defaultIfBlank(body, StringUtils.EMPTY);
        queryString = StringUtils.isBlank(queryString) ? StringUtils.EMPTY : "?" + queryString;

        String preHash = timestamp + method + requestPath + queryString + body;
        System.out.println(preHash);
        byte[] secretKeyBytes = secretKey.getBytes(SignatureUtils.CHARSET);
        SecretKeySpec secretKeySpec = new SecretKeySpec(secretKeyBytes, SignatureUtils.HMAC_SHA256);
        Mac mac = (Mac) SignatureUtils.MAC.clone();
        mac.init(secretKeySpec);
        return Base64.getEncoder().encodeToString(mac.doFinal(preHash.getBytes(SignatureUtils.CHARSET)));
    }


public static void main(String[] args) throws Exception {
      String msg=generate("1659927638003","POST","/api/mix/v1/order/placeOrder" ,null,"{"symbol":"TRXUSDT_UMCBL","side":"open_long","orderType":"limit","force":"normal","price":"0.046317","quantity":"1212"}","");
      System.out.println(msg);
    }

Python

def sign(message, secret_key):
    mac = hmac.new(bytes(secret_key, encoding='utf8'), bytes(message, encoding='utf-8'), digestmod='sha256')
    d = mac.digest()
    return base64.b64encode(d)


def pre_hash(timestamp, method, request_path, body):
    return str(timestamp) + str.upper(method) + request_path + body



if __name__ == '__main__':
    signStr = sign(pre_hash('1659927638003', 'POST', '/api/mix/v1/order/placeOrder', str('{"symbol":"TRXUSDT_SPBL","side":"open_long","orderType":"limit","force":"normal","price":"0.046317","quantity":"1212"}')), '')
    print(signStr)

For more demo code on other development languages, please refer to SDK

Request Interaction

All requests are based on the Https protocol, and the Content-Type in the POST request header should set to:'application/json'.

Request Interaction Description

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

Standard Specification

Timestamp

The unit of ACCESS-TIMESTAMP in the HTTP request signature is milliseconds. The timestamp of the request must be within 30 seconds of the API server 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 compare the timestamp 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.

Request Format

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

API Common parameters

productType

candlestick interval

marginMode

Margin Mode

Words Description
fixed Isolated margin
crossed Cross margin

holdMode

Position Mode

Words Description
single_hold One-way position
double_hold Two-way position

holdSide

Position Direction

Words Description
long Long position
short Short position

business

side

tradeSide

Values for double_hold

Words Description
open_long open long
open_short open short
close_long close long
close_short close short
reduce_close_long Force reduce long position
reduce_close_short Force reduce short position
offset_close_long Force netting: close long position
offset_close_short Force netting: close short position
burst_close_long Force liquidation: close long position
burst_close_short Force liquidation: close short position
delivery_close_long Future delivery close long
delivery_close_short Future delivery close short

Values for single_hold

Words Description
buy_single Buy in single_hold mode
sell_single Sell in single_hold mode
reduce_buy_single Force reduce buy in single_hold mode
reduce_sell_single Force reduce sell in single_hold mode
burst_buy_single Force liquidation: buy in single_hold mode
burst_sell_single Force liquidation: sell in single_hold mode
delivery_buy_single Future delivery buy in single_hold mode
delivery_sell_single Future delivery sell in single_hold mode

timeInForceValue

orderType

state

order status

Words Description
init initial order, inserted into DB
new new order, pending match in orderbook
partially_filled Partially Filled
filled Filled
canceled Canceled

triggerType

planType

isPlan

planStatus

stopType

Websocket planType

symbolStatus

RestAPI

Market

Get All Symbols

Limit rule: 20 times/1s (IP)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description
productType String Yes product type

Request Example

curl "https://api.bitget.com/api/mix/v1/market/contracts?productType=umcbl"

Response

{
  "code": "00000",
  "data": [
    {
      "baseCoin": "BTC",
      "buyLimitPriceRatio": "0.01",
      "feeRateUpRatio": "0.005",
      "makerFeeRate": "0.0002",
      "minTradeNum": "0.001",
      "openCostUpRatio": "0.01",
      "priceEndStep": "5",
      "pricePlace": "1",
      "quoteCoin": "USDT",
      "sellLimitPriceRatio": "0.01",
      "sizeMultiplier": "0.001",
      "supportMarginCoins": [
        "USDT"
      ],
      "symbol": "BTCUSDT_UMCBL",
      "takerFeeRate": "0.0006",
      "volumePlace": "3",
      "symbolType":"delivery",
      "symbolStatus": "normal",
      "offTime": "-1",
      "limitOpenTime": "-1"
    }
  ],
  "msg": "success",
  "requestTime": 1627114525850
}

Response Description

Parameter Description
symbol Symbol Id, BTCUSDT_UMCBL
symbolName Symbol name, BTCUSDT, might be empty
baseCoin Base currency, BTC
quoteCoin Quote currency, USDT
buyLimitPriceRatio Buy price limit ratio, 0.02 means 2%
sellLimitPriceRatio Sell price limit ratio, 0.01 means 1%
feeRateUpRatio Rate of increase in handling fee, 0.005 means 0.5%
makerFeeRate Maker fee rate, 0.0002 means 0.02%
takerFeeRate Taker fee rate, 0.0006 means 0.06%
openCostUpRatio Percentage of increase in opening cost, 0.01 means 1%
supportMarginCoins Support margin currency array
minTradeNum Minimum number of openings(Base Currency)
priceEndStep Price step, i.e. when pricePlace=1, priceEndStep=5 means the price would only accept numbers like 10.0, 10.5, and reject numbers like 10.2(10.2 divided by 0.5 not equals to 0)
volumePlace Number of decimal places
pricePlace Price scale precision, i.e. 1 means 0.1; 2 means 0.01
sizeMultiplier Quantity Multiplier The order size must be greater than minTradeNum and satisfy the multiple of sizeMultiplier
symbolType future type perpetual perpetual contract delivery delivery contract
symbolStatus Symbol Status
offTime delist time, '-1' means online symbol
limitOpenTime prohibit create order time, '-1' means normal; other value means symbol is under maintenance, and is not allow to create order afterwards

Get Depth

Limit rule: 20 times/1s (IP)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description
symbol String Yes Symbol Id (Must be capitalized)
limit String No Depth gear 5，15，50，100 default 100

Request Example

curl "https://api.bitget.com/api/mix/v1/market/depth?symbol=BTCUSDT_UMCBL&limit=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
}

The price & volume pair would return values in scientific notation expression

["1.937E+4","156.814"]

["0.000010934","1.2224E+8"]

Please do adjust your code for the scientific notation expression

Get Single Symbol Ticker

Limit rule: 20 times/1s (IP)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description
symbol String Yes Symbol Id (Must be capitalized)

Request Example

curl "https://api.bitget.com/api/mix/v1/market/ticker?symbol=BTCUSDT_UMCBL"

Response

{
    "code": "00000",
    "msg": "success",
    "data": {
        "symbol": "BTCUSDT_UMCBL",
        "last": "23990.5",
        "bestAsk": "23991",
        "bestBid": "23989.5",
        "bidSz": "2.154",
        "askSz": "176.623",
        "high24h": "24131.5",
        "low24h": "23660.5",
        "timestamp": "1660705778888",
        "priceChangePercent": "0.00442",
        "baseVolume": "156243.358",
        "quoteVolume": "3735854069.908",
        "usdtVolume": "3735854069.908",
        "openUtc": "23841.5",
        "chgUtc": "0.00625"
    }
}

Response Description

Parameter Description
symbol Symbol Id
last Latest price
bestAsk Ask1 price
bestBid Bid1 price
bidSz Ask1 size
askSz Bid1 size
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
openUtc UTC0 open price
chgUtc UTC0 price change(24 hour)

Get All Symbol Ticker

Limit rule: 20 times/1s (IP)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description
productType String Yes product type

Request Example

curl "https://api.bitget.com/api/mix/v1/market/tickers?productType=umcbl"

Response

{
    "code": "00000",
    "msg": "success",
    "requestTime": 0,
    "data": [{
        "symbol": "BTCUSDT_UMCBL",
        "last": "23990.5",
        "bestAsk": "23991",
        "bestBid": "23989.5",
        "bidSz": "2.154",
        "askSz": "176.623",
        "high24h": "24131.5",
        "low24h": "23660.5",
        "timestamp": "1660705778888",
        "priceChangePercent": "0.00442",
        "baseVolume": "156243.358",
        "quoteVolume": "3735854069.908",
        "usdtVolume": "3735854069.908",
        "openUtc": "23841.5",
        "chgUtc": "0.00625"
    }]
}

Response Description

Parameter Description
symbol Symbol Id
last Latest price
bestAsk Ask price
bestBid Bid price
bidSz Ask1 size
askSz Bid1 size
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
openUtc UTC0 open price
chgUtc UTC0 price change (24hour)

Get Fills

Get recent trades.

Limit rule: 20 times/1s (IP)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description
symbol String Yes Symbol Id (Must be capitalized)
limit String No Default limit is 100

Request Example

curl "https://api.bitget.com/api/mix/v1/market/fills?symbol=BTCUSDT_UMCBL&limit=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
}

Response Description

Parameter Description
tradeId tradeId
price price
size size
side side
timestamp timestamp, ms
symbol symbol

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Get Candle Data

Limit rule: 20 times/1s (IP)

Could only get data within 30 days, default return 100 rows

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description
symbol String Yes Symbol Id (Must be capitalized)
granularity String Yes Types of candlestick interval
startTime String Yes Start time (Timestamp ms, bigger or equals), will round-down as per granularity, which is: 1672410799436(2022-12-30 22:33:19) will rounded down to 1672410780000 (2022-12-30 22:33:00) if granularity=1m
endTime String Yes End time (Timestamp ms, less or equals), will round-down as per granularity, which is: 1672410799436(2022-12-30 22:33:19) will rounded down to 1672408800000 (2022-12-30 22:00:00) if granularity=1H

Request Example

curl "https://api.bitget.com/api/mix/v1/market/candles?symbol=BTCUSDT_UMCBL&granularity=300&startTime=1659406928000&endTime=1659410528000"

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 Index
Timestamp in milliseconds 0
Opening price 1
Highest price 2
Lowest price 3
Closing price, value of the latest candle stick might change, please try subscribe the websocket candlestick channel for the updates 4
Base currency trading volume 5
Quote currency trading volume 6

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Get Symbol Index Price

Limit rule: 20 times/1s (IP)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description
symbol String Yes Symbol Id (Must be capitalized)

Request Example

curl "https://api.bitget.com/api/mix/v1/market/index?symbol=BTCUSDT_UMCBL"

Response

{
    "code":"00000",
    "data":{
        "symbol":"BTCUSDT_UMCBL",
        "index":"35000",
        "timestamp":"1627291836179"
    },
    "msg":"success",
    "requestTime":1627291836179
}

Response Description

Parameter Description
symbol Symbol Id
index Index price
timestamp Timestamp, milliseconds

 

 

 

 

 

 

 

Get Symbol Next Funding Time

Limit rule: 20 times/1s (IP)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description
symbol String Yes Symbol Id (Must be capitalized)

Request Example

curl "https://api.bitget.com/api/mix/v1/market/funding-time?symbol=BTCUSDT_UMCBL"

Response

{
    "code":"00000",
    "data":{
        "symbol":"BTCUSDT_UMCBL",
        "fundingTime":"1627311600000"
    },
    "msg":"success",
    "requestTime":1627291915767
}

Response Description

Parameter Description
symbol Symbol ID
fundingTime Next settlement time, milliseconds

Get History Funding Rate

Limit rule: 20 times/1s (IP)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description
symbol String Yes Symbol 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

Request Example

curl "https://api.bitget.com/api/mix/v1/market/history-fundRate?symbol=BTCUSDT_UMCBL"

Response

{
    "code":"00000",
    "data":[
        {
            "symbol":"BTCUSDT",
            "fundingRate":"0",
            "settleTime":"1627369200000"
        }
    ],
    "msg":"success",
    "requestTime":1627389063463
}

Response Description

Parameter Description
symbol Symbol name
fundingRate Current funding rate
settleTime Settlement time

Get Current Funding Rate

Limit rule: 20 times/1s (IP)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description
symbol String Yes Symbol Id (Must be capitalized)

Request Example

curl "https://api.bitget.com/api/mix/v1/market/current-fundRate?symbol=BTCUSDT_UMCBL"

Response

{
    "code":"00000",
    "data":{
        "symbol":"BTCUSDT_UMCBL",
        "fundingRate":"0.0002"
    },
    "msg":"success",
    "requestTime":1627291969594
}

Response Description

Parameter Description
symbol Symbol Id
fundingRate Current funding rate

Get Open Interest

Limit rule: 20 times/1s (IP)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description
symbol String Yes Symbol Id (Must be capitalized)

Request Example

curl "https://api.bitget.com/api/mix/v1/market/open-interest?symbol=BTCUSDT_UMCBL"

Response

{
    "code":"00000",
    "data":{
        "symbol":"BTCUSDT_UMCBL",
        "amount":"757.8338",
        "timestamp":"1627292005913"
    },
    "msg":"success",
    "requestTime":1627292005913
}

Response Description

Parameter Description
symbol Symbol ID
amount Total platform open interest
timestamp Timestamp (milliseconds)

Get Symbol Mark Price

Limit rule: 20 times/1s (IP)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description
symbol String Yes Symbol Id (Must be capitalized)

Request Example

curl "https://api.bitget.com/api/mix/v1/market/mark-price?symbol=BTCUSDT_UMCBL"

Response

{
    "code":"00000",
    "data":{
        "symbol":"BTCUSDT_UMCBL",
        "markPrice":"35000",
        "timestamp":"1627292076687"
    },
    "msg":"success",
    "requestTime":1627292076687
}

Response Description

Parameter Description
symbol Symbol Id
markPrice Mark price
timestamp Timestamp (milliseconds)

Get Symbol Leverage

Limit rule: 20/sec (IP)

HTTP Request

Request Parameter

Parameter type required description
symbol String Yes symbol Id (Must be capitalized)

Request Example

curl "https://api.bitget.com/api/mix/v1/market/symbol-leverage?symbol=BTCUSDT_UMCBL"

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: 10 times/1s (uid)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description
symbol String Yes symbol Id (Must be capitalized)
marginCoin String Yes Margin coin

Request Example

curl "https://api.bitget.com/api/mix/v1/account/account?symbol=BTCUSDT_UMCBL&marginCoin=USDT" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

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), system will lock when close position
available Available balance(margin currency)
crossMaxAvailable The maximum available balance for crossed margin mode(margin currency)
fixedMaxAvailable The maximum available balance for fixed margin mode(margin currency)
maxTransferOut Maximum transferable
equity Account equity (margin currency)
usdtEquity Account equity convert to USDT,
btcEquity Account equity convert to BTC
crossRiskRate Risk ratio at crossed margin mode
crossMarginLeverage Leverage level for crossed margin mode
fixedLongLeverage Long leverage with isolated(fixed) margin mode
fixedShortLeverage Short leverage with isolated(fixed) margin mode
marginMode Margin mode
holdMode Hold mode

Get Account List

Limit rule: 20 times/2s (uid)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description
productType String Yes product type

Request Example

curl "https://api.bitget.com/api/mix/v1/account/accounts?productType=umcbl" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

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 Available balance(margin currency)
crossMaxAvailable The maximum available balance for crossed margin mode(margin currency)
fixedMaxAvailable The maximum available balance for isolated(fixed) margin mode(margin currency)
maxTransferOut Maximum transferable
equity Account equity (margin currency)
usdtEquity Account equity convert to USDT
btcEquity Account equity convert to BTC

Get sub Account Contract Assets

Limit rule: 1 times/10s (uid)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description
productType String Yes product type

Request Example

curl -X POST "https://api.bitget.com/api/mix/v1/account/sub-account-contract-assets" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"productType": "umcbl"}'

Response

{
    "code":"00000",
    "data":[
      {
        "userId": 4351550450,
        "contractAssetsList": [
          {
            "marginCoin": "USDT",
            "locked": "0",
            "available": "23.123",
            "crossMaxAvailable": "23.123",
            "fixedMaxAvailable": "23.123",
            "maxTransferOut": "23.123",
            "equity": "23.123",
            "usdtEquity": "23.123",
            "btcEquity": "0.001403612744",
            "unrealizedPL": "0"
          }
        ]
      },
      {
        "userId": 9465254769,
        "contractAssetsList": [
          {
            "marginCoin": "USDT",
            "locked": "0",
            "available": "11",
            "crossMaxAvailable": "11",
            "fixedMaxAvailable": "11",
            "maxTransferOut": "11",
            "equity": "11",
            "usdtEquity": "11",
            "btcEquity": "0.000667722189",
            "unrealizedPL": "0"
          }
        ]
      }
    ],
    "msg":"success",
    "requestTime":1630901215622
}

Response Description

Parameter Description
marginCoin Margin currency
locked Locked amount (margin currency)
available Available balance(margin currency)
crossMaxAvailable The maximum available balance for crossed margin mode(margin currency)
fixedMaxAvailable The maximum available balance for isolated(fixed) margin mode(margin currency)
maxTransferOut Maximum transferable
equity Account equity (margin currency)
usdtEquity Account equity convert to USDT
btcEquity Account equity convert to BTC
unrealizedPL Unrealized Profit or Lost

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 the specified leverage. The result does not represent the actual number of positions opened.

HTTP Request

Request Parameter(Request Body)

Parameter Name Parameter Type Required Description
symbol String Yes Symbol Id (Must be capitalized)
marginCoin String Yes Margin currency (Must be capitalized)
openPrice BigDecimal in String format Yes Opening price
leverage Int value in String format No Default leverage is 20
openAmount BigDecimal in String format Yes Opening amount in margin coin

Request Example

curl -X POST "https://api.bitget.com/api/mix/v1/account/open-count" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_UMCBL","marginCoin": "USDT","openPrice": "23189.5","leverage": "20","openAmount":"5000"}'

Response

{
    "code":"00000",
    "data":{
        "openCount":"2000"
    },
    "msg":"success",
    "requestTime":1627293049406
}

Change Leverage

Limit rule: 5 times/1s (uid)

HTTP Request

Request Parameter(Request Body)

Parameter Name Parameter Type Required Description
symbol String Yes Symbol Id (Must be capitalized)
marginCoin String Yes Margin currency (Must be capitalized)
leverage String Yes Leverage
holdSide String No Position direction (ignore this field if marginMode is crossed）

The leverage could set to different number in fixed margin mode(holdSide is required)

Request Example

curl -X POST "https://api.bitget.com/api/mix/v1/account/setLeverage" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_UMCBL","marginCoin": "USDT","leverage": "20"}'

Response

{
    "code":"00000",
    "data":{
        "symbol":"BTCUSDT_UMCBL",
        "marginCoin":"USDT",
        "longLeverage":25,
        "shortLeverage":20,
        "marginMode":"crossed"
    },
    "msg":"success",
    "requestTime":1627293049406
}

Response Description

Parameter Description
symbol Symbol Id
marginCoin Margin currency
longLeverage Long leverage
shortLeverage Short leverage
marginMode Margin Mode

Change Margin

Limit rule: 5 times/1s (uid)

HTTP Request

Request Parameter(Request Body)

Parameter Name Parameter Type Required Description
symbol String Yes Symbol Id (Must be capitalized)
marginCoin String Yes Margin currency (Must be capitalized)
amount String Yes Margin amount, positive: add margin, negative: reduce margin
holdSide String No Position direction (ignore this field if marginMode is crossed)

Request Example

curl -X POST "https://api.bitget.com/api/mix/v1/account/setMargin" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_UMCBL","marginCoin": "USDT","amount": "-10"}'

Response

{
    "code":"00000",
    "data":{
        "result":true
    },
    "msg":"success",
    "requestTime":1627293357336
}

 

 

 

 

 

 

 

 

 

 

 

Change Margin Mode

Limit rule: 5 times/1s (uid)

HTTP Request

Request Parameter(Request Body)

Server will return error if you call this interface with any exists position/order

Parameter Name Parameter Type Required Description
symbol String Yes Symbol Id (Must be capitalized)
marginCoin String Yes Margin currency (Must be capitalized)
marginMode String Yes Margin mode

Request Example

curl -X POST "https://api.bitget.com/api/mix/v1/account/setMarginMode" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_UMCBL","marginCoin": "USDT","marginMode": "crossed"}'

Response

{
    "code":"00000",
    "data":{
        "symbol":"BTCUSDT_UMCBL",
        "marginCoin":"USDT",
        "longLeverage":25,
        "shortLeverage":20,
        "marginMode":"crossed"
    },
    "msg":"success",
    "requestTime":1627293445916
}

Response Description

Parameter Description
symbol Symbol Id
marginCoin Margin currency
longLeverage Long leverage
shortLeverage Short leverage
marginMode Margin mode

 

 

 

 

 

 

 

 

 

 

 

Change Hold Mode

Please DO NOT change the hold mode with existing position under the symbol

Limit rule: 5 times/1s (uid)

HTTP Request

Request Parameter(Request Body)

Parameter Name Parameter Type Required Description
productType String Yes product type
holdMode String Yes Hold mode

Might fail if intended to change hold mode when the "symbol" has positions on any side

Request Example

curl -X POST "https://api.bitget.com/api/mix/v1/account/setPositionMode" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"productType": "umcbl","holdMode": "double_hold"}'

Response

{
    "code":"00000",
    "msg":"success",
    "data":{
        "symbol":"BTCUSDT_UMCBL",
        "marginCoin":"USDT",
        "dualSidePosition":true
    },
    "requestTime":1627293445916
}

Response Description

Parameter Description
symbol Symbol Id
marginCoin Margin currency
dualSidePosition boolean, true: "double_hold"; false: "single_hold"

 

 

 

 

 

 

 

 

Get Symbol Position

Limit rule: 10 times/1s (uid)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description
symbol String Yes symbol Id (Must be capitalized)
marginCoin String No Margin currency (Must be capitalized)

Request Example

curl "https://api.bitget.com/api/mix/v1/position/singlePosition?symbol=BTCUSDT_UMCBL&marginCoin=USDT" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

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",
            "marketPrice":"0",
            "ctime":"1626232130664"
        }
    ],
    "msg":"success",
    "requestTime":1627293612502
}

Response Description

Parameter Description
symbol Symbol Id
marginCoin Margin currency
holdSide Position direction
openDelegateCount Open amount pending to fill (base currency)
margin Margin quantity (margin currency)
available Position available (Quote currency)
locked Position locked (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 or loss
keepMarginRate keep margin rate
marketPrice market price
cTime Last update time Timestamp milliseconds

Get All Position

Limit rule: 5 times/1s (uid)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description
productType String Yes Product type
marginCoin String No Margin currency (Must be capitalized)

Request Example

curl "https://api.bitget.com/api/mix/v1/position/allPosition?productType=umcbl&marginCoin=USDT" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

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",
            "marketPrice":"0",
            "ctime":"1626232130664"
        }
    ],
    "msg":"success",
    "requestTime":1627293612502
}

Response Description

Parameter Description
symbol Symbol Id
marginCoin Margin currency
holdSide Position direction
openDelegateCount Opened amount pending to fill (trading currency)
margin Margin quantity (margin currency)
available Position available (Quote currency)
locked Position locked (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
marketPrice market price
cTime Last update time Timestamp milliseconds

Get Account Bill

Limit rule: 10/sec (uid)

HTTP Request

Request (Request Param)

Parameter type required description
symbol String Yes Symbol Id
marginCoin String Yes margin coin
startTime String Yes Start Time, milliseconds
endTime String Yes end time, milliseconds
pageSize int No page size, default 20, max is 100
lastEndId String No last end Id of last query
next boolean No Whether query return lastEndId? default false

Request Example

curl "https://api.bitget.com/api/mix/v1/account/accountBill?symbol=BTCUSDT_UMCBL&marginCoin=USDT&startTime=1659403328000&endTime=1659406928000&pageSize=20" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

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 ID
symbol Symbol Id
marginCoin margin Coin
amount charge amount
fee fee
feeByCoupon fee deduction coupon
feeCoin fee coin
business business
cTime create time
lastEndId last end Id, will return when next set to true

Get Business Account Bill

Limit rule: 5/sec (uid)

HTTP Request

Request (Request Param)

Parameter type required description
productType String Yes Product Type
startTime String Yes Start Time, millisecond
endTime String Yes end time, millisecond
pageSize int No page size, default 20, max is 100
lastEndId String No last end Id of last query
next boolean No Whether query return lastEndId? default false

Request Example

curl "https://api.bitget.com/api/mix/v1/account/accountBusinessBill?productType=umcbl&startTime=1659403328000&endTime=1659406928000&pageSize=20" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

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 charge amount
fee fee
feeByCoupon fee deduction coupon
feeCoin fee coin
business business
cTime create time
lastEndId last end Id, will return when next set to true

Trade

Place Order

Limit rule: 10 times/1s (uid)

Trader Limit rule: 1 times/1s (uid)

If you are a trader, you can only use this interface to open a position. To close a position, you need to call CopyTrade -> Trader close Position

The price and quantity of the order need to meet pricePlace and priceEndStep volumePlace, those fields could be found from the response of Market -> Get All Symbols

for example:

pricePlace of BTCUSDT_UMCBL is 1 and priceEndStep is 5, then the order price needs to satisfy a multiple of 0.5, for example, the price should be 23455.0, 23455.5, 23446.0

pricePlace of ETHUSDT_UMCBL is 2 and priceEndStep is 1, then the order price needs to satisfy a multiple of 0.01, for example, the price should be 1325.00, 1325.01, 1325.02

High frequency error when close position：

There are two scenarios where this error would happen

Specially, if specify a size greater than the position size when closing position, the order will success with actual position size, that is, reduceOnly.

For example,

Unknown error

HTTP Request

Request Parameter(Request Body)

Parameter Name Parameter Type Required Description
symbol String Yes Symbol Id
marginCoin String Yes Margin currency
size String Yes Order quantity, base coin
price String No Order price (not required at market price)
side String Yes Order direction
orderType String Yes Order type
timeInForceValue String No Time in force
clientOid String No Unique client order ID, The idempotent is promised but only within 30 days
reduceOnly Boolean No Default false; set to true when try to reduce position in 'single_hold' mode and when close position with value less than 5USDT, DOES NOT WORK under 'double_hold' mode
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

If client does not pass clientOid , the user should be awared that the order might be duplicated, as this is the only idempotent promise field between client and server

 

Duplicate clientOid

{
    "code":"40786",
    "msg":"Duplicate clientOid",
    "requestTime":1627293504612
}

 

 

 

 

 

 

 

 

 

 

 

 

Reversal

Limit rule: 10 times/1s (uid), counted together with placeOrder

Reversal share the same interface with Place order.

Reversal logic is different under "double_hold"/"single_hold" hold mode:

double_hold: 1) You could usually specify a size(size > 0 and size <= position size), which the size will be closed from your current position and a same size will be opened on the opposite side 2) "side" value: close_short or close_long

single_hold: 1) The size parameter is omitted, that means you could only close the whole position, then try to open on the opposite side with market price, the open position might fail due to margin condition 2) "side" value: sell_single when position side is buy_single, buy_single when position side is sell_single

Note: Your position will be closed at market price and open in reverse side for the specific amount.

If the close position settled amount + available balance are insufficient to open the specific size of positions, or the reverse order value is less than 5 USDT, the specified size position will be closed and the position open will fail.

Your operation may not be 100% successful due to margin, market conditions and other factors.

You must have an exists position to trigger a reversal operation, or server will return error "Not enough position is available."

Not enough position

{
    "code": "40757",
    "msg": "Not enough position is available.",
    "requestTime": 1665454799692,
    "data": null
}

The reverse order size usually should be same as the original size. For example: original position size 100, in reversal request you should set the size to 100, Server will then close your original position 100, and open extra 100 in reversal side in market price with the best efforts.

The reverse order size could also be set to 1.5 or 3 times of the original size(or even more), in reversal it will first close all of your position in market price, then try to open reverse position with the original size (that is: if reversal size is bigger than the original position size, the reversal size will be treated as the original position size)

The reverse order size could also be set to a number between 0 to 1 times of the original position size, in reversal it will first close your position with specific reversal size in market price, then try to open reverse position with the specific size

orderType must be market price, a limit price order will be treated as market price order in reversal

Reversal Sample: original order

{
    "size": "100",
    "side": "open_long",
    "orderType": "market",
    "timeInForceValue": "normal",
    "symbol": "TRXUSDT_UMCBL",
    "marginCoin": "USDT"
}

Reversal Sample: reverse order

{
   "size": "100",
   "side": "close_long",
    "orderType": "market",
    "timeInForceValue": "normal",
    "symbol": "TRXUSDT_UMCBL",
    "marginCoin": "USDT",   
    "reverse":true
}

If originally side is open_long, then in reversal you should set the side to close_long; If originally side is open_short, then in reversal you should set the side to close_short; Use sell_single when original position side is buy_single, Use buy_single when original position side is sell_single;

Samples on the right side demonstrate a reversal operation. Ideally at the end you should be holding 100 TRXUSDT short position

HTTP Request

Request Parameter(Request Body)

Parameter Name Parameter Type Required Description
symbol String Yes Symbol Id
marginCoin String Yes Margin currency
size String No Order quantity size = close_size = open_reverse_size; this param will be omitted in single_hold mode
side String Yes Order direction, set to close_long or close_short in double_hold mode; set to buy_single or sell_single in single_hold mode
orderType String Yes Order type: market
clientOid String No Unique Client ID
timeInForceValue String No set to 'normal'
reverse Boolean No Default false: place order; true: reversal order

Reversal Request Example

curl -X POST "https://api.bitget.com/api/mix/v1/order/placeOrder" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_UMCBL","marginCoin": "USDT","size": "0.01","side":"open_long","orderType":"market","timeInForceValue":"normal","clientOid":"reverse@483939290002","reverse":true}'

Reversal 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)

Trader Limit rule: 1 times/1s (uid)

HTTP Request

Request Parameter(Request Body)

Parameter Name Parameter Type Required Description
symbol String Yes Symbol Id (Must be capitalized)
marginCoin String Yes Margin currency (Must be capitalized)
orderDataList List Yes Order data list, maximum size: 50

orderDataList

Maximum 50 orders

Parameter Name Parameter Type Required Description
size String Yes Order quantity
price String No Order price, quote coin
side String Yes Order direction
orderType String Yes Order type
timeInForceValue String No Time In Force
clientOid String No Unique Client ID, the idempotent is promised but only within 24 hours

Request Example

curl -X POST "https://api.bitget.com/api/mix/v1/order/batch-orders" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_UMCBL","marginCoin": "USDT",  "orderDataList":[{"size": "0.01","price": "23145.5","side":"open_long","orderType":"limit","timeInForceValue":"normal","clientOid":"test@483939290000"}] }'

Response

{
  "code": "00000",
  "data": {
    "orderInfo": [
      {
        "orderId": "1627293504612",
        "clientOid": "BITGET#1627293504612"
      }
    ],
      "failure":[
          {
              "orderId": "1627293504611",
              "clientOid": "BITGET#1627293504611",
              "errorMsg":"Duplicate clientOid"
          }
      ]
  },
  "msg": "success",
  "requestTime": 1627293504612
}

Response Description

Parameter Description
orderInfo Successful order array
> orderId Order Id
> clientOid Client custom Id
failure Failure order array
> orderId Order Id, might be empty
> clientOid Client custom Id
> errorMsg Fail reason

 

 

 

 

  

 

 

 

 

Cancel Order

Limit rule: 10 times/1s (uid)

HTTP Request

Request Parameter(Request Body)

Parameter Name Parameter Type Required Description
symbol String Yes Symbol Id (Must be capitalized)
marginCoin String Yes Margin currency (Must be capitalized)
orderId String Yes Order Id

Request Example

curl -X POST "https://api.bitget.com/api/mix/v1/order/cancel-order" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_UMCBL","marginCoin": "USDT","orderId":"1627293504612"}'

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

Request Parameter(Request Body)

Parameter Name Parameter Type Required Description
symbol String Yes Symbol Id (Must be capitalized)
marginCoin String Yes Margin currency (Must be capitalized)
orderIds List Yes Order Id list

Request Example

curl -X POST "https://api.bitget.com/api/mix/v1/order/cancel-batch-orders" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_UMCBL","marginCoin": "USDT","orderIds":["1627293504612"]}'

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
symbol Symbol Id
order_ids Order Id array
fail_infos Failed information array
> order_id Failed order id
> err_code Error code
> err_msg error msg

Cancel All Order

Limit rule: 10 times/1s (uid)

HTTP Request

Request Parameter(Request Body)

Parameter Name Parameter Type Required Description
productType String Yes Product type
marginCoin String Yes Margin currency (Must be capitalized)

Request Example

curl -X POST "https://api.bitget.com/api/mix/v1/order/cancel-all-orders" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"productType": "umcbl","marginCoin": "USDT"}'

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
symbol Symbol Id
order_ids Cancel success order Id list
fail_infos cancel failed information
> order_id Failed order id
> err_code Error code
> err_msg Error message

Get Open Order

Limit rule: 20 times/1s (uid)

HTTP Request

Get pending order list on one symbol;

Note that for the history order please refer to Get History Orders

For the TPSL order please refer to Get Plan Order (TPSL) List

Request Parameter

Parameter Name Parameter Type Required Description
symbol String Yes symbol Id (Must be capitalized)

Request Example

curl "https://api.bitget.com/api/mix/v1/order/current?symbol=BTCUSDT_UMCBL" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

Response

{
    "code":"00000",
    "data":{
      "nextFlag":false,
      "endId":"802355881591844864",
      "orderList": [
            {
                "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",
                "orderType":"limit",
                "ctime":1627028708807
            }
        ]
    },
    "msg":"success"
}

Response Description

Parameter Description
symbol Symbol id
size Order size
orderId Order Id
clientOid Client custom id
filledQty Transaction volume, base coin
fee Transaction fee
price Order price
state Order state
side Order direction
timeInForce Time In Force
totalProfits Total profit and loss
posSide Position direction
marginCoin Margin currency
orderType Order type
cTime Last update time

Get All Open Order

Limit rule: 20 times/1s (uid)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description
productType String Yes productType
marginCoin String No margin coin

Request Example

curl "https://api.bitget.com/api/mix/v1/order/marginCoinCurrent?productType=umcbl&marginCoin=USDT" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

Response

{
    "code":"00000",
    "data":{
      "nextFlag":false,
      "endId":"802355881591844864",
      "orderList":[
            {
                "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",
                "orderType":"limit",
                "ctime":1627028708807
            }
        ]
    },
    "msg":"success"
}

Response Description

Parameter Description
symbol Symbol Id
size Order size
orderId Order Id
clientOid Client custom id
filledQty Transaction volume
fee Transaction fee
price Order price
state Order state
side Order direction
timeInForce Time In Force
totalProfits Total profit and loss
posSide Position direction
marginCoin Margin currency
orderType Order type
cTime Last update time

Get History Orders

Limit rule: 20 times/2s (uid)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description
symbol String Yes Symbol Id (Must be capitalized)
startTime String Yes Start time, milliseconds
endTime String Yes End time, milliseconds
pageSize String Yes Page size
lastEndId String No last end Id of last query
isPre Boolean No true: order by order Id asc; default false

Request Example

curl "https://api.bitget.com/api/mix/v1/order/history?symbol=BTCUSDT_UMCBL&startTime=1659403328000&endTime=1659410528000&pageSize=20" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

Response

{
  "code": "00000",
  "msg": "success",
  "requestTime": 1665715936583,
  "data": {
    "nextFlag": true,
    "endId": "963544804144852112",
    "orderList": [
    {
      "symbol": "SOLUSDT_UMCBL",
      "size": 1,
      "orderId": "963544804144852112",
      "clientOid": "963544804144852113",
      "filledQty": 1,
      "fee": -0.00629204,
      "price": 31.4602,
      "priceAvg": 31.4602,
      "state": "filled",
      "side": "close_short",
      "timeInForce": "normal",
      "totalProfits": 0.00760000,
      "posSide": "short",
      "marginCoin": "USDT",
      "filledAmount": 31.4602,
      "orderType": "limit",
      "leverage": "5",
      "marginMode": "crossed",
      "cTime": "1665452903781",
      "uTime": "1665452917467"
    }
    ]
  }
}

Response Description

Parameter Description
symbol Symbol Id
size Order size
orderId Order Id
clientOid Client order id
filledQty Transaction volume
fee Transaction fee
price Order price
priceAvg Order fill avg price
state Order state
side Order direction
timeInForce Time In Force
totalProfits Total profit and loss
posSide Position direction
marginCoin Margin currency
leverage order leverage
marginMode Margin mode
orderType Order type
cTime create time
uTime last update time

Get ProductType History Orders

Limit rule: 5/1s (uid)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description
productType String Yes Product type
startTime String Yes Start time, milliseconds
endTime String Yes End time, milliseconds
pageSize String Yes page size
lastEndId String No Last query endId
isPre Boolean No true: order by order Id asc; default false

Request Example

curl "https://api.bitget.com/api/mix/v1/order/historyProductType?productType=umcbl&startTime=1659403328000&endTime=1659410528000&pageSize=20" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

Response

{
    "code":"00000",
    "data":{
      "nextFlag": true,
      "endId": "963544804144852112",
      "orderList": [
            {
                "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",
                "leverage":"20",
                "marginMode":"crossed",
                "orderType":"limit",
                "ctime":1627028708807
            }
        ]
    },
    "msg":"success"
}

Response Description

Parameter Description
symbol Symbol Id
size Order size
orderId Order Id
clientOid Client custom id
filledQty Transaction volume
fee Transaction fee
price Order price
priceAvg Order fill avg price
state Order state
side Order direction
timeInForce Time In Force
totalProfits Total profit and loss
posSide Position direction
marginCoin Margin currency
leverage order leverage
marginMode account Margin mode
orderType Order type
cTime create time
uTime last update time

Get Order Details

Limit rule: 20 times/2s (uid)

HTTP Request

Request Parameter (Request Param)

Parameter Name Parameter Type Required Description
symbol String Yes Symbol Id (Must be capitalized)
orderId String No Order Id
clientOid String No Customized Client Order Id

Request Example

curl "https://api.bitget.com/api/mix/v1/order/detail?symbol=BTCUSDT_UMCBL&orderId=802382049422487552" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

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 Symbol Id
size Order size
orderId Order Id
clientOid Client custom id
filledQty Transaction volume
priceAvg Transaction price
fee Transaction fee
price Order price
state Order state
side Order direction
timeInForce Time In Force
totalProfits Total profit and loss
posSide Position direction
marginCoin Margin currency
cTime create time
uTime update time
presetTakeProfitPrice Preset take profit price
presetStopLossPrice Preset stop loss price
filledAmount filled amount, limit/market
orderType order type

Get Order fill detail

Limit rule: 20 times/2s (uid)

HTTP Request

Request Parameter (Request Param)

Parameter Type Required Description
symbol String Yes Symbol Id (Must be capitalized)
orderId String No Order Id
startTime String No Start time (timestamp in milliseconds) This field is required if orderId is empty
endTime String No End time (timestamp in milliseconds) This field is required if orderId is empty
lastEndId String No Pagination parameter; Query the data after this tradeId; works when orderId is null

Request Example

curl "https://api.bitget.com/api/mix/v1/order/fills?symbol=BTCUSDT_UMCBL&orderId=802382049422487552" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

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 Symbol Id
orderId Order Id
price Transaction price
sizeQty Transaction volume
fee Transaction fee
side Trade side
cTime Trade time

Get ProductType Order fill detail

Limit rule: 10 times/1s (uid)

HTTP Request

Request Parameter (Request Param)

Parameter Type Required Description
productType String Yes Product type
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

Default pageSize: 100

Request Example

curl "https://api.bitget.com/api/mix/v1/order/allFills?productType=umcbl&startTime=1659406928000&endTime=1659410528000" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

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 Symbol Id
orderId Order Id
price Transaction price
sizeQty Transaction volume
fee Transaction fee
side Trade side
cTime Trade time

Place Plan order

Limit rule: 10 times/1s (uid)

HTTP Request

Request Parameter (Request Body)

Parameter Name Parameter Type Required Description
symbol String Yes Symbol Id (Must be capitalized)
marginCoin String Yes Margin currency (Must be capitalized)
size String Yes Order quantity
executePrice String No Execute price, cuold not be null when orderType=limit
triggerPrice String Yes Trigger price
side String Yes Order side
orderType String Yes Order type
triggerType String Yes Trigger type
clientOid String No Unique Client ID, idempotent is only promised within 24 hours
presetTakeProfitPrice String No Preset take profit price
presetStopLossPrice String No Preset stop loss price

Request Example

curl -X POST "https://api.bitget.com/api/mix/v1/plan/placePlan" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_UMCBL","marginCoin": "USDT","size": "0.01","executePrice": "23145.5","triggerPrice":"23555.5","side":"open_long","orderType":"limit","timeInForceValue":"normal","triggerType":"market_price","clientOid":"test@483939290000"}'

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

Request Parameter (Request Body)

Parameter Name Parameter Type Required Description
orderId String Yes Limit order Id
marginCoin String Yes Margin currency
symbol String Yes Symbol Id
executePrice String No Strike price, cuold not be null when orderType=limit
triggerPrice String Yes Trigger price
triggerType String Yes Trigger type
orderType String Yes Order type

Request Example

curl -X POST "https://api.bitget.com/api/mix/v1/plan/modifyPlan" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"orderId":"803521986049314816","symbol": "BTCUSDT_UMCBL","marginCoin": "USDT","executePrice": "23145.5","triggerPrice":"23555.5","orderType":"limit","triggerType":"market_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 TPSL

Limit rule: 10 times/1s (uid)

HTTP Request

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

Request Example

curl -X POST "https://api.bitget.com/api/mix/v1/plan/modifyPlanPreset" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"orderId":"803521986049314816","symbol": "BTCUSDT_UMCBL","marginCoin": "USDT","presetTakeProfitPrice": "23145.5","presetStopLossPrice":"23555.5"}'

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

Request Parameter(Request Body)

Parameter Name Parameter Type Required Description
marginCoin String Yes Margin currency (Must be capitalized)
symbol String Yes Symbol Id (Must be capitalized)
planType String Yes plan type, please use "profit_plan", "loss_plan" and "moving_plan"
triggerPrice String Yes Trigger price
triggerType String No Trigger Type default 'fill_price'
holdSide String Yes Hold Side, Whether this position is long or short
size String No Order Quantity Default Position Quantity
rangeRate String No Only works when planType is "moving_plan", "1" means 1.0% price correction, two decimal places

Request Example

curl -X POST "https://api.bitget.com/api/mix/v1/plan/placeTPSL" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_UMCBL","marginCoin": "USDT","size": "0.01","planType": "profit_plan","triggerPrice":"23555.5","holdSide":"long"}'

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 Trailing Stop Order

Limit rule: 10 times/1s (uid)

HTTP Request

Request Parameter(Request Body)

Parameter Name Parameter Type Required Description
marginCoin String Yes Margin currency (Must be capitalized)
symbol String Yes Symbol Id (Must be capitalized)
triggerPrice String Yes Trigger price
triggerType String No Trigger Type
size String No Order Quantity Default Position Quantity
side String Yes Order side
rangeRate String No "1" means 1.0% price correction, two decimal places

Request Example

curl -X POST "https://api.bitget.com/api/mix/v1/plan/placeTrailStop" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_UMCBL","marginCoin": "USDT","size": "0.01","triggerPrice":"23555.5","holdSide":"long","rangeRate":"10"}'

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 Position TPSL

Limit rule: 10 times/1s (uid)

When the position take profit and stop loss are triggered, the full amount of the position will be entrusted at the market price by default

HTTP Request

Request Parameter(Request Body)

Parameter Name Parameter Type Required Description
marginCoin String Yes Margin currency (Must be capitalized)
symbol String Yes Symbol Id (Must be capitalized)
planType String Yes plan type, please use "pos_profit", "pos_loss"
triggerPrice String Yes Trigger price
triggerType String Yes Trigger type
holdSide String No Whether this position is long or short

Request Example

curl -X POST "https://api.bitget.com/api/mix/v1/plan/placePositionsTPSL" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_UMCBL","marginCoin": "USDT","planType": "pos_profit","triggerPrice":"23555.5","holdSide":"long"}'

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

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 Symbol Id (Must be capitalized)
triggerPrice String No Trigger price
planType String Yes Refer to plan type: "pos_profit" or "profit_plan"; "pos_loss" or "loss_plan"

Request Example

curl -X POST "https://api.bitget.com/api/mix/v1/plan/modifyTPSLPlan" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"orderId":"803521986049314816","symbol": "BTCUSDT_UMCBL","marginCoin": "USDT","triggerPrice":"23555.5","planType":"pos_profit"}'

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

Request Parameter(Request Body)

Parameter Name Parameter Type Required Description
orderId String Yes Limit order Id
symbol String Yes Symbol Id (Must be capitalized)
marginCoin String Yes Margin Coin
planType String Yes plan type

Request Example

curl -X POST "https://api.bitget.com/api/mix/v1/plan/cancelPlan" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"orderId":"803521986049314816","symbol": "BTCUSDT_UMCBL","marginCoin": "USDT","planType":"loss_plan"}'

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 All trigger Order (TPSL)

Limit rule: 10 times/1s (uid)

HTTP Request

Request Parameter(Request Body)

Parameter Name Parameter Type Required Description
productType String Yes product type
planType String Yes plan type

Request Example

curl -X POST "https://api.bitget.com/api/mix/v1/plan/cancelPlan" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"productType":"umcbl","planType":"loss_plan"}'

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/1s (uid)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description
symbol String Yes Symbol Id (Must be capitalized)
isPlan String No Is plan
productType String No product type

Request Example

curl "https://api.bitget.com/api/mix/v1/plan/currentPlan?symbol=BTCUSDT_UMCBL&isPlan=plan" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

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 Symbol Id
marginCoin Margin currency
size Order size
executePrice Order price
triggerPrice Trigger price
status Plan order status
orderType Order type
planType plan type
side Trade side
triggerType Trigger type
presetTakeProfitPrice Preset take profit price
presetTakeLossPrice Preset stop loss price
ctime Order creation time

Get History Plan Orders (TPSL)

Limit rule: 10 times/1s (uid)

HTTP Request

Request Parameter (Request Param)

Parameter Name Parameter Type Required Description
symbol String Yes Symbol Id (Must be capitalized)
startTime String Yes Start time, milliseconds
endTime String Yes End time, milliseconds
pageSize Integer No Page size, default 100
isPre boolean No true: order by order Id asc; default false
isPlan String No Is plan

Request Example

curl "https://api.bitget.com/api/mix/v1/plan/historyPlan?symbol=BTCUSDT_UMCBL&startTime=1659406928000&endTime=1659414128000&pageSize=20" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

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 Plan Order Id
executeOrderId Execute success Order Id
symbol Symbol Id
marginCoin Margin currency
size Order size
executeSize Execute Size
executePrice Order price
triggerPrice Trigger price
status Plan order status
orderType Order type
planType Plan type
side Side
triggerType Trigger type

CopyTrade

Get Trader Open order

Limit rule 10 times/1s (uid)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description
symbol String Yes Symbol Id (Must be capitalized)
productType String Yes Product type
pageSize int Yes Page size; Max 100
pageNo int Yes Page number

Request Example

curl "https://api.bitget.com/api/mix/v1/trace/currentTrack?symbol=BTCUSDT_UMCBL&productType=umcbl&pageSize=20&pageNo=1" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

Response

{
    "code":"00000",
    "data":[
        {
            "symbol":"BTCUSDT_UMCBL",
            "trackingNo":"699848017573842632",
            "openOrderId":"4839999132328",  
            "holdSide":"long",
            "openLeverage":20,
            "openAvgPrice":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, instead a tracking order number is required to close order
symbol Symbol Id
holdSide Position direction
openLeverage Opening leverage
openAvgPrice Average opening price
openTime Position opening time (milliseconds)
openDealCount Number of positions opened
stopProfitPrice Take profit price
stopLossPrice Stop price

Get Follower Open Orders

Limit rule 10 times/1s (uid)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description
symbol String Yes Symbol Id (Must be capitalized)
productType String Yes product type
pageSize int Yes Page size
pageNo int Yes Current page number

Request Example

curl "https://api.bitget.com/api/mix/v1/trace/followerOrder?symbol=BTCUSDT_UMCBL&productType=umcbl&pageSize=20&pageNo=1" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

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 Symbol Id
holdSide Current Position direction
openLeverage Opening leverage
openAvgPrice Average opening price
openTime Position opening time (milliseconds)
openDealCount Number of positions opened
openMargin Open margin in quote coin
averageClosePrice Average Close Price
closeDealCount Close Count
closeTime Close Position Time (milliseconds)

Get Follower History Orders

Limit rule 20 times/2s (uid)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description
startTime String Yes Start time timestamp
endTime String Yes product type
pageSize int Yes Page size
pageNo int Yes Current page number

Request Example

curl "https://api.bitget.com/api/mix/v1/trace/followerHistoryOrders?startTime=1668073994000&endTime=1668073994206&pageSize=20&pageNo=1" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

Response

{
    "code":"00000",
    "data":[
        {
            "symbol":"BTCUSDT_UMCBL",
            "trackingNo":"682799071840175632",
            "holdSide":"long",
            "openSize":"20",
            "closeSize":"20",
            "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",
            "profitRate":"1",
            "netProfit":"1"

        }
    ],
    "msg":"success",
    "requestTime":1627354109502
}

Response Description

Parameter Description
trackingNo Tracking order number
openOrderNo Open Position Order Id
closeOrderNo Close Position Order Id
symbol Symbol Id
holdSide Current Position direction
leverage Opening leverage
openAvgPrice Average opening price
openTime Position opening time (milliseconds)
openSize Open order size
closeAvgPrice Average close price
closeFee close fee
openFee open fee
closeSize close order size
closeTime close positions time (milliseconds)
profitRate Profit Rate
netProfit follow net income
achievedProfits Realized profit and loss

Trader Close Position

Limit rule 10 times/1s (uid)

HTTP Request

Request Parameter (Request Body)

Parameter Name Parameter Type Required Description
symbol String Yes Symbol Id (Must be capitalized)
trackingNo String Yes Tracking Order Id, From the /currentTrack in response the "trackingNo" field

Request Example

curl -X POST "https://api.bitget.com/api/mix/v1/trace/closeTrackOrder" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_UMCBL","trackingNo": "6258224712558517"}'

Response

{
    "code":"00000",
    "data":{
        "trackingNo":6258224712558517,
        "result":true
    },
    "msg":"success",
    "requestTime":1627354109502
}

Response Description

Parameter Description
trackingNo Tracking order number
result Close result

Trader Modify TPSL

Limit rule 10 times/1s (uid)

HTTP Request

Request Parameter

Parameter Type Required Description
trackingNo Long Yes Order Id, From the /currentTrack in response the "trackingNo" field
symbol String Yes Symbol Id
stopProfitPrice BigDecimal No Take Profit Price
stopLossPrice BigDecimal No stop price

Request Example

curl -X POST "https://api.bitget.com/api/mix/v1/trace/modifyTPSL" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_UMCBL","trackingNo": "6258224712558517","stopProfitPrice":"24123.5","stopLossPrice":"21487.5"}'

Response

{
    "code": "00000",
    "msg": "success",
    "requestTime": 1656066841304,
    "data": 924176438170464256
}

Get Traders History Orders

Limit rule 10 times/1s (uid)

HTTP Request

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 Page size
pageNo int Yes Current page number

Request Example

curl "https://api.bitget.com/api/mix/v1/trace/historyTrack?startTime=1659406928000&endTime=1659414128000&pageSize=20&pageNo=1" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

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 Symbol Id
holdSide Position direction
openLeverage Opening leverage
openAvgPrice Average opening price
openTime Position opening time (milliseconds）
close Closing time (milliseconds)
closeAvgPrice Average closing price
stopType Stop 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/1s (uid) HTTP Request

Request Example

curl "https://api.bitget.com/api/mix/v1/trace/summary" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

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): the moment that calculated the yesterdaySplitProfit
sumProfit Cumulative profit
waitProfit Profits to be shared

Get Trader History Profit Summary (according to settlement currency)

Limit rule 20 times/1s (uid)

HTTP Request

Request Example

curl "https://api.bitget.com/api/mix/v1/trace/profitSettleTokenIdGroup" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

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/1s (uid)

HTTP Request

Request Example

curl "https://api.bitget.com/api/mix/v1/trace/profitDateGroupList" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

Response

{
    "code":"00000",
    "data":[
        {
            "settleTokenId":"USDT",
            "profit":"0",
            "date":1627354109502
        }
    ],
    "msg":"success",
    "requestTime":1627354109502
}

Response Description

Parameter Description
settleTokenId Settlement currency
profit Profit
date Date (milliseconds)

Get Trader History Profit Detail

Limit rule 20 times/2s (uid)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description
marginCoin String Yes Margin currency
date String Yes Profit sharing time
pageSize int Yes Page Size
pageNo int Yes Current page number

Request Example

curl "https://api.bitget.com/api/mix/v1/trace/profitDateList?marginCoin=USDT&date=1627354109502&pageSize=20&pageNo=1" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

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/1s (uid)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required Description
pageSize Integer Yes Page size
pageNo Integer Yes Current page number

Request Example

curl "https://api.bitget.com/api/mix/v1/trace/waitProfitDateList?pageSize=20&pageNo=1" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

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/1s (uid)

HTTP Request

Request Example

curl "https://api.bitget.com/api/mix/v1/trace/traderSymbols" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json"

Response

{
    "code":"00000",
    "data":[
        {
            "symbol": "BTCUSDT_UMCBL",
            "minOpenCount": "0.01",
            "openTrader": true
        }
    ],
    "msg":"success",
    "requestTime":1634723284625
}

Response Description

Parameter Description
symbolId Symbol Id
openTrader Whether enabled copy trading
minOpenCount Trader min open size

Trader Change CopyTrade symbol

Limit rule 10 Times/1s (uid)

HTTP Request

Request Param(Request Body)

Parameter name Type Required Description
symbol String Yes Symbol Id, symbol detailsymbol
operation String Yes Add or delete add delete

Request Example

curl -X POST "https://api.bitget.com/api/mix/v1/trace/setUpCopySymbols" \
  -H "ACCESS-KEY:you apiKey" \
  -H "ACCESS-SIGN:*******" \
  -H "ACCESS-PASSPHRASE:*****" \
  -H "ACCESS-TIMESTAMP:1659076670000" \
  -H "locale:en-US" \
  -H "Content-Type: application/json" \
  -d \'{"symbol": "BTCUSDT_UMCBL","operation": "add"}'

Response

{
    "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:

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

Subscription limit: 240 times per hour

If there’s a network problem, the system will automatically disconnect 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:

  1. Set a timer of 30 seconds.
  2. If the timer is triggered, send the String 'ping'.
  3. Expect a 'pong' as a response. If the response message is not received within 30 seconds, please raise an error and/or reconnect.
  4. The Websocket server accepts up to 10 messages per second. The message includes:
    • PING frame
    • Messages in JSON format, such as subscribe, unsubscribe.
  5. If the user sends more messages than the limit, the connection will be disconnected. IPs that are repeatedly disconnected may be blocked by the server;
  6. A single connection can subscribe up to 1000 Streams;
  7. A single IP can create up to 100 connections.

Login

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

passphrase: APIKey password

timestamp: the Unix Epoch time, the unit is seconds(--different from the signature timestamp of restAPI--)

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

Example of timestamp

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

Sign example

sign=CryptoJS.enc.Base64.Stringify(CryptoJS.HmacSHA256(timestamp +'GET'+'/user/verify', secretKey))

method: always 'GET'.

requestPath : always '/user/verify'

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

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

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 compare the timestamp.

Steps to generate the final signature:

Step 1. concat the content

Long timestamp = System.currentTimeMillis() / 1000;
String content = timestamp +"GET"+"/user/verify";

Step 1. Use the private key secretkey to encrypt the string to be signed with hmac sha256

String hash = hmac_sha256(content, secretkey)

The final step is to base64 encode the hash

String sign = base64.encode(hash)

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 and private .

Public channels -- include

Tickers channel

Candlesticks channel

Order book channel

Trades channel

etc -- do not require log in.

Private channels -- include

Account channel

Positions channel

Order channel

Plan order channel

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 subscribe channels
> instType String No Instrument Type MC：Perpetual contract public channel
> 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：Perpetual contract public channel
> 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：Perpetual contract public channel
> 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(order book) data.

Merging update data into snapshot

After subscribe to the channel (such as books 400 levels) of Order book , user first receive the initial snapshot of market depth. Afterwards the incremental update is subsequently received, user are responsible to update the snapshot from client side.

  1. If there are any levels with same price from the updates, compare the amount with the snapshot order book:

    If the amount is 0, delete this depth data.

    If the amount changes, replace the depth data.

  2. If there is no level in the snapshot with same price from the update, insert the update depth information into the snapshot sort by price (bid in descending order, ask in ascending order).

Calculate Checksum

Use the first 25 bids and asks in the local snapshot to build 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 local snapshot of market depth (only 2 levels of the orderbook are shown here, while 25 levels of orderbook should actually be intercepted):
    "bids": [
      [ 43231.1, 4 ],   //bid1
      [ 43231,   6 ]    //bid2
    ]
    "asks": [
      [ 43232.8, 9 ],   //ask1
      [ 43232.9, 8 ]    //ask2
    ]
Build the string to check CRC32:
"43231.1:4:43232.8:9:43231:6:43232.9:8"
The sequence:
"bid1[price:amount]:ask1[price:amount]:bid2[price:amount]:ask2[price:amount]"

2. Less than 25 levels of bid or ask
A local snapshot of market depth:
    "bids": [
      [ 3366.1, 7 ] //bid1
    ]
    "asks": [
      [ 3366.8, 9 ],    //ask1
      [ 3368  , 8 ],    //ask2
      [ 3372  , 8 ]     //ask3
    ]

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

Public Channels

Tickers Channel

Retrieve the latest traded price, bid price, ask price and 24-hour trading volume of the 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: Perpetual contract 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": "instType:MC,channel:ticker,instId:BTC-USDT doesn't exist"
}

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",
            "openUtc": "17088.5000000000000000",
            "chgUTC": "-0.00778",
            "symbolType": 1,
            "symbolId": "BTCUSDT_UMCBL",
            "deliveryPrice": "0",
            "bidSz": "10.344",
            "askSz": "3.024"
        }
    ]
}

Push data parameters

Parameter 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
>priceChangePercent 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 Market 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
>openUtc String Open price at UTC 00:00
>chgUTC String Price change since UTC 00:00
>symbolType String SymbolType: delivery: Settled Futures; perpetual: Perpetual Futures
>symbolId String Symbol Id
>deliveryPrice String Delivery price - 0 when SymbolType=perpetual
>bidSz String Best bid size
>askSz String Best ask size

Candlesticks Channel

Retrieve the candlesticks data of an instrument. Data will be pushed every 500 ms.

The channel will push a snapshot after successful subscribed, later on the updates will be pushed

If intended to query history data in a customized time range, please refer to Get Candle Data

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: Perpetual contract 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 - snapshot

{
    "action": "snapshot",
    "arg":{
        "instType":"mc",
        "channel":"candle1D",
        "instId":"BTCUSDT"
    },
    "data":[
        [
            "1639584000000",
            "8533.02",
            "8553.74",
            "8527.17",
            "8548.26",
            "45247"
        ]
    ]
}

Push Data Example - update

{
    "action": "update",
    "arg": {
        "instType": "mc",
        "channel": "candle1D",
        "instId": "BTCUSDT"
    },
    "data": [
        [
            "1665590400000",
            "19129",
            "19223.5",
            "19007.5",
            "19078.5",
            "67440.713"
        ]
    ]
}

Push data parameters**

Parameter Type Description
action String snapshot or update
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 base coin.

Order Book Channel

Subscribe order book data.

Use books for snapshot data, book5 for 5 depth levels,  book15 for 15 depth levels

Channel Length of bids Length of asks Remark
books maximum 200 maximum 200 Snapshot and update might return less than 200 bids/asks as per symbol's orderbook various from each other; The number of bids/asks is not a fixed value and may vary in the future
books1 1 1 Top 1 order book of "books" that begins from bid1/ask1
books5 5 5 Top 5 order book of "books" that begins from bid1/ask1
books15 15 15 Top 15 order book of "books" that begins from bid1/ask1

For example, if the whole order book consist of 20 bids and 12 asks

channel books return 20 bids and 12 asks

channel books1 return 1 bids and 1 asks, bids return index 19(index 19 is bid1), asks return index 0 

channel books5 return 5 bids and 5 asks, bids return from index 15 to 19(index 19 is bid1), asks return from index 0 to index 4

channel books15 return 15 bids index from 5 to 19(index 19 is bid1), and return 12 asks index from 0 to 11

Noted that bids are in descending order, while asks are in ascending order

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: Perpetual contract public channel
> channel String Yes Channel name, books , books1, books5, books15
> instId String Yes Instrument ID, BTCUSDT

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 array
> 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"] where "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: Perpetual contract public channel
> channel String Yes Channel Name，trade
> instId String Yes Instrument ID, BTCUSDT

Successful Response Example

{
    "event":"subscribe",
    "arg":[
        {
            "instType":"mc",
            "channel":"trade",
            "instId":"BTCUSDT"
        }
    ]
}

Failure Response Example

{
    "event":"error",
    "code":30003,
    "msg":"",
    "instType":"mc",
    "channel":"trade",
    "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 example

{
    "action": "snapshot",
    "arg": {
        "instType": "mc",
        "channel": "trade",
        "instId": "BTCUSDT"
    },
    "data": [
        [
            "1665645128291",
            "18991",
            "0.016",
            "buy"
        ],
        [
            "1665645128256",
            "18990.5",
            "0.241",
            "sell"
        ]
    ]
}

Push data parameters

Parameter Type Description
action String snapshot for the first push, afterwards push data will be update
arg Object Successfully subscribed channel
> instType String Instrument Type
> channel String Channel Name
> instId String Instrument ID
data Array Subscribed data String array
> ts String Filled time, Unix timestamp format in milliseconds
> px String Trade price
> sz String Trade size
> side String Trade direction, buy, sell

New Trades Channel

Retrieve the recent trades data. The first snapshot will push 50 trade records. Data will be pushed whenever there is a trade.

Request Example

{
    "op":"subscribe",
    "args":[
        {
            "instType":"mc",
            "channel":"tradeNew",
            "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: Perpetual contract public channel
> channel String Yes Channel Name，tradeNew
> instId String Yes Instrument ID, BTCUSDT

Successful Response Example

{
    "event":"subscribe",
    "arg":[
        {
            "instType":"mc",
            "channel":"tradeNew",
            "instId":"BTCUSDT"
        }
    ]
}

Failure Response Example

{
    "event":"error",
    "code":30003,
    "msg":"",
    "instType":"mc",
    "channel":"tradeNew",
    "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 example - snaphsot

{
  "data": [
    {
      "p": "20221.5",
      "c": "0.009",
      "ti": "969054894406951028",
      "ty": "sell",
      "ts": 1666766611672
    },
    {
      "p": "20221.5",
      "c": "1.100",
      "ti": "969054894406951026",
      "ty": "sell",
      "ts": 1666766611672
    }
  ],
  "arg": {
    "instType": "mc",
    "instId": "BTCUSDT",
    "channel": "tradeNew"
  },
  "action": "snapshot"
}

Push data example - update

{
  "data": [
    {
      "p": "20221.0",
      "c": "0.249",
      "ti": "969054896504102913",
      "ty": "buy",
      "ts": 1666766612172
    }
  ],
  "arg": {
    "instType": "mc",
    "instId": "BTCUSDT",
    "channel": "tradeNew"
  },
  "action": "update"
}

Push data parameters

Parameter Type Description
action String snapshot for the first push, afterwards push data will be update
arg Object Successfully subscribed channel
> instType String Instrument Type
> channel String Channel Name
> instId String Instrument ID
data Array Subscribed data String array
> ts String Filled time, Unix timestamp format in milliseconds
> p String Trade price
> c String Trade size
> ty String Trade direction, buy, sell
> ti String Trade ID

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

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 Parameter

Parameter Type Required Description
op String Yes Operation，subscribe unsubscribe
args Array Yes Subscribed channel
> instType String Yes Instrument Type UMCBL:USDT Perpetual Contract Private Channel; DMCBL:Coin Margin Perpetual Contract Private Channel; CMCBL: USDC margin Perpetual Contract Private Channel
> channel String Yes Channel name account
> instId String Yes Coin, please set to default

Successful Response Example

{
    "event":"subscribe",
    "arg":{
        "instType":"UMCBL",
        "channel":"account",
        "instId":"default"
    }
}

Failure Response Example

{
    "event": "error",
    "code": 30003,
    "msg": "instType:UMCBL,account: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 Symbol Name
code String No Error code
msg String No Error message

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
maxOpenPosAvailable String Max available to open position
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 Perpetual Contract Private Channel; DMCBL:Coin Margin Perpetual Contract Private Channel; CMCBL: USDC margin Perpetual Contract 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
> marginRate String Risk rate.
> 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 Perpetual Contract Private Channel; DMCBL:Coin Margin Perpetual Contract Private Channel; CMCBL: USDC margin Perpetual Contract 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

Plan Order Channel

Retrieve order information. Data will not be pushed when first subscribed. Data will only be pushed when triggered by events such as created/cancelled/modified/triggered.

Request Example

{
    "op": "subscribe",
    "args": [{
        "channel": "ordersAlgo",
        "instType": "UMCBL",
        "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，ordersAlgo
> instType String Yes Instrument Type UMCBL:USDT Perpetual Contract Private Channel; DMCBL:Coin Margin Perpetual Contract Private Channel; CMCBL: USDC margin Perpetual Contract Private Channel
> instId String No Symbol Name

Success

{
    "event": "subscribe",
    "arg": {
        "channel": "ordersAlgo",
        "instType": "UMCBL",
        "instId": "default"
    }
}

Fail

{
    "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 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
> id String order ID
> cOid String Client-supplied order ID
> triggerPx String trigger price
> planType String Websocket planType, null means 'pl'
> ordPx String actual price
> sz String trigger size
> actualSz String actual size
> ordType String Order Type market limit
> side String Order Side ，buy sell
> posSide String Position side long  or  short
> tgtCcy String Margin Coin
> status String Order status not_trigger triggered fail_trigger cancel
> 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
Existing positions + open orders bigger than 60. 45116 400
You are currently a trader, please close the position under the current order 40728 400
Duplicate clientOid 40757 400
Not enough position is available. 40786 400
service return an error 40725 400
Request timed out 40010 400
Parameter verification exception {0} 40808 400
The parameter {0} should not be null 40811 400
The condition {0} is not met 40812 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
console