Introduction
Getting Started
Welcome to the developer documentation.
Instruction For Calling Endpoints
developers can choose their own way to query the market, trade or withdraw according to their usage scenarios and preferences.
Contact Us
Join our Telegram API Group
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
2023-03-16
- New endpoints for submit plan order
/contract/private/submit-plan-order
- New endpoints for cancel plan order
/contract/private/cancel-plan-order
2022-09-22
- New endpoints for get contract order history
/contract/private/orders-history
- New endpoints for get contract order trade detail
/contract/private/trades
- New endpoints for get contract assets detail
/contract/private/assets-detail
- New endpoints for get k-line
/contract/public/kline
- New endpoints for get current funding rate
/contract/public/funding-rate
- New endpoints for get current position detail
/contract/private/position
2022-08-23
- New endpoints for Openinterest
/contract/public/open-interest
2022-08-18
- New endpoints for get contract detail
/contract/public/details
- New endpoints for get contract depth
/contract/public/depth
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 |
Futures Market Data
Get Contract Details
Applicable to query contract details
(Authentication type:NONE, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/contract/public/details
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/contract/public/details
Field | Type | Required? | Description |
---|---|---|---|
symbol | string | No | Symbol of the contract(like BTCUSDT) |
Response Data
Response
{
"code": 1000,
"message": "Ok",
"trace": "9b92a999-9463-4c96-91a4-93ad1cad0d72",
"data": {
"symbols": [
{
"symbol": "BTCUSDT",
"product_type": 1,
"open_timestamp": 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"
},
...
]
}
}
Field | Type | Description |
---|---|---|
symbols | list | Array of trading pair details |
Description of the trading pair details field:
Trading pair details | Type | Description |
---|---|---|
symbols | list | Array of trading pair details |
symbol | string | Symbol of the contract |
product_type | int | Contract type |
1 =perpetual |
||
2 =futures |
||
base_currency | string | Base currency |
quote_currency | string | Quote currency |
volume_precision | string | Volume Precision |
price_precision | string | Price Precision |
max_volume | string | Maximum order quantity |
min_volume | string | Minimum order quantity |
contract_size | string | Contract Size |
index_price | string | Index Price |
index_name | string | Index Name |
min_leverage | string | Minimum leverage ratio |
max_leverage | string | Maximum leverage ratio |
turnover_24h | string | 24 hours turnover |
volume_24h | string | 24 hours volume |
last_price | string | Last Price |
open_timestamp | long | Opening time for the first time |
expire_timestamp | long | Expiration time,If null is returned, it does not expire |
settle_timestamp | long | Settlement time,If null is returned, it will not be automatically settlement |
Get Market Depth
Get full depth of trading pairs.
(Authentication type:NONE, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/contract/public/depth
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/contract/public/depth?symbol=BTCUSDT
Field | Type | Required? | Description |
---|---|---|---|
symbol | string | Yes | Symbol of the contract(like BTCUSDT) |
Response Data
Response
{
"code": 1000,
"message": "Ok",
"trace": "b9bff62d-9ac8-4815-8808-8f745673c096",
"data": {
"asks": [
[
"23935.4",
"65",
"65"
]
],
"bids": [
[
"23935.4",
"65",
"65"
]
],
"timestamp": 1660285421287,
"symbol": "BTCUSDT"
}
}
Field | Type | Description |
---|---|---|
timestamp | long | Unix timestamp in milliseconds for when the last updated time occurred |
bids | list | Bid order depth |
asks | list | Ask order depth |
Market depth details:
Field | Type | Description |
---|---|---|
The first | string | The price at current depth. For example 23935.4 |
The second | string | Total quantity of current price depth. For example 65 |
The third | string | Accumulates the total quantity above (including) the current price depth. For example 65 |
Get Futures Openinterest
Applicable for querying the open interest and open interest value data of the specified contract
(Authentication type:NONE, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/contract/public/open-interest
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/contract/public/open-interest?symbol=BTCUSDT
Field | Type | Required? | Description |
---|---|---|---|
symbol | string | Yes | Symbol of the contract(like BTCUSDT) |
Response Data
Response
{
"code": 1000,
"trace": "0cc6f4c4-8b8c-4253-8e90-8d3195aa109c",
"message": "Ok",
"data": {
"timestamp": 1661239541734,
"symbol": "BTCUSDT",
"open_interest": "4134180870",
"open_interest_value": "94100888927.0433258"
}
}
Field | Type | Description |
---|---|---|
timestamp | long | Timestamp |
symbol | string | Symbol of the contract |
open_interest | string | Open interest |
open_interest_value | string | Value of open interest |
Get Current Funding Rate
Applicable for checking the current funding rate of a specified contract
(Authentication type:NONE, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/contract/public/funding-rate
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/contract/public/funding-rate?symbol=BTCUSDT
Field | Type | Required? | Description |
---|---|---|---|
symbol | string | Yes | Symbol of the contract(like BTCUSDT) |
Response Data
Response
{
"code": 1000,
"message": "Ok",
"data": {
"timestamp": 1662518172178,
"symbol": "BTCUSDT",
"rate_value": "0.000164"
},
"trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}
Field | Type | Description |
---|---|---|
timestamp | long | Timestamp |
symbol | string | Symbol of the contract |
rate_value | string | Value of current rate |
Get K-line
Applicable for querying K-line data
(Authentication type:NONE, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/contract/public/kline
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/contract/public/kline?symbol=BTCUSDT&step=5&start_time=1662518172&end_time=1662518172
Field | Type | Required? | Description |
---|---|---|---|
symbol | string | Yes | Symbol of the contract(like BTCUSDT) |
step | long | No | K-Line step, default is 1 minute. step: 1 , 3 , 5 , 15 , 30 , 60 , 120 , 240 , 360 , 720 , 1440 , 4320 , 10080 |
start_time | long | Yes | Start time. Timestamps need to be in seconds |
end_time | long | Yes | End time. Timestamps need to be in seconds |
Response Data
Response
{
"code": 1000,
"trace": "0cc6f4c4-8b8c-4253-8e90-8d3195aa109c",
"message": "Ok",
"data": {
"timestamp": 1662518160,
"open_price": "100",
"close_price": "120",
"high_price": "130",
"low_price": "90",
"volume": "941008"
}
}
Field | Type | Description |
---|---|---|
timestamp | long | Time Window |
open_price | string | Opening Price |
close_price | string | Closing Price |
high_price | string | Highest Price |
low_price | string | Lowest Price |
volume | string | Turnover |
Futures Account Data
Get Contract Assets Detail
Applicable for querying user contract asset details
(Authentication type:KEYED, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/contract/private/assets-detail
Request Limit
Request Parameter
Request None
curl 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"
}
Field | Type | Description |
---|---|---|
currency | string | Currency |
position_deposit | string | Position margin |
frozen_balance | string | Transaction freeze amount |
available_balance | string | Available amount |
equity | string | Total equity |
unrealized | string | Unrealized P&L |
Futures Trading
Get Order Detail
Applicable for querying contract order detail
(Authentication type:KEYED, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/contract/private/order
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/contract/private/order?symbol=BTCUSDT&order_id=220609666322019
Field | Type | Required? | Description |
---|---|---|---|
symbol | string | Yes | Symbol of the contract(like BTCUSDT) |
order_id | string | Yes | Order ID |
Response Data
Response
{
"code": 1000,
"message": "Ok",
"data": {
"order_id": "220906179895578",
"price": "1",
"size": "1000",
"symbol": "BTCUSDT",
"state": 2,
"side": 1,
"type": "limit",
"leverage": "5",
"open_type": "isolated",
"deal_avg_price": "0",
"deal_size": "1000",
"create_time": 1662368173000,
"update_time": 1662368173000
},
"trace": "638d5048-ad21-4a4b-9365-d0756fbfc7ba"
}
Field | Type | Description |
---|---|---|
symbol | string | Symbol of the contract |
order_id | string | Order ID |
side | int | Order side |
1 =buy_open_long |
||
2 =buy_close_short |
||
3 =sell_close_long |
||
4 =sell_open_short |
||
type | string | Order type limit or market |
leverage | string | Leverage order multipliers |
open_type | string | Open type cross or isolated |
deal_avg_price | string | Average deal price |
deal_size | string | Deal amount |
price | string | Consignment price |
state | int | Order status |
2 =status_check |
||
4 =status_finish |
||
create_time | long | Create time |
update_time | long | Update time |
Get Order History
Applicable for querying contract order history
(Authentication type:KEYED, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/contract/private/order-history
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/contract/private/order-history?symbol=BTCUSDT&start_time=1662368173&end_time=1662368179
Field | Type | Required? | Description |
---|---|---|---|
symbol | string | Yes | Symbol of the contract(like BTCUSDT) |
start_time | timestamp | No | Start time, default is the last 7 days |
end_time | timestamp | No | End time, default is the last 7 days |
Response Data
Response
{
"code": 1000,
"message": "Ok",
"data": {
"order_id": "220906179895578",
"price": "1",
"size": "1000",
"symbol": "BTCUSDT",
"state": 2,
"side": 1,
"type": "limit",
"leverage": "5",
"open_type": "isolated",
"deal_avg_price": "0",
"deal_size": "1000",
"create_time": 1662368173000,
"update_time": 1662368173000
},
"trace": "638d5048-ad21-4a4b-9365-d0756fbfc7ba"
}
Field | Type | Description |
---|---|---|
symbol | string | Symbol of the contract |
order_id | string | Order ID |
side | int | Order side |
1 =buy_open_long |
||
2 =buy_close_short |
||
3 =sell_close_long |
||
4 =sell_open_short |
||
type | string | Order type limit or market |
leverage | string | Leverage order multipliers |
open_type | string | Open type cross or isolated |
deal_avg_price | string | Average deal price |
deal_size | string | Deal amount |
price | string | Consignment price |
state | int | Order status |
2 =status_check |
||
4 =status_finish |
||
create_time | long | Create time |
update_time | long | Update time |
Get Current Position Detail
Applicable for checking the position details a specified contract
(Authentication type:KEYED, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/contract/private/position
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/contract/private/position?symbol=BTCUSDT
Field | Type | Required? | Description |
---|---|---|---|
symbol | string | Yes | Symbol of the contract(like BTCUSDT) |
Response Data
Response
{
"code": 1000,
"message": "Ok",
"data": [
{
"symbol": "BTCUSDT",
"leverage": "3.255031032814235929",
"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",
"current_amount": "899",
"unrealized_value": "1903.956643943943943944339",
"realized_value": "55.049173071454605573",
"position_type": 2
}
],
"trace": "ae96cae5-1f09-4ea5-971e-4474a6724bc8"
}
Field | Type | Description |
---|---|---|
leverage | string | Leverage multiplier |
symbol | string | Symbol of the contract |
current_fee | string | Current position fees |
open_timestamp | long | Opening timestamp |
current_value | string | Current position value |
mark_price | string | Marker price |
position_value | string | Position value |
close_avg_price | string | Close volume |
close_vol | string | Close average price |
position_cross | string | Margin calls to positions |
maintenance_margin | string | Maintenance Margin |
current_amount | string | Current position amount |
unrealized_value | string | Unrealized value |
realized_value | string | Realized position value |
position_type | int | position type |
1 =long |
||
2 =short |
||
timestamp | long | Current timestamp |
Get Order Trade Detail
Applicable for querying contract order trade detail
(Authentication type:KEYED, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/contract/private/trades
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/contract/private/trades?symbol=BTCUSDT&start_time=1662368173&end_time=1662368179
Field | Type | Required? | Description |
---|---|---|---|
symbol | string | Yes | Symbol of the contract(like BTCUSDT) |
start_time | timestamp | No | Start time, default is the last 7 days |
end_time | timestamp | No | End time, default is the last 7 days |
Response Data
Response
{
"code": 1000,
"message": "Ok",
"data": [{
"order_id": "220921197409432",
"trade_id": "1141853921",
"symbol": "BTCUSDT",
"side": 1,
"price": "19313.3",
"vol": "108",
"exec_type": "Maker",
"profit": false,
"realised_profit": "-0.00832",
"paid_fees": "0",
"create_time": 1663663818589
}],
"trace": "638d5048-ad21-4a4b-9365-d0756fbfc7ba"
}
Field | Type | Description |
---|---|---|
symbol | string | Symbol of the contract |
order_id | string | Order ID |
trade_id | string | Trade detail ID |
side | int | Order side |
1 =buy_open_long |
||
2 =buy_close_short |
||
3 =sell_close_long |
||
4 =sell_open_short |
||
price | string | Deal price |
vol | string | Deal vol |
profit | boolean | Profitable or not |
exec_type | string | Liquidity type Taker or Maker |
realised_profit | string | realised profit |
paid_fees | string | paid fees |
create_time | long | Create time |
Submit an Order
Applicable for placing contract orders
(Authentication type:SIGNED, See Interface Permission)
Request Format
POST https://api-cloud.bitmart.com/contract/private/submit-order
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/contract/private/submit-order
{
"symbol":"ETHUSDT",
"side":4,
"mode":1,
"type":"limit",
"leverage":"1",
"open_type":"isolated",
"size":10,
"price":"2000"
}
Field | Type | Required? | Description |
---|---|---|---|
symbol | string | Yes | Symbol of the contract(like BTCUSDT) |
type | string | No | Order type limit or market . The default value is limit |
side | int | Yes | Order side |
1 =buy_open_long |
|||
2 =buy_close_short |
|||
3 =sell_close_long |
|||
4 =sell_open_short |
|||
leverage | string | Yes | Order leverage |
open_type | string | Yes | Open type cross or isolated . required at close position |
mode | int | No | Order mode, default value 1 |
1 =GTC |
|||
2 =FOK |
|||
3 =IOC |
|||
4 =Maker Only |
|||
price | string | Yes | Order price, required at limit order |
size | int | Yes | Order size. Size refers to the order amount in the unit of contracts |
Response Data
Response
{
"code": 1000,
"message": "Ok",
"data": {
"order_id": "220609666322019"
},
"trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}
Field | Type | Description |
---|---|---|
order_id | string | Order ID |
Cancel an Order
Applicable for canceling a specific contract order
(Authentication type:SIGNED, See Interface Permission)
Request Format
POST https://api-cloud.bitmart.com/contract/private/cancel-order
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/contract/private/cancel-order
{
"symbol":"ETHUSDT",
"order_id": "220906179559421"
}
Field | Type | Required? | Description |
---|---|---|---|
symbol | string | Yes | Symbol of the contract(like BTCUSDT) |
order_id | string | Yes | Order ID |
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
Applicable for batch order cancellation under a particular contract
(Authentication type:SIGNED, See Interface Permission)
Request Format
POST https://api-cloud.bitmart.com/contract/private/cancel-orders
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/contract/private/cancel-orders
{
"symbol":"ETHUSDT"
}
Field | Type | Required? | Description |
---|---|---|---|
symbol | string | Yes | Symbol of the contract(like BTCUSDT) |
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 an Order
Applicable for placing contract plan orders
(Authentication type:SIGNED, See Interface Permission)
Request Format
POST https://api-cloud.bitmart.com/contract/private/submit-plan-order
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/contract/private/submit-plan-order
{
"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"
}
Field | Type | Required? | Description |
---|---|---|---|
symbol | string | Yes | Symbol of the contract(like BTCUSDT) |
type | string | No | Order type limit or market . The default value is limit |
side | int | Yes | Order side |
1 =buy_open_long |
|||
2 =buy_close_short |
|||
3 =sell_close_long |
|||
4 =sell_open_short |
|||
leverage | string | Yes | Order leverage |
open_type | string | Yes | Open type cross or isolated . required at close position |
mode | int | No | Order mode, default value 1 |
1 =GTC |
|||
2 =FOK |
|||
3 =IOC |
|||
4 =Maker Only |
|||
size | int | Yes | Order size. Size refers to the order amount in the unit of contracts |
trigger_price | string | Yes | Trigger price |
executive_price | string | No | Order price, required at limit order |
price_way | int | Yes | Price way |
1 =price_way_long |
|||
2 =price_way_short |
|||
price_type | int | Yes | Trigger price type |
1 =last_price |
|||
2 =fair_price |
Response Data
Response
{
"code": 1000,
"message": "Ok",
"data": {
"order_id": "220609666322019"
},
"trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}
Field | Type | Description |
---|---|---|
order_id | string | Order ID |
Cancel Plan an Order
Applicable for canceling a specific contract plan order
(Authentication type:SIGNED, See Interface Permission)
Request Format
POST https://api-cloud.bitmart.com/contract/private/cancel-plan-order
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/contract/private/cancel-plan-order
{
"symbol":"ETHUSDT",
"order_id": "220906179559421"
}
Field | Type | Required? | Description |
---|---|---|---|
symbol | string | Yes | Symbol of the contract(like BTCUSDT) |
order_id | string | Yes | Order ID |
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": {
}
}
WebSocket Subscription
Overview
Address
Public Channel wss://openapi-ws.bitmart.com/api?protocol=1.1
Private Channel wss://openapi-ws.bitmart.com/user?protocol=1.1
Format
Request Format
{"action":"<operation>", "args":["<topic1>","<topic2>"]}
Terminology
operation: Request action, value
Subscribe=subscribe
Unsubscribe=unsubscribe
Login=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 can filter data, refer to the description of each channel for details
Example: futures/klineBin1m:BTCUSDT: which means klineBin data of contract trading pair BTCUSDT
error: When sending a subscription or login operation generates an error, the error code will be returned
Successful Response Format
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"]}}
When success field of return data is true, it indicates success
Failed Response Format
Failed Response Format
{"action":"subscribe","group":"Depth:1","success":false,"error":"authentication is temporarily unavailable"}
When success field of return data is false, it indicates failure
Stay Connected And Limit
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 5s. It is recommended that the user do the following:
1.After each message is received, the user sets a timer for N seconds (N<5).
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:
The following is the data format of ping:
- Standard Ping frame
ws.send(new PingWebSocketFrame();
- Ping Text
{"subscribe":"ping"}
- Pong Text
{"group":"System","data":"pong"}
Connection Limit
Public Channel
Channel | limit |
---|---|
Numbers of connections per IP. | 10 |
Times of connections request per minute | 30 |
Minimum message pushing frequency | 0.5 second |
Message limit sent to the server | 100/10 seconds |
Maximum number of batch subscriptions at a time | 20 topics |
Subscription limit for each connection | 100 topics |
Private Channel
Channel | limit |
---|---|
Numbers of connections per IP. | 10 |
Times of connections request per minute | 30 |
Minimum message pushing frequency | 0.5 |
Message limit sent to the server | 100/10 seconds |
Maximum number of batch subscriptions at a time | 20 |
Subscription limit for each connection | 100 |
Lifeless connection
Connection that do not send task subscription data within 5 seconds will be considered lifeless and the server will close the connection.
WebSocket Subscription
Users can subscribe to one or more channels, and the total length of multiple channels cannot exceed 4096 bytes
subscribe
{"action":"subscribe","args":["futures/depth50:BTCUSDT","futures/ticker"]}
Parameter Instructions
- action = subscribe
- 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
Request
{"action":"subscribe","args":["futures/depth50:BTCUSDT","futures/ticker"]}
Response
{"action":"subscribe","group":"futures/ticker","success":true,"request":{"action":"subscribe","args":["futures/ticker"]}}
{"action":"subscribe","group":"futures/depth50:BTCUSDT","success":true,"request":{"action":"subscribe","args":["futures/depth50:BTCUSDT"]}}
{"action":"subscribe","group":"futures/klineBin1m:BTCUSDT","success":true,"request":{"action":"subscribe","args":["futures/klineBin1m:BTCUSDT"]}}
Unsubscribe
Cancel subscription to one or more channels
unsubscribe
{"action": "unsubscribe", "args": ["<topic>"]}
Parameter Instruction
- action = unsubscribe
- 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
Request
{"action": "unsubscribe", "args": ["futures/klineBin1m:BTCUSDT"]}
Response
{"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, without user login, sent once in 1 second after subscription.
Pushing Rules
- No user login required
- After subscribing, the current data will be returned directly, and then the changes will be pushed
Example
Request
{"action":"subscribe","args":["futures/ticker"]}
futures/ticker
is the channel name
Response
{
"group":"futures/ticker",
"data":{
"symbol":"BTCUSDT",
"volume_24":"117387.58",
"fair_price":"146.24",
"last_price":"146.24",
"range":"147.17"
}
}
Parameter Type Description:
Parameter | Type | Description |
---|---|---|
symbol | string | Symbol of the contract(like BTCUSDT) |
last_price | string | Latest Price |
volume_24 | string | Volume of 24-hour transactions |
range | string | Up or Down |
fair_price | string | Fair Price |
【Public】Depth Channel
Get depth data and push updates as soon as they are available without user login.
Pushing Rules
- No user login required
- After subscribing, the current data will be returned directly, and then the changes will be pushed
Example
Request
{"action":"subscribe","args":["futures/depth20:BTCUSDT"]}
futures/depth20
is the channel name and BTCUSDT
is the trading side
Channel List
Channel Name | Description |
---|---|
futures/depth5 | 5 Level Depth Channel |
futures/depth20 | 20 Level Depth Channel |
futures/depth50 | 50 Level Depth Channel |
Response
{
"group":"futures/depth20:BTCUSDT",
"data":{
"symbol":"BTCUSDT",
"way":1,
"depths":[
{"price":"5","vol":"97"}
],
"ms_t": 1542337219120
}
}
Parameter Type Description:
Parameter | Type | Description |
---|---|---|
symbol | string | Symbol of the contract(like BTCUSDT ) |
way | long | Trading side |
1 =ask |
||
2 =bid |
||
depths | list | Array of depth details |
ms_t | long | Timestamp (in millisecond) |
Instruction
Description of the depth details field:
depth details | Type | Description |
---|---|---|
price | string | price |
vol | string | volume |
【Public】Trade Channel
Get trade data and push updates as soon as they are available without user login.
Pushing Rules
- No user login required
- After subscribing, the current data will be returned directly, and then the changes will be pushed
Example
Request
{"action":"subscribe","args":["futures/trade:BTCUSDT"]}
futures/trade
is the channel name and BTCUSDT
is the trading side
Response
{
"group":"futures/trade:BTCUSDT",
"data":[{
"symbol":"BTCUSDT",
"deal_price":"117387.58",
"deal_vol":"1445",
"created_at":"2023-02-24T07:54:11.124940968Z"
}]
}
Instruction
Description of the depth details field:
depth details | Type | Description |
---|---|---|
symbol | string | symbol |
deal_price | string | deal price |
deal_vol | string | deal vol |
created_at | string | create time |
【Public】klineBin Channel
Get individual contract K-line data and push updates as soon as they are available without user login.
Pushing Rules
- No user login required
- After subscribing, the current data will be returned directly, and then the changes will be pushed
Example
Request
{"action":"subscribe","args":["futures/klineBin1m:BTCUSDT"]}
futures/klineBin1m
is the channel name, BTCUSDT
is the trading pair
Channel List
Channel Name | Description |
---|---|
futures/klineBin1m | 1-min klineBin Channel |
futures/klineBin5m | 5-min klineBin Channel |
futures/klineBin15m | 15-min klineBin Channel |
futures/klineBin30m | 30-min klineBin Channel |
futures/klineBin1H | 1-hour klineBin Channel |
futures/klineBin2H | 2-hour klineBin Channel |
futures/klineBin4H | 4-hour klineBin Channel |
futures/klineBin1D | 1-day klineBin Channel |
futures/klineBin1W | 1-week klineBin Channel |
Response
{
"group":"futures/klineBin1m:BTCUSDT",
"data":{
"symbol":"BTCUSDT",
"o":"146.24",
"h":"146.24",
"l":"146.24",
"c":"146.24",
"v":"146"
}
}
Parameter Type Description:
Parameter | Type | Description |
---|---|---|
symbol | string | Symbol of the contract(like BTCUSDT) |
o | string | Opening Price |
h | string | Highest Price |
l | string | Lowest Price |
c | string | Closing Price |
v | string | Turnover |
【Private】Login
Login Subscription Format
Request
{"action":"access","args":["<API_KEY>","<timestamp>","<sign>","<dev>"]}
API_KEY: The user's API key
timestamp: Timestamp, the unit is milliseconds, it will expire after 60 seconds
sign: Signature, sign=CryptoJS.HmacSHA256("
dev: Device, web eg.
Example
sign
sign=
echo -n '1589267764859#test001#bitmart.WebSocket' | openssl dgst -sha256 -hmac "6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9"
(stdin)= 3ceeb7e1b8cb165a975e28a2e2dfaca4d30b358873c0351c1a071d8c83314556
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";
If success field of return data is true, it indicates success
【Private】Assets Channel
Asset balance change channel, any changes will be pushed immediately.
Example
Request
{
"action": "subscribe",
"args":["futures/asset:USDT", "futures/asset:BTC", "futures/asset:ETH"]
}
Supported asset types for subscription are: USDT (U-native), BTC (coin-native), ETH (coin-native)
Return
{
"group": "futures/asset:BTC",
"data": {
"currency": "BTC",
"available_balance": "1000",
"position_deposit": "1000",
"frozen_balance": "1000"
}
}
Parameter Type Description:
Parameter | Type | Description |
---|---|---|
currency | string | Currency |
available_balance | string | Available Amount |
position_deposit | string | Position Margin |
frozen_balance | string | Transaction Frozen Amount |
【Private】Position Channel
Position channel, any changes will be pushed immediately.
Push rules
- user login required
- 10 seconds timed push
Example
Request
{
"action": "subscribe",
"args":["futures/position"]
}
return
{
"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
}
]
}
Parameter Type Description:
Parameter | Type | Description |
---|---|---|
symbol | string | Contract pair (e.g. BTCUSDT) |
hold_volume | string | Number of positions |
position_type | int | Position type |
1 =long |
||
2 =short |
||
open_type | int | Open position type |
1 =isolated |
||
2 =cross |
||
frozen_volume | string | Frozen volume |
close_volume | string | Close volume |
hold_avg_price | string | Average price of a position |
close_avg_price | string | Average close price |
open_avg_price | string | Average opening price |
liquidate_price | string | Liquidation price |
create_time | timestamp | Create time |
update_time | timestamp | Update time |
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 |
Contract API Error Code
Example: httpStatus:400, body:{"code": 40001, "message":"out_trade_no not found", "trace":"8bynjk-nmoew-sd1221-csd-123" }
errMsg error message | code error code | http status code |
---|---|---|
OK | 1000 | 200 |
Cloud account not found | 40001 | 400 |
out_trade_no not found | 40002 | 400 |
out_trade_no already existed | 40003 | 400 |
Cloud account count limit | 40004 | 400 |
Transfer vol precision error | 40005 | 400 |
Invalid ip error | 40006 | 400 |
Parse parameter error | 40007 | 400 |
Check nonce error | 40008 | 400 |
Check ver error | 40009 | 400 |
Not found func error | 40010 | 400 |
Invalid request | 40011 | 400 |
System error | 40012 | 400 |
Access too often" CLIENT_TIME_INVALID, "Please check your system time. | 40013 | 400 |
This contract is offline | 40014 | 400 |
This contract's exchange has been paused | 40015 | 400 |
This order would trigger user position liquidate | 40016 | 400 |
It is not possible to open and close simultaneously in the same position | 40017 | 400 |
Your position is closed | 40018 | 400 |
Your position is in liquidation delegating | 40019 | 400 |
Your position volume is not enough | 40020 | 400 |
The position is not exsit | 40021 | 400 |
The position is not isolated | 40022 | 400 |
The position would liquidate when sub margin | 40023 | 400 |
The position would be warnning of liquidation when sub margin | 40024 | 400 |
The position’s margin shouldn’t be lower than the base limit | 40025 | 400 |
You cross margin position is in liquidation delegating | 40026 | 400 |
You contract account available balance not enough | 40027 | 400 |
Your plan order's count is more than system maximum limit. | 40028 | 400 |
The order's leverage is too large. | 40029 | 400 |
The order's leverage is too small. | 40030 | 400 |
The deviation between current price and trigger price is too large. | 40031 | 400 |
The plan order's life cycle is too long. | 40032 | 400 |
The plan order's life cycle is too short. | 40033 | 400 |
The Symbol is not exist | 40034 | 400 |
The order is not exist | 40035 | 400 |
The order status is invalid | 40036 | 400 |
The order id is not exist | 40037 | 400 |
The k-line step is invalid | 40038 | 400 |
The timestamp is invalid | 40039 | 400 |
The order leverage is invalid | 40040 | 400 |
The order side is invalid | 40041 | 400 |
The order type is invalid | 40042 | 400 |
The order precision is invalid | 40043 | 400 |
The order range is invalid | 40044 | 400 |
The order open type is invalid | 40045 | 400 |
The account is not opened futures | 40046 | 403 |