Update Plan

Change Log

2026-04-14

REST API

• [New] /newearn/cloud/v1/saving/product Get Product List (KEYED)
  • Feat: Query flexible savings product list
• [New] /newearn/cloud/v1/saving/subscribe Subscribe (SIGNED)
  • Feat: Subscribe to flexible savings product
• [New] /newearn/cloud/v1/saving/redeem Redeem (SIGNED)
  • Feat: Redeem from flexible savings product
• [New] /newearn/cloud/v1/saving/earn Get Earn Positions (KEYED)
  • Feat: Query flexible savings positions
• [New] /newearn/cloud/v1/saving/record Get History Records (KEYED)
  • Feat: Query flexible savings history records (subscribe/redeem/interest)

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.)
  • Finance (Earn savings subscribe, Earn savints redeem)

Read-Only Permissions:

Withdraw Permissions:

Spot-Trade Permissions:

Margin-Trade Permissions:

Future-Trade Permissions:

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

Contract Agent 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.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

Earn Savings

Get Product List (KEYED)

Query flexible savings product list

Request URL

GET https://api-cloud.bitmart.com/newearn/cloud/v1/saving/product

Request Limit

Based on UID, 10 times/2s

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
"https://api-cloud.bitmart.com/newearn/cloud/v1/saving/product?currentPage=1&sizePage=10"

Response Data

Response

{
    "message": "OK",
    "code": 1000,
    "trace": "0e6fbc21-e3a0-4465-8acf-8d4e52504bbd",
    "data": {
        "total": 10,
        "list": [
            {
                "productId": "1001",
                "coinName": "USDT",
                "productTag": "[\"HOT\"]",
                "apy": "5.00%",
                "minPurchaseAmount": "1",
                "maxPurchaseAmount": "100000",
                "additionalApy": "1.00%",
                "hasTierRate": true,
                "tierRate": [
                    {
                        "minPurchaseAmount": "1",
                        "maxPurchaseAmount": "10000",
                        "apy": "5.00%"
                    },
                    {
                        "minPurchaseAmount": "10000",
                        "maxPurchaseAmount": "100000",
                        "apy": "4.00%"
                    }
                ]
            }
        ]
    }
}

Subscribe (SIGNED)

Subscribe to flexible savings product

Request URL

POST https://api-cloud.bitmart.com/newearn/cloud/v1/saving/subscribe

Request Limit

Based on UID, 10 times/2s

Request Parameter

Request

curl -X POST -H 'X-BM-KEY:{{AccessKey}}' \
     -H 'X-BM-SIGN:{{Signature}}' \
     -H 'X-BM-TIMESTAMP:{{Timestamp}}' \
     -H 'Content-Type: application/json' \
     -d '{"productId":"1001","amount":"100","requestNo":"unique-request-id-001"}' \
     "https://api-cloud.bitmart.com/newearn/cloud/v1/saving/subscribe"

Response Data

Response

{
    "message": "OK",
    "code": 1000,
    "trace": "0e6fbc21-e3a0-4465-8acf-8d4e52504bbd",
    "data": true
}

Redeem (SIGNED)

Redeem from flexible savings product

Request URL

POST https://api-cloud.bitmart.com/newearn/cloud/v1/saving/redeem

Request Limit

Based on UID, 10 times/2s

Request Parameter

Request

curl -X POST -H 'X-BM-KEY:{{AccessKey}}' \
     -H 'X-BM-SIGN:{{Signature}}' \
     -H 'X-BM-TIMESTAMP:{{Timestamp}}' \
     -H 'Content-Type: application/json' \
     -d '{"earnId":"200001","amount":"50","requestNo":"unique-request-id-002"}' \
     "https://api-cloud.bitmart.com/newearn/cloud/v1/saving/redeem"

Response Data

Response

{
    "message": "OK",
    "code": 1000,
    "trace": "0e6fbc21-e3a0-4465-8acf-8d4e52504bbd",
    "data": true
}

Get Earn Positions (KEYED)

Query flexible savings positions

Request URL

GET https://api-cloud.bitmart.com/newearn/cloud/v1/saving/earn

Request Limit

Based on UID, 10 times/2s

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
"https://api-cloud.bitmart.com/newearn/cloud/v1/saving/earn?currentPage=1&sizePage=10"

Response Data

Response

{
    "message": "OK",
    "code": 1000,
    "trace": "0e6fbc21-e3a0-4465-8acf-8d4e52504bbd",
    "data": {
        "total": 5,
        "list": [
            {
                "earnId": "200001",
                "productId": "1001",
                "coinId": 1,
                "coinName": "USDT",
                "productTag": "[\"HOT\"]",
                "apy": "5.00%",
                "totalProfit": "10",
                "autoSubscribe": true,
                "additionalApy": "1.00%",
                "hasTierRate": true,
                "tierRate": [
                    {
                        "minPurchaseAmount": "1",
                        "maxPurchaseAmount": "10000",
                        "apy": "5.00%"
                    }
                ]
            }
        ]
    }
}

Get History Records (KEYED)

Query flexible savings history records (subscribe/redeem/interest)

Request URL

GET https://api-cloud.bitmart.com/newearn/cloud/v1/saving/record

Request Limit

Based on UID, 10 times/2s

Request Parameter

Request

curl -H 'X-BM-KEY:{{AccessKey}}'
"https://api-cloud.bitmart.com/newearn/cloud/v1/saving/record?type=subscribe&currentPage=1&sizePage=10"

Response Data

Response

{
    "message": "OK",
    "code": 1000,
    "trace": "0e6fbc21-e3a0-4465-8acf-8d4e52504bbd",
    "data": {
        "total": 20,
        "list": [
            {
                "type": "subscribe",
                "recordId": "300001",
                "productId": "1001",
                "coinName": "USDT",
                "amount": "100",
                "productTag": "[\"HOT\"]",
                "time": 1681701557927,
                "subscribeType": "NORMAL"
            }
        ]
    }
}

Error Code

Restful Error Code

Earn API Error Code

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