NAV
Example

Change Log

2024-02-29

2024-02-19

2023-10-27

2023-09-08

2023-08-14

2023-05-09

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

Introduction

API Key Create

PNG

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

PNG

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

API Key Permission Settings

PNG

Read-Only Permissions:
API Name Description Authentication Type
/account/v1/wallet Query account assets KEYED
/account/v1/deposit/address Query deposit addresses for each currency KEYED
/account/v2/deposit-withdraw/history Query deposit and withdrawal history KEYED
/account/v1/deposit-withdraw/detail Query deposit and withdrawal details KEYED
/spot/v1/wallet Query wallet balance for all currencies KEYED
/spot/v1/order_detail Query order details KEYED
/spot/v2/order_detail Query order details KEYED
/spot/v1/orders Query user's recent orders KEYED
/spot/v2/orders Query user's recent orders KEYED
/spot/v3/orders Query user's recent orders KEYED
/spot/v1/trades Query user's trade history KEYED
/spot/v2/trades Query user's trade history KEYED
/spot/v4/query/order Query order by id (v4) SIGNED
/spot/v4/query/client-order Query order by client order id (v4) SIGNED
/spot/v4/query/open-orders Current open orders (v4) SIGNED
/spot/v4/query/history-orders Account orders (v4) SIGNED
/spot/v4/query/trades Account trade list (v4) SIGNED
/spot/v4/query/order-trades Order trade list(v4) SIGNED
/spot/v1/user_fee Query basic fee rate for current user KEYED
/spot/v1/trade_fee Query fee rate for a specific trading pair for current user KEYED
/spot/v1/margin/isolated/pairs Query loan interest rate and limit for a trading pair KEYED
/spot/v1/margin/isolated/account Query isolated margin account information KEYED
/spot/v1/margin/isolated/borrow_record Query isolated margin borrowing record KEYED
/spot/v1/margin/isolated/repay_record Query isolated margin repayment record KEYED
/contract/private/get-open-orders Query Contract All Open Orders KEYED
/contract/private/order Query contract order details KEYED
/contract/private/order-history Query contract order history KEYED
/contract/private/trades Query contract trade details KEYED
/contract/private/assets-detail Query contract asset details KEYED
/contract/private/position Query position details KEYED
/contract/private/current-plan-order Query Current Plan Orders KEYED
Withdraw Permissions:
API Name Description Authentication Type
/account/v1/withdraw/charge Query withdrawal limits KEYED
/account/v1/withdraw/apply Apply for withdrawal SIGNED
Spot-Trade Permissions:
API Name Description Authentication Type
/spot/v1/submit_order Place an order SIGNED
/spot/v2/submit_order Place an order SIGNED
/spot/v1/batch_orders Place multiple orders SIGNED
/spot/v2/batch_orders Place multiple orders SIGNED
/spot/v1/cancel_order Cancel an unfinished order SIGNED
/spot/v3/cancel_order Cancel an unfinished order SIGNED
/spot/v1/cancel_orders Cancel all unfinished orders for a specified trading pair and direction SIGNED
Margin-Trade Permissions:
API Name Description Authentication Type
/spot/v1/margin/submit_order Margin order placement SIGNED
/spot/v1/margin/isolated/transfer Transfer funds between margin and spot accounts SIGNED
/spot/v1/margin/isolated/borrow Isolated margin borrowing SIGNED
/spot/v1/margin/isolated/repay Repay isolated margin debt SIGNED
Future-Trade Permissions:
API Name Description Authentication Type
/contract/private/submit-order Place an order for a futures contract SIGNED
/contract/private/cancel-order Cancel a single futures order SIGNED
/contract/private/cancel-orders Batch cancel futures orders SIGNED
/contract/private/submit-plan-order Place a batch order for futures contracts SIGNED
/contract/private/cancel-plan-order Batch cancel futures orders SIGNED
/account/v1/transfer-contract Future account transfer SIGNED
/account/v1/transfer-contract-list Get Future account transfer list SIGNED
Sub-Account Permissions:

You need to enter Institution Verification to use the sub-account endpoints.

After the creation is successful, the sub-account has Read-only permission by default.

PNG

Sub-Account Spot-Trade Permissions:

Same as the above spot trading authority

Sub-Account Contract-Trade Permissions:

Same as above futures trading authority

Sub-Account Inter-Account Transfer Permissions:
API Name Description Authentication Type
/account/sub-account/main/v1/sub-to-main Sub-Account Transfer to Main-Account (For Main Account, ues spot account) SIGNED
/account/sub-account/sub/v1/sub-to-main Sub-Account Transfer to Main-Account (For Sub-Account, ues spot account) SIGNED
/account/sub-account/main/v1/main-to-sub Main-Account Transfer to Sub-Account (For Main Account, ues spot account) SIGNED
/account/sub-account/sub/v1/sub-to-sub Sub-Account Transfer to Sub-Account (For Sub-Account, ues spot account) SIGNED
/account/sub-account/main/v1/sub-to-sub Sub-Account Transfer to Sub-Account (For Main Account, ues spot account) SIGNED
/account/sub-account/main/v1/transfer-list Get Sub-Account Transfer History (For Main Account, ues spot account) KEYED
/account/sub-account/v1/transfer-history Get Account Spot Asset Transfer History (For Main/Sub Account, ues spot account) KEYED
/account/sub-account/main/v1/wallet Get Sub-Account Spot Wallet Balance (For Main Account, ues spot account) KEYED
/account/sub-account/main/v1/subaccount-list Get Sub-Account List (For Main Account, ues spot account) KEYED
/account/contract/sub-account/main/v1/sub-to-main Sub-Account Transfer to Main-Account (For Main Account, ues futures account) SIGNED
/account/contract/sub-account/main/v1/main-to-sub Main-Account Transfer to Sub-Account (For Main Account, ues futures account) SIGNED
/account/contract/sub-account/sub/v1/sub-to-main Sub-Account Transfer to Main-Account (For Sub-Account, ues futures account) SIGNED
/account/contract/sub-account/main/v1/wallet Get Sub-Account Futures Wallet Balance (For Main Account, ues futures account) KEYED
/account/contract/sub-account/v1/transfer-history Get Account Futures Asset Transfer History (For Main/Sub Account, ues futures account) KEYED
/account/contract/sub-account/main/v1/transfer-list Get Sub-Account Transfer History (For Main Account, ues futures account) KEYED

API Library

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

Available SDK:

In addition to the SDK, we also provide code samples in multiple languages, and the samples mainly demonstrate how to use the signed interface. It can be built and run standalone or as part of your codebase.

FAQ

Here are some frequently asked questions.

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

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

Q3. How is the HTTP status code 429 created?

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

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

Q6. Where is the location of BitMart servers?

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

Q8. Why does it prompt "IP is forbidden. We recommend enabling IP whitelist for API trading. "

Contact Us

Basic Information

API Basic Information

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

Request Parameter Settings

HTTP Response Codes

API Returned Codes

For details, please refer to Error Code List

Signature

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

Authentication Type

1. Setting Request Parameters

1.1 Set Request Header Key

Create X-BM-TIMESTAMP

// Java
System.currentTimeMillis();

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

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

// Nodejs & TypeScript
Date.now();

// Javascript
Date.now();

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

// C#
DateTimeOffset.UtcNow.ToUnixTimeMilliseconds()

1.2 Set Request Body Params

2. Example

Shell Example

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

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

Then set the following:

Assuming the key you applied for is as follows:

then the right side is a complete request

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

Rate Limit

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

The specific interface limits are as follows:

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
/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
Spot Public Market Interface Interface Name Limit Target Rate
/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/quotation/v3/tickers Get Ticker of All Pairs (V3) IP 10 times/2 sec
/spot/quotation/v3/ticker Get Ticker of a Trading Pair(V3) IP 15 times/2 sec
/spot/quotation/v3/lite-klines Get Latest K-Line (V3) IP 15 times/2 sec
/spot/quotation/v3/klines Get History K-Line (V3) IP 10 times/2 sec
/spot/quotation/v3/books Get Depth(V3) IP 15 times/2 sec
/spot/quotation/v3/trades Get Recent Trades(V3) IP 15 times/2 sec
Spot Trading Interface Interface Name Limit Target Rate
/spot/v1/wallet Get the user's wallet balance(KEYED) X-BM-KEY 12 times/2 sec
/spot/v1/submit_order New Order (SIGNED) X-BM-KEY 60 times/2 sec
/spot/v2/submit_order New Order(v2) (SIGNED) X-BM-KEY 60 times/2 sec
/spot/v1/batch_orders New Batch Order (SIGNED) X-BM-KEY 60 times/2 sec
/spot/v2/batch_orders New Batch Order(v2) (SIGNED) X-BM-KEY 60 times/2 sec
/spot/v1/margin/submit_order New Margin Order (SIGNED) X-BM-KEY 60 times/2 sec
/spot/v2/cancel_order Cancel Order(v2) (SIGNED) X-BM-KEY 60 times/2 sec
/spot/v3/cancel_order Cancel Order(v3) (SIGNED) X-BM-KEY 60 times/2 sec
/spot/v1/cancel_orders Cancel Batch Order (SIGNED) X-BM-KEY 4 times/2 sec
/spot/v1/order_detail Query Order(v1) (KEYED) X-BM-KEY 60 times/2 sec
/spot/v2/order_detail Query Order(v2) (KEYED) X-BM-KEY 60 times/2 sec
/spot/v2/orders Account Orders(v2) (KEYED) X-BM-KEY 12 times/2 sec
/spot/v3/orders Account Orders(v3) (KEYED) X-BM-KEY 12 times/2 sec
/spot/v1/trades Account Trade List(v1) (KEYED) X-BM-KEY 12 times/2 sec
/spot/v2/trades Account Trade List(v2) (KEYED) X-BM-KEY 12 times/2 sec
/spot/v4/query/order Query Order By Id(v4) (SIGNED) X-BM-KEY 60 times/2 sec
/spot/v4/query/client-order Query Order By clientOrderId(v4) (SIGNED) X-BM-KEY 60 times/2 sec
/spot/v4/query/open-orders Current Open Orders(v4) (SIGNED) X-BM-KEY 12 times/2 sec
/spot/v4/query/history-orders Account Orders(v4) (SIGNED) X-BM-KEY 12 times/2 sec
/spot/v4/query/trades Account Trade List(v4) (SIGNED) X-BM-KEY 12 times/2 sec
/spot/v4/query/order-trades Order Trade List(v4) (SIGNED) X-BM-KEY 12 times/2 sec
Sub-Account Interface Interface Name Limit Target Rate
/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
/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

REST API

Speed limit judgment:

Each call to the interface will return 3 Response Headers with limit tags, as shown below:

Example:

X-BM-RateLimit-Remaining: 10
X-BM-RateLimit-Limit: 600
X-BM-RateLimit-Reset: 60
The above setting means that it can be called 600 times within 60 seconds, and currently has been called 10 times
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

About recvWindow, timestamp

Currently only applicable to v4 interfaces

Time synchronization security

Signed interfaces require the timestamp parameter to be passed, whose value should be the Unix timestamp (in milliseconds) at the time the request is sent, set in the X-BM-TIMESTAMP header of the request. When the server receives the request, it will check the timestamp in the request. If it was sent more than 5000 milliseconds ago, the request will be considered invalid. This time window value can be defined by sending the optional parameter recvWindow.

The pseudo code for this logic is as follows:

  if (timestamp < (serverTime + 1000) && (serverTime - timestamp) <= recvWindow)
  {
    // process request
  } 
  else 
  {
    // reject request
  }

About trade timeliness

The internet is not always stable and reliable, so there may be latency fluctuations between your program and the BitMart server. This is the purpose of setting recvWindow. If you are engaged in high-frequency trading and have high requirements for trade timeliness, you can set recvWindow flexibly to meet your requirements.

Public API Definitions

Field description

Order State (Field:state)

Order Side (Field:side)

Order Type (Field:type)

Trade Role (Field:tradeRole)

Timestamp

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

System Status

Get System Time

Get system time

Request URL

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

Request URL

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": {
    "service":[
      {
         "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

Public Market Data

Get Currency List (V1)

Get a list of all cryptocurrencies on the platform

Request URL

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

Get Trading Pairs List (V1)

Get a list of all trading pairs on the platform

Request URL

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
Note

Get Trading Pair Details (V1)

Get a detailed list of all trading pairs on the platform

Request URL

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
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 Trade Status
- trading=is trading
- pre-trade=pre-open

Get Ticker of All Pairs (V3)

Get the quotations of all trading pairs, including: snapshot information of the latest transaction price, first bid price, first ask price and 24-hour trading volume. Note that the interface is not real-time data, if you need real-time data, please use websocket to subscribe Ticker channel

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/quotation/v3/tickers`

None

Response Data

Response

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-1231",
  "message": "success",
  "data": [
    [
      "BTC_USDT",  // symbol
      "30000.00",  // last
      "582.08066", // v_24h
      "4793098.48", // qv_24h
      "28596.30", // open_24h
      "31012.44", // high_24h
      "12.44", // low_24h
      "0.04909", // fluctuation
      "30000", // bid_px
      "1",  // bid_sz
      "31012.44",  // ask_px
      "69994.75267", // ask_sz
      "1691671091933" // ts
    ],
    [
      "ETH_USDT",
      "1840.00",
      "2.00000",
      "3680.00",
      "1842.18",
      "1842.18",
      "1840.00",
      "-0.00118",
      "1812.35",
      "4.61989",
      "1859.34",
      "4.07793",
      "1691671094213"
    ]
  ]
}
Field Type Description
symbol String Trading pair
last String Latest price
v_24h String 24-hour trade volume in base currency
qv_24h String 24-hour trade volume in quote currency
open_24h String 24-hour open price
high_24h String 24-hour highest price
low_24h String 24-hour lowest price
fluctuation String 24-hour price change
bid_px String top buy price
bid_sz String Size of top buy order
ask_px String top sell price
ask_sz String Size of top sell order
ts String Time of generation(in milliseconds)

Get Ticker of a Trading Pair (V3)

Applicable to query the aggregated market price of a certain trading pair, and return the latest ticker information. Note that the interface is not real-time data, if you need real-time data, please use websocket to subscribe Ticker channel

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/quotation/v3/ticker?symbol=BTC_USDT
Field Type Required? Description
symbol String Yes Trading pair (e.g. BMX_USDT)

Response Data

Response

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-1231",
  "message": "success",
  "data": {
    "symbol": "BTC_USDT",
    "last": "30000.00",
    "v_24h": "582.08066",
    "qv_24h": "4793098.48",
    "open_24h": "28596.30",
    "high_24h": "31012.44",
    "low_24h": "12.44",
    "fluctuation": "0.04909",
    "bid_px": "30000",
    "bid_sz": "1",
    "ask_px": "31012.44",
    "ask_sz": "69994.75267",
    "ts": "1691671061919"
  }
}
Field Type Description
symbol String Trading pair
last String Latest price
v_24h String 24-hour trade volume in base currency
qv_24h String 24-hour trade volume in quote currency
open_24h String 24-hour open price
high_24h String 24-hour highest price
low_24h String 24-hour lowest price
fluctuation String 24-hour price change
bid_px String top buy price
bid_sz String Size of top buy order
ask_px String top sell price
ask_sz String Size of top sell order
ts String Time of generation(in milliseconds)

Get Latest K-Line (V3)

Query the latest K-line and return a maximum of 1000 data. Note that the latest K-line of the interface is not real-time data. If you want real-time data, please use websocket to subscribe to K-line channel

Request URL

GET https://api-cloud.bitmart.com/spot/quotation/v3/lite-klines

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/quotation/v3/lite-klines?symbol=BMX_ETH&step=15&before=1525760116&after=1525769116&limit=100
Field Type Required? Description
symbol String Yes Trading pair (e.g. BMX_USDT)
before Long No Query timestamp (unit: second), query the data before this time
after Long No Query timestamp (unit: second), query the data after this time
step Int No k-line step, value [1, 3, 5, 15, 30, 45, 60,
120, 180, 240, 1440, 10080, 43200] unit: minute, default 1
limit Int No Return number, the maximum value is 200, default is 100

Response Data

Response

{
  "code":1000,
  "trace":"886fb6ae-456b-4654-b4e0-1231",
  "message": "success",
  "data":[
    [
      "1689736680",  // t
      "3.721",  // o
      "3.743",  // h
      "3.677",  // l
      "3.708",  // c
      "22698348.04828491",  // v
      "12698348.04828491"  // qv
    ],
    [
      "1689736620",
      "3.731",
      "3.799",
      "3.494",
      "3.72",
      "67632347.24399722",
      "37632347.24399722"
    ]
  ]
}
Field Type Description
t String Create timestamp (in seconds), It can be used as the unique identification of K line
o String Open price
h String Highest price
l String Lowest price
c String Close price
v String Trading volume, with a unit of currency (If in BTC_USDT, The unit is BTC)
qv String Trading volume, the value is the quantity in quote currency (If in BTC_USDT, The unit is USDT)

Get History K-Line (V3)

Get k-line data within a specified time range of a specified trading pair. Note that the interface is not real-time data, if you need real-time data, please use websocket to subscribe KLine channel

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/quotation/v3/klines?symbol=BMX_ETH&step=15&before=1525760116&after=1525769116&limit=100
Field Type Required? Description
symbol String Yes Trading pair (e.g. BMX_USDT)
before Long No Query timestamp (unit: second), query the data before this time
after Long No Query timestamp (unit: second), query the data after this time
step Int No k-line step, value [1, 3, 5, 15, 30, 45, 60,
120, 180, 240, 1440, 10080, 43200] unit: minute, default 1
limit Int No Return number, the maximum value is 200, default is 100

Response Data

Response

{
  "code":1000,
  "trace":"886fb6ae-456b-4654-b4e0-1231",
  "message": "success",
  "data":[
    [
      "1689736680",  // t
      "3.721",  // o
      "3.743",  // h
      "3.677",  // l
      "3.708",  // c
      "22698348.04828491",  // v
      "12698348.04828491"  // qv
    ],
    [
      "1689736620",
      "3.731",
      "3.799",
      "3.494",
      "3.72",
      "67632347.24399722",
      "37632347.24399722"
    ]
  ]
}
Field Type Description
t String Create timestamp (in seconds), It can be used as the unique identification of K line
o String Open price
h String Highest price
l String Lowest price
c String Close price
v String Trading volume, with a unit of currency (If in BTC_USDT, The unit is BTC)
qv String Trading volume, the value is the quantity in quote currency (If in BTC_USDT, The unit is USDT)

Get Depth (V3)

Get full depth of trading pairs. Note that the interface is not real-time data, if you need real-time data, please use websocket to subscribe Depth channel

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/quotation/v3/books?symbol=BTC_USDT&limit=1
Field Type Required? Description
symbol String Yes Trading pair (e.g. BMX_USDT)
limit Int No Order book depth per side. Maximum 50, e.g. 50 bids + 50 asks. Default returns to 35 depth data, e.g. 35 bids + 35 asks.

Response Data

Response

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-1231",
  "message": "success",
  "data": {
    "ts": "1691672864874",
    "symbol": "BTC_USDT",
    "asks": [
      [
        "31012.44",  // price
        "69994.75267"  // amount
      ]
    ],
    "bids": [
      [
        "30000.00", // price
        "1.00000"  // amount
      ]
    ]
  }
}
Field Type Description
ts String Create time(Timestamp in milliseconds)
symbol String Trading pair
asks List[] Order book on sell side
bids List[] Order book on buy side
amount String Total number of current price depth
price String The price at current depth

Get Recent Trades (V3)

Get the latest trade records of the specified trading pair. Note that the interface is not real-time data, if you need real-time data, please use websocket to subscribe Trade channel

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/quotation/v3/trades?symbol=BMX_ETH&limit=10
Field Type Required? Description
symbol String Yes Trading pair (e.g. BMX_USDT)
limit Int No Number of returned items, maximum is 50, default 50

Response Data

Response

{
  "code": 1000,
  "trace":"886fb6ae-456b-4654-b4e0-1231",
  "message": "success",
  "data": [
    [
      "BMX_ETH", // symbol
      "1691743270994", // ts
      "1.00000000", // price
      "1.0", // size
      "sell" // side
    ]
  ]
}
Field Type Description
symbol String Trading pair
ts String Trade time (in milliseconds)
price String Trade price
size String Trade number
side String Order Side
- buy
- sell

Public Market Data (History Version)

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

Request URL

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

Applicable for querying aggregated tickers of a particular trading pair

Request URL

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 (e.g. BMX_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 (V1)

Get all k-line steps supported by the platform, expressed in minutes, minimum 1 minute.

Request URL

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

Get k-line data within a specified time range of a specified trading pair

Request URL

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 (e.g. BMX_USDT)
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 (V1)

Get full depth of trading pairs.

Request URL

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 (e.g. BMX_USDT)
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 (V1)

Get the latest trade records of the specified trading pair

Request URL

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 Side
- buy
- sell

Funding Account

Get Account Balance (KEYED)

Gets Account Balance

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/account/v1/wallet?currency=USDT
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"
            }
        ]
    }
}
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

Request URL

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

Get the user's wallet balance for all currencies

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

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

Gets Deposit Address

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

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

Query withdraw quota for currencies

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

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

Creates a withdraw request from spot account to an external address

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Field Type Required? Description
currency String Yes Token symbol, e.g., 'BTC'
amount String Yes The amount of currency to withdraw

Parameters for Withdraw to the blockchain

1.Request: Withdraw to the blockchain

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
{
    "currency": "USDT-TRC20",
    "amount": "100.000",
    "destination": "To Digital Address",
    "address": "0x1EE6FA5A3803608fc22a1f3F76********",
    "address_memo": ""
}'
https://api-cloud.bitmart.com/account/v1/withdraw/apply
Field Type Required? Description
address String Yes Withdraw address (only the address added on the official website is supported)
address_memo String Yes Address tag(tag Or payment_id Or memo)
destination String No Remark

Parameters for Withdraw to BitMart account

2.Request: Withdraw to BitMart account

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
{
    "currency": "USDT-TRC20",
    "amount": "100.000",
    "type": 1,
    "value": "876940329",
    "areaCode": ""
}'
https://api-cloud.bitmart.com/account/v1/withdraw/apply
Field Type Required? Description
type Int Yes Account type
1=CID
2=Email
3=Phone
value String Yes Account
areaCode String Yes Phone area code, required when account type is phone, e.g.: 61
Important notes on request parameters

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
Note

1. When withdraw_id is returned, it means that the withdrawal request has been sent successfully.

2. You can check the tx_id of this withdrawal by using the interface of Get A Deposit Or Withdraw Detail, and use it to query the withdrawal progress on the blockchain.

3. If you get an error message, message=Only withdrawals from added addresses are allowed
You need to add the address to the whitelist address according to the following 2 steps.

Step1. On the webpage, after logging in to the account, first enter the Withdraw Crypto page

PNG

Step2. Go to Withdrawal Address Management page and add

PNG

Get Deposit And Withdraw History (KEYED)

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.

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
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=Done
- 4=Cancel
- 5=Fail
address String Address
address_memo String Address tag
tx_id String Hash record

Get A Deposit Or Withdraw Detail (KEYED)

Query a single charge record

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
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=Done
- 4=Cancel
- 5=Fail
address String address
address_memo String address tag
tx_id String Hash record

Get Margin Account Details(Isolated) (KEYED)

Applicable for isolated margin account inquiries

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}' 
https://api-cloud.bitmart.com/spot/v1/margin/isolated/account?symbol=BTC_USDT
Field Type Required? Description
symbol String No Trading pair (e.g. BMX_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 (SIGNED)

For fund transfers between a margin account and spot account

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl 
 -H 'X-BM-KEY:{{AccessKey}}' 
 -H 'X-BM-TIMESTAMP:{{currentTime}}' 
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "symbol":"BTC_USDT",
    "currency":"BTC",
    "amount":"1",
    "side":"in"
}'
https://api-cloud.bitmart.com/spot/v1/margin/isolated/transfer
Field Type Required? Description
symbol String Yes Trading pair (e.g. BMX_USDT)
currency String Yes Currency
amount String Yes Amount of transfers (precision: 8 decimal places)
side String Yes Transfer direction
- in=Transfer in
- 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 (KEYED)

For querying the base rate of the current user

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

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

For the actual fee rate of the trading pairs

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/spot/v1/trade_fee?symbol=BTC_USDT
Field Type Required? Description
symbol String Yes Trading pair (e.g. BMX_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

New Order(v2) (SIGNED)

Send in a new order.

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "symbol":"BTC_USDT",
    "side":"buy",
    "type":"limit",
    "size":"10",
    "price":"7000"
}'
https://api-cloud.bitmart.com/spot/v2/submit_order
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
-limit=Limit order
-market=Market order
-limit_maker=PostOnly order
-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

New Margin Order(v1) (SIGNED)

Applicable for margin order placement

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "symbol":"BTC_USDT",
    "side":"buy",
    "type":"limit",
    "size":"10",
    "price":"7000"
}'
https://api-cloud.bitmart.com/spot/v1/margin/submit_order
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
-limit=Limit order
-market=Market order
-limit_maker=PostOnly order
-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

New Batch Order(v2) (SIGNED)

Batch order

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "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"
        }
    ]
}'
https://api-cloud.bitmart.com/spot/v2/batch_orders
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
-limit=Limit order
-market=Market order
-limit_maker=PostOnly order
-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(v3) (SIGNED)

Applicable to the cancellation of a specified unfinished order

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "symbol": "BTC_USDT",
    "order_id": "112121212"
}'
https://api-cloud.bitmart.com/spot/v3/cancel_order
Field Type Required? Description
symbol String Yes Trading pair (e.g. BMX_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 Boolean Cancel result
-true=Cancel successfully
-false=Cancel failed

Cancel Batch Order(v1) (SIGNED)

Cancel all outstanding orders in the specified side for a trading pair

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"BTC_USDT",
  "side":"buy"
}'
https://api-cloud.bitmart.com/spot/v1/cancel_orders
Field Type Required? Description
symbol String No Trading pair (e.g. BTC_USDT)
side String No Order side
-buy
-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.

Query Order By Id (v4) (SIGNED)

Query a single order by orderId

Request URL

POST https://api-cloud.bitmart.com/spot/v4/query/order

Request Limit

Refer to Rate Limitation Details

Request Parameter

Request

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "orderId":"118100034543076010",
  "queryState":"open",
  "recvWindow":5000
}'
https://api-cloud.bitmart.com/spot/v4/query/order
Field Type Required? Description
orderId String Yes Order id
queryState String No Query Type
- open=Query order state [new, partially_filled]
- history=QUery order state [filled, canceled, partially_canceled])
recvWindow Long No Trade time limit, allowed range (0,60000], default: 5000 milliseconds
Note

Response Details

Response

{
  "code" : 1000,
  "message" : "success",
  "data" : {
    "orderId" : "118100034543076010",
    "clientOrderId" : "118100034543076010",
    "symbol" : "BTC_USDT",
    "side" : "buy",
    "orderMode" : "spot",
    "type" : "limit",
    "state" : "filled",
    "price" : "48800.00",
    "priceAvg" : "39999.00",
    "size" : "0.10000",
    "filledSize" : "0.10000",
    "notional" : "4880.00000",
    "filledNotional" : "3999.90000",
    "createTime" : 1681701557927,
    "updateTime" : 1681701559408
  },
  "trace" : "8aab576e50024648ae45e3cfaf90f9cf.60.16817015721880197"
}
Field Type Description
orderId String Order ID
clientOrderId String User-defined ID
symbol String Trading pair (e.g. BTC_USDT)
side String Order side
-buy=buy
-sell=sell
orderMode String Order mode
-spot=spot
-iso_margin=isolated margin
type String Order type
-limit=limit order
-market=market order
-limit_maker=PostOnly order
-ioc=IOC order
state String Order status
-new=The order has been accepted by the engine.
-partially_filled=a part of the order has been filled.
-filled=the order has been completed.
-canceled=the order has been canceled by the user.
-partially_canceled=partially filled canceled
price String Order price
priceAvg String Average execution price of the order
size String Order quantity
filledSize String Actual execution quantity
notional String Order amount
filledNotional String Actual execution amount
createTime Long Order creation time in milliseconds, e.g. 1681701557927
updateTime Long Last update time in milliseconds, e.g. 1681701557927

Query Order By clientOrderId(v4) (SIGNED)

Query a single order by clientOrderId.

Request URL

POST https://api-cloud.bitmart.com/spot/v4/query/client-order

Request Limit

Refer to Rate Limitation Details

Request Parameter

Request

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "clientOrderId":"118100034543076010",
  "queryState":"open",
  "recvWindow":5000
}'
https://api-cloud.bitmart.com/spot/v4/query/client-order
Field Type Required? Description
clientOrderId String Yes User-defined order id
queryState String No Query Type
- open=Query order state [new, partially_filled]
- history=Query order state [filled, canceled, partially_canceled])
recvWindow Long No Trade time limit, allowed range (0,60000], default: 5000 milliseconds
Note

Response Details

Response

{
  "code" : 1000,
  "message" : "success",
  "data" : {
    "orderId" : "118100034543076010",
    "clientOrderId" : "118100034543076010",
    "symbol" : "BTC_USDT",
    "side" : "buy",
    "orderMode" : "spot",
    "type" : "limit",
    "state" : "filled",
    "price" : "48800.00",
    "priceAvg" : "39999.00",
    "size" : "0.10000",
    "filledSize" : "0.10000",
    "notional" : "4880.00000",
    "filledNotional" : "3999.90000",
    "createTime" : 1681701557927,
    "updateTime" : 1681701559408
  },
  "trace" : "8aab576e50024648ae45e3cfaf90f9cf.60.16817015721880197"
}
Field Type Description
orderId String Order ID
clientOrderId String User-defined ID
symbol String Trading pair (e.g. BTC_USDT)
side String Order side
-buy=buy
-sell=sell
orderMode String Order mode
-spot=spot
-iso_margin=isolated margin
type String Order type
-limit=limit order
-market=market order
-limit_maker=PostOnly order
-ioc=IOC order
state String Order status
-new=The order has been accepted by the engine.
-partially_filled=a part of the order has been filled.
-filled=the order has been completed.
-canceled=the order has been canceled by the user.
-partially_canceled=partially filled canceled
price String Order price
priceAvg String Average execution price of the order
size String Order quantity
filledSize String Actual execution quantity
notional String Order amount
filledNotional String Actual execution amount
createTime Long Order creation time in milliseconds, e.g. 1681701557927
updateTime Long Last update time in milliseconds, e.g. 1681701557927

Current Open Orders(v4) (SIGNED)

Query the current opening order list of the account, only including state=[new, partially_filled] orders

Request URL

POST https://api-cloud.bitmart.com/spot/v4/query/open-orders

Request Limit

Refer to Rate Limitation Details

Request Parameter

Request

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"BTC_USDT",
  "orderMode":"spot",
  "startTime":1682239652931,
  "endTime":1682239657931,
  "limit":10,
  "recvWindow":5000
}'
https://api-cloud.bitmart.com/spot/v4/query/open-orders
Field Type Required? Description
symbol String No Trading pair (e.g. BTC_USDT)
orderMode String No Order mode
- spot=spot trade
- iso_margin=isolated margin trade
startTime Long No Start time in milliseconds, (e.g. 1681701557927)
endTime Long No End time in milliseconds, (e.g. 1681701557927)
limit Int No Number of queries, allowed range [1,200], default 200
recvWindow Long No Trade time limit, allowed range (0,60000], default: 5000 milliseconds
Note

Response Details

Response

{
  "code" : 1000,
  "message" : "success",
  "data" : [ {
    "orderId" : "125213058731346056",
    "clientOrderId" : "125213058731346056",
    "symbol" : "BTC_USDT",
    "side" : "buy",
    "orderMode" : "spot",
    "type" : "limit",
    "state" : "new",
    "price" : "800.00",
    "priceAvg" : "0.00",
    "size" : "0.10000",
    "filledSize" : "0.00000",
    "notional" : "80.00000000",
    "filledNotional" : "0.00000000",
    "createTime" : 1681892198608,
    "updateTime" : 1681892198946
  } ],
  "trace" : "5e1c9f98d761443ea559c7af71ca57fa.60.16818922069220005"
}
Field Type Description
orderId String Order ID
clientOrderId String User-defined ID
symbol String Trading pair (e.g. BTC_USDT)
side String Order side
-buy=buy
-sell=sell
orderMode String Order mode
-spot=spot
-iso_margin=isolated margin
type String Order type
-limit=limit order
-market=market order
-limit_maker=PostOnly order
-ioc=IOC order
state String Order status
-new=The order has been accepted by the engine.
-partially_filled=a part of the order has been filled.
price String Order price
priceAvg String Average execution price of the order
size String Order quantity
filledSize String Actual execution quantity
notional String Order amount
filledNotional String Actual execution amount
createTime Long Order creation time in milliseconds, e.g. 1681701557927
updateTime Long Last update time in milliseconds, e.g. 1681701557927

Account Orders(v4) (SIGNED)

Query the account history order list, only including state=[filled, canceled, partially_canceled] orders

Request URL

POST https://api-cloud.bitmart.com/spot/v4/query/history-orders

Request Limit

Refer to Rate Limitation Details

Request Parameter

Request

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"BTC_USDT",
  "orderMode":"spot",
  "startTime":1682239502394,
  "endTime":1682239507394,
  "limit":10,
  "recvWindow":5000
}'
https://api-cloud.bitmart.com/spot/v4/query/history-orders
Field Type Required? Description
symbol String No Trading pair (e.g. BTC_USDT)
orderMode String No Order mode
- spot=spot trade
- iso_margin=isolated margin trade
startTime Long No Start time in milliseconds, (e.g. 1681701557927)
endTime Long No End time in milliseconds, (e.g. 1681701557927)
limit Int No Number of queries, allowed range [1,200], default 200
recvWindow Long No Trade time limit, allowed range (0,60000], default: 5000 milliseconds
Note

Response Details

Response

{
  "code" : 1000,
  "message" : "success",
  "data" : [ {
    "orderId" : "118100034543076010",
    "clientOrderId" : "118100034543076010",
    "symbol" : "BTC_USDT",
    "side" : "buy",
    "orderMode" : "spot",
    "type" : "limit",
    "state" : "filled",
    "price" : "48800.00",
    "priceAvg" : "39999.00",
    "size" : "0.10000",
    "filledSize" : "0.10000",
    "notional" : "4880.00000000",
    "filledNotional" : "3999.90000000",
    "createTime" : 1681701557927,
    "updateTime" : 1681701559408
  } ],
  "trace" : "acc282ba9e434cc1a90bf6326de9e119.64.16818913787390001"
}
Field Type Description
orderId String Order ID
clientOrderId String User-defined ID
symbol String Trading pair (e.g. BTC_USDT)
side String Order side
-buy=buy
-sell=sell
orderMode String Order mode
-spot=spot
-iso_margin=isolated margin
type String Order type
-limit=limit order
-market=market order
-limit_maker=PostOnly order
-ioc=IOC order
state String Order status
-filled=the order has been completed.
-canceled=the order has been canceled by the user.
-partially_canceled=partially filled canceled
price String Order price
priceAvg String Average execution price of the order
size String Order quantity
filledSize String Actual execution quantity
notional String Order amount
filledNotional String Actual execution amount
createTime Long Order creation time in milliseconds, e.g. 1681701557927
updateTime Long Last update time in milliseconds, e.g. 1681701557927

Account Trade List(v4) (SIGNED)

Query all transaction records of the account

Request URL

POST https://api-cloud.bitmart.com/spot/v4/query/trades

Request Limit

Refer to Rate Limitation Details

Request Parameter

Request

 curl 
  -H 'X-BM-KEY:{{AccessKey}}'
  -H 'X-BM-TIMESTAMP:{{currentTime}}'
  -H 'X-BM-SIGN:{{SIGN}}' 
  -X POST -d '{
  "symbol":"BTC_USDT",
  "orderMode":"spot",
  "startTime":1682239845952,
  "endTime":1682239850952,
  "limit":10,
  "recvWindow":5000
}'
https://api-cloud.bitmart.com/spot/v4/query/trades
Field Type Required? Description
symbol String No Trading pair (e.g. BTC_USDT)
orderMode String No Order mode
- spot=spot trade
- iso_margin=isolated margin trade
startTime Long No Start time in milliseconds, (e.g. 1681701557927)
endTime Long No End time in milliseconds, (e.g. 1681701557927)
limit Int No Number of queries, allowed range [1,200], default 200
recvWindow Long No Trade time limit, allowed range (0,60000], default: 5000 milliseconds
Note

Response Details

Response

{
  "code" : 1000,
  "message" : "success",
  "data" : [ {
    "tradeId" : "125277182593091639",
    "orderId" : "125213058731346053",
    "clientOrderId" : "125213058731346053",
    "symbol" : "BTC_USDT",
    "side" : "buy",
    "orderMode" : "spot",
    "type" : "limit",
    "price" : "39999.00",
    "size" : "0.10000",
    "notional" : "3999.90000000",
    "fee" : "9.99975000",
    "feeCoinName" : "USDT",
    "tradeRole" : "taker",
    "createTime" : 1681891896569,
    "updateTime" : 1681891896569
  } ],
  "trace" : "5e1c9f98d761443ea559c7af71ca57fa.61.16819603026240455"
}
Field Type Description
tradeId String Trade id
orderId String Order ID
clientOrderId String User-defined ID
symbol String Trading pair (e.g. BTC_USDT)
side String Order side
-buy=buy
-sell=sell
orderMode String Order mode
-spot=spot
-iso_margin=isolated margin
type String Order type
-limit=limit order
-market=market order
-limit_maker=PostOnly order
-ioc=IOC order
price String Transaction price
size String Transaction quantity
notional String Transaction amount
fee String Fee amount
feeCoinName String Fee coin name
tradeRole String Trade role
-taker=Take orders, take the initiative to deal
-maker=Pending order, passive transaction
createTime Long Order creation time in milliseconds, e.g. 1681701557927
updateTime Long Last update time in milliseconds, e.g. 1681701557927

Order Trade List(v4) (SIGNED)

Query all transaction records of a single order

Request URL

POST https://api-cloud.bitmart.com/spot/v4/query/order-trades

Request Limit

Refer to Rate Limitation Details

Request Parameter

Request

 curl 
  -H 'X-BM-KEY:{{AccessKey}}'
  -H 'X-BM-TIMESTAMP:{{currentTime}}'
  -H 'X-BM-SIGN:{{SIGN}}' 
  -X POST -d '{
  "orderId":"118100034543076010",
  "recvWindow":5000
}'
https://api-cloud.bitmart.com/spot/v4/query/order-trades
Field Type Required? Description
orderId String Yes Order id
recvWindow Long No Trade time limit, allowed range (0,60000], default: 5000 milliseconds
Note

Response Details

Response

{
  "code" : 1000,
  "message" : "success",
  "data" : [ {
    "tradeId" : "122177405911172002",
    "orderId" : "118100034543076010",
    "clientOrderId" : "118100034543076010",
    "symbol" : "BTC_USDT",
    "side" : "buy",
    "orderMode" : "spot",
    "type" : "limit",
    "price" : "39999.00",
    "size" : "0.10000",
    "notional" : "3999.90000000",
    "fee" : "9.99975000",
    "feeCoinName" : "USDT",
    "tradeRole" : "taker",
    "createTime" : 1681701559210,
    "updateTime" : 1681701559210
  } ],
  "trace" : "5e1c9f98d761443ea559c7af71ca57fa.62.16818934219090007"
}
Field Type Description
tradeId String Trade id
orderId String Order ID
clientOrderId String User-defined ID
symbol String Trading pair (e.g. BTC_USDT)
side String Order side
-buy=buy
-sell=sell
orderMode String Order mode
-spot=spot
-iso_margin=isolated margin
type String Order type
-limit=limit order
-market=market order
-limit_maker=PostOnly order
-ioc=IOC order
price String Transaction price
size String Transaction quantity
notional String Transaction amount
fee String Fee amount
feeCoinName String Fee coin name
tradeRole String Trade role
-taker=Take orders, take the initiative to deal
-maker=Pending order, passive transaction
createTime Long Order creation time in milliseconds, e.g. 1681701557927
updateTime Long Last update time in milliseconds, e.g. 1681701557927

Spot / Margin Trading (History Version)

New Order(v1) (SIGNED)

Send in a new order.

new endpoint /spot/v2/submit_order

Request Format

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "symbol":"BTC_USDT",
    "side":"buy",
    "type":"limit",
    "size":"10",
    "price":"7000"
}'
https://api-cloud.bitmart.com/spot/v1/submit_order
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

New Batch Order(v1) (SIGNED)

Batch order

new endpoint /spot/v2/batch_orders

Request Format

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "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"
        }
    ]
}'
https://api-cloud.bitmart.com/spot/v1/batch_orders
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

Cancel Order(v2) (SIGNED)

Cancel an outstanding order

new endpoint /spot/v3/cancel_order

Request Format

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "order_id":112121212
}'
https://api-cloud.bitmart.com/spot/v2/cancel_order
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 Boolean Cancel successfully=true; Cancel failed=false

Query Order(v2) (KEYED)

Applicable query a specified order detail

new endpoint /spot/v4/query/order

Request Format

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

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

Account Orders(v3) (KEYED)

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

new endpoint /spot/v4/query/open-orders new endpoint /spot/v4/query/history-orders

Request Format

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

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

Account Trade List(v2) (KEYED)

Applicable for searching the trade history within a certain time frame, up to 200 records

new endpoint /spot/v4/query/trades

Request Format

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

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

Applicable to isolated margin account borrowing operations

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "symbol":"BTC_USDT",
    "currency":"BTC",
    "amount":"1"
}'
https://api-cloud.bitmart.com/spot/v1/margin/isolated/borrow
Field Type Required? Description
symbol String Yes Trading pair (e.g. BMX_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) (SIGNED)

Applicable to isolated margin account repayment operations

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "symbol":"BTC_USDT",
    "currency":"BTC",
    "amount":"1"
}'
https://api-cloud.bitmart.com/spot/v1/margin/isolated/repay
Field Type Required? Description
symbol String Yes Trading pair (e.g. BMX_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) (KEYED)

Applicable to the inquiry of borrowing records of an isolated margin account

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}' 
https://api-cloud.bitmart.com/spot/v1/margin/isolated/borrow_record?symbol=BTC_USDT
Field Type Required? Description
symbol String Yes Trading pair (e.g. BMX_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, allowed range[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) (KEYED)

Applicable to the inquiry of repayment records of isolated margin account

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/spot/v1/margin/isolated/repay_record?symbol=BTC_USDT
Field Type Required? Description
symbol String Yes Trading pair (e.g. BMX_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, allowed range[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 (KEYED)

Applicable for checking the borrowing rate and borrowing amount of trading pairs

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/spot/v1/margin/isolated/pairs?symbol=BTC_USDT
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)

Sub-Account

Sub-Account to Main-Account (For Main Account) (SIGNED)

Sub-account spot asset transfer to Main-account (For Main Account)

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "requestNo":"4e2adcff-2122-1ce7-2557-4f65d2ce1ca2",
    "amount":"1",
    "currency":"BTC",
    "subAccount":"[email protected]"
}'
https://api-cloud.bitmart.com/account/sub-account/main/v1/sub-to-main
Field Type Required? Description
requestNo String Yes UUID,unique identifier, max length 64
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 Main-Account (For Sub-Account) (SIGNED)

Sub-Account spot asset transfer to Main-Account spot asset (For Sub-Account)

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "requestNo":"4e2adcff-2122-1ce7-2557-4f65d2ce1ca2",
    "amount":"1",
    "currency":"BTC"
}'
https://api-cloud.bitmart.com/account/sub-account/sub/v1/sub-to-main
Field Type Required? Description
requestNo String Yes UUID,unique identifier, max length 64
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 to Sub-Account (For Main Account) (SIGNED)

Main-account spot asset transfer to Sub-account spot asset (For Main Account)

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "requestNo":"4e2adcff-2122-1ce7-2557-4f65d2ce1ca2",
    "amount":"1",
    "currency":"BTC",
    "subAccount":"[email protected]"
}'
https://api-cloud.bitmart.com/account/sub-account/main/v1/main-to-sub
Field Type Required? Description
requestNo String Yes UUID,unique identifier, max length 64
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 (For Main Account) (SIGNED)

Sub-Account spot asset transfer to Sub-Account spot asset (For Main Account)

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "requestNo":"4e2adcff-2122-1ce7-2557-4f65d2ce1ca2",
    "amount":"1",
    "currency":"BTC",
    "fromAccount":"[email protected]",
    "toAccount":"[email protected]"
}'
https://api-cloud.bitmart.com/account/sub-account/main/v1/sub-to-sub
Field Type Required? Description
requestNo String Yes UUID,unique identifier, max length 64
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.

Sub-Account to Sub-Account (For Sub-Account) (SIGNED)

Sub-Account spot asset transfer to Sub-Account spot asset (For Sub-Account)

Request URL

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
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "requestNo":"4e2adcff-2122-1ce7-2557-4f65d2ce1ca2",
    "amount":"1",
    "currency":"BTC",
    "subAccount":"[email protected]"
}'
https://api-cloud.bitmart.com/account/sub-account/sub/v1/sub-to-sub
Field Type Required? Description
requestNo String Yes UUID,unique identifier, max length 64
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.

Get Sub-Account Transfer History (For Main Account) (KEYED)

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

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
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 (default: all sub-accounts will be queried)
N Int Yes Recent N records, allowed 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 (For Main/Sub Account) (KEYED)

Get account spot asset transfer history (For Main/Sub Account)

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

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

Get Sub-Account spot wallet balance (For Main Account)

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

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

Get Sub-Account list (For Main Account)

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
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
-0=disabled in background
-1=normal
-2=frozen by main account

WebSocket Subscription

Overview

Server URL

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

The message format sent by the client to the BitMart server.

{"op":"<operation>", "args":["<topic1>","<topic2>"]}

Explain:

Example:


Successful Response Format

The format of the success message returned by the BitMart server to the client.

The returned field not contains errorCode

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

Example:


Failed Response Format

The format of the failed message returned by the BitMart server to the client.

If the returned field contains errorCode, it means failure. For the reason of failure, please refer to: WebSocket Error Code

Failed Response Format

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

Stay Connected And Limit

How 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: (Example in Java pseudocode)

ws.send(new PingWebSocketFrame();

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

Connection Limit

How to subscribe to more than 1000 channels?

Best example of subscribing to 1000 channels or less: Use one IP to establish 10 server connections with BitMart, and each connection initiates 100 channel subscriptions

Best example of subscribing to 1000+ channels: Multiple IPs can be used, and each IP can establish 10 connections, and each connection initiates 100 channel subscriptions

Need to pay attention to?

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

For more and more complete programming codes, please refer to the Quick Start API

Python

import zlib

def inflate(data):
    decompress = zlib.decompressobj(
            -zlib.MAX_WBITS
    )
    inflated = decompress.decompress(data)
    inflated += decompress.flush()
    return inflated.decode('UTF-8')

Nodejs

const zlib = require('zlib');

zlib.inflateRawSync(data);

Golang

import (
    "compress/flate"
)

func zipDecode(in []byte) ([]byte, error) {
    reader := flate.NewReader(bytes.NewReader(in))
    defer reader.Close()

    return ioutil.ReadAll(reader)
}

string(zipDecode(data))

php

@link https://php.net/manual/en/function.gzinflate.php

gzinflate($data)

Java

import java.util.zip.*;

public class StringCompressUtil {

    private static String uncompress(ByteBuf buf) {
        try {
            byte[] temp = new byte[buf.readableBytes()];
            ByteBufInputStream bis = new ByteBufInputStream(buf);
            bis.read(temp);
            bis.close();
            Inflater decompresser = new Inflater(true);
            decompresser.setInput(temp, 0, temp.length);
            StringBuilder sb = new StringBuilder();
            byte[] result = new byte[1024];
            while (!decompresser.finished()) {
                int resultLength = decompresser.inflate(result);
                sb.append(new String(result, 0, resultLength, "UTF-8"));
            }
            decompresser.end();
            return sb.toString();
        }catch (Exception e) {
            e.printStackTrace();
        }
        return "";
    }

    public static String decode(ByteBuf content){
        byte[] bytes = new byte[content.readableBytes()];
        content.readBytes(bytes);
        ByteBuf byteBuf = Unpooled.wrappedBuffer(bytes);
        String str = uncompress(byteBuf);
        return str;
    }

}

StringCompressUtil.decode(data)

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

Subscribe Request

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

Subscription successful

{"event": "subscribe","topic": "spot/ticker:BTC_USDT"}

After successful subscription, push data

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

Unsubscribe

Cancel subscription to one or more channels

unsubscribe

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

Parameter Instruction

Example

Unsubscribe Request

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

Unsubscribe successful

{"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
  3. Push frequency: The fastest is 500ms once

Subscribe Request

Subscribe Request

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

Message Format:

{"op": "subscribe", "args": ["spot/ticker:<symbol>"]}

Subscription successful

Subscription successful

{
  "event":  "subscribe",
  "topic":  "spot/ticker:BTC_USDT"
}

{"event":"subscribe","topic":"spot/ticker:<symbol>"}

After successful subscription, push data

Push data

{
  "data":  [
    {
      "ask_px":  "36000",
      "ask_sz":  "1.021",
      "base_volume_24h":  "2.02000",
      "bid_px":  "35000",
      "bid_sz":  "11",
      "fluctuation":  "-0.0001",
      "high_24h":  "35003.04",
      "last_price":  "35000.00",
      "low_24h":  "35000.00",
      "ms_t":  1709024652967,
      "open_24h":  "35003.03",
      "quote_volume_24h":  "70700.00",
      "s_t":  1709024652,
      "symbol":  "BTC_USDT"
    }
  ],
  "table":  "spot/ticker"
}

Return data description:

Field 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 traded volume in base currency
quote_volume_24h String 24-hour traded volume in quote currency
s_t Long Create Time (timestamp in seconds) (The field will be removed, please use the ms_t field)
ms_t Long Create Time (timestamp in millisecond)
fluctuation String 24-hour Price change
bid_px String Best bid price
bid_sz String Best bid quantity
ask_px String Best ask price
ask_sz String Best bid quantity

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

【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
  3. Push frequency: The fastest is 500ms once

Subscribe Request

Subscribe Request

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

Message Format:

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

Parameters Channel Name List

Channel Name Description
spot/kline1m 1-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

Subscription successful

Subscription successful

{
  "topic":  "spot/kline1m:BTC_USDT",
  "event":  "subscribe"
}

{"event":"subscribe","topic":"<channel>:<symbol>"}

After successful subscription, push data

Push data

{
  "data":  [
    {
      "candle":  [
        1709025360,
        "162.01",
        "162.02",
        "162.03",
        "162.04",
        "336.452694"
      ],
      "symbol":  "BTC_USDT"
    }
  ],
  "table":  "spot/kline1m"
}

Return data description:

Field Type Description
symbol String Trading pair, BTC_USDT
candle List KLine data

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

【Public】Depth-All Channel

Return depth data, each push is the full 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
  3. Push frequency: The fastest is 500ms once

Subscribe Request

Subscribe Request

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

Message Format:

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

Parameters Channel Name List

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

Subscription successful

Subscription successful

{
  "topic":  "spot/depth5:BTC_USDT",
  "event":  "subscribe"
}

{"event":"subscribe","topic":"<channel>:<symbol>"}

After successful subscription, push data

Push data

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

Return data description:

Field Type Description
symbol String Trading pair, BTC_USDT
asks List Ask depth
bids List Bid depth
ms_t Long Timestamp (in millisecond)

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

【Public】Depth-Increase Channel

Return depth data, support the creation of a local full depth cache 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
  3. Push frequency: The fastest is 100ms once

Subscribe Request

Subscribe Request

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

Full depth snapshot data Request

{ 
  "op": "request", 
  "args": ["spot/depth/increase100:BTC_USDT"]
}

Message Format:

{"op": "<op>", "args": ["spot/depth/increase100:<symbol>"]}

Subscription successful

Subscription successful

{
  "topic":  "spot/depth/increase100:BTC_USDT",
  "event":  "subscribe"
}

{"event":"subscribe","topic":"spot/depth/increase100:<symbol>"}

Response

Full depth snapshot data

{
  "data": [{
    "asks": [
      ["23200", "0.69959"],
      ["28000.00", "0.20000"]
    ],
    "bids": [
      ["23105", "1.80114"]
    ],
    "ms_t": 1698292343610,
    "symbol": "BTC_USDT",
    "type": "snapshot",
    "version": 4
  }],
  "table": "spot/depth/increase100"
}

Incremental depth data

{
    "data": [{
        "asks": [
            ["23200", "0.59959"]
        ],
        "bids": [],
        "ms_t": 1698292358292,
        "symbol": "BTC_USDT",
        "type": "update",
        "version": 5
    }],
    "table": "spot/depth/increase100"
}

Return data description:

Field Type Description
symbol String Trading pair, BTC_USDT
asks List Ask depth
bids List Bid depth
ms_t Long Timestamp (in millisecond)
version String data version
type String data type
-snapshot=Full depth snapshot data
-update=Incremental depth data

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

How to correctly maintain a copy of OrderBook locally:

  1. First, the client send a subscription request {"op": "subscribe", "args": ["spot/depth/increase100:<symbol>"] }
  2. After successful subscription, you will receive two types of messages, type=snapshot (full data) and type=update (update)
  3. If a type=snapshot type message is received, update the deep snapshot content to the local cache. If there is no local cache, create one.
  4. If a type=update message is received, update the data in the deep snapshot to local cache. The update rules are as follows:
    • 4.1 If the field version number in the received new message is less than or equal to the version in the local cache(new version<=local version), this data can be discarded.
    • 4.2 If the field version number in the new message received is equal to the version in the local cache plus 1(new version==local version+1), the quantity of the corresponding price will be updated to the local cache.
    • 4.3 If the field version number in the new message received is greater than the version in the local cache plus 1(new version>local version+1), please obtain the latest depth snapshot from step 7 and overwrite the local cache.
  5. The pending order volume in each returned message represents the absolute value of the current pending order volume at this price, rather than the relative change.
  6. How to update local cache? Under the premise of 4.2:
    • 6.1 New: If the same price is not already in the local cache, it means that it is a new pending order and needs to be added to the cache.
    • 6.2 Modify or Remove: If the same price is already in the local cache, it means that the quantity has changed. If the quantity is 0, it will be directly removed from the cache. Otherwise, just change the quantity.
  7. Request through request {"op": "request", "args": ["spot/depth/increase100:<symbol>"] }to obtain the latest depth snapshot (type=snapshot in the message), and add the depth The content in the snapshot is overwritten to the local cache, and then the logic continues from step 2.

Flow Chart

PNG

【Public】Trade Channel

Get the latest real-time transaction data

Pushing Rules

  1. No user login required
  2. After successful subscription, incremental trade messages will be pushed(Taker trade message)
  3. Push frequency: Push when changes

Subscribe Request

Subscribe Request

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

Message Format:

{"op": "subscribe", "args": ["spot/trade:<symbol>"]}

Subscription successful

Subscription successful

{
  "event":  "subscribe",
  "topic":  "spot/trade:BTC_USDT"
}

{"event":"subscribe","topic":"spot/trade:<symbol>"}

After successful subscription, push data

Push data

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

Return data description:

Field Type Description
symbol String Trading pair, BTC_USDT
side String Side of trade for taker order(buy or sell
price String Trade price for taker order
size String Trade quantity for taker order
s_t Long Order execution time (Timestamp in seconds) (The field will be removed, please use the ms_t field)
ms_t Long Order execution time (Timestamp in millisecond)

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

【Private】Login

Login Subscription Format

Request Format

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

Example

Login Example

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

Response

{"event":"login"}

Assume that the values of the API requested by the user is as follows:

Ues Javascript create param sign: sign = CryptoJS.HmacSHA256(1589267764859 + "#" + test001 + "#" + "bitmart.WebSocket", '6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9') = 3ceeb7e1b8cb165a975e28a2e2dfaca4d30b358873c0351c1a071d8c83314556

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

The final login parameters are:

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

Note

【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)
  3. Push frequency: Push when changes

Subscribe Request

Subscribe Request

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

Message Format:

{"op": "subscribe", "args": ["spot/user/order:<symbol>"]}

Subscription successful

Subscription successful

{
  "event":  "subscribe",
  "topic":  "spot/user/order:BTC_USDT"
}

{"event":"subscribe","topic":"spot/user/order:<symbol>"}

After successful subscription, push data

Push data

{
    "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",
            "create_time":"1609926028000",
            "update_time":"1609926044000",
            "order_mode":"0",
            "entrust_type":"normal",
            "order_state":"partially_filled"
        }
    ],
    "table":"spot/user/order"
}

Return data description:

Field 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 Side
-buy
-sell
type string Type
-limit
-market
ms_t string Order Create Timestamp (in milliseconds)
filled_size string Filled size (Base currency)
filled_notional string Filled notional amount (Quote currency)
margin_trading string 0:Spot order (The field will be removed, please use the order_mode field)
order_type string Order type (The field will be removed, please use the entrust_type field)
-0=Regular
-1=Maker only(Post only)
-2=Fill or kill(FOK)
-3=Immediate or Cancel(IOC)
state string Order state (The field will be removed, please use the order_state field)
-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=Maker
-T=Taker
detail_id string Trade id
client_order_id string Client-defined OrderId
create_time String Order Create Time (in milliseconds)
update_time String Order Update Time (in milliseconds)
order_mode String Order mode
-spot=spot
-iso_margin=margin
entrust_type String Order Type
-normal=Normal trade order(Limit Order or Market Order)
-limit_maker=PostOnly Order
-ioc=IOC Order
order_state String Order State
-new=The order has been accepted by the engine.
-partially_filled=A part of the order has been filled.
-filled=The order has been completed.
-canceled=The order has been canceled by the user.
-partially_canceled=A part of the order has been filled , and the order has been canceled.

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

【Private】Balance Change

Balance change push

Pushing Rules

  1. User login required
  2. Qualified balance changes (recharge, withdrawal, transfer, transaction)
  3. Push frequency: Push when changes

Subscribe Request

Subscribe Request

{
  "op": "subscribe",
  "args": ["spot/user/balance:BALANCE_UPDATE"]
}

Message Format:

{"op": "subscribe", "args": ["spot/user/balance:BALANCE_UPDATE"]}

Subscription successful

Subscription successful

{
  "event":  "subscribe",
  "topic":  "spot/user/balance:BALANCE_UPDATE"
}

{"event": "subscribe","topic": "spot/user/balance:BALANCE_UPDATE"}

After successful subscription, push data

Push data

{
  "data":[
    {
      "event_type":"TRANSACTION_COMPLETED  ",
      "event_time":"1693364237000",
      "balance_details":[{
        "ccy": "BTC",
        "av_bal": "123.22",
        "fz_bal": "12.56"
      }]
    }
  ],
  "table":"spot/user/balance"
}

Return data description:

Field Type Description
event_type string Reason for change. Type
-TRANSACTION_COMPLETED=Trade
-ACCOUNT_RECHARGE=Recharge
-ACCOUNT_WITHDRAWAL=Withdraw
-ACCOUNT_TRANSFER=Transfer
event_time string Create time
balance_details string Detail
>ccy string Changing Balance Currency
>av_bal string Available balance after change
>fz_bal string Freeze balance after change

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

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 must be long type 30006 401
Header X-BM-TIMESTAMP range. Within a minute 30007 401
Header X-BM-TIMESTAMP range. Timestamp for this request is outside of the recvWindow. 30007 401
Param recvWindow must be long type 30007 401
Param recvWindow must be less than 60000 and greater than 0 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
Service maintenance, the function is temporarily unavailable 30016 200
Your account request is temporarily rejected due to violation of current limiting rules, please contact customer service 30017 418
Request Body requires JSON format 30018 503
You do not have the permissions to perform this operation. Please contact customer service or BD for assistance 30019 200

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
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 status is unavailable 60028 403
The account is frozen by the master account, please contact the master account to unfreeze the account 60029 403
Method Not Allowed 60030 405
Unsupported Media Type 60031 415
User account not found 60050 500
Internal Server Error 60051 500
Exception 60052 400
please check The Email/PhoneNumber/BitMart ID And try again 60053 403
Sub-account does not support withdraw 60054 403
This currency is not support 60055 403
This currency withdrawal is suspended 60056 403
User status is not available 60057 403
Monitor that the withdrawal will cause the overall spot wallet to fall below the Margin call risk rate. Please revise the withdrawal amount as appropriate 60058 403
internal Withdraw forbidden 60059 403
Invalid request 60060 403
Unsupported operation 60061 403
Forbidden 60062 403
Account is frozen due to security policies. Please contact customer service 60063 403
Exceed daily withdrawal quota, for your safety, please wait 24 hours and try again 60064 403
The withdrawal user and the target user cannot be the same 60065 403
The specified sub-account could not be found 61003 400
Duplicate requests (such as using an existing requestNo) 61004 400
Asset transfer between accounts is not available 61005 403
The sub-account api only supports organization accounts 61006 403
Please complete your institution verification to enable withdrawal function. 61007 403
Suspend transfer out 61008 403

Spot Public Mark API Error Code

error message code error code http status code
OK 1000 200
no data 70000 200
request param can not be null 70001 200
symbol is invalid 70002 200
after is invalid 71001 200
before is invalid 71002 200
request after or before is invalid 71003 200
request kline count limit 71004 200
request step error 71005 200

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
Unsupported OrderMode Type 52000 400
Unsupported Trade Type 52001 400
Unsupported Side Type 52002 400
Unsupported Query State Type 52003 400
End time must be greater than or equal to Start time 52004 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
This account is restricted from borrowing 53010 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
Topic quantity in single subscription exceeds limit 90005
Subscribed total topic quantity exceeds limit 90006
Subscribed message frequency exceeds limit, please try later 90007
Duplicate subscription 90008
Invalid subscription 90009
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