Change Log

2023-05-09

• New spot query order endpoints
  • /spot/v4/query/order Query order by id (v4)
  • /spot/v4/query/client-order Query order by client order id (v4)
  • /spot/v4/query/open-orders Current open orders (v4)
  • /spot/v4/query/history-orders Account orders (v4)
  • /spot/v4/query/trades Account trade list (v4)
  • /spot/v4/query/order-trades Order trade list(v4)

2023-03-03

• Update endpoints for Account
  • /spot/v1/user_feeAdd new field taker_fee_rate_C and maker_fee_rate_C

2022-12-22

• Update endpoints for Spot
  • WebSocket Subscription-【Private】Order Progress add new order status 12 = Partially filled and canceled

2022-11-03

• Update endpoints for Spot / Margin trading
  • /spot/v3/orders /spot/v2/tradesadd start_time and end_time field for flexible querying
  • add new order status 11 = Partially filled and canceled

2022-11-01

• Update endpoints for Account
  • /account/v1/currenciesAdd new field contract_address,withdraw_minsize and withdraw_minfee

2022-10-11

• The new version of market data-relateded endpoints
  • /spot/v2/ticker
  • /spot/v1/ticker_detail

2022-09-29

• New spot trading endpoints
  • /spot/v2/submit_order
  • /spot/v2/batch_orders
  • /spot/v3/cancel_order
  • /spot/v2/order_detail
  • /spot/v3/orders
  • /spot/v2/trades

2022-08-16

• New Endpoint for Trade Fee
  • /spot/v1/trade_fee
• New Endpoint for Basic Fee
  • /spot/v1/user_fee

2022-07-07

• New endpoints for the margin loan
  • /spot/v1/margin/isolated/borrow
  • /spot/v1/margin/isolated/repay
  • /spot/v1/margin/isolated/borrow_record
  • /spot/v1/margin/isolated/repay_record
  • /spot/v1/margin/isolated/pairs
• New endpoint for margin trading
  • /spot/v1/margin/submit_order
• New endpoints for margin accounts
  • /spot/v1/margin/isolated/account
  • /spot/v1/margin/isolated/transfer
• Update endpoints for Spot / Margin trading
  • A new "order_mode" field has been added to the following endpoints to distinguish whether the order originates from a spot or margin trade
  • /spot/v1/order_detail
  • /spot/v2/orders
  • /spot/v1/trades

2022-05-24

• Update endpoints for Spot
  • /spot/v2/ordersAdd new field clientOrderId
  • /spot/v1/tradesAdd new field clientOrderId
  • /spot/v1/order_detailAdd new field clientOrderId

2022-04-19

• New sub-account endpoints
  • /sub-account/main/v1/sub-to-main
  • /sub-account/sub/v1/sub-to-main
  • /sub-account/main/v1/main-to-sub
  • /sub-account/sub/v1/sub-to-sub
  • /sub-account/main/v1/sub-to-sub
  • /sub-account/main/v1/transfer-list
  • /sub-account/v1/transfer-history
  • /sub-account/main/v1/wallet
  • /sub-account/main/v1/subaccount-list
• Update WebSocket Order Progress channel
  • Add new field client_order_id
  • Add new field detail_id

2022-03-29

• WebSocket subscription, 【private】 order channel renamed to 【private】 order progress
• New parameter exec_type is added to 【Private】 order progress channel, which indicates liquidity type

2022-03-08

• Improvement of Websocket connection holding
• Catalog level repair to enhance readability

2022-03-01

• support user to create , request and cancel order through client-defined OrderId

2022-02-15

• increase the maximum rate limit based on users' feedback
• improve UI of the document

2022-01-20

• Update endpoints for Spot
  • /spot/v1/symbols/detailsAdd a new respond parameter trade_status, to show the trading status of a trading pair symbol.

2022-01-18

• websocket public channel addresswss://ws-manager-compress.bitmart.com?protocol=1.1will be taken down on 2022-02-28 UTC time,The new address iswss://ws-manager-compress.bitmart.com/api?protocol=1.1

2021-11-24

• New endpoints for Spot
  • /spot/v2/ordersGet User Order History V2
  • /spot/v1/batch_ordersBatch Order
• Update endpoints for Spot
  • /spot/v1/symbols/klineAdd new field 'quote_volume'
  • /spot/v1/symbols/tradesAdd optional parameter N to return the number of items, the default is up to 50 items
  • /spot/v1/order_detailAdd new field 'unfilled_volume'
  • /spot/v1/submit_orderThe request parameter type added limit_maker and ioc order types
• New endpoints for Account
  • /account/v2/deposit-withdraw/historyGet Deposit And Withdraw History V2
• Update endpoints for Account
  • /account/v1/walletRemove the account_type,Only respond to currency accounts; you can bring currency parameters (optional)

2021-11-06

• Update endpoints for Spot WebSocket
  • Public-Depth Channel:
  • spot/depth50 50 Level Depth Channel
  • spot/depth100 100 Level Depth Channel
  • User-Trade Channel:
  • Eligible pushes add new orders successfully

2021-01-19

• New endpoints for Spot WebSocket
  • Public - ticket channels
  • Public - K channel
  • Public - trading channels
  • Public - depth channels
  • Login
  • User - Trading Channel

2020-07-15

• New endpoints for Spot
  • /spot/v2/cancel_orderCancel an outstanding order，V2

2020-06-29

• New endpoints for Account
  • /account/v1/currenciesGet Currency
    
  • /account/v1/walletGet Account Balance
    
  • /account/v1/deposit/addressDeposit Address
    
  • /account/v1/withdraw/chargeWithdraw Quota
    
  • /account/v1/withdraw/applyWithdraw
    
  • /account/v1/recharge-withdraw/historyGet Deposit And Withdraw History
  • /account/v1/recharge-withdraw/detailGet A Deposit Or Withdraw Detail

2020-05-14

• New endpoints for Spot
  • /spot/v1/currenciesGet a list of all cryptocurrencies on the platform
  • /spot/v1/symbolsGet a list of all trading pairs on the platform
  • /spot/v1/symbols/detailsGet a detailed list of all trading pairs on the platform
  • /spot/v1/tickerGet ticker
  • /spot/v1/stepsGet K-Line steps
  • /spot/v1/symbols/klineGet k-Line
  • /spot/v1/symbols/bookGet orderbook
  • /spot/v1/symbols/tradesGet trades
  • /spot/v1/walletGet user wallet
  • /spot/v1/submit_orderPlace order
  • /spot/v1/cancel_orderCancel order
  • /spot/v1/cancel_ordersCancel all outstanding orders in the specified direction for the specified trading pair
  • /spot/v1/order_detailGet order details
  • /spot/v1/ordersGet user recent orders
  • /spot/v1/tradesGet user trade history

Introduction

API Key Create

• Many APIs require an API Access Key for access. Please refer to this page to set up.
• When setting up an API Access Key, it is recommended to set up an IP access whitelist for security purposes.
• Never give your API Access key/secret key to anyone.

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

• Access Key: represents the identity of the account, this is your api key
• Secret Key: used for API signature
• Memo: used for API signature

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

• The default permission of a newly created API is Read-Only.
• To withdraw funds through the API, you need to modify the permissions in the UI and select Withdraw.
• Permission descriptions:
  • Read-only (query spot trading orders, query contract trading orders, query funds)
  • Spot-Trade (place orders, cancel orders)
  • Withdraw (withdraw funds)
  • Margin-Trade (repayment, borrowing, placing orders, etc.)
  • Contract-Trade (long position, short position, closing position, etc.)

Read-Only Permissions:

Withdraw Permissions:

Spot-Trade Permissions:

Margin-Trade Permissions:

Contract-Trade Permissions:

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.

1. BitMart Golang SDK

The Websocket code quickly implements a lightweight code library, including HTTP requests for all BitMart API interfaces and subscriptions to websocket public and private channels, and can be used after being cloned. This is written specifically for Golang developers.

https://github.com/bitmartexchange/bitmart-go-sdk-api

2. BitMart Python SDK

The Websocket code quickly implements a lightweight code library, including HTTP requests for all BitMart API interfaces and subscriptions to websocket public and private channels, and can be used after being cloned. This is written specifically for Python developers.

https://github.com/bitmartexchange/bitmart-python-sdk-api

3. BitMart Java SDK

The Websocket code quickly implements a lightweight code library, including HTTP requests for all BitMart API interfaces and subscriptions to websocket public and private channels, and can be used after being cloned. This is written specifically for Java developers.

https://github.com/bitmartexchange/bitmart-java-sdk-api

4. BitMart PHP SDK

The Websocket code quickly implements a lightweight code library, including HTTP requests for all BitMart API interfaces and subscriptions to websocket public and private channels, and can be used after being cloned. This is written specifically for PHP developers.

https://github.com/bitmartexchange/bitmart-php-sdk-api

5. BitMart PostMan API

There is now a BitMart Postman collection containing the API endpoints for quick and easy use.

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?

Contact Us

• Get support in our Telegram group BitMart API Club
• Please take 1 minute to help us improve: API Satisfaction Survey

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

• For GET and DELETE method interfaces, parameters must be sent in the query string, i.e., the parameters concatenated after the URL?.
• For POST and PUT method interfaces, parameters are sent in the request body in JSON format.

HTTP Response Codes

• HTTP 4XX Error codes are used to indicate wrong request content, behavior, and format. The problem is from the request sender.
• HTTP 403 The error code indicates a violation of the restriction (prohibited call).
• HTTP 429 The error code indicates that the access frequency is overrun and the IP will be blocked.
• HTTP 418 The error code indicates that the IP has been blocked after error code 429.
• HTTP 5XX Error codes are used to indicate problems with BitMart server.

API Returned Codes

• code Error code
• message Error description
• trace Event tracking ID for each request, which is returned by the server for every request
• data User Data

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

• NONE: Public endpoint, accessible to anyone
• KEYED: Endpoint requires a valid X-BM-KEY to be set in the request header
• SIGNED: Endpoint requires a valid X-BM-KEY and X-BM-SIGN signature to be set in the request header

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

• X-BM-KEY (Your created API Access KEY)
• X-BM-SIGN (Signature using Sha-256)
• X-BM-TIMESTAMP (Current timestamp in milliseconds when the request is sent)

1.2 Set Request Body Params

• For GET/DELETE requests, the query string is in form format, such as symbol=BMX&side=BUY.
• For POST/PUT requests, the query string is in JSON format, such as {"symbol":"BMX","side":"BUY"}.

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

• Request API: /spot/v1/test-post (SIGNED)
• Request method: POST
• Current timestamp: timestamp=1589793796145
• Request body: {"symbol":"BTC_USDT","price":"8600","count":"100"}

Then set the following:

• X-BM-TIMESTAMP=1589793796145
• X-BM-KEY=Your_api_access_key
• X-BM-SIGN= hmac_sha256(Your_api_secret_key, X-BM-TIMESTAMP + '#' + Your_api_memo + '#' + {"symbol":"BTC_USDT","price":"8600","count":"100"})

Assuming the key you applied for is as follows:

• accessKey=80618e45710812162b04892c7ee5ead4a3cc3e56
• secretKey=6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9
• memo=test001

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:

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

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

• currency Currency refers to the basic unit that can be transferred in and out, such as BTC, ETH, EOS, etc
• symbol Trading pair name, consists of base and quote currency. Taking BTC_USDT as an example, BTC is the base currency, and USDT is the quote currency. Trading pairs are mainly used in spot trading
• orderId Order number, the order ID under the same currency pair of each business line is unique
• tradeId The unique number of the trade

Order State （Field: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.

Order Side （Field:side)

• buy=Buy
• sell=Sell

Order Type （Field:type)

• limit=Limit Order
• market=Market Order
• limit_maker=PostOnly Order
• ioc=IOC Order

Trade Role （Field:tradeRole)

• taker=Take orders, take the initiative to deal
• maker=Pending order, passive transaction

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

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": {
    "serivce":[
      {
         "title": "Spot API Stop",
         "service_type": "spot",
         "status": "2",
         "start_time": 1527777538000,
         "end_time": 1527777538000
     },
     {
        "title": "Contract API Stop",
        "service_type": "contract",
        "status": "2",
        "start_time": 1527777538000,
        "end_time": 1527777538000
    }
   ]
  }
}

Public Market Data

Get Currency List

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

Get List of Trading Pairs

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

Note

• Returns an array of trading pairs
• "BMX_ETH" it means that the base currency of this trading pair is BMX, and the quote currency is ETH

Get List of Trading Pair Details

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

Get Ticker of All Pairs

Ticker is an overview of the market status of a trading pair, including the latest trade price, top bid and ask prices and 24-hour trading volume

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/spot/v1/ticker?symbol=BTC_USDT

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

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

Get Ticker of a Trading Pair

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

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

Get K-Line Step

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

Get K-Line

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

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

Description of k-line details field:

Get Depth

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

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

Market depth details：

Get Recent Trades

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

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

Depth data details field description:

Sub-Account Endpoints

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

Sub-Account Spot Asset Transfer (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

Response Data

Response

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

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

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

Sub-Account Spot Asset Transfer (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

Response Data

Response

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

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

Main Account Spot Asset Transfer (For Main Account) (SIGNED)

Main Account Spot Asset Transfer (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

Response Data

Response

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

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

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

Sub-Account to Sub-Account Spot Asset Transfer (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

Response Data

Response

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

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

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

Sub-Account to Sub-Account Spot Asset Transfer (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

Response Data

Response

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

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

Query Sub-Account Spot Asset Transfer History (For Main Account) (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

Response Data

Response

{
  "message": "OK",
  "code": 1000,
  "trace": "282fd16e-73ee-464f-adb7-7241345929f6",
  "data": {
    "total": 2,
    "historyList": [
      {
        "fromAccount": "[email protected]",
        "fromWalletType": "spot",
        "toAccount": "SubAccoun[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
      }
    ]
  }
}

Get Account Spot Asset Transfer History (KEYED)

Get Account Spot Asset Transfer History

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

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

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]

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

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

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

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

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

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

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

Instruction

Response Data

Response

{
    "message":"OK",
    "code":1000,
    "trace":"0e6edd79-f77f-4251-abe5-83ba75d06c1a",
    "data":{
        "currency":"USDT-TRC20",
        "chain":"USDT-TRC20",
        "address":"TGR3ghy2b5VLbyAYrmiE15jasR6aPHTvC5",
        "address_memo":""
    }
}

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

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

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

Request

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

Response Data

Response

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

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

Step2. Go to Withdrawal Address Management page and add

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

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":""
      },
      ...
    ]
  }
}

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

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

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

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

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

Response Data

Response

{
    "message":"OK",
    "code":1000,
    "trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
    "data":{
      "transfer_id":"124532"
    }
}

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

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

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

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

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

Special Parameters for Market Orders (type=market)

Instruction

Buy-limit-maker

• When "order price">="market lowest selling price", the system will refuse to accept the order after the order is submitted

• When the "order price" <"the lowest selling price in the market", the order will be accepted by the system after the submission is successful

• When "order price"*"order size"<minimum deal amount in the market, the system will refuse to accept the order after the order is submitted.

Sell-limit-maker

• When "order price" <= "market highest bid price", after the order is submitted, the system will refuse to accept the order

• When "order price"> "market highest bid price", the order will be accepted by the system after the submission is successful

• When "order price"*"order size"<minimum deal amount in the market, the system will refuse to accept the order after the order is submitted.

Buy-ioc,Sell-ioc

• After the order is placed, all orders that cannot be filled immediately are cancelled immediately

Response Data

Response

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

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

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

Special Parameters for Market Orders (type=market)

Instruction

Buy-limit-maker

• When "order price">="market lowest selling price", the system will refuse to accept the order after the order is submitted

• When the "order price" <"the lowest selling price in the market", the order will be accepted by the system after the submission is successful

Sell-limit-maker

• When "order price" <= "market highest bid price", after the order is submitted, the system will refuse to accept the order

• When "order price"> "market highest bid price", the order will be accepted by the system after the submission is successful

Buy-ioc,Sell-ioc

• After the order is placed, all orders that cannot be filled immediately are cancelled immediately

Response Data

Response

{
    "message":"OK",
    "code":1000,
    "trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
    "data":{
      "order_id":1223181
    }
}

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

orderParam

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

Special Parameters for Market Orders (type=market)

Instruction

Buy-limit-maker

• When "order price">="market lowest selling price", the system will refuse to accept the order after the order is submitted

• When the "order price" <"the lowest selling price in the market", the order will be accepted by the system after the submission is successful

• When "order price"*"order size"<minimum deal amount in the market, the system will refuse to accept the order after the order is submitted.

Sell-limit-maker

• When "order price" <= "market highest bid price", after the order is submitted, the system will refuse to accept the order

• When "order price"> "market highest bid price", the order will be accepted by the system after the submission is successful

• When "order price"*"order size"<minimum deal amount in the market, the system will refuse to accept the order after the order is submitted.

Buy-ioc,Sell-ioc

• After the order is placed, all orders that cannot be filled immediately are cancelled immediately

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

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

Response Data

Response

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

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

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

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

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

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