English
NAV
console

Update log

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 business APIs by clicking the upper menu, and you can switch the document language by clicking the language button on the upper right.

On the right side of the document is an example of request parameters and response results.

Market Cooperation/Quantitative Market Maker

Users with excellent maker strategies and large trading volumes are welcome to participate in long-term market maker projects. Please provide the following information and send an email to:

  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 here:

FAQ

Quick Start

Access Preparation

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

You can click here to create an API Key.

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

The permissions are described as follows:

After the creation is successful, please remember the following information:

SDK/Code Example

open SDK（Recommended）

Java | Python | GoLang | NodeJs | PHP

Interface Type

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

Public Interface

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

Private Interface

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

The private interface needs to be verified with your APIKey.

Access Restriction

This chapter mainly focuses on access restrictions:

Rest API

If the APIKey is valid, you can use the APIKey to limit the speed; if not, use the public network IP to limit the speed.

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

Special note: When placing orders in batches, if 4 currency pairs are placed, 10 orders per currency pair will be counted as one request.

API Public Parameters

Side(Trade Direction)

Name Description
open_long Open long position
open_short Open short position
close_long Close long position
close_short Close short position

orderType(Trading Type)

Name Description
limit Limit order
market Market order

timeInForceValue(Order Validity Period)

Name Description
normal Normal order
post_only The order will remain valid until it is traded or cancelled
Ioc The part that cannot be traded immediately has been cancelled
fok Cannot be cancelled immediately

triggerType(Trigger Type)

Words Description
fill_price Triggered by strike price
market_price Triggered by mark price

planType(Limit Order Type)

Words Description
normal_plan Normal limit
profit_plan Take profit price
loss_plan Stop loss price

holdSide(Position Directon)

Words Description
long Long position
short Short position

marginMode(Position Mode)

Words Description
fixed Isolated margin
crossed Cross margin

holdMode(Position Mode)

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

status(Limit Order Status)

Words Description
no_trigger Not triggered
triggered Triggered
fail_trigger Triggered failed
cancel Cancelled

productType(Product Type )

Words Description
umcbl USDT Unified Contract
dmcbl Quanto Swap Contract
sumcbl USDT Unified Contract Analog disk
sdmcbl Quanto Swap Contract Analog disk

state(order status)

Words Description
new new order
partially_filled Partially Filled
filled Filled
canceled Canceled

isPlan

Words Description
plan plan order
profit_loss Tpsl order

granularity(candles interval)

API Domain Name

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

Domain Name REST API Recommended To Use
Domain 1 https://api.bitget.com Main Domain name
Domain 1 https://capi.bitget.com backup

API Verification

Initiate a request

The header of all REST requests must contain the following key：

Signature

The request header of ACCESS-SIGN is to timestamp + method.toUpperCase() + requestPath + "?" + queryString + body string (+ means string connection) encrypted with HMAC SHA256 method, passed* BASE64* encoded output.

Description of each field of the signature

The queryString as empty, signature format

timestamp + method.toUpperCase() + requestPath + body

The queryString not empty, signature format

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

For example

Get contract depth information, take cmt_btcusdt as an example:

Generate the string to be signed:

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

Contract order, take cmt_btcusdt as an example:

Generate the string to be signed:

'16273667805456POST/api/mix/v1/order/placeOrder{"symbol":"BTCUSDT_UMCBL","size":"8","side":"open_long","order_type":"limit","client_oid":"bitget#123456"}'

Steps to generate the final signature

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

Signature = hmac_sha256(secretkey, Message)

The second step is to base64 encode the Signature

Signature = base64.encode(Signature)

Request Interaction

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

Request Interaction Description

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 request signature is milliseconds. The timestamp of the request must be within 30 seconds of the API service time, otherwise the request will be considered expired and rejected. If there is a large deviation between the local server time and the API server time, we recommend that you update the http header by querying the API server time.

Frequency Limiting Rules

If the request is too frequent, the system will automatically limit the request and return the 429 too many requests status code in the http header.

Request Format

There are currently only two request methods in formats: GET and POST

RestAPI

Market

Get All Symbols

Limit rule: 20 times/1s (IP)

HTTP Request

Request Parameter(Request Param)

Parameter Name Parameter Type Required? Description
productType String Yes product type

Response

{
    "code":"00000",
    "data":[
        {
            "symbol":"BTCUSDT_UMCBL",
            "symbolName":"BTCUSDT",
            "makerFeeRate":"0.0004",
            "takerFeeRate":"0.0006",
            "feeRateUpRatio":"0.1",
            "openCostUpRatio":"0.1",
            "quoteCoin":"USDT",
            "baseCoin":"BTC",
            "buyLimitPriceRatio":"0.1",
            "sellLimitPriceRatio":"0.1",
            "supportMarginCoins":[
                "USDT"
            ],
            "minTradeNum":"0.0001",
            "priceEndStep":"1",
            "volumePlace":"4",
            "pricePlace":"1"
        }
    ],
    "msg":"success",
    "requestTime":1627114525850
}

Response Description

Parameter Description
symbol product Id
symbolName product name
baseCoin Base currency
quoteCoin Quote currency
buyLimitPriceRatio Buy price limit ratio 1%
sellLimitPriceRatio Sell price limit ratio 1%
feeRateUpRatio Rate of increase in handling fee%
makerFeeRate Market fee rate%
takerFeeRate Taker fee rate%
openCostUpRatio Percentage of increase in opening cost%
supportMarginCoins Support margin currency
minTradeNum Minimum number of openings
priceEndStep Price step
volumePlace Number of decimal places
pricePlace Price decimal places

Get Depth

Limit rule: 20 times/1s (IP)

HTTP Request

Request Parameter(Request Param)

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

Response

{
    "code":"00000",
    "data":{
        "asks":[
            [
                "30002",
                "0.2300000000000000"
            ],
            [
                "30002.5",
                "0.91"
            ],
            [
                "30003",
                "0.18"
            ]
        ],
        "bids":[
            [
                "29987",
                "0.28"
            ],
            [
                "300",
                "0.3333000000000000"
            ]
        ],
        "timestamp":"1627115809358"
    },
    "msg":"success",
    "requestTime":1627115809358
}

Get Single Symbol Ticker

Limit rule: 20 times/1s (IP)

HTTP Request

Request Parameter(Request Param)

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

Response

{
    "code":"00000",
    "data":{
        "symbol":"BTCUSDT_UMCBL",
        "last":"30002",
        "bestAsk":"30000.5",
        "bestBid":"30000",
        "high24h":"30002",
        "low24h":"30002",
        "timestamp":"1627115973334",
        "priceChangePercent":"0.15392308",
        "baseVolume":"68.4427",
        "quoteVolume":"1806816.7596",
        "usdtVolume":"1806816.7596"
    },
    "msg":"success",
    "requestTime":1627115973334
}

Response Description

Parameter Description
symbol Currency pair name
last Latest price
bestAsk Ask price
bestBid Bid price
high24h Highest price in 24 hours
low24h Lowest price in 24 hours
timestamp Timestamp (milliseconds)
priceChangePercent Price change (24 hours)
baseVolume Base currency trading volume
quoteVolume Quote currency trading volume
usdtVolume USDT transaction volume

Get All Symbol Ticker

Limit rule: 20 times/1s (IP)

HTTP Request

Request Parameter(Request Param)

Parameter Name Parameter Type Required? Description
productType String Yes product type

Response

{
    "code":"00000",
    "data":[
        {
            "symbol":"BTCUSDT_UMCBL",
            "last":"29990.5",
            "bestAsk":"30000.5",
            "bestBid":"30000",
            "high24h":"30007",
            "low24h":"30007",
            "timestamp":"1627116888108",
            "priceChangePercent":"0.15348077",
            "baseVolume":"73.4114",
            "quoteVolume":"1978178.35205",
            "usdtVolume":"1978178.35205"
        }
    ],
    "msg":"success",
    "requestTime":1627116888119
}

Response Description

Parameter Description
symbol Currency pair name
last Latest price
bestAsk Ask price
bestBid Bid price
high24h Highest price in 24 hours
low24h Lowest price in 24 hours
timestamp Timestamp (milliseconds)
priceChangePercent Price change (24 hours)
baseVolume Base currency trading volume
quoteVolume Quote currency trading volume
usdtVolume USDT transaction volume

Get Fills

Limit rule: 20 times/1s (IP)

HTTP Request

Request Parameter(Request Param)

Parameter Name Parameter Type Required? Description
symbol String Yes product Id (Must be capitalized)
limit String No Default number of rows is 100

Response Data 

{
    "code":"00000",
    "data":[
        {
            "tradeId":"802751431994691585",
            "price":"29990.5",
            "size":"0.0166",
            "side":"sell",
            "timestamp":"1627116776464",
            "symbol":"BTCUSDT_UMCBL"
        },
        {
            "tradeId":"802750695521046529",
            "price":"30007.0",
            "size":"0.0166",
            "side":"buy",
            "timestamp":"1627116600875",
            "symbol":"BTCUSDT_UMCBL"
        }
    ],
    "msg":"success",
    "requestTime":1627116936176
}

Get Candle Data

Limit rule: 20 times/1s (IP)

HTTP Request

Request Parameter(Request Param)

Parameter Name Parameter Type Required? Description
symbol String Yes product Id (Must be capitalized)
granularity String Yes Types of candlestick
startTime String Yes Start time (Timestamp ms)
endTime String Yes End time (Timestamp ms）

Response

[
    [
        "1627008780000",
        "24016.0000000000000000",
        "24016.0000000000000000",
        "24016.0000000000000000",
        "24016.0000000000000000",
        "0.000000000000",
        "0.000000000000"
    ],
    [
        "1627008840000",
        "24016.0000000000000000",
        "24016.0000000000000000",
        "24016.0000000000000000",
        "24016.0000000000000000",
        "0.000000000000",
        "0.000000000000"
    ]
]

Response Description

Parameter
Timestamp
Opening price
Highest price
Lowest price
Closing price
Base currency trading volume
Quote currency trading volume

Get Symbol Index Price

Limit rule: 20 times/1s (IP)

HTTP Request

Request Parameter(Request Param)

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

Response

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

Response Description

Parameter Description
symbol Currency pair name (Must be capitalized)
index Index price
timestamp Timestamp

Get Symbol Next Funding Time

Limit rule: 20 times/1s (IP)

HTTP Request

Request Parameter(Request Param)

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

Response

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

Response Description

Parameter Description
symbol Currency pair name
fundingTime Next settlement time

Get History Funding Rate

Limit rule: 20 times/1s (IP)

HTTP Request

Request Parameter(Request Param)

Parameter Name Parameter Type Required? Description
symbol String Yes product Id (Must be capitalized)
pageSize int No Page Size Default 20
pageNo int No Page No
nextPage Boolean No Whether to query the next page default false

Response

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

Response Description

Parameter Description
symbol Currency pair name
fundingRate Current funding rate
settleTime Settlement time

Get Current Funding Rate

Limit rule: 20 times/1s (IP)

HTTP Request

Request Parameter(Request Param)

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

Response

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

Response Description

Parameter Description
symbol Currency pair name
fundingRate Current funding rate

Get Open Interest

Limit rule: 20 times/1s (IP)

HTTP Request

Request Parameter(Request Param)

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

Response

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

Response Description

Parameter Description
symbol Currency pair name
amount Total platform position
timsetamp Timestamp (milliseconds)

Get Symbol Mark Price

Limit rule: 20 times/1s (IP)

HTTP Request

Request Parameter(Request Param)

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

Response

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

Response Description

Parameter Description
symbol Currency pair name
markPrice Mark price
timsetamp Timestamp (milliseconds)

Get Symbol Leverage

Limit rule: 20次/1s (IP)

HTTP Request

Request Parameter(Request Param)

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

Success Response

{
    "code":"00000",
    "data":{
        "symbol":"BTCUSDT_UMCBL",
        "minLeverage":"1",
        "maxLeverage":"125"
    },
    "msg":"success",
    "requestTime":1627292076687
}

Response Description

Parameter Description
symbol symbol id
minLeverage min leverage
maxLeverage max leverage

Account

Get Single Account

Limit rule: 20 times/2s (uid)

HTTP Request

Request Parameter

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

Response

{
    "code":"00000",
    "data":{
        "marginCoin":"USDT",
        "locked":0,
        "available":13168.86110692,
        "crossMaxAvailable":13168.86110692,
        "fixedMaxAvailable":13168.86110692,
        "maxTransferOut":13168.86110692,
        "equity":13178.86110692,
        "usdtEquity":13178.861106922,
        "btcEquity":0.344746495477,
        "crossRiskRate":0,
        "crossMarginLeverage":20,
        "fixedLongLeverage":20,
        "fixedShortLeverage":20,
        "marginMode":"crossed",
        "holdMode":"double_hold"
    },
    "msg":"success",
    "requestTime":1627292199523
}

Response Description

Parameter Description
marginCoin Margin currency
locked Locked amount (margin currency)
available Number of accounts available
crossMaxAvailable The maximum open position balance available for the whole position (margin currency)
fixedMaxAvailable The maximum isolated margin can be used to open a position (margin currency)
maxTransferOut Maximum transferable
equity Account equity (margin currency)
usdtEquity Convert USDT account equity
btcEquity Convert BTC account equity
crossRiskRate Risk ratio at full position
crossMarginLeverage Leverage level for full position
fixedLongLeverage Long leverage with isolated margin
fixedShortLeverage Short leverage with isolated margin
marginMode Margin mode
holdMode Hold position mode

Get Account List

Limit rule: 20 times/2s (uid)

HTTP Request

Request Parameter

Parameter Name Parameter Type Required? Description
productType String Yes product type

Response

{
    "code":"00000",
    "data":[
        {
            "marginCoin":"USDT",
            "locked":"0.31876482",
            "available":"10575.26735771",
            "crossMaxAvailable":"10580.56434289",
            "fixedMaxAvailable":"10580.56434289",
            "maxTransferOut":"10572.92904289",
            "equity":"10582.90265771",
            "usdtEquity":"10582.902657719473",
            "btcEquity":"0.204885807029"
        }
    ],
    "msg":"success",
    "requestTime":1630901215622
}

Response Description

Parameter Description
marginCoin Margin currency
locked Locked amount (margin currency)
available Number of accounts available
crossMaxAvailable The maximum open position balance available for the whole position (margin currency)
fixedMaxAvailable The maximum isolated margin can be used to open a position (margin currency)
maxTransferOut Maximum transferable
equity Account equity (margin currency)
usdtEquity Convert USDT account equity
btcEquity Convert BTC account equity

Get Open Count

Limit rule: 20 times/1s (IP)

This interface is only used to calculate the maximum number of positions that can be opened when the user does not hold a position by default. The result does not represent the actual number of positions opened.

HTTP Request

Request Parameter(Request Body)

Parameter Name Parameter Type Required? Description
symbol String Yes product Id (Must be capitalized)
marginCoin String Yes Margin currency (Must be capitalized)
openPrice BigDecimal Yes Opening price
leverage BigDecimal No Default leverage is 20
openAmount BigDecimal Yes Opening amount

Response

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

Change Leverage

Limit rule: 5 times/2s (uid)

HTTP Request

Request Parameter(Request Body)

Parameter Name Parameter Type Required? Description
symbol String Yes product Id (Must be capitalized)
marginCoin String Yes Margin currency (Must be capitalized)
leverage String Yes Leverage
holdSide String No Position direction (the whole position is not transmitted）

Response

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

Response Description

Parameter Description
symbol Currency pair name
marginCoin Margin currency
longLeverage Long leverage
shortLeveage Short leverage
marginMode Margin Mode

Change Margin

Limit rule: 5 times/2s (uid)

HTTP Request

Request Parameter(Request Body)

Parameter Name Parameter Type Required? Description
symbol String Yes product Id (Must be capitalized)
marginCoin String Yes Margin currency (Must be capitalized)
amount String Yes margin amount
holdSide String No Position direction (the whole position is not transmitted

Response

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

Change Margin Mode

Limit rule: 5 times/2s (uid)

HTTP Request

Request Parameter(Request Body)

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

Response

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

Response Description

Parameter Description
symbol Currency pair name
marginCoin Margin currency
longLeverage Long leverage
shortLeveage Short leverage
marginMode Margin mode

Get Symbol Position

Limit rule: 20 times/2s (uid)

HTTP Request

Request Parameter(Request Param)

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

Response

{
    "code":"00000",
    "data":[
        {
            "marginCoin":"USDT",
            "symbol":"BTCUSDT_UMCBL",
            "holdSide":"long",
            "openDelegateCount":"0",
            "margin":"10",
            "available":"0",
            "locked":"0",
            "total":"0",
            "leverage":25,
            "achievedProfits":"0",
            "averageOpenPrice":"0",
            "marginMode":"fixed",
            "holdMode":"double_hold",
            "unrealizedPL":"0",
            "keepMarginRate":"0.015",
            "ctime":"1626232130664"
        }
    ],
    "msg":"success",
    "requestTime":1627293612502
}

Response Description

Parameter Description
symbol Currency pair name
marginCoin Margin currency
holdSide Position direction
openDelegateCount Number of positions opened (trading currency)
margin Margin quantity (margin currency)
available Position available (Quote currency)
locked Position freeze (Quote currency)
total Total position (available + locked)
leverage Leverage
achievedProfits Realized profit and loss
averageOpenPrice Average opening price
marginMode Margin mode
holdMode Position mode
unrealizedPL Unrealized profit and loss
keepMarginRate keep margin rate
cTime Last update time Timestamp milliseconds

Get All Position

Limit rule: 5 times/2s (uid)

HTTP Request

Request Parameter(Request Param)

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

Response

{
    "code":"00000",
    "data":[
        {
            "marginCoin":"USDT",
            "symbol":"BTCUSDT_UMCBL",
            "holdSide":"long",
            "openDelegateCount":"0",
            "margin":"10",
            "available":"0",
            "locked":"0",
            "total":"0",
            "leverage":25,
            "achievedProfits":"0",
            "averageOpenPrice":"0",
            "marginMode":"fixed",
            "holdMode":"double_hold",
            "unrealizedPL":"0",
            "keepMarginRate":"0",
            "ctime":"1626232130664"
        }
    ],
    "msg":"success",
    "requestTime":1627293612502
}

Response Description

Parameter Description
symbol Currency pair name
marginCoin Margin currency
holdSide Position direction
openDelegateCount Number of positions opened (trading currency)
margin Margin quantity (margin currency)
available Position available (Quote currency)
locked Position freeze (Quote currency)
total Total position (available + locked)
leverage Leverage
achievedProfits Realized profit and loss
averageOpenPrice Average opening price
marginMode Margin mode
holdMode Position mode
unrealizedPL Unrealized profit and loss
keepMarginRate keep margin rate
cTime Last update time Timestamp milliseconds

Get Account Bill

Limit rule: 10次/1s (uid)

HTTP Request

Request (Request Param)

Parameter type required description
symbol String Yes Symbol Id
marginCoin String Yes margin coin
startTime String Yes Start Time （timestamp mills）
endTime String Yes end time (timestamp mills）
pageSize int No page size, default 20, max is 100
lastEndId String No last end id
next boolean No Is query next page? default false

Response

{
  "code": "00000",
  "msg": "success",
  "data": {
    "result": [
      {
        "id": "892962903462432768",
        "symbol": "ETHUSDT_UMCBL",
        "marginCoin": "USDT",
        "amount": "0",
        "fee": "-0.1765104",
        "feeByCoupon": "",
        "feeCoin": "USDT",
        "business": "open_long",
        "ctime": "1648624867354"
      }
    ],
    "endId": "885353495773458432",
    "nextFlag": false,
    "preFlag": false
  }
}

Response params

Parameter Description
id record no
symbol Symbol Id
marginCoin margin Coin
amount change amount
fee fee
feeByCoupon fee deduction coupon
feeCoin fee coin
business type
cTime create time
lastEndId last end id

Trade

Place Order

Limit rule: 10 times/1s (uid)

HTTP Request

Request Parameter(Request Body)

Parameter Name Parameter Type Required? Description
symbol String Yes product Id
marginCoin String Yes Margin currency
size String Yes Order quantity (not transmitted at market price)
price String No Order price (not transmitted at market price)
side String Yes Order direction
orderType String Yes Order type
timeInForceValue String No Order validity period
clientOid String No Client ID is unique
presetTakeProfitPrice String No Preset take profit price
presetStopLossPrice String No Preset stop loss price

Response Data 

{
    "code":"00000",
    "data":{
        "orderId":"1627293504612",
        "clientOid":"BITGET#1627293504612"
    },
    "msg":"success",
    "requestTime":1627293504612
}

Response Description

Parameter Description
orderId Order Id
clientOid Client custom Id

Batch Order

Limit rule: 10 times/1s (uid)

HTTP Request

Request Parameter(Request Body)

Parameter Name Parameter Type Required? Description
symbol String Yes product Id (Must be capitalized)
marginCoin String Yes Margin currency (Must be capitalized)
orderDataList List Yes Order data list

orderDataList

Parameter Name Parameter Type Required? Description
size String Yes Order quantity
price String No Order price
side String Yes Order direction
orderType String Yes Order type
timeInForceValue String No Order validity period
clientOid String No Client ID is unique

Response

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

Response Description

Parameter Description
orderId Order Id
clientOid Client custom Id

Cancel Order

Limit rule: 10 times/1s (uid)

HTTP Request

Request Parameter(Request Body)

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

Response

{
    "code":"00000",
    "data":{
        "orderId":"1627293504612",
        "clientOid":"BITGET#1627293504612"
    },
    "msg":"success",
    "requestTime":1627293504612
}

Response Description

Parameter Description
orderId Order Id
clientOid Client custom Id

Batch Cancel Order

Limit rule: 10 times/1s (uid)

HTTP Request

Request Parameter(Request Body)

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

Response

{
  "code": "00000",
  "data": {
    "symbol": "BTCUSDT_UMCBL",
    "order_ids": [
      "1627293504612"
    ],
    "fail_infos": [
      {
        "order_id": "",
        "err_code": "",
        "err_msg": ""
      }
    ]
  },
  "msg": "success",
  "requestTime": 1627293504612
}

Response Description

Parameter Description
orderId Order Id
clientOid Client custom Id

Get Open Order

Limit rule: 20 times/2s (uid)

HTTP Request

Request Parameter(Request Param)

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

Response

{
    "code":"00000",
    "data":{
        [
            {
                "symbol":"BTCUSDT_UMCBL",
                "size":1,
                "orderId":"802382049422487552",
                "clientOid":"RFIut#1627028708738",
                "filledQty":0,
                "fee":0,
                "price":23999.3,
                "state":"canceled",
                "side":"open_long",
                "timeInForce":"normal",
                "totalProfits":0,
                "posSide":"long",
                "marginCoin":"USDT",
                "ctime":1627028708807
            }
        ]
    },
    "msg":"success"
}

Response Description

Parameter Description
symbol Trading pair name
size Order size
orderId Order Id
clientOid Client custom id
filledQty Transaction volume
fee Transaction fee
price Order price
state Order status
side Order direction
timeInForce Order validity period
totalProfits Total profit and loss
posSide Position direction
marginCoin Margin currency
cTime Last update time

Get History Orders

Limit rule: 20 times/2s (uid)

HTTP Request

Request Parameter(Request Param)

Parameter Name Parameter Type Required? Description
symbol String Yes product Id (Must be capitalized)
startTime String Yes Start time (timestamp)
endTime String Yes End time (time stamp)
pageSize String Yes Number of queries
lastEndId String No Last query orderId
isPre Boolean No Whether to query the previous page (default false)

Response

{
    "code":"00000",
    "data":{
        [
            {
                "symbol":"BTCUSDT_UMCBL",
                "size":1,
                "orderId":"802382049422487552",
                "clientOid":"RFIut#1627028708738",
                "filledQty":0,
                "fee":0,
                "price":23999.3,
                "state":"canceled",
                "side":"open_long",
                "timeInForce":"normal",
                "totalProfits":0,
                "posSide":"long",
                "marginCoin":"USDT",
                "ctime":1627028708807
            }
        ]
    },
    "msg":"success"
}

Response Description

Parameter Description
symbol Trading pair name
size Order size
orderId Order Id
clientOid Client custom id
filledQty Transaction volume
fee Transaction fee
price Order price
state Order status
side Order direction
timeInForce Order validity period
totalProfits Total profit and loss
posSide Position direction
marginCoin Margin currency
cTime Last update time

Get Order Details

Limit rule: 20 times/2s (uid)

HTTP Request

Request Parameter (Request Param)

Parameter Name Parameter Type Required? Description
symbol String Yes product Id (Must be capitalized)
orderId String Yes Order Id

Response

{
    "code":"00000",
    "data":{
        "symbol":"BTCUSDT_UMCBL",
        "size":1,
        "orderId":"802382049422487552",
        "clientOid":"RFIut#1627028708738",
        "filledQty":0,
        "priceAvg":0,
        "fee":0,
        "price":23999.3,
        "state":"canceled",
        "side":"open_long",
        "timeInForce":"normal",
        "totalProfits":0,
        "posSide":"long",
        "marginCoin":"USDT",
        "presetTakeProfitPrice":69582.5,
        "presetStopLossPrice":21432.5,
        "filledAmount":45838,
        "orderType":"limit",
        "cTime":1627028708807,
        "uTime":1627028717807
    },
    "msg":"success",
    "requestTime":1627300098776
}

Response Description

Parameter Description
symbol Trading pair name
size Order size
orderId Order Id
clientOid Client custom id
filledQty Transaction volume
priceAvg Transaction price
fee Transaction fee
price Order price
state Order status
side Order direction
timeInForce Order validity period
totalProfits Total profit and loss
posSide Position direction
marginCoin Margin currency
cTime create time
presetTakeProfitPrice Preset take profit price

Get Order fill detail

Limit rule: 20 times/2s (uid)

HTTP Request

Request Parameter (Request Param)

Parameter Type Required Description
symbol String Yes product Id (Must be capitalized)
orderId String No Order Id
startTime String No Start time (timestamp in milliseconds) This field is required if querying all details
endTime String No End time (timestamp in milliseconds) This field is required if querying all details
lastEndId String No Query the data after this tradeId

Response Data

{
    "code":"00000",
    "data":[
        {
            "tradeId":"802377534023585793",
            "symbol":"BTCUSDT_UMCBL",
            "orderId":"802377533381816325",
            "price":"0",
            "sizeQty":"0.3247",
            "fee":"0E-8",
            "side":"burst_close_long",
            "ctime":"1627027632241"
        }
    ],
    "msg":"success",
    "requestTime":1627386245672
}

Response Description

Parameter Description
tradeId Trade Id
symbol Trading pair name
orderId Order Id
price Transaction price
sizeQty Transaction volume
fee Transaction fee
side Trade type
cTime Trade time

Place Plan order

Limit rule: 10 times/1s (uid)

HTTP Request

Request Parameter (Request Body)

Parameter Name Parameter Type Required? Description
symbol String Yes product Id (Must be capitalized)
marginCoin String Yes Margin currency (Must be capitalized)
size String Yes Order quantity (not transmitted at market price)
executePrice String No Strike price
triggerPrice String Yes Trigger price
side String Yes Order Side
orderType String Yes Order Type
triggerType String Yes Trigger type
clientOid String No Client ID is unique within 24 hours
presetTakeProfitPrice String No Preset take profit price
presetStopLossPrice String No Preset stop price

Response

{
    "code":"00000",
    "data":{
        "clientOid":"RFIut#1627300490884",
        "orderId":"803521986049314816"
    },
    "msg":"success",
    "requestTime":1627300490899
}

Response Description

Parameter Description
clientOid Client custom Id
orderId Order Id

Modify Plan Order

Limit rule: 10 times/1s (uid)

HTTP Request

Request Parameter (Request Body)

Parameter Name Parameter Type Required? Description
orderId String Yes Limit order Id
marginCoin String Yes Margin currency
symbol String Yes Currency pair name
executePrice String No Strike price
triggerPrice String Yes Trigger price
triggerType String Yes Trigger type
orderType String Yes Trading Type

Response

{
    "code":"00000",
    "data":{
        "clientOid":"RFIut#1627300490884",
        "orderId":"803521986049314816"
    },
    "msg":"success",
    "requestTime":1627300490899
}

Response Description

Parameter Description
clientOid Client custom Id
orderId Order Id

Modify Plan Order TPSL

Limit rule: 10 times/1s (uid)

HTTP Request

Request Parameter (Request Body)

Parameter Name Parameter Type Required? Description
orderId String Yes Limit order Id
marginCoin String Yes Margin currency (Must be capitalized)
symbol String Yes product Id (Must be capitalized)
presetTakeProfitPrice String No Take profit price If it is empty, cancel and take profit
presetStopLossPrice String No Stop loss price If it is empty, cancel the stop loss

Response

{
    "code":"00000",
    "data":{
        "clientOid":"RFIut#1627300490884",
        "orderId":"803521986049314816"
    },
    "msg":"success",
    "requestTime":1627300490899
}

Response Description

Parameter Description
clientOid Client custom Id
orderId Order Id

Place Stop Order

Limit rule: 10 times/1s (uid)

At present, take-profit and stop-loss orders are only supported at market price, and the trigger type is transaction trigger price

HTTP Request

Request Parameter(Request Body)

Parameter Name Parameter Type Required? Description
marginCoin String Yes Margin currency (Must be capitalized)
symbol String Yes product Id (Must be capitalized)
planType String Yes Take-profit and stop-loss type
triggerPrice String No Trigger price
holdSide String No Whether this position is long or short
size String No Order Quantity Default Position Quantity

Response

{
    "code":"00000",
    "data":{
        "clientOid":"RFIut#1627300490884",
        "orderId":"803521986049314816"
    },
    "msg":"success",
    "requestTime":1627300490899
}

Response Description

Parameter Description
clientOid Client custom Id
orderId Order Id

Modify Stop Order

Limit rule: 10 times/1s (uid)

HTTP Request

Request Parameter(Request Body)

Parameter Name Parameter Type Required? Description
orderId String Yes Take-profit and stop-loss order Id
marginCoin String Yes Margin currency (Must be capitalized)
symbol String Yes product Id (Must be capitalized)
triggerPrice String No Trigger price

Response

{
    "code":"00000",
    "data":{
        "clientOid":"RFIut#1627300490884",
        "orderId":"803521986049314816"
    },
    "msg":"success",
    "requestTime":1627300490899
}

Response Description

Parameter Description
clientOid Client custom Id
orderId Order Id

Cancel Plan Order (TPSL)

Limit rule: 10 times/1s (uid)

HTTP Request

Request Parameter(Request Body)

Parameter Name Parameter Type Required? Description
orderId String Yes Limit order Id
symbol String Yes product Id (Must be capitalized)
planType String Yes Cancellation type

Response

{
    "code":"00000",
    "data":{
        "clientOid":"RFIut#1627300490884",
        "orderId":"803521986049314816"
    },
    "msg":"success",
    "requestTime":1627300490899
}

Response Description

Parameter Description
clientOid Client custom Id
orderId Order Id

Get Plan Order (TPSL) List

Limit rule: 20 times/2s (uid)

HTTP Request

Request Parameter(Request Param)

Parameter Name Parameter Type Required? Description
symbol String Yes product Id (Must be capitalized)
isPlan String No Query type

Response

{
    "code":"00000",
    "data":[
        {
            "orderId":"803521986049314816",
            "symbol":"BTCUSDT_UMCBL",
            "marginCoin":"USDT",
            "size":"1",
            "executePrice":"38923.1",
            "triggerPrice":"45000.3",
            "status":"not_trigger",
            "orderType":"limit",
            "planType":"normal_plan",
            "side":"open_long",
            "triggerType":"fill_price",
            "presetTakeProfitPrice":"0",
            "presetTakeLossPrice":"0",
            "ctime":"1627300490867"
        }
    ],
    "msg":"success",
    "requestTime":1627354109502
}

Response Description

Parameter Description
orderId Order Id
symbol Currency pair name
marginCoin Margin currency
size Order size
executePrice Order price
triggerPrice Trigger price
status Order status
orderType Trade type
planType Order type
side Order direction
triggerType Trigger type
presetTakeProfitPrice Preset take profit price
presetTakeLossPrice Preset stop loss price
ctime Order creation time

Get History Plan Orders (TPSL)

Limit rule: 20 times/2s (uid)

HTTP Request

Request Parameter (Request Param)

Parameter Name Parameter Type Required? Description
symbol String Yes product Id (Must be capitalized)
startTime String Yes Start time
endTime String Yes End time
pageSize Integer No Number of queries default 100
isPre boolean No Whether to query the previous page
isPlan String No Query type

Response

{
    "code":"00000",
    "data":[
        {
            "orderId":"803521986049314816",
            "executeOrderId":"84271931884910",
            "symbol":"BTCUSDT_UMCBL",
            "marginCoin":"USDT",
            "size":"1",
            "executePrice":"38923.1",
            "triggerPrice":"45000.3",
            "status":"not_trigger",
            "orderType":"limit",
            "planType":"normal_plan",
            "side":"open_long",
            "triggerType":"fill_price",
            "presetTakeProfitPrice":"0",
            "presetTakeLossPrice":"0",
            "ctime":"1627300490867"
        }
    ],
    "msg":"success",
    "requestTime":1627354109502
}

Response Description

Parameter Description
orderId Order Id
executeOrderId Execute success Order Id
symbol Currency pair name
marginCoin Margin currency
size Order size
executeSize execute Size
executePrice Order price
triggerPrice Trigger price
status Order status
orderType Trade type
planType Order type
side Order direction
triggerType Trigger type

CopyTrade

Get Trader Open order

Limit rule 20 times/2s (uid)

HTTP Request

Request Parameter(Request Param)

Parameter Name Parameter Type Required? Description
symbol String Yes product Id (Must be capitalized)
productType String Yes product type
pageSize int Yes Number of queries
pageNo int Yes Current page number

Response

{
    "code":"00000",
    "data":[
        {
            "symbol":"BTCUSDT_UMCBL",
            "trackingNo":"699848017573842632",
            "openOrderId":"4839999132328",  
            "holdSide":"long",
            "openLeverage":20,
            "avgOpenPrice":11451.5,
            "openTime":1602582690614,
            "openDealCount":"10",
            "stopProfitPrice":"123.14",
            "stopLossPrice":"20.52"
        }
    ],
    "msg":"success",
    "requestTime":1627354109502
}

Response Description

Parameter Description
trackingNo Tracking order number
openOrderId Trader’s order number This order number cannot be used when the trader closes a position, and a tracking order number is required
symbol Trading pair name
holdSide Current position direction
openLeverage Opening leverage
avgOpenPrice Average opening price
openTime Position opening time (milliseconds)
openDealCount Number of positions opened
stopProfitPrice Take profit price
stopLossPrice Stop price

Get Followers Open Order

Limit rule 20 times/2s (uid)

HTTP Request

Request Parameter(Request Param)

Parameter Name Parameter Type Required? Description
symbol String Yes product Id (Must be capitalized)
productType String Yes product type
pageSize int Yes Number of queries
pageNo int Yes Current page number

Response

{
    "code":"00000",
    "data":[
        {
            "trackingNo":"804641389214179330",
            "openOrderId":"804641382428463106",
            "closeOrderId":"",
            "symbol":"BTCUSDT_UMCBL",
            "holdSide":"short",
            "openLeverage":47,
            "openAvgPrice":39827,
            "openTime":1627567376984,
            "openDealCount":"0.0010000000000000",
            "openMargin":"21",
            "averageClosePrice":0,
            "closeDealCount":"0.0000000000000000",
            "closeTime":0
        }
    ],
    "msg":"success",
    "requestTime":1634107646972
}

Response Description

Parameter Description
trackingNo Tracking order number
openOrderId Open Position Order Id
closeOrderId Close Position Order Id
symbol Trading pair name
holdSide Current position direction
openLeverage Opening leverage
openAvgPrice Average opening price
openTime Position opening time (milliseconds)
openDealCount Number of positions opened
openMargin Open
averageClosePrice Average Close Price
closeDealCount Close Count
closeTime Close Position Time (milliseconds)

Trader Close Position

Limit rule 10 times/1s (uid)

HTTP Request

Request Parameter (Request Body)

Parameter Name Parameter Type Required? Description
symbol String Yes product Id (Must be capitalized)
trackingNo String Yes Order Id From the /currentTrack "trackingNo" field

Response

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

Response Description

Parameter Description
trackingNo Tracking order number
result Tracking order number

Get Traders History Orders

Limit rule 20 times/2s (uid)

HTTP Request

Request Parameter (Request Param)

Parameter Name Parameter Type Required? Description
startTime String Yes Start time timestamp (milliseconds)
endTime String Yes End time timestamp (milliseconds)
pageSize int Yes Number of queries
pageNo int Yes Current page number

Response

{
    "code":"00000",
    "data":[
        {
            "symbol":"BTCUSDT_UMCBL",
            "trackingNo":"682799071840175632",
            "holdSide":"long",
            "openLevel":20,
            "openAvgPrice":"11366.50",
            "openTime":1627356444000,
            "closeDealCount":"10",
            "closeTime":1626838044000,
            "closeAvgPrice":"11272.00",
            "stopType":"profit",
            "achievedProfits":"-0.07650000",
            "openFee":"-0.00680910",
            "closeFee":"0.000000"
        }
    ],
    "msg":"success",
    "requestTime":1627354109502
}

Response Description

Parameter Description
trackingNo Tracking order number
symbol Trading pair name
holdSide Current position direction
openLeverage Opening leverage
openAvgPrice Average opening price
openTime Position opening time (milliseconds）
close Closing time (milliseconds)
closeAvgPrice Average closing price
stopType Closing type
achievedProfits Realized profit and loss
openFee Opening fee
closeFee Closing fee
closeDealCount Number of closed Positions

Get Trader Profit Summary

Limit rule 20 times/2s (uid) HTTP Request

Response

{
    "code":"00000",
    "data":{
        "yesterdaySplitProfit":"0",
        "sumProfit":"0",
        "waitProfit":"0",
        "yesterdayTimeStamp":"1627354109502"
    },
    "msg":"success",
    "requestTime":1627354109502
}

Response Description

Parameter Description
yesterdaySplitProfit Yesterday's Profit Sharing (Trader)
yesterdayTimeStamp Yesterday's profit sharing time (milliseconds)
sumProfit Cumulative profit
waitProfit Profits to be shared

Get Trader History Profit Summary (according to settlement currency)

Limit rule 20 times/2s (uid)

HTTP Request

Response

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

Response Description

Parameter Description
settleTokenId Settlement currency
profit Profit

Get Trader History Profit Summary (according to settlement currency and date)

Limit rule 20 times/2s (uid)

HTTP Request

Response

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

Response Description

Parameter Description
settleTokenId Settlement currency
profit Porfit
date Margin time (milliseconds)

Get Trader Histroy Profit Detail

Limit rule 20 times/2s (uid)

HTTP Request

Request Parameter(Request Param)

Parameter Name Parameter Type Required? Description
marginCoin String Yes Margin currency
date String Yes Profit sharing time
pageSize int Yes Number of queries
pageNo int Yes Current page number

Response

{
    "code":"00000",
    "data":[
        {
            "settleTokenId":"usdt",
            "profit":"0",
            "nickName":"bitget"
        }
    ],
    "msg":"success",
    "requestTime":1627354109502
}

Response Description

Parameter Description
settleTokenId Settlement currency
profit Profit has been shared
nickName Nickname

Get Trader Profits Details

Limit rule 20 times/2s (uid)

HTTP Request

Request Parameter(Request Param)

Parameter Name Parameter Type Required? Description
pageSize int Yes Number of queries
pageNo int Yes Current page number

Response

{
    "code":"00000",
    "data":[
        {
            "settleTokenId":"usdt",
            "profit":"0",
            "nickName":"bitget"
        }
    ],
    "msg":"success",
    "requestTime":1627354109502
}

Response Description

Parameter Description
settleTokenId Settlement currency
profit Profit
nickName Nickname

Get CopyTrade Symbols

Limit rule 20 Times/2s (uid)

HTTP Request

Response

{
    "code":"00000",
    "data":[
        {
            "symbol":"BTCUSDT",
            "openTrader":true
        },
            "symbol":"BTCUSD",
            "openTrader":false
        }
    ],
    "msg":"success",
    "requestTime":1634723284625
}

Response Description

Parameter Description
symbolId Symbol Id
openTrade Whether to open copy trade

Trader Change CopyTrade symbol

Limit rule 10 Times/1s (uid)

HTTP Request

Request Param(Request Body)

Parameter name Type Required Desciption
symbol String Yes Symbol Id /contracts symbol
operation String Yes Add or delete add delete

返回数据

{
    "code":"00000",
    "data":"",
    "msg":"success",
    "requestTime":1627354109502
}

WebSocketAPI

Overview

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

It is strongly recommended that developers use WebSocket API to obtain market information and transaction depth. ​

domain WebSocket API Recommended to use
domain 1 wss://ws.bitget.com/mix/v1/stream internationality

Connect

Connection instructions:

Connection limit: 1 time per second

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

Subscription limit: 240 times per hour

If there’s a network problem, the system will automatically disable the connection.

The connection will break automatically if the subscription is not established or data has not been pushed for more than 30 seconds.

To keep the connection stable:

  1. Set a timer of N seconds whenever a response message is received, where N is less than 30.
  2. If the timer is triggered, which means that no new message is received within N seconds, send the String 'ping'.
  3. Expect a 'pong' as a response. If the response message is not received within N seconds, please raise an error or reconnect.

Login

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

passphrase: APIKey password

timestamp: the Unix Epoch time, the unit is seconds

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

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

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

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

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

method: always 'GET'.

requestPath : always '/user/verify'

The request will expire 30 seconds after the timestamp. If your server time differs from the API server time, we recommended using the REST API to query the API server time and then set the timestamp.

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

Steps to generate the final signature:

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

Signature = hmac_sha256(secretkey, Message)

The second step is to base64 encode the Signature

Signature = base64.encode(Signature)

If login fails, it will automatically disconnect

Request format description

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

Request Example

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

Successful Response Example

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

Failure Response Example

{
    "event":"error",
    "code":"30005",
    "msg":"error"
}

Subscribe

Subscription Instructions

Request format description

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

WebSocket channels : public .

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

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

Request Example

{
    "op":"subscribe",
    "args":[
        {
            "instType":"mc",
            "channel":"ticker",
            "instId":"BTCUSDT"
        },
        {
            "instType":"mc",
            "channel":"candle5m",
            "instId":"BTCUSDT"
        }
    ]
}

Request parameters

Parameter Type Required Description
op String Yes Operation, subscribe
args Array Yes List of subscribed channels
> instType String No Instrument Type MC：Public
> channel String Yes Channel name
> instId String No Instrument ID

Example response

{ "event": "subscribe", "arg": { {"instType":"SP","channel":"ticker", "instId":"BTCUSDT" }}

Return parameters

Parameter Type Required Description
event String Yes Event, subscribe error
arg Object No Subscribed channel
> instType String No Instrument Type MC：Public
> channel String Yes Channel name
> instId String No Instrument ID
code String No Error code
msg String No Error message

Unsubscribe

Unsubscribe from one or more channels.

Request format description

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

Request Example

{
    "op":"unsubscribe",
    "args":[
        {
            "instType":"mc",
            "channel":"ticker",
            "instId":"BTCUSDT"
        },
        {
            "instType":"mc",
            "channel":"candle1m",
            "instId":"BTCUSDT"
        }
    ]
}

Request parameters

Parameter Type Required Description
op String Yes Operation, unsubscribe
args Array Yes List of channels to unsubscribe from
> instType String Yes Instrument Type MC：Public
> channel String Yes Channel name
> instId String Yes Instrument ID

Example response

{
    "op":"unsubscribe",
    "args":[
        {
            "instType":"mc",
            "channel":"ticker",
            "instId":"BTCUSDT"
        },
        {
            "instType":"mc",
            "channel":"candle1m",
            "instId":"BTCUSDT"
        }
    ]
}

Return parameters

Parameter Type Required Description
event String Yes Event, unsubscribe error
arg Object Yes Unsubscribed channel
> instType String Yes Instrument Type
> channel String Yes Channel name
> instId String Yes Instrument ID
code String No Error Code
msg String No Error Message

Checksum

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

Merging incremental data into full data

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

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

Calculate Checksum

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

Calculate Checksum

1. More than 25 levels of bid and ask
A full load of market depth (only 2 levels of data are shown here, while 25 levels of data should actually be intercepted):
"bids": [
  [ 43231.1, 4 ],
  [ 43231, 6 ]
]
"asks": [
  [ 43230.8, 9 ],
  [ 43230.7, 8 ]
]
Check string:
"43231.1:4:43231:6:43230.8:9:43230.7:8"

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

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

Public Channels

Tickers Channel

Retrieve the last traded price, bid price, ask price and 24-hour trading volume of instruments. Data will be pushed every 100 ms.

Request Example

{
    "op":"subscribe",
    "args":[
        {
            "instType":"mc",
            "channel":"ticker",
            "instId":"BTCUSDT"
        }
    ]
}

Request parameters

Parameter Type Required Description
op String Yes Operation, subscribe unsubscribe
args Array Yes List of subscribed channels
> instType String Yes Instrument Type MCPublic Channel
> channel String Yes Channel name, tickers
> instId String Yes Instrument ID

Successful Response Example

{ "event": "subscribe", "arg": { "instType":"mc","channel": "ticker", "instId": “BTCUSDT"} }

Failure Response Example

{ "event": "error", "code": "30001", "msg": "Unrecognized request: {\"op\": \"subscribe\", \"arg\":[ \"instType\":"\mc\",\"channel\" : \"ticker\", \"instId\" : \"BTCUSDT\"}]}" } 

Response parameters

Parameter Type Required Description
event String Yes Event, subscribe unsubscribe error
arg Object No Subscribed channel
> instType String Yes Instrument type
> channel String Yes Channel name
> instId String Yes Instrument ID
code String No Error Code
msg String No Error Message

Push data Example

{
    "action":"snapshot",
    "arg":{
        "instType":"mc",
        "channel":"ticker",
        "instId":"BTCUSDT"
    },
    "data":[
        {
            "instId":"BTCUSDT",
            "last":"44962.00",
            "bestAsk":"44962",
            "bestBid":"44961",
            "high24h":"45136.50",
            "low24h":"43620.00",
            "priceChangePercent":"0.02",
            "capitalRate":"-0.00010",
            "nextSettleTime":1632495600000,
            "systemTime":1632470889087,
            "markPrice":"44936.21",
            "indexPrice":"44959.23",
            "holding":"1825.822",
            "baseVolume":"39746.470",
            "quoteVolume":"1760329683.834"
        }
    ]
}

Push data parameters

Paramter Type Description
arg Object Successfully subscribed channel
> instType String Instrument Type
> channel String Channel name
> instId String Instrument Name
action String Push data action, incremental push data or full push data snapshot: full update: incremental
data Array Subscribed data
> instId String Instrument Name
> last String Last traded price
>bestAsk String Best ask price
>bestBid String Best bid price
>high24h String Highest price in the past 24 hours
>low24h String Lowest price in the past 24 hours
>priceCahngePercent String Price change int the past 24 hours
>capitalRate String Funding rate
>nextSettleTime String The next fund rate settlement time timestamp milliseconds
>systemTime String system time
>marketPrice String Mark price
>indexPrice String Index price
>holding String Open interest
>baseVolume String 24h trading volume, with a unit of base.
>quoteVolume String 24h trading volume, with a unit of quote

Candlesticks Channel

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

Request Example

{
    "op":"subscribe",
    "args":[
        {
            "instType":"mc",
            "channel":"candle1m",
            "instId":"BTCUSDT"
        }
    ]
}

Request parameters

Parameter Type Required Description
op String Yes Operation, subscribe unsubscribe
args Array Yes List of subscribed channels
> instType String Yes Instrument Type MCPublic Channel
> channel String Yes Channel Name，candle1Wcandle1Dcandle12H candle4H  candle1Hcandle30m candle15m candle5m candle1m
> instId String Yes Instrument ID

Successful Response Example

{
    "event":"subscribe",
    "arg":{
        "instType":"mc",
        "channel":"candle1D",
        "instId":"BTCUSDT"
    }
}

Failure Response Example

{
    "event":"error",
    "code":30003,
    "instType":"mc",
    "channel":"candle1D",
    "instId":"BTC-USDT Symbol not exists"
}

Response parameters

Parameter Type Required Description
event String Yes Event, subscribe unsubscribe error
arg Object No Subscribed channel
> instType String Yes Instrument Type
> channel String Yes channel name
> instId String Yes Instrument ID
code String No Error Code
msg String No Error Message

Push Data Example

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

Push data parameters

Parameter Type Description
arg Object Successfully subscribed channel
> instType String Instrument Type
> channel String Channel name
> instId String Instrument ID
data Array Subscribed data
> ts String Data generation time, Unix timestamp format in milliseconds
> o String Open price
> h String highest price
> l String Lowest price
> c String Close price
baseVol String Trading volume, with a unit of contact.

Order Book Channel

Retrieve order book data.

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

Request Example

{
    "op":"subscribe",
    "args":[
        {
            "instType":"mc",
            "channel":"books5",
            "instId":"BTCUSDT"
        }
    ]
}

Request parameters

Parameter Type Required Description
op String Yes Operation, subscribe unsubscribe
args Array Yes List of subscribed channels
> instType String Yes Instrument type MC: Hybrid contract public channel, UMCBL: Professional contract private channel, DMCBL: Hybrid contract private channel
> channel String Yes Channel name, books books5
> instId String Yes Instrument ID

Example Response

{
    "event":"subscribe",
    "arg":{
        "instType":"mc",
        "channel":"books5",
        "instId":"BTCUSDT"
    }
}

Failure example

{
    "event":"error",
    "code":30003,
    "msg":"",
    "instType":"mc",
    "channel":"books5",
    "instId":"BTC-USDT Symbol not exists"
}

Response parameters

Parameter Type Required Description
event String Yes Event，subscribe unsubscribe error
arg Object No Subscribed channel
> instType String Yes Instrument Type
> channel String Yes Channel name
> instId String Yes Instrument ID
msg String No Error Message
code String No Error Code

Push data parameters

Parameter Type Description
arg Object Successfully subscribed channel
> instType String Instrument Type
> channel String Channel name
> instId String Instrument ID
action String Push data action, incremental push data or full push data snapshot: full update: incremental
data Array Subscribed data
> asks Array Order book on sell side
> bids Array Order book on buy side
> ts String Order book generation time, Unix timestamp format in milliseconds
> checksum Integer Checksum

An example of the array of asks and bids values: ["411.8", "10", "1", "4"] "411.8" is the depth price, "10" is the size

Trades Channel

Retrieve the recent trades data. Data will be pushed whenever there is a trade.

Request Example

{
    "op":"subscribe",
    "args":[
        {
            "instType":"mc",
            "channel":"trade",
            "instId":"BTCUSDT"
        }
    ]
}

Request parameters

Parameter Type Required Description
op String Yes Operation, subscribe unsubscribe
args Array Yes List of subscribed channels
> instType String Yes Instrument type MC: Hybrid contract public channel, UMCBL: Professional contract private channel, DMCBL: Hybrid contract private channel
> channel String Yes Channel Name，trade
> instId String Yes Instrument ID

Successful Response Example

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

Failure Response Example

{
    "event":"error",
    "code":30003,
    "msg":"",
    "instType":"mc",
    "channel":"books5",
    "instId":"BTC-USDT Symbol not exists"
}

Response parameters

Parameter Type Required Description
event String Yes Event，subscribe unsubscribe error
arg Object No Subscribed channel
> instType String Yes InstrumentType
> channel String Yes Channel Name
> instId String Yes Instrument ID
code String No Error Code
msg String No Error Message

Push data parameters

Parameter Type Description
arg Object Successfully subscribed channel
> instType String Instrument Type
> channel String Channel Name
> instId String Instrument ID
data Array Subscribed data
> ts String Filled time, Unix timestamp format in milliseconds
> px String Trade price
> sz String Trade size
> side String Trade direction, buy, sell

Private Channels

Account Channel

Retrieve account information. Data will be pushed when triggered by events such as placing/canceling order, and will also be pushed in regular interval according to subscription granularity.

Request Example

{
    "op": "subscribe",
    "args": [{
        "instType": "UMCBL",
        "channel": "account",
        "instId": "default"
    }]
}

Request Paramter

Paramter Type Required Description
op String Yes Operation，subscribe unsubscribe
args Array Yes Subscribed channel
> instType String Yes Instrument Type UMCBL:USDT Private Channel DMCBL:Mix Private Channel
> channel String Yes Channel name account
> instId String Yes Coin, All is default

Successful Response Example

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

Failure Response Example

{
    "event": "error",
    "code": 30003,
    "msg": "instType:UMCBL,channel:ticker,instId:BTC-USDT Symbol not exists" 
} 

Response parameters

Parameter Type Required Description
event String Yes Operation，subscribe unsubscribe error
arg Object No Subscribed channel
> instType String Yes Instrument Type
> channel String Yes Channel Name
> instId String No Coin
code String No Error code
msg String No Error messgae

Push Data Parameter

Parameter Type Description
arg Object Subscribed channel
> instType String Instrument Type
> channel String Channel Name
> instId String Coin
data Array Subscribed Data
marginCoin String Margin Coin
locked String Lock balance
available String Available balance
crossMaxAvailable String Cross Liabilities of the currency
fixedMaxAvailable String Isolated Liabilities of the currency
maxTransferOut String Max transfer out
equity String Equity of the currency
usdtEquity String Equity of the currency USD

First push: full push.

Incremental push: push transaction changes

Positions Channel

Retrieve position information. Initial snapshot will be pushed according to subscription granularity. Data will be pushed when triggered by events such as placing/canceling order, and will also be pushed in regular interval according to subscription granularity.

Request Example

{
    "op": "subscribe",
    "args": [{
        "instType": "UMCBL",
        "channel": "positions",
        "instId": "default"
    }]
}

Request Parameter

Parameter Type Required Description
op String Yes Operation ，subscribe unsubscribe
args Array Yes Subscribed channel List
> channel String Yes Channel Name，positions
> instType String Yes Instrument Type UMCBL:USDT Private Channel DMCBL:Mix Private Channel
> instId String No Symbol Name

Response Parameter

Parameter Type Required Description
event String Yes Event ，subscribe unsubscribe errror
arg Object No Subscribed channel
> channel String Yes Channel Name
> instType String Yes Instrument Type
> instId String No Symbol Name
code String No Error Code
msg String No Error Message

Push Data Parameter

Parameter Type Description
arg Object Subscribed channel
> channel String Channel Name
> instType String Instrument Type
> instId String Instrument ID
data Array Subscribed Data
> posId String Position Id
> instId String Symbol Name
> instName String Symbol Name
> marginCoin String Margin Coin
> margin String Margin, can be added or reduced
>marginMode String Margin mode, cross fixed
> holdSide String Position sidelong short
> holdMode String hold Mode single_hold , double_hold
> total String Quantity of positions
> available String Position that can be closed
> locked String Frozen quantity
>averageOpenPrice String Average open price
> leverage String Leverage
> achievedProfits String Realized profit and loss
> upl String Unrealized profit and loss
> uplRate String Unrealized profit and loss ratio
> liqPx String Estimated liquidation price
> keepMarginRate String Maintenance margin requirement Ratio
> fixedMarginRate String Margin requirement Ratio fixed
> fixedRiskRate String Risk rate. fixed
> cTime String Creation time, Unix timestamp format in milliseconds
> uTime String Latest time position was adjusted, Unix timestamp format in milliseconds

When multiple orders are being executed at the same time, the changes of position data will be aggregated into one as much as possible.

Order Channel

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

Request Example

{
    "op": "subscribe",
    "args": [{
        "channel": "orders",
        "instType": "UMCBL",
        "instId": "default"
    }]
}

Request Parameter

Parameter Type Required Description
op String Yes Operation ，subscribe unsubscribe
args Array Yes Request Subscribed channel List
> channel String Yes Channel Name， orders
> instType String Yes Instrument Type UMCBL:USDT Private Channel DMCBL:Mix Private Channel
> instId String No Currently only supports default all trading pair orders

Success Response Example

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

Failure Response Example

{
    "event": "error",
    "code": 30003,
    "msg": "instType:UMCBL,channel:orders,instId:BTC-USDT Symbol not exists"
}

Response Parameter

Parameter Type Required Description
event String Yes Event ，subscribe unsubscribe errror
arg Object No Subscribed channel
> channel String Yes Channel Name
> instType String Yes Instrument Type
> instId String No Instrument Id
code String No Error Code
msg String No Error Message

Push Data Parameter

Parameter Type Description
arg Object Subscribed channel
> channel String Channel Name
> instType String Instrument Type
> instId String Instrument Id
data Array Subscribed Data
> instId String Instrument Id
> ordId String Order Id
> clOrdId String Client-supplied order ID
> px String Order price
> sz String The original order quantity, in the unit of currency
> notionalUsd String Estimated national value in USD of order
> ordType String Order Type market limit
> force String Order Force normal: normal order post_only: Post-only orderfok: Fill-or-kill orderioc: Immediate-or-cancel order
> side String Order side, buy sell
> posSide String Position side long  or  short
> tdMode String Trade mode, cross: cross fixed: fixed
> tgtCcy String Margin Coin
> fillPx String Last filled price
> tradeId String Last trade ID
> fillSz String Last filled quantity
> fillTime String Last filled time
> fillFee String last filled fee
> fillFeeCcy String last filled fee currency
> execType String Order flow type, T: taker M: maker
> accFillSz String Accumulated fill quantity
> fillNotionalUsd String Filled notional value in USD of order
> avgPx String Average filled price. If none is filled, it will return 0.
> status String Order Status new partial-fill full-fill cancelled
> lever String Leverage
>orderFee Array
>> feeCcy String Fee currency
>> fee String FeeNegative number represents the user transaction fee charged by the platform.Positive number represents rebate.
> pnl String Profit and loss
> uTime String Update time, Unix timestamp format in milliseconds
> cTime String Creation time, Unix timestamp format in milliseconds

RestAPI error codes

Error message Error code http status code
The request header "ACCESS_KEY" cannot be empty 40001 400
The request header "ACCESS_SIGN" cannot be empty 40002 400
The request header "ACCESS_TIMESTAMP" cannot be empty 40003 400
Invalid ACCESS_TIMESTAMP 40005 400
Invalid ACCESS_KEY 40006 400
Invalid Content_Type, please use the "application/json" format 40007 400
Request timestamp expired 40008 400
Api verification failed 40009 400
Request too frequent 429 429
The request header "ACCESS_PASSPHRASE" cannot be empty 40011 400
apikey/passphrase is incorrect 40012 400
User is frozen 40013 400
Incorrect permissions 40014 400
System error 40015 400
The user must bind a mobile phone or Google 40016 400
Parameter verification failed 40017 400
Illegal ip request 40018 400
Take profit price needs to be > current price 43013 400
Take profit price needs to be > current price 43014 400
Stop loss price needs to be <current price 43015 400
Stop loss price needs to be <current price 43016 400
You are currently a trader and currently do not support liquidation through limit orders 43001 400
Take profit and stop loss order does not exist 43020 400
The take-profit and stop-loss order has been closed 43021 400
Failed to trigger the default stop loss 43022 429
Insufficient position, can not set take profit or stop loss 43023 400
Take profit/stop loss in an existing order, please change it after canceling all 43024 400
Limit order does not exist 43025 400
The limit order has been closed 43026 400
You are currently a trader, please close the position under the current order 40728 400

WebSocket error codes

Error Message Error Code
Channel does not exist 30001
Illegal request 30002
Invalid op 30003
User needs to log in 30004
Login failed 30005
Invalid ACCESS_KEY 30011
Invalid ACCESS_PASSPHRASE 30012
Invalid ACCESS_TIMESTAMP 30013
Request timestamp expired 30014
Invalid signature 30015
console