Change Log

2023-05-18

• New endpoints for transfer
  • /account/v1/transfer-contract
  • /account/v1/transfer-contract-list

2023-03-23

• New endpoints for websocket order notify
  • /contract/public/websocket/order

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

• New websocket for public data
  • /contract/public/websocket

2022-08-23

• New endpoints for get current funding rate of a specified contract
  • /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

Introduction

API Key Create

• Many APIs require an API Access Key for access. Please refer to this page to set up.
• When setting up an API Access Key, it is recommended to set up an IP access whitelist for security purposes.
• Never give your API Access key/secret key to anyone.

After creating an API Key, you will receive three pieces of information that you must remember:

• Access Key: represents the identity of the account, this is your api key
• Secret Key: used for API signature
• Memo: used for API signature

The Access Key and Secret Key will be randomly generated and provided by BitMart, and the Memo will be provided by you to ensure the security of API access.

API Key Permission Settings

• The default permission of a newly created API is Read-Only.
• To withdraw funds through the API, you need to modify the permissions in the UI and select Withdraw.
• Permission descriptions:
  • Read-only (query spot trading orders, query contract trading orders, query funds)
  • Spot-Trade (place orders, cancel orders)
  • Withdraw (withdraw funds)
  • Margin-Trade (repayment, borrowing, placing orders, etc.)
  • Contract-Trade (long position, short position, closing position, etc.)

Read-Only Permissions:

Withdraw Permissions:

Spot-Trade Permissions:

Margin-Trade Permissions:

Contract-Trade Permissions:

API Library

In order to facilitate access, we provide SDK in some languages for reference. For more programming codes, please refer to the Quick Start API on the page.

1. BitMart Golang SDK

The Websocket code quickly implements a lightweight code library, including HTTP requests for all BitMart API interfaces and subscriptions to websocket public and private channels, and can be used after being cloned. This is written specifically for Golang developers.

https://github.com/bitmartexchange/bitmart-go-sdk-api

2. BitMart Python SDK

The Websocket code quickly implements a lightweight code library, including HTTP requests for all BitMart API interfaces and subscriptions to websocket public and private channels, and can be used after being cloned. This is written specifically for Python developers.

https://github.com/bitmartexchange/bitmart-python-sdk-api

3. BitMart Java SDK

The Websocket code quickly implements a lightweight code library, including HTTP requests for all BitMart API interfaces and subscriptions to websocket public and private channels, and can be used after being cloned. This is written specifically for Java developers.

https://github.com/bitmartexchange/bitmart-java-sdk-api

4. BitMart PHP SDK

The Websocket code quickly implements a lightweight code library, including HTTP requests for all BitMart API interfaces and subscriptions to websocket public and private channels, and can be used after being cloned. This is written specifically for PHP developers.

https://github.com/bitmartexchange/bitmart-php-sdk-api

5. BitMart PostMan API

There is now a BitMart Postman collection containing the API endpoints for quick and easy use.

FAQ

Here are some frequently asked questions.

Q1. Will different API KEY in the same account return different data?

Q2. How to fill information in when applying for APIKEY?

Q3. How is the HTTP status code 429 created?

Q4. Using ccxt, the API KEY is correctly filled in, but it will also prompt 'message': 'Header X-BM-SIGN is wrong'

Q5. The program I wrote myself always prompts 'message': 'Header X-BM-SIGN is wrong'

Q6. Where is the location of BitMart servers?

Q7. When will the VIP fee I applied for take effect?

Contact Us

• Get support in our Telegram group BitMart API Club
• Please take 1 minute to help us improve: API Satisfaction Survey

Basic Information

API Basic Information

1. This article lists the rest baseurl of the interfaces: https://api-cloud.bitmart.com
2. All interface responses are in JSON format.

Request Parameter Settings

• For GET and DELETE method interfaces, parameters must be sent in the query string, i.e., the parameters concatenated after the URL?.
• For POST and PUT method interfaces, parameters are sent in the request body 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

• code Error code
• message Error description
• trace Event tracking ID for each request, which is returned by the server for every request
• data User Data

For details, please refer to Error Code List

Signature

The authentication type of each API endpoint will be indicated. If it is marked as SIGNED,it means that the endpoint requires a signature to access. If it is marked as KEYED, it means that the endpoint only requires an API Access KEY to be set in the request header.

Authentication Type

• NONE: Public endpoint, accessible to anyone
• KEYED: Endpoint requires a valid X-BM-KEY to be set in the request header
• SIGNED: Endpoint requires a valid X-BM-KEY and X-BM-SIGN signature to be set in the request header

1. Setting Request Parameters

1.1 Set Request Header Key

Create X-BM-TIMESTAMP

// Java
System.currentTimeMillis();

// Python
int(time.time() * 1000) 

// Golang
time.Now().UnixNano() / int64(time.Millisecond)

// Nodejs & TypeScript
Date.now();

// Javascript
Date.now();

// PHP
round(microtime(true) * 1000)

// C#
DateTimeOffset.UtcNow.ToUnixTimeMilliseconds()

• X-BM-KEY (Your created API Access KEY)
• X-BM-SIGN (Signature using Sha-256)
• X-BM-TIMESTAMP (Current timestamp in milliseconds when the request is sent)

1.2 Set Request Body Params

• For GET/DELETE requests, the query string is in form format, such as symbol=BMX&side=BUY.
• For POST/PUT requests, the query string is in JSON format, such as {"symbol":"BMX","side":"BUY"}.

2. Example

Shell Example

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"}'

• Request API: /spot/v1/test-post (SIGNED)
• Request method: POST
• Current timestamp: timestamp=1589793796145
• Request body: {"symbol":"BTC_USDT","price":"8600","count":"100"}

Then set the following:

• X-BM-TIMESTAMP=1589793796145
• X-BM-KEY=Your_api_access_key
• X-BM-SIGN= hmac_sha256(Your_api_secret_key, X-BM-TIMESTAMP + '#' + Your_api_memo + '#' + {"symbol":"BTC_USDT","price":"8600","count":"100"})

Assuming the key you applied for is as follows:

• accessKey=80618e45710812162b04892c7ee5ead4a3cc3e56
• secretKey=6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9
• memo=test001

then the right side is a complete request

You can also refer to the SDK or Quick Start API below to implement

Rate Limit

The speed of the public interface is limited according to the IP, and the speed of the private interface is limited according to the API KEY. When the requests exceed the rate limit, the 429 status will be returned: the request is too frequent.

The specific interface limits are as follows:

REST API

Speed limit judgment:

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

Futures Public API Definitions

Field description

Field description

• symbol is the name of the trading pair, consisting of the trading currency and the quote currency. Taking BTCUSDT as an example, BTC is the transaction currency, USDT is the pricing currency, and the transaction pair is mainly used in contract transactions
• order_id order number, the order ID of the same currency pair of each business line is unique

Order State（Field:state)

• 2=status_check
• 4=status_finish

Order Side（Field:side)

• 1=buy_open_long
• 2=buy_close_short
• 3=sell_close_long
• 4=sell_open_short

Position（Field:position_type)

• 1=long
• 2=short

Order Type（Field:type)

• limit
• market
• liquidate
• bankruptcy

Open Type（Field:open_type)

• cross
• isolated

Order Mode（Field:mode)

• 1=GTC (Good Till Cancel)
• 2=FOK (Fill or Kill)
• 3=IOC (Immediate or Cancel)
• 4=Maker Only (Good Till Crossing)

Timestamp

All the times returned by the system are in the form of timestamps.

Futures Market Data

Get Contract Details

Applicable to query contract details

Request URL

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?symbol=BTCUSDT

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",
        "funding_rate": "0.0001",
        "expected_funding_rate": "0.00011",
        "open_interest": "4134180870",
        "open_interest_value": "94100888927.0433258"
      },
      ...
    ]
  }
}

Description of the trading pair details field:

Get Market Depth

Get full depth of trading pairs.

Request URL

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

Request URL

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

Request URL

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",
    "expected_rate": "0.000164"
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}

Get K-line

Applicable for querying K-line data

Request URL

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 (KEYED)

Applicable for querying user contract asset details

Request URl

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request None

curl -H 'X-BM-KEY:{{AccessKey}}'
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 (KEYED)

Applicable for querying contract order detail

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
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 (KEYED)

Applicable for querying contract order history

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
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 (KEYED)

Applicable for checking the position details a specified contract

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/contract/private/position?symbol=BTCUSDT

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": [
    {
      "symbol": "BTCUSDT",
      "leverage": "5",
      "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",
      "open_avg_price": "20200",
      "current_amount": "899",
      "unrealized_value": "1903.956643943943943944339",
      "realized_value": "55.049173071454605573",
      "position_type": 2
    }
  ],
  "trace": "ae96cae5-1f09-4ea5-971e-4474a6724bc8"
}

Get Order Trade (KEYED)

Applicable for querying contract order trade detail

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
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"
}

Get Transfer List (SIGNED)

Query futures account transfer records

Request URl

POST https://api-cloud.bitmart.com/account/v1/transfer-contract-list

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "currency":"USDT",
    "time_start":1684391137804,
    "time_end":1684392577804,
    "page":1,
    "limit":10,
    "recvWindow":5000
}'
https://api-cloud.bitmart.com/account/v1/transfer-contract-list

Note

• If the time range time_start and time_end are not filled in, all data will be displayed by default.
• When filling in the time range, time_end must be greater than the value of time_start.
• If only time_start is filled in, query the historical records starting from the timestamp.
• If only time_end is filled in, query the historical records starting from this timestamp.

Response Data

Response

{
    "message":"OK",
    "code":1000,
    "trace":"82abff12-b9d9-4f66-89ea-3b604c6d84",
    "data":{
        "records":[{
            "transfer_id":"664651258694168576",
            "currency":"USDT",
            "amount":"0.1",
            "type":"contract_to_spot",
            "state":"FINISHED",
            "timestamp":1638631674326
        }]
    }
}

Submit Order (SIGNED)

Applicable for placing contract orders

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"ETHUSDT",
  "side":4,
  "mode":1,
  "type":"limit",
  "leverage":"1",
  "open_type":"isolated",
  "size":10,
  "price":"2000"
}'
https://api-cloud.bitmart.com/contract/private/submit-order

Response Data

Response

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

Cancel Order (SIGNED)

Applicable for canceling a specific contract order

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"ETHUSDT",
  "order_id": "220906179559421"
}'
https://api-cloud.bitmart.com/contract/private/cancel-order

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 (SIGNED)

Applicable for batch order cancellation under a particular contract

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"ETHUSDT"
}'
https://api-cloud.bitmart.com/contract/private/cancel-orders

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 Order (SIGNED)

Applicable for placing contract plan orders

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "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
}'
https://api-cloud.bitmart.com/contract/private/submit-plan-order

Response Data

Response

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

Cancel Plan Order (SIGNED)

Applicable for canceling a specific contract plan order

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"ETHUSDT",
  "order_id": "220906179559421"
}'
https://api-cloud.bitmart.com/contract/private/cancel-plan-order

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

Transfer (SIGNED)

Transfer between spot account and contract account

Request URl

POST https://api-cloud.bitmart.com/account/v1/transfer-contract

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "currency":"USDT",
  "amount":"10",
  "type":"spot_to_contract",
  "recvWindow":5000
}'
https://api-cloud.bitmart.com/account/v1/transfer-contract

Response Data

Response

{
  "message":"OK",
  "code":1000,
  "trace":"34018ca3-fe24-446a-9e1d-f82edfb3e3",
  "data":{
    "currency":"USDT",
    "amount":"10"
  }
}

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",
          "ask_price": "147.11",
          "bid_price": "142.11"
        }
}

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:

【Private】Order Channel

Order Channel, which pushes immediately when the order status, transaction amount, etc. changes.

Example

request

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

back

{
  "group": "futures/order",
  "data": [
    {
      "action": 3,
      "order": {
        "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,
        "plan_order_id":"220901412155341"
      }
    }
  ]
}

返回参数说明:

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" }