NAV
Example

Update Plan

Change Log

2024-12-04

REST API

2024-11-28

REST API
Websocket Order

2024-11-25

Websocket Stream

2024-11-01

Websocket Stream

2024-10-29

REST API

2024-10-24

REST API

2024-10-17

REST API

2024-10-10

REST API

2024-09-26

Documentation

2024-09-19

REST API

2024-07-23

Introduction

API Key Create

PNG

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

PNG

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

API Key Permission Settings

PNG

Read-Only Permissions:
API Name Description Authentication Type
/account/v1/wallet Query account assets KEYED
/account/v1/deposit/address Query deposit addresses for each currency KEYED
/account/v2/deposit-withdraw/history Query deposit and withdrawal history KEYED
/account/v1/deposit-withdraw/detail Query deposit and withdrawal details KEYED
/spot/v1/wallet Query wallet balance for all currencies KEYED
/spot/v4/query/order Query order by id (v4) SIGNED
/spot/v4/query/client-order Query order by client order id (v4) SIGNED
/spot/v4/query/open-orders Current open orders (v4) SIGNED
/spot/v4/query/history-orders Account orders (v4) SIGNED
/spot/v4/query/trades Account trade list (v4) SIGNED
/spot/v4/query/order-trades Order trade list(v4) SIGNED
/spot/v1/user_fee Query basic fee rate for current user KEYED
/spot/v1/trade_fee Query fee rate for a specific trading pair for current user KEYED
/spot/v1/margin/isolated/pairs Query loan interest rate and limit for a trading pair KEYED
/spot/v1/margin/isolated/account Query isolated margin account information KEYED
/spot/v1/margin/isolated/borrow_record Query isolated margin borrowing record KEYED
/spot/v1/margin/isolated/repay_record Query isolated margin repayment record KEYED
/contract/private/get-open-orders Query Contract All Open Orders KEYED
/contract/private/order Query contract order details KEYED
/contract/private/trade-fee-rate Query Trade Fee Rate KEYED
/contract/private/order-history Query contract order history KEYED
/contract/private/trades Query contract trade details KEYED
/contract/private/assets-detail Query contract asset details KEYED
/contract/private/position Query position details KEYED
/contract/private/current-plan-order Query Current Plan Orders KEYED
/contract/private/position-risk Query Position Risk 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/v4/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 multiple orders SIGNED
/spot/v4/cancel_orders Cancel multiple orders SIGNED
Margin-Trade Permissions:
API Name Description Authentication Type
/spot/v1/margin/submit_order Margin order placement SIGNED
/spot/v1/margin/isolated/transfer Transfer funds between margin and spot accounts SIGNED
/spot/v1/margin/isolated/borrow Isolated margin borrowing SIGNED
/spot/v1/margin/isolated/repay Repay isolated margin debt SIGNED
Future-Trade Permissions:
API Name Description Authentication Type
/contract/private/submit-order Place an order for a futures contract SIGNED
/contract/private/cancel-order Cancel a single futures order SIGNED
/contract/private/cancel-orders Batch cancel futures orders SIGNED
/contract/private/submit-plan-order Place a batch order for futures contracts SIGNED
/contract/private/cancel-plan-order Batch cancel futures orders SIGNED
/account/v1/transfer-contract Future account transfer SIGNED
/account/v1/transfer-contract-list Get Future account transfer list SIGNED
/contract/private/submit-tp-sl-order Place a tp or sl order for a futures contract SIGNED
/contract/private/modify-plan-order Modify a plan order for a futures contract SIGNED
/contract/private/modify-preset-plan-order Modify a preset plan order for a futures contract SIGNED
/contract/private/modify-tp-sl-order Modify a tp or sl order for a futures contract SIGNED
Sub-Account Permissions:

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

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

PNG

Sub-Account Spot-Trade Permissions:

Same as the above spot trading authority

Sub-Account Contract-Trade Permissions:

Same as above futures trading authority

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

API Library

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

Available SDK:

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

FAQ

Here are some frequently asked questions.

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

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

Q3. How is the HTTP status code 429 created?

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

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

Q6. Where is the location of BitMart servers?

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

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

Contact Us

Basic Information

API Basic Information

  1. This article lists the rest baseurl of the interfaces: https://api-cloud-v2.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.

Endpoints Limit Rules:

Futures Market Endpoints Interface Name Limit Target Rate
/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 Open Interest IP 2 times/2 sec
/contract/public/funding-rate Get Current Funding Rate IP 12 times/2 sec
/contract/public/kline Get K-line IP 12 times/2 sec
Futures Trade Endpoints Interface Name Limit Target Rate
/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/get-open-orders Get Contract All Open Orders X-BM-KEY 50 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/private/submit-leverage Submit Contract Leverage X-BM-KEY 24 times/2 sec
/account/v1/transfer-contract Transfer X-BM-KEY 1 times/2 sec
/account/v1/transfer-contract-list Get Transfer List X-BM-KEY 1 times/2 sec
/contract/private/position-risk Get Position Risk Info X-BM-KEY 24 times/2 sec
Sub-Account Endpoints Interface Name Limit Target Rate
/account/contract/sub-account/main/v1/sub-to-main Sub-Account Transfer to Main-Account (For Main Account, ues futures account) X-BM-KEY 8 times/2s
/account/contract/sub-account/main/v1/main-to-sub Main-Account Transfer to Sub-Account (For Main Account, ues futures account) X-BM-KEY 8 times/2s
/account/contract/sub-account/sub/v1/sub-to-main Sub-Account Transfer to Main-Account (For Sub-Account, ues futures account) X-BM-KEY 8 times/2s
/account/contract/sub-account/main/v1/wallet Get Sub-Account Futures Wallet Balance (For Main Account, ues futures account) X-BM-KEY 12 times/2s
/account/contract/sub-account/v1/transfer-history Get Account Futures Asset Transfer History (For Main/Sub Account, ues futures account) X-BM-KEY 8 times/2s
/account/contract/sub-account/main/v1/transfer-list Get Sub-Account Transfer History (For Main Account, ues futures account) X-BM-KEY 8 times/2s
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 Open Interest 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/get-open-orders Get Contract All Open Orders X-BM-KEY 50 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
/contract/private/current-plan-order Get Contract All Current Plan Orders X-BM-KEY 50 times/2 sec
/contract/private/trade-fee-rate Get Trade Fee Rate X-BM-KEY 2 times/2s
/contract/private/submit-tp-sl-order Submit Contract TP or SL order X-BM-KEY 24 times/2s
/contract/private/modify-plan-order Modify Contract Plan Order X-BM-KEY 24 times/2s
/contract/private/modify-preset-plan-order Modify Contract Preset Plan Order X-BM-KEY 24 times/2s
/contract/private/modify-tp-sl-order Modify Contract TP or SL Order X-BM-KEY 24 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 that have been used 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-v2.bitmart.com/contract/public/details

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud-v2.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": 1594080000123,
        "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",
        "market_max_volume": "500000",
        "min_volume": "1",
        "funding_rate": "0.0001",
        "expected_funding_rate": "0.00011",
        "open_interest": "4134180870",
        "open_interest_value": "94100888927.0433258",
        "high_24h": "23900",
        "low_24h": "23100",
        "change_24h": "0.004",
        "funding_interval_hours": 8
      },
      ...
    ]
  }
}
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 limit order quantity
market_max_volume String Maximum market 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
high_24h String 24h High
low_24h String 24h Low
change_24h String 24h Change
funding_interval_hours Int Funding interval

Get Market Depth

Get full depth of trading pairs.

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud-v2.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
symbol String symbol

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-v2.bitmart.com/contract/public/open-interest

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud-v2.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-v2.bitmart.com/contract/public/funding-rate

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud-v2.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",
    "funding_time": 1709971200000,
    "funding_upper_limit": "0.0375",
    "funding_lower_limit": "-0.0375"
  },
  "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
funding_time Long Next funding settlement time
funding_upper_limit Long Upper limit of funding rate for this trading pair
funding_lower_limit Long Lower limit of funding rate for this trading pair

Get K-line

Applicable for querying K-line data. Single time request size upper limit 500

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud-v2.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"
    },
    {
      "timestamp": 1662518161,
      "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-v2.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-v2.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 Trade Fee Rate (KEYED)

Applicable for querying trade fee rate

Request URL

GET https://api-cloud-v2.bitmart.com/contract/private/trade-fee-rate

Request Limit

See Detailed Rate Limit

Request Parameter

Request

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

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "symbol": "BTCUSDT",
    "taker_fee_rate": "0.0006",
    "maker_fee_rate": "0.0002"
  },
  "trace": "638d5048-ad21-4a4b-1234-d0756fbfc7ba"
}
Field Type Description
symbol String Symbol of the contract
taker_fee_rate String Taker fee rate
maker_fee_rate String Maker fee rate

Get Order Detail (KEYED)

Applicable for querying contract order detail

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.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",
    "client_order_id": "BM123",
    "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
client_order_id String Client-defined OrderId (If the field is not defined, a empty string is returned)
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
-adl
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
-1=status_approval
-2=status_check
-4=status_finish
activation_price String Activation price, returned at trailing order
callback_rate String Callback rate, returned at trailing order
activation_price_type Int Activation price type, returned at trailing order
-1=last_price
-2=fair_price
preset_take_profit_price_type Int Pre-set TP price type
-1=last_price
-2=fair_price
preset_stop_loss_price_type Int Pre-set SL price type
-1=last_price
-2=fair_price
preset_take_profit_price String Pre-set TP price
preset_stop_loss_price String Pre-set SL price
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-v2.bitmart.com/contract/private/order-history

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.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",
    "client_order_id": "BM123",
    "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
client_order_id String Client-defined OrderId (If the field is not defined, a empty string is returned)
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
- adl
- trailing
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
activation_price String Activation price, returned at trailing order
callback_rate String Callback rate, returned at trailing order
activation_price_type Int Activation price type, returned at trailing order
-1=last_price
-2=fair_price
executive_order_id String Activation Execute Order ID
preset_take_profit_price_type Int Pre-set TP price type
-0=unset
-1=last_price
-2=fair_price
preset_stop_loss_price_type Int Pre-set SL price type
-0=unset
-1=last_price
-2=fair_price
preset_take_profit_price String Pre-set TP price
preset_stop_loss_price String Pre-set SL price
create_time Long Create time
update_time Long Update time

Get All Open Orders (KEYED)

Applicable for querying contract all open orders

Request URL

GET https://api-cloud-v2.bitmart.com/contract/private/get-open-orders

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.bitmart.com/contract/private/get-open-orders?symbol=BTCUSDT&order_state=partially_filled&type=market&limit=10
Field Type Required? Description
symbol String No Symbol of the contract(like BTCUSDT)
type string No Order type
-limit
- market
- trailing
order_state string No Order state
-all(default)
- partially_filled
limit int No The number of returned results, with a maximum of 100 and a default of 100

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": [
    {
      "order_id": "220908185908509",
      "client_order_id": "BM123",
      "price": "14277",
      "size": "7216",
      "symbol": "BTCUSDT",
      "state": 4,
      "side": 3,
      "type": "limit",
      "leverage": "0",
      "open_type": "isolated",
      "deal_avg_price": "14277",
      "deal_size": "7216",
      "preset_take_profit_price_type": 1,
      "preset_stop_loss_price_type": 2,
      "preset_take_profit_price": "68000",
      "preset_stop_loss_price": "60000",
      "create_time": 1662368173000,
      "update_time": 1662368173000
    }
  ],
  "trace": "80ba1f07-1b6f-46ad-81dd-78ac7e9bbccd"
}
Field Type Description
symbol String Symbol of the contract
order_id String Order ID
client_order_id String Client-defined OrderId (If the field is not defined, a empty string is returned)
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
- trailing
size String Order amount
leverage String Leverage order multipliers
String 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
activation_price String Activation price, returned at trailing order
callback_rate String Callback rate, returned at trailing order
activation_price_type Int Activation price type, returned at trailing order
-1=last_price
-2=fair_price
preset_take_profit_price_type Int Pre-set TP price type
-1=last_price
-2=fair_price
preset_stop_loss_price_type Int Pre-set SL price type
-1=last_price
-2=fair_price
preset_take_profit_price String Pre-set TP price
preset_stop_loss_price String Pre-set SL price
create_time Long Create time
update_time Long Update time

Get All Current Plan Orders (KEYED)

Applicable for querying contract all plan orders

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.bitmart.com/contract/private/current-plan-order?symbol=BTCUSDT&type=market&limit=10
Field Type Required? Description
symbol String No Symbol of the contract(like BTCUSDT)
type String No Order type
-limit
- market
limit int No The number of returned results, with a maximum of 100 and a default of 100
plan_type String No Plan order type
-plan
- profit_loss
default all

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": [
    {
      "order_id": "220908185908509",
      "client_order_id": "BM123",
      "executive_price": "14277",
      "trigger_price": "14277",
      "size": "7216",
      "symbol": "BTCUSDT",
      "state": 4,
      "side": 3,
      "mode": 1,
      "price_way": 2,
      "price_type": 1,
      "plan_category": 2,
      "type": "stop_loss",
      "leverage": "0",
      "open_type": "isolated",
      "create_time": 1662368173000,
      "update_time": 1662368173000
    }
  ],
  "trace": "80ba1f07-1b6f-46ad-81dd-78ac7e9bbccd"
}
Field Type Description
symbol String Symbol of the contract
order_id String Order ID
client_order_id String Client-defined OrderId (If the field is not defined, a empty string is returned)
side Int Order side
-1=buy_open_long
-2=buy_close_short
-3=sell_close_long
-4=sell_open_short
type String Order type
- plan
- take_profit
- stop_loss
plan_category Int TP/SL type
- 1=TP/SL
- 2=Position TP/SL
size String Order amount
leverage String Leverage order multipliers
open_type String Open type
-cross
-isolated
executive_price String Executive price
trigger_price String Trigger price
state Int Order status
-1=status_approval
-2=status_check
preset_take_profit_price_type Int Pre-set TP price type
-1=last_price
-2=fair_price
preset_stop_loss_price_type Int Pre-set SL price type
-1=last_price
-2=fair_price
preset_take_profit_price String Pre-set TP price
preset_stop_loss_price String Pre-set SL price
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-v2.bitmart.com/contract/private/position

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.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_value": "16673.27053207877",
      "mark_price": "93000.50",
      "position_value": "18584.272343943943943944339",
      "position_cross": "3798.397624451826977945",
      "maintenance_margin": "4798.397624451826977945",
      "margin_type":"Isolated",
      "close_vol": "100",
      "close_avg_price": "20700.7",
      "open_avg_price": "20200",
      "entry_price": "20201",
      "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 Position value based on last price
mark_value String Position value based on mark price
mark_price String mark price
position_value String Position value based on entry price
open_avg_price String Open average price
close_avg_price String Close average price
entry_price String Average entry price of the position
close_vol String Close volume
position_cross String Margin calls to positions
maintenance_margin String Maintenance Margin
margin_type String Margin type of the position
-Cross
-Isolated
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 Current Position Risk Details(KEYED)

Applicable for checking the position risk details a specified contract

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.bitmart.com/contract/private/position-risk?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",
      "position_amt":"1",
      "mark_price":"67957.7",
      "unrealized_profit":"969.6",
      "liquidation_price":"64245",
      "leverage":"20",
      "max_notional_value":"3000000",
      "margin_type":"Isolated",
      "isolated_margin":"3078.51948691",
      "position_side":"Long",
      "notional":"66988.1",
      "update_time":1712390438}
  ],
  "trace": "ae96cae5-1f09-4ea5-971e-4474a6724bc8"
}
字段 类型 描述
symbol String Symbol of the contract(like BTCUSDT)
position_amt String Position amount
mark_price String Mark Price of the contract
unrealized_profit String Unrealized profit of the position
liquidation_price String LiquidationPrice of the position
leverage String Position leverage
max_notional_value String Maximum notional value for the current risk level
margin_type String Margin type of the position
-Cross
-Isolated
isolated_margin String Margin for the isolated position
position_side String Position side
-Long
-Short
notional String notional = position_amt*mark_Price
update_time Long Unix timestamp in milliseconds for when the last updated time occurred

Get Order Trade (KEYED)

Applicable for querying contract order trade detail

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.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-v2.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-v2.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-v2.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",
  "client_order_id":"BM1234",
  "side":4,
  "mode":1,
  "type":"limit",
  "leverage":"1",
  "open_type":"isolated",
  "size":10,
  "price":"2000"
}'
https://api-cloud-v2.bitmart.com/contract/private/submit-order
Field Type Required? Description
symbol String Yes Symbol of the contract(like BTCUSDT)
client_order_id String No Client-defined OrderId(A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters)
type String No Order type
-limit(default)
-market
-trailing
side Int Yes Order side
-1=buy_open_long
-2=buy_close_short
-3=sell_close_long
-4=sell_open_short
leverage String No Order leverage
open_type String No 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 (Number of contracts)
activation_price String No Activation price, required at trailing order
callback_rate String No Callback rate, required at trailing order, min 0.1, max 5 where 1 for 1%
activation_price_type Int No Activation price type, required at trailing order
-1=last_price
-2=fair_price
preset_take_profit_price_type Int No Pre-set TP price type
-1=last_price(default)
-2=fair_price
preset_stop_loss_price_type Int No Pre-set SL price type
-1=last_price(default)
-2=fair_price
preset_take_profit_price String No Pre-set TP price
preset_stop_loss_price String No Pre-set SL price

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "order_id": 220609666322019,
    "price": "25637.2"
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}
Field Type Description
order_id Int Order ID
price String Order Submit Price,if submit market type order,will return string:"market price"

Cancel Order (SIGNED)

Applicable for canceling a specific contract order

Request URL

POST https://api-cloud-v2.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-v2.bitmart.com/contract/private/cancel-order
Field Type Required? Description
symbol String Yes Symbol of the contract(like BTCUSDT),(If not submitted order_id and client_order_id, cancel all orders under the symbol)
order_id String No Order ID
client_order_id String No Client-defined OrderId

Response Data

If code value is 1000, it means the order cancellation is successfully submitted, cancellation results will be pushed by websocket service.

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-v2.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-v2.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 cancellation is successfully submitted, cancellation results will be pushed by websocket service.

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-v2.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-v2.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
-take_profit
-stop_loss
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 (Number of contracts)
trigger_price String Yes Trigger price
executive_price String No Execution price for plan order, mandatory when type = limit
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
plan_category Int No TP/SL type
-1=TP/SL
-2=Position TP/SL
preset_take_profit_price_type Int No Pre-set TP price type
-1=last_price(default)
-2=fair_price
preset_stop_loss_price_type Int No Pre-set SL price type
-1=last_price(default)
-2=fair_price
preset_take_profit_price String No Pre-set TP price
preset_stop_loss_price String No Pre-set SL price

Response Data

Response

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

Cancel Plan Order (SIGNED)

Applicable for canceling a specific contract plan order

Request URL

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

Response Data

If code value is 1000, it means the order cancellation is successfully submitted, cancellation results will be pushed by websocket service.

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

Submit Leverage (SIGNED)

Applicable for adjust contract leverage `

Request URL

POST https://api-cloud-v2.bitmart.com/contract/private/submit-leverage

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",
  "leverage":"5",
  "open_type":"isolated"
}'
https://api-cloud-v2.bitmart.com/contract/private/submit-leverage
Field Type Required? Description
symbol String Yes Symbol of the contract(like BTCUSDT)
leverage String No Order leverage
open_type String Yes Open type, required at close position
-cross
-isolated

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "symbol":"ETHUSDT",
    "leverage":"5",
    "open_type":"isolated",
    "max_value":"100"
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}
Field Type Description
symbol String Symbol of the contract(like BTCUSDT)
leverage String Order leverage
open_type String Open type, required at close position
-cross
-isolated
max_value String Maximum leverage

Submit TP/SL Order (SIGNED)

Applicable for placing contract TP/SL orders

Request URL

POST https://api-cloud-v2.bitmart.com/contract/private/submit-tp-sl-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":2,
  "type":"take_profit",
  "size":10,
  "trigger_price":"2000",
  "executive_price":"1450",
  "price_type":1,
  "plan_category":1,
  "client_order_id":"123456789",
  "category":"limit"
}'
https://api-cloud-v2.bitmart.com/contract/private/submit-plan-order
Field Type Required? Description
symbol String Yes Symbol of the contract(like BTCUSDT)
type String Yes Order type
-take_profit
-stop_loss
side Int Yes Order side
-2=buy_close_short
-3=sell_close_long
size Int No Order size (Number of contracts) Default the size of position
trigger_price String Yes Trigger price
executive_price String Yes Execution price
price_type Int Yes Trigger price type
-1=last_price
-2=fair_price
plan_category Int No TP/SL type
-1=TP/SL
-2=Position TP/SL(default)
client_order_id String No Client-defined OrderId(A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters)
category String No Trigger order type, position TP/SL default market
-limit
-market

Response Data

Response

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

Modify Plan Order (SIGNED)

Applicable for modifying contract plan orders

Request URL

POST https://api-cloud-v2.bitmart.com/contract/private/modify-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",
  "trigger_price":"2000",
  "executive_price":"1450",
  "price_type":1,
  "type":"limit"
}'
https://api-cloud-v2.bitmart.com/contract/private/modify-plan-order
Field Type Required? Description
symbol String Yes Symbol of the contract(like BTCUSDT)
order_id String No Order ID(order_id or client_order_id must give one)
trigger_price String Yes Trigger price
executive_price String No Execution price for plan order, mandatory when type = limit
price_type Int Yes Trigger price type
-1=last_price
-2=fair_price
type String Yes Order type
-limit
-market

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

Modify Preset Plan Order (SIGNED)

Applicable for modifying contract preset plan orders

Request URL

POST https://api-cloud-v2.bitmart.com/contract/private/modify-preset-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":"220609666322019",
  "preset_take_profit_price":"2000",
  "preset_stop_loss_price":"1900",
  "preset_take_profit_price_type":1,
  "preset_stop_loss_price_type":1
}'
https://api-cloud-v2.bitmart.com/contract/private/modify-preset-plan-order
Field Type Required? Description
order_id String Yes Order ID
symbol String Yes Symbol of the contract(like BTCUSDT)
preset_take_profit_price_type Int No Pre-set TP price type
-1=last_price(default)
-2=fair_price
preset_stop_loss_price_type Int No Pre-set SL price type
-1=last_price(default)
-2=fair_price
preset_take_profit_price String No Pre-set TP price
preset_stop_loss_price String No Pre-set SL 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

Modify TP/SL Order (SIGNED)

Applicable for modifying TP/SL orders

Request URL

POST https://api-cloud-v2.bitmart.com/contract/private/modify-tp-sl-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",
  "trigger_price":"2100",
  "executive_price":"2100",
  "price_type":2,
  "order_id":"37758000001",
  "client_order_id":"",
  "plan_category":2,
  "category": "limit"
}'
https://api-cloud-v2.bitmart.com/contract/private/modify-tp-sl-order
Field Type Required? Description
symbol String Yes Symbol of the contract(like BTCUSDT)
order_id String No Order ID(order_id or client_order_id must give one)
client_order_id String No Client order ID(order_id or client_order_id must give one)
trigger_price String Yes Trigger price
executive_price String No Execution price for order, mandatory when plan_category = 1
price_type Int Yes Trigger price type
-1=last_price
-2=fair_price
plan_category Int No TP/SL type
-1=TP/SL
-2=Position TP/SL
category String No Order type, Position TP/SL default market
-limit
-market

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

Sub-Account

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

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

Request URL

POST https://api-cloud-v2.bitmart.com/account/contract/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":"USDT",
    "subAccount":"[email protected]"
}'
https://api-cloud-v2.bitmart.com/account/contract/sub-account/main/v1/sub-to-main`
Field Type Required? Description
requestNo String Yes UUID,unique identifier, max length 64
amount String Yes Transfer amount
currency String Yes Currently only USDT is supported
subAccount String Yes Sub-Account username

Response Data

Response

{
  "message": "OK",
  "code": 1000,
  "trace": "c1e4e99ff0ec452f8b8bc5f1eb38d733.76.16861963186213159",
  "data": {}
}

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

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

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

Request URL

POST https://api-cloud-v2.bitmart.com/account/contract/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-v2.bitmart.com/account/contract/sub-account/main/v1/main-to-sub`
Field Type Required? Description
requestNo String Yes UUID,unique identifier, max length 64
amount String Yes Transfer amount
currency String Yes Currently only USDT is supported
subAccount String Yes Sub-Account username

Response Data

Response

{
  "message": "OK",
  "code": 1000,
  "trace": "c1e4e99ff0ec452f8b8bc5f1eb38d733.76.16861963186213159",
  "data": {}
}

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

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

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

Request URL

POST https://api-cloud-v2.bitmart.com/account/contract/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":"USDT"
}'
https://api-cloud-v2.bitmart.com/account/contract/sub-account/sub/v1/sub-to-main`
Field Type Required? Description
requestNo String Yes UUID,unique identifier, max length 64
amount String Yes Transfer amount
currency String Yes Currently only USDT is supported

Response Data

Response

{
  "message": "OK",
  "code": 1000,
  "trace": "c1e4e99ff0ec452f8b8bc5f1eb38d733.76.16861970092723253",
  "data": {}
}

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

Get Sub-Account Futures Wallet Balance (For Main Account) (KEYED)

Get Sub-Account futures wallet balance (For Main Account) (KEYED)

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.bitmart.com/account/contract/sub-account/main/v1/wallet?subAccount=[email protected]&currency=USDT
Field Type Required? Description
subAccount String Yes Sub-Account username
currency String No currency

Response Data

Response

{
  "message": "OK",
  "code": 1000,
  "trace": "87db8cd43374470f96aacb0e3fcaf34c.77.16872314088656435",
  "data": {
    "wallet": [
      {
        "currency": "USDT",
        "name": "USDT",
        "available": "204.15216696",
        "frozen": "0.00000000"
      }
    ]
  }
}
Field Type Description
currency String Token symbol, e.g., 'BTC'
name String Token name, e.g., 'Bitcoin'
available String Available Balance
frozen String Frozen Balance

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

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

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.bitmart.com/account/contract/sub-account/main/v1/transfer-list?subAccount=[email protected]&limit=10
Field Type Required? Description
subAccount String Yes Sub-Account username
limit Int Yes Recent N records, allowed range[1,100]

Response Data

Response

{
  "message": "OK",
  "code": 1000,
  "trace": "ba950ec2bd114fd7bc069cb812b0129f.62.16887213774200649",
  "data": [
    {
      "fromAccount": "[email protected]",
      "toAccount": "[email protected]",
      "toWalletType": "future",
      "fromWalletType": "future",
      "currency": "USDT",
      "amount": "1",
      "submissionTime": 1686207254
    }
  ]
}
Field Type Description
fromAccount String Transfer out Sub-Account username
fromWalletType String Transfer out wallet type
-future=futures wallet
toAccount String Transfer to Sub-Account username
toWalletType String Transfer to wallet type
-future=futures wallet
currency String currency
amount String Transfer amount
submissionTime Long The request timestamp is accurate to seconds(UTC-0)

Get Account Futures Asset Transfer History (For Main/Sub Account) (KEYED)

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

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.bitmart.com/account/contract/sub-account/v1/transfer-history?limit=10
Field Type Required? Description
limit Int Yes Recent N records, allowed range[1,100]

Response Data

Response

{
  "message": "OK",
  "code": 1000,
  "trace": "ba950ec2bd114fd7bc069cb812b0129f.62.16887215218140681",
  "data": [
    {
      "fromAccount": "[email protected]",
      "toAccount": "[email protected]",
      "toWalletType": "future",
      "fromWalletType": "future",
      "currency": "USDT",
      "amount": "1",
      "submissionTime": 1686207254
    }
  ]
}
Field Type Description
fromAccount String Transfer out Sub-Account username
fromWalletType String Transfer out wallet type
-future=futures wallet
toAccount String Transfer to Sub-Account username
toWalletType String Transfer to wallet type
-future=futures wallet
currency String currency
amount String Transfer amount
submissionTime Long The request timestamp is accurate to seconds(UTC-0)

WebSocket Subscription

Overview

Server URL

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

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

Format

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

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

Explain:

Example:


Successful Response Format

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

Return success field is ture

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

Example:


Failed Response Format

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

Return success field is false

Failed Response Format

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

Stay Connected And Limit

How Stay Connected

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

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

  1. After each message is received, the user sets a timer for N seconds (N<20).
  2. If the timer is triggered (no new message is received within N seconds), send a ping frame or send a string 'ping'.
  3. Expect for a text string 'pong' as a response. If not received within N seconds, please issue an error or reconnect.
  4. We do not actively disconnect when there is a continuous message interaction between the two parties.

The following is the data format of ping: (Example in Java pseudocode)

ws.send(new PingWebSocketFrame());

ws.send(new TextWebSocketFrame('{"action":"ping"}'));

Connection Limit

Lifeless connection

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

Subscription

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

Subscribe Message Format

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

Parameter Instructions

Example

  1. Send message to BitMart server

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

  2. The BitMart server returns the subscription result, success=true means the subscription is successful

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

Unsubscribe

Cancel subscription to one or more channels

Unsubscribe Message Format

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

Parameter Instruction

Example

  1. Send message to BitMart server

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

  2. The BitMart server returns the subscription result, success=true means the subscription is successful

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

Pushing Rules

  1. No user login required
  2. After subscribing, then the changes will be pushed
  3. Sent once in 1 second after subscription

Request

Request

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

Message Format:

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

Response

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",
          "ask_vol": "1",
          "bid_price": "142.11",
          "bid_vol": "1"
        }
}

Return data description:

Field 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
ask_vol String Sell depths first vol
bid_price String Buy depths first price
bid_vol String Buy depths first vol

【Public】Funding Rate Channel

Return funding Rate data

Pushing Rules

  1. No user login required
  2. After subscribing, the current data will be returned directly, and updates will be pushed every minute.

Request

Subscribe Request

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

Funding rate data Request

{ 
  "action": "request", 
  "args":["futures/fundingRate:BTCUSDT"]
}

Message Format:

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

Response

Funding rate data

{
    "data": {
        "symbol": "BTCUSDT",
        "fundingRate": "0.000098800809",
        "fundingTime": 1732525864000,
        "nextFundingRate": "0.0000947",
        "nextFundingTime": 1732550400000,
        "funding_upper_limit": "0.0375",
        "funding_lower_limit": "-0.0375",
        "ts": 1732525864601
    },
    "group": "futures/fundingRate:BTCUSDT"
}

Return data description:

Field Type Description
symbol String Symbol of the contract (like BTCUSDT)
fundingRate String Current funding rate
fundingTime Long Funding time of the upcoming settlement, Unix timestamp format in milliseconds
nextFundingRate String Forecasted funding rate for the next period
nextFundingTime Long Forecasted funding time for the next period, Unix timestamp format in milliseconds
funding_upper_limit String The upper limit of the predicted funding rate of the next cycle
funding_lower_limit String The lower limit of the predicted funding rate of the next cycle
ts Long Data return time, Unix timestamp format in milliseconds

【Public】Depth Channel

Get depth data

Pushing Rules

  1. No user login required
  2. After subscribing, then the changes will be pushed

Request

Request

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

Message Format:

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

Parameters Channel Name List

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

Response

Response

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

Return data description:

Field Type Description
symbol String Symbol of the contract(like BTCUSDT)
way Long Trading side
-1=bid
-2=ask
depths List Array of depth details
ms_t Long Timestamp (in millisecond)

Instruction

Description of the depths details field:

Field Type Description
price String price
vol String volume

【Public】Depth-All Channel

Return depth data, each push is the full data

Pushing Rules

  1. No user login required
  2. After subscribing, then the changes will be pushed

Request

Request

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

Message Format:

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

Parameters Channel Name List

Channel Name Description
futures/depthAll5 5 Level Depth Channel
futures/depthAll20 20 Level Depth Channel
futures/depthAll50 50 Level Depth Channel

Response

Response

{
    "data": {
        "symbol": "BTCUSDT",
        "asks": [
            {
                "price": "70294.4",
                "vol": "455"
            }
        ],
        "bids": [
            {
                "price": "70293.9",
                "vol": "1856"
            }
        ],
        "ms_t": 1730399750402
    },
    "group": "futures/depthAll20:BTCUSDT"
}

Return data description:

Field Type Description
symbol String Symbol of the contract(like BTCUSDT
asks List Asks Depth Array
bids List Bids Depth Array
ms_t Long Timestamp (in millisecond)

Instruction Description of the asks bids details field:

Field Type Description
price String price
vol String volume

【Public】Depth-Increase Channel

Return depth data, support the creation of a local full depth cache data

Pushing Rules

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

Request

Subscribe Request

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

Full depth snapshot data Request

{ 
  "action": "request", 
  "args":["futures/depthIncrease20:BTCUSDT"]
}

Message Format:

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

Parameters Channel Name List

Channel Name Description
futures/depthIncrease5 5 Level Depth Channel
futures/depthIncrease20 20 Level Depth Channel
futures/depthIncrease50 50 Level Depth Channel

Response

Full depth snapshot data

{
    "data": {
        "symbol": "BTCUSDT",
        "asks": [
            {
                "price": "70391.6",
                "vol": "3550"
            }
        ],
        "bids": [
            {
                "price": "70391.2",
                "vol": "1335"
            }
        ],
        "ms_t": 1730400086184,
        "version": 980361,
        "type": "snapshot"
    },
    "group": "futures/depthIncrease20:BTCUSDT"
}

Incremental depth data

{
    "data": {
        "symbol": "BTCUSDT",
        "asks": [
            {
                "price": "70395.3",
                "vol": "341"
            },
            {
                "price": "70395.4",
                "vol": "323"
            }
        ],
        "bids": [
            {
                "price": "70391.2",
                "vol": "0"
            },
            {
                "price": "70353.4",
                "vol": "11435"
            }
        ],
        "ms_t": 1730400086194,
        "version": 980362,
        "type": "update"
    },
    "group": "futures/depthIncrease20:BTCUSDT"
}

Return data description:

Field Type Description
symbol String Symbol of the contract (like BTCUSDT)
asks List Asks Depth Array
bids List Bids Depth Array
ms_t Long Timestamp (in millisecond)
version Long data version
type String data type
-snapshot=Full depth snapshot data
-update=Incremental depth data

Instruction

Description of the asks bids details field:

Field Type Description
price String price
vol String volume

How to correctly maintain a copy of OrderBook locally:

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

【Public】Trade Channel

Get trade data

Pushing Rules

  1. No user login required
  2. After subscribing, then the changes will be pushed

Request

Request

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

Message Format:

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

Response

Response

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

Return data description:

Field Type Description
symbol String symbol
deal_price String deal price
trade_id Long trade id
deal_vol String deal vol
way int Trading type
-1=buy_open_long sell_open_short
-2=buy_open_long sell_close_long
-3=buy_close_short sell_open_short
-4=buy_close_short sell_close_long
-5=sell_open_short buy_open_long
-6=sell_open_short buy_close_short
-7=sell_close_long buy_open_long
-8=sell_close_long buy_close_short
created_at String create time

【Public】klineBin Channel

Get individual contract K-line data

Pushing Rules

  1. No user login required
  2. After subscribing, then the changes will be pushed

Request

Request

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

Message Format:

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

Parameters Channel Name 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

Response

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

Return data description:

Field 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
ts Int64 Timestamp

【Private】Login

Login Subscription Format

Request Format

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

Please note that the following parameters are all of type String

Example

Login 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:

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

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

The final login parameters are:

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

Note

【Private】Assets Channel

Get asset balance change

Pushing Rules

  1. User login required
  2. After subscribing, then the changes will be pushed

Request

Request

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

Message Format:

{"action":"subscribe","args":["<channel:currency>","<channel:currency>"]}

Response

Response

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

Return data description:

Field Type Description
currency String Currency
available_balance String Available Amount
position_deposit String Position Margin
frozen_balance String Transaction Frozen Amount

【Private】Position Channel

Get Position Data

Pushing Rules

  1. User login required
  2. After subscribing, then the changes will be pushed
  3. 10 seconds timed push

Request

Request

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

Message Format:

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

Response

Response

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

Return data description:

Field 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 Long Create time
update_time Long Update time

【Private】Order Channel

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

Pushing Rules

  1. User login required
  2. After subscribing, then the changes will be pushed

Request

Request

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

Message Format:

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

Response

Response

{
  "group": "futures/order",
  "data": [
    {
      "action": 3,
      "order": {
        "order_id": "220906179895578",
        "client_order_id": "BM1234",
        "price": "1",
        "size": "1000",
        "symbol": "BTCUSDT",
        "state": 2,
        "side": 1,
        "type": "limit",
        "leverage": "5",
        "open_type": "isolated",
        "deal_avg_price": "0",
        "deal_size": "0",
        "create_time": 1662368173000,
        "update_time": 1662368173000,
        "plan_order_id": "220901412155341",
        "last_trade": {
          "lastTradeID": 1247592391,
          "fillQty": "1",
          "fillPrice": "25667.2",
          "fee": "-0.00027",
          "feeCcy": "USDT"
        },
        "trigger_price": "-",
        "trigger_price_type": "-",
        "execution_price": "-",
        "activation_price_type": "-",
        "activation_price": "-",
        "callback_rate": "-"
      }
    }
  ]
}

Return data description:

Field Type Description
action Int Action
-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
client_order_id String Client-defined OrderId
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
-plan_order
-trailing_order
-take_profit
-stop_loss
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
-1=status_approval
-2=status_check
-4=status_finish
create_time Long Create time
update_time Long Update time
plan_order_id String Trigger plan order id
last_trade object recently trade info for this order,return null if not exist
trigger_price String Trigger price of TP/SL / plan order
trigger_price_type String Trigger price type of TP/SL / plan order
-last_price
-fair_price
execution_price String Execution price of TP/SL / plan order
activation_price String Activation price
activation_price_type String Activation price type
-last_price
-fair_price
callback_rate String Call back rate of trailing stop order

market - market order execution

limit order price - limit order execution | | activation_price | String | recently trade info for this order,return null if not exist | | activation_price_type | String | Activation type
-last_price
-fair_price | | callback_rate | String | recently trade info for this order,return null if not exist |

Recently trade fields describe:

Parameter Type Description
lastTradeID Long recently trade id
fillQty String last trade deal vol
fillPrice String last trade deal price
fee String last trade fee
feeCcy String last trade fee coin name

Futures Affiliate Endpoints

Get Futures Rebate List(KEYED)

Used for API affiliates to query contract rebate records within a certain time range

Request URL

GET https://api-cloud-v2.bitmart.com/contract/private/affiliate/rebate-list

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud-v2.bitmart.com/contract/private/affiliate/rebate-list?page=1&size=10&currency=USDT
Field Type Required Description
user_id Long No user ID
page Int Yes Page number
size Int Yes Number of records per page
currency String Yes query currency
rebate_start_time Long No Query rebate start timestamp
rebate_end_time Long No Query rebate end timestamp
register_start_time Long No Query register start timestamp
register_end_time Long No Query register end timestamp

Response Data

Response

{
  "total": 2,
  "btc_rebate_sum": 0,
  "size": 10,
  "usdt_rebate_sum": 448.9697507148,
  "page": 1,
  "eth_rebate_sum": 0,
  "rebate_detail_page_data": [{
    "rebate_coin": "USDT",
    "trade_user_id": 4225149,
    "total_rebate_amount": 427.1825970576,
    "user_type":1
  }, {
    "rebate_coin": "USDT",
    "trade_user_id": 4225148,
    "total_rebate_amount": 21.7871536572,
    "user_type":1
  }]
}
Field Type Description
btc_rebate_sum Decimal Total BTC rebates
usdt_rebate_sum Decimal Total USDT rebates
eth_rebate_sum Decimal Total ETH rebates
rebate_detail_page_data Object Rebate details
rebate_coin String Currency
trade_user_id Long Trading user ID
total_rebate_amount Decimal Total commission for the user
user_type Int User type
-0=Indirect
-1=Direct

Get Futures Trade List(KEYED)

Used for API affiliates to query contract rebate records within a certain time range

Request URL

GET https://api-cloud-v2.bitmart.com/contract/private/affiliate/trade-list

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl https://api-cloud-v2.bitmart.com/contract/private/affiliate/trade-list?user_id=123456&type=1&page=1&size=10
Field Type Required Description
user_id Long Yes userID
type Int Yes Query type:
-1=U-based
-2=Coin-based
page Int Yes Page number
size Int Yes Number of records per page
start_time Long No Query start timestamp
end_time Long No Query end timestamp

Response Data

Response

{
  "total": 60,
  "size": 10,
  "page": 1,
  "list": [{
    "leverage": 20.000000000000000000,
    "symbol": "BTCUSDT",
    "create_time": 1689933471000,
    "open_type": 2,
    "fee": 0.57162048,
    "deal_price": 29771.900000000000000000,
    "realised_profit": 0,
    "way": 1,
    "deal_vol": 32.000000000000000000,
    "select_copy_trade": 1,
    "user_type": 1,
    "user_id": 10048829,
    "category": 2
  }]
}
Field Type Description
user_id Long userID
user_type Int User Type:
-Direct User
-Indirect User
create_time Long Creation Time
symbol String symbol
leverage Int leverage
select_copy_trade Int Type:
1-Copy Trading
2-Non-Copy Trading
open_type Int Position Type:
-1=Isolated
-2=Cross
way Int Order Direction:
-1=Long
-2=Close Short
-3=Close Long
-4=Short
category Int Order Type:
-1=Limit Order
-2=Market Order
deal_price Decimal Average Deal Price
deal_vol Decimal Deal Volume
fee Decimal fee
realised_profit Decimal Realized Profit and Loss

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
Service maintenance, the function is temporarily unavailable 30016 200
Your account request is temporarily rejected due to violation of current limiting rules, please contact customer service 30017 418
Request Body requires JSON format 30018 503
You do not have the permissions to perform this operation. Please contact customer service or BD for assistance 30019 200
Futures V1 API has been deprecated. Please use Futures V2 API. You can view the change logs for upgrade 30030 200
This endpoint has been deprecated. You can view the change logs for upgrade 30031 200

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
Services is not available in you countries and areas 40047 403
ClientOrderId only allows a combination of numbers and letters 40048 403
The maximum length of clientOrderId cannot exceed 32 40049 403
Client OrderId duplicated with existing orders 40050 403