Change Log

2023-09-19

• Update endpoints for order
  • /contract/private/orderupdate response field adl
• Update endpoints for order history
  • /contract/private/order-historyupdate response field adl

2023-08-01

• Update endpoints for position
  • /contract/private/positionAdd new field entry_price

2023-07-22

• New endpoints for trading
  • /contract/private/submit-leverageSubmit Leverage (SIGNED)

2023-07-07

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

2023-06-20

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

2023-06-13

• New endpoints for order
  • /contract/private/get-open-ordersGet All Open Orders (KEYED)

2023-06-06

• Update endpoints for trading
  • /contract/private/submit-orderAdd new field client_order_id
  • /contract/private/orderAdd new field client_order_id
  • /contract/private/order-historyAdd new field client_order_id
• Update endpoints for websocket order notify
  • futures/orderAdd new field client_order_id

2023-05-18

• New endpoints for transfer
  • /account/v1/transfer-contractGet Transfer List (SIGNED)
  • /account/v1/transfer-contract-listTransfer (SIGNED)

2023-03-23

• New endpoints for websocket order notify
  • /contract/public/websocket/order

2023-03-16

• New endpoints for trading
  • /contract/private/submit-plan-orderSubmit Plan Order (SIGNED)
  • /contract/private/cancel-plan-orderCancel Plan Order (SIGNED)

2022-09-22

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

2022-08-31

• New websocket for public data
  • /contract/public/websocket

2022-08-23

• New endpoints for get current funding rate of a specified contract
  • /contract/public/open-interest

2022-08-18

• 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.)
  • Contract-Trade (long position, short position, closing position, etc.)

Read-Only Permissions:

Withdraw Permissions:

Spot-Trade Permissions:

Margin-Trade Permissions:

Contract-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
• Javascript 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?

Contact Us

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

Basic Information

API Basic Information

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

Request Parameter Settings

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

HTTP Response Codes

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

API Returned Codes

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

For details, please refer to Error Code List

Signature

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

Authentication Type

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

1. Setting Request Parameters

1.1 Set Request Header Key

Create X-BM-TIMESTAMP

// Java
System.currentTimeMillis();

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

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

// Nodejs & TypeScript
Date.now();

// Javascript
Date.now();

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

// C#
DateTimeOffset.UtcNow.ToUnixTimeMilliseconds()

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

1.2 Set Request Body Params

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

2. Example

Shell Example

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

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

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

Then set the following:

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

Assuming the key you applied for is as follows:

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

then the right side is a complete request

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

Rate Limit

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

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.bitmart.com/contract/public/details

Request Limit

See Detailed Rate Limit

Request Parameter

Request

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

Response Data

Response

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

Description of the trading pair details field:

Get Market Depth

Get full depth of trading pairs.

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

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

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

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

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.bitmart.com/contract/public/funding-rate

Request Limit

See Detailed Rate Limit

Request Parameter

Request

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

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": {
    "timestamp": 1662518172178,
    "symbol": "BTCUSDT",
    "rate_value": "0.000164",
    "expected_rate": "0.000164"
  },
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}

Get K-line

Applicable for querying K-line data

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

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

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

Futures Account Data

Get Contract Assets (KEYED)

Applicable for querying user contract asset details

Request URl

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request None

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

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": [
    {
      "currency": "USDT",
      "position_deposit": "100",
      "frozen_balance": "100",
      "available_balance": "100",
      "equity": "100",
      "unrealized": "100"
    },
    {
      "currency": "BTC",
      "available_balance": "0",
      "frozen_balance": "0",
      "unrealized": "0",
      "equity": "0",
      "position_deposit": "0"
    },
    {
      "currency": "ETH",
      "available_balance": "0",
      "frozen_balance": "0",
      "unrealized": "0",
      "equity": "0",
      "position_deposit": "0"
    }
  ],
  "trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}

Futures Trading

Get Order Detail (KEYED)

Applicable for querying contract order detail

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/contract/private/order?symbol=BTCUSDT&order_id=220609666322019

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.bitmart.com/contract/private/order-history

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/contract/private/order-history?symbol=BTCUSDT&start_time=1662368173&end_time=1662368179

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.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.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",
      "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.bitmart.com/contract/private/position

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/contract/private/position?symbol=BTCUSDT

Response Data

Response

{
  "code": 1000,
  "message": "Ok",
  "data": [
    {
      "symbol": "BTCUSDT",
      "leverage": "5",
      "timestamp": 1663814313531,
      "current_fee": "5.00409471",
      "open_timestamp": 1662714817820,
      "current_value": "16680.3157",
      "mark_price": "16673.27053207877",
      "position_value": "18584.272343943943943944339",
      "position_cross": "3798.397624451826977945",
      "maintenance_margin": "4798.397624451826977945",
      "close_vol": "100",
      "close_avg_price": "20700.7",
      "open_avg_price": "20200",
      "entry_price": "20201",
      "current_amount": "899",
      "unrealized_value": "1903.956643943943943944339",
      "realized_value": "55.049173071454605573",
      "position_type": 2
    }
  ],
  "trace": "ae96cae5-1f09-4ea5-971e-4474a6724bc8"
}

Get Order Trade (KEYED)

Applicable for querying contract order trade detail

Request URL

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/contract/private/trades?symbol=BTCUSDT&start_time=1662368173&end_time=1662368179

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.bitmart.com/account/v1/transfer-contract-list

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
    "currency":"USDT",
    "time_start":1684391137804,
    "time_end":1684392577804,
    "page":1,
    "limit":10,
    "recvWindow":5000
}'
https://api-cloud.bitmart.com/account/v1/transfer-contract-list

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.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.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.bitmart.com/contract/private/cancel-order

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"ETHUSDT",
  "order_id": "220906179559421"
}'
https://api-cloud.bitmart.com/contract/private/cancel-order

Response Data

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

Response

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

Cancel All Orders (SIGNED)

Applicable for batch order cancellation under a particular contract

Request URL

POST https://api-cloud.bitmart.com/contract/private/cancel-orders

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"ETHUSDT"
}'
https://api-cloud.bitmart.com/contract/private/cancel-orders

Response Data

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

Response

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

Submit Plan Order (SIGNED)

Applicable for placing contract plan orders

Request URL

POST https://api-cloud.bitmart.com/contract/private/submit-plan-order

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"ETHUSDT",
  "side":4,
  "mode":1,
  "type":"limit",
  "leverage":"1",
  "open_type":"isolated",
  "size":10,
  "trigger_price":"2000",
  "executive_price":"1450",
  "price_type":1,
  "price_way":1
}'
https://api-cloud.bitmart.com/contract/private/submit-plan-order

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.bitmart.com/contract/private/cancel-plan-order

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "symbol":"ETHUSDT",
  "order_id": "220906179559421"
}'
https://api-cloud.bitmart.com/contract/private/cancel-plan-order

Response Data

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

Response

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

Transfer (SIGNED)

Transfer between spot account and contract account

Request URl

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

Request Limit

See Detailed Rate Limit

Request Parameter

Request

curl 
 -H 'X-BM-KEY:{{AccessKey}}'
 -H 'X-BM-TIMESTAMP:{{currentTime}}'
 -H 'X-BM-SIGN:{{SIGN}}' 
 -X POST -d '{
  "currency":"USDT",
  "amount":"10",
  "type":"spot_to_contract",
  "recvWindow":5000
}'
https://api-cloud.bitmart.com/account/v1/transfer-contract

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

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.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.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.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.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.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.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.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.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.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.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.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.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.bitmart.com/api?protocol=1.1

Private Channel: wss://openapi-ws.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 10 connections can be maintained between each IP and BitMart server.
• Once connected, allows clients to subscribe to up to 100 channels per connection.
• Send message rate limit:
  1. Initiate connection: Clients can initiate a maximum of 30 requests to connect to the BitMart server within 1 minute.
     
  2. Once connected: Clients can sending a maximum of 100 subscription messages within 10 seconds
  3. Once connected: A maximum of 20 messages arrays can be sent by clients for a single subscription.

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

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

Response

Response

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

Return data description:

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

• channel: Channel name, such as futures/klineBin1m
• symbol: Trading pair, such as BTCUSDT

Parameters Channel Name List

Response

Response

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

Return data description:

【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

• API_KEY: The user's API key
• timestamp: Timestamp, the unit is milliseconds, it will expire after 60 seconds
• sign: Signature, sign=CryptoJS.HmacSHA256(timestamp + "#" + your_api_memo + "#" + "bitmart.WebSocket", your_api_secret_key)
• dev: Device, web eg.

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:

• timestamp=1589267764859
• API_KEY = "80618e45710812162b04892c7ee5ead4a3cc3e56"
• API_SECRET = "6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9"
• API_MEMO = "test001";

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

• actions: subscribe
• channel: Channel name futures/asset, fixed value
• currency: Currency, such as BTC, asset types that support subscriptions are: USDT (U-native), BTC (coin-native), ETH (coin-native)

Response

Response

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

Return data description:

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

• actions: subscribe
• channel: Channel name futures/position, fixed value

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:

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

• actions: subscribe
• channel: Channel name futures/order, fixed value

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": "1000",
        "create_time": 1662368173000,
        "update_time": 1662368173000,
        "plan_order_id": "220901412155341",
        "last_trade": {
          "lastTradeID": 1247592391,
          "fillQty": "1",
          "fillPrice": "25667.2",
          "fee": "-0.00027",
          "feeCcy": "USDT"
        }
      }
    }
  ]
}

Return data description:

Recently trade fields describe：

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.bitmart.com/contract/private/affiliate/rebate-list

Request Limit

See Detailed Rate Limit

Request Parameter

Request

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

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
  }, {
    "rebate_coin": "USDT",
    "trade_user_id": 4225148,
    "total_rebate_amount": 21.7871536572
  }]
}

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.bitmart.com/contract/private/affiliate/trade-list

Request Limit

See Detailed Rate Limit

Request Parameter

Request

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

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

Error Code

Restful Error Code

List of global HTTP return codes

Authentication Error Code

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

Contract API Error Code

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