NAV
Example

Introduction

Getting Started

Welcome to the developer documentation.

Instruction For Calling Endpoints

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

Contact Us

Join our Telegram API Group

Product Dictionary

Trade

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

Contract

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

Order and Trade ID

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

Time

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

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

Standard Rules

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

Numbers ID

Numbers

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

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

ID

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

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

Update Plan

Change Log

2023-03-03

2022-12-22

2022-11-03

2022-11-01

2022-10-11

2022-09-29

2022-08-16

2022-07-07

2022-05-24

2022-04-19

2022-03-29

2022-03-08

2022-03-01

2022-02-15

2022-01-20

2022-01-18

2021-11-24

2021-11-06

2021-01-19

2020-07-15

2020-06-29

2020-05-14

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

Request Example: GET/DELETE

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

# queryString: symbol=BMXBTC&side=BUY

Request Example: POST/PUT

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

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

Special Note: In the example on the right,

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

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

3.Signature

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

// javascript language
sign=CryptoJS.HmacSHA256(message, YourSecretKey)
// python language
def sign(message, your_secret_key):
    mac = hmac.new(bytes(your_secret_key, encoding='utf8'), bytes(message, encoding='utf-8'), digestmod='sha256')
    return mac.hexdigest()
// java language
import org.apache.commons.codec.binary.Hex;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public final class CloudSignature {
    static final String HMAC_SHA256 = "HmacSHA256";
    static String createSha256Signature(String yourSecretKey, String message) {
        try {
            Mac sha256 = Mac.getInstance(HMAC_SHA256);
            SecretKeySpec secretKeySpec = new SecretKeySpec(yourSecretKey.getBytes(), HMAC_SHA256);
            sha256.init(secretKeySpec);
            return Hex.encodeHexString(sha256.doFinal(message.getBytes()));
        } catch (Exception ex) {
            ex.printStackTrace();
        }
        return null;
    }
}
// go language
import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
)
func HmacSha256Base64Signer(message string, yourSecretKey string) (string, error) {
    mac := hmac.New(sha256.New, []byte(yourSecretKey))
    _, err := mac.Write([]byte(message))
    if err != nil {
        return "", err
    }
    return hex.EncodeToString(mac.Sum(nil)), nil
}

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

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

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

4.Timestamp

Unix timestamps accurate to milliseconds using UTC0 time zone

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

Example

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

Key Value
accessKey 80618e45710812162b04892c7ee5ead4a3cc3e56
secretKey 6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9
memo test001

Example: /spot/v1/test-get

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

curl --location --request GET 'localhost:8080/spot/v1/test-get?symbol=BTC_USDT'
--header 'Content-Type: application/json'
--header 'X-BM-KEY: 80618e45710812162b04892c7ee5ead4a3cc3e56'
--header 'X-BM-SIGN: 118eb558afa7d84e8710004f8416ddb771f50718c85f60a45069d0ccbe6ee1e0'
--header 'X-BM-TIMESTAMP: 1589793795969'
{"message":"OK","code":1000,"trace":"17105b32-cc5b-406a-ab6e-6d9ed0fa4fd8","data":{}}

Request interface: /spot/v1/test-get

Request method: GET

Current timestamp: timestamp=1589793795969

Parameter Value
symbol BTC_USDT

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

Example: /spot/v1/test-post

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

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

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

Request interface: /spot/v1/test-post

Request method: POST

Current timestamp: timestamp=1589793796145

Parameter Value
symbol BTC_USDT
price 8600
count 100

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

RequestFormat

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

Request Standard

1.Rest Interface

1.1 Request parameter and format

GET/DELETE

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

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

POST/PUT

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

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

1.2 Reponse

Response:

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

The server response data format is JSON.

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

2.WebSocket Interface

No description.

Authentication Type

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

1. Public Interface

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

2. Private Interface

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

Interface Permission

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

Interface authentication

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

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

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

API KEY Permission

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

Details:

Spot Interface Description Authentication Type Permissions
/contract/public/details Get a detailed list of all trading pairs NONE No permission required
/contract/public/depth Get full depth of trading pairs NONE No permission required
/contract/public/open-interest Get Contract Openinterest NONE No permission required
/contract/private/submit-order Submit Contract Order SIGNED Trading Permission
/contract/private/cancel-order Cancel Contract Order SIGNED Trading Permission
/contract/private/cancel-orders Batch Cancel Contract Orders SIGNED Trading Permission
/contract/private/order Get Contract Order Detail KEYED Read-Only Permission
/contract/private/order-history Get Contract Order History KEYED Read-Only Permission
/contract/private/trades Get Contract Order Trade Detail KEYED Read-Only Permission
/contract/private/assets-detail Get Contract Assets Detail KEYED Read-Only Permission
/contract/private/position Get Current Position Detail KEYED Read-Only Permission
/contract/public/funding-rate Get Current Funding Rate NONE No permission required
/contract/public/kline Get K-line NONE No permission required
Spot Interface Description Authentication Type Permissions
/spot/v1/currencies Get a list of all cryptocurrencies on the platform NONE No permission required
/spot/v1/symbols Get a list of all trading pairs on the platform NONE No permission required
/spot/v1/symbols/details Get a detailed list of all trading pairs on the platform NONE No permission required
/spot/v1/ticker Get ticker NONE No permission required
/spot/v1/steps Get K-Line steps NONE No permission required
/spot/v1/symbols/kline Get K-Line NONE No permission required
/spot/v1/symbols/book Get orderbook NONE No permission required
/spot/v1/symbols/trades Get recent trades NONE No permission required
/spot/v1/wallet Get user wallet KEYED Read-Only Permission
/spot/v1/submit_order Place order SIGNED Trading Permission
/spot/v1/cancel_order Cancel order SIGNED Trading Permission
/spot/v1/cancel_orders Cancel all orders SIGNED Trading Permission
/spot/v1/order_detail Get order detail KEYED Read-Only Permission
/spot/v1/orders Get user orders KEYED Read-Only Permission
/spot/v1/trades Get user trades KEYED Read-Only Permission
API Broker Interface Description Authentication Type Permissions
/spot/v1/broker/rebate Applicable to query API Broker's rebate records 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 2 times/2 sec
/account/v1/wallet Get account balance X-BM-KEY 12 times/2 sec
/account/v1/deposit/address Deposit address X-BM-KEY 2 times/2 sec
/account/v1/withdraw/charge Withdraw quota X-BM-KEY 2 times/2 sec
/account/v1/withdraw/apply Withdraw X-BM-KEY 8 times/2 sec
/account/v2/deposit-withdraw/history Get deposit and withdraw history V2 X-BM-KEY 8 times/2 sec
/account/v1/deposit-withdraw/detail Get a deposit Or withdraw detail X-BM-KEY 8 times/2 sec
/spot/v1/margin/isolated/account Get Margin Account Details(Isolated) X-BM-KEY 12 times/2 sec
/spot/v1/margin/isolated/transfer Margin Asset Transfer X-BM-KEY 2 times/2 sec
/spot/v1/user_fee Basic Fee Rate X-BM-KEY 2 times/2 sec
/spot/v1/trade_fee Actual Trade Fee Rate X-BM-KEY 2 times/2 sec
Contract Interface Interface Name Limit Target Rate Special Remarks
/contract/public/details Get a detailed list of all trading pairs IP 12 times/2 sec
/contract/public/depth Get full depth of trading pairs IP 12 times/2 sec
/contract/public/open-interest Get Contract Openinterest IP 2 times/2 sec
/contract/private/submit-order Submit Contract Order X-BM-KEY 24 times/2 sec
/contract/private/cancel-order Cancel Contract Order X-BM-KEY 40 times/2 sec
/contract/private/cancel-orders Batch Cancel Contract Orders X-BM-KEY 2 times/2 sec
/contract/private/submit-plan-order Submit Contract Plan Order X-BM-KEY 24 times/2 sec
/contract/private/cancel-plan-order Cancel Contract Plan Order X-BM-KEY 40 times/2 sec
/contract/private/order Get Contract Order Detail X-BM-KEY 50 times/2 sec
/contract/private/order-history Get Contract Order History X-BM-KEY 6 times/2 sec
/contract/private/trades Get Contract Order Trade Detail X-BM-KEY 6 times/2 sec
/contract/private/assets-detail Get Contract Assets Detail X-BM-KEY 12 times/2 sec
/contract/private/position Get Current Position Detail X-BM-KEY 6 times/2 sec
/contract/public/funding-rate Get Current Funding Rate IP 2 times/2 sec
/contract/public/kline Get K-line IP 12 times/2 sec
Spot Interface Interface Name Limit Target Rate Special Remarks
/spot/v1/currencies Get a list of all cryptocurrencies IP 8 times/2 sec
/spot/v1/symbols Get a list of all trading pairs IP 8 times/2 sec
/spot/v1/symbols/details Get a detailed list of all trading pairs IP 12 times/2 sec
/spot/v1/ticker Get ticker IP 12 times/2 sec
/spot/v2/ticker Get Ticker of All Pairs IP 2 times/2 sec
/spot/v1/ticker_detail Get Ticker of a Trading Pair IP 12 times/2 sec
/spot/v1/steps Get K-Line steps IP 2 times/2 sec
/spot/v1/symbols/kline Get k-Line IP 12 times/2 sec
/spot/v1/symbols/book Get orderbook IP 12 times/2 sec
/spot/v1/symbols/trades Get the latest trades IP 12 times/2 sec
/spot/v1/wallet Get the user's wallet balance X-BM-KEY 12 times/2 sec
/spot/v1/submit_order Place spot order X-BM-KEY 60 times/2 sec
/spot/v2/submit_order Place spot order X-BM-KEY 60 times/2 sec
/spot/v1/margin/submit_order Place margin order X-BM-KEY 60 times/2 sec
/spot/v2/cancel_order Cancel order X-BM-KEY 60 times/2 sec
/spot/v3/cancel_order Cancel order X-BM-KEY 60 times/2 sec
/spot/v1/cancel_orders Cancel all orders in the specified direction of the specified trading pair X-BM-KEY 4 times/2 sec
/spot/v1/order_detail Get order details X-BM-KEY 60 times/2 sec
/spot/v2/order_detail Get order details X-BM-KEY 60 times/2 sec
/spot/v2/orders Get user's recent orders V2 X-BM-KEY 12 times/2 sec
/spot/v3/orders Get user's recent orders X-BM-KEY 12 times/2 sec
/spot/v1/trades User trade records X-BM-KEY 12 times/2 sec
/spot/v2/trades User trade records X-BM-KEY 12 times/2 sec
/spot/v1/batch_orders Batch order X-BM-KEY 60 times/2 sec
/spot/v2/batch_orders Batch order X-BM-KEY 60 times/2 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 2 times/2 sec
/account/sub-account/sub/v1/sub-to-main Sub-Account Spot Asset Transfer (For Sub-Account) X-BM-KEY 2 times/2 sec
/account/sub-account/main/v1/main-to-sub Main Account Spot Asset Transfer (For Main Account) X-BM-KEY 2 times/2 sec
/account/sub-account/sub/v1/sub-to-sub Sub-Account to Sub-Account Spot Asset Transfer (For Sub-Account) X-BM-KEY 2 times/2 sec
/account/sub-account/main/v1/sub-to-sub Sub-account to Sub-Account Spot Asset Transfer (For Main Account) X-BM-KEY 2 times/2 sec
/account/sub-account/main/v1/transfer-list Query Sub-account Spot Asset Transfer History (For Main Account) X-BM-KEY 8 times/2 sec
/account/sub-account/v1/transfer-history Get Account Spot Asset Transfer History X-BM-KEY 8 times/2 sec
/account/sub-account/main/v1/wallet Get Sub-Account Spot Wallet Balance (For Main Account) X-BM-KEY 12 times/2 sec
/account/sub-account/main/v1/subaccount-list Get Sub-account List (For Main Account) X-BM-KEY 8 times/2 sec
Margin Loan Interface Interface Name Limit Target Rate Special Remarks
/spot/v1/margin/isolated/borrow Margin Borrow (Isolated) X-BM-KEY 2 times/2 sec
/spot/v1/margin/isolated/repay Margin Repay (Isolated) X-BM-KEY 2 times/2 sec
/spot/v1/margin/isolated/borrow_record Get Borrow Record(Isolated) X-BM-KEY 60 times/2 sec
/spot/v1/margin/isolated/repay_record Get Repayment Record(Isolated) X-BM-KEY 60 times/2 sec
/spot/v1/margin/isolated/pairs Get Trading Pair Borrowing Rate and Amount X-BM-KEY 2 times/2 sec
API Broker Interface Interface Name Limit Target Rate Special Remarks
/spot/v1/broker/rebate Applicable to query API Broker's rebate records X-BM-KEY 1 times/1 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",
             "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
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 Minimum sell amount
trade_status string ’trading’,is trading;’pre-trade’,pre-open

Get Ticker of All Pairs

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 Ticker of All Pairs (V2)

Applicable to query the latest ticker of all trading pairs, please note that the endpoint returns more data, please reduce the frequency of calls (Authentication type:NONE, See Interface Permission)

Request Format

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v2/ticker

None

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",
                "timestamp":1665200293
            }
        ]
    }
}
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
timestamp long Time of generation

Get Ticker of a Trading Pair

Applicable for querying aggregated tickers of a particular trading pair (Authentication type:NONE, See Interface Permission)

Request Format

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v1/ticker_detail?symbol=BTC_USDT
Field Type Required? Description
symbol string Yes Trading pair, like (BTC_USDT)

Response Data

Response

{
  "message":"OK",
  "code":1000,
  "trace":"7d3a7e589cad4d578e17a6bdea8e4d09.65.16687519530806699",
  "data":{
    "symbol":"BTC_USDT",
    "last_price":"16795.11",
    "quote_volume_24h":"71784875.05",
    "base_volume_24h":"4306.22738",
    "high_24h":"16995.94",
    "low_24h":"16434.08",
    "open_24h":"16583.37",
    "close_24h":"16795.11",
    "best_ask":"16792.26",
    "best_ask_size":"0.02377",
    "best_bid":"16792.23",
    "best_bid_size":"0.00640",
    "fluctuation":"+0.0128",
    "timestamp":1668751802882,
    "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
timestamp long Time of generation

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

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-50], there are altogether [2-100] 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 '50', 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 Required? Description
symbol string Yes Trading pair (e.g. BMX_USDT)
N string No Number of returned items, the default maximum is 50

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)

Sub-Account Endpoints

Sub-Account Spot Asset Transfer (For Main Account)

Sub-Account Spot Asset Transfer (For Main Account) (Authentication type:SIGNED, See Interface Permission)

Request Format

POST https://api-cloud.bitmart.com/account/sub-account/main/v1/sub-to-main

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/account/sub-account/main/v1/sub-to-main
{
  "requestNo":"4e2adcff-2122-1ce7-2557-4f65d2ce1ca2",
  "amount":"1",
  "currency":"BTC",
  "subAccount":"[email protected]"
}
Field Type Required? Description
requestNo string Yes UUID,unique identifier
amount string Yes Transfer amount
currency string Yes Currency
subAccount string Yes Sub-Account username

Response Data

Response

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

If code value is 1000,it means the transfer is successful.

Sub-Account Spot Asset Transfer (For Sub-Account)

Sub-Account Spot Asset Transfer (For Sub-Account) (Authentication type:SIGNED, See Interface Permission)

Request Format

POST https://api-cloud.bitmart.com/account/sub-account/sub/v1/sub-to-main

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/account/sub-account/sub/v1/sub-to-main
{
  "requestNo":"4e2adcff-2122-1ce7-2557-4f65d2ce1ca2",
  "amount":"1",
  "currency":"BTC"
}
Field Type Required? Description
requestNo string Yes UUID,unique identifier
amount string Yes Transfer amount
currency string Yes Currency

Response Data

Response

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

If code value is 1000,it means the transfer is successful.

Main Account Spot Asset Transfer (For Main Account)

Main Account Spot Asset Transfer (For Main Account) (Authentication type:SIGNED, See Interface Permission)

Request Format

POST https://api-cloud.bitmart.com/account/sub-account/main/v1/main-to-sub

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/account/sub-account/main/v1/main-to-sub
{
  "requestNo":"4e2adcff-2122-1ce7-2557-4f65d2ce1ca2",
  "amount":"1",
  "currency":"BTC",
  "subAccount":"[email protected]"
}
Field Type Required? Description
requestNo string Yes UUID,unique identifier
amount string Yes Transfer amount
currency string Yes Currency
subAccount string Yes Sub-Account username

Response Data

Response

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

If code value is 1000,it means the transfer is successful.

Sub-Account to Sub-Account Spot Asset Transfer (For Sub-Account)

Sub-Account to Sub-Account Spot Asset Transfer (For Sub-Account) (Authentication type:SIGNED, See Interface Permission)

Request Format

POST https://api-cloud.bitmart.com/account/sub-account/sub/v1/sub-to-sub

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/account/sub-account/sub/v1/sub-to-sub
{
  "requestNo":"4e2adcff-2122-1ce7-2557-4f65d2ce1ca2",
  "amount":"1",
  "currency":"BTC",
  "subAccount":"[email protected]"
}
Field Type Required? Description
requestNo string Yes UUID,unique identifier
amount string Yes Transfer amount
currency string Yes Currency
subAccount string Yes Sub-Account username

Response Data

Response

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

If code value is 1000,it means the transfer is successful.

Sub-Account to Sub-Account Spot Asset Transfer (For Main Account)

Sub-Account to Sub-Account Spot Asset Transfer (For Main Account) (Authentication type:SIGNED, See Interface Permission)

Request Format

POST https://api-cloud.bitmart.com/account/sub-account/main/v1/sub-to-sub

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/account/sub-account/main/v1/sub-to-sub
{
  "requestNo":"4e2adcff-2122-1ce7-2557-4f65d2ce1ca2",
  "amount":"1",
  "currency":"BTC",
  "fromAccount":"[email protected]",
  "toAccount":"[email protected]"
}
Field Type Required? Description
requestNo string Yes UUID,unique identifier
amount string Yes Transfer amount
currency string Yes Currency
fromAccount string Yes Transfer out Sub-Account username
toAccount string Yes Transfer to Sub-Account username

Response Data

Response

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

If code value is 1000,it means the transfer is successful.

Query Sub-Account Spot Asset Transfer History (For Main Account)

Query Sub-Account Spot Asset Transfer History (For Main Account) (Authentication type:KEYED, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/account/sub-account/main/v1/transfer-list

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/account/sub-account/main/v1/transfer-list?moveType=spot to spot
Field Type Required? Description
moveType string Yes type
spot to spot=Spot wallet transfer to spot wallet
accountName string No Sub-Account username
N int Yes Recent N records (value range 1-100)

Response Data

Response

{
  "message": "OK",
  "code": 1000,
  "trace": "282fd16e-73ee-464f-adb7-7241345929f6",
  "data": {
    "total": 2,
    "historyList": [
      {
        "fromAccount": "[email protected]",
        "fromWalletType": "spot",
        "toAccount": "[email protected]",
        "toWalletType": "spot",
        "currency": "BTC",
        "amount": "1",
        "submissionTime": 1648471522
      },
      {
        "fromAccount": "[email protected]",
        "fromWalletType": "spot",
        "toAccount": "[email protected]",
        "toWalletType": "spot",
        "currency": "BTC",
        "amount": "30",
        "submissionTime": 1648466178
      }
    ]
  }
}
Field Type Description
fromAccount string Transfer out Sub-Account username
fromWalletType string Transfer out wallet type
spot=spot wallet
toAccount string Transfer to Sub-Account username
toWalletType string Transfer to wallet type
spot=spot wallet
currency string currency
amount string Transfer amount
submissionTime long The request timestamp is accurate to seconds(UTC-0)

Get Account Spot Asset Transfer History

Get Account Spot Asset Transfer History (Authentication type:KEYED, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/account/sub-account/v1/transfer-history

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/account/sub-account/v1/transfer-history?moveType=spot to spot
Field Type Required? Description
moveType string Yes type
spot to spot=Spot wallet transfer to spot wallet
N int Yes Recent N records (value range 1-100)

Response Data

Response

{
  "message": "OK",
  "code": 1000,
  "trace": "282fd16e-73ee-464f-adb7-7241345929f6",
  "data": {
    "total": 2,
    "historyList": [
      {
        "fromAccount": "[email protected]",
        "fromWalletType": "spot",
        "toAccount": "[email protected]",
        "toWalletType": "spot",
        "currency": "BTC",
        "amount": "1",
        "submissionTime": 1648471522
      },
      {
        "fromAccount": "[email protected]",
        "fromWalletType": "spot",
        "toAccount": "[email protected]",
        "toWalletType": "spot",
        "currency": "BTC",
        "amount": "30",
        "submissionTime": 1648466178
      }
    ]
  }
}
Field Type Description
fromAccount string Transfer out Sub-Account username
fromWalletType string Transfer out wallet type
spot=spot wallet
toAccount string Transfer to Sub-Account username
toWalletType string Transfer to wallet type
spot=spot wallet
currency string currency
amount string Transfer amount
submissionTime long The request timestamp is accurate to seconds(UTC-0)

Get Sub-Account Spot Wallet Balance (For Main Account)

Get Sub-Account Spot Wallet Balance (For Main Account) (Authentication type:KEYED, See Interface Permission)

Request Format

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/account/sub-account/main/v1/wallet?subAccount=[email protected]
Field Type Required? Description
subAccount string Yes Sub-Account username
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 Sub-account List (For Main Account)

Get Sub-account List (For Main Account) (Authentication type:KEYED, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/account/sub-account/main/v1/subaccount-list

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/account/sub-account/main/v1/subaccount-list

Response Data

Response

{
  "message": "OK",
  "code": 1000,
  "trace": "c03c22c3-75db-4aaa-9500-6dcd63dd9ccf",
  "data": {
    "subAccountList": [
      {
        "accountName": "[email protected]",
        "status": 1
      },
      {
        "accountName": "[email protected]",
        "status": 1
      }
    ]
  }
}
Field Type Description
accountName string Sub-Account username
status int Account Status
'1' = normal
'0' = disabled in background
'2' = frozen by main account

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
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",
        "contract_address": null,
        "network": "OMNI",
        "withdraw_enabled": false,
        "deposit_enabled": false,
        "withdraw_minsize": null,
        "withdraw_minfee": null
      },
      {
        "currency": "USDT-TRC20",
        "name": "USDT-TRC20",
        "contract_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
        "network": "TRC20",
        "withdraw_enabled": true,
        "deposit_enabled": true,
        "withdraw_minsize": "10",
        "withdraw_minfee": "1"
      },
      {
        "currency": "USDT-ERC20",
        "name": "USDT-ERC20",
        "contract_address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
        "network": "ERC20",
        "withdraw_enabled": true,
        "deposit_enabled": true,
        "withdraw_minsize": "26",
        "withdraw_minfee": "13"
      },
      {
        "currency": "USDT-BSC",
        "name": "USDT-BSC",
        "contract_address": "0x55d398326f99059fF775485246999027B3197955",
        "network": "BEP20(BSC)",
        "withdraw_enabled": true,
        "deposit_enabled": true,
        "withdraw_minsize": "2",
        "withdraw_minfee": "1"
      }
    ]
  }
}
Field Type Description
currency string Token symbol, e.g., 'BTC'
name string Token name, e.g., 'Bitcoin'
contract_address string Contract address
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
withdraw_minsize string Minimum withdrawal amount
withdraw_minfee string Minimum withdrawal fee

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&operation_type=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

Get Margin Account Details(Isolated)

Applicable for isolated margin account inquiries (Authentication type:KEYED, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/spot/v1/margin/isolated/account

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v1/margin/isolated/account
Field Type Required? Description
symbol string No Trading pair, like (BTC_USDT), no symbol is passed, and all isolated margin assets are returned

Response Data

Response

{
    "message":"OK",
    "code":1000,
    "trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
    "data":{
      "symbols":[
        {
          "symbol": "BTC_USDT",
          "risk_rate": "18.77",
          "risk_level": "1",
          "buy_enabled": true,
          "sell_enabled": true,
          "liquidate_price": "-0.09408905",
          "liquidate_rate": "1.1",
          "base": {
            "currency": "BTC",
            "borrow_enabled": false,
            "borrowed": "2.00000000",
            "borrow_unpaid": "0.84478234",
            "interest_unpaid": "0.01385763",
            "available": "112.89603334",
            "frozen": "0.00000000",
            "net_asset": "110.89603334",
            "net_assetBTC": "0.00000000",
            "total_asset": "112.89603334"
          },
          "quote": {
            "currency": "USDT",
            "borrow_enabled": true,
            "borrowed": "0.00000000",
            "borrow_unpaid": "0.84478234",
            "interest_unpaid": "0.01385763",
            "available": "10.00000000",
            "frozen": "0.00000000",
            "net_asset": "10.00000000",
            "net_assetBTC": "0.00000000",
            "total_asset": "10.00000000"
          }
        },
        ...
      ]
    }
}
Field Type Description
symbol string Trading pair
risk_rate string Current risk rate
risk_level string Risk level
buy_enabled Boolean Whether open to buy
sell_enabled Boolean Whether open to sell
liquidate_price string Liquidation price (precision: 8 decimal places)
liquidate_rate string Liquidation rate
currency string Currency
borrow_enabled Boolean Whether open to borrow
borrowed string Borrowed assets (precision: 8 decimal places)
borrow_unpaid string Outstanding principal amount (precision: 8 decimal places)
interest_unpaid string Interest outstanding (precision: 8 decimal places)
available string Available assets (precision: 8 decimal places)
frozen string Trading frozen assets (precision: 8 decimal places)
net_asset string Net assets (precision: 8 decimal places)
net_assetBTC string Converted BTC net assets (precision: 8 decimal places)
total_asset string Total assets (precision: 8 decimal places)

Margin Asset Transfer

For fund transfers between a margin account and spot account (Authentication type:SIGNED, See Interface Permission)

Request Format

POST https://api-cloud.bitmart.com/spot/v1/margin/isolated/transfer

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v1/margin/isolated/transfer
{
    "symbol":"BTC_USDT",
    "currency":"BTC",
    "amount":"1",
    "side":"in"
}
Field Type Required? Description
symbol string Yes Trading pair(Like BTC_USDT)
currency string Yes Currency
amount string Yes Amount of transfers (precision: 8 decimal places)
side string Yes Transfer direction
Yes in=Transfer in
Yes out=Transfer out

Response Data

Response

{
    "message":"OK",
    "code":1000,
    "trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
    "data":{
      "transfer_id":"124532"
    }
}
Field Type Description
transfer_id string Transfer order id, only successful transfers will be returned

Get Basic Fee Rate

For querying the base rate of the current user (Authentication type:KEYED, See Interface Permission)

Request Format

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

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

Response Data

Response

{
  "message":"OK",
  "code":1000,
  "trace":"0187ba0c876e4236ac191d9848a0f719.94.16778301620100121",
  "data":{
    "user_rate_type":0,
    "level":"LV1",
    "taker_fee_rate_A":"0.001",
    "maker_fee_rate_A":"0.001",
    "taker_fee_rate_B":"0.0025",
    "maker_fee_rate_B":"0.0025",
    "taker_fee_rate_C":"0.004",
    "maker_fee_rate_C":"0.004"
  }
}
Field Type Description
user_rate_type Long Rate type:0-Normal Users, 1-VIP Users, 2-Special VIP Users
level string User Level
taker_fee_rate_A string Taker fee rate for Class-A pairs
maker_fee_rate_A string Maker fee rate for Class-A pairs
taker_fee_rate_B string Taker fee rate for Class-B pairs
maker_fee_rate_B string Maker fee rate for Class-B pairs
taker_fee_rate_C string Taker fee rate for Class-C pairs
maker_fee_rate_C string Maker fee rate for Class-C pairs

Get Actual Trade Fee Rate

For the actual fee rate of the trading pairs (Authentication type:KEYED, See Interface Permission)

Request Format

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v1/trade_fee?symbol=BTC_USDT
Field Type Required? Description
symbol string Yes Trading pair, like (BTC_USDT)

Response Data

Response

{
  "message": "OK",
  "code": 1000,
  "trace": "87614aa8-5327-4fe2-aafc-02e2ddca7210",
  "data": {
    "symbol": "BTC_USDT",
    "buy_taker_fee_rate": "0.0008",
    "sell_taker_fee_rate": "0.0008",
    "buy_maker_fee_rate": "0.0006",
    "sell_maker_fee_rate": "0.0006"
  }
}
Field Type Description
symbol string Trading pair
buy_taker_fee_rate string Taker fee rate (Buy)
sell_taker_fee_rate string Taker fee rate (Sell)
buy_maker_fee_rate string Maker fee rate (Buy)
sell_maker_fee_rate string Maker fee rate (Sell)

Spot / Margin Trading

Place Spot Order

Applicable for spot order placement (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
clientOrderId string No Client-defined OrderId(A combination of numbers and letters, less than 32 bits)

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

Place Spot Order (V2)

Applicable for spot order placement (Authentication type:SIGNED, See Interface Permission)

Request Format

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v2/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
client_order_id string No Client-defined OrderId(A combination of numbers and letters, less than 32 bits)

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 string Order ID

Place Margin Order

Applicable for margin order placement (Authentication type:SIGNED, See Interface Permission)

Request Format

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v1/margin/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
clientOrderId string No Client-defined OrderId(A combination of numbers and letters, less than 32 bits)

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

{
    "message":"OK",
    "code":1000,
    "trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
    "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
clientOrderId string No Client-defined OrderId(A combination of numbers and letters, less than 32 bits)

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

Batch Order (V2)

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

Request Format

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v2/batch_orders
{
    "order_params":[
        {
        "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
order_params 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
client_order_id string No Client-defined OrderId(A combination of numbers and letters, less than 32 bits)

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": {
    "responses": [
      {
        "code": 11402,
        "msg": "Balance not enough"
      },
      {
        "code": 0,
        "msg": "SUCCESS",
        "data": {
          "order_id": "145771"
        }
      }
    ]
  }
}
Field Type Description
order_id string 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
{
  "order_id":112121212
}
Field Type Required? Description
order_id long No Order id
clientOrderId string No Client-defined OrderId

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 an Order (V3)

Applicable to the cancellation of a specified unfinished order (Authentication type:SIGNED, See Interface Permission)

Request Format

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v3/cancel_order
{
  "symbol": "BTC_USDT",
  "order_id": "112121212"
}
Field Type Required? Description
symbol string Yes Trading pairs(e.g. BTC_USDT)
order_id string No Order ID
client_order_id string No Client-defined 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:KEYED, 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?order_id=1736871726781
Field Type Required? Description
order_id long No Order id
clientOrderId string No Client-defined OrderId

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",
        "order_mode":"spot",
        "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",
        "clientOrderId":"d9850c05-9091-4740-ae07-43e62153e9bd"
    }
}
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
order_mode string Order mode
spot=spot trade
iso_margin=isolated margin trade
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
4=Order success, Pending for fulfilment
5=Partially filled
6=Fully filled
8=Canceled
clientOrderId string Client-defined OrderId (If the field is not defined, a random string is returned)

Get Order Detail (V2)

Applicable query a specified order detail (Authentication type:KEYED, See Interface Permission)

Request Format

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v2/order_detail?order_id=1736871726781
Field Type Required? Description
order_id string Yes Order ID

Response Data

Response

{
    "message":"OK",
    "code":1000,
    "trace":"a27c2cb5-ead4-471d-8455-1cfeda054ea6",
    "data":{
        "order_id":"1736871726781",
        "client_order_id":"d9850c05-9091-4740-ae07-43e62153e9bd",
        "symbol":"BTC_USDT",
        "create_time":1591096004000,
        "side":"sell",
        "order_mode":"spot",
        "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 string Order ID
client_order_id string Client-defined OrderId (If the field is not defined, a random string is returned)
symbol string Trading pair (e.g. BMX_USDT)
create_time long Timestamp, accurate to milliseconds
side string Side
buy=Buy order
sell=Sell order
order_mode string Order mode
spot=spot trade
iso_margin=isolated margin trade
type string Order type
limit=Limit order
market=Market order
limit_maker=PostOnly order
ioc=IOC 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
4=Order success, Pending for fulfilment
5=Partially filled
6=Fully filled
8=Canceled
11=Partially filled and canceled

Get User Order History

Get a list of user orders (Authentication type:KEYED, 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=4&N=100
Field Type Required? Description
symbol string Yes Trading pair (e.g. BTC_USDT)
order_mode string No Order mode, Default returns spot
spot=spot trade
iso_margin=isolated margin trade
all=all modes
N int Yes Recent N records (value range 1-100)
status string Yes Status
4=Order success, Pending for fulfilment
5=Partially filled
6=Fully filled
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",
        "order_mode":"spot",
        "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",
        "clientOrderId":"d9850c05-9091-4740-ae07-43e62153e9bd"
      }
    ]
  }
}
Field Type Description
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
order_mode string Order mode
spot=spot trade
iso_margin=isolated margin trade
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
4=Order success, Pending for fulfilment
5=Partially filled
6=Fully filled
8=Canceled
clientOrderId string Client-defined OrderId (If the field is not defined, a random string is returned)

Get User Order History (V3)

Applicable to search for order history within a certain time frame, up to 200 records (Authentication type:KEYED, See Interface Permission)

Request Format

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v3/orders?symbol=BTC_USDT&status=4&N=100
Field Type Required? Description
symbol string Yes Trading pair (e.g. BTC_USDT)
order_mode string No Order mode, Default returns spot
spot=spot trade
iso_margin=isolated margin trade
all=all modes
N int No Records amount (value range 1-200, default is 200)
start_time long No Start time timestamp in millsecond, must be within the last three months
end_time long No End time timestamp in millsecond, must be within the last three months
status string Yes Status
4=Order success, Pending for fulfilment
5=Partially filled
6=Fully filled
8=Canceled
9=Outstanding (4 and 5)
10= 6 and 8 and 11
11=Partially filled and canceled

Response Data

Response

{
  "message":"OK",
  "code":1000,
  "trace":"70e7d427-7436-4fb8-8cdd-97e1f5eadbe9",
  "data":{
    "orders":[
      {
        "order_id":"2147601241",
        "symbol":"BTC_USDT",
        "create_time":1591099963000,
        "side":"sell",
        "order_mode":"spot",
        "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",
        "client_order_id":"bm4877624"
      }
    ]
  }
}
Field Type Description
orders List Order list
order_id string 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
order_mode string Order mode
spot=spot trade
iso_margin=isolated margin trade
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
4=Order success, Pending for fulfilment
5=Partially filled
6=Fully filled
8=Canceled
11=Partially filled and canceled
client_order_id string Client-defined OrderId (If the field is not defined, a random string is returned)

Get User Trade History

Get user trade history (Authentication type:KEYED, 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)
order_mode string No Order mode, Default returns spot
spot=spot trade
iso_margin=isolated margin trade
all=all modes

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",
                "order_mode":"spot",
                "fees":"0.00001350",
                "fee_coin_name":"BTC",
                "notional":"88.00000000",
                "price_avg":"8800.00",
                "size":"0.01000",
                "exec_type":"M",
                "clientOrderId":"d9850c05-9091-4740-ae07-43e62153e9bd"
            },
            ...
        ]
    }
}
Field Type Description
trades 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
order_mode string Order mode
spot=spot trade
iso_margin=isolated margin trade
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
clientOrderId string Client-defined OrderId (If the field is not defined, a random string is returned)

Get User Trade History (V2)

Applicable for searching the trade history within a certain time frame, up to 200 records (Authentication type:KEYED, See Interface Permission)

Request Format

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v2/trades?symbol=BTC_USDT&N=10
Field Type Required? Description
symbol string Yes Trading pair (e.g. BTC_USDT)
order_mode string No Order mode, Default returns spot
spot=spot trade
iso_margin=isolated margin trade
all=all modes

Special Parameters for Querying Trade Record of a Single Order

Field Type Required? Description
order_id string No Order ID

Special Parameters for Querying Trade Record of All Orders

Field Type Required? Description
N int No Records amount (value range 1-200, default is 200)
start_time long No Start time timestamp in millsecond, must be within the last three months
end_time long No End time timestamp in millsecond, must be within the last three months

Response Data

Response

{
  "message":"OK",
  "code":1000,
  "trace":"a06a5c53-8e6f-42d6-8082-2ff4718d221c",
  "data":{
    "trades":[
      {
        "detail_id":"256348632",
        "order_id":"2147484350",
        "symbol":"BTC_USDT",
        "create_time":1590462303000,
        "side":"buy",
        "order_mode":"spot",
        "fees":"0.00001350",
        "fee_coin_name":"BTC",
        "notional":"88.00000000",
        "price_avg":"8800.00",
        "size":"0.01000",
        "exec_type":"M",
        "client_order_id":"bm476897"
      },
      ...
    ]
  }
}
Field Type Description
trades List Order list
detail_id string Trade id
order_id string Order id
symbol string Trading pair symbol
create_time long Trade time (in milliseconds)
side string Side
buy=Buy order
sell=Sell order
order_mode string Order mode
spot=spot trade
iso_margin=isolated margin trade
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
client_order_id string Client-defined OrderId (If the field is not defined, a random string is returned)

Margin Loan

Margin Borrow (Isolated)

Applicable to isolated margin account borrowing operations (Authentication type:SIGNED, See Interface Permission)

Request Format

POST https://api-cloud.bitmart.com/spot/v1/margin/isolated/borrow

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v1/margin/isolated/borrow
{
    "symbol":"BTC_USDT",
    "currency":"BTC",
    "amount":"1"
}
Field Type Required? Description
symbol string Yes Borrowing trading pairs(like BTC_USDT)
currency string Yes Borrowing currency, selected according to the borrowing trading pair(like BTC or USDT)
amount string Yes Amount of borrowing (precision: 8 decimal places)

Response Data

Response

{
    "message":"OK",
    "code":1000,
    "trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
    "data":{
      "borrow_id":"113896"
    }
}
Field Type Description
borrow_id string Borrowing order ID, only successful borrowing will be returned

Margin Repay (Isolated)

Applicable to isolated margin account repayment operations (Authentication type:SIGNED, See Interface Permission)

Request Format

POST https://api-cloud.bitmart.com/spot/v1/margin/isolated/repay

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v1/margin/isolated/repay
{
    "symbol":"BTC_USDT",
    "currency":"BTC",
    "amount":"1"
}
Field Type Required? Description
symbol string Yes Repayment trading pairs(like BTC_USDT)
currency string Yes Repayment currency, selected according to the borrowing trading pair(like BTC or USDT)
amount string Yes Amount of repayments (precision: 8 decimal places)

Response Data

Response

{
    "message":"OK",
    "code":1000,
    "trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
    "data":{
        "repay_id":"123165"
    }
}
Field Type Description
repay_id string Repayment order ID, only successful repayment will be returned

Get Borrow Record(Isolated)

Applicable to the inquiry of borrowing records of an isolated margin account (Authentication type:KEYED, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/spot/v1/margin/isolated/borrow_record

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v1/margin/isolated/borrow_record?symbol=BTC_USDT
Field Type Required? Description
symbol string Yes Trading pair(like BTC_USDT)
borrow_id string No Borrow order id
start_time long No Query start time: Timestamp
end_time long No Query end time: Timestamp
N int No Query record size (1-100). Default is 50

Response Data

Response

{
    "message":"OK",
    "code":1000,
    "trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
    "data":{
      "records":[
        {
          "borrow_id": "133425",
          "symbol": "BTC_USDT",
          "currency": "BTC",
          "borrow_amount": "1.23854339",
          "daily_interest": "0.05",
          "hourly_interest": "0.00208334",
          "interest_amount": "0.02398474",
          "create_time": 1655345808
        },
        ...
      ]
    }
}
Field Type Description
borrow_id string Borrow order id
symbol string Trading pair
currency string Currency
borrow_amount string The total principal amount borrowed (precision: 8 decimal places)
daily_interest string Daily interest
hourly_interest string Hourly interest
interest_amount string Total interest (precision: 8 decimal places)
create_time long Order creation time

Get Repayment Record(Isolated)

Applicable to the inquiry of repayment records of isolated margin account (Authentication type:KEYED, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/spot/v1/margin/isolated/repay_record

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v1/margin/isolated/repay_record?symbol=BTC_USDT
Field Type Required? Description
symbol string Yes Trading pair(like BTC_USDT)
repay_id string No Repayment ID
currency string No Currency
start_time long No Query start time: Timestamp
end_time long No Query end time: Timestamp
N int No Query record size (1-100). Default is 50

Response Data

Response

{
    "message":"OK",
    "code":1000,
    "trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
    "data":{
      "records":[
        {
          "repay_id":"118723",
          "repay_time":1655345808,
          "symbol":"BTC_USDT",
          "currency":"BTC",
          "repaid_amount":"1.1",
          "repaid_principal":"1",
          "repaid_interest":"0.1"
        },
        ...
      ]
    }
}
Field Type Description
repay_id string Repayment ID
repay_time long Repayment Timestamp
symbol string Repayment trading pairs(like BTC_USDT)
currency string Repayment currency
repaid_amount string Repayment amount
repaid_principal string The principal amount returned by this repayment
repaid_interest string Interest returned by this repayment

Get Trading Pair Borrowing Rate and Amount

Applicable for checking the borrowing rate and borrowing amount of trading pairs (Authentication type:KEYED, See Interface Permission)

Request Format

GET https://api-cloud.bitmart.com/spot/v1/margin/isolated/pairs

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v1/margin/isolated/pairs
Field Type Required? Description
symbol string No It can be multiple-choice; if not filled in, then return all, like BTC_USDT, ETH_USDT

Response Data

Response

{
    "message":"OK",
    "code":1000,
    "trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
    "data":{
      "symbols":[
        {
          "symbol": "BTC_USDT",
          "max_leverage": "10",
          "symbol_enabled": true,
          "base": {
            "currency": "BTC",
            "daily_interest": "0.05",
            "hourly_interest": "0.00208334",
            "max_borrow_amount": "1000.00000000",
            "min_borrow_amount": "1.00000000",
            "borrowable_amount": "955.90221219"
          },
          "quote": {
            "currency": "USDT",
            "daily_interest": "0.05",
            "hourly_interest": "0.00208334",
            "max_borrow_amount": "12000.00000000",
            "min_borrow_amount": "0.01000000",
            "borrowable_amount": "12000.00000000"
          }
        },
        ...
      ]
    }
}
Field Type Description
symbol string Trading pair
max_leverage string Leverage multiplier
symbol_enabled Boolean Whether the trading pair is enabled
currency string Currency
daily_interest string Daily interest
hourly_interest string Hourly interest
max_borrow_amount string The maximum amount of borrowing (precision: 8 decimal places)
min_borrow_amount string The minimum amount of borrowing (precision: 8 decimal places)
borrowable_amount string The current available amount of borrowing (precision: 8 decimal places)

WebSocket Subscription

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

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

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

The following is the data format of ping:

ws.send(new PingWebSocketFrame();

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

Connection Limit

Public Channel

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

Private Channel

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

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

【Public】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)

【Public】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

【Public】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)

【Public】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)

【Private】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

【Private】Order Progress

Get user trade data

Pushing Rules

  1. 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":"4",
            "order_id":"2147857398",
            "order_type":"0",
            "last_fill_time":"1609926039226",
            "last_fill_price":"46100.00000",
            "last_fill_count":"1.00000",
            "exec_type":"M",
            "detail_id":"256348632",
            "client_order_id":"order4872191"
        }
    ],
    "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
4=Order success, Pending for fulfilment
5=Partially filled
6=Fully filled
8=Canceled
12=Canceled after Partially filled
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
exec_type string Whether the trade was created by a maker or a taker. M means Maker, T means Taker
detail_id string Trade id
client_order_id string Client-defined OrderId

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&Sub-Account 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
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
The specified sub-account could not be found 61003 400
Duplicate requests (such as using an existing requestNo) 61004 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
Sub-account does not have permission to operate 60026 403
Only supports sub-account calls 60027 403
Account is disabled for security reasons, please contact customer service 60028 403
The account is frozen by the master account, please contact the master account to unfreeze the account 60029 403
Asset transfer between accounts is not available 61005 403
The sub-account api only supports organization accounts 61006 403
Method Not Allowed 60030 405
Unsupported Media Type 60031 415
User account not found 60050 500
Internal Server Error 60051 500

Spot&Margin 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
The order was matched or cancelled 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
The maximum length of clientOrderId cannot exceed 32 50037 400
ClientOrderId only allows a combination of numbers and letters 50038 400
Order_id and clientOrderId cannot be empty at the same time 50039 400
Symbol Not Available 50040 400
Out of query time range 50041 400
clientOrderId is duplicate 50042 400
Currency not found 51000 400
Margin Account not Opened 51001 400
Margin Account Not Available 51002 400
Account Limit 51003 400
Exceed the maximum number of borrows available 51004 400
Less than the minimum borrowable amount 51005 400
Exceeds the amount to be repaid 51006 400
order_mode not found 51007 400
Operation is limited, please try again later 51008 400
Parameter mismatch: limit order/market order quantity should be greater than the minimum number of should buy/sell 51009 400
Parameter mismatch: limit order price should be greater than the minimum buy price 51010 400
Parameter mismatch: Limit order quantity * price should be greater than the minimum transaction amount 51011 400
Participation mismatch: the number of market order buy orders should be greater than the minimum buyable amount 51012 400
Parameter mismatch: the price of market order buy order placed is too small 51013 400
Parameter mismatch: the amount of market order sell orders placed is too small 51014 400
Quantity is too small 51015 400
Your account is frozen due to security policies. Please contact customer service 53000 403
Your kyc country is restricted. Please contact customer service. 53001 403
Your account has not yet completed the kyc advanced certification, please complete first 53002 403
No permission, please contact the main account 53003 403
This trading pair is not available to trade in your region 53004 403
Don't have permission to access the interface 53005 403
Please complete your personal verification(Starter) 53006 403
Please complete your personal verification(Advanced) 53007 403
Services is not available in your countries and areas 53008 403
Your account has not yet completed the qr code certification, please complete first 53009 403
Method Not Allowed 57001 405
Unsupported Media Type 58001 415
User account not found 59001 500
Internal Server Error 59002 500
Spot wallet call fail 59003 500
Margin wallet service call exception 59004 500
Margin wallet service restricted 59005 500
Transfer fail 59006 500
Get symbol risk data fail 59007 500
Trading order failure 59008 500
Loan success,but trading order failure 59009 500
Insufficient loan amount. 59010 500
The Get Wallet Balance service call fail, please try again later 59011 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

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.