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 20 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 10 times/5 sec
/account/v2/deposit-withdraw/history Get deposit and withdraw history V2 X-BM-KEY 10 times/5 sec
/account/v1/deposit-withdraw/detail Get a deposit Or withdraw detail X-BM-KEY 10 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 10 times/5 sec
/spot/v1/symbols Get a list of all trading pairs IP 10 times/5 sec
/spot/v1/symbols/details Get a detailed list of all trading pairs IP 10 times/5 sec
/spot/v1/ticker Get ticker IP 10 times/5 sec
/spot/v1/steps Get K-Line steps IP 5 times/5 sec
/spot/v1/symbols/kline Get k-Line IP 20 times/5 sec
/spot/v1/symbols/book Get orderbook IP 20 times/5 sec
/spot/v1/symbols/trades Get the latest trades IP 20 times/5 sec
/spot/v1/wallet Get the user's wallet balance X-BM-KEY 20 times/5 sec
/spot/v1/submit_order Place order X-BM-KEY 100 times/5 sec
/spot/v2/cancel_order Cancel order X-BM-KEY 100 times/5 sec
/spot/v1/cancel_orders Cancel all orders in the specified direction of the specified trading pair X-BM-KEY 100 times/5 sec
/spot/v1/order_detail Get order details X-BM-KEY 100 times/5 sec
/spot/v2/orders Get user's recent orders V2 X-BM-KEY 20 times/5 sec
/spot/v1/trades User trade records X-BM-KEY 20 times/5 sec
/spot/v1/batch_orders Batch order X-BM-KEY 100 times/5 sec

System Status

Get System Time

Get system time (Authentication type:NONE, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/system/time

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/system/time

None

Response Data

Response

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
    "server_time": 1527777538000
  }
}
Field Type Description
server_time long Current system time (timestamp, accuracy in milliseconds)

Get System Service Status

Get system service status (Authentication type:NONE, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/system/service

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/system/service

None

Response Data

Response

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
    "serivce":[
      {
         "title": "Spot API Stop",
         "service_type": "spot",
         "status": "2",
         "start_time": 1527777538000,
         "end_time": 1527777538000
     },
     {
        "title": "Contract API Stop",
        "service_type": "contract",
        "status": "2",
        "start_time": 1527777538000,
        "end_time": 1527777538000
    }
   ]
  }
}
Field Type Description
title string System maintenance instructions title
status long System maintenance status
0: Waiting
1: Working
2: Completed
service_type string Service type
spot=Spot API service
contract=Contract API service
start_time long System maintenance start time, UTC-0, timestamp accuracy in milliseconds
end_time long System maintenance end time, UTC-0, timestamp accuracy in milliseconds

Restful public Market Data

Get Currency List

Get a list of all cryptocurrencies on the platform (Authentication type:NONE, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/spot/v1/currencies

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v1/currencies

None

Response Data

Response

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
    "currencies": [
      {
        "id": "BTC",
        "name": "Bitcoin",
        "withdraw_enabled": true,
        "deposit_enabled": true
      },
      {
        "id": "ETH",
        "name": "Ethereum",
        "withdraw_enabled": true,
        "deposit_enabled": true
      }
    ]
  }
}
Field Type Description
id String Currency abbreviation, such as BTC
name String Currency full name, such as Bitcoin
withdraw_enabled Boolean Whether this currency can be withdrawn on the platform, true-can; false-no
deposit_enabled Boolean Whether this currency can be deposited on the platform, true-can; false-not

Get List of Trading Pairs

Get a list of all trading pairs on the platform (Authentication type:NONE, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/spot/v1/symbols

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v1/symbols

None

Response Data

Response

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
    "symbols": [
       "BMX_ETH",
       "XLM_ETH",
       "MOBI_ETH",
       ...
    ]
  }
}
Field Type Description
symbols List Array of trading pairs

Get List of Trading Pair Details

Get a detailed list of all trading pairs on the platform (Authentication type:NONE, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/spot/v1/symbols/details

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v1/symbols/details

None

Response Data

Response

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
    "symbols": [
        {
            "symbol":"GXC_BTC",
             "symbol_id":1024,
             "base_currency":"GXC",
             "quote_currency":"BTC",
             "quote_increment":"1.00000000",
             "base_min_size":"1.00000000",
             "base_max_size":"10000000.00000000",
             "price_min_precision":6,
             "price_max_precision":8,
             "expiration":"NA",
             "min_buy_amount":"0.00010000",
             "min_sell_amount":"0.00010000",
             "trade_status":"trading"
        },
        ...
    ]
  }
}
Field Type Description
symbols List Array of trading pair details

Instruction

Description of the trading pair details field:

Trading pair details Type Description
symbols List Array of trading pair details
symbol string Trading pair name
symbol_id int Trading pair id
base_currency string Base currency
quote_currency string Quote currency
quote_increment string The minimum order quantity is also the minimum order quantity increment
base_min_size string Minimum order quantity
base_max_size string Maximum order quantity
price_min_precision number Minimum price accuracy (decimal places), used to query k-line and depth
price_max_precision number Maximum price accuracy (decimal places), used to query k-line and depth
expiration string Expiration time of trading pair
min_buy_amount string Minimum order amount
min_sell_amount string Maximum order amount
trade_status string ’trading’,is trading;’pre-trade’,pre-open

Get Ticker

Ticker is an overview of the market status of a trading pair, including the latest trade price, top bid and ask prices and 24-hour trading volume (Authentication type:NONE, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/spot/v1/ticker

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v1/ticker?symbol=BTC_USDT
Field Type Required? Description
symbol String No Trading pair symbol (Optional, return ticker data of all trading pairs by default)

Response Data

Response

{
    "message":"OK",
    "code":1000,
    "trace":"6e42c7c9-fdc5-461b-8fd1-b4e2e1b9ed57",
    "data":{
        "tickers":[
            {
                "symbol":"BTC_USDT",
                "last_price":"1.00",
                "quote_volume_24h":"201477650.88000",
                "base_volume_24h":"25186.48000",
                "high_24h":"8800.00",
                "low_24h":"1.00",
                "open_24h":"8800.00",
                "close_24h":"1.00",
                "best_ask":"0.00",
                "best_ask_size":"0.00000",
                "best_bid":"0.00",
                "best_bid_size":"0.00000",
                "fluctuation":"-0.9999",
                "url":"https://www.bitmart.com/trade?symbol=BTC_USDT"
            }
        ]
    }
}
Field Type Description
symbol string Trading pair
last_price string Latest price
base_volume_24h string 24-hour trade volume in base currency
quote_volume_24h string 24-hour trade volume in quote currency
high_24h string 24-hour highest price
open_24h string 24-hour open price
low_24h string 24-hour lowest price
close_24h string 24-hour close price
fluctuation string 24-hour price change
best_ask string top ask price
best_ask_size string Size of top ask order
best_bid string top bid price
best_bid_size string Size of top bid order
url string Link to the trading page on BitMart

Get K-Line Step

Get all k-line steps supported by the platform, expressed in minutes, minimum 1 minute. (Authentication type:NONE, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/spot/v1/steps

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v1/steps?symbol=BMX_ETH

None

Response Data

Response

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
    "steps": [1, 3, 5, 15, 30, 45, 60, 120, 180, 240, 1440, 10080, 43200]
  }
}
Field Type Description
steps List List of K-Line steps in minutes

Get K-Line

Get k-line data within a specified time range of a specified trading pair (Authentication type:NONE, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/spot/v1/symbols/kline

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v1/symbols/kline?symbol=BMX_ETH&step=15&from=1525760116&to=1525769116
Field Type Required? Description
symbol string Yes Trading pair symbol
from long Yes Start timestamp (in seconds, UTC+0 TimeZome)
to long Yes End timestamp (in seconds, UTC+0 TimeZome)
step long No k-line step Steps (in minutes, default 1 minute)

Response Data

Response

{
    "message":"OK",
    "code":1000,
    "trace":"ae7ede4c-04a3-4004-bd8b-022a12d17e45",
    "data":{
        "klines":[
            {
                "timestamp":1590969600,
                "open":"1.2400000000",
                "high":"1.2400000000",
                "low":"1.2000000000",
                "close":"1.2000000000",
                "last_price":"1.2000000000",
                "volume":"4.9000000000",
                "quote_volume":"0.000000"
            }
        ]
    }
}
Field Type Description
kline List K-Line data

Description of k-line details field:

Field Type Description
last_price string Current price
timestamp long Timestamp (in seconds, UTC+0 TimeZome)
volume string Total volume
quote_volume string Transaction amount
high string Highest price
low string Lowest price
open string Open price
close string Close price

Get Depth

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

Request Format

GET https://api-cloud.bitmart.com/spot/v1/symbols/book

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v1/symbols/book?symbol=BMX_ETH&precision=6
Field Type Required? Description
symbol String Yes Trading pair symbol
precision String No Price precision, the range is defined in trading pair details
size Int No Number of results per request. The value can be transmitted [1-200], there are altogether [2-400] buying and selling depths

Instruction

  1. precision is optional. If not passed, the default is to use price_max_precision returned by symbols details.

  2. If the size is left blank, default 50 of data will be returned. If size is larger than '200', error code will be returned.

Response Data

Response

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
       "timestamp": 1527777538000,
       "buys":[
          {
             "amount":"4800.00",
             "total":"4800.00",
             "price":"0.000767",
             "count":"1"
          },
          {
             "amount":"99996475.79",
             "total":"100001275.79",
             "price":"0.000201",
             "count":"1"
          },
          ...
       ],
       "sells":[
          {
             "amount":"100.00",
             "total":"100.00",
             "price":"0.007000",
             "count":"1"
          },
          {
             "amount":"6997.00",
             "total":"7097.00",
             "price":"1.000000",
             "count":"1"
          },
          ...
       ]
  }
}
Field Type Description
timestamp long Unix timestamp in milliseconds for when the last updated time occurred
buys List Bid order depth
sells List Ask order depth

Market depth details:

Field Type Description
amount string Total amount of current price depth
total string Total accumulation above the current price depth (including current price)
price string The price at current depth
count string The number of orders at current depth

Get Recent Trades

Get the latest trade records of the specified trading pair (Authentication type:NONE, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/spot/v1/symbols/trades

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v1/symbols/trades?symbol=BMX_ETH
Field Type Description
symbol string Yes
N string No

Response Data

Response

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
    "trades": [
       {
          "amount":"0.05768509",
          "order_time":1527057452000,
          "price":"0.004811",
          "count":"11.99",
          "type":"buy"
       },
       ...
    ]
  }
}
Field Type Description
trades List List of trades

Depth data details field description:

Field Type Description
amount string Total trade value
order_time long Trade time (in milliseconds)
price string Trade price
count string Trade amount
type String Order type (buy or sell)

Funding Account

Get Account Balance

Gets Account Balance (Authentication type:KEYED, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/account/v1/wallet

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/account/v1/wallet?account_type=1
Field Type Required? Description
currency string No currency

Response Data

Response

{
    "message":"OK",
    "code":1000,
    "trace":"ef834248-51d3-4223-9481-f862aa9dd39f",
    "data":{
        "wallet":[
            {
                "currency":"USDT",
                "name":"Tether USD",
                "available":"1000.00000000",
                "frozen":"0.00000000"
            },
            {
                "currency":"BTC",
                "name":"Bitcoin",
                "available":"10000.00000000",
                "frozen":"10.00000000"
            }
        ]
    }
}
Field Type Description
currency string Token symbol, e.g., 'BTC'
name string Token name, e.g., 'Bitcoin'
available string Available Balance
frozen string Frozen Balance

Get Currencies

Gets the currency of the asset for withdrawal (Authentication type:None, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/account/v1/currencies

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/account/v1/currencies

None

Response Data

Response

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
    "currencies": [
      {
        "currency": "USDT",
        "name": "Tether USD",
        "network": "OMNI",
        "withdraw_enabled": false,
        "deposit_enabled": false
      },
      {
        "currency": "USDT-TRC20",
        "name": "USDT-TRC20",
        "network": "TRC20",
        "withdraw_enabled": true,
        "deposit_enabled": true
      },
      {
        "currency": "USDT-ERC20",
        "name": "USDT-ERC20",
        "network": "ERC20",
        "withdraw_enabled": true,
        "deposit_enabled": true
      },
      {
        "currency": "USDT-BSC",
        "name": "USDT-BSC",
        "network": "BEP20(BSC)",
        "withdraw_enabled": true,
        "deposit_enabled": true
      }
    ]
  }
}
Field Type Description
currency string Token symbol, e.g., 'BTC'
name string Token name, e.g., 'Bitcoin'
network string network, e.g., 'ERC20'
withdraw_enabled boolean Availability to withdraw, true - available; false - not available
deposit_enabled boolean Availability to deposit, true - available; false - not available

Get Spot Wallet Balance

Get the user's wallet balance for all currencies (Authentication type:NONE, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/spot/v1/wallet

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v1/wallet

None

Response Data

Response

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
    "wallet": [
         {
              "id": "BTC",
              "available": "10.000000",
              "name": "Bitcoin",
              "frozen": "10.000000",
          },
          ...
    ]
  }
}
Field Type Description
id string Cryptocurrency abbreviation
name string Full name
available string Available balance
frozen string Frozen balance

Deposit Address

Gets Deposit Address (Authentication type:KEYED, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/account/v1/deposit/address

Request Format

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/account/v1/deposit/address?currency=USDT-TRC20
Field Type Required? Description
currency string Yes Token symbol, e.g., 'BTC'

Instruction

PNG

Response Data

Response

{
    "message":"OK",
    "code":1000,
    "trace":"0e6edd79-f77f-4251-abe5-83ba75d06c1a",
    "data":{
        "currency":"USDT-TRC20",
        "chain":"USDT-TRC20",
        "address":"TGR3ghy2b5VLbyAYrmiE15jasR6aPHTvC5",
        "address_memo":""
    }
}
Field Type Description
currency string Token symbol, e.g., 'BTC'
chain string Token chain
address string Deposit address
address_memo string Tag (tag/payment_id/memo); If some currencies need to withdraw currency, it will return data. If not, it will return empty string

Forgot to write Memo/Wrote a wrong Memo?

Withdraw Quota

Query withdraw quota for currencies (Authentication type:KEYED, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/account/v1/withdraw/charge

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/account/v1/withdraw/charge?currency=BTC
Field Type Required? Description
currency string Yes Token symbol, e.g., 'BTC'

Response Data

Response

{
    "message":"OK",
    "code":1000,
    "trace":"62a80bde-0cb4-4bf1-b8e5-5ad2c71463e7",
    "data":{
        "today_available_withdraw_BTC":"100.0000",
        "min_withdraw":"0.00000000",
        "withdraw_precision":8,
        "withdraw_fee":"0.00000000"
    }
}
Field Type Description
today_available_withdraw_BTC String Amount available for withdrawal today, unit: BTC
min_withdraw string Minimum withdrawable amount
withdraw_precision int Withdrawal precision
withdraw_fee string Withdrawal fee

Withdraw

Creates a withdraw request from spot account to an external address (Authentication type:SIGNED, See Interface Permission)

Request Format

POST https://api-cloud.bitmart.com/account/v1/withdraw/apply

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/account/v1/withdraw/apply
{
    "currency": "USDT",
    "amount": "100.000",
    "destination": "To Digital Address",
    "address": "0x1EE6FA5A3803608fc22a1f3F76ea9447D2E8b335",
    "address_memo": ""
}
Field Type Required? Description
currency string Yes Token symbol, e.g., 'BTC'
amount string Yes The amount of currency to withdraw
destination string Yes withdrawal address
To Digital Address=Withdraw to the digital currency address
address string Yes Address (only the address added on the official website is supported)
address_memo string No Tag(tag Or payment_id Or memo)

Response Data

Response

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
    "withdraw_id": "121212"
  }
}
Field Type Description
withdraw_id string Withdrawa ID

Get Deposit And Withdraw History

The original /account/v1/deposit-withdraw/history interface, the old interface is no longer supported, please switch to the new interface as soon as possible

Search for all existed withdraws and deposits and return their latest status. (Authentication type:KEYED, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/account/v2/deposit-withdraw/history

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/account/v2/deposit-withdraw/history?N=100&operationType=withdraw
Field Type Required? Description
currency string No Token symbol, e.g., 'BTC'
operation_type string Yes type
deposit=deposit
withdraw=withdraw
N int Yes Recent N records (value range 1-100)

Response Data

Response

{
  "message":"OK",
  "code":1000,
  "trace":"142bf92a-fc50-4689-92b6-590886f90b97",
  "data":{
    "records":[
      {
        "withdraw_id":"1679952",
        "deposit_id":"",
        "operation_type":"withdraw",
        "currency":"BMX",
        "apply_time":1588867374000,
        "arrival_amount":"59.000000000000",
        "fee":"1.000000000000",
        "status":0,
        "address":"0xe57b69a8776b37860407965B73cdFFBDFe668Bb5",
        "address_memo":"",
        "tx_id":""
      },
      ...
    ]
  }
}
Field Type Description
withdraw_id string withdraw id
deposit_id string deposit id
operation_type string type
deposit=deposit
withdraw=withdraw
currency string Token symbol, e.g., 'BTC'
apply_time long The request timestamp is accurate to milliseconds(UTC-0)
arrival_amount string Actual amount received
fee string fee
status int status
0-Create
1-Submitted, waiting for withdrawal
2-Processing
3-Success
4-Cancel
5-Fail
address string Address
address_memo string Address tag
tx_id string Hash record

Get A Deposit Or Withdraw Detail

Query a single charge record (Authentication type:KEYED, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/account/v1/deposit-withdraw/detail

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/account/v1/deposit-withdraw/detail?id=1679952
Field Type Required? Description
id string Yes withdraw_id or deposit_id

Response Data

Response

{
    "message":"OK",
    "code":1000,
    "trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
    "data":{
        "record":{
            "withdraw_id":"1679952",
            "deposit_id":"",
            "operation_type":"withdraw",
            "currency":"BMX",
            "apply_time":1588867374000,
            "arrival_amount":"59.000000000000",
            "fee":"1.000000000000",
            "status":0,
            "address":"0xe57b69a8776b37860407965B73cdFFBDFe668Bb5",
            "address_memo":"",
            "tx_id":""
        }
    }
}
Field Type Description
withdraw_id string withdraw id
deposit_id string deposit id
operation_type string type
deposit=deposit
withdraw=withdraw
currency string Token symbol, e.g., 'BTC'
apply_time long The request timestamp is accurate to milliseconds(UTC-0)
arrival_amount string Actual amount received
fee string fee
status int status
0-Create
1-Submitted, waiting for withdrawal
2-Processing
3-Success
4-Cancel
5-Fail
address string address
address_memo string address tag
tx_id string Hash record

Transaction Order

Place Order

Place order (Authentication type:SIGNED, See Interface Permission)

Request Format

POST https://api-cloud.bitmart.com/spot/v1/submit_order

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v1/submit_order
{
    "symbol":"BTC_USDT",
    "side":"buy",
    "type":"limit",
    "size":"10",
    "price":"7000"
}
Field Type Required? Description
symbol string Yes Trading pair (e.g. BTC_USDT)
side string Yes Side
buy=Buy order
sell=Sell order
type string Yes Order type
Yes limit=Limit order
Yes market=Market order
Yes limit_maker=PostOnly order
Yes ioc=IOC order

Special Parameters for Limit Orders/PostOnly Orders/IOC Orders (type=limit/limit_maker/ioc)

Field Type Required? Description
size string Yes Order size
price string Yes Price

Special Parameters for Market Orders (type=market)

Field Type Required? Description
size string Yes Quantity sold, required when selling at market price size
notional string Yes Quantity bought, required when buying at market price notional

Instruction

Buy-limit-maker

Sell-limit-maker

Buy-ioc,Sell-ioc

Response Data

Response

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
    "order_id":1223181
  }
}
Field Type Description
order_id long Order ID

Batch Order

Batch order (Authentication type:SIGNED, See Interface Permission)

Request Format

POST https://api-cloud.bitmart.com/spot/v1/batch_orders

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v1/batch_orders
{
    "orderParams":[
        {
        "symbol":"BTC_USDT",
        "size":"0.1",
        "price":"8800",
        "side":"buy",
        "type":"limit"
        },
        {
        "symbol":"BTC_USDT",
        "size":"0.1",
        "price":"8800",
        "side":"sell",
        "type":"limit"
        }
    ]
}
Field Type Required? Description
orderParams List Yes Order parameters, the number of transactions cannot exceed 10

orderParam

Field Type Required? Description
symbol string Yes Trading pair (e.g. BTC_USDT)
side string Yes Side
buy=Buy order
sell=Sell order
type string Yes Order type
Yes limit=Limit order
Yes market=Market order
Yes limit_maker=PostOnly order
Yes ioc=IOC order

Special Parameters for Limit Orders/PostOnly Orders/IOC Orders (type=limit/limit_maker/ioc)

Field Type Required? Description
size string Yes Order size
price string Yes Price

Special Parameters for Market Orders (type=market)

Field Type Required? Description
size string Yes Quantity sold, required when selling at market price size
notional string Yes Quantity bought, required when buying at market price notional

Instruction

Buy-limit-maker

Sell-limit-maker

Buy-ioc,Sell-ioc

Response Data

Response

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
    "orderResponses": [
      {
        "code": 11402,
        "msg": "Balance not enough"
      },
      {
        "code": 0,
        "msg": "SUCCESS",
        "data": {
          "orderId": 145771
        }
      }
    ]
  }
}
Field Type Description
order_id long Order ID

Cancel Order

Cancel an outstanding order (Authentication type:SIGNED, See Interface Permission)

Request Format

POST https://api-cloud.bitmart.com/spot/v2/cancel_order

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v2/cancel_order
{
  "symbol": "BTC_USDT",
  "order_id":112121212
}
Field Type Required? Description
symbol string Yes Trading pair(e.g. BTC_USDT)
order_id long Yes Order id

Response Data

Response

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
    "result": true
  }
}
Field Type Description
result bool Cancel successfully=true; Cancel failed=false

Cancel All Orders

Cancel all outstanding orders in the specified side for a trading pair (Authentication type:SIGNED, See Interface Permission)

Request Format

POST https://api-cloud.bitmart.com/spot/v1/cancel_orders

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v1/cancel_orders
{
  "symbol":"BTC_USDT",
  "side":"buy"
}
Field Type Description
symbol string Trading pair (e.g. BTC_USDT)
side string buy or sell

Response Data

Response

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
  "message": "OK",
  "data": {
  }
}

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

Get Order Detail

Get order detail (Authentication type:SIGNED, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/spot/v1/order_detail

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v1/order_detail?symbol=BTC_USDT&order_id=1736871726781
Field Type Required? Description
symbol string Yes Trading pair (e.g. BTC_USDT)
order_id long Yes Order id

Response Data

Response

{
    "message":"OK",
    "code":1000,
    "trace":"a27c2cb5-ead4-471d-8455-1cfeda054ea6",
    "data":{
        "order_id":1736871726781,
        "symbol":"BTC_USDT",
        "create_time":1591096004000,
        "side":"sell",
        "type":"market",
        "price":"0.00",
        "price_avg":"0.00",
        "size":"0.02000",
        "notional":"0.00000000",
        "filled_notional":"0.00000000",
        "filled_size":"0.00000",
        "unfilled_volume":"0.02000",
        "status":"8"
    }
}
Field Type Description
order_id long Order ID
symbol string Trading pair (e.g. BMX_USDT)
create_time long Timestamp, accurate to milliseconds
side string Side
buy=Buy order
sell=Sell order
type string Order type
limit=Limit order
market=Market order
price string Order price
price_avg string Average filled price
size string Order size (Base currency)
notional string Trade amount, unit is quote currency (special case: base currency when selling market orders)
filled_notional string Filled notional amount
filled_size string Filled amount
unfilled_volume string Unsettled quantity
status string Status
1=Order failure
2=Placing order
3=Order failure, Freeze failure
4=Order success, Pending for fulfilment
5=Partially filled
6=Fully filled
7=Canceling
8=Canceled

Get User Order History

The original /spot/v1/orders interface, the old interface is no longer supported, please switch to the new interface as soon as possible

Get a list of user orders (Authentication type:SIGNED, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/spot/v2/orders

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v2/orders?symbol=BTC_USDT&status=1&N=100
Field Type Required? Description
symbol string Yes Trading pair (e.g. BTC_USDT)
N int Yes Recent N records (value range 1-100)
status string Yes Status
1=Order failure
2=Placing order
3=Order failure, Freeze failure
4=Order success, Pending for fulfilment
5=Partially filled
6=Fully filled
7=Canceling
8=Canceled
9=Outstanding (4 and 5)
10= 6 and 8

Response Data

Response

{
  "message":"OK",
  "code":1000,
  "trace":"70e7d427-7436-4fb8-8cdd-97e1f5eadbe9",
  "data":{
    "current_page":1,
    "orders":[
      {
        "order_id":2147601241,
        "symbol":"BTC_USDT",
        "create_time":1591099963000,
        "side":"sell",
        "type":"limit",
        "price":"9000.00",
        "price_avg":"0.00",
        "size":"1.00000",
        "notional":"9000.00000000",
        "filled_notional":"0.00000000",
        "filled_size":"0.00000",
        "status":"4"
      }
    ]
  }
}
字段 类型 描述
orders List Order list
order_id long Order id
symbol string Trading pair (e.g. BTC_USDT)
create_time long Timestamp, accurate to milliseconds
side string Side
buy=Buy order
sell=Sell order
type string Order type
limit=Limit order
market=Market order
price string Order price
price_avg string Average filled price
size string Order size (Base currency)
notional string Trade amount, unit is quote currency (special case: base currency when selling market orders)
filled_notional string Filled notional amount
filled_size string Filled amount
status string Status
1=Order failure
2=Placing order
3=Order failure, Freeze failure
4=Order success, Pending for fulfilment
5=Partially filled
6=Fully filled
7=Canceling
8=Canceled

Get User Trade History

Get user trade history (Authentication type:SIGNED, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/spot/v1/trades

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v1/trades?symbol=BTC_USDT&limit=10&offset=1
Field Type Required? Description
symbol string Yes Trading pair (e.g. BTC_USDT)

Special Parameters for Querying Trade Record of a Single Order

Field Type Required? Description
order_id long No Order id

Special Parameters for Querying Trade Record of All Orders

Field Type Required? Description
offset int No Current page, starts from 1
limit int No Records returned per page (value range 1-100)

Response Data

Response

{
    "message":"OK",
    "code":1000,
    "trace":"a06a5c53-8e6f-42d6-8082-2ff4718d221c",
    "data":{
        "current_page":1,
        "trades":[
            {
                "detail_id":256348632,
                "order_id":2147484350,
                "symbol":"BTC_USDT",
                "create_time":1590462303000,
                "side":"buy",
                "fees":"0.00001350",
                "fee_coin_name":"BTC",
                "notional":"88.00000000",
                "price_avg":"8800.00",
                "size":"0.01000",
                "exec_type":"M"
            },
            ...
        ]
    }
}
Field Type Description
orders List Order list
detail_id long Trade id
order_id long Order id
symbol string Trading pair symbol
create_time long Trade time (in milliseconds)
side string Side
buy=Buy order
sell=Sell order
price_avg string Average filled price
notional string Notional amount
size string Order size
fees string Fees
fee_coin_name string Coin used for paying fees
exec_type string Whether the trade was created by a maker or a taker. M means Maker, T means Taker

WebSocket Public Channel

Overview

Address

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

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

Format

Request Format

{"op":"<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: spot/ticker: BTC_USDT, which means ticker data of BTC/USDT spot trading pair

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

errorMessage: When an error occurs when sending a subscription or a login operation, the error message will be returned

Successful Response Format

Successful Response Format

When op=login:
{"event":"<operation>"}

When op=unsubscribe:
{"event":"<operation>","topic":"<topic>"}

When op=subscribe:
{"table":"<topic1>","data":"[{"<value1>","<value2>"}]"}
{"table":"<topic2>","data":"[{"<value1>","<value2>"}]"}

When return data does not contain the error_code field, it indicates success

Failed Response Format

Failed Response Format

{"event":"<operation>","errorMessage":"<error_message>","errorCode":"<error_code>"}

If the error_code field is returned, it means failure. For the reason of failure, please refer to: WebSocket error code

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 20s. It is recommended that the user do the following:

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

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

The following is the data format of ping:

ws.send(new PingWebSocketFrame();

ws.send(new TextWebSocketFrame("ping");

Connection Limit

Connection limit: 1 times /1 second

To prevent malicious hogging of connections, only one connection per second is allowed per IP.

Subscription limit: 60 times /10 minutes

After a successful connection, to prevent malicious transmission of data, limit each connection to send 60 subscription data within 10 minutes.

Lifeless connection

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

Data Compression

Only when the market data is returned after subscription, the remote service will compress the data and return it to the client. The remote service returns data in two formats, Binary format and Text format. When the binary format is returned, the data has been compressed by the remote service and the client needs to decompress it.

Compression Introduction

zlib is a library for data compression, developed by Jean-loup Gailly and Mark Adler. The first version (v0.9) was published on May 1, 1995. zlib uses the abstract DEFLATE algorithm, originally written for the libpng library, and later generally used by many software. This library is free. Official link http://zlib.net/

Decompression Example

python

import zlib

message = b'abcd1234'
compressed = zlib.compress(message)
decompressed = zlib.decompress(compressed).decode('UTF-8')
print(decompressed) # abcd1234

java

import java.util.zip.*;
try {
     // Encode a String into bytes
     String inputString = "blahblahblah";
     byte[] input = inputString.getBytes("UTF-8");

     // Compress the bytes
     byte[] output = new byte[100];
     Deflater compresser = new Deflater(true);
     compresser.setInput(input);
     compresser.finish();
     int compressedDataLength = compresser.deflate(output);
     compresser.end();

     // Decompress the bytes
     Inflater decompresser = new Inflater(true);
     decompresser.setInput(output, 0, compressedDataLength);
     byte[] result = new byte[100];
     int resultLength = decompresser.inflate(result);
     decompresser.end();

     // Decode the bytes into a String
     String outputString = new String(result, 0, resultLength, "UTF-8");
 } catch(java.io.UnsupportedEncodingException ex) {
     // handle
 } catch (java.util.zip.DataFormatException ex) {
     // handle
 }

Subscribe

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

subscribe

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

Parameter Instructions

Example

Request

{"op": "subscribe", "args": ["spot/ticker:BTC_USDT"]}

Response

{"table":"spot/ticker:BTC_USDT","data":[]}

Unsubscribe

Cancel subscription to one or more channels

unsubscribe

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

Parameter Instruction

Example

Request

{"op": "unsubscribe", "args": ["spot/ticker:BTC_USDT", "spot/ticker:ETH_USDT"]}

Response

{"event":"unsubscribe","topic":"spot/ticker:BTC_USDT"}
{"event":"unsubscribe","topic":"spot/ticker:ETH_USDT"}

Ticker Channel

Get the latest price, bid price, ask price and 24-hour trading volume

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

{"op": "subscribe", "args": ["spot/ticker:BTC_USDT"]}

spot/ticker is the channel name, BTC_USDT is the trading pair

Response

{
    "table":"spot/ticker",
    "data":[
        {
            "symbol":"BTC_USDT",
            "last_price":"146.24",
            "open_24h":"147.17",
            "high_24h":"147.48",
            "low_24h":"143.88",
            "base_volume_24h":"117387.58",
            "s_t": 1610936002
        }
    ]
}

notice: This data is displayed after decompression, Refer to Data Compression for details)

Return Parameter Description:

Parameter Type Description
symbol string Trading pair, BTC_USDT
last_price string Last trading price
high_24h string 24-hour highest price
low_24h string 24-hour lowest price
open_24h string 24-hour open price
base_volume_24h string 24-hour volume in base currency
s_t long timestamp (in seconds)

KLine Channel

Get the spot K-line data

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

{"op": "subscribe", "args": ["spot/kline1m:BTC_USDT"]}

spot/kline1m is the channel name, BTC_USDT is the trading pair

Channel List

Channel Name Description
spot/kline1m 1-min KLine Channel
spot/kline3m 3-min KLine Channel
spot/kline5m 5-min KLine Channel
spot/kline15m 15-min KLine Channel
spot/kline30m 30-min KLine Channel
spot/kline1H 1-hour KLine Channel
spot/kline2H 2-hour KLine Channel
spot/kline4H 4-hour KLine Channel
spot/kline1D 1-day KLine Channel
spot/kline1W 1-week KLine Channel
spot/kline1M 1-month KLine Channel

Response

{
    "table":"spot/kline1m",
    "data":[
        {
            "candle":[
                1534141852,
                "162.03",
                "162.04",
                "161.96",
                "161.98",
                "336.452694"
            ],
            "symbol":"ETH_USDT"
        }
    ]
}

notice: This data is displayed after decompression, Refer to Data Compression for details

Return Parameter Description:

Parameter Type Description
symbol string Trading pair, BTC_USDT
candle List KLine data

Depth Channel

Return the depth data

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

{"op": "subscribe", "args": ["spot/depth5:BTC_USDT"]}

spot/depth5 is the channel name and BTC_USDT is the trading pair

Channel List

Channel Name Description
spot/depth5 5 Level Depth Channel
spot/depth20 20 Level Depth Channel
spot/depth50 50 Level Depth Channel

Response

{
    "table":"spot/depth5",
    "data":[
        {
            "asks":[
                [
                    "161.96",
                    "7.37567"
                ]
            ],
            "bids":[
                [
                    "161.94",
                    "4.552355"
                ]
            ],
            "symbol":"ETH_USDT",
            "ms_t": 1542337219120
        }
    ]
}

notice:This data is displayed after decompression, Refer to Data Compression for details

Return Parameter Description:

Parameter Type Description
symbol string Trading pair, BTC_USDT
asks List Ask depth
bids List Bid depth
ms_t long Timestamp (in millisecond)

Trade Channel

Get the latest trade data

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

{"op": "subscribe", "args": ["spot/trade:BTC_USDT"]}

spot/trade is the channel name, BTC_USDT is the trading pair

Response

{
    "table": "spot/trade",
    "data": [{
        "symbol": "ETH_USDT",
        "price": "162.12",
        "side": "buy",
        "size": "11.085",
        "s_t": 1542337219
    }]
}

notice:This data is displayed after decompression, Refer to Data Compression for details

Return Parameter Description:

Parameter Type Description
symbol string Trading pair, BTC_USDT
side string Side of trade(buy or sell
price string Trade price
size string Trade quantity
s_t long Timestamp (in seconds)

WebSocket Private Channel

Login

Login Subscription Format

Request

{"op":"login","args":["<API_KEY>", "<timestamp>", "<sign>"]}

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)

Example

sign

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

example

{"op": "login", "args": ["80618e45710812162b04892c7ee5ead4a3cc3e56", "1589267764859", "3ceeb7e1b8cb165a975e28a2e2dfaca4d30b358873c0351c1a071d8c83314556"]}

Response

{"event":"login"}

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 return data does not contain the error_code field, it indicates success

Order Channel

Get user trade data

Pushing Rules

  1. No user login required
  2. Qualified orders will be pushed (Successfully placed an order, Partially filled, Fully filled, Canceled)

Example

Request

{"op": "subscribe", "args": ["spot/user/order:BTC_ USDT"]}

spot/user/order is the channel name, BTC_USDT is the trading pair

Response

{
    "data":[
        {
            "symbol":"BTC_USDT",
            "side":"buy",
            "type":"market",
            "notional":"",
            "size":"1.0000000000",
            "ms_t":"1609926028000",
            "price":"46100.0000000000",
            "filled_notional":"46100.0000000000",
            "filled_size":"1.0000000000",
            "margin_trading":"0",
            "state":"2",
            "order_id":"2147857398",
            "order_type":"0",
            "last_fill_time":"1609926039226",
            "last_fill_price":"46100.00000",
            "last_fill_count":"1.00000"
        }
    ],
    "table":"spot/user/order"
}

notice:This data is displayed after decompression, Refer to Data Compression for details

Return Parameter Description:

Parameter Type Description
symbol string Trading pair, BTC_USDT
order_id string Order ID
price string Order price
size string Order quantity
notional string The purchase amount, returned when buying at market price; otherwise, an empty string is returned
side string buy or sell
type string limit or market
ms_t string Timestamp (in milliseconds)
filled_size string Filled size (Base currency)
filled_notional string Filled notional amount (Quote currency)
margin_trading string 0:Spot order
order_type string Order type(0:Regular, 1:Maker only(Post only), 2:Fill or kill(FOK), 3:Immediate or Cancel(IOC))
state string Order state
1=Order failure
2=Placing order
3=Order failure, Freeze failure
4=Order success, Pending for fulfilment
5=Partially filled
6=Fully filled
7=Canceling
8=Canceled
last_fill_price string Latest trade price(0 if not filled)
last_fill_count string Latest trade quantity(0 if not filled)
last_fill_time string Latest trade time(0 if not filled) millisecond

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

Funding Account API Error Code

如:httpStatus:200, body:{"code": 1000,"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1","message": "OK","data": {}}

error message code error code http status code
OK 1000 200
Invalid request (maybe the body is empty, or the int parameter passes string data) 60000 400
Asset account type does not exist 60001 400
currency does not exist 60002 400
Currency has been closed recharge channel, if there is any problem, please consult customer service 60003 400
Currency has been closed withdraw channel, if there is any problem, please consult customer service 60004 400
Minimum amount is %s 60005 400
Maximum withdraw precision is %d 60006 400
Only withdrawals from added addresses are allowed 60007 400
Balance not enough 60008 400
Beyond the limit 60009 400
Withdraw id or deposit id not found 60010 400
Address is not valid 60011 400
This action is not supported in this currency(If IOTA, HLX recharge and withdraw calls are prohibited) 60012 400
Your account is not allowed to recharge 60020 403
Your account is not allowed to withdraw 60021 403
No withdrawals for 24 hours 60022 403
Method Not Allowed 60030 405
Unsupported Media Type 60031 415
User account not found 60050 500
Internal Server Error 60051 500

Spot API Error Code

Example: httpStatus:200, body:{"code": 1000,"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1","message": "OK","data": {}}

error message code error code http status code
OK 1000 200
Bad Request 50000 400
Symbol not found 50001 400
From Or To format error 50002 400
Step format error 50003 400
Kline size over 500 50004 400
Order Id not found 50005 400
Minimum size is %s 50006 400
Maximum size is %s 50007 400
Minimum price is %s 50008 400
Minimum count*price is %s 50009 400
RequestParam size is required 50010 400
RequestParam price is required 50011 400
RequestParam notional is required 50012 400
Maximum limit*offset is %d 50013 400
RequestParam limit is required 50014 400
Minimum limit is 1 50015 400
Maximum limit is %d 50016 400
RequestParam offset is required 50017 400
Minimum offset is 1 50018 400
Invalid status. validate status is [1=Failed, 2=Success, 3=Frozen Failed, 4=Frozen Success, 5=Partially Filled, 6=Fully Fulled, 7=Canceling, 8=Canceled 50019 400
Balance not enough 50020 400
Invalid %s 50021 400
Service unavailable 50022 400
This Symbol can't place order by api 50023 400
Order book size over 200 50024 400
Maximum price is %s 50025 400
The buy order price cannot be higher than the open price 50026 400
The sell order price cannot be lower than the open price 50027 400
Missing parameters 50028 400
The parameters do not match 50029 400
Order is already canceled 50030 400
Order is already completed 50031 400
Order does not exist 50032 400
The order quantity should be greater than 0 and less than or equal to 10 50033 400
The price is high and there is no matching depth 50034 400
The price is low and there is no matching depth 50035 400
Cancel failed, order is not revocable status 50036 400
Your account is frozen due to security policies. Please contact customer service 53000 403
Method Not Allowed 57001 405
Unsupported Media Type 58001 415
User account not found 59001 500
Internal Server Error 59002 500

WebSocket Error Code

Error Code Format

{"event":"<operation>", "errorMessage":"", "errorCode":""}

Error Code

Error Message Error Code
Invalid message format 90001
Invalid op param 90002
Invalid args param 90003
Invalid channel param 90004
API KEY is empty 91001
API KEY not found 91002
API KEY has frozen 91003
API KEY over expire time 91004
Already logged in 91005
User not logged in / User must be logged in 91006
Param sign is empty 91010
Param sign is wrong 91011
Param timestamp is empty 91021
Param timestamp range. Within a minute 91022
Param timestamp invalid format 91023
Invalid symbol param 92001
Request frequency exceeds limit 94001
Internal system error 95000

Change Log

2022-01-20

2022-01-18

2021-11-24

2021-11-06

2021-01-19

2020-07-15

2020-06-29

2020-05-14

Questions And Answers

This is the Q&A section. If you cannot find answer to your question, please join us Telegram API Group in time.

APIKey Q&A

1. How to apply for APIKEY?

API application site: https://www.bitmart.com/api

After successful application on the website, please keep your access key, secret key and memo.

2. Can I retrieve the secret key of APIKEY?

No, you will need to create new APIKEY.

3. Is there any risk of authorizing APIKEY to a third party?

This will create some risk, and it is recommended to keep it yourself for account security.

4. Can I apply for APIKEY without binding my phone or Google?

No, you must bind more than 2 security items to apply for APIKEY.

5. When creating an APIKEY, do I have to bind an IP address?

It is not necessary. The option to bind IP when applying for APIKEY is optional, but in order to increase the security of user accounts, it is recommended to bind the IP address.

6. Will different APIKEYs in the same account return different data?

Different APIKEY data under the same account is the same.

7. How many Api Keys can I apply for in one account?

Each account can create 5 sets of Api keys, and each Api Key can be set up with 3 permissions, namely read-only, trade and withdrawal, three types of permissions.

Details:

1) Read-only permission: Read the user's own trading information, order information, account capital information, etc.

2) Trade permission: Users can place orders and cancel orders in spot and contract.

3) Withdrawal permission: The user can withdraw the balance of the wallet to the digital currency address outside the exchange.

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

Fill in according to the prompt on the web page, and the memo can be filled in at will by the user; the secret key must be remembered, and it will be used when calling the API interface; binding IP is not required, but it is recommended for account security; API permissions can be checked based on user needs.

9. What is memo?

Memo is provided by users themselves. It will be used in the signing of the interface.

Authentication Q&A

1. What is the maximum difference between the timestamp parameter of the request interface and the time to reach the server?

Requests that differ by more than 1 minute between the timestamp and the API server time will be considered expired by the system and rejected. If there is a large time deviation between the user server and the API server, it is recommended that the user use the "Get Server Time" interface to query the API server time.

2. How to solve error "The request header "X-BM-TIMESTAMP" cannot be empty", which occurs from time to time?

First of all, it is recommended that the user print out whether the request header parameter X-BM-TIMESTAMP has a value. In addition, it is recommended that the user code be optimized. Before each request, determine whether X-BM-TIMESTAMP is empty.

3. What is the time used as the timestamp in the API?

UTC 0 timestamp。

4. Why does signature authentication always return invalid signatures?

Caused by incorrect signatures:

You can use the following SDK, the signature part has been packaged, you can directly debug and call:

If you are writing your own signature function, please refer to the following description step by step:

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

When checking, you can print out the request header information and the pre-signature string, focusing on the following points:

Whether the APIKey is correctly configured in the code

Your KEY is as follows:

API_KEY = "80618e45710812162b04892c7ee5ead4a3cc3e56";

API_SECRET = "6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9";

API_MEMO = "test001";

Please confirm that the settings are correct:

Content-Type: application/json

X-BM-KEY: 80618e45710812162b04892c7ee5ead4a3cc3e56

Check whether the string before signing conforms to the standard format, the order of all elements must be consistent, you can use the following example to compare with your string before signing:

GET

  X-BM-SIGN=
    echo -n '1589267764859#test001#contract_id=1&category=1' | openssl dgst -sha256 -hmac "6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9"
  (stdin)= 6d5e774446448073f68e99c28ace86503451bed1fd44e43f80b9b518937c4ef1
Request:
  Host: {{host}}/v1
  Content-Type: application/json
  X-BM-KEY: 80618e45710812162b04892c7ee5ead4a3cc3e56
  X-BM-SIGN: 6d5e774446448073f68e99c28ace86503451bed1fd44e43f80b9b518937c4ef1
  X-BM-TIMESTAMP: 1589267764859

GET Example: Request address is {{host}}/v1?contract_id=1&category=1, the current timestamp=1589267764859, so queryString=1589267764859#test001#contract_id=1&category=1

POST

  X-BM-SIGN=
    echo -n '1589267764859#test001#{"contract_id":1,"category":1,"way":1,"open_type":1,"leverage":10,"custom_id":1,"price":5000,"vol":10,"nonce":1589267764}' | openssl dgst -sha256 -hmac "6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9"
  (stdin)= 595a00aa2ecbd2f7e857909497e3aa8b222da6b6055411c7f4dfce0e7dc6c6ae
Request:
  HOST: {{host}}/v1
  Body: {"contract_id":1,"category":1,"way":1,"open_type":1,"leverage":10,"custom_id":1,"price":5000,"vol":10,"nonce":1589267764}
  Content-Type: application/json
  X-BM-KEY: 80618e45710812162b04892c7ee5ead4a3cc3e56
  X-BM-SIGN: 595a00aa2ecbd2f7e857909497e3aa8b222da6b6055411c7f4dfce0e7dc6c6ae
  X-BM-TIMESTAMP: 1589267764859

POST Example: Request address is {{host}}/v1?contract_id=1&category=1, the current timestamp=1589267764859, so queryString=1589267764859#test001#{"contract_id":1,"category":1,"way":1,"open_type":1,"leverage":10,"custom_id":1,"price":5000,"vol":10,"nonce":1589267764}

Rate Limit Q&A

1.Is there a limit to how often the API is called per second?

There are limits, specific can see the menu bar 'Rate Limit' in each interface access frequency limit.

2."why do I have to complete a CAPTCHA?" comes up on the call

This time, the IP was intercepted because it was accessed too much from a different environment and was considered an attack by the system. It is recommended that you do not share IP and that applications be accessed using a separate IP.Second, use the browser to call the interface and select 'I am Human' to submit to unrestrict as prompted on the page.

PNG

3.How is the HTTP status code 429 created?

The request interface exceeds the access frequency limit. It is recommended to reduce the access frequency.

4.Will API call interfaces be blocked if they exceed the access frequency? How long letter?

No, just reduce the access frequency.

5.Access interface error overclocking, how to solve?

Reduce the frequency of access. Each interface of the document has a frequency description. You need to lower the request frequency to the frequency description.

Interface Q&A

1. When does the K-Line start to calculate?

The start time of the K-Line interface is the UTC time, which is 8 hours different from Beijing time.

Spot Q&A

1. Why cancel the spot order will return failure?

Because when the cancellation is requested, this order may have been successfully matched.

2. How are the highest, lowest and volume calculated?

The highest price, the lowest price and the turnover are calculated according to the dimension of the last 24 hours.

The 24 hour opening price takes its value from the opening price of the K line at the last minute of the 24 hour period. That is, at 11:23:45 on July 23, 2019, the rise and fall depends on the opening price at 11:23:00 on July 22, 2019.

Contract Q&A

1. What does the request field errno mean?

This is a legacy field, please ignore it, the returned field code shall prevail.

Contact Us

If you have any api related questions, comments or suggestions, join us Telegram API Group: (please indicate whether it is a contract interface or a spot interface), we will reply to your problem in a timely manner.