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
contract_id Contract ID The contract ID is the basic unit of contract trading, including the target currency and margin type. Take BTC-USDT as an example, BTC is the target currency, and USDT is the margin type. It could be further divided into USD margin and USDT margin types

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

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:

Interface Description Authentication Type Permissions
/contract/v1/tickers Get tickers data NONE No permission required
/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
/account/v1/margin/isolated/account Get Margin Account Details(Isolated) X-BM-KEY 30 times/5 sec
/account/v1/margin/isolated/transfer Margin Asset Transfer X-BM-KEY 5 times/5 sec
Contract Interface Interface Name Limit Target Rate Special Remarks
/contract/v1/tickers Get the latest market quotations of the contract IP 10 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
/margin/v1/isolated/borrow Margin Borrow (Isolated) X-BM-KEY 5 times/5 sec
/margin/v1/isolated/repay Margin Repay (Isolated) X-BM-KEY 5 times/5 sec
/margin/v1/isolated/borrow_record Get Borrow Record(Isolated) X-BM-KEY 150 times/5 sec
/margin/v1/isolated/repay_record Get Repayment Record(Isolated) X-BM-KEY 150 times/5 sec
/margin/v1/isolated/pairs Get Trading Pair Borrowing Rate and Amount X-BM-KEY 5 times/5 sec

Market Data

Get the latest market quotations of the futures

Get the latest market quotations of the futures (Authentication type: NONE, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/contract/v1/tickers

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/contract/v1/tickers?contract_symbol=ETHUSDT
Field Type Required? Description
contract_symbol string No Contract Trading pair: contract_symbol (Optional, return the market information of all trading pairs by default)

Response Data

Response

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
    "tickers": [
      {
        "contract_symbol":"ETHUSDT",
        "last_price":"3060.86",
        "index_price":"3059.59772727",
        "last_funding_rate":"0.00010000",
        "price_change_percent_24h":"11.242",
        "volume_24h":"1435266.349217253",
        "url":"https://futures.bitmart.com/en?contract_symbol=ETHUSDT"
      }
    ]
  }
}
Field Type Description
contract_symbol string name of contract trading
last_price string last price of contract
index_price string indexPrice of contract
last_funding_rate string last funding rate
price_change_percent_24h string The ratio of price increase and decrease in the last 24 hours
volume_24h string 24-hour volume
url string Link to the trading page on the BitMart website

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 500
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
This contract is not found 40034 400

Change Log

2021-08-07