Change Log
2023-05-18
- New endpoints for transfer
/account/v1/transfer-contract
/account/v1/transfer-contract-list
2023-03-23
- New endpoints for websocket order notify
/contract/public/websocket/order
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-31
- New websocket for public data
/contract/public/websocket
2022-08-23
- New endpoints for get current funding rate of a specified contract
/contract/public/open-interest
2022-08-18
- New endpoints for get contract detail
/contract/public/details
- New endpoints for get contract depth
/contract/public/depth
Introduction
API Key Create
- Many APIs require an API Access Key for access. Please refer to this page to set up.
- When setting up an API Access Key, it is recommended to set up an IP access whitelist for security purposes.
- Never give your API Access key/secret key to anyone.
After creating an API Key, you will receive three pieces of information that you must remember:
- Access Key: represents the identity of the account, this is your api key
- Secret Key: used for API signature
- Memo: used for API signature
The Access Key and Secret Key will be randomly generated and provided by BitMart, and the Memo will be provided by you to ensure the security of API access.
API Key Permission Settings
- The default permission of a newly created API is
Read-Only
. - To withdraw funds through the API, you need to modify the permissions in the UI and select
Withdraw
. - Permission descriptions:
Read-only
(query spot trading orders, query contract trading orders, query funds)Spot-Trade
(place orders, cancel orders)Withdraw
(withdraw funds)Margin-Trade
(repayment, borrowing, placing orders, etc.)Contract-Trade
(long position, short position, closing position, etc.)
Read-Only Permissions:
API Name | Description | Authentication Type |
---|---|---|
/account/v1/wallet | Query account assets | KEYED |
/account/v1/deposit/address | Query deposit addresses for each currency | KEYED |
/account/v2/deposit-withdraw/history | Query deposit and withdrawal history | KEYED |
/account/v1/deposit-withdraw/detail | Query deposit and withdrawal details | KEYED |
/spot/v1/wallet | Query wallet balance for all currencies | KEYED |
/spot/v1/order_detail | Query order details | KEYED |
/spot/v2/order_detail | Query order details | KEYED |
/spot/v1/orders | Query user's recent orders | KEYED |
/spot/v2/orders | Query user's recent orders | KEYED |
/spot/v3/orders | Query user's recent orders | KEYED |
/spot/v1/trades | Query user's trade history | KEYED |
/spot/v2/trades | Query user's trade history | KEYED |
/spot/v4/query/order | Query order by id (v4) | SIGNED |
/spot/v4/query/client-order | Query order by client order id (v4) | SIGNED |
/spot/v4/query/open-orders | Current open orders (v4) | SIGNED |
/spot/v4/query/history-orders | Account orders (v4) | SIGNED |
/spot/v4/query/trades | Account trade list (v4) | SIGNED |
/spot/v4/query/order-trades | Order trade list(v4) | SIGNED |
/spot/v1/user_fee | Query basic fee rate for current user | KEYED |
/spot/v1/trade_fee | Query fee rate for a specific trading pair for current user | KEYED |
/spot/v1/margin/isolated/pairs | Query loan interest rate and limit for a trading pair | KEYED |
/spot/v1/margin/isolated/account | Query isolated margin account information | KEYED |
/spot/v1/margin/isolated/borrow_record | Query isolated margin borrowing record | KEYED |
/spot/v1/margin/isolated/repay_record | Query isolated margin repayment record | KEYED |
/contract/private/order | Query contract order details | KEYED |
/contract/private/order-history | Query contract order history | KEYED |
/contract/private/trades | Query contract trade details | KEYED |
/contract/private/assets-detail | Query contract asset details | KEYED |
/contract/private/position | Query position details | KEYED |
Withdraw Permissions:
API Name | Description | Authentication Type |
---|---|---|
/account/v1/withdraw/charge | Query withdrawal limits | KEYED |
/account/v1/withdraw/apply | Apply for withdrawal | SIGNED |
Spot-Trade Permissions:
API Name | Description | Authentication Type |
---|---|---|
/spot/v1/submit_order | Place an order | SIGNED |
/spot/v2/submit_order | Place an order | SIGNED |
/spot/v1/batch_orders | Place multiple orders | SIGNED |
/spot/v2/batch_orders | Place multiple orders | SIGNED |
/spot/v1/cancel_order | Cancel an unfinished order | SIGNED |
/spot/v3/cancel_order | Cancel an unfinished order | SIGNED |
/spot/v1/cancel_orders | Cancel all unfinished orders for a specified trading pair and direction | SIGNED |
Margin-Trade Permissions:
API Name | Description | Authentication Type |
---|---|---|
/spot/v1/margin/submit_order | Margin order placement | SIGNED |
/spot/v1/margin/isolated/transfer | Transfer funds between margin and spot accounts | SIGNED |
/spot/v1/margin/isolated/borrow | Isolated margin borrowing | SIGNED |
/spot/v1/margin/isolated/repay | Repay isolated margin debt | SIGNED |
Contract-Trade Permissions:
API Name | Description | Authentication Type |
---|---|---|
/contract/private/submit-order | Place an order for a futures contract | SIGNED |
/contract/private/cancel-order | Cancel a single futures order | SIGNED |
/contract/private/cancel-orders | Batch cancel futures orders | SIGNED |
/contract/private/submit-plan-order | Place a batch order for futures contracts | SIGNED |
/contract/private/cancel-plan-order | Batch cancel futures orders | SIGNED |
/account/v1/transfer-contract | Future account transfer | SIGNED |
/account/v1/transfer-contract-list | Get Future account transfer list | SIGNED |
API Library
In order to facilitate access, we provide SDK in some languages for reference. For more programming codes, please refer to the Quick Start API on the page.
1. BitMart Golang SDK
The Websocket code quickly implements a lightweight code library, including HTTP requests for all BitMart API interfaces and subscriptions to websocket public and private channels, and can be used after being cloned. This is written specifically for Golang developers.
https://github.com/bitmartexchange/bitmart-go-sdk-api
2. BitMart Python SDK
The Websocket code quickly implements a lightweight code library, including HTTP requests for all BitMart API interfaces and subscriptions to websocket public and private channels, and can be used after being cloned. This is written specifically for Python developers.
https://github.com/bitmartexchange/bitmart-python-sdk-api
3. BitMart Java SDK
The Websocket code quickly implements a lightweight code library, including HTTP requests for all BitMart API interfaces and subscriptions to websocket public and private channels, and can be used after being cloned. This is written specifically for Java developers.
https://github.com/bitmartexchange/bitmart-java-sdk-api
4. BitMart PHP SDK
The Websocket code quickly implements a lightweight code library, including HTTP requests for all BitMart API interfaces and subscriptions to websocket public and private channels, and can be used after being cloned. This is written specifically for PHP developers.
https://github.com/bitmartexchange/bitmart-php-sdk-api
5. BitMart PostMan API
There is now a BitMart Postman collection containing the API endpoints for quick and easy use.
FAQ
Here are some frequently asked questions.
Q1. Will different API KEY in the same account return different data?
Q2. How to fill information in when applying for APIKEY?
Q3. How is the HTTP status code 429 created?
Q4. Using ccxt, the API KEY is correctly filled in, but it will also prompt 'message': 'Header X-BM-SIGN is wrong'
Q5. The program I wrote myself always prompts 'message': 'Header X-BM-SIGN is wrong'
Q6. Where is the location of BitMart servers?
Q7. When will the VIP fee I applied for take effect?
Contact Us
- Get support in our Telegram group BitMart API Club
- Please take 1 minute to help us improve: API Satisfaction Survey
Basic Information
API Basic Information
- This article lists the rest baseurl of the interfaces: https://api-cloud.bitmart.com
- All interface responses are in JSON format.
Request Parameter Settings
- For
GET
andDELETE
method interfaces, parameters must be sent in the query string, i.e., the parameters concatenated after theURL?
. - For
POST
andPUT
method interfaces, parameters are sent in the request body in JSON format.
HTTP Response Codes
- HTTP 4XX Error codes are used to indicate wrong request content, behavior, and format. The problem is from the request sender.
- HTTP 403 The error code indicates a violation of the restriction (prohibited call).
- HTTP 429 The error code indicates that the access frequency is overrun and the IP will be blocked.
- HTTP 418 The error code indicates that the IP has been blocked after error code 429.
- HTTP 5XX Error codes are used to indicate problems with BitMart server.
API Returned Codes
code
Error codemessage
Error descriptiontrace
Event tracking ID for each request, which is returned by the server for every requestdata
User Data
For details, please refer to Error Code List
Signature
The authentication type of each API endpoint will be indicated.
If it is marked as SIGNED
,it means that the endpoint requires a signature to access.
If it is marked as KEYED
, it means that the endpoint only requires an API Access KEY to be set in the request header.
Authentication Type
NONE
: Public endpoint, accessible to anyoneKEYED
: Endpoint requires a valid X-BM-KEY to be set in the request headerSIGNED
: Endpoint requires a valid X-BM-KEY and X-BM-SIGN signature to be set in the request header
1. Setting Request Parameters
1.1 Set Request Header Key
Create X-BM-TIMESTAMP
// Java
System.currentTimeMillis();
// Python
int(time.time() * 1000)
// Golang
time.Now().UnixNano() / int64(time.Millisecond)
// Nodejs & TypeScript
Date.now();
// Javascript
Date.now();
// PHP
round(microtime(true) * 1000)
// C#
DateTimeOffset.UtcNow.ToUnixTimeMilliseconds()
X-BM-KEY
(Your created API Access KEY)X-BM-SIGN
(Signature using Sha-256)X-BM-TIMESTAMP
(Current timestamp in milliseconds when the request is sent)
1.2 Set Request Body Params
- For
GET/DELETE
requests, the query string is in form format, such assymbol=BMX&side=BUY
. - For
POST/PUT
requests, the query string is in JSON format, such as{"symbol":"BMX","side":"BUY"}
.
2. Example
Shell Example
echo -n '1589793796145#test001#{"symbol":"BTC_USDT","price":"8600","count":"100"}' | openssl dgst -sha256 -hmac "6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9"
(stdin)= c31dc326bf87f38bfb49a3f8494961abfa291bd549d0d98d9578e87516cee46d
curl --location --request POST 'localhost:8080/spot/v1/test-post'
--header 'Content-Type: application/json'
--header 'X-BM-KEY: 80618e45710812162b04892c7ee5ead4a3cc3e56'
--header 'X-BM-SIGN: c31dc326bf87f38bfb49a3f8494961abfa291bd549d0d98d9578e87516cee46d'
--header 'X-BM-TIMESTAMP: 1589793796145'
--d '{"symbol":"BTC_USDT","price":"8600","count":"100"}'
- Request API: /spot/v1/test-post (SIGNED)
- Request method: POST
- Current timestamp: timestamp=
1589793796145
- Request body:
{"symbol":"BTC_USDT","price":"8600","count":"100"}
Then set the following:
- X-BM-TIMESTAMP=
1589793796145
- X-BM-KEY=
Your_api_access_key
- X-BM-SIGN= hmac_sha256(
Your_api_secret_key
,X-BM-TIMESTAMP
+ '#' +Your_api_memo
+ '#' +{"symbol":"BTC_USDT","price":"8600","count":"100"}
)
Assuming the key you applied for is as follows:
accessKey
=80618e45710812162b04892c7ee5ead4a3cc3e56secretKey
=6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9memo
=test001
then the right side is a complete request
You can also refer to the SDK or Quick Start API below to implement
Rate Limit
The speed of the public interface is limited according to the IP, and the speed of the private interface is limited according to the API KEY. When the requests exceed the rate limit, the 429 status will be returned: the request is too frequent.
The specific interface limits are as follows:
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 | |
/account/v1/transfer-contract | Transfer | X-BM-KEY | 1 times/2s | |
/account/v1/transfer-contract-list | Get Transfer List | X-BM-KEY | 1 times/2s |
REST API
Speed limit judgment:
Each call to the interface will return 3 Response Headers with limit tags, as shown below:
Example:
X-BM-RateLimit-Remaining: 10
X-BM-RateLimit-Limit: 600
X-BM-RateLimit-Reset: 60
The above setting means that it can be called 600 times within 60 seconds, and currently has been called 10 times
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 |
Futures Public API Definitions
Field description
Field description
symbol
is the name of the trading pair, consisting of the trading currency and the quote currency. Taking BTCUSDT as an example, BTC is the transaction currency, USDT is the pricing currency, and the transaction pair is mainly used in contract transactionsorder_id
order number, the order ID of the same currency pair of each business line is unique
Order State(Field:state)
2
=status_check4
=status_finish
Order Side(Field:side)
1
=buy_open_long2
=buy_close_short3
=sell_close_long4
=sell_open_short
Position(Field:position_type)
1
=long2
=short
Order Type(Field:type)
limit
market
liquidate
bankruptcy
Open Type(Field:open_type)
cross
isolated
Order Mode(Field:mode)
1
=GTC (Good Till Cancel)2
=FOK (Fill or Kill)3
=IOC (Immediate or Cancel)4
=Maker Only (Good Till Crossing)
Timestamp
All the times returned by the system are in the form of timestamps.
Futures Market Data
Get Contract Details
Applicable to query contract details
Request URL
GET https://api-cloud.bitmart.com/contract/public/details
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/contract/public/details?symbol=BTCUSDT
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",
"funding_rate": "0.0001",
"expected_funding_rate": "0.00011",
"open_interest": "4134180870",
"open_interest_value": "94100888927.0433258"
},
...
]
}
}
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 |
funding_rate | String | current funding rate |
expected_funding_rate | String | expect funding rate |
open_interest | String | Open interest |
open_interest_value | String | Value of open interest |
Get Market Depth
Get full depth of trading pairs.
Request URL
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
Request URL
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
Request URL
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",
"expected_rate": "0.000164"
},
"trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}
Field | Type | Description |
---|---|---|
timestamp | Long | Timestamp |
symbol | String | Symbol of the contract |
rate_value | String | Funding rate of the previous period |
expected_rate | String | Funding rate for the next period |
Get K-line
Applicable for querying K-line data
Request URL
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 (KEYED)
Applicable for querying user contract asset details
Request URl
GET https://api-cloud.bitmart.com/contract/private/assets-detail
Request Limit
Request Parameter
Request None
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/contract/private/assets-detail
Response Data
Response
{
"code": 1000,
"message": "Ok",
"data": [
{
"currency": "USDT",
"position_deposit": "100",
"frozen_balance": "100",
"available_balance": "100",
"equity": "100",
"unrealized": "100"
},
{
"currency": "BTC",
"available_balance": "0",
"frozen_balance": "0",
"unrealized": "0",
"equity": "0",
"position_deposit": "0"
},
{
"currency": "ETH",
"available_balance": "0",
"frozen_balance": "0",
"unrealized": "0",
"equity": "0",
"position_deposit": "0"
}
],
"trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}
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 (KEYED)
Applicable for querying contract order detail
Request URL
GET https://api-cloud.bitmart.com/contract/private/order
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
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 - market - liquidate - bankruptcy |
leverage | String | Leverage order multipliers |
open_type | String | Open type - cross - 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 (KEYED)
Applicable for querying contract order history
Request URL
GET https://api-cloud.bitmart.com/contract/private/order-history
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/contract/private/order-history?symbol=BTCUSDT&start_time=1662368173&end_time=1662368179
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Symbol of the contract(like BTCUSDT) |
start_time | Long | No | Start time, default is the last 7 days |
end_time | Long | 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 - market - liquidate - bankruptcy |
leverage | String | Leverage order multipliers |
open_type | String | Open type - cross - 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 (KEYED)
Applicable for checking the position details a specified contract
Request URL
GET https://api-cloud.bitmart.com/contract/private/position
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/contract/private/position?symbol=BTCUSDT
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | No | Symbol of the contract(like BTCUSDT) |
Response Data
Response
{
"code": 1000,
"message": "Ok",
"data": [
{
"symbol": "BTCUSDT",
"leverage": "5",
"timestamp": 1663814313531,
"current_fee": "5.00409471",
"open_timestamp": 1662714817820,
"current_value": "16680.3157",
"mark_price": "16673.27053207877",
"position_value": "18584.272343943943943944339",
"position_cross": "3798.397624451826977945",
"maintenance_margin": "4798.397624451826977945",
"close_vol": "100",
"close_avg_price": "20700.7",
"open_avg_price": "20200",
"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 |
open_avg_price | String | Open average price |
close_avg_price | String | Close average price |
close_vol | String | Close volume |
position_cross | String | Margin calls to positions |
maintenance_margin | String | Maintenance Margin |
current_amount | String | Current position amount |
unrealized_value | String | Unrealized PnL |
realized_value | String | Realized PnL |
position_type | Int | position type - 1 =long- 2 =short |
timestamp | Long | Current timestamp |
Get Order Trade (KEYED)
Applicable for querying contract order trade detail
Request URL
GET https://api-cloud.bitmart.com/contract/private/trades
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/contract/private/trades?symbol=BTCUSDT&start_time=1662368173&end_time=1662368179
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Symbol of the contract(like BTCUSDT) |
start_time | Long | No | Start time, default is the last 7 days |
end_time | Long | 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 - Maker |
realised_profit | String | realised profit |
paid_fees | String | paid fees |
create_time | Long | Create time |
Get Transfer List (SIGNED)
Query futures account transfer records
Request URl
POST https://api-cloud.bitmart.com/account/v1/transfer-contract-list
Request Limit
Request Parameter
Request
curl
-H 'X-BM-KEY:{{AccessKey}}'
-H 'X-BM-TIMESTAMP:{{currentTime}}'
-H 'X-BM-SIGN:{{SIGN}}'
-X POST -d '{
"currency":"USDT",
"time_start":1684391137804,
"time_end":1684392577804,
"page":1,
"limit":10,
"recvWindow":5000
}'
https://api-cloud.bitmart.com/account/v1/transfer-contract-list
Field | Type | Required? | Description |
---|---|---|---|
currency | String | No | Currency (like USDT ) |
time_start | Long | No | Start time in milliseconds, (e.g. 1681701557927) |
time_end | Long | No | End time in milliseconds, (e.g. 1681701557927) |
page | Int | Yes | Number of pages, allowed range [1,1000] |
limit | Int | Yes | Number of queries, allowed range [10,100] |
recvWindow | Long | No | Trade time limit, allowed range (0,60000], default: 5000 milliseconds |
Note
- If the time range
time_start
andtime_end
are not filled in, all data will be displayed by default. - When filling in the time range,
time_end
must be greater than the value oftime_start
. - If only
time_start
is filled in, query the historical records starting from the timestamp. - If only
time_end
is filled in, query the historical records starting from this timestamp.
Response Data
Response
{
"message":"OK",
"code":1000,
"trace":"82abff12-b9d9-4f66-89ea-3b604c6d84",
"data":{
"records":[{
"transfer_id":"664651258694168576",
"currency":"USDT",
"amount":"0.1",
"type":"contract_to_spot",
"state":"FINISHED",
"timestamp":1638631674326
}]
}
}
Field | Type | Description |
---|---|---|
transfer_id | String | ID |
currency | String | Currency |
amount | String | Amount |
type | String | Type - spot_to_contract - contract_to_spot |
state | String | Result - PROCESSING =Waiting to execute- FINISHED =Successful transfer- FAILED =Transfer failed |
timestamp | Long | Transfer creation time in milliseconds, e.g. 1638631674326 |
Submit Order (SIGNED)
Applicable for placing contract orders
Request URL
POST https://api-cloud.bitmart.com/contract/private/submit-order
Request Limit
Request Parameter
Request
curl
-H 'X-BM-KEY:{{AccessKey}}'
-H 'X-BM-TIMESTAMP:{{currentTime}}'
-H 'X-BM-SIGN:{{SIGN}}'
-X POST -d '{
"symbol":"ETHUSDT",
"side":4,
"mode":1,
"type":"limit",
"leverage":"1",
"open_type":"isolated",
"size":10,
"price":"2000"
}'
https://api-cloud.bitmart.com/contract/private/submit-order
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Symbol of the contract(like BTCUSDT) |
type | String | No | Order type - limit (default)- market |
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, required at close position - cross - isolated |
mode | Int | No | Order mode - 1 =GTC(default)- 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 Order (SIGNED)
Applicable for canceling a specific contract order
Request URL
POST https://api-cloud.bitmart.com/contract/private/cancel-order
Request Limit
Request Parameter
Request
curl
-H 'X-BM-KEY:{{AccessKey}}'
-H 'X-BM-TIMESTAMP:{{currentTime}}'
-H 'X-BM-SIGN:{{SIGN}}'
-X POST -d '{
"symbol":"ETHUSDT",
"order_id": "220906179559421"
}'
https://api-cloud.bitmart.com/contract/private/cancel-order
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 (SIGNED)
Applicable for batch order cancellation under a particular contract
Request URL
POST https://api-cloud.bitmart.com/contract/private/cancel-orders
Request Limit
Request Parameter
Request
curl
-H 'X-BM-KEY:{{AccessKey}}'
-H 'X-BM-TIMESTAMP:{{currentTime}}'
-H 'X-BM-SIGN:{{SIGN}}'
-X POST -d '{
"symbol":"ETHUSDT"
}'
https://api-cloud.bitmart.com/contract/private/cancel-orders
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 Order (SIGNED)
Applicable for placing contract plan orders
Request URL
POST https://api-cloud.bitmart.com/contract/private/submit-plan-order
Request Limit
Request Parameter
Request
curl
-H 'X-BM-KEY:{{AccessKey}}'
-H 'X-BM-TIMESTAMP:{{currentTime}}'
-H 'X-BM-SIGN:{{SIGN}}'
-X POST -d '{
"symbol":"ETHUSDT",
"side":4,
"mode":1,
"type":"limit",
"leverage":"1",
"open_type":"isolated",
"size":10,
"trigger_price":"2000",
"executive_price":"1450",
"price_type":1,
"price_way":1
}'
https://api-cloud.bitmart.com/contract/private/submit-plan-order
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Symbol of the contract(like BTCUSDT) |
type | String | No | Order type - limit (default)- market |
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, required at close position - cross - isolated |
mode | Int | No | Order mode - 1 =GTC(default)- 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 Order (SIGNED)
Applicable for canceling a specific contract plan order
Request URL
POST https://api-cloud.bitmart.com/contract/private/cancel-plan-order
Request Limit
Request Parameter
Request
curl
-H 'X-BM-KEY:{{AccessKey}}'
-H 'X-BM-TIMESTAMP:{{currentTime}}'
-H 'X-BM-SIGN:{{SIGN}}'
-X POST -d '{
"symbol":"ETHUSDT",
"order_id": "220906179559421"
}'
https://api-cloud.bitmart.com/contract/private/cancel-plan-order
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": {
}
}
Transfer (SIGNED)
Transfer between spot account and contract account
Request URl
POST https://api-cloud.bitmart.com/account/v1/transfer-contract
Request Limit
Request Parameter
Request
curl
-H 'X-BM-KEY:{{AccessKey}}'
-H 'X-BM-TIMESTAMP:{{currentTime}}'
-H 'X-BM-SIGN:{{SIGN}}'
-X POST -d '{
"currency":"USDT",
"amount":"10",
"type":"spot_to_contract",
"recvWindow":5000
}'
https://api-cloud.bitmart.com/account/v1/transfer-contract
Field | Type | Required? | Description |
---|---|---|---|
currency | String | Yes | Currency (Only USDT is supported) |
amount | String | Yes | Transfer amount,allowed range[0.01,10000000000] |
type | String | Yes | Transfer type - spot_to_contract - contract_to_spot |
recvWindow | Long | No | Trade time limit, allowed range (0,60000], default: 5000 milliseconds |
Response Data
Response
{
"message":"OK",
"code":1000,
"trace":"34018ca3-fe24-446a-9e1d-f82edfb3e3",
"data":{
"currency":"USDT",
"amount":"10"
}
}
Field | Type | Description |
---|---|---|
currency | String | currency |
amount | String | Amount successfully transferred |
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",
"ask_price": "147.11",
"bid_price": "142.11"
}
}
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 |
ask_price | string | Sell depths first price |
bid_price | string | Buy depths first 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 |
【Private】Order Channel
Order Channel, which pushes immediately when the order status, transaction amount, etc. changes.
Example
request
{
"action":"subscribe",
"args":["futures/order"]
}
back
{
"group": "futures/order",
"data": [
{
"action": 3,
"order": {
"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,
"plan_order_id":"220901412155341"
}
}
]
}
返回参数说明:
参数名称 | 数据类型 | 描述 |
---|---|---|
action | int | 1 =match deal |
2 =submit order |
||
3 =cancel order |
||
4 =liquidate cancel order |
||
5 =adl cancel order |
||
6 =part liquidate |
||
7 =bankruptcy order |
||
8 =passive adl match deal |
||
9 =active adl match deal |
||
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 |
plan_order_id | string | Trigger plan order id |
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 |