NAV
Example

Change Log

2023-05-18

2023-03-23

2023-03-16

2022-09-22

2022-08-31

2022-08-23

2022-08-18

Introduction

API Key Create

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

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

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/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
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
Contract-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

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

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:

Contract Interface Interface Name Limit Target Rate Special Remarks
/contract/public/details Get a detailed list of all trading pairs IP 12 times/2 sec
/contract/public/depth Get full depth of trading pairs IP 12 times/2 sec
/contract/public/open-interest Get Contract Openinterest IP 2 times/2 sec
/contract/private/submit-order Submit Contract Order X-BM-KEY 24 times/2 sec
/contract/private/cancel-order Cancel Contract Order X-BM-KEY 40 times/2 sec
/contract/private/cancel-orders Batch Cancel Contract Orders X-BM-KEY 2 times/2 sec
/contract/private/submit-plan-order Submit Contract Plan Order X-BM-KEY 24 times/2 sec
/contract/private/cancel-plan-order Cancel Contract Plan Order X-BM-KEY 40 times/2 sec
/contract/private/order Get Contract Order Detail X-BM-KEY 50 times/2 sec
/contract/private/order-history Get Contract Order History X-BM-KEY 6 times/2 sec
/contract/private/trades Get Contract Order Trade Detail X-BM-KEY 6 times/2 sec
/contract/private/assets-detail Get Contract Assets Detail X-BM-KEY 12 times/2 sec
/contract/private/position Get Current Position Detail X-BM-KEY 6 times/2 sec
/contract/public/funding-rate Get Current Funding Rate IP 2 times/2 sec
/contract/public/kline Get K-line IP 12 times/2 sec
/account/v1/transfer-contract Transfer X-BM-KEY 1 times/2s
/account/v1/transfer-contract-list Get Transfer List X-BM-KEY 1 times/2s

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

Futures Public API Definitions

Field description

Field description

Order State(Field:state)

Order Side(Field:side)

Position(Field:position_type)

Order Type(Field:type)

Open Type(Field:open_type)

Order Mode(Field:mode)

Timestamp

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

Futures Market Data

Get Contract Details

Applicable to query contract details

Request URL

GET https://api-cloud.bitmart.com/contract/public/details

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/contract/public/details?symbol=BTCUSDT
Field Type Required? Description
symbol String No Symbol of the contract(like BTCUSDT)

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "trace": "9b92a999-9463-4c96-91a4-93ad1cad0d72",
  "data": {
    "symbols": [
      {
        "symbol": "BTCUSDT",
        "product_type": 1,
        "open_timestamp": 1594080000,
        "expire_timestamp": 0,
        "settle_timestamp": 0,
        "base_currency": "BTC",
        "quote_currency": "USDT",
        "last_price": "23920",
        "volume_24h": "18969368",
        "turnover_24h": "458933659.7858",
        "index_price": "23945.25191635",
        "index_name": "BTCUSDT",
        "contract_size": "0.001",
        "min_leverage": "1",
        "max_leverage": "100",
        "price_precision": "0.1",
        "vol_precision": "1",
        "max_volume": "500000",
        "min_volume": "1",
        "funding_rate": "0.0001",
        "expected_funding_rate": "0.00011",
        "open_interest": "4134180870",
        "open_interest_value": "94100888927.0433258"
      },
      ...
    ]
  }
}
Field Type Description
symbols List Array of trading pair details

Description of the trading pair details field:

Trading pair details Type Description
symbols List Array of trading pair details
symbol String Symbol of the contract
product_type Int Contract type
-1=perpetual
-2=futures
base_currency String Base currency
quote_currency String Quote currency
volume_precision String Volume Precision
price_precision String Price Precision
max_volume String Maximum order quantity
min_volume String Minimum order quantity
contract_size String Contract Size
index_price String Index Price
index_name String Index Name
min_leverage String Minimum leverage ratio
max_leverage String Maximum leverage ratio
turnover_24h String 24 hours turnover
volume_24h String 24 hours volume
last_price String Last Price
open_timestamp Long Opening time for the first time
expire_timestamp Long Expiration time,If null is returned, it does not expire
settle_timestamp Long Settlement time,If null is returned, it will not be automatically settlement
funding_rate String current funding rate
expected_funding_rate String expect funding rate
open_interest String Open interest
open_interest_value String Value of open interest

Get Market Depth

Get full depth of trading pairs.

Request URL

GET https://api-cloud.bitmart.com/contract/public/depth

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/contract/public/depth?symbol=BTCUSDT
Field Type Required? Description
symbol String Yes Symbol of the contract(like BTCUSDT)

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "trace": "b9bff62d-9ac8-4815-8808-8f745673c096",
  "data": {
    "asks": [
      [
        "23935.4",
        "65",
        "65"
      ]
    ],
    "bids": [
      [
        "23935.4",
        "65",
        "65"
      ]
    ],
    "timestamp": 1660285421287,
    "symbol": "BTCUSDT"
  }
}
Field Type Description
timestamp Long Unix timestamp in milliseconds for when the last updated time occurred
bids List Bid order depth
asks List Ask order depth

Market depth details:

Field Type Description
The first String The price at current depth. For example 23935.4
The second String Total quantity of current price depth. For example 65
The third String Accumulates the total quantity above (including) the current price depth. For example 65

Get Futures Openinterest

Applicable for querying the open interest and open interest value data of the specified contract

Request URL

GET https://api-cloud.bitmart.com/contract/public/open-interest

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/contract/public/open-interest?symbol=BTCUSDT

Field Type Required? Description
symbol String Yes Symbol of the contract(like BTCUSDT)

Response Data

Response

{
  "code": 1000,
  "trace": "0cc6f4c4-8b8c-4253-8e90-8d3195aa109c",
  "message": "Ok",
  "data": {
    "timestamp": 1661239541734,
    "symbol": "BTCUSDT",
    "open_interest": "4134180870",
    "open_interest_value": "94100888927.0433258"
  }
}
Field Type Description
timestamp Long Timestamp
symbol String Symbol of the contract
open_interest String Open interest
open_interest_value String Value of open interest

Get Current Funding Rate

Applicable for checking the current funding rate of a specified contract

Request URL

GET https://api-cloud.bitmart.com/contract/public/funding-rate

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/contract/public/funding-rate?symbol=BTCUSDT

Field Type Required? Description
symbol String Yes Symbol of the contract(like BTCUSDT)

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "timestamp": 1662518172178,
    "symbol": "BTCUSDT",
    "rate_value": "0.000164",
    "expected_rate": "0.000164"
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}
Field Type Description
timestamp Long Timestamp
symbol String Symbol of the contract
rate_value String Funding rate of the previous period
expected_rate String Funding rate for the next period

Get K-line

Applicable for querying K-line data

Request URL

GET https://api-cloud.bitmart.com/contract/public/kline

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud.bitmart.com/contract/public/kline?symbol=BTCUSDT&step=5&start_time=1662518172&end_time=1662518172

Field Type Required? Description
symbol String Yes Symbol of the contract(like BTCUSDT)
step Long No K-Line step, default is 1 minute. step: 1, 3, 5, 15, 30, 60, 120, 240, 360, 720, 1440, 4320, 10080
start_time Long Yes Start time. Timestamps need to be in seconds
end_time Long Yes End time. Timestamps need to be in seconds

Response Data

Response

{
  "code": 1000,
  "trace": "0cc6f4c4-8b8c-4253-8e90-8d3195aa109c",
  "message": "Ok",
  "data": {
    "timestamp": 1662518160,
    "open_price": "100",
    "close_price": "120",
    "high_price": "130",
    "low_price": "90",
    "volume": "941008"
  }
}
Field Type Description
timestamp Long Time Window
open_price String Opening Price
close_price String Closing Price
high_price String Highest Price
low_price String Lowest Price
volume String Turnover

Futures Account Data

Get Contract Assets (KEYED)

Applicable for querying user contract asset details

Request URl

GET https://api-cloud.bitmart.com/contract/private/assets-detail

Request Limit

See Detailed Rate Limit

Request Parameter

Request None

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/contract/private/assets-detail

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": [
    {
      "currency": "USDT",
      "position_deposit": "100",
      "frozen_balance": "100",
      "available_balance": "100",
      "equity": "100",
      "unrealized": "100"
    },
    {
      "currency": "BTC",
      "available_balance": "0",
      "frozen_balance": "0",
      "unrealized": "0",
      "equity": "0",
      "position_deposit": "0"
    },
    {
      "currency": "ETH",
      "available_balance": "0",
      "frozen_balance": "0",
      "unrealized": "0",
      "equity": "0",
      "position_deposit": "0"
    }
  ],
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}
Field Type Description
currency String Currency
position_deposit String Position margin
frozen_balance String Transaction freeze amount
available_balance String Available amount
equity String Total equity
unrealized String Unrealized P&L

Futures Trading

Get Order Detail (KEYED)

Applicable for querying contract order detail

Request URL

GET https://api-cloud.bitmart.com/contract/private/order

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/contract/private/order?symbol=BTCUSDT&order_id=220609666322019
Field Type Required? Description
symbol String Yes Symbol of the contract(like BTCUSDT)
order_id String Yes Order ID

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "order_id": "220906179895578",
    "price": "1",
    "size": "1000",
    "symbol": "BTCUSDT",
    "state": 2,
    "side": 1,
    "type": "limit",
    "leverage": "5",
    "open_type": "isolated",
    "deal_avg_price": "0",
    "deal_size": "1000",
    "create_time": 1662368173000,
    "update_time": 1662368173000
  },
  "trace": "638d5048-ad21-4a4b-9365-d0756fbfc7ba"
}
Field Type Description
symbol String Symbol of the contract
order_id String Order ID
side Int Order side
-1=buy_open_long
-2=buy_close_short
-3=sell_close_long
-4=sell_open_short
type String Order type
-limit
- market
- liquidate
- bankruptcy
leverage String Leverage order multipliers
open_type String Open type
-cross
-isolated
deal_avg_price String Average deal price
deal_size String Deal amount
price String Consignment price
state Int Order status
-2=status_check
-4=status_finish
create_time Long Create time
update_time Long Update time

Get Order History (KEYED)

Applicable for querying contract order history

Request URL

GET https://api-cloud.bitmart.com/contract/private/order-history

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/contract/private/order-history?symbol=BTCUSDT&start_time=1662368173&end_time=1662368179
Field Type Required? Description
symbol String Yes Symbol of the contract(like BTCUSDT)
start_time Long No Start time, default is the last 7 days
end_time Long No End time, default is the last 7 days

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "order_id": "220906179895578",
    "price": "1",
    "size": "1000",
    "symbol": "BTCUSDT",
    "state": 2,
    "side": 1,
    "type": "limit",
    "leverage": "5",
    "open_type": "isolated",
    "deal_avg_price": "0",
    "deal_size": "1000",
    "create_time": 1662368173000,
    "update_time": 1662368173000
  },
  "trace": "638d5048-ad21-4a4b-9365-d0756fbfc7ba"
}
Field Type Description
symbol String Symbol of the contract
order_id String Order ID
side Int Order side
-1=buy_open_long
-2=buy_close_short
-3=sell_close_long
-4=sell_open_short
type String Order type
-limit
- market
- liquidate
- bankruptcy
leverage String Leverage order multipliers
open_type String Open type
-cross
-isolated
deal_avg_price String Average deal price
deal_size String Deal amount
price String Consignment price
state Int Order status
-2=status_check
-4=status_finish
create_time Long Create time
update_time Long Update time

Get Current Position (KEYED)

Applicable for checking the position details a specified contract

Request URL

GET https://api-cloud.bitmart.com/contract/private/position

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/contract/private/position?symbol=BTCUSDT
Field Type Required? Description
symbol String No Symbol of the contract(like BTCUSDT)

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": [
    {
      "symbol": "BTCUSDT",
      "leverage": "5",
      "timestamp": 1663814313531,
      "current_fee": "5.00409471",
      "open_timestamp": 1662714817820,
      "current_value": "16680.3157",
      "mark_price": "16673.27053207877",
      "position_value": "18584.272343943943943944339",
      "position_cross": "3798.397624451826977945",
      "maintenance_margin": "4798.397624451826977945",
      "close_vol": "100",
      "close_avg_price": "20700.7",
      "open_avg_price": "20200",
      "current_amount": "899",
      "unrealized_value": "1903.956643943943943944339",
      "realized_value": "55.049173071454605573",
      "position_type": 2
    }
  ],
  "trace": "ae96cae5-1f09-4ea5-971e-4474a6724bc8"
}
Field Type Description
leverage String Leverage multiplier
symbol String Symbol of the contract
current_fee String Current position fees
open_timestamp Long Opening timestamp
current_value String Current position value
mark_price String Marker price
position_value String Position value
open_avg_price String Open average price
close_avg_price String Close average price
close_vol String Close volume
position_cross String Margin calls to positions
maintenance_margin String Maintenance Margin
current_amount String Current position amount
unrealized_value String Unrealized PnL
realized_value String Realized PnL
position_type Int position type
-1=long
-2=short
timestamp Long Current timestamp

Get Order Trade (KEYED)

Applicable for querying contract order trade detail

Request URL

GET https://api-cloud.bitmart.com/contract/private/trades

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/contract/private/trades?symbol=BTCUSDT&start_time=1662368173&end_time=1662368179
Field Type Required? Description
symbol String Yes Symbol of the contract(like BTCUSDT)
start_time Long No Start time, default is the last 7 days
end_time Long No End time, default is the last 7 days

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": [{
    "order_id": "220921197409432",
    "trade_id": "1141853921",
    "symbol": "BTCUSDT",
    "side": 1,
    "price": "19313.3",
    "vol": "108",
    "exec_type": "Maker",
    "profit": false,
    "realised_profit": "-0.00832",
    "paid_fees": "0",
    "create_time": 1663663818589
  }],
  "trace": "638d5048-ad21-4a4b-9365-d0756fbfc7ba"
}
Field Type Description
symbol String Symbol of the contract
order_id String Order ID
trade_id String Trade detail ID
side Int Order side
-1=buy_open_long
-2=buy_close_short
-3=sell_close_long
-4=sell_open_short
price String Deal price
vol String Deal vol
profit Boolean Profitable or not
exec_type String Liquidity type
-Taker
-Maker
realised_profit String realised profit
paid_fees String paid fees
create_time Long Create time

Get Transfer List (SIGNED)

Query futures account transfer records

Request URl

POST https://api-cloud.bitmart.com/account/v1/transfer-contract-list

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",
    "time_start":1684391137804,
    "time_end":1684392577804,
    "page":1,
    "limit":10,
    "recvWindow":5000
}'
https://api-cloud.bitmart.com/account/v1/transfer-contract-list
Field Type Required? Description
currency String No Currency (like USDT)
time_start Long No Start time in milliseconds, (e.g. 1681701557927)
time_end Long No End time in milliseconds, (e.g. 1681701557927)
page Int Yes Number of pages, allowed range [1,1000]
limit Int Yes Number of queries, allowed range [10,100]
recvWindow Long No Trade time limit, allowed range (0,60000], default: 5000 milliseconds
Note

Response Data

Response

{
    "message":"OK",
    "code":1000,
    "trace":"82abff12-b9d9-4f66-89ea-3b604c6d84",
    "data":{
        "records":[{
            "transfer_id":"664651258694168576",
            "currency":"USDT",
            "amount":"0.1",
            "type":"contract_to_spot",
            "state":"FINISHED",
            "timestamp":1638631674326
        }]
    }
}
Field Type Description
transfer_id String ID
currency String Currency
amount String Amount
type String Type
-spot_to_contract
-contract_to_spot
state String Result
-PROCESSING=Waiting to execute
-FINISHED=Successful transfer
-FAILED=Transfer failed
timestamp Long Transfer creation time in milliseconds, e.g. 1638631674326

Submit Order (SIGNED)

Applicable for placing contract orders

Request URL

POST https://api-cloud.bitmart.com/contract/private/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":"ETHUSDT",
  "side":4,
  "mode":1,
  "type":"limit",
  "leverage":"1",
  "open_type":"isolated",
  "size":10,
  "price":"2000"
}'
https://api-cloud.bitmart.com/contract/private/submit-order
Field Type Required? Description
symbol String Yes Symbol of the contract(like BTCUSDT)
type String No Order type
-limit(default)
-market
side Int Yes Order side
-1=buy_open_long
-2=buy_close_short
-3=sell_close_long
-4=sell_open_short
leverage String Yes Order leverage
open_type String Yes Open type, required at close position
-cross
-isolated
mode Int No Order mode
-1=GTC(default)
-2=FOK
-3=IOC
-4=Maker Only
price String Yes Order price, required at limit order
size Int Yes Order size. Size refers to the order amount in the unit of contracts

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "order_id": "220609666322019"
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}
Field Type Description
order_id String Order ID

Cancel Order (SIGNED)

Applicable for canceling a specific contract order

Request URL

POST https://api-cloud.bitmart.com/contract/private/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":"ETHUSDT",
  "order_id": "220906179559421"
}'
https://api-cloud.bitmart.com/contract/private/cancel-order
Field Type Required? Description
symbol String Yes Symbol of the contract(like BTCUSDT)
order_id String Yes Order ID

Response Data

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

Response

{
  "code": 1000,
  "trace": "0cc6f4c4-8b8c-4253-8e90-8d3195aa109c",
  "message": "Ok",
  "data": {
  }
}

Cancel All Orders (SIGNED)

Applicable for batch order cancellation under a particular contract

Request URL

POST https://api-cloud.bitmart.com/contract/private/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":"ETHUSDT"
}'
https://api-cloud.bitmart.com/contract/private/cancel-orders
Field Type Required? Description
symbol String Yes Symbol of the contract(like BTCUSDT)

Response Data

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

Response

{
  "code": 1000,
  "trace": "0cc6f4c4-8b8c-4253-8e90-8d3195aa109c",
  "message": "Ok",
  "data": {
  }
}

Submit Plan Order (SIGNED)

Applicable for placing contract plan orders

Request URL

POST https://api-cloud.bitmart.com/contract/private/submit-plan-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":"ETHUSDT",
  "side":4,
  "mode":1,
  "type":"limit",
  "leverage":"1",
  "open_type":"isolated",
  "size":10,
  "trigger_price":"2000",
  "executive_price":"1450",
  "price_type":1,
  "price_way":1
}'
https://api-cloud.bitmart.com/contract/private/submit-plan-order
Field Type Required? Description
symbol String Yes Symbol of the contract(like BTCUSDT)
type String No Order type
-limit(default)
-market
side Int Yes Order side
-1=buy_open_long
-2=buy_close_short
-3=sell_close_long
-4=sell_open_short
leverage String Yes Order leverage
open_type String Yes Open type, required at close position
-cross
-isolated
mode Int No Order mode
-1=GTC(default)
-2=FOK
-3=IOC
-4=Maker Only
size Int Yes Order size. Size refers to the order amount in the unit of contracts
trigger_price String Yes Trigger price
executive_price String No Order price, required at limit order
price_way Int Yes Price way
-1=price_way_long
-2=price_way_short
price_type Int Yes Trigger price type
-1=last_price
-2=fair_price

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "order_id": "220609666322019"
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}
Field Type Description
order_id String Order ID

Cancel Plan Order (SIGNED)

Applicable for canceling a specific contract plan order

Request URL

POST https://api-cloud.bitmart.com/contract/private/cancel-plan-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":"ETHUSDT",
  "order_id": "220906179559421"
}'
https://api-cloud.bitmart.com/contract/private/cancel-plan-order
Field Type Required? Description
symbol String Yes Symbol of the contract(like BTCUSDT)
order_id String Yes Order ID

Response Data

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

Response

{
  "code": 1000,
  "trace": "0cc6f4c4-8b8c-4253-8e90-8d3195aa109c",
  "message": "Ok",
  "data": {
  }
}

Transfer (SIGNED)

Transfer between spot account and contract account

Request URl

POST https://api-cloud.bitmart.com/account/v1/transfer-contract

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",
  "amount":"10",
  "type":"spot_to_contract",
  "recvWindow":5000
}'
https://api-cloud.bitmart.com/account/v1/transfer-contract
Field Type Required? Description
currency String Yes Currency (Only USDT is supported)
amount String Yes Transfer amount,allowed range[0.01,10000000000]
type String Yes Transfer type
-spot_to_contract
-contract_to_spot
recvWindow Long No Trade time limit, allowed range (0,60000], default: 5000 milliseconds

Response Data

Response

{
  "message":"OK",
  "code":1000,
  "trace":"34018ca3-fe24-446a-9e1d-f82edfb3e3",
  "data":{
    "currency":"USDT",
    "amount":"10"
  }
}
Field Type Description
currency String currency
amount String Amount successfully transferred

WebSocket Subscription

Overview

Address

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

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

Format

Request Format

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

Terminology

operation: Request action, value

Subscribe=subscribeUnsubscribe=unsubscribeLogin=login

args: Request parameter, value: channel array or parameters required for login

topic: Channel topic, composed of <channel>:<filter>

channel is composed of business/name

filter can filter data, refer to the description of each channel for details

Example: futures/klineBin1m:BTCUSDT: which means klineBin data of contract trading pair BTCUSDT

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

Successful Response Format

Successful Response Format

When action=access 
{"action":"access","success":true}

When action=unsubscribe 
{"action":"unsubscribe","group":"Depth:1","success":true,"request":{"action":"unsubscribe","args":["Depth:1"]}}

When action=subscribe 
{"action":"subscribe","group":"Depth:1","success":true,"request":{"action":"subscribe","args":["Depth:1"]}}

When success field of return data is true, it indicates success

Failed Response Format

Failed Response Format

{"action":"subscribe","group":"Depth:1","success":false,"error":"authentication is temporarily unavailable"}

When success field of return data is false, it indicates failure

Stay Connected And Limit

Stay Connected

WebSocket uses the Ping/Pong mechanism to maintain the connection. Once the connection is opened, a Ping frame is sent every N seconds, and the remote endpoint will return a Pong frame to keep responding. This is an approach to stay active. It helps to keep the connection open, especially if there is a short timeout proxy on an inactive connection.

If no data is returned after connecting to WebSocket, the link will be automatically disconnected after 5s. It is recommended that the user do the following:

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

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:

The following is the data format of ping:

ws.send(new PingWebSocketFrame();

{"subscribe":"ping"}

Connection Limit

Public Channel

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

Private Channel

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

Lifeless connection

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

WebSocket Subscription

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

subscribe

{"action":"subscribe","args":["futures/depth50:BTCUSDT","futures/ticker"]}

Parameter Instructions

Example

Request

{"action":"subscribe","args":["futures/depth50:BTCUSDT","futures/ticker"]}

Response

{"action":"subscribe","group":"futures/ticker","success":true,"request":{"action":"subscribe","args":["futures/ticker"]}}
{"action":"subscribe","group":"futures/depth50:BTCUSDT","success":true,"request":{"action":"subscribe","args":["futures/depth50:BTCUSDT"]}}
{"action":"subscribe","group":"futures/klineBin1m:BTCUSDT","success":true,"request":{"action":"subscribe","args":["futures/klineBin1m:BTCUSDT"]}}

Unsubscribe

Cancel subscription to one or more channels

unsubscribe

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

Parameter Instruction

Example

Request

{"action": "unsubscribe", "args": ["futures/klineBin1m:BTCUSDT"]}

Response

{"action":"unsubscribe","group":"futures/klineBin1m:BTCUSDT","success":true,"request":{"action":"unsubscribe","args":["futures/klineBin1m:BTCUSDT"]}}

【Public】Ticker Channel

Get the latest transaction price, bid one price, ask for one price, and 24 trading volumes of all perpetual contracts on the platform, without user login, sent once in 1 second after subscription.

Pushing Rules

  1. No user login required
  2. After subscribing, the current data will be returned directly, and then the changes will be pushed

Example

Request

{"action":"subscribe","args":["futures/ticker"]}

futures/ticker is the channel name

Response

{
    "group":"futures/ticker",
    "data":{
          "symbol":"BTCUSDT",
          "volume_24":"117387.58",
          "fair_price":"146.24",
          "last_price":"146.24",
          "range":"147.17",
          "ask_price": "147.11",
          "bid_price": "142.11"
        }
}

Parameter Type Description:

Parameter Type Description
symbol string Symbol of the contract(like BTCUSDT)
last_price string Latest Price
volume_24 string Volume of 24-hour transactions
range string Up or Down
fair_price string Fair Price
ask_price string Sell depths first price
bid_price string Buy depths first price

【Public】Depth Channel

Get depth data and push updates as soon as they are available without user login.

Pushing Rules

  1. No user login required
  2. After subscribing, the current data will be returned directly, and then the changes will be pushed

Example

Request

{"action":"subscribe","args":["futures/depth20:BTCUSDT"]}

futures/depth20 is the channel name and BTCUSDT is the trading side

Channel List

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

Response

{
    "group":"futures/depth20:BTCUSDT",
    "data":{
            "symbol":"BTCUSDT",
            "way":1,
            "depths":[
              {"price":"5","vol":"97"}
            ],
            "ms_t": 1542337219120
        }
}

Parameter Type Description:

Parameter Type Description
symbol string Symbol of the contract(like BTCUSDT)
way long Trading side
1=ask
2=bid
depths list Array of depth details
ms_t long Timestamp (in millisecond)

Instruction

Description of the depth details field:

depth details Type Description
price string price
vol string volume

【Public】Trade Channel

Get trade data and push updates as soon as they are available without user login.

Pushing Rules

  1. No user login required
  2. After subscribing, the current data will be returned directly, and then the changes will be pushed

Example

Request

{"action":"subscribe","args":["futures/trade:BTCUSDT"]}

futures/trade is the channel name and BTCUSDT is the trading side

Response

{
  "group":"futures/trade:BTCUSDT",
  "data":[{
    "symbol":"BTCUSDT",
    "deal_price":"117387.58",
    "deal_vol":"1445",
    "created_at":"2023-02-24T07:54:11.124940968Z"
  }]
}

Instruction

Description of the depth details field:

depth details Type Description
symbol string symbol
deal_price string deal price
deal_vol string deal vol
created_at string create time

【Public】klineBin Channel

Get individual contract K-line data and push updates as soon as they are available without user login.

Pushing Rules

  1. No user login required
  2. After subscribing, the current data will be returned directly, and then the changes will be pushed

Example

Request

{"action":"subscribe","args":["futures/klineBin1m:BTCUSDT"]}

futures/klineBin1m is the channel name, BTCUSDT is the trading pair

Channel List

Channel Name Description
futures/klineBin1m 1-min klineBin Channel
futures/klineBin5m 5-min klineBin Channel
futures/klineBin15m 15-min klineBin Channel
futures/klineBin30m 30-min klineBin Channel
futures/klineBin1H 1-hour klineBin Channel
futures/klineBin2H 2-hour klineBin Channel
futures/klineBin4H 4-hour klineBin Channel
futures/klineBin1D 1-day klineBin Channel
futures/klineBin1W 1-week klineBin Channel

Response

{
    "group":"futures/klineBin1m:BTCUSDT",
    "data":{
            "symbol":"BTCUSDT",
            "o":"146.24",
            "h":"146.24",
            "l":"146.24",
            "c":"146.24",
            "v":"146"
        }
}

Parameter Type Description:

Parameter Type Description
symbol string Symbol of the contract(like BTCUSDT)
o string Opening Price
h string Highest Price
l string Lowest Price
c string Closing Price
v string Turnover

【Private】Login

Login Subscription Format

Request

{"action":"access","args":["<API_KEY>","<timestamp>","<sign>","<dev>"]}

API_KEY: The user's API key

timestamp: Timestamp, the unit is milliseconds, it will expire after 60 seconds

sign: Signature, sign=CryptoJS.HmacSHA256("" + "#" + "" + "#" + "bitmart.WebSocket", secret)

dev: Device, web eg.

Example

sign

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

example

{"action": "access", "args": ["80618e45710812162b04892c7ee5ead4a3cc3e56", "1589267764859", "3ceeb7e1b8cb165a975e28a2e2dfaca4d30b358873c0351c1a071d8c83314556","web"]}

Response

{"action":"access","success":true}

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

timestamp=1589267764859

API_KEY = "80618e45710812162b04892c7ee5ead4a3cc3e56"

API_SECRET = "6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9"

API_MEMO = "test001";

If success field of return data is true, it indicates success

【Private】Assets Channel

Asset balance change channel, any changes will be pushed immediately.

Example

Request

{
    "action": "subscribe",
    "args":["futures/asset:USDT", "futures/asset:BTC", "futures/asset:ETH"]
}

Supported asset types for subscription are: USDT (U-native), BTC (coin-native), ETH (coin-native)

Return

{
  "group": "futures/asset:BTC",
  "data": {
    "currency": "BTC",
    "available_balance": "1000",
    "position_deposit": "1000",
    "frozen_balance": "1000"
  }
}

Parameter Type Description:

Parameter Type Description
currency string Currency
available_balance string Available Amount
position_deposit string Position Margin
frozen_balance string Transaction Frozen Amount

【Private】Position Channel

Position channel, any changes will be pushed immediately.

Push rules

  1. user login required
  2. 10 seconds timed push

Example

Request

{
    "action": "subscribe",
    "args":["futures/position"]
}

return

{
  "group": "futures/position",
  "data": [
    {
      "symbol": "BTCUSDT",
      "hold_volume": "2000",
      "position_type": 1,
      "open_type": 1,
      "frozen_volume": "0",
      "close_volume": "0",
      "hold_avg_price": "19406.2092",
      "close_avg_price": "0",
      "open_avg_price": "19406.2092",
      "liquidate_price": "15621.998406",
      "create_time": 1662692862255,
      "update_time": 1662692862255
    }
  ]
}

Parameter Type Description:

Parameter Type Description
symbol string Contract pair (e.g. BTCUSDT)
hold_volume string Number of positions
position_type int Position type
1=long
2=short
open_type int Open position type
1=isolated
2=cross
frozen_volume string Frozen volume
close_volume string Close volume
hold_avg_price string Average price of a position
close_avg_price string Average close price
open_avg_price string Average opening price
liquidate_price string Liquidation price
create_time timestamp Create time
update_time timestamp Update time

【Private】Order Channel

Order Channel, which pushes immediately when the order status, transaction amount, etc. changes.

Example

request

{
    "action":"subscribe",
    "args":["futures/order"]
}

back

{
  "group": "futures/order",
  "data": [
    {
      "action": 3,
      "order": {
        "order_id": "220906179895578",
        "price": "1",
        "size": "1000",
        "symbol": "BTCUSDT",
        "state": 2,
        "side": 1,
        "type": "limit",
        "leverage": "5",
        "open_type": "isolated",
        "deal_avg_price": "0",
        "deal_size": "1000",
        "create_time": 1662368173000,
        "update_time": 1662368173000,
        "plan_order_id":"220901412155341"
      }
    }
  ]
}

返回参数说明:

参数名称 数据类型 描述
action int 1=match deal
2=submit order
3=cancel order
4=liquidate cancel order
5=adl cancel order
6=part liquidate
7=bankruptcy order
8=passive adl match deal
9=active adl match deal
symbol string Symbol of the contract
order_id string Order ID
side int Order side
1=buy_open_long
2=buy_close_short
3=sell_close_long
4=sell_open_short
type string Order type limit or market
leverage string Leverage order multipliers
open_type string Open type cross or isolated
deal_avg_price string Average deal price
deal_size string Deal amount
price string Consignment price
state int Order status
2=status_check
4=status_finish
create_time long Create time
update_time long Update time
plan_order_id string Trigger plan order id

Error Code

Restful Error Code

List of global HTTP return codes

HTTP Description
404 Not Found-The requested interface could not be found
403 Forbidden-No permission to access the resource (KEY may not have permission, or it may be IP restrictions)
401 Unauthorized-Authentication failed (there are problems with the 3 header parameters, failed)
500 Internal Server Error-Server exception, BitMart service problem

Authentication Error Code

Example: httpStatus:200, body:{"code": 1000, "message": "OK", "trace": "12323-3243242-34334534-4353","data":{}}

error message code error code http status code
Not found 30000 404
Header X-BM-KEY is empty 30001 401
Header X-BM-KEY not found 30002 401
Header X-BM-KEY has frozen 30003 401
Header X-BM-SIGN is empty 30004 401
Header X-BM-SIGN is wrong 30005 401
Header X-BM-TIMESTAMP is empty 30006 401
Header X-BM-TIMESTAMP range. Within a minute 30007 401
Header X-BM-TIMESTAMP invalid format 30008 401
IP is forbidden. We recommend enabling IP whitelist for API trading. After that reauth your account 30010 403
Header X-BM-KEY over expire time 30011 403
Header X-BM-KEY is forbidden to request it 30012 403
Request too many requests 30013 429
Service unavailable 30014 503

Contract API Error Code

Example: httpStatus:400, body:{"code": 40001, "message":"out_trade_no not found", "trace":"8bynjk-nmoew-sd1221-csd-123" }

errMsg error message code error code http status code
OK 1000 200
Cloud account not found 40001 400
out_trade_no not found 40002 400
out_trade_no already existed 40003 400
Cloud account count limit 40004 400
Transfer vol precision error 40005 400
Invalid ip error 40006 400
Parse parameter error 40007 400
Check nonce error 40008 400
Check ver error 40009 400
Not found func error 40010 400
Invalid request 40011 400
System error 40012 400
Access too often" CLIENT_TIME_INVALID, "Please check your system time. 40013 400
This contract is offline 40014 400
This contract's exchange has been paused 40015 400
This order would trigger user position liquidate 40016 400
It is not possible to open and close simultaneously in the same position 40017 400
Your position is closed 40018 400
Your position is in liquidation delegating 40019 400
Your position volume is not enough 40020 400
The position is not exsit 40021 400
The position is not isolated 40022 400
The position would liquidate when sub margin 40023 400
The position would be warnning of liquidation when sub margin 40024 400
The position’s margin shouldn’t be lower than the base limit 40025 400
You cross margin position is in liquidation delegating 40026 400
You contract account available balance not enough 40027 400
Your plan order's count is more than system maximum limit. 40028 400
The order's leverage is too large. 40029 400
The order's leverage is too small. 40030 400
The deviation between current price and trigger price is too large. 40031 400
The plan order's life cycle is too long. 40032 400
The plan order's life cycle is too short. 40033 400
The Symbol is not exist 40034 400
The order is not exist 40035 400
The order status is invalid 40036 400
The order id is not exist 40037 400
The k-line step is invalid 40038 400
The timestamp is invalid 40039 400
The order leverage is invalid 40040 400
The order side is invalid 40041 400
The order type is invalid 40042 400
The order precision is invalid 40043 400
The order range is invalid 40044 400
The order open type is invalid 40045 400
The account is not opened futures 40046 403