Update Plan

• The V1 OpenAPI service for futures trading will be fully discontinued on 2024-11-30. Please use the V2 OpenAPI for future trading.
  • The domain name https://api-cloud.bitmart.com will not provide Futures 1.0 HTTP services. Please use the domain name https://api-cloud-v2.bitmart.com to access Futures 2.0 HTTP services
  • The domain name wss://openapi-ws.bitmart.com will not provide Futures 1.0 Websocket services. Please use the domain name wss://openapi-ws-v2.bitmart.com to access Futures 2.0 Websocket services

Change Log

2024-11-01

Websocket Stream

• [New] [Public] Full-depth Channel
  • Supports full-depth simultaneous push
• [New] [Public] Incremental Depth Push Channel
  • Supports incremental depth push

2024-10-29

REST API

• [Update] /contract/public/kline Get K-line
  • Single time request size upper limit 500

2024-10-24

REST API

• [Update] /contract/public/details Get Contract Details
  • Add new response field market_max_volume

2024-10-17

REST API

• [New] /contract/private/trade-fee-rate Support querying trade fee rate(KEYED)
  • Feature：Support querying trade fee rate
• [Update] /contract/public/funding-rate Get Current Funding Rate
  • Update rate limit from 2 times/2 sec to 12 times/2 sec
• [Update] /contract/public/details Get Contract Details
  • Add new response field funding_interval_hour
  • Support get funding interval

2024-10-10

REST API

• [Update] /contract/private/submit-tp-sl-order Support replacing contract TP/SL orders(SIGNED)
  • Change the default value of field plan_category to 2-Position TP/SL

2024-09-26

Documentation

• [Deleted] Futures 1.0 documentation

2024-09-19

REST API

• [New] /contract/private/submit-tp-sl-order Support replacing contract TP/SL orders(SIGNED)
  • Feature：Support replacing contract TP/SL orders
• [New] /contract/private/modify-plan-order Support modifying contract plan orders(SIGNED)
  • Feature：Support modifying contract plan orders
• [New] /contract/private/modify-preset-plan-order Support modifying contract preset plan orders(SIGNED)
  • Feature：Support modifying contract preset plan orders
• [New] /contract/private/modify-tp-sl-order Support modifying contract TP/SL orders(SIGNED)
  • Feature：Support modifying contract TP/SL orders
• [Update] /contract/private/cancel-order Cancel a single futures order
  • Add new request field client_order_id
  • Support batch cancel orders by symbol
• [Update] /contract/private/cancel-plan-order Cancel Plan Order
  • Add new request field client_order_id
  • Support batch cancel orders by symbol
• [Update] /contract/private/current-plan-order Get All Current Plan Orders
  • Add new request field plan_type

2024-07-23

• Add a new endpoint named current-plan-order
  • /contract/private/current-plan-ordersupport query contract all current plan orders（TP/SL、plan）
• New endpoints for trading
  • /contract/private/submit-leverageSubmit Leverage (SIGNED)
• New endpoints for Sub-Account
  • /account/contract/sub-account/main/v1/transfer-listGet Sub-Account Transfer History (For Main Account）(KEYED)
  • /account/contract/sub-account/v1/transfer-historyGet Account Futures Asset Transfer History (For Main/Sub Account）(KEYED)
• New endpoints for Sub-Account
  • /account/contract/sub-account/main/v1/sub-to-mainSub-Account to Main-Account (For Main Account) (SIGNED)
  • /account/contract/sub-account/main/v1/main-to-subMain-Account to Sub-Account (For Main Account) (SIGNED)
  • /account/contract/sub-account/sub/v1/sub-to-mainSub-Account to Main-Account (For Sub-Account) (SIGNED)
  • /account/contract/sub-account/main/v1/walletGet Sub-Account Futures Wallet Balance (For Main Account) (KEYED)
• New endpoints for order
  • /contract/private/get-open-ordersGet All Open Orders (KEYED)
• New endpoints for transfer
  • /account/v1/transfer-contractGet Transfer List (SIGNED)
  • /account/v1/transfer-contract-listTransfer (SIGNED)
• New endpoints for websocket order notify
  • /contract/public/websocket/order
• New endpoints for trading
  • /contract/private/submit-plan-orderSubmit Plan Order (SIGNED)
  • /contract/private/cancel-plan-orderCancel Plan Order (SIGNED)
• New endpoints for trading
  • /contract/private/orders-historyGet Order History (KEYED)
  • /contract/private/tradesGet Order Trade (KEYED)
  • /contract/private/positionGet Current Position (KEYED)
• New endpoints for Futures Market Data
  • /contract/public/klineGet K-line
  • /contract/public/funding-rateGet Current Funding Rate
• New endpoints for Futures Account Data
  • /contract/private/assets-detailGet Contract Assets (KEYED)
• New websocket for public data
  • /contract/public/websocket
• New endpoints for get current funding rate of a specified contract
  • /contract/public/open-interest
• New endpoints for Futures Market Data
  • /contract/public/detailsGet Contract Details
  • /contract/public/depthGet Market Depth

Introduction

API Key Create

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

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

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

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

API Key Permission Settings

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

Read-Only Permissions:

Withdraw Permissions:

Spot-Trade Permissions:

Margin-Trade Permissions:

Future-Trade Permissions:

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.

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

• Java
• Python
• Nodejs
• Go
• PHP

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.

• Python Signature Example
• Go Signature Example
• Nodejs Signature Example
• Java Signature Example
• PHP Signature Example
• Ruby Signature Example
• C# Signature Example
• Rust Signature Example
• C++ Signature Example
• Postman

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

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

Basic Information

API Basic Information

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

Request Parameter Settings

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

HTTP Response Codes

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

API Returned Codes

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

For details, please refer to Error Code List

Signature

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

Authentication Type

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

1. Setting Request Parameters

1.1 Set Request Header Key

Create X-BM-TIMESTAMP

// Java
System.currentTimeMillis();

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

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

// Nodejs & TypeScript
Date.now();

// Javascript
Date.now();

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

// C#
DateTimeOffset.UtcNow.ToUnixTimeMilliseconds()

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

1.2 Set Request Body Params

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

2. Example

Shell Example

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

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

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

Then set the following:

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

Assuming the key you applied for is as follows:

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

then the right side is a complete request

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

Rate Limit

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

Endpoints Limit Rules:

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

Futures Public API Definitions

Field description

Field description

• symbol is the name of the trading pair, consisting of the trading currency and the quote currency. Taking BTCUSDT as an example, BTC is the transaction currency, USDT is the pricing currency, and the transaction pair is mainly used in contract transactions
• order_id order number, the order ID of the same currency pair of each business line is unique

Order State（Field:state)

• 2=status_check
• 4=status_finish

Order Side（Field:side)

• 1=buy_open_long
• 2=buy_close_short
• 3=sell_close_long
• 4=sell_open_short

Position（Field:position_type)

• 1=long
• 2=short

Order Type（Field:type)

• limit
• market
• liquidate
• bankruptcy

Open Type（Field:open_type)

• cross
• isolated

Order Mode（Field:mode)

• 1=GTC (Good Till Cancel)
• 2=FOK (Fill or Kill)
• 3=IOC (Immediate or Cancel)
• 4=Maker Only (Good Till Crossing)

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

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

Description of the trading pair details field:

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

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

Market depth details：

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Note

• If the time range time_start and time_end are not filled in, all data will be displayed by default.
• When filling in the time range, time_end must be greater than the value of time_start.
• If only time_start is filled in, query the historical records starting from the timestamp.
• If only time_end is filled in, query the historical records starting from this timestamp.

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

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

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "order_id": 220609666322019,
    "price": "25637.2"
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}

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

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

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

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "order_id": 220609666322019
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}

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

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

Response Data

Response

{
  "message":"OK",
  "code":1000,
  "trace":"34018ca3-fe24-446a-9e1d-f82edfb3e3",
  "data":{
    "currency":"USDT",
    "amount":"10"
  }
}

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

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "symbol":"ETHUSDT",
    "leverage":"5",
    "open_type":"isolated",
    "max_value":"100"
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}

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

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "order_id": "220609666322019",
    "client_order_id": "123456789"
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}

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",
  "client_order_id":"123456789",
  "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

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "order_id": "220609666322019"
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}

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

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "order_id": "220609666322019"
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}

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

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "order_id": "220609666322019"
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}

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`

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`

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`

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

Response Data

Response

{
  "message": "OK",
  "code": 1000,
  "trace": "87db8cd43374470f96aacb0e3fcaf34c.77.16872314088656435",
  "data": {
    "wallet": [
      {
        "currency": "USDT",
        "name": "USDT",
        "available": "204.15216696",
        "frozen": "0.00000000"
      }
    ]
  }
}

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

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

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

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

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:

• operation request action, value: [subscribe=Subscribe channel, unsubscribe=Unsubscribe channel, login=Account 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 is filterable data, refer to each channel description for details

Example:

• Example 1: {"action": "subscribe", "args": ["futures/depth50:BTCUSDT"]}
  • Means to subscribe to the depth data of the trading pair BTCUSDT
• Example 2: {"action": "login", "args": ["80618e45710812162b04892c7ee5ead4a3cc3e56", "1589267764859", "3ceeb7e1b8cb165a975e28a2e2dfaca4d30b358873c0351c1a071d8c83314556", "web"]}
  • Login request before private channel subscription

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:

• Example 1：{"action":"access","success":true}
  • Means successful login
• Example 2：{"action":"unsubscribe","group":"futures/depth50:BTCUSDT","success":true,"request":{"action":"unsubscribe","args":["futures/depth50:BTCUSDT"]}}
  • Means successful cancellation of depth50 subscription for trading pair BTCUSDT
• Example 3：{"action":"subscribe","group":"futures/depth50:BTCUSDT","success":true,"request":{"action":"subscribe","args":["futures/depth50:BTCUSDT"]}}
  • Means successful subscribe of depth50 subscription for trading pair BTCUSDT
• Example 4：{"group":"futures/depth50:BTCUSDT","data":{"symbol":"BTCUSDT","way":2,"depths":[{"price":"30107.7","vol":"234"},{"price":"30107.8","vol":"1587"}]}}
  • Means the depth50 subscription of spot trading pair BTCUSDT, generates data, and returns it to the client

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

• Example 1：{"action":"subscribe","group":"futures/order","success":false,"error":"futures/order need authenication"}
  • Means you need to log in
• Example 2：{"action":"access","success":false,"error":"access failed: openapi auth: apiKey 880d5edecs**** failed: openapi auth failed"}
  • Means login failed, your sign is wrong
• Example 3：{"action":"subscribe","group":"sfutures/depth50:BTCUSDT","success":false,"request":{"action":"subscribe","args":["sfutures/depth50:BTCUSDT"]},"error":"group [sfutures/depth50:BTCUSDT] not exist"}
  • Means subscription failed, your parameter is invalid, this channel does not exist

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)

• Standard Ping frame

ws.send(new PingWebSocketFrame());

• Ping Text

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

Connection Limit

• A maximum of 500 connections can be maintained between each IP and BitMart server.

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

• action = subscribe
• args = The content of the args array is the subscribed topic
• topic is composed of <channel>:<filter>
  • channel is composed of business/name
  • filter can filter data, refer to the description of each channel for details

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

• action = unsubscribe
• args = The content of the args array is the subscribed topic
• topic is composed of <channel>:<filter>
  • channel is composed of business/name
  • filter can filter data, refer to the description of each channel for details

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

• actions: subscribe
• channel: futures/ticker

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:

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

• actions: subscribe
• channel: Channel name, such as futures/depth20
• symbol: Trading pair, such as BTCUSDT

Parameters Channel Name List

Response

Response

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

Return data description:

Instruction

Description of the depths details field:

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

• channel: Channel name, such asfutures/depthAll20
• symbol: Trading pair, such asBTCUSDT

Parameters Channel Name List

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:

Instruction Description of the asks bids details field:

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

• op: subscribe=Subscribe, You will receive a message that the subscription is successful, and then you will receive incremental depth data pushed in real time. request=Single request for the latest depth snapshot, You will receive a full depth of data immediately.
• channel:Channel name, such as futures/depthIncrease20
• symbol: Trading pair, such as BTCUSDT

Parameters Channel Name List