Introduction
Getting Started
We welcome trading robots, order-following platforms, strategy software providers, and other organizations to take advantage of the rich trading currency pairs and liquidity of the BitMart platform, as well as the ease of use of the API brokers themselves, to attract investors to trade on our marketplace through the trading tools they provide. We will give those API Brokers who bring in order volume a rebate on their trading fees.
If you need advice on other matters, please contact
Telegram: BM Institution/VIP
Email: [email protected]
Access Process
Steps | Description |
---|---|
1、Open API brokerage institutional account | 1.API brokers need to register with BitMart and pass the audit. 2.BitMart will assign a BrokerID to the institution and set parameters such as rebate length, rebate percentage, additional incentives for new users, etc. 3.After settlement, all rebates will be credited to the API broker's spot wallet in BitMart. |
2、User registration for BitMart account | 1.Users need to register a BitMart account and pass at least the personal LV1 KYC. 2.Users should generate an API Key with spot trading privileges and read-only privileges on the API page (the specific benefits are based on the requirements in the trading robot documentation). |
3、User binding deployment API to the tools platform provided by API brokers | According to the specific needs of the API broker, the user binds the BitMart API to the tools provided by the API broker, connects to the BitMart market, and performs operations such as market information inquiry, trade order placement, and order inquiry through the tools provided by the API broker. |
4、API brokers send orders to BitMart | When an API broker sends an order request instead of a user, the order must carry the user's APIKey+BrokerID to identify that the order was placed through a specific API broker. |
5、BitMart rebates to the API broker's account opened in BitMart | 1.When an order is received and filled, BitMart must split the transaction fee (including BMX credit, etc.) and rebate it to the API broker's spot wallet account. 2.It is necessary to determine whether the user who placed the order has an inviter or not. If there is an affiliate rebate, then no refund will be given to the API broker. |
6、API brokers check rebate details and statements through a particular API | Check rebate details and customer orders according to the dedicated API brokerage interface provided by BitMart. |
Product Dictionary
Trade
Field | Description | Details |
---|---|---|
currency | Currency | Currency refers to the basic unit that can be transferred in and out, such as BTC, ETH, EOS, etc |
symbol_id | Trading pair id | The unique number of the trading pair, such as the ID of BTC_USDT is 53, mainly used in the Websocket interface |
symbol | Trading pair name | Consists of base and quote currency. Taking BTC_USDT as an example, BTC is the base currency, and USDT is the quote currency. Trading pairs are mainly used in spot trading |
Contract
Field | Description | Details |
---|---|---|
symbol | Trading pair name | Consists of base and quote currency. Taking BTCUSDT as an example, BTC is the base currency, and USDT is the quote currency. Trading pairs are mainly used in contract trading |
Order and Trade ID
Field | Description |
---|---|
order_id | Order number, the order ID under the same currency pair of each business line is unique |
trade_id | The unique number of the trade |
Time
The time returned by the system is all in the form of time pinches.
Field | Description |
---|---|
s_t | accurate to seconds of timestamp |
ms_t | accurate to milliseconds of timestamp |
Standard Rules
This chapter is mainly divided into the following three aspects for the details of standard specifications:
Numbers ID
Numbers
To maintain the integrity and accuracy across platforms, decimal numbers are returned as strings. It is recommended that you also convert numbers to strings when making requests to avoid truncation and precision errors.
Integers (such as transaction ID and order) are not quoted.
ID
Unless otherwise stated, most identifiers are UUIDs. When making a request that requires a UUID, the following two formats (with and without dashes) are accepted.
132fb6ae-456b-4654-b4e0-d681ac05cea1 or 132fb6ae456b4654b4e0d681ac05cea1
Change Log
2022-11-03
- New API Broker endpoints
/spot/v1/broker/rebate
Basic Information
API Basic Information
- The interface may require the user's API Key. For how to create an API-KEY, please refer to here API KEY Interface Authentication.
- RESTful API URL: https://api-cloud.bitmart.com
- The responses of all interfaces are 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
When using the interface, HTTP 200 means that the client has submitted a request to the business core through the gateway and it has returned information, but it does not mean that the business request is successful. It may have been executed, or the execution may fail, and further confirmation is required at this time. Please pay attention to the code field in the returned data.
For details, please refer to Error Code List
Authentication and Signature
In order to facilitate access, we provide SDK in some languages for reference
* bitmart-go-sdk-api
* bitmart-python-sdk-api
* bitmart-java-sdk-api
* bitmart-php-sdk-api
This chapter mainly divides the verification details into the following four aspects:
- Generate API Key
- Make a request
- Signature
- Timestamp
1. Generate API Key
Before signing any request, you must create an API Key through the BitMart website. After creating the API Key, you will get 3 pieces of information you must remember:
- Access Key
- Secret Key
- Memo
Access Key and Secret Key will be randomly generated and provided by BitMart, and Memo will be provided by you to ensure the security of API access. BitMart will store the encrypted hash value of the Secret Key for verification, but if you forget the Secret Key, it cannot be recovered. Please regenerate the new API Key through the BitMart website.
Example
Login Bitmart website and enter the account page
Click the API Settings button to enter the CREATE API page
2. Make a Request
The request contains two parts, one is header and the other is queryString
Interface Header Parameters
All REST request headers must include the following:
X-BM-KEY: Access Key of type string.
X-BM-SIGN: Use HmacSHA256 signature (see Signature).
X-BM-TIMESTAMP: The timestamp of the request. (UTC0 time zone timestamp, accurate to milliseconds)
Interface Content Type
Request Example: GET/DELETE
curl {{host}}/v1/goto?symbol=BMXBTC&side=BUY
# queryString: symbol=BMXBTC&side=BUY
- For interfaces using the GET and DELETE methods, the content can be sent in two forms: application/json or application/x-www-form-urlencoded. The parameter must be sent in the query string. (The order of the parameters is not required.)
Request Example: POST/PUT
curl -X POST {{host}}/v1/goto -H "Content-type: application/json" -d '{"symbol":"BMX","side":"BUY"}'
# queryString: {"symbol":"BMX","side":"BUY"}
- For interfaces using the POST and PUT methods, the content can be sent in application/json form. (The order of the parameters is not required.)
Special Note: In the example on the right,
The request method of GET/DELETE, the query string is the form type of key1=value2&key2=value2
The request method of POST/PUT, the query string is the json type of {"symbol":"BMX","side":"BUY"}
3.Signature
Signature Algorithm Example: In the example below, param variable message=
timestamp + "#" + memo + "#" + queryString
// javascript language
sign=CryptoJS.HmacSHA256(message, YourSecretKey)
// python language
def sign(message, your_secret_key):
mac = hmac.new(bytes(your_secret_key, encoding='utf8'), bytes(message, encoding='utf-8'), digestmod='sha256')
return mac.hexdigest()
// java language
import org.apache.commons.codec.binary.Hex;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
public final class CloudSignature {
static final String HMAC_SHA256 = "HmacSHA256";
static String createSha256Signature(String yourSecretKey, String message) {
try {
Mac sha256 = Mac.getInstance(HMAC_SHA256);
SecretKeySpec secretKeySpec = new SecretKeySpec(yourSecretKey.getBytes(), HMAC_SHA256);
sha256.init(secretKeySpec);
return Hex.encodeHexString(sha256.doFinal(message.getBytes()));
} catch (Exception ex) {
ex.printStackTrace();
}
return null;
}
}
// go language
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
)
func HmacSha256Base64Signer(message string, yourSecretKey string) (string, error) {
mac := hmac.New(sha256.New, []byte(yourSecretKey))
_, err := mac.Write([]byte(message))
if err != nil {
return "", err
}
return hex.EncodeToString(mac.Sum(nil)), nil
}
The request header of X-BM-SIGN is signed by the HMAC SHA256 algorithm and converted to lowercase hexadecimal (toHexString) encoding. Among them, the key of the algorithm is your api secret key, and the signed content is timestamp + "#" + memo + "#" + queryString
.
Among them, the value of timestamp is the same as the X-BM-TIMESTAMP in request header.
Note: If the length of your sign is not equal to 64, or if the sign is uppercase, it is wrong.
4.Timestamp
Unix timestamps accurate to milliseconds using UTC0 time zone
Example: If the current time: 2020-04-28 09:21:30.000, then timestamp=1588065690000
Example
The keys are as follows: Note that the following two interfaces are deployed in the production environment, and users can directly test and call after replacing with their own KEY.
Key | Value |
---|---|
accessKey | 80618e45710812162b04892c7ee5ead4a3cc3e56 |
secretKey | 6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9 |
memo | test001 |
Example: /spot/v1/test-get
echo -n "1589793795969#test001#symbol=BTC_USDT" | openssl dgst -sha256 -hmac "6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9"
(stdin)= 118eb558afa7d84e8710004f8416ddb771f50718c85f60a45069d0ccbe6ee1e0
curl --location --request GET 'localhost:8080/spot/v1/test-get?symbol=BTC_USDT'
--header 'Content-Type: application/json'
--header 'X-BM-KEY: 80618e45710812162b04892c7ee5ead4a3cc3e56'
--header 'X-BM-SIGN: 118eb558afa7d84e8710004f8416ddb771f50718c85f60a45069d0ccbe6ee1e0'
--header 'X-BM-TIMESTAMP: 1589793795969'
{"message":"OK","code":1000,"trace":"17105b32-cc5b-406a-ab6e-6d9ed0fa4fd8","data":{}}
Request interface: /spot/v1/test-get
Request method: GET
Current timestamp: timestamp=1589793795969
Parameter | Value |
---|---|
symbol | BTC_USDT |
Returned data: The request is a success if code=1000 in returned data.
Example: /spot/v1/test-post
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"}'
{"message":"OK","code":1000,"trace":"17105b32-cc5b-406a-ab6e-6d9ed0fa4fd8","data":{}}
Request interface: /spot/v1/test-post
Request method: POST
Current timestamp: timestamp=1589793796145
Parameter | Value |
---|---|
symbol | BTC_USDT |
price | 8600 |
count | 100 |
Returned data: The request is a success if code=1000 in returned data.
RequestFormat
This article mainly describes some specifications of the interface from the following two aspects. * Request standard * Authentication type
Request Standard
1.Rest Interface
1.1 Request parameter and format
GET/DELETE
curl https://api-cloud.bitmart.com/contract/v1/ifcontract/contracts?contractID=1
For interfaces using GET, DELETE methods, the parameters should be sent via query string.
POST/PUT
curl https://api-cloud.bitmart.com/contract/v1/ifcontract/submitOrder
body: {"contract_id":1,"category":1,"way":1,"open_type":1,"leverage":10,"custom_id":1,"price":5000,"vol":10,"nonce":1589266686}
For interfaces using POST, PUT methods, the parameters should be sent in the request body for concent type of application/json.
1.2 Reponse
Response:
{
"code": 1000,
"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
"message": "OK",
"data": [
{
"low": "130",
"high": "130",
"open": "130",
"close": "130",
"last_price": "130",
"avg_price": "130",
"volume": "0",
"timestamp": 1532610000,
"rise_fall_rate": "0",
"rise_fall_value": "0"
}
]
}
The server response data format is JSON.
Field | Description |
---|---|
code | Error code,See Details |
message | Error message |
trace | Each request event tracking ID, the server will return for each request |
data | Data returned by the server |
2.WebSocket Interface
No description.
Authentication Type
This chapter is mainly divided into the following two aspects of interface type details:
- Public interface
- Private interface
1. Public Interface
The public interface can be used to obtain configuration information and market data. Public requests can be called without authentication.
2. Private Interface
The private interface can be used for order and account management. Each private request must be signed using a standardized authentication method. The private interface needs to be verified with your API key.
Interface Permission
Whether you have permission to call the interface requires attention to the following two aspects:
* Interface authentication
* API Permission
Interface authentication
When the user calls, APIKEY and verification parameters need to be passed in the way specified by the interface. The first line of each interface will have a description of what authentication the interface needs.
Simply put, the interface authentication is divided into the following three cases:
Interface Type | Authentication Type | Description |
---|---|---|
Public | NONE | X-BM-KEY is not required, X-BM-SIGN is not required |
Private | KEYED | X-BM-KEY is required, X-BM-SIGN is not required |
Private | SIGNED | X-BM-KEY is required, X-BM-SIGN is required |
API KEY Permission
Refers to the user specified authorization to the API when applying for the API. That is, when users apply for API KEY on the BitMart website page, they can check API permissions, such as: trading permissions (including contract transactions and spot transactions). (Default: read-only permission).
Details:
Spot Interface | Description | Authentication Type | Permissions |
---|---|---|---|
/contract/public/details | Get a detailed list of all trading pairs | NONE | No permission required |
/contract/public/depth | Get full depth of trading pairs | NONE | No permission required |
/contract/public/open-interest | Get Contract Openinterest | NONE | No permission required |
/contract/private/submit-order | Submit Contract Order | SIGNED | Trading Permission |
/contract/private/cancel-order | Cancel Contract Order | SIGNED | Trading Permission |
/contract/private/cancel-orders | Batch Cancel Contract Orders | SIGNED | Trading Permission |
/contract/private/order | Get Contract Order Detail | KEYED | Read-Only Permission |
/contract/private/order-history | Get Contract Order History | KEYED | Read-Only Permission |
/contract/private/trades | Get Contract Order Trade Detail | KEYED | Read-Only Permission |
/contract/private/assets-detail | Get Contract Assets Detail | KEYED | Read-Only Permission |
/contract/private/position | Get Current Position Detail | KEYED | Read-Only Permission |
/contract/public/funding-rate | Get Current Funding Rate | NONE | No permission required |
/contract/public/kline | Get K-line | NONE | No permission required |
Spot Interface | Description | Authentication Type | Permissions |
---|---|---|---|
/spot/v1/currencies | Get a list of all cryptocurrencies on the platform | NONE | No permission required |
/spot/v1/symbols | Get a list of all trading pairs on the platform | NONE | No permission required |
/spot/v1/symbols/details | Get a detailed list of all trading pairs on the platform | NONE | No permission required |
/spot/v1/ticker | Get ticker | NONE | No permission required |
/spot/v1/steps | Get K-Line steps | NONE | No permission required |
/spot/v1/symbols/kline | Get K-Line | NONE | No permission required |
/spot/v1/symbols/book | Get orderbook | NONE | No permission required |
/spot/v1/symbols/trades | Get recent trades | NONE | No permission required |
/spot/v1/wallet | Get user wallet | KEYED | Read-Only Permission |
/spot/v1/submit_order | Place order | SIGNED | Trading Permission |
/spot/v1/cancel_order | Cancel order | SIGNED | Trading Permission |
/spot/v1/cancel_orders | Cancel all orders | SIGNED | Trading Permission |
/spot/v1/order_detail | Get order detail | KEYED | Read-Only Permission |
/spot/v1/orders | Get user orders | KEYED | Read-Only Permission |
/spot/v1/trades | Get user trades | KEYED | Read-Only Permission |
API Broker Interface | Description | Authentication Type | Permissions |
---|---|---|---|
/spot/v1/broker/rebate | Applicable to query API Broker's rebate records | KEYED | Read-Only Permission |
Rate Limit
When the requests exceed the rate limit, the 429 status will be returned: the request is too frequent.
REST API
If a valid API key is passed in, the user id will be used to limit the rate; if not, the public IP will be used to limit the rate.
Rate limit rules: There is a separate description on each interface. If there is not, the rate limit is 25 times/5 sec in general.
Each call to the interface will return 3 Response Headers with limit tags, as shown below:
Example:
X-BM-RateLimit-Remaining: 10
X-BM-RateLimit-Limit: 600
X-BM-RateLimit-Reset: 60
The above setting means that it can be called 600 times within 60 seconds, and currently has been called 10 times
Response Header | Description |
---|---|
X-BM-RateLimit-Remaining | The number of requests left in the current time window |
X-BM-RateLimit-Limit | The max number of requests in the current time window |
X-BM-RateLimit-Reset | Current time window, in seconds |
The specific interface limits are as follows:
System Interface | Interface Name | Limit Target | Rate |
---|---|---|---|
/system/time | Get system time | IP | 10 times/sec |
/system/service | Get system service status | IP | 10 times/sec |
Funding Account Interface | Interface Name | Limit Target | Rate | Special Remarks |
---|---|---|---|---|
/account/v1/currencies | Get currencies | IP | 2 times/2 sec | |
/account/v1/wallet | Get account balance | X-BM-KEY | 12 times/2 sec | |
/account/v1/deposit/address | Deposit address | X-BM-KEY | 2 times/2 sec | |
/account/v1/withdraw/charge | Withdraw quota | X-BM-KEY | 2 times/2 sec | |
/account/v1/withdraw/apply | Withdraw | X-BM-KEY | 8 times/2 sec | |
/account/v2/deposit-withdraw/history | Get deposit and withdraw history V2 | X-BM-KEY | 8 times/2 sec | |
/account/v1/deposit-withdraw/detail | Get a deposit Or withdraw detail | X-BM-KEY | 8 times/2 sec | |
/spot/v1/margin/isolated/account | Get Margin Account Details(Isolated) | X-BM-KEY | 12 times/2 sec | |
/spot/v1/margin/isolated/transfer | Margin Asset Transfer | X-BM-KEY | 2 times/2 sec | |
/spot/v1/user_fee | Basic Fee Rate | X-BM-KEY | 2 times/2 sec | |
/spot/v1/trade_fee | Actual Trade Fee Rate | X-BM-KEY | 2 times/2 sec |
Contract Interface | Interface Name | Limit Target | Rate | Special Remarks |
---|---|---|---|---|
/contract/public/details | Get a detailed list of all trading pairs | IP | 12 times/2 sec | |
/contract/public/depth | Get full depth of trading pairs | IP | 12 times/2 sec | |
/contract/public/open-interest | Get Contract Openinterest | IP | 2 times/2 sec | |
/contract/private/submit-order | Submit Contract Order | X-BM-KEY | 24 times/2 sec | |
/contract/private/cancel-order | Cancel Contract Order | X-BM-KEY | 40 times/2 sec | |
/contract/private/cancel-orders | Batch Cancel Contract Orders | X-BM-KEY | 2 times/2 sec | |
/contract/private/submit-plan-order | Submit Contract Plan Order | X-BM-KEY | 24 times/2 sec | |
/contract/private/cancel-plan-order | Cancel Contract Plan Order | X-BM-KEY | 40 times/2 sec | |
/contract/private/order | Get Contract Order Detail | X-BM-KEY | 50 times/2 sec | |
/contract/private/order-history | Get Contract Order History | X-BM-KEY | 6 times/2 sec | |
/contract/private/trades | Get Contract Order Trade Detail | X-BM-KEY | 6 times/2 sec | |
/contract/private/assets-detail | Get Contract Assets Detail | X-BM-KEY | 12 times/2 sec | |
/contract/private/position | Get Current Position Detail | X-BM-KEY | 6 times/2 sec | |
/contract/public/funding-rate | Get Current Funding Rate | IP | 2 times/2 sec | |
/contract/public/kline | Get K-line | IP | 12 times/2 sec |
Spot Interface | Interface Name | Limit Target | Rate | Special Remarks |
---|---|---|---|---|
/spot/v1/currencies | Get a list of all cryptocurrencies | IP | 8 times/2 sec | |
/spot/v1/symbols | Get a list of all trading pairs | IP | 8 times/2 sec | |
/spot/v1/symbols/details | Get a detailed list of all trading pairs | IP | 12 times/2 sec | |
/spot/v1/ticker | Get ticker | IP | 12 times/2 sec | |
/spot/v2/ticker | Get Ticker of All Pairs | IP | 2 times/2 sec | |
/spot/v1/ticker_detail | Get Ticker of a Trading Pair | IP | 12 times/2 sec | |
/spot/v1/steps | Get K-Line steps | IP | 2 times/2 sec | |
/spot/v1/symbols/kline | Get k-Line | IP | 12 times/2 sec | |
/spot/v1/symbols/book | Get orderbook | IP | 12 times/2 sec | |
/spot/v1/symbols/trades | Get the latest trades | IP | 12 times/2 sec | |
/spot/v1/wallet | Get the user's wallet balance | X-BM-KEY | 12 times/2 sec | |
/spot/v1/submit_order | Place spot order | X-BM-KEY | 60 times/2 sec | |
/spot/v2/submit_order | Place spot order | X-BM-KEY | 60 times/2 sec | |
/spot/v1/margin/submit_order | Place margin order | X-BM-KEY | 60 times/2 sec | |
/spot/v2/cancel_order | Cancel order | X-BM-KEY | 60 times/2 sec | |
/spot/v3/cancel_order | Cancel order | X-BM-KEY | 60 times/2 sec | |
/spot/v1/cancel_orders | Cancel all orders in the specified direction of the specified trading pair | X-BM-KEY | 4 times/2 sec | |
/spot/v1/order_detail | Get order details | X-BM-KEY | 60 times/2 sec | |
/spot/v2/order_detail | Get order details | X-BM-KEY | 60 times/2 sec | |
/spot/v2/orders | Get user's recent orders V2 | X-BM-KEY | 12 times/2 sec | |
/spot/v3/orders | Get user's recent orders | X-BM-KEY | 12 times/2 sec | |
/spot/v1/trades | User trade records | X-BM-KEY | 12 times/2 sec | |
/spot/v2/trades | User trade records | X-BM-KEY | 12 times/2 sec | |
/spot/v1/batch_orders | Batch order | X-BM-KEY | 60 times/2 sec | |
/spot/v2/batch_orders | Batch order | X-BM-KEY | 60 times/2 sec |
Sub-Account Interface | Interface Name | Limit Target | Rate | Special Remarks |
---|---|---|---|---|
/account/sub-account/main/v1/sub-to-main | Sub-Account Spot Asset Transfer (For Main Account) | X-BM-KEY | 2 times/2 sec | |
/account/sub-account/sub/v1/sub-to-main | Sub-Account Spot Asset Transfer (For Sub-Account) | X-BM-KEY | 2 times/2 sec | |
/account/sub-account/main/v1/main-to-sub | Main Account Spot Asset Transfer (For Main Account) | X-BM-KEY | 2 times/2 sec | |
/account/sub-account/sub/v1/sub-to-sub | Sub-Account to Sub-Account Spot Asset Transfer (For Sub-Account) | X-BM-KEY | 2 times/2 sec | |
/account/sub-account/main/v1/sub-to-sub | Sub-account to Sub-Account Spot Asset Transfer (For Main Account) | X-BM-KEY | 2 times/2 sec | |
/account/sub-account/main/v1/transfer-list | Query Sub-account Spot Asset Transfer History (For Main Account) | X-BM-KEY | 8 times/2 sec | |
/account/sub-account/v1/transfer-history | Get Account Spot Asset Transfer History | X-BM-KEY | 8 times/2 sec | |
/account/sub-account/main/v1/wallet | Get Sub-Account Spot Wallet Balance (For Main Account) | X-BM-KEY | 12 times/2 sec | |
/account/sub-account/main/v1/subaccount-list | Get Sub-account List (For Main Account) | X-BM-KEY | 8 times/2 sec |
Margin Loan Interface | Interface Name | Limit Target | Rate | Special Remarks |
---|---|---|---|---|
/spot/v1/margin/isolated/borrow | Margin Borrow (Isolated) | X-BM-KEY | 2 times/2 sec | |
/spot/v1/margin/isolated/repay | Margin Repay (Isolated) | X-BM-KEY | 2 times/2 sec | |
/spot/v1/margin/isolated/borrow_record | Get Borrow Record(Isolated) | X-BM-KEY | 60 times/2 sec | |
/spot/v1/margin/isolated/repay_record | Get Repayment Record(Isolated) | X-BM-KEY | 60 times/2 sec | |
/spot/v1/margin/isolated/pairs | Get Trading Pair Borrowing Rate and Amount | X-BM-KEY | 2 times/2 sec |
API Broker Interface | Interface Name | Limit Target | Rate | Special Remarks |
---|---|---|---|---|
/spot/v1/broker/rebate | Applicable to query API Broker's rebate records | X-BM-KEY | 1 times/1 sec |
Endpoints
Get Rebate Records
Applicable to query API Broker's rebate records
(Authentication type:KEYED, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/spot/v1/broker/rebate
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v1/broker/rebate
Field | Type | Required? | Description |
---|---|---|---|
start_time | long | No | Query start time stamp, if neither is filled in, then return the last 180 days of records |
end_time | long | No | Query end time stamp, if neither is filled in, then return the last 180 days of records |
Response Data
Response
{
"message":"OK",
"code":1000,
"trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
"data":{
"rebates":{
"2022-10-22":[
{
"currency":"USDT",
"rebate_amount":"10.238"
},
{
"currency":"BMX",
"rebate_amount":"5.68"
}
],
"2022-10-23":[
{
"currency":"USDT",
"rebate_amount":"21.9895"
}
],
...
}
}
}
Field | Type | Description |
---|---|---|
rebates | string | Daily rebate list |
currency | string | Rebate currency |
rebate_amount | string | Rebate amount |
Error Code
Restful Error Code
List of global HTTP return codes
HTTP | Description |
---|---|
404 | Not Found-The requested interface could not be found |
403 | Forbidden-No permission to access the resource (KEY may not have permission, or it may be IP restrictions) |
401 | Unauthorized-Authentication failed (there are problems with the 3 header parameters, failed) |
500 | Internal Server Error-Server exception, BitMart service problem |
Authentication Error Code
Example: httpStatus:200, body:{"code": 1000, "message": "OK", "trace": "12323-3243242-34334534-4353","data":{}}
error message | code error code | http status code |
---|---|---|
Not found | 30000 | 404 |
Header X-BM-KEY is empty | 30001 | 401 |
Header X-BM-KEY not found | 30002 | 401 |
Header X-BM-KEY has frozen | 30003 | 401 |
Header X-BM-SIGN is empty | 30004 | 401 |
Header X-BM-SIGN is wrong | 30005 | 401 |
Header X-BM-TIMESTAMP is empty | 30006 | 401 |
Header X-BM-TIMESTAMP range. Within a minute | 30007 | 401 |
Header X-BM-TIMESTAMP invalid format | 30008 | 401 |
IP is forbidden. We recommend enabling IP whitelist for API trading. After that reauth your account | 30010 | 403 |
Header X-BM-KEY over expire time | 30011 | 403 |
Header X-BM-KEY is forbidden to request it | 30012 | 403 |
Request too many requests | 30013 | 429 |
Service unavailable | 30014 | 503 |
API Broker Error Code
Example: httpStatus:200, body:{"code": 1000,"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1","message": "OK","data": {}}
error message | code error code | http status code |
---|---|---|
OK | 1000 | 200 |
Bad Request | 50000 | 400 |
Out of query time range | 50041 | 400 |
You do not have permission to access the interface | 53005 | 403 |
Method Not Allowed | 57001 | 405 |
Unsupported Media Type | 58001 | 415 |
Internal Server Error | 59002 | 500 |
Questions And Answers
This is the Q&A section. If you cannot find answer to your question, please join us Telegram API Group in time.
APIKey Q&A
1. How to apply for APIKEY?
API application site: https://www.bitmart.com/api
After successful application on the website, please keep your access key, secret key and memo.
2. Can I retrieve the secret key of APIKEY?
No, you will need to create new APIKEY.
3. Is there any risk of authorizing APIKEY to a third party?
This will create some risk, and it is recommended to keep it yourself for account security.
4. Can I apply for APIKEY without binding my phone or Google?
No, you must bind more than 2 security items to apply for APIKEY.
5. When creating an APIKEY, do I have to bind an IP address?
It is not necessary. The option to bind IP when applying for APIKEY is optional, but in order to increase the security of user accounts, it is recommended to bind the IP address.
6. Will different APIKEYs in the same account return different data?
Different APIKEY data under the same account is the same.
7. How many Api Keys can I apply for in one account?
Each account can create 5 sets of Api keys, and each Api Key can be set up with 3 permissions, namely read-only, trade and withdrawal, three types of permissions.
Details:
1) Read-only permission: Read the user's own trading information, order information, account capital information, etc.
2) Trade permission: Users can place orders and cancel orders in spot and contract.
3) Withdrawal permission: The user can withdraw the balance of the wallet to the digital currency address outside the exchange.
8. How to fill information in when applying for APIKEY?
Fill in according to the prompt on the web page, and the memo can be filled in at will by the user; the secret key must be remembered, and it will be used when calling the API interface; binding IP is not required, but it is recommended for account security; API permissions can be checked based on user needs.
9. What is memo?
Memo is provided by users themselves. It will be used in the signing of the interface.
Authentication Q&A
1. What is the maximum difference between the timestamp parameter of the request interface and the time to reach the server?
Requests that differ by more than 1 minute between the timestamp and the API server time will be considered expired by the system and rejected. If there is a large time deviation between the user server and the API server, it is recommended that the user use the "Get Server Time" interface to query the API server time.
2. How to solve error "The request header "X-BM-TIMESTAMP" cannot be empty", which occurs from time to time?
First of all, it is recommended that the user print out whether the request header parameter X-BM-TIMESTAMP has a value. In addition, it is recommended that the user code be optimized. Before each request, determine whether X-BM-TIMESTAMP is empty.
3. What is the time used as the timestamp in the API?
UTC 0 timestamp。
4. Why does signature authentication always return invalid signatures?
Caused by incorrect signatures:
You can use the following SDK, the signature part has been packaged, you can directly debug and call:
If you are writing your own signature function, please refer to the following description step by step:
The request header of X-BM-SIGN is obtained by encrypting the timestamp + "#" + memo + "#" + queryString, and the secret key using the HMAC SHA256 method.
When checking, you can print out the request header information and the pre-signature string, focusing on the following points:
Whether the APIKey is correctly configured in the code
Your KEY is as follows:
API_KEY = "80618e45710812162b04892c7ee5ead4a3cc3e56";
API_SECRET = "6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9";
API_MEMO = "test001";
Please confirm that the settings are correct:
Content-Type: application/json
X-BM-KEY: 80618e45710812162b04892c7ee5ead4a3cc3e56
Check whether the string before signing conforms to the standard format, the order of all elements must be consistent, you can use the following example to compare with your string before signing:
GET
X-BM-SIGN=
echo -n '1589267764859#test001#contract_id=1&category=1' | openssl dgst -sha256 -hmac "6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9"
(stdin)= 6d5e774446448073f68e99c28ace86503451bed1fd44e43f80b9b518937c4ef1
Request:
Host: {{host}}/v1
Content-Type: application/json
X-BM-KEY: 80618e45710812162b04892c7ee5ead4a3cc3e56
X-BM-SIGN: 6d5e774446448073f68e99c28ace86503451bed1fd44e43f80b9b518937c4ef1
X-BM-TIMESTAMP: 1589267764859
GET Example: Request address is {{host}}/v1?contract_id=1&category=1, the current timestamp=1589267764859, so queryString=1589267764859#test001#contract_id=1&category=1
POST
X-BM-SIGN=
echo -n '1589267764859#test001#{"contract_id":1,"category":1,"way":1,"open_type":1,"leverage":10,"custom_id":1,"price":5000,"vol":10,"nonce":1589267764}' | openssl dgst -sha256 -hmac "6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9"
(stdin)= 595a00aa2ecbd2f7e857909497e3aa8b222da6b6055411c7f4dfce0e7dc6c6ae
Request:
HOST: {{host}}/v1
Body: {"contract_id":1,"category":1,"way":1,"open_type":1,"leverage":10,"custom_id":1,"price":5000,"vol":10,"nonce":1589267764}
Content-Type: application/json
X-BM-KEY: 80618e45710812162b04892c7ee5ead4a3cc3e56
X-BM-SIGN: 595a00aa2ecbd2f7e857909497e3aa8b222da6b6055411c7f4dfce0e7dc6c6ae
X-BM-TIMESTAMP: 1589267764859
POST Example: Request address is {{host}}/v1?contract_id=1&category=1, the current timestamp=1589267764859, so queryString=1589267764859#test001#{"contract_id":1,"category":1,"way":1,"open_type":1,"leverage":10,"custom_id":1,"price":5000,"vol":10,"nonce":1589267764}
Rate Limit Q&A
1.Is there a limit to how often the API is called per second?
There are limits, specific can see the menu bar 'Rate Limit' in each interface access frequency limit.
2."why do I have to complete a CAPTCHA?" comes up on the call
This time, the IP was intercepted because it was accessed too much from a different environment and was considered an attack by the system. It is recommended that you do not share IP and that applications be accessed using a separate IP.Second, use the browser to call the interface and select 'I am Human' to submit to unrestrict as prompted on the page.
3.How is the HTTP status code 429 created?
The request interface exceeds the access frequency limit. It is recommended to reduce the access frequency.
4.Will API call interfaces be blocked if they exceed the access frequency? How long letter?
No, just reduce the access frequency.
5.Access interface error overclocking, how to solve?
Reduce the frequency of access. Each interface of the document has a frequency description. You need to lower the request frequency to the frequency description.
Contact Us
If you have any api related questions, comments or suggestions, join us Telegram API Group: (please indicate whether it is a contract interface or a spot interface), we will reply to your problem in a timely manner.