Introduction

Getting Started

Welcome to the developer documentation.

Instruction For Calling Endpoints

developers can choose their own way to query the market, trade or withdraw according to their usage scenarios and preferences.

Contact Us

Join our Telegram API Group

Product Dictionary

Trade

Contract

Order and Trade ID

Time

The time returned by the system is all in the form of time pinches.

Standard Rules

This chapter is mainly divided into the following three aspects for the details of standard specifications:

Numbers ID

Numbers

To maintain the integrity and accuracy across platforms, decimal numbers are returned as strings. It is recommended that you also convert numbers to strings when making requests to avoid truncation and precision errors.

Integers (such as transaction ID and order) are not quoted.

ID

Unless otherwise stated, most identifiers are UUIDs. When making a request that requires a UUID, the following two formats (with and without dashes) are accepted.

132fb6ae-456b-4654-b4e0-d681ac05cea1 or 132fb6ae456b4654b4e0d681ac05cea1

Change Log

2023-03-16

• New endpoints for submit plan order
  • /contract/private/submit-plan-order
• New endpoints for cancel plan order
  • /contract/private/cancel-plan-order

2022-09-22

• New endpoints for get contract order history
  • /contract/private/orders-history
• New endpoints for get contract order trade detail
  • /contract/private/trades
• New endpoints for get contract assets detail
  • /contract/private/assets-detail
• New endpoints for get k-line
  • /contract/public/kline
• New endpoints for get current funding rate
  • /contract/public/funding-rate
• New endpoints for get current position detail
  • /contract/private/position

2022-08-23

• New endpoints for Openinterest
  • /contract/public/open-interest

2022-08-18

• New endpoints for get contract detail
  • /contract/public/details
• New endpoints for get contract depth
  • /contract/public/depth

Basic Information

API Basic Information

1. The interface may require the user's API Key. For how to create an API-KEY, please refer to here API KEY Interface Authentication.
2. RESTful API URL: https://api-cloud.bitmart.com
3. The responses of all interfaces are in JSON format.

HTTP Response Codes

• HTTP 4XX Error codes are used to indicate wrong request content, behavior, and format. The problem is from the request sender.
• HTTP 403 The error code indicates a violation of the restriction (prohibited call).
• HTTP 429 The error code indicates that the access frequency is overrun and the IP will be blocked.
• HTTP 418 The error code indicates that the IP has been blocked after error code 429.
• HTTP 5XX Error codes are used to indicate problems with BitMart server.

API Returned Codes

When using the interface, HTTP 200 means that the client has submitted a request to the business core through the gateway and it has returned information, but it does not mean that the business request is successful. It may have been executed, or the execution may fail, and further confirmation is required at this time. Please pay attention to the code field in the returned data.

For details, please refer to Error Code List

Authentication and Signature

In order to facilitate access, we provide SDK in some languages for reference
* bitmart-go-sdk-api
* bitmart-python-sdk-api
* bitmart-java-sdk-api
* bitmart-php-sdk-api

This chapter mainly divides the verification details into the following four aspects:

• Generate API Key
• Make a request
• Signature
• Timestamp

1. Generate API Key

Before signing any request, you must create an API Key through the BitMart website. After creating the API Key, you will get 3 pieces of information you must remember:

• Access Key
  
• Secret Key
  
• Memo
  

Access Key and Secret Key will be randomly generated and provided by BitMart, and Memo will be provided by you to ensure the security of API access. BitMart will store the encrypted hash value of the Secret Key for verification, but if you forget the Secret Key, it cannot be recovered. Please regenerate the new API Key through the BitMart website.

Example

Login Bitmart website and enter the account page

Click the API Settings button to enter the CREATE API page

2. Make a Request

The request contains two parts, one is header and the other is queryString

Interface Header Parameters

All REST request headers must include the following:

• X-BM-KEY: Access Key of type string.

• X-BM-SIGN: Use HmacSHA256 signature (see Signature).

• X-BM-TIMESTAMP: The timestamp of the request. (UTC0 time zone timestamp, accurate to milliseconds)

Interface Content Type

Request Example: GET/DELETE

curl {{host}}/v1/goto?symbol=BMXBTC&side=BUY

# queryString: symbol=BMXBTC&side=BUY

• For interfaces using the GET and DELETE methods, the content can be sent in two forms: application/json or application/x-www-form-urlencoded. The parameter must be sent in the query string. (The order of the parameters is not required.)

Request Example: POST/PUT

curl -X POST {{host}}/v1/goto -H "Content-type: application/json" -d '{"symbol":"BMX","side":"BUY"}'

# queryString: {"symbol":"BMX","side":"BUY"}

• For interfaces using the POST and PUT methods, the content can be sent in application/json form. (The order of the parameters is not required.)

Special Note: In the example on the right,

The request method of GET/DELETE, the query string is the form type of key1=value2&key2=value2

The request method of POST/PUT, the query string is the json type of {"symbol":"BMX","side":"BUY"}

3.Signature

Signature Algorithm Example: In the example below, param variable message=timestamp + "#" + memo + "#" + queryString

// javascript language
sign=CryptoJS.HmacSHA256(message, YourSecretKey)

// python language
def sign(message, your_secret_key):
    mac = hmac.new(bytes(your_secret_key, encoding='utf8'), bytes(message, encoding='utf-8'), digestmod='sha256')
    return mac.hexdigest()

// java language
import org.apache.commons.codec.binary.Hex;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public final class CloudSignature {
    static final String HMAC_SHA256 = "HmacSHA256";
    static String createSha256Signature(String yourSecretKey, String message) {
        try {
            Mac sha256 = Mac.getInstance(HMAC_SHA256);
            SecretKeySpec secretKeySpec = new SecretKeySpec(yourSecretKey.getBytes(), HMAC_SHA256);
            sha256.init(secretKeySpec);
            return Hex.encodeHexString(sha256.doFinal(message.getBytes()));
        } catch (Exception ex) {
            ex.printStackTrace();
        }
        return null;
    }
}

// go language
import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
)
func HmacSha256Base64Signer(message string, yourSecretKey string) (string, error) {
    mac := hmac.New(sha256.New, []byte(yourSecretKey))
    _, err := mac.Write([]byte(message))
    if err != nil {
        return "", err
    }
    return hex.EncodeToString(mac.Sum(nil)), nil
}

The request header of X-BM-SIGN is signed by the HMAC SHA256 algorithm and converted to lowercase hexadecimal (toHexString) encoding. Among them, the key of the algorithm is your api secret key, and the signed content is timestamp + "#" + memo + "#" + queryString.

Among them, the value of timestamp is the same as the X-BM-TIMESTAMP in request header.

Note: If the length of your sign is not equal to 64, or if the sign is uppercase, it is wrong.

4.Timestamp

Unix timestamps accurate to milliseconds using UTC0 time zone

Example: If the current time: 2020-04-28 09:21:30.000, then timestamp=1588065690000

Example

The keys are as follows: Note that the following two interfaces are deployed in the production environment, and users can directly test and call after replacing with their own KEY.

Example: /spot/v1/test-get

echo -n "1589793795969#test001#symbol=BTC_USDT" | openssl dgst -sha256 -hmac "6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9"
    (stdin)= 118eb558afa7d84e8710004f8416ddb771f50718c85f60a45069d0ccbe6ee1e0

curl --location --request GET 'localhost:8080/spot/v1/test-get?symbol=BTC_USDT'
--header 'Content-Type: application/json'
--header 'X-BM-KEY: 80618e45710812162b04892c7ee5ead4a3cc3e56'
--header 'X-BM-SIGN: 118eb558afa7d84e8710004f8416ddb771f50718c85f60a45069d0ccbe6ee1e0'
--header 'X-BM-TIMESTAMP: 1589793795969'

{"message":"OK","code":1000,"trace":"17105b32-cc5b-406a-ab6e-6d9ed0fa4fd8","data":{}}

Request interface: /spot/v1/test-get

Request method: GET

Current timestamp: timestamp=1589793795969

Returned data: The request is a success if code=1000 in returned data.

Example: /spot/v1/test-post

echo -n '1589793796145#test001#{"symbol":"BTC_USDT","price":"8600","count":"100"}' | openssl dgst -sha256 -hmac "6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9"
    (stdin)= c31dc326bf87f38bfb49a3f8494961abfa291bd549d0d98d9578e87516cee46d

    curl --location --request POST 'localhost:8080/spot/v1/test-post'
    --header 'Content-Type: application/json'
    --header 'X-BM-KEY: 80618e45710812162b04892c7ee5ead4a3cc3e56'
    --header 'X-BM-SIGN: c31dc326bf87f38bfb49a3f8494961abfa291bd549d0d98d9578e87516cee46d'
    --header 'X-BM-TIMESTAMP: 1589793796145'
    --d '{"symbol":"BTC_USDT","price":"8600","count":"100"}'

{"message":"OK","code":1000,"trace":"17105b32-cc5b-406a-ab6e-6d9ed0fa4fd8","data":{}}

Request interface: /spot/v1/test-post

Request method: POST

Current timestamp: timestamp=1589793796145

Returned data: The request is a success if code=1000 in returned data.

RequestFormat

This article mainly describes some specifications of the interface from the following two aspects. * Request standard * Authentication type

Request Standard

1.Rest Interface

1.1 Request parameter and format

GET/DELETE

curl https://api-cloud.bitmart.com/contract/v1/ifcontract/contracts?contractID=1

For interfaces using GET, DELETE methods, the parameters should be sent via query string.

POST/PUT

curl https://api-cloud.bitmart.com/contract/v1/ifcontract/submitOrder
body: {"contract_id":1,"category":1,"way":1,"open_type":1,"leverage":10,"custom_id":1,"price":5000,"vol":10,"nonce":1589266686}

For interfaces using POST, PUT methods, the parameters should be sent in the request body for concent type of application/json.

1.2 Reponse

Response:

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": [
    {
      "low": "130",
      "high": "130",
      "open": "130",
      "close": "130",
      "last_price": "130",
      "avg_price": "130",
      "volume": "0",
      "timestamp": 1532610000,
      "rise_fall_rate": "0",
      "rise_fall_value": "0"
    }
  ]
}

The server response data format is JSON.

2.WebSocket Interface

No description.

Authentication Type

This chapter is mainly divided into the following two aspects of interface type details:

• Public interface
• Private interface

1. Public Interface

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

2. Private Interface

The private interface can be used for order and account management. Each private request must be signed using a standardized authentication method. The private interface needs to be verified with your API key.

Interface Permission

Whether you have permission to call the interface requires attention to the following two aspects:
* Interface authentication
* API Permission

Interface authentication

When the user calls, APIKEY and verification parameters need to be passed in the way specified by the interface. The first line of each interface will have a description of what authentication the interface needs.

Simply put, the interface authentication is divided into the following three cases:

API KEY Permission

Refers to the user specified authorization to the API when applying for the API. That is, when users apply for API KEY on the BitMart website page, they can check API permissions, such as: trading permissions (including contract transactions and spot transactions). (Default: read-only permission).

Details:

Rate Limit

When the requests exceed the rate limit, the 429 status will be returned: the request is too frequent.

REST API

If a valid API key is passed in, the user id will be used to limit the rate; if not, the public IP will be used to limit the rate.

Rate limit rules: There is a separate description on each interface. If there is not, the rate limit is 25 times/5 sec in general.

Each call to the interface will return 3 Response Headers with limit tags, as shown below:

Example:

X-BM-RateLimit-Remaining: 10
X-BM-RateLimit-Limit: 600
X-BM-RateLimit-Reset: 60
The above setting means that it can be called 600 times within 60 seconds, and currently has been called 10 times

The specific interface limits are as follows:

Futures Market Data

Get Contract Details

Applicable to query contract details (Authentication type:NONE, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/contract/public/details

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/contract/public/details

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "trace": "9b92a999-9463-4c96-91a4-93ad1cad0d72",
  "data": {
    "symbols": [
      {
        "symbol": "BTCUSDT",
        "product_type": 1,
        "open_timestamp": 1594080000,
        "expire_timestamp": 0,
        "settle_timestamp": 0,
        "base_currency": "BTC",
        "quote_currency": "USDT",
        "last_price": "23920",
        "volume_24h": "18969368",
        "turnover_24h": "458933659.7858",
        "index_price": "23945.25191635",
        "index_name": "BTCUSDT",
        "contract_size": "0.001",
        "min_leverage": "1",
        "max_leverage": "100",
        "price_precision": "0.1",
        "vol_precision": "1",
        "max_volume": "500000",
        "min_volume": "1"
      },
      ...
    ]
  }
}

Description of the trading pair details field:

Get Market Depth

Get full depth of trading pairs. (Authentication type:NONE, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/contract/public/depth

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/contract/public/depth?symbol=BTCUSDT

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "trace": "b9bff62d-9ac8-4815-8808-8f745673c096",
  "data": {
    "asks": [
      [
        "23935.4",
        "65",
        "65"
      ]
    ],
    "bids": [
      [
        "23935.4",
        "65",
        "65"
      ]
    ],
    "timestamp": 1660285421287,
    "symbol": "BTCUSDT"
  }
}

Market depth details：

Get Futures Openinterest

Applicable for querying the open interest and open interest value data of the specified contract (Authentication type:NONE, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/contract/public/open-interest

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/contract/public/open-interest?symbol=BTCUSDT

Response Data

Response

{
  "code": 1000,
  "trace": "0cc6f4c4-8b8c-4253-8e90-8d3195aa109c",
  "message": "Ok",
  "data": {
    "timestamp": 1661239541734,
    "symbol": "BTCUSDT",
    "open_interest": "4134180870",
    "open_interest_value": "94100888927.0433258"
  }
}

Get Current Funding Rate

Applicable for checking the current funding rate of a specified contract (Authentication type:NONE, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/contract/public/funding-rate

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/contract/public/funding-rate?symbol=BTCUSDT

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "timestamp": 1662518172178,
    "symbol": "BTCUSDT",
    "rate_value": "0.000164"
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}

Get K-line

Applicable for querying K-line data (Authentication type:NONE, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/contract/public/kline

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/contract/public/kline?symbol=BTCUSDT&step=5&start_time=1662518172&end_time=1662518172

Response Data

Response

{
  "code": 1000,
  "trace": "0cc6f4c4-8b8c-4253-8e90-8d3195aa109c",
  "message": "Ok",
  "data": {
    "timestamp": 1662518160,
    "open_price": "100",
    "close_price": "120",
    "high_price": "130",
    "low_price": "90",
    "volume": "941008"
  }
}

Futures Account Data

Get Contract Assets Detail

Applicable for querying user contract asset details (Authentication type:KEYED, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/contract/private/assets-detail

Request Limit

See Detailed Rate Limit

Request Parameter

Request None

curl https://api-cloud.bitmart.com/contract/private/assets-detail

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": [
    {
      "currency": "USDT",
      "position_deposit": "100",
      "frozen_balance": "100",
      "available_balance": "100",
      "equity": "100",
      "unrealized": "100"
    },
    {
      "currency": "BTC",
      "available_balance": "0",
      "frozen_balance": "0",
      "unrealized": "0",
      "equity": "0",
      "position_deposit": "0"
    },
    {
      "currency": "ETH",
      "available_balance": "0",
      "frozen_balance": "0",
      "unrealized": "0",
      "equity": "0",
      "position_deposit": "0"
    }
  ],
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}

Futures Trading

Get Order Detail

Applicable for querying contract order detail (Authentication type:KEYED, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/contract/private/order

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/contract/private/order?symbol=BTCUSDT&order_id=220609666322019

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "order_id": "220906179895578",
    "price": "1",
    "size": "1000",
    "symbol": "BTCUSDT",
    "state": 2,
    "side": 1,
    "type": "limit",
    "leverage": "5",
    "open_type": "isolated",
    "deal_avg_price": "0",
    "deal_size": "1000",
    "create_time": 1662368173000,
    "update_time": 1662368173000
  },
  "trace": "638d5048-ad21-4a4b-9365-d0756fbfc7ba"
}

Get Order History

Applicable for querying contract order history (Authentication type:KEYED, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/contract/private/order-history

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/contract/private/order-history?symbol=BTCUSDT&start_time=1662368173&end_time=1662368179

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "order_id": "220906179895578",
    "price": "1",
    "size": "1000",
    "symbol": "BTCUSDT",
    "state": 2,
    "side": 1,
    "type": "limit",
    "leverage": "5",
    "open_type": "isolated",
    "deal_avg_price": "0",
    "deal_size": "1000",
    "create_time": 1662368173000,
    "update_time": 1662368173000
  },
  "trace": "638d5048-ad21-4a4b-9365-d0756fbfc7ba"
}

Get Current Position Detail

Applicable for checking the position details a specified contract (Authentication type:KEYED, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/contract/private/position

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/contract/private/position?symbol=BTCUSDT

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": [
    {
      "symbol": "BTCUSDT",
      "leverage": "3.255031032814235929",
      "timestamp": 1663814313531,
      "current_fee": "5.00409471",
      "open_timestamp": 1662714817820,
      "current_value": "16680.3157",
      "mark_price": "16673.27053207877",
      "position_value": "18584.272343943943943944339",
      "position_cross": "3798.397624451826977945",
      "maintenance_margin": "4798.397624451826977945",
      "close_vol": "100",
      "close_avg_price": "20700.7",
      "current_amount": "899",
      "unrealized_value": "1903.956643943943943944339",
      "realized_value": "55.049173071454605573",
      "position_type": 2
    }
  ],
  "trace": "ae96cae5-1f09-4ea5-971e-4474a6724bc8"
}

Get Order Trade Detail

Applicable for querying contract order trade detail (Authentication type:KEYED, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/contract/private/trades

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/contract/private/trades?symbol=BTCUSDT&start_time=1662368173&end_time=1662368179

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": [{
    "order_id": "220921197409432",
    "trade_id": "1141853921",
    "symbol": "BTCUSDT",
    "side": 1,
    "price": "19313.3",
    "vol": "108",
    "exec_type": "Maker",
    "profit": false,
    "realised_profit": "-0.00832",
    "paid_fees": "0",
    "create_time": 1663663818589
  }],
  "trace": "638d5048-ad21-4a4b-9365-d0756fbfc7ba"
}

Submit an Order

Applicable for placing contract orders (Authentication type:SIGNED, See Interface Permission)

Request Format

POST https://api-cloud.bitmart.com/contract/private/submit-order

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/contract/private/submit-order

{
  "symbol":"ETHUSDT",
  "side":4,
  "mode":1,
  "type":"limit",
  "leverage":"1",
  "open_type":"isolated",
  "size":10,
  "price":"2000"
}

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "order_id": "220609666322019"
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}

Cancel an Order

Applicable for canceling a specific contract order (Authentication type:SIGNED, See Interface Permission)

Request Format

POST https://api-cloud.bitmart.com/contract/private/cancel-order

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/contract/private/cancel-order

{
  "symbol":"ETHUSDT",
  "order_id": "220906179559421"
}

Response Data

If code value is 1000, it means the order is successfully canceled.

Response

{
  "code": 1000,
  "trace": "0cc6f4c4-8b8c-4253-8e90-8d3195aa109c",
  "message": "Ok",
  "data": {
  }
}

Cancel All Orders

Applicable for batch order cancellation under a particular contract (Authentication type:SIGNED, See Interface Permission)

Request Format

POST https://api-cloud.bitmart.com/contract/private/cancel-orders

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/contract/private/cancel-orders

{
  "symbol":"ETHUSDT"
}

Response Data

If code value is 1000, it means the order is successfully canceled.

Response

{
  "code": 1000,
  "trace": "0cc6f4c4-8b8c-4253-8e90-8d3195aa109c",
  "message": "Ok",
  "data": {
  }
}

Submit Plan an Order

Applicable for placing contract plan orders (Authentication type:SIGNED, See Interface Permission)

Request Format

POST https://api-cloud.bitmart.com/contract/private/submit-plan-order

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/contract/private/submit-plan-order

{
  "symbol":"ETHUSDT",
  "side":4,
  "mode":1,
  "type":"limit",
  "leverage":"1",
  "open_type":"isolated",
  "size":10,
  "trigger_price":"2000",
  "executive_price":"1450",
  "price_type":"1",
  "price_way":"1"
}

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "order_id": "220609666322019"
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}

Cancel Plan an Order

Applicable for canceling a specific contract plan order (Authentication type:SIGNED, See Interface Permission)

Request Format

POST https://api-cloud.bitmart.com/contract/private/cancel-plan-order

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/contract/private/cancel-plan-order

{
  "symbol":"ETHUSDT",
  "order_id": "220906179559421"
}

Response Data

If code value is 1000, it means the order is successfully canceled.

Response

{
  "code": 1000,
  "trace": "0cc6f4c4-8b8c-4253-8e90-8d3195aa109c",
  "message": "Ok",
  "data": {
  }
}

WebSocket Subscription

Overview

Address

Public Channel wss://openapi-ws.bitmart.com/api?protocol=1.1

Private Channel wss://openapi-ws.bitmart.com/user?protocol=1.1

Format

Request Format

{"action":"<operation>", "args":["<topic1>","<topic2>"]}

Terminology

operation: Request action, value

Subscribe=subscribeUnsubscribe=unsubscribeLogin=login

args: Request parameter, value: channel array or parameters required for login

topic: Channel topic, composed of <channel>:<filter>

channel is composed of business/name

filter can filter data, refer to the description of each channel for details

Example: futures/klineBin1m:BTCUSDT: which means klineBin data of contract trading pair BTCUSDT

error: When sending a subscription or login operation generates an error, the error code will be returned

Successful Response Format

Successful Response Format

When action=access ：
{"action":"access","success":true}

When action=unsubscribe ：
{"action":"unsubscribe","group":"Depth:1","success":true,"request":{"action":"unsubscribe","args":["Depth:1"]}}

When action=subscribe ：
{"action":"subscribe","group":"Depth:1","success":true,"request":{"action":"subscribe","args":["Depth:1"]}}

When success field of return data is true, it indicates success

Failed Response Format

Failed Response Format

{"action":"subscribe","group":"Depth:1","success":false,"error":"authentication is temporarily unavailable"}

When success field of return data is false, it indicates failure

Stay Connected And Limit

Stay Connected

WebSocket uses the Ping/Pong mechanism to maintain the connection. Once the connection is opened, a Ping frame is sent every N seconds, and the remote endpoint will return a Pong frame to keep responding. This is an approach to stay active. It helps to keep the connection open, especially if there is a short timeout proxy on an inactive connection.

If no data is returned after connecting to WebSocket, the link will be automatically disconnected after 5s. It is recommended that the user do the following:

1.After each message is received, the user sets a timer for N seconds (N<5).

2.If the timer is triggered (no new message is received within N seconds), send a ping frame or send a string 'ping'.

3.Expect for a text string 'pong' as a response. If not received within N seconds, please issue an error or reconnect.

4.We do not actively disconnect when there is a continuous message interaction between the two parties.

The following is the data format of ping:

The following is the data format of ping:

• Standard Ping frame

ws.send(new PingWebSocketFrame();

• Ping Text

{"subscribe":"ping"}

• Pong Text {"group":"System","data":"pong"}

Connection Limit

Public Channel

Private Channel

Lifeless connection

Connection that do not send task subscription data within 5 seconds will be considered lifeless and the server will close the connection.

WebSocket Subscription

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

subscribe

{"action":"subscribe","args":["futures/depth50:BTCUSDT","futures/ticker"]}

Parameter Instructions

• action = subscribe
• The content of the args array is the subscribed topic
• topic is composed of <channel>:<filter>
  • channel is composed of business/name
  • filter can filter data, refer to the description of each channel for details

Example

Request

{"action":"subscribe","args":["futures/depth50:BTCUSDT","futures/ticker"]}

Response

{"action":"subscribe","group":"futures/ticker","success":true,"request":{"action":"subscribe","args":["futures/ticker"]}}

{"action":"subscribe","group":"futures/depth50:BTCUSDT","success":true,"request":{"action":"subscribe","args":["futures/depth50:BTCUSDT"]}}

{"action":"subscribe","group":"futures/klineBin1m:BTCUSDT","success":true,"request":{"action":"subscribe","args":["futures/klineBin1m:BTCUSDT"]}}

Unsubscribe

Cancel subscription to one or more channels

unsubscribe

{"action": "unsubscribe", "args": ["<topic>"]}

Parameter Instruction

• action = unsubscribe
• The content of the args array is the subscribed topic
• topic is composed of <channel>:<filter>
  • channel is composed of business/name
  • filter can filter data, refer to the description of each channel for details

Example

Request

{"action": "unsubscribe", "args": ["futures/klineBin1m:BTCUSDT"]}

Response

{"action":"unsubscribe","group":"futures/klineBin1m:BTCUSDT","success":true,"request":{"action":"unsubscribe","args":["futures/klineBin1m:BTCUSDT"]}}

【Public】Ticker Channel

Get the latest transaction price, bid one price, ask for one price, and 24 trading volumes of all perpetual contracts on the platform, without user login, sent once in 1 second after subscription.

Pushing Rules

1. No user login required
2. After subscribing, the current data will be returned directly, and then the changes will be pushed

Example

Request

{"action":"subscribe","args":["futures/ticker"]}

futures/ticker is the channel name

Response

{
    "group":"futures/ticker",
    "data":{
          "symbol":"BTCUSDT",
          "volume_24":"117387.58",
          "fair_price":"146.24",
          "last_price":"146.24",
          "range":"147.17"
        }
}

Parameter Type Description:

【Public】Depth Channel

Get depth data and push updates as soon as they are available without user login.

Pushing Rules

1. No user login required
2. After subscribing, the current data will be returned directly, and then the changes will be pushed

Example

Request

{"action":"subscribe","args":["futures/depth20:BTCUSDT"]}

futures/depth20 is the channel name and BTCUSDT is the trading side

Channel List

Response

{
    "group":"futures/depth20:BTCUSDT",
    "data":{
            "symbol":"BTCUSDT",
            "way":1,
            "depths":[
              {"price":"5","vol":"97"}
            ],
            "ms_t": 1542337219120
        }
}

Parameter Type Description:

Instruction

Description of the depth details field:

【Public】Trade Channel

Get trade data and push updates as soon as they are available without user login.

Pushing Rules

1. No user login required
2. After subscribing, the current data will be returned directly, and then the changes will be pushed

Example

Request

{"action":"subscribe","args":["futures/trade:BTCUSDT"]}

futures/trade is the channel name and BTCUSDT is the trading side

Response

{
  "group":"futures/trade:BTCUSDT",
  "data":[{
    "symbol":"BTCUSDT",
    "deal_price":"117387.58",
    "deal_vol":"1445",
    "created_at":"2023-02-24T07:54:11.124940968Z"
  }]
}

Instruction

Description of the depth details field:

【Public】klineBin Channel

Get individual contract K-line data and push updates as soon as they are available without user login.

Pushing Rules

1. No user login required
2. After subscribing, the current data will be returned directly, and then the changes will be pushed

Example

Request

{"action":"subscribe","args":["futures/klineBin1m:BTCUSDT"]}

futures/klineBin1m is the channel name, BTCUSDT is the trading pair

Channel List

Response

{
    "group":"futures/klineBin1m:BTCUSDT",
    "data":{
            "symbol":"BTCUSDT",
            "o":"146.24",
            "h":"146.24",
            "l":"146.24",
            "c":"146.24",
            "v":"146"
        }
}

Parameter Type Description:

【Private】Login

Login Subscription Format

Request

{"action":"access","args":["<API_KEY>","<timestamp>","<sign>","<dev>"]}

API_KEY: The user's API key

timestamp: Timestamp, the unit is milliseconds, it will expire after 60 seconds

sign: Signature, sign=CryptoJS.HmacSHA256("" + "#" + "" + "#" + "bitmart.WebSocket", secret)

dev: Device, web eg.

Example

sign

sign=
   echo -n '1589267764859#test001#bitmart.WebSocket' | openssl dgst -sha256 -hmac "6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9"
 (stdin)= 3ceeb7e1b8cb165a975e28a2e2dfaca4d30b358873c0351c1a071d8c83314556

example

{"action": "access", "args": ["80618e45710812162b04892c7ee5ead4a3cc3e56", "1589267764859", "3ceeb7e1b8cb165a975e28a2e2dfaca4d30b358873c0351c1a071d8c83314556","web"]}

Response

{"action":"access","success":true}

Assume that the values of the API requested by the user is as follows:

timestamp=1589267764859

API_KEY = "80618e45710812162b04892c7ee5ead4a3cc3e56"

API_SECRET = "6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9"

API_MEMO = "test001";

If success field of return data is true, it indicates success

【Private】Assets Channel

Asset balance change channel, any changes will be pushed immediately.

Example

Request

{
    "action": "subscribe",
    "args":["futures/asset:USDT", "futures/asset:BTC", "futures/asset:ETH"]
}

Supported asset types for subscription are: USDT (U-native), BTC (coin-native), ETH (coin-native)

Return

{
  "group": "futures/asset:BTC",
  "data": {
    "currency": "BTC",
    "available_balance": "1000",
    "position_deposit": "1000",
    "frozen_balance": "1000"
  }
}

Parameter Type Description:

【Private】Position Channel

Position channel, any changes will be pushed immediately.

Push rules

1. user login required
2. 10 seconds timed push

Example

Request

{
    "action": "subscribe",
    "args":["futures/position"]
}

return

{
  "group": "futures/position",
  "data": [
    {
      "symbol": "BTCUSDT",
      "hold_volume": "2000",
      "position_type": 1,
      "open_type": 1,
      "frozen_volume": "0",
      "close_volume": "0",
      "hold_avg_price": "19406.2092",
      "close_avg_price": "0",
      "open_avg_price": "19406.2092",
      "liquidate_price": "15621.998406",
      "create_time": 1662692862255,
      "update_time": 1662692862255
    }
  ]
}

Parameter Type Description:

Error Code

Restful Error Code

List of global HTTP return codes

Authentication Error Code

Example: httpStatus:200, body:{"code": 1000, "message": "OK", "trace": "12323-3243242-34334534-4353","data":{}}

Contract API Error Code

Example: httpStatus:400, body:{"code": 40001, "message":"out_trade_no not found", "trace":"8bynjk-nmoew-sd1221-csd-123" }