Update Plan
- The V1 OpenAPI service for futures trading will be fully discontinued on 2024-11-30. Please use the V2 OpenAPI for future trading.
- The domain name
https://api-cloud.bitmart.com
will not provide Futures 1.0 HTTP services. Please use the domain namehttps://api-cloud-v2.bitmart.com
to access Futures 2.0 HTTP services - The domain name
wss://openapi-ws.bitmart.com
will not provide Futures 1.0 Websocket services. Please use the domain namewss://openapi-ws-v2.bitmart.com
to access Futures 2.0 Websocket services
- The domain name
Change Log
2024-12-04
REST API
- [Update]
/account/v1/transfer-contract
Transfer (SIGNED)- Feature:support sub-account call
2024-11-28
REST API
- [Update]
/contract/private/modify-plan-order
Modify Plan Order (SIGNED)- Remove the field client_order_id
Websocket Order
- [Update] 【Private】Order Channel
- The field of state adds type status_approval
2024-11-25
Websocket Stream
- [New] [Public] Funding rate Channel
- Supports funding rate push
2024-11-01
Websocket Stream
- [New] [Public] Full-depth Channel
- Supports full-depth simultaneous push
- [New] [Public] Incremental Depth Push Channel
- Supports incremental depth push
2024-10-29
REST API
- [Update]
/contract/public/kline
Get K-line- Single time request size upper limit 500
2024-10-24
REST API
- [Update]
/contract/public/details
Get Contract Details- Add new response field market_max_volume
2024-10-17
REST API
- [New]
/contract/private/trade-fee-rate
Support querying trade fee rate(KEYED)- Feature:Support querying trade fee rate
- [Update]
/contract/public/funding-rate
Get Current Funding Rate- Update rate limit from 2 times/2 sec to 12 times/2 sec
- [Update]
/contract/public/details
Get Contract Details- Add new response field funding_interval_hour
- Support get funding interval
2024-10-10
REST API
- [Update]
/contract/private/submit-tp-sl-order
Support replacing contract TP/SL orders(SIGNED)- Change the default value of field plan_category to 2-Position TP/SL
2024-09-26
Documentation
- [Deleted] Futures 1.0 documentation
2024-09-19
REST API
- [New]
/contract/private/submit-tp-sl-order
Support replacing contract TP/SL orders(SIGNED)- Feature:Support replacing contract TP/SL orders
- [New]
/contract/private/modify-plan-order
Support modifying contract plan orders(SIGNED)- Feature:Support modifying contract plan orders
- [New]
/contract/private/modify-preset-plan-order
Support modifying contract preset plan orders(SIGNED)- Feature:Support modifying contract preset plan orders
- [New]
/contract/private/modify-tp-sl-order
Support modifying contract TP/SL orders(SIGNED)- Feature:Support modifying contract TP/SL orders
- [Update]
/contract/private/cancel-order
Cancel a single futures order- Add new request field client_order_id
- Support batch cancel orders by symbol
- [Update]
/contract/private/cancel-plan-order
Cancel Plan Order- Add new request field client_order_id
- Support batch cancel orders by symbol
- [Update]
/contract/private/current-plan-order
Get All Current Plan Orders- Add new request field plan_type
2024-07-23
- Add a new endpoint named current-plan-order
/contract/private/current-plan-order
support query contract all current plan orders(TP/SL、plan)
- New endpoints for trading
/contract/private/submit-leverage
Submit Leverage (SIGNED)
- New endpoints for Sub-Account
/account/contract/sub-account/main/v1/transfer-list
Get Sub-Account Transfer History (For Main Account)(KEYED)/account/contract/sub-account/v1/transfer-history
Get Account Futures Asset Transfer History (For Main/Sub Account)(KEYED)
- New endpoints for Sub-Account
/account/contract/sub-account/main/v1/sub-to-main
Sub-Account to Main-Account (For Main Account) (SIGNED)/account/contract/sub-account/main/v1/main-to-sub
Main-Account to Sub-Account (For Main Account) (SIGNED)/account/contract/sub-account/sub/v1/sub-to-main
Sub-Account to Main-Account (For Sub-Account) (SIGNED)/account/contract/sub-account/main/v1/wallet
Get Sub-Account Futures Wallet Balance (For Main Account) (KEYED)
- New endpoints for order
/contract/private/get-open-orders
Get All Open Orders (KEYED)
- New endpoints for transfer
/account/v1/transfer-contract
Get Transfer List (SIGNED)/account/v1/transfer-contract-list
Transfer (SIGNED)
- New endpoints for websocket order notify
/contract/public/websocket/order
- New endpoints for trading
/contract/private/submit-plan-order
Submit Plan Order (SIGNED)/contract/private/cancel-plan-order
Cancel Plan Order (SIGNED)
- New endpoints for trading
/contract/private/orders-history
Get Order History (KEYED)/contract/private/trades
Get Order Trade (KEYED)/contract/private/position
Get Current Position (KEYED)
- New endpoints for Futures Market Data
/contract/public/kline
Get K-line/contract/public/funding-rate
Get Current Funding Rate
- New endpoints for Futures Account Data
/contract/private/assets-detail
Get Contract Assets (KEYED)
- New websocket for public data
/contract/public/websocket
- New endpoints for get current funding rate of a specified contract
/contract/public/open-interest
- New endpoints for Futures Market Data
/contract/public/details
Get Contract Details/contract/public/depth
Get Market Depth
Introduction
API Key Create
- Many APIs require an API Access Key for access. Please refer to this page to set up.
- When setting up an API Access Key, it is recommended to set up an IP access whitelist for security purposes.
- Never give your API Access key/secret key to anyone.
After creating an API Key, you will receive three pieces of information that you must remember:
Access Key
: represents the identity of the account, this is your api keySecret Key
: used for API signatureMemo
: used for API signature
The Access Key and Secret Key will be randomly generated and provided by BitMart, and the Memo will be provided by you to ensure the security of API access.
API Key Permission Settings
- The default permission of a newly created API is
Read-Only
. - To withdraw funds through the API, you need to modify the permissions in the UI and select
Withdraw
. - Permission descriptions:
Read-only
(query spot trading orders, query contract trading orders, query funds)Spot-Trade
(place orders, cancel orders)Withdraw
(withdraw funds)Margin-Trade
(repayment, borrowing, placing orders, etc.)Future-Trade
(long position, short position, closing position, etc.)
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/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/get-open-orders | Query Contract All Open Orders | KEYED |
/contract/private/order | Query contract order details | KEYED |
/contract/private/trade-fee-rate | Query Trade Fee Rate | 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 |
/contract/private/current-plan-order | Query Current Plan Orders | KEYED |
/contract/private/position-risk | Query Position Risk 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/v4/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 multiple orders | SIGNED |
/spot/v4/cancel_orders | Cancel multiple orders | 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 |
Future-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 |
/contract/private/submit-tp-sl-order | Place a tp or sl order for a futures contract | SIGNED |
/contract/private/modify-plan-order | Modify a plan order for a futures contract | SIGNED |
/contract/private/modify-preset-plan-order | Modify a preset plan order for a futures contract | SIGNED |
/contract/private/modify-tp-sl-order | Modify a tp or sl order for a futures contract | SIGNED |
Sub-Account Permissions:
You need to enter Institution Verification to use the sub-account endpoints.
After the creation is successful, the sub-account has Read-only
permission by default.
Sub-Account Spot-Trade Permissions:
Same as the above spot trading authority
Sub-Account Contract-Trade Permissions:
Same as above futures trading authority
Sub-Account Inter-Account Transfer Permissions:
API Name | Description | Authentication Type |
---|---|---|
/account/sub-account/main/v1/sub-to-main | Sub-Account Transfer to Main-Account (For Main Account, use spot account) | SIGNED |
/account/sub-account/sub/v1/sub-to-main | Sub-Account Transfer to Main-Account (For Sub-Account, use spot account) | SIGNED |
/account/sub-account/main/v1/main-to-sub | Main-Account Transfer to Sub-Account (For Main Account, use spot account) | SIGNED |
/account/sub-account/main/v1/sub-to-sub | Sub-Account Transfer to Sub-Account (For Main Account, use spot account) | SIGNED |
/account/sub-account/main/v1/transfer-list | Get Sub-Account Transfer History (For Main Account, use spot account) | KEYED |
/account/sub-account/v1/transfer-history | Get Account Spot Asset Transfer History (For Main/Sub Account, use spot account) | KEYED |
/account/sub-account/main/v1/wallet | Get Sub-Account Spot Wallet Balance (For Main Account, use spot account) | KEYED |
/account/sub-account/main/v1/subaccount-list | Get Sub-Account List (For Main Account, use spot account) | KEYED |
/account/contract/sub-account/main/v1/sub-to-main | Sub-Account Transfer to Main-Account (For Main Account, use futures account) | SIGNED |
/account/contract/sub-account/main/v1/main-to-sub | Main-Account Transfer to Sub-Account (For Main Account, use futures account) | SIGNED |
/account/contract/sub-account/sub/v1/sub-to-main | Sub-Account Transfer to Main-Account (For Sub-Account, use futures account) | SIGNED |
/account/contract/sub-account/main/v1/wallet | Get Sub-Account Futures Wallet Balance (For Main Account, use futures account) | KEYED |
/account/contract/sub-account/v1/transfer-history | Get Account Futures Asset Transfer History (For Main/Sub Account, use futures account) | KEYED |
/account/contract/sub-account/main/v1/transfer-list | Get Sub-Account Transfer History (For Main Account, use futures account) | KEYED |
API Library
In order to facilitate access, we provide SDK in some languages for reference. For more programming codes, please refer to the Quick Start API on the page.
Available SDK:
In addition to the SDK, we also provide code samples in multiple languages, and the samples mainly demonstrate how to use the signed interface. It can be built and run standalone or as part of your codebase.
- Python Signature Example
- Go Signature Example
- Nodejs Signature Example
- Java Signature Example
- PHP Signature Example
- Ruby Signature Example
- C# Signature Example
- Rust Signature Example
- C++ Signature Example
- Postman
FAQ
Here are some frequently asked questions.
Q1. Will different API KEY in the same account return different data?
Q2. How to fill information in when applying for APIKEY?
Q3. How is the HTTP status code 429 created?
Q4. Using ccxt, the API KEY is correctly filled in, but it will also prompt 'message': 'Header X-BM-SIGN is wrong'
Q5. The program I wrote myself always prompts 'message': 'Header X-BM-SIGN is wrong'
Q6. Where is the location of BitMart servers?
Q7. When will the VIP fee I applied for take effect?
Q8. Why does it prompt "IP is forbidden. We recommend enabling IP whitelist for API trading. "
Contact Us
- Get support in our Telegram group BitMart API Club
- Please take 1 minute to help us improve: API Satisfaction Survey
Basic Information
API Basic Information
- This article lists the rest baseurl of the interfaces: https://api-cloud-v2.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.
Endpoints Limit Rules:
Futures Market Endpoints | Interface Name | Limit Target | Rate |
---|---|---|---|
/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 Open Interest | IP | 2 times/2 sec |
/contract/public/funding-rate | Get Current Funding Rate | IP | 12 times/2 sec |
/contract/public/kline | Get K-line | IP | 12 times/2 sec |
Futures Trade Endpoints | Interface Name | Limit Target | Rate |
---|---|---|---|
/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/get-open-orders | Get Contract All Open Orders | X-BM-KEY | 50 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/private/submit-leverage | Submit Contract Leverage | X-BM-KEY | 24 times/2 sec |
/account/v1/transfer-contract | Transfer | X-BM-KEY | 1 times/2 sec |
/account/v1/transfer-contract-list | Get Transfer List | X-BM-KEY | 1 times/2 sec |
/contract/private/position-risk | Get Position Risk Info | X-BM-KEY | 24 times/2 sec |
Sub-Account Endpoints | Interface Name | Limit Target | Rate |
---|---|---|---|
/account/contract/sub-account/main/v1/sub-to-main | Sub-Account Transfer to Main-Account (For Main Account, ues futures account) | X-BM-KEY | 8 times/2s |
/account/contract/sub-account/main/v1/main-to-sub | Main-Account Transfer to Sub-Account (For Main Account, ues futures account) | X-BM-KEY | 8 times/2s |
/account/contract/sub-account/sub/v1/sub-to-main | Sub-Account Transfer to Main-Account (For Sub-Account, ues futures account) | X-BM-KEY | 8 times/2s |
/account/contract/sub-account/main/v1/wallet | Get Sub-Account Futures Wallet Balance (For Main Account, ues futures account) | X-BM-KEY | 12 times/2s |
/account/contract/sub-account/v1/transfer-history | Get Account Futures Asset Transfer History (For Main/Sub Account, ues futures account) | X-BM-KEY | 8 times/2s |
/account/contract/sub-account/main/v1/transfer-list | Get Sub-Account Transfer History (For Main Account, ues futures account) | X-BM-KEY | 8 times/2s |
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 Open Interest | 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/get-open-orders | Get Contract All Open Orders | X-BM-KEY | 50 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 | |
/contract/private/current-plan-order | Get Contract All Current Plan Orders | X-BM-KEY | 50 times/2 sec | |
/contract/private/trade-fee-rate | Get Trade Fee Rate | X-BM-KEY | 2 times/2s | |
/contract/private/submit-tp-sl-order | Submit Contract TP or SL order | X-BM-KEY | 24 times/2s | |
/contract/private/modify-plan-order | Modify Contract Plan Order | X-BM-KEY | 24 times/2s | |
/contract/private/modify-preset-plan-order | Modify Contract Preset Plan Order | X-BM-KEY | 24 times/2s | |
/contract/private/modify-tp-sl-order | Modify Contract TP or SL Order | X-BM-KEY | 24 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 that have been used 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-v2.bitmart.com/contract/public/details
Request Limit
Request Parameter
Request
curl https://api-cloud-v2.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": 1594080000123,
"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",
"market_max_volume": "500000",
"min_volume": "1",
"funding_rate": "0.0001",
"expected_funding_rate": "0.00011",
"open_interest": "4134180870",
"open_interest_value": "94100888927.0433258",
"high_24h": "23900",
"low_24h": "23100",
"change_24h": "0.004",
"funding_interval_hours": 8
},
...
]
}
}
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 limit order quantity |
market_max_volume | String | Maximum market 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 |
high_24h | String | 24h High |
low_24h | String | 24h Low |
change_24h | String | 24h Change |
funding_interval_hours | Int | Funding interval |
Get Market Depth
Get full depth of trading pairs.
Request URL
GET https://api-cloud-v2.bitmart.com/contract/public/depth
Request Limit
Request Parameter
Request
curl https://api-cloud-v2.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 |
symbol | String | symbol |
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-v2.bitmart.com/contract/public/open-interest
Request Limit
Request Parameter
Request
curl https://api-cloud-v2.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-v2.bitmart.com/contract/public/funding-rate
Request Limit
Request Parameter
Request
curl https://api-cloud-v2.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",
"funding_time": 1709971200000,
"funding_upper_limit": "0.0375",
"funding_lower_limit": "-0.0375"
},
"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 |
funding_time | Long | Next funding settlement time |
funding_upper_limit | Long | Upper limit of funding rate for this trading pair |
funding_lower_limit | Long | Lower limit of funding rate for this trading pair |
Get K-line
Applicable for querying K-line data. Single time request size upper limit 500
Request URL
GET https://api-cloud-v2.bitmart.com/contract/public/kline
Request Limit
Request Parameter
Request
curl https://api-cloud-v2.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"
},
{
"timestamp": 1662518161,
"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-v2.bitmart.com/contract/private/assets-detail
Request Limit
Request Parameter
Request None
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.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 Trade Fee Rate (KEYED)
Applicable for querying trade fee rate
Request URL
GET https://api-cloud-v2.bitmart.com/contract/private/trade-fee-rate
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.bitmart.com/contract/private/trade-fee-rate?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",
"taker_fee_rate": "0.0006",
"maker_fee_rate": "0.0002"
},
"trace": "638d5048-ad21-4a4b-1234-d0756fbfc7ba"
}
Field | Type | Description |
---|---|---|
symbol | String | Symbol of the contract |
taker_fee_rate | String | Taker fee rate |
maker_fee_rate | String | Maker fee rate |
Get Order Detail (KEYED)
Applicable for querying contract order detail
Request URL
GET https://api-cloud-v2.bitmart.com/contract/private/order
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.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",
"client_order_id": "BM123",
"price": "1",
"size": "1000",
"symbol": "BTCUSDT",
"state": 2,
"side": 1,
"type": "limit",
"leverage": "5",
"open_type": "isolated",
"deal_avg_price": "0",
"deal_size": "1000",
"create_time": 1662368173000,
"update_time": 1662368173000
},
"trace": "638d5048-ad21-4a4b-9365-d0756fbfc7ba"
}
Field | Type | Description |
---|---|---|
symbol | String | Symbol of the contract |
order_id | String | Order ID |
client_order_id | String | Client-defined OrderId (If the field is not defined, a empty string is returned) |
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 - adl |
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 - 1 =status_approval- 2 =status_check- 4 =status_finish |
activation_price | String | Activation price, returned at trailing order |
callback_rate | String | Callback rate, returned at trailing order |
activation_price_type | Int | Activation price type, returned at trailing order - 1 =last_price- 2 =fair_price |
preset_take_profit_price_type | Int | Pre-set TP price type - 1 =last_price- 2 =fair_price |
preset_stop_loss_price_type | Int | Pre-set SL price type - 1 =last_price- 2 =fair_price |
preset_take_profit_price | String | Pre-set TP price |
preset_stop_loss_price | String | Pre-set SL price |
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-v2.bitmart.com/contract/private/order-history
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.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",
"client_order_id": "BM123",
"price": "1",
"size": "1000",
"symbol": "BTCUSDT",
"state": 2,
"side": 1,
"type": "limit",
"leverage": "5",
"open_type": "isolated",
"deal_avg_price": "0",
"deal_size": "1000",
"create_time": 1662368173000,
"update_time": 1662368173000
},
"trace": "638d5048-ad21-4a4b-9365-d0756fbfc7ba"
}
Field | Type | Description |
---|---|---|
symbol | String | Symbol of the contract |
order_id | String | Order ID |
client_order_id | String | Client-defined OrderId (If the field is not defined, a empty string is returned) |
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 - adl - trailing |
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 |
activation_price | String | Activation price, returned at trailing order |
callback_rate | String | Callback rate, returned at trailing order |
activation_price_type | Int | Activation price type, returned at trailing order - 1 =last_price- 2 =fair_price |
executive_order_id | String | Activation Execute Order ID |
preset_take_profit_price_type | Int | Pre-set TP price type - 0 =unset- 1 =last_price- 2 =fair_price |
preset_stop_loss_price_type | Int | Pre-set SL price type - 0 =unset- 1 =last_price- 2 =fair_price |
preset_take_profit_price | String | Pre-set TP price |
preset_stop_loss_price | String | Pre-set SL price |
create_time | Long | Create time |
update_time | Long | Update time |
Get All Open Orders (KEYED)
Applicable for querying contract all open orders
Request URL
GET https://api-cloud-v2.bitmart.com/contract/private/get-open-orders
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.bitmart.com/contract/private/get-open-orders?symbol=BTCUSDT&order_state=partially_filled&type=market&limit=10
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | No | Symbol of the contract(like BTCUSDT) |
type | string | No | Order type - limit - market - trailing |
order_state | string | No | Order state - all (default) - partially_filled |
limit | int | No | The number of returned results, with a maximum of 100 and a default of 100 |
Response Data
Response
{
"code": 1000,
"message": "Ok",
"data": [
{
"order_id": "220908185908509",
"client_order_id": "BM123",
"price": "14277",
"size": "7216",
"symbol": "BTCUSDT",
"state": 4,
"side": 3,
"type": "limit",
"leverage": "0",
"open_type": "isolated",
"deal_avg_price": "14277",
"deal_size": "7216",
"preset_take_profit_price_type": 1,
"preset_stop_loss_price_type": 2,
"preset_take_profit_price": "68000",
"preset_stop_loss_price": "60000",
"create_time": 1662368173000,
"update_time": 1662368173000
}
],
"trace": "80ba1f07-1b6f-46ad-81dd-78ac7e9bbccd"
}
Field | Type | Description |
---|---|---|
symbol | String | Symbol of the contract |
order_id | String | Order ID |
client_order_id | String | Client-defined OrderId (If the field is not defined, a empty string is returned) |
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 - trailing |
size | String | Order amount |
leverage | String | Leverage order multipliers |
String | 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 |
activation_price | String | Activation price, returned at trailing order |
callback_rate | String | Callback rate, returned at trailing order |
activation_price_type | Int | Activation price type, returned at trailing order - 1 =last_price- 2 =fair_price |
preset_take_profit_price_type | Int | Pre-set TP price type - 1 =last_price- 2 =fair_price |
preset_stop_loss_price_type | Int | Pre-set SL price type - 1 =last_price- 2 =fair_price |
preset_take_profit_price | String | Pre-set TP price |
preset_stop_loss_price | String | Pre-set SL price |
create_time | Long | Create time |
update_time | Long | Update time |
Get All Current Plan Orders (KEYED)
Applicable for querying contract all plan orders
Request URL
GET https://api-cloud-v2.bitmart.com/contract/private/current-plan-order
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.bitmart.com/contract/private/current-plan-order?symbol=BTCUSDT&type=market&limit=10
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | No | Symbol of the contract(like BTCUSDT) |
type | String | No | Order type - limit - market |
limit | int | No | The number of returned results, with a maximum of 100 and a default of 100 |
plan_type | String | No | Plan order type - plan - profit_loss default all |
Response Data
Response
{
"code": 1000,
"message": "Ok",
"data": [
{
"order_id": "220908185908509",
"client_order_id": "BM123",
"executive_price": "14277",
"trigger_price": "14277",
"size": "7216",
"symbol": "BTCUSDT",
"state": 4,
"side": 3,
"mode": 1,
"price_way": 2,
"price_type": 1,
"plan_category": 2,
"type": "stop_loss",
"leverage": "0",
"open_type": "isolated",
"create_time": 1662368173000,
"update_time": 1662368173000
}
],
"trace": "80ba1f07-1b6f-46ad-81dd-78ac7e9bbccd"
}
Field | Type | Description |
---|---|---|
symbol | String | Symbol of the contract |
order_id | String | Order ID |
client_order_id | String | Client-defined OrderId (If the field is not defined, a empty string is returned) |
side | Int | Order side - 1 =buy_open_long- 2 =buy_close_short- 3 =sell_close_long- 4 =sell_open_short |
type | String | Order type - plan - take_profit - stop_loss |
plan_category | Int | TP/SL type - 1 =TP/SL - 2 =Position TP/SL |
size | String | Order amount |
leverage | String | Leverage order multipliers |
open_type | String | Open type - cross - isolated |
executive_price | String | Executive price |
trigger_price | String | Trigger price |
state | Int | Order status - 1 =status_approval- 2 =status_check |
preset_take_profit_price_type | Int | Pre-set TP price type - 1 =last_price- 2 =fair_price |
preset_stop_loss_price_type | Int | Pre-set SL price type - 1 =last_price- 2 =fair_price |
preset_take_profit_price | String | Pre-set TP price |
preset_stop_loss_price | String | Pre-set SL price |
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-v2.bitmart.com/contract/private/position
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.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_value": "16673.27053207877",
"mark_price": "93000.50",
"position_value": "18584.272343943943943944339",
"position_cross": "3798.397624451826977945",
"maintenance_margin": "4798.397624451826977945",
"margin_type":"Isolated",
"close_vol": "100",
"close_avg_price": "20700.7",
"open_avg_price": "20200",
"entry_price": "20201",
"current_amount": "899",
"unrealized_value": "1903.956643943943943944339",
"realized_value": "55.049173071454605573",
"position_type": 2
}
],
"trace": "ae96cae5-1f09-4ea5-971e-4474a6724bc8"
}
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 | Position value based on last price |
mark_value | String | Position value based on mark price |
mark_price | String | mark price |
position_value | String | Position value based on entry price |
open_avg_price | String | Open average price |
close_avg_price | String | Close average price |
entry_price | String | Average entry price of the position |
close_vol | String | Close volume |
position_cross | String | Margin calls to positions |
maintenance_margin | String | Maintenance Margin |
margin_type | String | Margin type of the position - Cross - Isolated |
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 Current Position Risk Details(KEYED)
Applicable for checking the position risk details a specified contract
Request URL
GET https://api-cloud-v2.bitmart.com/contract/private/position-risk
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.bitmart.com/contract/private/position-risk?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",
"position_amt":"1",
"mark_price":"67957.7",
"unrealized_profit":"969.6",
"liquidation_price":"64245",
"leverage":"20",
"max_notional_value":"3000000",
"margin_type":"Isolated",
"isolated_margin":"3078.51948691",
"position_side":"Long",
"notional":"66988.1",
"update_time":1712390438}
],
"trace": "ae96cae5-1f09-4ea5-971e-4474a6724bc8"
}
字段 | 类型 | 描述 |
---|---|---|
symbol | String | Symbol of the contract(like BTCUSDT) |
position_amt | String | Position amount |
mark_price | String | Mark Price of the contract |
unrealized_profit | String | Unrealized profit of the position |
liquidation_price | String | LiquidationPrice of the position |
leverage | String | Position leverage |
max_notional_value | String | Maximum notional value for the current risk level |
margin_type | String | Margin type of the position - Cross - Isolated |
isolated_margin | String | Margin for the isolated position |
position_side | String | Position side - Long - Short |
notional | String | notional = position_amt*mark_Price |
update_time | Long | Unix timestamp in milliseconds for when the last updated time occurred |
Get Order Trade (KEYED)
Applicable for querying contract order trade detail
Request URL
GET https://api-cloud-v2.bitmart.com/contract/private/trades
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.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-v2.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-v2.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-v2.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",
"client_order_id":"BM1234",
"side":4,
"mode":1,
"type":"limit",
"leverage":"1",
"open_type":"isolated",
"size":10,
"price":"2000"
}'
https://api-cloud-v2.bitmart.com/contract/private/submit-order
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Symbol of the contract(like BTCUSDT) |
client_order_id | String | No | Client-defined OrderId(A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters) |
type | String | No | Order type - limit (default)- market - trailing |
side | Int | Yes | Order side - 1 =buy_open_long- 2 =buy_close_short- 3 =sell_close_long- 4 =sell_open_short |
leverage | String | No | Order leverage |
open_type | String | No | 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 (Number of contracts) |
activation_price | String | No | Activation price, required at trailing order |
callback_rate | String | No | Callback rate, required at trailing order, min 0.1, max 5 where 1 for 1% |
activation_price_type | Int | No | Activation price type, required at trailing order - 1 =last_price- 2 =fair_price |
preset_take_profit_price_type | Int | No | Pre-set TP price type - 1 =last_price(default)- 2 =fair_price |
preset_stop_loss_price_type | Int | No | Pre-set SL price type - 1 =last_price(default)- 2 =fair_price |
preset_take_profit_price | String | No | Pre-set TP price |
preset_stop_loss_price | String | No | Pre-set SL price |
Response Data
Response
{
"code": 1000,
"message": "Ok",
"data": {
"order_id": 220609666322019,
"price": "25637.2"
},
"trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}
Field | Type | Description |
---|---|---|
order_id | Int | Order ID |
price | String | Order Submit Price,if submit market type order,will return string:"market price" |
Cancel Order (SIGNED)
Applicable for canceling a specific contract order
Request URL
POST https://api-cloud-v2.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-v2.bitmart.com/contract/private/cancel-order
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Symbol of the contract(like BTCUSDT),(If not submitted order_id and client_order_id, cancel all orders under the symbol) |
order_id | String | No | Order ID |
client_order_id | String | No | Client-defined OrderId |
Response Data
If code value is 1000, it means the order cancellation is successfully submitted, cancellation results will be pushed by websocket service.
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-v2.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-v2.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 cancellation is successfully submitted, cancellation results will be pushed by websocket service.
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-v2.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-v2.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 - take_profit - stop_loss |
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 (Number of contracts) |
trigger_price | String | Yes | Trigger price |
executive_price | String | No | Execution price for plan order, mandatory when type = limit |
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 |
plan_category | Int | No | TP/SL type - 1 =TP/SL- 2 =Position TP/SL |
preset_take_profit_price_type | Int | No | Pre-set TP price type - 1 =last_price(default)- 2 =fair_price |
preset_stop_loss_price_type | Int | No | Pre-set SL price type - 1 =last_price(default)- 2 =fair_price |
preset_take_profit_price | String | No | Pre-set TP price |
preset_stop_loss_price | String | No | Pre-set SL price |
Response Data
Response
{
"code": 1000,
"message": "Ok",
"data": {
"order_id": 220609666322019
},
"trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}
Field | Type | Description |
---|---|---|
order_id | Int | Order ID |
Cancel Plan Order (SIGNED)
Applicable for canceling a specific contract plan order
Request URL
POST https://api-cloud-v2.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",
"client_order_id": "123456789"
}'
https://api-cloud-v2.bitmart.com/contract/private/cancel-plan-order
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Symbol of the contract(like BTCUSDT) |
order_id | String | No | Order ID |
client_order_id | String | No | Client Order ID |
Response Data
If code value is 1000, it means the order cancellation is successfully submitted, cancellation results will be pushed by websocket service.
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-v2.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-v2.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 |
Submit Leverage (SIGNED)
Applicable for adjust contract leverage
`
Request URL
POST https://api-cloud-v2.bitmart.com/contract/private/submit-leverage
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",
"leverage":"5",
"open_type":"isolated"
}'
https://api-cloud-v2.bitmart.com/contract/private/submit-leverage
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Symbol of the contract(like BTCUSDT) |
leverage | String | No | Order leverage |
open_type | String | Yes | Open type, required at close position - cross - isolated |
Response Data
Response
{
"code": 1000,
"message": "Ok",
"data": {
"symbol":"ETHUSDT",
"leverage":"5",
"open_type":"isolated",
"max_value":"100"
},
"trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}
Field | Type | Description |
---|---|---|
symbol | String | Symbol of the contract(like BTCUSDT) |
leverage | String | Order leverage |
open_type | String | Open type, required at close position - cross - isolated |
max_value | String | Maximum leverage |
Submit TP/SL Order (SIGNED)
Applicable for placing contract TP/SL orders
Request URL
POST https://api-cloud-v2.bitmart.com/contract/private/submit-tp-sl-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":2,
"type":"take_profit",
"size":10,
"trigger_price":"2000",
"executive_price":"1450",
"price_type":1,
"plan_category":1,
"client_order_id":"123456789",
"category":"limit"
}'
https://api-cloud-v2.bitmart.com/contract/private/submit-plan-order
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Symbol of the contract(like BTCUSDT) |
type | String | Yes | Order type - take_profit - stop_loss |
side | Int | Yes | Order side - 2 =buy_close_short- 3 =sell_close_long |
size | Int | No | Order size (Number of contracts) Default the size of position |
trigger_price | String | Yes | Trigger price |
executive_price | String | Yes | Execution price |
price_type | Int | Yes | Trigger price type - 1 =last_price- 2 =fair_price |
plan_category | Int | No | TP/SL type - 1 =TP/SL- 2 =Position TP/SL(default) |
client_order_id | String | No | Client-defined OrderId(A combination of case-sensitive alphanumerics, all numbers, or all letters of up to 32 characters) |
category | String | No | Trigger order type, position TP/SL default market - limit - market |
Response Data
Response
{
"code": 1000,
"message": "Ok",
"data": {
"order_id": "220609666322019",
"client_order_id": "123456789"
},
"trace": "13f7fda9-9543-4e11-a0ba-cbe117989988"
}
Field | Type | Description |
---|---|---|
order_id | String | Order ID |
client_order_id | String | Client Order ID |
Modify Plan Order (SIGNED)
Applicable for modifying contract plan orders
Request URL
POST https://api-cloud-v2.bitmart.com/contract/private/modify-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",
"trigger_price":"2000",
"executive_price":"1450",
"price_type":1,
"type":"limit"
}'
https://api-cloud-v2.bitmart.com/contract/private/modify-plan-order
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Symbol of the contract(like BTCUSDT) |
order_id | String | No | Order ID(order_id or client_order_id must give one) |
trigger_price | String | Yes | Trigger price |
executive_price | String | No | Execution price for plan order, mandatory when type = limit |
price_type | Int | Yes | Trigger price type - 1 =last_price- 2 =fair_price |
type | String | Yes | Order type - limit - market |
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 |
Modify Preset Plan Order (SIGNED)
Applicable for modifying contract preset plan orders
Request URL
POST https://api-cloud-v2.bitmart.com/contract/private/modify-preset-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":"220609666322019",
"preset_take_profit_price":"2000",
"preset_stop_loss_price":"1900",
"preset_take_profit_price_type":1,
"preset_stop_loss_price_type":1
}'
https://api-cloud-v2.bitmart.com/contract/private/modify-preset-plan-order
Field | Type | Required? | Description |
---|---|---|---|
order_id | String | Yes | Order ID |
symbol | String | Yes | Symbol of the contract(like BTCUSDT) |
preset_take_profit_price_type | Int | No | Pre-set TP price type - 1 =last_price(default)- 2 =fair_price |
preset_stop_loss_price_type | Int | No | Pre-set SL price type - 1 =last_price(default)- 2 =fair_price |
preset_take_profit_price | String | No | Pre-set TP price |
preset_stop_loss_price | String | No | Pre-set SL 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 |
Modify TP/SL Order (SIGNED)
Applicable for modifying TP/SL orders
Request URL
POST https://api-cloud-v2.bitmart.com/contract/private/modify-tp-sl-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",
"trigger_price":"2100",
"executive_price":"2100",
"price_type":2,
"order_id":"37758000001",
"client_order_id":"",
"plan_category":2,
"category": "limit"
}'
https://api-cloud-v2.bitmart.com/contract/private/modify-tp-sl-order
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Symbol of the contract(like BTCUSDT) |
order_id | String | No | Order ID(order_id or client_order_id must give one) |
client_order_id | String | No | Client order ID(order_id or client_order_id must give one) |
trigger_price | String | Yes | Trigger price |
executive_price | String | No | Execution price for order, mandatory when plan_category = 1 |
price_type | Int | Yes | Trigger price type - 1 =last_price- 2 =fair_price |
plan_category | Int | No | TP/SL type - 1 =TP/SL- 2 =Position TP/SL |
category | String | No | Order type, Position TP/SL default market - limit - market |
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 |
Sub-Account
Sub-Account to Main-Account (For Main Account) (SIGNED)
Sub-account futures asset transfer to Main-account futures asset (For Main Account)
Request URL
POST https://api-cloud-v2.bitmart.com/account/contract/sub-account/main/v1/sub-to-main
Request Limit
Request Parameter
Request
curl
-H 'X-BM-KEY:{{AccessKey}}'
-H 'X-BM-TIMESTAMP:{{currentTime}}'
-H 'X-BM-SIGN:{{SIGN}}'
-X POST -d '{
"requestNo":"4e2adcff-2122-1ce7-2557-4f65d2ce1ca2",
"amount":"1",
"currency":"USDT",
"subAccount":"[email protected]"
}'
https://api-cloud-v2.bitmart.com/account/contract/sub-account/main/v1/sub-to-main`
Field | Type | Required? | Description |
---|---|---|---|
requestNo | String | Yes | UUID,unique identifier, max length 64 |
amount | String | Yes | Transfer amount |
currency | String | Yes | Currently only USDT is supported |
subAccount | String | Yes | Sub-Account username |
Response Data
Response
{
"message": "OK",
"code": 1000,
"trace": "c1e4e99ff0ec452f8b8bc5f1eb38d733.76.16861963186213159",
"data": {}
}
If code value is 1000,it means the transfer is successful.
Main-Account to Sub-Account (For Main Account) (SIGNED)
Main-account futures asset transfer to Sub-account futures asset (For Main Account)
Request URL
POST https://api-cloud-v2.bitmart.com/account/contract/sub-account/main/v1/main-to-sub
Request Limit
Request Parameter
Request
curl
-H 'X-BM-KEY:{{AccessKey}}'
-H 'X-BM-TIMESTAMP:{{currentTime}}'
-H 'X-BM-SIGN:{{SIGN}}'
-X POST -d '{
"requestNo":"4e2adcff-2122-1ce7-2557-4f65d2ce1ca2",
"amount":"1",
"currency":"BTC",
"subAccount":"[email protected]"
}'
https://api-cloud-v2.bitmart.com/account/contract/sub-account/main/v1/main-to-sub`
Field | Type | Required? | Description |
---|---|---|---|
requestNo | String | Yes | UUID,unique identifier, max length 64 |
amount | String | Yes | Transfer amount |
currency | String | Yes | Currently only USDT is supported |
subAccount | String | Yes | Sub-Account username |
Response Data
Response
{
"message": "OK",
"code": 1000,
"trace": "c1e4e99ff0ec452f8b8bc5f1eb38d733.76.16861963186213159",
"data": {}
}
If code value is 1000,it means the transfer is successful.
Sub-Account to Main-Account (For Sub-Account) (SIGNED)
Sub-Account futures asset transfer to Main-Account futures asset (For Sub-Account)
Request URL
POST https://api-cloud-v2.bitmart.com/account/contract/sub-account/sub/v1/sub-to-main
Request Limit
Request Parameter
Request
curl
-H 'X-BM-KEY:{{AccessKey}}'
-H 'X-BM-TIMESTAMP:{{currentTime}}'
-H 'X-BM-SIGN:{{SIGN}}'
-X POST -d '{
"requestNo":"4e2adcff-2122-1ce7-2557-4f65d2ce1ca2",
"amount":"1",
"currency":"USDT"
}'
https://api-cloud-v2.bitmart.com/account/contract/sub-account/sub/v1/sub-to-main`
Field | Type | Required? | Description |
---|---|---|---|
requestNo | String | Yes | UUID,unique identifier, max length 64 |
amount | String | Yes | Transfer amount |
currency | String | Yes | Currently only USDT is supported |
Response Data
Response
{
"message": "OK",
"code": 1000,
"trace": "c1e4e99ff0ec452f8b8bc5f1eb38d733.76.16861970092723253",
"data": {}
}
If code value is 1000,it means the transfer is successful.
Get Sub-Account Futures Wallet Balance (For Main Account) (KEYED)
Get Sub-Account futures wallet balance (For Main Account) (KEYED)
Request URL
GET https://api-cloud-v2.bitmart.com/account/contract/sub-account/main/v1/wallet
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.bitmart.com/account/contract/sub-account/main/v1/wallet?subAccount=[email protected]¤cy=USDT
Field | Type | Required? | Description |
---|---|---|---|
subAccount | String | Yes | Sub-Account username |
currency | String | No | currency |
Response Data
Response
{
"message": "OK",
"code": 1000,
"trace": "87db8cd43374470f96aacb0e3fcaf34c.77.16872314088656435",
"data": {
"wallet": [
{
"currency": "USDT",
"name": "USDT",
"available": "204.15216696",
"frozen": "0.00000000"
}
]
}
}
Field | Type | Description |
---|---|---|
currency | String | Token symbol, e.g., 'BTC' |
name | String | Token name, e.g., 'Bitcoin' |
available | String | Available Balance |
frozen | String | Frozen Balance |
Get Sub-Account Transfer History (For Main Account) (KEYED)
Query Sub-Account Futures Asset Transfer History (For Main Account)
Request URL
GET https://api-cloud-v2.bitmart.com/account/contract/sub-account/main/v1/transfer-list
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.bitmart.com/account/contract/sub-account/main/v1/transfer-list?subAccount=[email protected]&limit=10
Field | Type | Required? | Description |
---|---|---|---|
subAccount | String | Yes | Sub-Account username |
limit | Int | Yes | Recent N records, allowed range[1,100] |
Response Data
Response
{
"message": "OK",
"code": 1000,
"trace": "ba950ec2bd114fd7bc069cb812b0129f.62.16887213774200649",
"data": [
{
"fromAccount": "[email protected]",
"toAccount": "[email protected]",
"toWalletType": "future",
"fromWalletType": "future",
"currency": "USDT",
"amount": "1",
"submissionTime": 1686207254
}
]
}
Field | Type | Description |
---|---|---|
fromAccount | String | Transfer out Sub-Account username |
fromWalletType | String | Transfer out wallet type - future =futures wallet |
toAccount | String | Transfer to Sub-Account username |
toWalletType | String | Transfer to wallet type - future =futures wallet |
currency | String | currency |
amount | String | Transfer amount |
submissionTime | Long | The request timestamp is accurate to seconds(UTC-0) |
Get Account Futures Asset Transfer History (For Main/Sub Account) (KEYED)
Get account Futures asset transfer history (For Main/Sub Account)
Request URL
GET https://api-cloud-v2.bitmart.com/account/contract/sub-account/v1/transfer-history
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud-v2.bitmart.com/account/contract/sub-account/v1/transfer-history?limit=10
Field | Type | Required? | Description |
---|---|---|---|
limit | Int | Yes | Recent N records, allowed range[1,100] |
Response Data
Response
{
"message": "OK",
"code": 1000,
"trace": "ba950ec2bd114fd7bc069cb812b0129f.62.16887215218140681",
"data": [
{
"fromAccount": "[email protected]",
"toAccount": "[email protected]",
"toWalletType": "future",
"fromWalletType": "future",
"currency": "USDT",
"amount": "1",
"submissionTime": 1686207254
}
]
}
Field | Type | Description |
---|---|---|
fromAccount | String | Transfer out Sub-Account username |
fromWalletType | String | Transfer out wallet type - future =futures wallet |
toAccount | String | Transfer to Sub-Account username |
toWalletType | String | Transfer to wallet type - future =futures wallet |
currency | String | currency |
amount | String | Transfer amount |
submissionTime | Long | The request timestamp is accurate to seconds(UTC-0) |
WebSocket Subscription
Overview
Server URL
Public Channel: wss://openapi-ws-v2.bitmart.com/api?protocol=1.1
Private Channel: wss://openapi-ws-v2.bitmart.com/user?protocol=1.1
Format
The message format sent by the client to the BitMart server.
{"action":"<operation>", "args":["<topic1>","<topic2>"]}
Explain:
operation
request action, value: [subscribe
=Subscribe channel,unsubscribe
=Unsubscribe channel,login
=Account login]args
request parameter, value: channel array or parameters required for logintopic
channel topic, composed of<channel>:<filter>
- channel is composed of business/name
- filter is filterable data, refer to each channel description for details
Example:
- Example 1:
{"action": "subscribe", "args": ["futures/depth50:BTCUSDT"]}
- Means to subscribe to the depth data of the trading pair BTCUSDT
- Example 2:
{"action": "login", "args": ["80618e45710812162b04892c7ee5ead4a3cc3e56", "1589267764859", "3ceeb7e1b8cb165a975e28a2e2dfaca4d30b358873c0351c1a071d8c83314556", "web"]}
- Login request before private channel subscription
Successful Response Format
The format of the success message returned by the BitMart server to the client.
Return success
field is ture
Successful Response Format
When action=access :
{"action":"access","success":true}
When action=unsubscribe :
{"action":"unsubscribe","group":"Depth:1","success":true,"request":{"action":"unsubscribe","args":["Depth:1"]}}
When action=subscribe :
{"action":"subscribe","group":"Depth:1","success":true,"request":{"action":"subscribe","args":["Depth:1"]}}
Example:
- Example 1:
{"action":"access","success":true}
- Means successful login
- Example 2:
{"action":"unsubscribe","group":"futures/depth50:BTCUSDT","success":true,"request":{"action":"unsubscribe","args":["futures/depth50:BTCUSDT"]}}
- Means successful cancellation of depth50 subscription for trading pair BTCUSDT
- Example 3:
{"action":"subscribe","group":"futures/depth50:BTCUSDT","success":true,"request":{"action":"subscribe","args":["futures/depth50:BTCUSDT"]}}
- Means successful subscribe of depth50 subscription for trading pair BTCUSDT
- Example 4:
{"group":"futures/depth50:BTCUSDT","data":{"symbol":"BTCUSDT","way":2,"depths":[{"price":"30107.7","vol":"234"},{"price":"30107.8","vol":"1587"}]}}
- Means the depth50 subscription of spot trading pair BTCUSDT, generates data, and returns it to the client
Failed Response Format
The format of the failed message returned by the BitMart server to the client.
Return success
field is false
Failed Response Format
{"action":"subscribe","group":"Depth:1","success":false,"error":"authentication is temporarily unavailable"}
- Example 1:
{"action":"subscribe","group":"futures/order","success":false,"error":"futures/order need authenication"}
- Means you need to log in
- Example 2:
{"action":"access","success":false,"error":"access failed: openapi auth: apiKey 880d5edecs**** failed: openapi auth failed"}
- Means login failed, your sign is wrong
- Example 3:
{"action":"subscribe","group":"sfutures/depth50:BTCUSDT","success":false,"request":{"action":"subscribe","args":["sfutures/depth50:BTCUSDT"]},"error":"group [sfutures/depth50:BTCUSDT] not exist"}
- Means subscription failed, your parameter is invalid, this channel does not exist
Stay Connected And Limit
How Stay Connected
WebSocket uses the Ping/Pong mechanism to maintain the connection. Once the connection is opened, a Ping frame is sent every N seconds, and the remote endpoint will return a Pong frame to keep responding. This is an approach to stay active. It helps to keep the connection open, especially if there is a short timeout proxy on an inactive connection.
If no data is returned after connecting to WebSocket, the link will be automatically disconnected after 20s. It is recommended that the user do the following:
- After each message is received, the user sets a timer for N seconds (N<20).
- If the timer is triggered (no new message is received within N seconds), send a ping frame or send a string 'ping'.
- Expect for a text string 'pong' as a response. If not received within N seconds, please issue an error or reconnect.
- We do not actively disconnect when there is a continuous message interaction between the two parties.
The following is the data format of ping: (Example in Java pseudocode)
- Standard Ping frame
ws.send(new PingWebSocketFrame());
- Ping Text
ws.send(new TextWebSocketFrame('{"action":"ping"}'));
Connection Limit
- A maximum of 500 connections can be maintained between each IP and BitMart server.
Lifeless connection
Connection that do not send task subscription data within 5 seconds will be considered lifeless and the server will close the connection.
Subscription
Users can subscribe to one or more channels, and the total length of multiple channels cannot exceed 4096 bytes
Subscribe Message Format
{"action":"subscribe","args":["<topic>"]}
Parameter Instructions
action
= subscribeargs
= The content of the args array is the subscribed topictopic
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
Send message to BitMart server
{"action":"subscribe","args":["futures/klineBin1m:BTCUSDT"]}
The BitMart server returns the subscription result, success=true means the subscription is successful
{"action":"subscribe","group":"futures/klineBin1m:BTCUSDT","success":true,"request":{"action":"subscribe","args":["futures/klineBin1m:BTCUSDT"]}}
Unsubscribe
Cancel subscription to one or more channels
Unsubscribe Message Format
{"action": "unsubscribe", "args": ["<topic>"]}
Parameter Instruction
action
= unsubscribeargs
= The content of the args array is the subscribed topictopic
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
Send message to BitMart server
{"action": "unsubscribe", "args": ["futures/klineBin1m:BTCUSDT"]}
The BitMart server returns the subscription result, success=true means the subscription is successful
{"action":"unsubscribe","group":"futures/klineBin1m:BTCUSDT","success":true,"request":{"action":"unsubscribe","args":["futures/klineBin1m:BTCUSDT"]}}
【Public】Ticker Channel
Get the latest transaction price, bid one price, ask for one price, and 24 trading volumes of all perpetual contracts on the platform
Pushing Rules
- No user login required
- After subscribing, then the changes will be pushed
- Sent once in 1 second after subscription
Request
Request
{
"action":"subscribe",
"args":["futures/ticker"]
}
Message Format:
{"action":"subscribe","args":["<channel>"]}
- actions:
subscribe
- channel:
futures/ticker
Response
Response
{
"group":"futures/ticker",
"data":{
"symbol":"BTCUSDT",
"volume_24":"117387.58",
"fair_price":"146.24",
"last_price":"146.24",
"range":"147.17",
"ask_price": "147.11",
"ask_vol": "1",
"bid_price": "142.11",
"bid_vol": "1"
}
}
Return data description:
Field | 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 |
ask_vol | String | Sell depths first vol |
bid_price | String | Buy depths first price |
bid_vol | String | Buy depths first vol |
【Public】Funding Rate Channel
Return funding Rate data
Pushing Rules
- No user login required
- After subscribing, the current data will be returned directly, and updates will be pushed every minute.
Request
Subscribe Request
{
"action":"subscribe",
"args":["futures/fundingRate:BTCUSDT"]
}
Funding rate data Request
{
"action": "request",
"args":["futures/fundingRate:BTCUSDT"]
}
Message Format:
{"action": "<op>", "args": ["<channel:symbol>"]}
- op:
subscribe
=Subscribe, You will receive a message that the subscription is successful, and then you will receive funding rate data pushed every minute.request
=Single request for the latest funding rate data, You will receive a funding rate data immediately. - channel:Channel name, such as
futures/fundingRate
- symbol: Trading pair, such as
BTCUSDT
Response
Funding rate data
{
"data": {
"symbol": "BTCUSDT",
"fundingRate": "0.000098800809",
"fundingTime": 1732525864000,
"nextFundingRate": "0.0000947",
"nextFundingTime": 1732550400000,
"funding_upper_limit": "0.0375",
"funding_lower_limit": "-0.0375",
"ts": 1732525864601
},
"group": "futures/fundingRate:BTCUSDT"
}
Return data description:
Field | Type | Description |
---|---|---|
symbol | String | Symbol of the contract (like BTCUSDT ) |
fundingRate | String | Current funding rate |
fundingTime | Long | Funding time of the upcoming settlement, Unix timestamp format in milliseconds |
nextFundingRate | String | Forecasted funding rate for the next period |
nextFundingTime | Long | Forecasted funding time for the next period, Unix timestamp format in milliseconds |
funding_upper_limit | String | The upper limit of the predicted funding rate of the next cycle |
funding_lower_limit | String | The lower limit of the predicted funding rate of the next cycle |
ts | Long | Data return time, Unix timestamp format in milliseconds |
【Public】Depth Channel
Get depth data
Pushing Rules
- No user login required
- After subscribing, then the changes will be pushed
Request
Request
{
"action":"subscribe",
"args":["futures/depth20:BTCUSDT"]
}
Message Format:
{"action":"subscribe","args":["<channel:symbol>","<channel:symbol>"]}
- actions:
subscribe
- channel: Channel name, such as
futures/depth20
- symbol: Trading pair, such as
BTCUSDT
Parameters Channel Name List
Channel Name | Description |
---|---|
futures/depth5 | 5 Level Depth Channel |
futures/depth20 | 20 Level Depth Channel |
futures/depth50 | 50 Level Depth Channel |
Response
Response
{
"group":"futures/depth20:BTCUSDT",
"data":{
"symbol":"BTCUSDT",
"way":1,
"depths":[
{"price":"5","vol":"97"}
],
"ms_t": 1542337219120
}
}
Return data description:
Field | Type | Description |
---|---|---|
symbol | String | Symbol of the contract(like BTCUSDT ) |
way | Long | Trading side - 1 =bid- 2 =ask |
depths | List | Array of depth details |
ms_t | Long | Timestamp (in millisecond) |
Instruction
Description of the depths
details field:
Field | Type | Description |
---|---|---|
price | String | price |
vol | String | volume |
【Public】Depth-All Channel
Return depth data, each push is the full data
Pushing Rules
- No user login required
- After subscribing, then the changes will be pushed
Request
Request
{
"action":"subscribe",
"args":["futures/depthAll20:BTCUSDT"]
}
Message Format:
{"action":"subscribe","args":["<channel:symbol>","<channel:symbol>"]}
- channel: Channel name, such as
futures/depthAll20
- symbol: Trading pair, such as
BTCUSDT
Parameters Channel Name List
Channel Name | Description |
---|---|
futures/depthAll5 | 5 Level Depth Channel |
futures/depthAll20 | 20 Level Depth Channel |
futures/depthAll50 | 50 Level Depth Channel |
Response
Response
{
"data": {
"symbol": "BTCUSDT",
"asks": [
{
"price": "70294.4",
"vol": "455"
}
],
"bids": [
{
"price": "70293.9",
"vol": "1856"
}
],
"ms_t": 1730399750402
},
"group": "futures/depthAll20:BTCUSDT"
}
Return data description:
Field | Type | Description |
---|---|---|
symbol | String | Symbol of the contract(like BTCUSDT ) |
asks | List | Asks Depth Array |
bids | List | Bids Depth Array |
ms_t | Long | Timestamp (in millisecond) |
Instruction
Description of the asks
bids
details field:
Field | Type | Description |
---|---|---|
price | String | price |
vol | String | volume |
【Public】Depth-Increase Channel
Return depth data, support the creation of a local full depth cache data
Pushing Rules
- No user login required
- After subscribing, the current data will be returned directly, and then the changes will be pushed
Request
Subscribe Request
{
"action":"subscribe",
"args":["futures/depthIncrease20:BTCUSDT"]
}
Full depth snapshot data Request
{
"action": "request",
"args":["futures/depthIncrease20:BTCUSDT"]
}
Message Format:
{"action": "<op>", "args": ["<channel:symbol>"]}
- op:
subscribe
=Subscribe, You will receive a message that the subscription is successful, and then you will receive incremental depth data pushed in real time.request
=Single request for the latest depth snapshot, You will receive a full depth of data immediately. - channel:Channel name, such as
futures/depthIncrease20
- symbol: Trading pair, such as
BTCUSDT
Parameters Channel Name List
Channel Name | Description |
---|---|
futures/depthIncrease5 | 5 Level Depth Channel |
futures/depthIncrease20 | 20 Level Depth Channel |
futures/depthIncrease50 | 50 Level Depth Channel |
Response
Full depth snapshot data
{
"data": {
"symbol": "BTCUSDT",
"asks": [
{
"price": "70391.6",
"vol": "3550"
}
],
"bids": [
{
"price": "70391.2",
"vol": "1335"
}
],
"ms_t": 1730400086184,
"version": 980361,
"type": "snapshot"
},
"group": "futures/depthIncrease20:BTCUSDT"
}
Incremental depth data
{
"data": {
"symbol": "BTCUSDT",
"asks": [
{
"price": "70395.3",
"vol": "341"
},
{
"price": "70395.4",
"vol": "323"
}
],
"bids": [
{
"price": "70391.2",
"vol": "0"
},
{
"price": "70353.4",
"vol": "11435"
}
],
"ms_t": 1730400086194,
"version": 980362,
"type": "update"
},
"group": "futures/depthIncrease20:BTCUSDT"
}
Return data description:
Field | Type | Description |
---|---|---|
symbol | String | Symbol of the contract (like BTCUSDT ) |
asks | List | Asks Depth Array |
bids | List | Bids Depth Array |
ms_t | Long | Timestamp (in millisecond) |
version | Long | data version |
type | String | data type - snapshot =Full depth snapshot data - update =Incremental depth data |
Instruction
Description of the asks
bids
details field:
Field | Type | Description |
---|---|---|
price | String | price |
vol | String | volume |
How to correctly maintain a copy of OrderBook locally:
- First, the client send a subscription request
{"action": "subscribe", "args": ["futures/depthIncrease20:<symbol>"] }
- After successful subscription, you will receive two types of messages, type=
snapshot
(full data)和type=update
(update) - If a type=snapshot type message is received, update the deep snapshot content to the
local cache
. If there is nolocal cache
, create one. - If a type=update message is received, update the data in the deep snapshot to
local cache
. The update rules are as follows:- 4.1 If the field version number in the received new message is less than or equal to the version in the local cache(new version<=local version), this data can be discarded.
- 4.2 If the field version number in the new message received is equal to the version in the local cache plus 1(new version==local version+1), the quantity of the corresponding price will be
updated to the local cache
. - 4.3 If the field version number in the new message received is greater than the version in the local cache plus 1(new version>local version+1), please obtain the latest depth snapshot from step 7 and overwrite the
local cache
.
- The pending order volume in each returned message represents the
absolute value
of the current pending order volume at this price, rather than the relative change. - How to update local cache? Under the premise of 4.2:
- 6.1 New: If the same price is not already in the local cache, it means that it is a new pending order and needs to be added to the cache.
- 6.2 Modify or Remove: If the same price is already in the local cache, it means that the quantity has changed. If the quantity is 0, it will be directly removed from the cache. Otherwise, just change the quantity.
- Request through request
{"action": "request", "args": ["futures/depthIncrease20:<symbol>"] }
to obtain the latest depth snapshot (type=snapshot in the message), and add the depth The content in the snapshot is overwritten to thelocal cache
, and then the logic continues from step 2.
- Abnormal Situation:
- Because the depth snapshot has a limit on the number of price tiers, price tiers outside the initial snapshot and without quantity changes will not appear in the incremental depth update information. Therefore, even if all updates from the incremental depth are applied, these price brackets will not be visible in the local order book, so there may be some differences between the local order book and the real order book.
【Public】Trade Channel
Get trade data
Pushing Rules
- No user login required
- After subscribing, then the changes will be pushed
Request
Request
{
"action":"subscribe",
"args":["futures/trade:BTCUSDT"]
}
Message Format:
{"action":"subscribe","args":["<channel:symbol>","<channel:symbol>"]}
- actions:
subscribe
- channel: Channel name
futures/trade
, fixed value - symbol: Trading pair, such as
BTCUSDT
Response
Response
{
"group":"futures/trade:BTCUSDT",
"data":[{
"trade_id":1409495322,
"symbol":"BTCUSDT",
"deal_price":"117387.58",
"deal_vol":"1445",
"created_at":"2023-02-24T07:54:11.124940968Z"
}]
}
Return data description:
Field | Type | Description |
---|---|---|
symbol | String | symbol |
deal_price | String | deal price |
trade_id | Long | trade id |
deal_vol | String | deal vol |
way | int | Trading type - 1 =buy_open_long sell_open_short - 2 =buy_open_long sell_close_long - 3 =buy_close_short sell_open_short - 4 =buy_close_short sell_close_long - 5 =sell_open_short buy_open_long - 6 =sell_open_short buy_close_short - 7 =sell_close_long buy_open_long - 8 =sell_close_long buy_close_short |
created_at | String | create time |
【Public】klineBin Channel
Get individual contract K-line data
Pushing Rules
- No user login required
- After subscribing, then the changes will be pushed
Request
Request
{"action":"subscribe","args":["futures/klineBin1m:BTCUSDT"]}
Message Format:
{"action":"subscribe","args":["<channel:symbol>","<channel:symbol>"]}
- channel: Channel name, such as
futures/klineBin1m
- symbol: Trading pair, such as
BTCUSDT
Parameters Channel Name List
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
Response
{
"group":"futures/klineBin1m:BTCUSDT",
"data":{
"symbol":"BTCUSDT",
"o":"146.24",
"h":"146.24",
"l":"146.24",
"c":"146.24",
"v":"146",
"ts":1700533801
}
}
Return data description:
Field | 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 |
ts | Int64 | Timestamp |
【Private】Login
Login Subscription Format
Request Format
{"action":"access","args":["<API_KEY>","<timestamp>","<sign>","<dev>"]}
Please note that the following parameters are all of type String
API_KEY
: The user's API keytimestamp
: Timestamp, the unit is milliseconds, it will expire after 60 secondssign
: Signature, sign=CryptoJS.HmacSHA256(timestamp + "#" + your_api_memo + "#" + "bitmart.WebSocket", your_api_secret_key)dev
: Device, web eg.
Example
Login Example
{"action": "access", "args": ["80618e45710812162b04892c7ee5ead4a3cc3e56", "1589267764859", "3ceeb7e1b8cb165a975e28a2e2dfaca4d30b358873c0351c1a071d8c83314556","web"]}
Response
{"action":"access","success":true}
Assume that the values of the API requested by the user is as follows:
- timestamp=1589267764859
- API_KEY = "80618e45710812162b04892c7ee5ead4a3cc3e56"
- API_SECRET = "6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9"
- API_MEMO = "test001";
Ues Javascript create param sign
:
sign = CryptoJS.HmacSHA256(1589267764859 + "#" + test001 + "#" + "bitmart.WebSocket", '6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9')
= 3ceeb7e1b8cb165a975e28a2e2dfaca4d30b358873c0351c1a071d8c83314556
Ues Shell create param sign
:
sign = echo -n '1589267764859#test001#bitmart.WebSocket' | openssl dgst -sha256 -hmac "6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9"
(stdin)= 3ceeb7e1b8cb165a975e28a2e2dfaca4d30b358873c0351c1a071d8c83314556
The final login parameters are:
{"action": "access", "args": ["80618e45710812162b04892c7ee5ead4a3cc3e56", "1589267764859", "3ceeb7e1b8cb165a975e28a2e2dfaca4d30b358873c0351c1a071d8c83314556","web"]}
Note
【Private】Assets Channel
Get asset balance change
Pushing Rules
- User login required
- After subscribing, then the changes will be pushed
Request
Request
{
"action": "subscribe",
"args":["futures/asset:USDT", "futures/asset:BTC", "futures/asset:ETH"]
}
Message Format:
{"action":"subscribe","args":["<channel:currency>","<channel:currency>"]}
- actions:
subscribe
- channel: Channel name
futures/asset
, fixed value - currency: Currency, such as
BTC
, asset types that support subscriptions are: USDT (U-native), BTC (coin-native), ETH (coin-native)
Response
Response
{
"group": "futures/asset:BTC",
"data": {
"currency": "BTC",
"available_balance": "1000",
"position_deposit": "1000",
"frozen_balance": "1000"
}
}
Return data description:
Field | Type | Description |
---|---|---|
currency | String | Currency |
available_balance | String | Available Amount |
position_deposit | String | Position Margin |
frozen_balance | String | Transaction Frozen Amount |
【Private】Position Channel
Get Position Data
Pushing Rules
- User login required
- After subscribing, then the changes will be pushed
- 10 seconds timed push
Request
Request
{
"action": "subscribe",
"args":["futures/position"]
}
Message Format:
{"action":"subscribe","args":["<channel>"]}
- actions:
subscribe
- channel: Channel name
futures/position
, fixed value
Response
Response
{
"group": "futures/position",
"data": [
{
"symbol": "BTCUSDT",
"hold_volume": "2000",
"position_type": 1,
"open_type": 1,
"frozen_volume": "0",
"close_volume": "0",
"hold_avg_price": "19406.2092",
"close_avg_price": "0",
"open_avg_price": "19406.2092",
"liquidate_price": "15621.998406",
"create_time": 1662692862255,
"update_time": 1662692862255
}
]
}
Return data description:
Field | 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 | Long | Create time |
update_time | Long | Update time |
【Private】Order Channel
Order Channel, which pushes immediately when the order status, transaction amount, etc. changes.
Pushing Rules
- User login required
- After subscribing, then the changes will be pushed
Request
Request
{
"action": "subscribe",
"args": ["futures/order"]
}
Message Format:
{"action":"subscribe","args":["<channel>"]}
- actions:
subscribe
- channel: Channel name
futures/order
, fixed value
Response
Response
{
"group": "futures/order",
"data": [
{
"action": 3,
"order": {
"order_id": "220906179895578",
"client_order_id": "BM1234",
"price": "1",
"size": "1000",
"symbol": "BTCUSDT",
"state": 2,
"side": 1,
"type": "limit",
"leverage": "5",
"open_type": "isolated",
"deal_avg_price": "0",
"deal_size": "0",
"create_time": 1662368173000,
"update_time": 1662368173000,
"plan_order_id": "220901412155341",
"last_trade": {
"lastTradeID": 1247592391,
"fillQty": "1",
"fillPrice": "25667.2",
"fee": "-0.00027",
"feeCcy": "USDT"
},
"trigger_price": "-",
"trigger_price_type": "-",
"execution_price": "-",
"activation_price_type": "-",
"activation_price": "-",
"callback_rate": "-"
}
}
]
}
Return data description:
Field | Type | Description |
---|---|---|
action | Int | Action - 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 |
client_order_id | String | Client-defined OrderId |
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 - plan_order - trailing_order - take_profit - stop_loss |
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 - 1 =status_approval- 2 =status_check- 4 =status_finish |
create_time | Long | Create time |
update_time | Long | Update time |
plan_order_id | String | Trigger plan order id |
last_trade | object | recently trade info for this order,return null if not exist |
trigger_price | String | Trigger price of TP/SL / plan order |
trigger_price_type | String | Trigger price type of TP/SL / plan order - last_price - fair_price |
execution_price | String | Execution price of TP/SL / plan order |
activation_price | String | Activation price |
activation_price_type | String | Activation price type - last_price - fair_price |
callback_rate | String | Call back rate of trailing stop order |
market - market order execution
limit order price - limit order execution |
| activation_price | String | recently trade info for this order,return null if not exist |
| activation_price_type | String | Activation type
-last_price
-fair_price
|
| callback_rate | String | recently trade info for this order,return null if not exist |
Recently trade fields describe:
Parameter | Type | Description |
---|---|---|
lastTradeID | Long | recently trade id |
fillQty | String | last trade deal vol |
fillPrice | String | last trade deal price |
fee | String | last trade fee |
feeCcy | String | last trade fee coin name |
Futures Affiliate Endpoints
Get Futures Rebate List(KEYED)
Used for API affiliates to query contract rebate records within a certain time range
Request URL
GET https://api-cloud-v2.bitmart.com/contract/private/affiliate/rebate-list
Request Limit
Request Parameter
Request
curl https://api-cloud-v2.bitmart.com/contract/private/affiliate/rebate-list?page=1&size=10¤cy=USDT
Field | Type | Required | Description |
---|---|---|---|
user_id | Long | No | user ID |
page | Int | Yes | Page number |
size | Int | Yes | Number of records per page |
currency | String | Yes | query currency |
rebate_start_time | Long | No | Query rebate start timestamp |
rebate_end_time | Long | No | Query rebate end timestamp |
register_start_time | Long | No | Query register start timestamp |
register_end_time | Long | No | Query register end timestamp |
Response Data
Response
{
"total": 2,
"btc_rebate_sum": 0,
"size": 10,
"usdt_rebate_sum": 448.9697507148,
"page": 1,
"eth_rebate_sum": 0,
"rebate_detail_page_data": [{
"rebate_coin": "USDT",
"trade_user_id": 4225149,
"total_rebate_amount": 427.1825970576,
"user_type":1
}, {
"rebate_coin": "USDT",
"trade_user_id": 4225148,
"total_rebate_amount": 21.7871536572,
"user_type":1
}]
}
Field | Type | Description |
---|---|---|
btc_rebate_sum | Decimal | Total BTC rebates |
usdt_rebate_sum | Decimal | Total USDT rebates |
eth_rebate_sum | Decimal | Total ETH rebates |
rebate_detail_page_data | Object | Rebate details |
rebate_coin | String | Currency |
trade_user_id | Long | Trading user ID |
total_rebate_amount | Decimal | Total commission for the user |
user_type | Int | User type - 0 =Indirect- 1 =Direct |
Get Futures Trade List(KEYED)
Used for API affiliates to query contract rebate records within a certain time range
Request URL
GET https://api-cloud-v2.bitmart.com/contract/private/affiliate/trade-list
Request Limit
Request Parameter
Request
curl https://api-cloud-v2.bitmart.com/contract/private/affiliate/trade-list?user_id=123456&type=1&page=1&size=10
Field | Type | Required | Description |
---|---|---|---|
user_id | Long | Yes | userID |
type | Int | Yes | Query type: - 1 =U-based - 2 =Coin-based |
page | Int | Yes | Page number |
size | Int | Yes | Number of records per page |
start_time | Long | No | Query start timestamp |
end_time | Long | No | Query end timestamp |
Response Data
Response
{
"total": 60,
"size": 10,
"page": 1,
"list": [{
"leverage": 20.000000000000000000,
"symbol": "BTCUSDT",
"create_time": 1689933471000,
"open_type": 2,
"fee": 0.57162048,
"deal_price": 29771.900000000000000000,
"realised_profit": 0,
"way": 1,
"deal_vol": 32.000000000000000000,
"select_copy_trade": 1,
"user_type": 1,
"user_id": 10048829,
"category": 2
}]
}
Field | Type | Description |
---|---|---|
user_id | Long | userID |
user_type | Int | User Type: -Direct User -Indirect User |
create_time | Long | Creation Time |
symbol | String | symbol |
leverage | Int | leverage |
select_copy_trade | Int | Type: 1-Copy Trading 2-Non-Copy Trading |
open_type | Int | Position Type: - 1 =Isolated - 2 =Cross |
way | Int | Order Direction: - 1 =Long - 2 =Close Short - 3 =Close Long - 4 =Short |
category | Int | Order Type: - 1 =Limit Order - 2 =Market Order |
deal_price | Decimal | Average Deal Price |
deal_vol | Decimal | Deal Volume |
fee | Decimal | fee |
realised_profit | Decimal | Realized Profit and Loss |
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 |
Service maintenance, the function is temporarily unavailable | 30016 | 200 |
Your account request is temporarily rejected due to violation of current limiting rules, please contact customer service | 30017 | 418 |
Request Body requires JSON format | 30018 | 503 |
You do not have the permissions to perform this operation. Please contact customer service or BD for assistance | 30019 | 200 |
Futures V1 API has been deprecated. Please use Futures V2 API. You can view the change logs for upgrade | 30030 | 200 |
This endpoint has been deprecated. You can view the change logs for upgrade | 30031 | 200 |
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 |
Services is not available in you countries and areas | 40047 | 403 |
ClientOrderId only allows a combination of numbers and letters | 40048 | 403 |
The maximum length of clientOrderId cannot exceed 32 | 40049 | 403 |
Client OrderId duplicated with existing orders | 40050 | 403 |