NAV
Example

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

Field Description Details
currency Currency Currency refers to the basic unit that can be transferred in and out, such as BTC, ETH, EOS, etc
symbol_id Trading pair id The unique number of the trading pair, such as the ID of BTC_USDT is 53, mainly used in the Websocket interface
symbol Trading pair name Consists of base and quote currency. Taking BTC_USDT as an example, BTC is the base currency, and USDT is the quote currency. Trading pairs are mainly used in spot trading

Contract

Field Description Details
symbol Trading pair name Consists of base and quote currency. Taking BTCUSDT as an example, BTC is the base currency, and USDT is the quote currency. Trading pairs are mainly used in contract trading

Order and Trade ID

Field Description
order_id Order number, the order ID under the same currency pair of each business line is unique
trade_id The unique number of the trade

Time

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

Field Description
s_t accurate to seconds of timestamp
ms_t accurate to milliseconds of timestamp

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

2022-09-22

2022-08-23

2022-08-18

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

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:

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

PNG

Click the API Settings button to enter the CREATE API page

PNG

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:

Interface Content Type

GET/DELETE

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

# queryString: symbol=BMXBTC&side=BUY

POST/PUT

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

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

3.Signature

SIGN

sign=CryptoJS.HmacSHA256(timestamp + "#" + memo + "#" + queryString, SecretKey)

The request header of X-BM-SIGN is obtained by encrypting the timestamp + "#" + memo + "#" + queryString, and the secret key using the HMAC SHA256 method.

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

4.Timestamp

The timestamp of the request. (UTC0 time zone Unix timestamp accurate to milliseconds) 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.

Key Value
accessKey 80618e45710812162b04892c7ee5ead4a3cc3e56
secretKey 6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9
memo test001

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

Parameter Value
symbol BTC_USDT

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

Parameter Value
symbol BTC_USDT
price 8600
count 100

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.

Field Description
code Error code,See Details
message Error message
trace Each request event tracking ID, the server will return for each request
data Data returned by the server

2.WebSocket Interface

No description.

Authentication Type

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

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:

Interface Type Authentication Type Description
Public NONE X-BM-KEY is not required, X-BM-SIGN is not required
Private KEYED X-BM-KEY is required, X-BM-SIGN is not required
Private SIGNED X-BM-KEY is required, X-BM-SIGN is required

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:

Spot Interface Description Authentication Type Permissions
/contract/public/details Get a detailed list of all trading pairs NONE No permission required
/contract/public/depth Get full depth of trading pairs NONE No permission required
/contract/public/open-interest Get Contract Openinterest NONE No permission required
/contract/private/submit-order Submit Contract Order SIGNED Trading Permission
/contract/private/cancel-order Cancel Contract Order SIGNED Trading Permission
/contract/private/cancel-orders Batch Cancel Contract Orders SIGNED Trading Permission
/contract/private/order Get Contract Order Detail KEYED Read-Only Permission
/contract/private/order-history Get Contract Order History KEYED Read-Only Permission
/contract/private/trades Get Contract Order Trade Detail KEYED Read-Only Permission
/contract/private/assets-detail Get Contract Assets Detail KEYED Read-Only Permission
/contract/private/position Get Current Position Detail KEYED Read-Only Permission
/contract/public/funding-rate Get Current Funding Rate NONE No permission required
/contract/public/kline Get K-line NONE No permission required
Spot Interface Description Authentication Type Permissions
/spot/v1/currencies Get a list of all cryptocurrencies on the platform NONE No permission required
/spot/v1/symbols Get a list of all trading pairs on the platform NONE No permission required
/spot/v1/symbols/details Get a detailed list of all trading pairs on the platform NONE No permission required
/spot/v1/ticker Get ticker NONE No permission required
/spot/v1/steps Get K-Line steps NONE No permission required
/spot/v1/symbols/kline Get K-Line NONE No permission required
/spot/v1/symbols/book Get orderbook NONE No permission required
/spot/v1/symbols/trades Get recent trades NONE No permission required
/spot/v1/wallet Get user wallet KEYED Read-Only Permission
/spot/v1/submit_order Place order SIGNED Trading Permission
/spot/v1/cancel_order Cancel order SIGNED Trading Permission
/spot/v1/cancel_orders Cancel all orders SIGNED Trading Permission
/spot/v1/order_detail Get order detail KEYED Read-Only Permission
/spot/v1/orders Get user orders KEYED Read-Only Permission
/spot/v1/trades Get user trades KEYED Read-Only Permission

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
Response Header Description
X-BM-RateLimit-Remaining The number of requests left in the current time window
X-BM-RateLimit-Limit The max number of requests in the current time window
X-BM-RateLimit-Reset Current time window, in seconds

The specific interface limits are as follows:

System Interface Interface Name Limit Target Rate
/system/time Get system time IP 10 times/sec
/system/service Get system service status IP 10 times/sec
Funding Account Interface Interface Name Limit Target Rate Special Remarks
/account/v1/currencies Get currencies IP 5 times/5 sec
/account/v1/wallet Get account balance X-BM-KEY 30 times/5 sec
/account/v1/deposit/address Deposit address X-BM-KEY 5 times/5 sec
/account/v1/withdraw/charge Withdraw quota X-BM-KEY 5 times/5 sec
/account/v1/withdraw/apply Withdraw X-BM-KEY 20 times/5 sec
/account/v2/deposit-withdraw/history Get deposit and withdraw history V2 X-BM-KEY 20 times/5 sec
/account/v1/deposit-withdraw/detail Get a deposit Or withdraw detail X-BM-KEY 20 times/5 sec
/spot/v1/margin/isolated/account Get Margin Account Details(Isolated) X-BM-KEY 30 times/5 sec
/spot/v1/margin/isolated/transfer Margin Asset Transfer X-BM-KEY 5 times/5 sec
/spot/v1/user_fee Basic Fee Rate X-BM-KEY 5 times/5 sec
/spot/v1/trade_fee Actual Trade Fee Rate X-BM-KEY 5 times/5 sec
Contract Interface Interface Name Limit Target Rate Special Remarks
/contract/public/details Get a detailed list of all trading pairs IP 30 times/5 sec
/contract/public/depth Get full depth of trading pairs IP 30 times/5 sec
/contract/public/open-interest Get Contract Openinterest IP 5 times/5 sec
/contract/private/submit-order Submit Contract Order X-BM-KEY 60 times/5 sec
/contract/private/cancel-order Cancel Contract Order X-BM-KEY 100 times/5 sec
/contract/private/cancel-orders Batch Cancel Contract Orders X-BM-KEY 5 times/5 sec
/contract/private/order Get Contract Order Detail X-BM-KEY 125 times/5 sec
/contract/private/order-history Get Contract Order History X-BM-KEY 15 times/5 sec
/contract/private/trades Get Contract Order Trade Detail X-BM-KEY 15 times/5 sec
/contract/private/assets-detail Get Contract Assets Detail X-BM-KEY 30 times/5 sec
/contract/private/position Get Current Position Detail X-BM-KEY 15 times/5 sec
/contract/public/funding-rate Get Current Funding Rate IP 5 times/5 sec
/contract/public/kline Get K-line IP 30 times/5 sec
Spot Interface Interface Name Limit Target Rate Special Remarks
/spot/v1/currencies Get a list of all cryptocurrencies IP 20 times/5 sec
/spot/v1/symbols Get a list of all trading pairs IP 20 times/5 sec
/spot/v1/symbols/details Get a detailed list of all trading pairs IP 30 times/5 sec
/spot/v1/ticker Get ticker IP 30 times/5 sec
/spot/v1/steps Get K-Line steps IP 5 times/5 sec
/spot/v1/symbols/kline Get k-Line IP 30 times/5 sec
/spot/v1/symbols/book Get orderbook IP 30 times/5 sec
/spot/v1/symbols/trades Get the latest trades IP 30 times/5 sec
/spot/v1/wallet Get the user's wallet balance X-BM-KEY 30 times/5 sec
/spot/v1/submit_order Place spot order X-BM-KEY 150 times/5 sec
/spot/v1/margin/submit_order Place margin order X-BM-KEY 150 times/5 sec
/spot/v2/cancel_order Cancel order X-BM-KEY 150 times/5 sec
/spot/v1/cancel_orders Cancel all orders in the specified direction of the specified trading pair X-BM-KEY 10 times/5 sec
/spot/v1/order_detail Get order details X-BM-KEY 150 times/5 sec
/spot/v2/orders Get user's recent orders V2 X-BM-KEY 30 times/5 sec
/spot/v1/trades User trade records X-BM-KEY 30 times/5 sec
/spot/v1/batch_orders Batch order X-BM-KEY 150 times/5 sec
Sub-Account Interface Interface Name Limit Target Rate Special Remarks
/account/sub-account/main/v1/sub-to-main Sub-Account Spot Asset Transfer (For Main Account) X-BM-KEY 5 times/5 sec
/account/sub-account/sub/v1/sub-to-main Sub-Account Spot Asset Transfer (For Sub-Account) X-BM-KEY 5 times/5 sec
/account/sub-account/main/v1/main-to-sub Main Account Spot Asset Transfer (For Main Account) X-BM-KEY 5 times/5 sec
/account/sub-account/sub/v1/sub-to-sub Sub-Account to Sub-Account Spot Asset Transfer (For Sub-Account) X-BM-KEY 5 times/5 sec
/account/sub-account/main/v1/sub-to-sub Sub-account to Sub-Account Spot Asset Transfer (For Main Account) X-BM-KEY 5 times/5 sec
/account/sub-account/main/v1/transfer-list Query Sub-account Spot Asset Transfer History (For Main Account) X-BM-KEY 20 times/5 sec
/account/sub-account/v1/transfer-history Get Account Spot Asset Transfer History X-BM-KEY 20 times/5 sec
/account/sub-account/main/v1/wallet Get Sub-Account Spot Wallet Balance (For Main Account) X-BM-KEY 30 times/5 sec
/account/sub-account/main/v1/subaccount-list Get Sub-account List (For Main Account) X-BM-KEY 20 times/5 sec
Margin Loan Interface Interface Name Limit Target Rate Special Remarks
/spot/v1/margin/isolated/borrow Margin Borrow (Isolated) X-BM-KEY 5 times/5 sec
/spot/v1/margin/isolated/repay Margin Repay (Isolated) X-BM-KEY 5 times/5 sec
/spot/v1/margin/isolated/borrow_record Get Borrow Record(Isolated) X-BM-KEY 150 times/5 sec
/spot/v1/margin/isolated/repay_record Get Repayment Record(Isolated) X-BM-KEY 150 times/5 sec
/spot/v1/margin/isolated/pairs Get Trading Pair Borrowing Rate and Amount X-BM-KEY 5 times/5 sec

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

Field Type Required? Description
symbol string No Symbol of the contract(like 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",
        "funding_rate": "0.000074865",
        "contract_size": "0.001",
        "min_leverage": "1",
        "max_leverage": "100",
        "price_precision": "0.1",
        "vol_precision": "1",
        "max_volume": "500000",
        "min_volume": "1"
      },
      ...
    ]
  }
}
Field Type Description
symbols list Array of trading pair details

Description of the trading pair details field:

Trading pair details Type Description
symbols list Array of trading pair details
symbol string Symbol of the contract
product_type int Contract type
1=perpetual
2=futures
base_currency string Base currency
quote_currency string Quote currency
volume_precision string Volume Precision
price_precision string Price Precision
max_volume string Maximum order quantity
min_volume string Minimum order quantity
funding_rate string Funding Rate
contract_size string Contract Size
index_price string Index Price
index_name string Index Name
min_leverage string Minimum leverage ratio
max_leverage string Maximum leverage ratio
turnover_24h string 24 hours turnover
volume_24h string 24 hours volume
last_price string Last Price
open_timestamp long Opening time for the first time
expire_timestamp long Expiration time,If null is returned, it does not expire
settle_timestamp long Settlement time,If null is returned, it will not be automatically settlement

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
Field Type Required? Description
symbol string Yes Symbol of the contract(like 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"
  }
}
Field Type Description
timestamp long Unix timestamp in milliseconds for when the last updated time occurred
bids list Bid order depth
asks list Ask order depth

Market depth details:

Field Type Description
The first string The price at current depth. For example 23935.4
The second string Total quantity of current price depth. For example 65
The third string Accumulates the total quantity above (including) the current price depth. For example 65

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

Field Type Required? Description
symbol string Yes Symbol of the contract(like 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"
  }
}
Field Type Description
timestamp long Timestamp
symbol string Symbol of the contract
open_interest string Open interest
open_interest_value string Value of open interest

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

Field Type Required? Description
symbol string Yes Symbol of the contract(like BTCUSDT)

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "timestamp": 1662518172178,
    "symbol": "BTCUSDT",
    "rate_value": "0.000164"
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}
Field Type Description
timestamp long Timestamp
symbol string Symbol of the contract
rate_value string Value of current rate

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

Field Type Required? Description
symbol string Yes Symbol of the contract(like BTCUSDT)
step long No K-Line step, default is 1 minute. step: 1, 3, 5, 15, 30, 60, 120, 240, 360, 720, 1440, 4320, 10080
start_time long Yes Start time. Timestamps need to be in seconds
end_time long Yes End time. Timestamps need to be in seconds

Response Data

Response

{
  "code": 1000,
  "trace": "0cc6f4c4-8b8c-4253-8e90-8d3195aa109c",
  "message": "Ok",
  "data": {
    "timestamp": 1661239541734,
    "open_price": "100",
    "close_price": "120",
    "high_price": "130",
    "low_price": "90",
    "volume": "941008"
  }
}
Field Type Description
timestamp long Time Window
open_price string Opening Price
close_price string Closing Price
high_price string Highest Price
low_price string Lowest Price
volume string Turnover

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": "ETH",
    "available_balance": "99999.998702963091765039",
    "frozen_balance": "0",
    "unrealized": "-0.0010830486873508752",
    "equity": "99999.9987825720750270548",
    "position_deposit": "0.001162657670612891"
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}
Field Type Description
currency string Currency
position_deposit string Position margin
frozen_balance string Transaction freeze amount
available_balance string Available amount
equity string Total equity
unrealized string Unrealized P&L

Futures Trading

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,
  "type":"limit",
  "leverage":"1",
  "open_type":"isolated",
  "size":10,
  "price":"2000"
}
Field Type Required? Description
symbol string Yes Symbol of the contract(like BTCUSDT)
type string No Order type limit or market. The default value is limit
side int Yes Order side
1=buy_open_long
2=buy_close_short
3=sell_close_long
4=sell_open_short
leverage string Yes Leverage order multipliers
open_type string Yes Open type cross or isolated. required at close position
price string Yes Order price, required at limit order
size int Yes Order size. Size refers to the order amount in the unit of contracts

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "order_id": "220609666322019"
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}
Field Type Description
order_id string Order ID

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"
}
Field Type Required? Description
symbol string Yes Symbol of the contract(like BTCUSDT)
order_id string Yes Order ID

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"
}
Field Type Required? Description
symbol string Yes Symbol of the contract(like BTCUSDT)

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

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

Field Type Required? Description
symbol string Yes Symbol of the contract(like BTCUSDT)
order_id string Yes Order ID

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"
}
Field Type Description
symbol string Symbol of the contract
order_id string Order ID
side int Order side
1=buy_open_long
2=buy_close_short
3=sell_close_long
4=sell_open_short
type string Order type limit or market
leverage string Leverage order multipliers
open_type string Open type cross or isolated
deal_avg_price string Average deal price
deal_size string Deal amount
price string Consignment price
state int Order status
2=status_check
4=status_finish
create_time long Create time
update_time long Update time

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

Field Type Required? Description
symbol string Yes Symbol of the contract(like BTCUSDT)
start_time timestamp No Start time, default is the last 7 days
end_time timestamp No End time, default is the last 7 days

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"
}
Field Type Description
symbol string Symbol of the contract
order_id string Order ID
side int Order side
1=buy_open_long
2=buy_close_short
3=sell_close_long
4=sell_open_short
type string Order type limit or market
leverage string Leverage order multipliers
open_type string Open type cross or isolated
deal_avg_price string Average deal price
deal_size string Deal amount
price string Consignment price
state int Order status
2=status_check
4=status_finish
create_time long Create time
update_time long Update time

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

Field Type Required? Description
symbol string Yes Symbol of the contract(like 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",
      "close_vol": "100",
      "close_avg_price": "20700.7",
      "current_amount": "899",
      "unrealized_value": "1903.956643943943943944339",
      "realized_value": "55.049173071454605573"
    }
  ],
  "trace": "ae96cae5-1f09-4ea5-971e-4474a6724bc8"
}
Field Type Description
leverage string Leverage multiplier
symbol string Symbol of the contract
current_fee string Current position fees
open_timestamp long Opening timestamp
current_value string Current position value
mark_price string Marker price
position_value string Position value
close_avg_price string Close volume
close_vol string Close average price
position_cross string Margin calls to positions
current_amount string Current position amount
unrealized_value string Unrealized value
realized_value string Realized position value
timestamp long Current timestamp

Get Order Trade Detail

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

Request Format

POST 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

Field Type Required? Description
symbol string Yes Symbol of the contract(like BTCUSDT)
start_time timestamp No Start time, default is the last 7 days
end_time timestamp No End time, default is the last 7 days

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,
    "create_time": 1663663818589
  },
  "trace": "638d5048-ad21-4a4b-9365-d0756fbfc7ba"
}
Field Type Description
symbol string Symbol of the contract
order_id string Order ID
trade_id string Trade detail ID
side int Order side
1=buy_open_long
2=buy_close_short
3=sell_close_long
4=sell_open_short
price string Deal price
vol string Deal vol
profit boolean Profitable or not
exec_type string Liquidity type Taker or Maker
create_time long Create time

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: Depth:1: which means ticker data of contract trading pair 1

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:

ws.send(new PingWebSocketFrame();

{"subscribe":"ping"}

Connection Limit

Public Channel

Channel limit
Numbers of connections per IP. 10
Times of connections request per minute 30
Minimum message pushing frequency 0.5 second
Message limit sent to the server 100/10 seconds
Maximum number of batch subscriptions at a time 20 topics
Subscription limit for each connection 100 topics

Private Channel

Channel limit
Numbers of connections per IP. 10
Times of connections request per minute 30
Minimum message pushing frequency 0.5
Message limit sent to the server 100/10 seconds
Maximum number of batch subscriptions at a time 20
Subscription limit for each connection 100

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":["Depth:1","Ticker"]}

Parameter Instructions

Example

Request

{"action":"subscribe","args":["Depth:1","Ticker"]}

Response

{"action":"subscribe","group":"Ticker","success":true,"request":{"action":"subscribe","args":["Ticker"]}}
{"action":"subscribe","group":"Depth:1","success":true,"request":{"action":"subscribe","args":["Depth:1"]}}
{"action":"subscribe","group":"QuoteBin15m:1","success":true,"request":{"action":"subscribe","args":["QuoteBin15m:1"]}}

Unsubscribe

Cancel subscription to one or more channels

unsubscribe

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

Parameter Instruction

Example

Request

{"action": "unsubscribe", "args": ["QuoteBin15m:1"]}

Response

{"action":"unsubscribe","group":"QuoteBin15m:1","success":true,"request":{"action":"unsubscribe","args":["QuoteBin15m:1"]}}

【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":["Ticker"]}

Ticker is the channel name

Response

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

Parameter Type Description:

Parameter Type Description
symbol string Symbol of the contract(like BTCUSDT)
last_price string Latest Price
volume_24 string Volume of 24-hour transactions
range string Up or Down
fair_price string Fair Price

【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":["asset:USDT", "asset:BTC", "asset:ETH"]
}

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

Return

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

Parameter Type Description:

Parameter Type Description
currency string Currency
available_balance string Available Amount
position_deposit string Position Margin
frozen_balance string Transaction Frozen Amount

【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":["position"]
}

return

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

Parameter Type Description
symbol string Contract pair (e.g. BTCUSDT)
hold_volume string Number of positions
position_type int Position type
1=long
2=short
open_type int Open position type
1=isolated
2=cross
frozen_volume string Frozen volume
close_volume string Close volume
hold_avg_price string Average price of a position
close_avg_price string Average close price
open_avg_price string Average opening price
liquidate_price string Liquidation price
create_time timestamp Create time
update_time timestamp Update time

Error Code

Restful Error Code

List of global HTTP return codes

HTTP Description
404 Not Found-The requested interface could not be found
403 Forbidden-No permission to access the resource (KEY may not have permission, or it may be IP restrictions)
401 Unauthorized-Authentication failed (there are problems with the 3 header parameters, failed)
500 Internal Server Error-Server exception, BitMart service problem

Authentication Error Code

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

error message code error code http status code
Not found 30000 404
Header X-BM-KEY is empty 30001 401
Header X-BM-KEY not found 30002 401
Header X-BM-KEY has frozen 30003 401
Header X-BM-SIGN is empty 30004 401
Header X-BM-SIGN is wrong 30005 401
Header X-BM-TIMESTAMP is empty 30006 401
Header X-BM-TIMESTAMP range. Within a minute 30007 401
Header X-BM-TIMESTAMP invalid format 30008 401
IP is forbidden. We recommend enabling IP whitelist for API trading. After that reauth your account 30010 403
Header X-BM-KEY over expire time 30011 403
Header X-BM-KEY is forbidden to request it 30012 403
Request too many requests 30013 429
Service unavailable 30014 503

Contract API Error Code

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

errMsg error message code error code http status code
OK 1000 200
Cloud account not found 40001 400
out_trade_no not found 40002 400
out_trade_no already existed 40003 400
Cloud account count limit 40004 400
Transfer vol precision error 40005 400
Invalid ip error 40006 400
Parse parameter error 40007 400
Check nonce error 40008 400
Check ver error 40009 400
Not found func error 40010 400
Invalid request 40011 400
System error 40012 400
Access too often" CLIENT_TIME_INVALID, "Please check your system time. 40013 400
This contract is offline 40014 400
This contract's exchange has been paused 40015 400
This order would trigger user position liquidate 40016 400
It is not possible to open and close simultaneously in the same position 40017 400
Your position is closed 40018 400
Your position is in liquidation delegating 40019 400
Your position volume is not enough 40020 400
The position is not exsit 40021 400
The position is not isolated 40022 400
The position would liquidate when sub margin 40023 400
The position would be warnning of liquidation when sub margin 40024 400
The position’s margin shouldn’t be lower than the base limit 40025 400
You cross margin position is in liquidation delegating 40026 400
You contract account available balance not enough 40027 400
Your plan order's count is more than system maximum limit. 40028 400
The order's leverage is too large. 40029 400
The order's leverage is too small. 40030 400
The deviation between current price and trigger price is too large. 40031 400
The plan order's life cycle is too long. 40032 400
The plan order's life cycle is too short. 40033 400
The Symbol is not exist 40034 400
The order is not exist 40035 400
The order status is invalid 40036 400
The order id is not exist 40037 400
The k-line step is invalid 40038 400
The timestamp is invalid 40039 400
The order leverage is invalid 40040 400
The order side is invalid 40041 400
The order type is invalid 40042 400
The order precision is invalid 40043 400
The order range is invalid 40044 400
The order open type is invalid 40045 400
The account is not opened futures 40046 403