Change Log
2023-10-27
- Added spot websocket Depth-Increase channel
spot/depth/increase100:
【Private】Depth-Increase channel
2023-09-08
- Added spot websocket balance change channel
spot/user/balance:BALANCE_UPDATE
【Private】Balance Change
2023-08-14
- New spot public market v3 endpoints
/spot/quotation/v3/tickers
Get Ticker of All Pairs (V3)/spot/quotation/v3/ticker
Get Ticker of a Trading Pair(V3)/spot/quotation/v3/lite-klines
Get Latest K-Line (V3)/spot/quotation/v3/klines
Get History K-Line (V3)/spot/quotation/v3/books
Get Depth(V3)/spot/quotation/v3/trades
Get Recent Trades(V3)
2023-05-09
- New spot query order endpoints
/spot/v4/query/order
Query order by id (v4)/spot/v4/query/client-order
Query order by client order id (v4)/spot/v4/query/open-orders
Current open orders (v4)/spot/v4/query/history-orders
Account orders (v4)/spot/v4/query/trades
Account trade list (v4)/spot/v4/query/order-trades
Order trade list(v4)
2023-03-03
- Update endpoints for Account
/spot/v1/user_fee
Add new field taker_fee_rate_C and maker_fee_rate_C
2022-12-22
- Update endpoints for Spot
- WebSocket Subscription-【Private】Order Progress add new order status 12 = Partially filled and canceled
2022-11-03
- Update endpoints for Spot / Margin trading
/spot/v3/orders
/spot/v2/trades
add start_time and end_time field for flexible querying- add new order status 11 = Partially filled and canceled
2022-11-01
- Update endpoints for Account
/account/v1/currencies
Add new field contract_address,withdraw_minsize and withdraw_minfee
2022-10-11
- The new version of market data-relateded endpoints
/spot/v2/ticker
/spot/v1/ticker_detail
2022-09-29
- New spot trading endpoints
/spot/v2/submit_order
/spot/v2/batch_orders
/spot/v3/cancel_order
/spot/v2/order_detail
/spot/v3/orders
/spot/v2/trades
2022-08-16
- New Endpoint for Trade Fee
/spot/v1/trade_fee
- New Endpoint for Basic Fee
/spot/v1/user_fee
2022-07-07
- New endpoints for the margin loan
/spot/v1/margin/isolated/borrow
/spot/v1/margin/isolated/repay
/spot/v1/margin/isolated/borrow_record
/spot/v1/margin/isolated/repay_record
/spot/v1/margin/isolated/pairs
- New endpoint for margin trading
/spot/v1/margin/submit_order
- New endpoints for margin accounts
/spot/v1/margin/isolated/account
/spot/v1/margin/isolated/transfer
- Update endpoints for Spot / Margin trading
- A new "order_mode" field has been added to the following endpoints to distinguish whether the order originates from a spot or margin trade
/spot/v1/order_detail
/spot/v2/orders
/spot/v1/trades
2022-05-24
- Update endpoints for Spot
/spot/v2/orders
Add new field clientOrderId/spot/v1/trades
Add new field clientOrderId/spot/v1/order_detail
Add new field clientOrderId
2022-04-19
- New sub-account endpoints
/sub-account/main/v1/sub-to-main
/sub-account/sub/v1/sub-to-main
/sub-account/main/v1/main-to-sub
/sub-account/sub/v1/sub-to-sub
/sub-account/main/v1/sub-to-sub
/sub-account/main/v1/transfer-list
/sub-account/v1/transfer-history
/sub-account/main/v1/wallet
/sub-account/main/v1/subaccount-list
- Update WebSocket Order Progress channel
- Add new field client_order_id
- Add new field detail_id
2022-03-29
- WebSocket subscription, 【private】 order channel renamed to 【private】 order progress
- New parameter exec_type is added to 【Private】 order progress channel, which indicates liquidity type
2022-03-08
- Improvement of Websocket connection holding
- Catalog level repair to enhance readability
2022-03-01
- support user to create , request and cancel order through client-defined OrderId
2022-02-15
- increase the maximum rate limit based on users' feedback
- improve UI of the document
2022-01-20
- Update endpoints for Spot
/spot/v1/symbols/details
Add a new respond parameter trade_status, to show the trading status of a trading pair symbol.
2022-01-18
- websocket public channel address
wss://ws-manager-compress.bitmart.com?protocol=1.1
will be taken down on 2022-02-28 UTC time,The new address iswss://ws-manager-compress.bitmart.com/api?protocol=1.1
2021-11-24
- New endpoints for Spot
/spot/v2/orders
Get User Order History V2/spot/v1/batch_orders
Batch Order
- Update endpoints for Spot
/spot/v1/symbols/kline
Add new field 'quote_volume'/spot/v1/symbols/trades
Add optional parameter N to return the number of items, the default is up to 50 items/spot/v1/order_detail
Add new field 'unfilled_volume'/spot/v1/submit_order
The request parameter type added limit_maker and ioc order types
- New endpoints for Account
/account/v2/deposit-withdraw/history
Get Deposit And Withdraw History V2
- Update endpoints for Account
/account/v1/wallet
Remove the account_type,Only respond to currency accounts; you can bring currency parameters (optional)
2021-11-06
- Update endpoints for Spot WebSocket
- Public-Depth Channel:
- spot/depth50 50 Level Depth Channel
- spot/depth100 100 Level Depth Channel
- User-Trade Channel:
- Eligible pushes add new orders successfully
2021-01-19
- New endpoints for Spot WebSocket
- Public - ticket channels
- Public - K channel
- Public - trading channels
- Public - depth channels
- Login
- User - Trading Channel
2020-07-15
- New endpoints for Spot
/spot/v2/cancel_order
Cancel an outstanding order,V2
2020-06-29
- New endpoints for Account
/account/v1/currencies
Get Currency/account/v1/wallet
Get Account Balance/account/v1/deposit/address
Deposit Address/account/v1/withdraw/charge
Withdraw Quota/account/v1/withdraw/apply
Withdraw/account/v1/recharge-withdraw/history
Get Deposit And Withdraw History/account/v1/recharge-withdraw/detail
Get A Deposit Or Withdraw Detail
2020-05-14
- New endpoints for Spot
/spot/v1/currencies
Get a list of all cryptocurrencies on the platform/spot/v1/symbols
Get a list of all trading pairs on the platform/spot/v1/symbols/details
Get a detailed list of all trading pairs on the platform/spot/v1/ticker
Get ticker/spot/v1/steps
Get K-Line steps/spot/v1/symbols/kline
Get k-Line/spot/v1/symbols/book
Get orderbook/spot/v1/symbols/trades
Get trades/spot/v1/wallet
Get user wallet/spot/v1/submit_order
Place order/spot/v1/cancel_order
Cancel order/spot/v1/cancel_orders
Cancel all outstanding orders in the specified direction for the specified trading pair/spot/v1/order_detail
Get order details/spot/v1/orders
Get user recent orders/spot/v1/trades
Get user trade history
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.)Contract-Trade
(long position, short position, closing position, etc.)
Read-Only Permissions:
API Name | Description | Authentication Type |
---|---|---|
/account/v1/wallet | Query account assets | KEYED |
/account/v1/deposit/address | Query deposit addresses for each currency | KEYED |
/account/v2/deposit-withdraw/history | Query deposit and withdrawal history | KEYED |
/account/v1/deposit-withdraw/detail | Query deposit and withdrawal details | KEYED |
/spot/v1/wallet | Query wallet balance for all currencies | KEYED |
/spot/v1/order_detail | Query order details | KEYED |
/spot/v2/order_detail | Query order details | KEYED |
/spot/v1/orders | Query user's recent orders | KEYED |
/spot/v2/orders | Query user's recent orders | KEYED |
/spot/v3/orders | Query user's recent orders | KEYED |
/spot/v1/trades | Query user's trade history | KEYED |
/spot/v2/trades | Query user's trade history | KEYED |
/spot/v4/query/order | Query order by id (v4) | SIGNED |
/spot/v4/query/client-order | Query order by client order id (v4) | SIGNED |
/spot/v4/query/open-orders | Current open orders (v4) | SIGNED |
/spot/v4/query/history-orders | Account orders (v4) | SIGNED |
/spot/v4/query/trades | Account trade list (v4) | SIGNED |
/spot/v4/query/order-trades | Order trade list(v4) | SIGNED |
/spot/v1/user_fee | Query basic fee rate for current user | KEYED |
/spot/v1/trade_fee | Query fee rate for a specific trading pair for current user | KEYED |
/spot/v1/margin/isolated/pairs | Query loan interest rate and limit for a trading pair | KEYED |
/spot/v1/margin/isolated/account | Query isolated margin account information | KEYED |
/spot/v1/margin/isolated/borrow_record | Query isolated margin borrowing record | KEYED |
/spot/v1/margin/isolated/repay_record | Query isolated margin repayment record | KEYED |
/contract/private/get-open-orders | Query Contract All Open Orders | KEYED |
/contract/private/order | Query contract order details | KEYED |
/contract/private/order-history | Query contract order history | KEYED |
/contract/private/trades | Query contract trade details | KEYED |
/contract/private/assets-detail | Query contract asset details | KEYED |
/contract/private/position | Query position details | KEYED |
Withdraw Permissions:
API Name | Description | Authentication Type |
---|---|---|
/account/v1/withdraw/charge | Query withdrawal limits | KEYED |
/account/v1/withdraw/apply | Apply for withdrawal | SIGNED |
Spot-Trade Permissions:
API Name | Description | Authentication Type |
---|---|---|
/spot/v1/submit_order | Place an order | SIGNED |
/spot/v2/submit_order | Place an order | SIGNED |
/spot/v1/batch_orders | Place multiple orders | SIGNED |
/spot/v2/batch_orders | Place multiple orders | SIGNED |
/spot/v1/cancel_order | Cancel an unfinished order | SIGNED |
/spot/v3/cancel_order | Cancel an unfinished order | SIGNED |
/spot/v1/cancel_orders | Cancel all unfinished orders for a specified trading pair and direction | SIGNED |
Margin-Trade Permissions:
API Name | Description | Authentication Type |
---|---|---|
/spot/v1/margin/submit_order | Margin order placement | SIGNED |
/spot/v1/margin/isolated/transfer | Transfer funds between margin and spot accounts | SIGNED |
/spot/v1/margin/isolated/borrow | Isolated margin borrowing | SIGNED |
/spot/v1/margin/isolated/repay | Repay isolated margin debt | SIGNED |
Contract-Trade Permissions:
API Name | Description | Authentication Type |
---|---|---|
/contract/private/submit-order | Place an order for a futures contract | SIGNED |
/contract/private/cancel-order | Cancel a single futures order | SIGNED |
/contract/private/cancel-orders | Batch cancel futures orders | SIGNED |
/contract/private/submit-plan-order | Place a batch order for futures contracts | SIGNED |
/contract/private/cancel-plan-order | Batch cancel futures orders | SIGNED |
/account/v1/transfer-contract | Future account transfer | SIGNED |
/account/v1/transfer-contract-list | Get Future account transfer list | SIGNED |
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, ues spot account) | SIGNED |
/account/sub-account/sub/v1/sub-to-main | Sub-Account Transfer to Main-Account (For Sub-Account, ues spot account) | SIGNED |
/account/sub-account/main/v1/main-to-sub | Main-Account Transfer to Sub-Account (For Main Account, ues spot account) | SIGNED |
/account/sub-account/sub/v1/sub-to-sub | Sub-Account Transfer to Sub-Account (For Sub-Account, ues spot account) | SIGNED |
/account/sub-account/main/v1/sub-to-sub | Sub-Account Transfer to Sub-Account (For Main Account, ues spot account) | SIGNED |
/account/sub-account/main/v1/transfer-list | Get Sub-Account Transfer History (For Main Account, ues spot account) | KEYED |
/account/sub-account/v1/transfer-history | Get Account Spot Asset Transfer History (For Main/Sub Account, ues spot account) | KEYED |
/account/sub-account/main/v1/wallet | Get Sub-Account Spot Wallet Balance (For Main Account, ues spot account) | KEYED |
/account/sub-account/main/v1/subaccount-list | Get Sub-Account List (For Main Account, ues spot account) | KEYED |
/account/contract/sub-account/main/v1/sub-to-main | Sub-Account Transfer to Main-Account (For Main Account, ues futures account) | SIGNED |
/account/contract/sub-account/main/v1/main-to-sub | Main-Account Transfer to Sub-Account (For Main Account, ues futures account) | SIGNED |
/account/contract/sub-account/sub/v1/sub-to-main | Sub-Account Transfer to Main-Account (For Sub-Account, ues futures account) | SIGNED |
/account/contract/sub-account/main/v1/wallet | Get Sub-Account Futures Wallet Balance (For Main Account, ues futures account) | KEYED |
/account/contract/sub-account/v1/transfer-history | Get Account Futures Asset Transfer History (For Main/Sub Account, ues futures account) | KEYED |
/account/contract/sub-account/main/v1/transfer-list | Get Sub-Account Transfer History (For Main Account, ues 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
- Javascript 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?
Contact Us
- Get support in our Telegram group BitMart API Club
- Please take 1 minute to help us improve: API Satisfaction Survey
Basic Information
API Basic Information
- This article lists the rest baseurl of the interfaces: https://api-cloud.bitmart.com
- All interface responses are in JSON format.
Request Parameter Settings
- For
GET
andDELETE
method interfaces, parameters must be sent in the query string, i.e., the parameters concatenated after theURL?
. - For
POST
andPUT
method interfaces, parameters are sent in the request body in JSON format.
HTTP Response Codes
- HTTP 4XX Error codes are used to indicate wrong request content, behavior, and format. The problem is from the request sender.
- HTTP 403 The error code indicates a violation of the restriction (prohibited call).
- HTTP 429 The error code indicates that the access frequency is overrun and the IP will be blocked.
- HTTP 418 The error code indicates that the IP has been blocked after error code 429.
- HTTP 5XX Error codes are used to indicate problems with BitMart server.
API Returned Codes
code
Error codemessage
Error descriptiontrace
Event tracking ID for each request, which is returned by the server for every requestdata
User Data
For details, please refer to Error Code List
Signature
The authentication type of each API endpoint will be indicated.
If it is marked as SIGNED
,it means that the endpoint requires a signature to access.
If it is marked as KEYED
, it means that the endpoint only requires an API Access KEY to be set in the request header.
Authentication Type
NONE
: Public endpoint, accessible to anyoneKEYED
: Endpoint requires a valid X-BM-KEY to be set in the request headerSIGNED
: Endpoint requires a valid X-BM-KEY and X-BM-SIGN signature to be set in the request header
1. Setting Request Parameters
1.1 Set Request Header Key
Create X-BM-TIMESTAMP
// Java
System.currentTimeMillis();
// Python
int(time.time() * 1000)
// Golang
time.Now().UnixNano() / int64(time.Millisecond)
// Nodejs & TypeScript
Date.now();
// Javascript
Date.now();
// PHP
round(microtime(true) * 1000)
// C#
DateTimeOffset.UtcNow.ToUnixTimeMilliseconds()
X-BM-KEY
(Your created API Access KEY)X-BM-SIGN
(Signature using Sha-256)X-BM-TIMESTAMP
(Current timestamp in milliseconds when the request is sent)
1.2 Set Request Body Params
- For
GET/DELETE
requests, the query string is in form format, such assymbol=BMX&side=BUY
. - For
POST/PUT
requests, the query string is in JSON format, such as{"symbol":"BMX","side":"BUY"}
.
2. Example
Shell Example
echo -n '1589793796145#test001#{"symbol":"BTC_USDT","price":"8600","count":"100"}' | openssl dgst -sha256 -hmac "6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9"
(stdin)= c31dc326bf87f38bfb49a3f8494961abfa291bd549d0d98d9578e87516cee46d
curl --location --request POST 'localhost:8080/spot/v1/test-post'
--header 'Content-Type: application/json'
--header 'X-BM-KEY: 80618e45710812162b04892c7ee5ead4a3cc3e56'
--header 'X-BM-SIGN: c31dc326bf87f38bfb49a3f8494961abfa291bd549d0d98d9578e87516cee46d'
--header 'X-BM-TIMESTAMP: 1589793796145'
--d '{"symbol":"BTC_USDT","price":"8600","count":"100"}'
- Request API: /spot/v1/test-post (SIGNED)
- Request method: POST
- Current timestamp: timestamp=
1589793796145
- Request body:
{"symbol":"BTC_USDT","price":"8600","count":"100"}
Then set the following:
- X-BM-TIMESTAMP=
1589793796145
- X-BM-KEY=
Your_api_access_key
- X-BM-SIGN= hmac_sha256(
Your_api_secret_key
,X-BM-TIMESTAMP
+ '#' +Your_api_memo
+ '#' +{"symbol":"BTC_USDT","price":"8600","count":"100"}
)
Assuming the key you applied for is as follows:
accessKey
=80618e45710812162b04892c7ee5ead4a3cc3e56secretKey
=6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9memo
=test001
then the right side is a complete request
You can also refer to the SDK or Quick Start API below to implement
Rate Limit
The speed of the public interface is limited according to the IP, and the speed of the private interface is limited according to the API KEY. When the requests exceed the rate limit, the 429 status will be returned: the request is too frequent.
The specific interface limits are as follows:
System Interface | Interface Name | Limit Target | Rate |
---|---|---|---|
/system/time | Get system time | IP | 10 times/sec |
/system/service | Get system service status | IP | 10 times/sec |
Funding Account Interface | Interface Name | Limit Target | Rate |
---|---|---|---|
/account/v1/currencies | Get currencies | IP | 2 times/2 sec |
/account/v1/wallet | Get account balance | X-BM-KEY | 12 times/2 sec |
/account/v1/deposit/address | Deposit address | X-BM-KEY | 2 times/2 sec |
/account/v1/withdraw/charge | Withdraw quota | X-BM-KEY | 2 times/2 sec |
/account/v1/withdraw/apply | Withdraw | X-BM-KEY | 8 times/2 sec |
/account/v2/deposit-withdraw/history | Get deposit and withdraw history V2 | X-BM-KEY | 8 times/2 sec |
/account/v1/deposit-withdraw/detail | Get a deposit Or withdraw detail | X-BM-KEY | 8 times/2 sec |
/spot/v1/margin/isolated/account | Get Margin Account Details(Isolated) | X-BM-KEY | 12 times/2 sec |
/spot/v1/margin/isolated/transfer | Margin Asset Transfer | X-BM-KEY | 2 times/2 sec |
/spot/v1/user_fee | Basic Fee Rate | X-BM-KEY | 2 times/2 sec |
/spot/v1/trade_fee | Actual Trade Fee Rate | X-BM-KEY | 2 times/2 sec |
Spot Public Market Interface | Interface Name | Limit Target | Rate |
---|---|---|---|
/spot/v1/currencies | Get a list of all cryptocurrencies | IP | 8 times/2 sec |
/spot/v1/symbols | Get a list of all trading pairs | IP | 8 times/2 sec |
/spot/v1/symbols/details | Get a detailed list of all trading pairs | IP | 12 times/2 sec |
/spot/v1/ticker | Get ticker | IP | 12 times/2 sec |
/spot/v2/ticker | Get Ticker of All Pairs | IP | 2 times/2 sec |
/spot/v1/ticker_detail | Get Ticker of a Trading Pair | IP | 12 times/2 sec |
/spot/v1/steps | Get K-Line steps | IP | 2 times/2 sec |
/spot/v1/symbols/kline | Get k-Line | IP | 12 times/2 sec |
/spot/v1/symbols/book | Get orderbook | IP | 12 times/2 sec |
/spot/v1/symbols/trades | Get the latest trades | IP | 12 times/2 sec |
/spot/quotation/v3/tickers | Get Ticker of All Pairs (V3) | IP | 10 times/2 sec |
/spot/quotation/v3/ticker | Get Ticker of a Trading Pair(V3) | IP | 15 times/2 sec |
/spot/quotation/v3/lite-klines | Get Latest K-Line (V3) | IP | 15 times/2 sec |
/spot/quotation/v3/klines | Get History K-Line (V3) | IP | 10 times/2 sec |
/spot/quotation/v3/books | Get Depth(V3) | IP | 15 times/2 sec |
/spot/quotation/v3/trades | Get Recent Trades(V3) | IP | 15 times/2 sec |
Spot Trading Interface | Interface Name | Limit Target | Rate |
---|---|---|---|
/spot/v1/wallet | Get the user's wallet balance(KEYED) | X-BM-KEY | 12 times/2 sec |
/spot/v1/submit_order | New Order (SIGNED) | X-BM-KEY | 60 times/2 sec |
/spot/v2/submit_order | New Order(v2) (SIGNED) | X-BM-KEY | 60 times/2 sec |
/spot/v1/batch_orders | New Batch Order (SIGNED) | X-BM-KEY | 60 times/2 sec |
/spot/v2/batch_orders | New Batch Order(v2) (SIGNED) | X-BM-KEY | 60 times/2 sec |
/spot/v1/margin/submit_order | New Margin Order (SIGNED) | X-BM-KEY | 60 times/2 sec |
/spot/v2/cancel_order | Cancel Order(v2) (SIGNED) | X-BM-KEY | 60 times/2 sec |
/spot/v3/cancel_order | Cancel Order(v3) (SIGNED) | X-BM-KEY | 60 times/2 sec |
/spot/v1/cancel_orders | Cancel Batch Order (SIGNED) | X-BM-KEY | 4 times/2 sec |
/spot/v1/order_detail | Query Order(v1) (KEYED) | X-BM-KEY | 60 times/2 sec |
/spot/v2/order_detail | Query Order(v2) (KEYED) | X-BM-KEY | 60 times/2 sec |
/spot/v2/orders | Account Orders(v2) (KEYED) | X-BM-KEY | 12 times/2 sec |
/spot/v3/orders | Account Orders(v3) (KEYED) | X-BM-KEY | 12 times/2 sec |
/spot/v1/trades | Account Trade List(v1) (KEYED) | X-BM-KEY | 12 times/2 sec |
/spot/v2/trades | Account Trade List(v2) (KEYED) | X-BM-KEY | 12 times/2 sec |
/spot/v4/query/order | Query Order By Id(v4) (SIGNED) | X-BM-KEY | 60 times/2 sec |
/spot/v4/query/client-order | Query Order By clientOrderId(v4) (SIGNED) | X-BM-KEY | 60 times/2 sec |
/spot/v4/query/open-orders | Current Open Orders(v4) (SIGNED) | X-BM-KEY | 12 times/2 sec |
/spot/v4/query/history-orders | Account Orders(v4) (SIGNED) | X-BM-KEY | 12 times/2 sec |
/spot/v4/query/trades | Account Trade List(v4) (SIGNED) | X-BM-KEY | 12 times/2 sec |
/spot/v4/query/order-trades | Order Trade List(v4) (SIGNED) | X-BM-KEY | 12 times/2 sec |
Sub-Account Interface | Interface Name | Limit Target | Rate |
---|---|---|---|
/account/sub-account/main/v1/sub-to-main | Sub-Account Spot Asset Transfer (For Main Account) | X-BM-KEY | 2 times/2 sec |
/account/sub-account/sub/v1/sub-to-main | Sub-Account Spot Asset Transfer (For Sub-Account) | X-BM-KEY | 2 times/2 sec |
/account/sub-account/main/v1/main-to-sub | Main Account Spot Asset Transfer (For Main Account) | X-BM-KEY | 2 times/2 sec |
/account/sub-account/sub/v1/sub-to-sub | Sub-Account to Sub-Account Spot Asset Transfer (For Sub-Account) | X-BM-KEY | 2 times/2 sec |
/account/sub-account/main/v1/sub-to-sub | Sub-account to Sub-Account Spot Asset Transfer (For Main Account) | X-BM-KEY | 2 times/2 sec |
/account/sub-account/main/v1/transfer-list | Query Sub-account Spot Asset Transfer History (For Main Account) | X-BM-KEY | 8 times/2 sec |
/account/sub-account/v1/transfer-history | Get Account Spot Asset Transfer History | X-BM-KEY | 8 times/2 sec |
/account/sub-account/main/v1/wallet | Get Sub-Account Spot Wallet Balance (For Main Account) | X-BM-KEY | 12 times/2 sec |
/account/sub-account/main/v1/subaccount-list | Get Sub-account List (For Main Account) | X-BM-KEY | 8 times/2 sec |
Margin Loan Interface | Interface Name | Limit Target | Rate |
---|---|---|---|
/spot/v1/margin/isolated/borrow | Margin Borrow (Isolated) | X-BM-KEY | 2 times/2 sec |
/spot/v1/margin/isolated/repay | Margin Repay (Isolated) | X-BM-KEY | 2 times/2 sec |
/spot/v1/margin/isolated/borrow_record | Get Borrow Record(Isolated) | X-BM-KEY | 60 times/2 sec |
/spot/v1/margin/isolated/repay_record | Get Repayment Record(Isolated) | X-BM-KEY | 60 times/2 sec |
/spot/v1/margin/isolated/pairs | Get Trading Pair Borrowing Rate and Amount | X-BM-KEY | 2 times/2 sec |
REST API
Speed limit judgment:
Each call to the interface will return 3 Response Headers with limit tags, as shown below:
Example:
X-BM-RateLimit-Remaining: 10
X-BM-RateLimit-Limit: 600
X-BM-RateLimit-Reset: 60
The above setting means that it can be called 600 times within 60 seconds, and currently has been called 10 times
Response Header | Description |
---|---|
X-BM-RateLimit-Remaining | The number of requests left in the current time window |
X-BM-RateLimit-Limit | The max number of requests in the current time window |
X-BM-RateLimit-Reset | Current time window, in seconds |
About recvWindow, timestamp
Currently only applicable to v4 interfaces
Time synchronization security
Signed interfaces require the timestamp parameter to be passed,
whose value should be the Unix timestamp (in milliseconds) at the time the request is sent,
set in the X-BM-TIMESTAMP
header of the request.
When the server receives the request, it will check the timestamp in the request.
If it was sent more than 5000 milliseconds ago, the request will be considered invalid.
This time window value can be defined by sending the optional parameter recvWindow
.
The pseudo code for this logic is as follows:
if (timestamp < (serverTime + 1000) && (serverTime - timestamp) <= recvWindow)
{
// process request
}
else
{
// reject request
}
About trade timeliness
The internet is not always stable and reliable,
so there may be latency fluctuations between your program and the BitMart server.
This is the purpose of setting recvWindow
.
If you are engaged in high-frequency trading and have high requirements for trade timeliness,
you can set recvWindow flexibly to meet your requirements.
Public API Definitions
Field description
currency
Currency refers to the basic unit that can be transferred in and out, such as BTC, ETH, EOS, etcsymbol
Trading pair name, consists of base and quote currency. Taking BTC_USDT as an example, BTC is the base currency, and USDT is the quote currency. Trading pairs are mainly used in spot tradingorderId
Order number, the order ID under the same currency pair of each business line is uniquetradeId
The unique number of the trade
Order State (Field:state)
new
=The order has been accepted by the engine.partially_filled
=A part of the order has been filled.filled
=The order has been completed.canceled
=The order has been canceled by the user.partially_canceled
=A part of the order has been filled , and the order has been canceled.
Order Side (Field:side)
buy
=Buysell
=Sell
Order Type (Field:type)
limit
=Limit Ordermarket
=Market Orderlimit_maker
=PostOnly Orderioc
=IOC Order
Trade Role (Field:tradeRole)
taker
=Take orders, take the initiative to dealmaker
=Pending order, passive transaction
Timestamp
All the times returned by the system are in the form of timestamps.
System Status
Get System Time
Get system time
Request URL
GET https://api-cloud.bitmart.com/system/time
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/system/time
None
Response Data
Response
{
"code": 1000,
"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
"message": "OK",
"data": {
"server_time": 1527777538000
}
}
Field | Type | Description |
---|---|---|
server_time | Long | Current system time (timestamp, accuracy in milliseconds) |
Get System Service Status
Get system service status
Request URL
GET https://api-cloud.bitmart.com/system/service
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/system/service
None
Response Data
Response
{
"code": 1000,
"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
"message": "OK",
"data": {
"serivce":[
{
"title": "Spot API Stop",
"service_type": "spot",
"status": "2",
"start_time": 1527777538000,
"end_time": 1527777538000
},
{
"title": "Contract API Stop",
"service_type": "contract",
"status": "2",
"start_time": 1527777538000,
"end_time": 1527777538000
}
]
}
}
Field | Type | Description |
---|---|---|
title | String | System maintenance instructions title |
status | Long | System maintenance status - 0 =Waiting - 1 =Working - 2 =Completed |
service_type | String | Service type - spot =Spot API service - contract =Contract API service |
start_time | Long | System maintenance start time, UTC-0, timestamp accuracy in milliseconds |
end_time | Long | System maintenance end time, UTC-0, timestamp accuracy in milliseconds |
Public Market Data
Get Currency List (V1)
Get a list of all cryptocurrencies on the platform
Request URL
GET https://api-cloud.bitmart.com/spot/v1/currencies
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v1/currencies
None
Response Data
Response
{
"code": 1000,
"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
"message": "OK",
"data": {
"currencies": [
{
"id": "BTC",
"name": "Bitcoin",
"withdraw_enabled": true,
"deposit_enabled": true
},
{
"id": "ETH",
"name": "Ethereum",
"withdraw_enabled": true,
"deposit_enabled": true
}
]
}
}
Field | Type | Description |
---|---|---|
id | String | Currency abbreviation, such as BTC |
name | String | Currency full name, such as Bitcoin |
withdraw_enabled | Boolean | Whether this currency can be withdrawn on the platform - true =can - false =no |
deposit_enabled | Boolean | Whether this currency can be deposited on the platform - true =can - false =no |
Get Trading Pairs List (V1)
Get a list of all trading pairs on the platform
Request URL
GET https://api-cloud.bitmart.com/spot/v1/symbols
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v1/symbols
None
Response Data
Response
{
"code": 1000,
"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
"message": "OK",
"data": {
"symbols": [
"BMX_ETH",
"XLM_ETH",
"MOBI_ETH"
]
}
}
Field | Type | Description |
---|---|---|
symbols | List |
Array of trading pairs |
Note
- Returns an array of trading pairs
- "BMX_ETH" it means that the base currency of this trading pair is BMX, and the quote currency is ETH
Get Trading Pair Details (V1)
Get a detailed list of all trading pairs on the platform
Request URL
GET https://api-cloud.bitmart.com/spot/v1/symbols/details
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v1/symbols/details
None
Response Data
Response
{
"code": 1000,
"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
"message": "OK",
"data": {
"symbols": [
{
"symbol":"GXC_BTC",
"symbol_id":1024,
"base_currency":"GXC",
"quote_currency":"BTC",
"quote_increment":"1.00000000",
"base_min_size":"1.00000000",
"price_min_precision":6,
"price_max_precision":8,
"expiration":"NA",
"min_buy_amount":"0.00010000",
"min_sell_amount":"0.00010000",
"trade_status":"trading"
}
]
}
}
Field | Type | Description |
---|---|---|
symbols | List | Array of trading pair details |
symbol | String | Trading pair name |
symbol_id | Int | Trading pair id |
base_currency | String | Base currency |
quote_currency | String | Quote currency |
quote_increment | String | The minimum order quantity is also the minimum order quantity increment |
base_min_size | String | Minimum order quantity |
price_min_precision | Number | Minimum price accuracy (decimal places), used to query k-line and depth |
price_max_precision | Number | Maximum price accuracy (decimal places), used to query k-line and depth |
expiration | String | Expiration time of trading pair |
min_buy_amount | String | Minimum order amount |
min_sell_amount | String | Minimum sell amount |
trade_status | String | Trade Status - trading =is trading - pre-trade =pre-open |
Get Ticker of All Pairs (V3)
Get the quotations of all trading pairs, including: snapshot information of the latest transaction price, first bid price, first ask price and 24-hour trading volume.
Note that the interface is not real-time data, if you need real-time data, please use websocket to subscribe Ticker channel
Request URL
GET https://api-cloud.bitmart.com/spot/quotation/v3/tickers
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/quotation/v3/tickers`
None
Response Data
Response
{
"code": 1000,
"trace":"886fb6ae-456b-4654-b4e0-1231",
"message": "success",
"data": [
[
"BTC_USDT", // symbol
"30000.00", // last
"582.08066", // v_24h
"4793098.48", // qv_24h
"28596.30", // open_24h
"31012.44", // high_24h
"12.44", // low_24h
"0.04909", // fluctuation
"30000", // bid_px
"1", // bid_sz
"31012.44", // ask_px
"69994.75267", // ask_sz
"1691671091933" // ts
],
[
"ETH_USDT",
"1840.00",
"2.00000",
"3680.00",
"1842.18",
"1842.18",
"1840.00",
"-0.00118",
"1812.35",
"4.61989",
"1859.34",
"4.07793",
"1691671094213"
]
]
}
Field | Type | Description |
---|---|---|
symbol | String | Trading pair |
last | String | Latest price |
v_24h | String | 24-hour trade volume in base currency |
qv_24h | String | 24-hour trade volume in quote currency |
open_24h | String | 24-hour open price |
high_24h | String | 24-hour highest price |
low_24h | String | 24-hour lowest price |
fluctuation | String | 24-hour price change |
bid_px | String | top buy price |
bid_sz | String | Size of top buy order |
ask_px | String | top sell price |
ask_sz | String | Size of top sell order |
ts | String | Time of generation(in milliseconds) |
Get Ticker of a Trading Pair (V3)
Applicable to query the aggregated market price of a certain trading pair, and return the latest ticker information.
Note that the interface is not real-time data, if you need real-time data, please use websocket to subscribe Ticker channel
Request URL
GET https://api-cloud.bitmart.com/spot/quotation/v3/ticker
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/quotation/v3/ticker?symbol=BTC_USDT
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Trading pair (e.g. BMX_USDT) |
Response Data
Response
{
"code": 1000,
"trace":"886fb6ae-456b-4654-b4e0-1231",
"message": "success",
"data": {
"symbol": "BTC_USDT",
"last": "30000.00",
"v_24h": "582.08066",
"qv_24h": "4793098.48",
"open_24h": "28596.30",
"high_24h": "31012.44",
"low_24h": "12.44",
"fluctuation": "0.04909",
"bid_px": "30000",
"bid_sz": "1",
"ask_px": "31012.44",
"ask_sz": "69994.75267",
"ts": "1691671061919"
}
}
Field | Type | Description |
---|---|---|
symbol | String | Trading pair |
last | String | Latest price |
v_24h | String | 24-hour trade volume in base currency |
qv_24h | String | 24-hour trade volume in quote currency |
open_24h | String | 24-hour open price |
high_24h | String | 24-hour highest price |
low_24h | String | 24-hour lowest price |
fluctuation | String | 24-hour price change |
bid_px | String | top buy price |
bid_sz | String | Size of top buy order |
ask_px | String | top sell price |
ask_sz | String | Size of top sell order |
ts | String | Time of generation(in milliseconds) |
Get Latest K-Line (V3)
Query the latest K-line and return a maximum of 1000 data. Note that the latest K-line of the interface is not real-time data.
If you want real-time data, please use websocket to subscribe to K-line channel
Request URL
GET https://api-cloud.bitmart.com/spot/quotation/v3/lite-klines
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/quotation/v3/lite-klines?symbol=BMX_ETH&step=15&before=1525760116&after=1525769116&limit=100
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Trading pair (e.g. BMX_USDT ) |
before | Long | No | Query timestamp (unit: second), query the data before this time |
after | Long | No | Query timestamp (unit: second), query the data after this time |
step | Int | No | k-line step, value [1, 3, 5, 15, 30, 45, 60, 120, 180, 240, 1440, 10080, 43200] unit: minute, default 1 |
limit | Int | No | Return number, the maximum value is 200, default is 100 |
Response Data
Response
{
"code":1000,
"trace":"886fb6ae-456b-4654-b4e0-1231",
"message": "success",
"data":[
[
"1689736680", // t
"3.721", // o
"3.743", // h
"3.677", // l
"3.708", // c
"22698348.04828491", // v
"12698348.04828491" // qv
],
[
"1689736620",
"3.731",
"3.799",
"3.494",
"3.72",
"67632347.24399722",
"37632347.24399722"
]
]
}
Field | Type | Description |
---|---|---|
t | String | Create timestamp (in seconds), It can be used as the unique identification of K line |
o | String | Open price |
h | String | Highest price |
l | String | Lowest price |
c | String | Close price |
v | String | Trading volume, with a unit of currency (If in BTC_USDT, The unit is BTC) |
qv | String | Trading volume, the value is the quantity in quote currency (If in BTC_USDT, The unit is USDT) |
Get History K-Line (V3)
Get k-line data within a specified time range of a specified trading pair.
Note that the interface is not real-time data, if you need real-time data, please use websocket to subscribe KLine channel
Request URL
GET https://api-cloud.bitmart.com/spot/quotation/v3/klines
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/quotation/v3/klines?symbol=BMX_ETH&step=15&before=1525760116&after=1525769116&limit=100
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Trading pair (e.g. BMX_USDT ) |
before | Long | No | Query timestamp (unit: second), query the data before this time |
after | Long | No | Query timestamp (unit: second), query the data after this time |
step | Int | No | k-line step, value [1, 3, 5, 15, 30, 45, 60, 120, 180, 240, 1440, 10080, 43200] unit: minute, default 1 |
limit | Int | No | Return number, the maximum value is 200, default is 100 |
Response Data
Response
{
"code":1000,
"trace":"886fb6ae-456b-4654-b4e0-1231",
"message": "success",
"data":[
[
"1689736680", // t
"3.721", // o
"3.743", // h
"3.677", // l
"3.708", // c
"22698348.04828491", // v
"12698348.04828491" // qv
],
[
"1689736620",
"3.731",
"3.799",
"3.494",
"3.72",
"67632347.24399722",
"37632347.24399722"
]
]
}
Field | Type | Description |
---|---|---|
t | String | Create timestamp (in seconds), It can be used as the unique identification of K line |
o | String | Open price |
h | String | Highest price |
l | String | Lowest price |
c | String | Close price |
v | String | Trading volume, with a unit of currency (If in BTC_USDT, The unit is BTC) |
qv | String | Trading volume, the value is the quantity in quote currency (If in BTC_USDT, The unit is USDT) |
Get Depth (V3)
Get full depth of trading pairs.
Note that the interface is not real-time data, if you need real-time data, please use websocket to subscribe Depth channel
Request URL
GET https://api-cloud.bitmart.com/spot/quotation/v3/books
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/quotation/v3/books?symbol=BTC_USDT&limit=1
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Trading pair (e.g. BMX_USDT ) |
limit | Int | No | Order book depth per side. Maximum 50, e.g. 50 bids + 50 asks. Default returns to 35 depth data, e.g. 35 bids + 35 asks. |
Response Data
Response
{
"code": 1000,
"trace":"886fb6ae-456b-4654-b4e0-1231",
"message": "success",
"data": {
"ts": "1691672864874",
"symbol": "BTC_USDT",
"asks": [
[
"31012.44", // price
"69994.75267" // amount
]
],
"bids": [
[
"30000.00", // price
"1.00000" // amount
]
]
}
}
Field | Type | Description |
---|---|---|
ts | String | Create time(Timestamp in milliseconds) |
symbol | String | Trading pair |
asks | List[] | Order book on sell side |
bids | List[] | Order book on buy side |
amount | String | Total number of current price depth |
price | String | The price at current depth |
Get Recent Trades (V3)
Get the latest trade records of the specified trading pair.
Note that the interface is not real-time data, if you need real-time data, please use websocket to subscribe Trade channel
Request URL
GET https://api-cloud.bitmart.com/spot/quotation/v3/trades
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/quotation/v3/trades?symbol=BMX_ETH&limit=10
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Trading pair (e.g. BMX_USDT ) |
limit | Int | No | Number of returned items, maximum is 50, default 50 |
Response Data
Response
{
"code": 1000,
"trace":"886fb6ae-456b-4654-b4e0-1231",
"message": "success",
"data": [
[
"BMX_ETH", // symbol
"1691743270994", // ts
"1.00000000", // price
"1.0", // size
"sell" // side
]
]
}
Field | Type | Description |
---|---|---|
symbol | String | Trading pair |
ts | String | Trade time (in milliseconds) |
price | String | Trade price |
size | String | Trade number |
side | String | Order Side - buy - sell |
Public Market Data (History Version)
Get Ticker of All Pairs (V2)
Applicable to query the latest ticker of all trading pairs, please note that the endpoint returns more data, please reduce the frequency of calls
Request URL
GET https://api-cloud.bitmart.com/spot/v2/ticker
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v2/ticker
None
Response Data
Response
{
"message":"OK",
"code":1000,
"trace":"6e42c7c9-fdc5-461b-8fd1-b4e2e1b9ed57",
"data":{
"tickers":[
{
"symbol":"BTC_USDT",
"last_price":"1.00",
"quote_volume_24h":"201477650.88000",
"base_volume_24h":"25186.48000",
"high_24h":"8800.00",
"low_24h":"1.00",
"open_24h":"8800.00",
"close_24h":"1.00",
"best_ask":"0.00",
"best_ask_size":"0.00000",
"best_bid":"0.00",
"best_bid_size":"0.00000",
"fluctuation":"-0.9999",
"url":"https://www.bitmart.com/trade?symbol=BTC_USDT",
"timestamp":1665200293
}
]
}
}
Field | Type | Description |
---|---|---|
symbol | String | Trading pair |
last_price | String | Latest price |
base_volume_24h | String | 24-hour trade volume in base currency |
quote_volume_24h | String | 24-hour trade volume in quote currency |
high_24h | String | 24-hour highest price |
open_24h | String | 24-hour open price |
low_24h | String | 24-hour lowest price |
close_24h | String | 24-hour close price |
fluctuation | String | 24-hour price change |
best_ask | String | top ask price |
best_ask_size | String | Size of top ask order |
best_bid | String | top bid price |
best_bid_size | String | Size of top bid order |
url | String | Link to the trading page on BitMart |
timestamp | Long | Time of generation |
Get Ticker of a Trading Pair (V1)
Applicable for querying aggregated tickers of a particular trading pair
Request URL
GET https://api-cloud.bitmart.com/spot/v1/ticker_detail
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v1/ticker_detail?symbol=BTC_USDT
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Trading pair (e.g. BMX_USDT) |
Response Data
Response
{
"message":"OK",
"code":1000,
"trace":"7d3a7e589cad4d578e17a6bdea8e4d09.65.16687519530806699",
"data":{
"symbol":"BTC_USDT",
"last_price":"16795.11",
"quote_volume_24h":"71784875.05",
"base_volume_24h":"4306.22738",
"high_24h":"16995.94",
"low_24h":"16434.08",
"open_24h":"16583.37",
"close_24h":"16795.11",
"best_ask":"16792.26",
"best_ask_size":"0.02377",
"best_bid":"16792.23",
"best_bid_size":"0.00640",
"fluctuation":"+0.0128",
"timestamp":1668751802882,
"url":"https://www.bitmart.com/trade?symbol=BTC_USDT"
}
}
Field | Type | Description |
---|---|---|
symbol | String | Trading pair |
last_price | String | Latest price |
base_volume_24h | String | 24-hour trade volume in base currency |
quote_volume_24h | String | 24-hour trade volume in quote currency |
high_24h | String | 24-hour highest price |
open_24h | String | 24-hour open price |
low_24h | String | 24-hour lowest price |
close_24h | String | 24-hour close price |
fluctuation | String | 24-hour price change |
best_ask | String | top ask price |
best_ask_size | String | Size of top ask order |
best_bid | String | top bid price |
best_bid_size | String | Size of top bid order |
url | String | Link to the trading page on BitMart |
timestamp | Long | Time of generation |
Get K-Line Step (V1)
Get all k-line steps supported by the platform, expressed in minutes, minimum 1 minute.
Request URL
GET https://api-cloud.bitmart.com/spot/v1/steps
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v1/steps
None
Response Data
Response
{
"code": 1000,
"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
"message": "OK",
"data": {
"steps": [1, 3, 5, 15, 30, 45, 60, 120, 180, 240, 1440, 10080, 43200]
}
}
Field | Type | Description |
---|---|---|
steps | List | List of K-Line steps in minutes |
Get K-Line (V1)
Get k-line data within a specified time range of a specified trading pair
Request URL
GET https://api-cloud.bitmart.com/spot/v1/symbols/kline
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v1/symbols/kline?symbol=BMX_ETH&step=15&from=1525760116&to=1525769116
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Trading pair (e.g. BMX_USDT) |
from | Long | Yes | Start timestamp (in seconds, UTC+0 TimeZome) |
to | Long | Yes | End timestamp (in seconds, UTC+0 TimeZome) |
step | Long | No | k-line step Steps (in minutes, default 1 minute) |
Response Data
Response
{
"message":"OK",
"code":1000,
"trace":"ae7ede4c-04a3-4004-bd8b-022a12d17e45",
"data":{
"klines":[
{
"timestamp":1590969600,
"open":"1.2400000000",
"high":"1.2400000000",
"low":"1.2000000000",
"close":"1.2000000000",
"last_price":"1.2000000000",
"volume":"4.9000000000",
"quote_volume":"0.000000"
}
]
}
}
Field | Type | Description |
---|---|---|
kline | List | K-Line data |
Description of k-line details field:
Field | Type | Description |
---|---|---|
last_price | String | Current price |
timestamp | Long | Timestamp (in seconds, UTC+0 TimeZome) |
volume | String | Total volume |
quote_volume | String | Transaction amount |
high | String | Highest price |
low | String | Lowest price |
open | String | Open price |
close | String | Close price |
Get Depth (V1)
Get full depth of trading pairs.
Request URL
GET https://api-cloud.bitmart.com/spot/v1/symbols/book
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v1/symbols/book?symbol=BMX_ETH&precision=6
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Trading pair (e.g. BMX_USDT) |
precision | String | No | Price precision, the range is defined in trading pair details |
size | Int | No | Number of results per request. The value can be transmitted [1-50], there are altogether [2-100] buying and selling depths |
Instruction
precision is optional. If not passed, the default is to use
price_max_precision
returned by symbols details.If the size is left blank, default 50 of data will be returned. If size is larger than '50', error code will be returned.
Response Data
Response
{
"code": 1000,
"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
"message": "OK",
"data": {
"timestamp": 1527777538000,
"buys":[
{
"amount":"4800.00",
"total":"4800.00",
"price":"0.000767",
"count":"1"
},
{
"amount":"99996475.79",
"total":"100001275.79",
"price":"0.000201",
"count":"1"
},
...
],
"sells":[
{
"amount":"100.00",
"total":"100.00",
"price":"0.007000",
"count":"1"
},
{
"amount":"6997.00",
"total":"7097.00",
"price":"1.000000",
"count":"1"
},
...
]
}
}
Field | Type | Description |
---|---|---|
timestamp | Long | Unix timestamp in milliseconds for when the last updated time occurred |
buys | List | Bid order depth |
sells | List | Ask order depth |
Market depth details:
Field | Type | Description |
---|---|---|
amount | String | Total amount of current price depth |
total | String | Total accumulation above the current price depth (including current price) |
price | String | The price at current depth |
count | String | The number of orders at current depth |
Get Recent Trades (V1)
Get the latest trade records of the specified trading pair
Request URL
GET https://api-cloud.bitmart.com/spot/v1/symbols/trades
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v1/symbols/trades?symbol=BMX_ETH
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Trading pair (e.g. BMX_USDT) |
N | String | No | Number of returned items, the default maximum is 50 |
Response Data
Response
{
"code": 1000,
"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
"message": "OK",
"data": {
"trades": [
{
"amount":"0.05768509",
"order_time":1527057452000,
"price":"0.004811",
"count":"11.99",
"type":"buy"
}
]
}
}
Field | Type | Description |
---|---|---|
trades | List | List of trades |
Depth data details field description:
Field | Type | Description |
---|---|---|
amount | String | Total trade value |
order_time | Long | Trade time (in milliseconds) |
price | String | Trade price |
count | String | Trade amount |
type | String | Order Side - buy - sell |
Funding Account
Get Account Balance (KEYED)
Gets Account Balance
Request URL
GET https://api-cloud.bitmart.com/account/v1/wallet
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/account/v1/wallet?currency=USDT
Field | Type | Required? | Description |
---|---|---|---|
currency | String | No | currency |
Response Data
Response
{
"message":"OK",
"code":1000,
"trace":"ef834248-51d3-4223-9481-f862aa9dd39f",
"data":{
"wallet":[
{
"currency":"USDT",
"name":"Tether USD",
"available":"1000.00000000",
"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 Currencies
Gets the currency of the asset for withdrawal
Request URL
GET https://api-cloud.bitmart.com/account/v1/currencies
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/account/v1/currencies
None
Response Data
Response
{
"code": 1000,
"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
"message": "OK",
"data": {
"currencies": [
{
"currency": "USDT",
"name": "Tether USD",
"contract_address": null,
"network": "OMNI",
"withdraw_enabled": false,
"deposit_enabled": false,
"withdraw_minsize": null,
"withdraw_minfee": null
},
{
"currency": "USDT-TRC20",
"name": "USDT-TRC20",
"contract_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"network": "TRC20",
"withdraw_enabled": true,
"deposit_enabled": true,
"withdraw_minsize": "10",
"withdraw_minfee": "1"
},
{
"currency": "USDT-ERC20",
"name": "USDT-ERC20",
"contract_address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
"network": "ERC20",
"withdraw_enabled": true,
"deposit_enabled": true,
"withdraw_minsize": "26",
"withdraw_minfee": "13"
},
{
"currency": "USDT-BSC",
"name": "USDT-BSC",
"contract_address": "0x55d398326f99059fF775485246999027B3197955",
"network": "BEP20(BSC)",
"withdraw_enabled": true,
"deposit_enabled": true,
"withdraw_minsize": "2",
"withdraw_minfee": "1"
}
]
}
}
Field | Type | Description |
---|---|---|
currency | String | Token symbol, e.g., 'BTC' |
name | String | Token name, e.g., 'Bitcoin' |
contract_address | String | Contract address |
network | String | network, e.g., 'ERC20' |
withdraw_enabled | Boolean | Availability to withdraw - true =available- false =not available |
deposit_enabled | Boolean | Availability to deposit - true =available- false =not available |
withdraw_minsize | String | Minimum withdrawal amount |
withdraw_minfee | String | Minimum withdrawal fee |
Get Spot Wallet Balance (KEYED)
Get the user's wallet balance for all currencies
Request URL
GET https://api-cloud.bitmart.com/spot/v1/wallet
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/spot/v1/wallet
None
Response Data
Response
{
"code": 1000,
"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
"message": "OK",
"data": {
"wallet": [
{
"id": "BTC",
"available": "10.000000",
"name": "Bitcoin",
"frozen": "10.000000",
},
...
]
}
}
Field | Type | Description |
---|---|---|
id | String | Cryptocurrency abbreviation |
name | String | Full name |
available | String | Available balance |
frozen | String | Frozen balance |
Deposit Address (KEYED)
Gets Deposit Address
Request URL
GET https://api-cloud.bitmart.com/account/v1/deposit/address
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/account/v1/deposit/address?currency=USDT-TRC20
Field | Type | Required? | Description |
---|---|---|---|
currency | String | Yes | Token symbol, e.g., 'BTC' |
Instruction
Response Data
Response
{
"message":"OK",
"code":1000,
"trace":"0e6edd79-f77f-4251-abe5-83ba75d06c1a",
"data":{
"currency":"USDT-TRC20",
"chain":"USDT-TRC20",
"address":"TGR3ghy2b5VLbyAYrmiE15jasR6aPHTvC5",
"address_memo":""
}
}
Field | Type | Description |
---|---|---|
currency | String | Token symbol, e.g., 'BTC' |
chain | String | Token chain |
address | String | Deposit address |
address_memo | String | Tag (tag/payment_id/memo); If some currencies need to withdraw currency, it will return data. If not, it will return empty string |
Forgot to write Memo/Wrote a wrong Memo?
Withdraw Quota (KEYED)
Query withdraw quota for currencies
Request URL
GET https://api-cloud.bitmart.com/account/v1/withdraw/charge
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/account/v1/withdraw/charge?currency=BTC
Field | Type | Required? | Description |
---|---|---|---|
currency | String | Yes | Token symbol, e.g., 'BTC' |
Response Data
Response
{
"message":"OK",
"code":1000,
"trace":"62a80bde-0cb4-4bf1-b8e5-5ad2c71463e7",
"data":{
"today_available_withdraw_BTC":"100.0000",
"min_withdraw":"0.00000000",
"withdraw_precision":8,
"withdraw_fee":"0.00000000"
}
}
Field | Type | Description |
---|---|---|
today_available_withdraw_BTC | String | Amount available for withdrawal today, unit: BTC |
min_withdraw | String | Minimum withdrawable amount |
withdraw_precision | Int | Withdrawal precision |
withdraw_fee | String | Withdrawal fee |
Withdraw (SIGNED)
Creates a withdraw request from spot account to an external address
Request URL
POST https://api-cloud.bitmart.com/account/v1/withdraw/apply
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-TRC20",
"amount": "100.000",
"destination": "To Digital Address",
"address": "0x1EE6FA5A3803608fc22a1f3F76********",
"address_memo": ""
}'
https://api-cloud.bitmart.com/account/v1/withdraw/apply
Field | Type | Required? | Description |
---|---|---|---|
currency | String | Yes | Token symbol, e.g., 'BTC' |
amount | String | Yes | The amount of currency to withdraw |
destination | String | Yes | Remark |
To Digital Address =Withdraw to the digital currency address |
|||
address | String | Yes | Withdraw address (only the address added on the official website is supported) |
address_memo | String | No | Address tag(tag Or payment_id Or memo) |
Response Data
Response
{
"code": 1000,
"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
"message": "OK",
"data": {
"withdraw_id": "121212"
}
}
Field | Type | Description |
---|---|---|
withdraw_id | String | Withdrawa ID |
Note
1. When withdraw_id is returned, it means that the withdrawal request has been sent successfully.
2. You can check the tx_id of this withdrawal by using the interface of Get A Deposit Or Withdraw Detail, and use it to query the withdrawal progress on the blockchain.
3. If you get an error message, message=Only withdrawals from added addresses are allowed
You need to add the address to the whitelist address according to the following 2 steps.
Step1. On the webpage, after logging in to the account, first enter the Withdraw Crypto
page
Step2. Go to Withdrawal Address Management
page and add
Get Deposit And Withdraw History (KEYED)
The original /account/v1/deposit-withdraw/history interface, the old interface is no longer supported, please switch to the new interface as soon as possible
Search for all existed withdraws and deposits and return their latest status.
Request URL
GET https://api-cloud.bitmart.com/account/v2/deposit-withdraw/history
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/account/v2/deposit-withdraw/history?N=100&operation_type=withdraw
Field | Type | Required? | Description |
---|---|---|---|
currency | String | No | Token symbol, e.g., 'BTC' |
operation_type | String | Yes | type - deposit =deposit- withdraw =withdraw |
N | Int | Yes | Recent N records (value range 1-100) |
Response Data
Response
{
"message":"OK",
"code":1000,
"trace":"142bf92a-fc50-4689-92b6-590886f90b97",
"data":{
"records":[
{
"withdraw_id":"1679952",
"deposit_id":"",
"operation_type":"withdraw",
"currency":"BMX",
"apply_time":1588867374000,
"arrival_amount":"59.000000000000",
"fee":"1.000000000000",
"status":0,
"address":"0xe57b69a8776b37860407965B73cdFFBDFe668Bb5",
"address_memo":"",
"tx_id":""
},
...
]
}
}
Field | Type | Description |
---|---|---|
withdraw_id | String | withdraw id |
deposit_id | String | deposit id |
operation_type | String | type - deposit =deposit- withdraw =withdraw |
currency | String | Token symbol, e.g., 'BTC' |
apply_time | Long | The request timestamp is accurate to milliseconds(UTC-0) |
arrival_amount | String | Actual amount received |
fee | String | fee |
status | Int | status - 0 =Create- 1 =Submitted, waiting for withdrawal- 2 =Processing- 3 =Done- 4 =Cancel- 5 =Fail |
address | String | Address |
address_memo | String | Address tag |
tx_id | String | Hash record |
Get A Deposit Or Withdraw Detail (KEYED)
Query a single charge record
Request URL
GET https://api-cloud.bitmart.com/account/v1/deposit-withdraw/detail
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/account/v1/deposit-withdraw/detail?id=1679952
Field | Type | Required? | Description |
---|---|---|---|
id | String | Yes | withdraw_id or deposit_id |
Response Data
Response
{
"message":"OK",
"code":1000,
"trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
"data":{
"record":{
"withdraw_id":"1679952",
"deposit_id":"",
"operation_type":"withdraw",
"currency":"BMX",
"apply_time":1588867374000,
"arrival_amount":"59.000000000000",
"fee":"1.000000000000",
"status":0,
"address":"0xe57b69a8776b37860407965B73cdFFBDFe668Bb5",
"address_memo":"",
"tx_id":""
}
}
}
Field | Type | Description |
---|---|---|
withdraw_id | String | withdraw id |
deposit_id | String | deposit id |
operation_type | String | type - deposit =deposit - withdraw =withdraw |
currency | String | Token symbol, e.g., 'BTC' |
apply_time | Long | The request timestamp is accurate to milliseconds(UTC-0) |
arrival_amount | String | Actual amount received |
fee | String | fee |
status | Int | status - 0 =Create- 1 =Submitted, waiting for withdrawal- 2 =Processing- 3 =Done- 4 =Cancel- 5 =Fail |
address | String | address |
address_memo | String | address tag |
tx_id | String | Hash record |
Get Margin Account Details(Isolated) (KEYED)
Applicable for isolated margin account inquiries
Request URL
GET https://api-cloud.bitmart.com/spot/v1/margin/isolated/account
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/spot/v1/margin/isolated/account?symbol=BTC_USDT
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | No | Trading pair (e.g. BMX_USDT), no symbol is passed, and all isolated margin assets are returned |
Response Data
Response
{
"message":"OK",
"code":1000,
"trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
"data":{
"symbols":[
{
"symbol": "BTC_USDT",
"risk_rate": "18.77",
"risk_level": "1",
"buy_enabled": true,
"sell_enabled": true,
"liquidate_price": "-0.09408905",
"liquidate_rate": "1.1",
"base": {
"currency": "BTC",
"borrow_enabled": false,
"borrowed": "2.00000000",
"borrow_unpaid": "0.84478234",
"interest_unpaid": "0.01385763",
"available": "112.89603334",
"frozen": "0.00000000",
"net_asset": "110.89603334",
"net_assetBTC": "0.00000000",
"total_asset": "112.89603334"
},
"quote": {
"currency": "USDT",
"borrow_enabled": true,
"borrowed": "0.00000000",
"borrow_unpaid": "0.84478234",
"interest_unpaid": "0.01385763",
"available": "10.00000000",
"frozen": "0.00000000",
"net_asset": "10.00000000",
"net_assetBTC": "0.00000000",
"total_asset": "10.00000000"
}
},
...
]
}
}
Field | Type | Description |
---|---|---|
symbol | String | Trading pair |
risk_rate | String | Current risk rate |
risk_level | String | Risk level |
buy_enabled | Boolean | Whether open to buy |
sell_enabled | Boolean | Whether open to sell |
liquidate_price | String | Liquidation price (precision: 8 decimal places) |
liquidate_rate | String | Liquidation rate |
currency | String | Currency |
borrow_enabled | Boolean | Whether open to borrow |
borrowed | String | Borrowed assets (precision: 8 decimal places) |
borrow_unpaid | String | Outstanding principal amount (precision: 8 decimal places) |
interest_unpaid | String | Interest outstanding (precision: 8 decimal places) |
available | String | Available assets (precision: 8 decimal places) |
frozen | String | Trading frozen assets (precision: 8 decimal places) |
net_asset | String | Net assets (precision: 8 decimal places) |
net_assetBTC | String | Converted BTC net assets (precision: 8 decimal places) |
total_asset | String | Total assets (precision: 8 decimal places) |
Margin Asset Transfer (SIGNED)
For fund transfers between a margin account and spot account
Request URL
POST https://api-cloud.bitmart.com/spot/v1/margin/isolated/transfer
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":"BTC_USDT",
"currency":"BTC",
"amount":"1",
"side":"in"
}'
https://api-cloud.bitmart.com/spot/v1/margin/isolated/transfer
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Trading pair (e.g. BMX_USDT) |
currency | String | Yes | Currency |
amount | String | Yes | Amount of transfers (precision: 8 decimal places) |
side | String | Yes | Transfer direction - in =Transfer in- out =Transfer out |
Response Data
Response
{
"message":"OK",
"code":1000,
"trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
"data":{
"transfer_id":"124532"
}
}
Field | Type | Description |
---|---|---|
transfer_id | String | Transfer order id, only successful transfers will be returned |
Get Basic Fee Rate (KEYED)
For querying the base rate of the current user
Request URL
GET https://api-cloud.bitmart.com/spot/v1/user_fee
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/spot/v1/user_fee
Response Data
Response
{
"message":"OK",
"code":1000,
"trace":"0187ba0c876e4236ac191d9848a0f719.94.16778301620100121",
"data":{
"user_rate_type":0,
"level":"LV1",
"taker_fee_rate_A":"0.001",
"maker_fee_rate_A":"0.001",
"taker_fee_rate_B":"0.0025",
"maker_fee_rate_B":"0.0025",
"taker_fee_rate_C":"0.004",
"maker_fee_rate_C":"0.004"
}
}
Field | Type | Description |
---|---|---|
user_rate_type | Long | Rate type: - 0 =Normal Users- 1 =VIP Users - 2 =Special VIP Users |
level | String | User Level |
taker_fee_rate_A | String | Taker fee rate for Class-A pairs |
maker_fee_rate_A | String | Maker fee rate for Class-A pairs |
taker_fee_rate_B | String | Taker fee rate for Class-B pairs |
maker_fee_rate_B | String | Maker fee rate for Class-B pairs |
taker_fee_rate_C | String | Taker fee rate for Class-C pairs |
maker_fee_rate_C | String | Maker fee rate for Class-C pairs |
Get Actual Trade Fee Rate (KEYED)
For the actual fee rate of the trading pairs
Request URL
GET https://api-cloud.bitmart.com/spot/v1/trade_fee
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/spot/v1/trade_fee?symbol=BTC_USDT
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Trading pair (e.g. BMX_USDT) |
Response Data
Response
{
"message": "OK",
"code": 1000,
"trace": "87614aa8-5327-4fe2-aafc-02e2ddca7210",
"data": {
"symbol": "BTC_USDT",
"buy_taker_fee_rate": "0.0008",
"sell_taker_fee_rate": "0.0008",
"buy_maker_fee_rate": "0.0006",
"sell_maker_fee_rate": "0.0006"
}
}
Field | Type | Description |
---|---|---|
symbol | String | Trading pair |
buy_taker_fee_rate | String | Taker fee rate (Buy) |
sell_taker_fee_rate | String | Taker fee rate (Sell) |
buy_maker_fee_rate | String | Maker fee rate (Buy) |
sell_maker_fee_rate | String | Maker fee rate (Sell) |
Spot / Margin Trading
New Order(v2) (SIGNED)
Send in a new order.
Request URL
POST https://api-cloud.bitmart.com/spot/v2/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":"BTC_USDT",
"side":"buy",
"type":"limit",
"size":"10",
"price":"7000"
}'
https://api-cloud.bitmart.com/spot/v2/submit_order
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Trading pair (e.g. BTC_USDT) |
side | String | Yes | Side - buy =Buy order- sell =Sell order |
type | String | Yes | Order type - limit =Limit order- market =Market order- limit_maker =PostOnly order- ioc =IOC order |
client_order_id | String | No | Client-defined OrderId(A combination of numbers and letters, less than 32 bits) |
Special Parameters for Limit Orders/PostOnly Orders/IOC Orders (type
=limit/limit_maker/ioc)
Field | Type | Required? | Description |
---|---|---|---|
size | String | Yes | Order size |
price | String | Yes | Price |
Special Parameters for Market Orders (type
=market)
Field | Type | Required? | Description |
---|---|---|---|
size | String | Yes | Quantity sold, required when selling at market price size |
notional | String | Yes | Quantity bought, required when buying at market price notional |
Instruction
Buy-limit-maker
When "order price">="market lowest selling price", the system will refuse to accept the order after the order is submitted
When the "order price" <"the lowest selling price in the market", the order will be accepted by the system after the submission is successful
When "order price"*"order size"<minimum deal amount in the market, the system will refuse to accept the order after the order is submitted.
Sell-limit-maker
When "order price" <= "market highest bid price", after the order is submitted, the system will refuse to accept the order
When "order price"> "market highest bid price", the order will be accepted by the system after the submission is successful
When "order price"*"order size"<minimum deal amount in the market, the system will refuse to accept the order after the order is submitted.
Buy-ioc,Sell-ioc
- After the order is placed, all orders that cannot be filled immediately are cancelled immediately
Response Data
Response
{
"code": 1000,
"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
"message": "OK",
"data": {
"order_id":"1223181"
}
}
Field | Type | Description |
---|---|---|
order_id | String | Order ID |
New Margin Order(v1) (SIGNED)
Applicable for margin order placement
Request URL
POST https://api-cloud.bitmart.com/spot/v1/margin/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":"BTC_USDT",
"side":"buy",
"type":"limit",
"size":"10",
"price":"7000"
}'
https://api-cloud.bitmart.com/spot/v1/margin/submit_order
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Trading pair (e.g. BTC_USDT) |
side | String | Yes | Side - buy =Buy order- sell =Sell order |
type | String | Yes | Order type - limit =Limit order- market =Market order- limit_maker =PostOnly order- ioc =IOC order |
clientOrderId | String | No | Client-defined OrderId(A combination of numbers and letters, less than 32 bits) |
Special Parameters for Limit Orders/PostOnly Orders/IOC Orders (type
=limit/limit_maker/ioc)
Field | Type | Required? | Description |
---|---|---|---|
size | String | Yes | Order size |
price | String | Yes | Price |
Special Parameters for Market Orders (type
=market)
Field | Type | Required? | Description |
---|---|---|---|
size | String | Yes | Quantity sold, required when selling at market price size |
notional | String | Yes | Quantity bought, required when buying at market price notional |
Instruction
Buy-limit-maker
When "order price">="market lowest selling price", the system will refuse to accept the order after the order is submitted
When the "order price" <"the lowest selling price in the market", the order will be accepted by the system after the submission is successful
Sell-limit-maker
When "order price" <= "market highest bid price", after the order is submitted, the system will refuse to accept the order
When "order price"> "market highest bid price", the order will be accepted by the system after the submission is successful
Buy-ioc,Sell-ioc
- After the order is placed, all orders that cannot be filled immediately are cancelled immediately
Response Data
Response
{
"message":"OK",
"code":1000,
"trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
"data":{
"order_id":1223181
}
}
Field | Type | Description |
---|---|---|
order_id | Long | Order ID |
New Batch Order(v2) (SIGNED)
Batch order
Request URL
POST https://api-cloud.bitmart.com/spot/v2/batch_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 '{
"order_params":[
{
"symbol":"BTC_USDT",
"size":"0.1",
"price":"8800",
"side":"buy",
"type":"limit"
},
{
"symbol":"BTC_USDT",
"size":"0.1",
"price":"8800",
"side":"sell",
"type":"limit"
}
]
}'
https://api-cloud.bitmart.com/spot/v2/batch_orders
Field | Type | Required? | Description |
---|---|---|---|
order_params | List | Yes | Order parameters, the number of transactions cannot exceed 10 |
orderParam
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Trading pair (e.g. BTC_USDT) |
side | String | Yes | Side - buy =Buy order- sell =Sell order |
type | String | Yes | Order type - limit =Limit order- market =Market order- limit_maker =PostOnly order- ioc =IOC order |
client_order_id | String | No | Client-defined OrderId(A combination of numbers and letters, less than 32 bits) |
Special Parameters for Limit Orders/PostOnly Orders/IOC Orders (type
=limit/limit_maker/ioc)
Field | Type | Required? | Description |
---|---|---|---|
size | String | Yes | Order size |
price | String | Yes | Price |
Special Parameters for Market Orders (type
=market)
Field | Type | Required? | Description |
---|---|---|---|
size | String | Yes | Quantity sold, required when selling at market price size |
notional | String | Yes | Quantity bought, required when buying at market price notional |
Instruction
Buy-limit-maker
When "order price">="market lowest selling price", the system will refuse to accept the order after the order is submitted
When the "order price" <"the lowest selling price in the market", the order will be accepted by the system after the submission is successful
When "order price"*"order size"<minimum deal amount in the market, the system will refuse to accept the order after the order is submitted.
Sell-limit-maker
When "order price" <= "market highest bid price", after the order is submitted, the system will refuse to accept the order
When "order price"> "market highest bid price", the order will be accepted by the system after the submission is successful
When "order price"*"order size"<minimum deal amount in the market, the system will refuse to accept the order after the order is submitted.
Buy-ioc,Sell-ioc
- After the order is placed, all orders that cannot be filled immediately are cancelled immediately
Response Data
Response
{
"code": 1000,
"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
"message": "OK",
"data": {
"responses": [
{
"code": 11402,
"msg": "Balance not enough"
},
{
"code": 0,
"msg": "SUCCESS",
"data": {
"order_id": "145771"
}
}
]
}
}
Field | Type | Description |
---|---|---|
order_id | String | Order ID |
Cancel Order(v3) (SIGNED)
Applicable to the cancellation of a specified unfinished order
Request URL
POST https://api-cloud.bitmart.com/spot/v3/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": "BTC_USDT",
"order_id": "112121212"
}'
https://api-cloud.bitmart.com/spot/v3/cancel_order
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Trading pair (e.g. BMX_USDT) |
order_id | String | No | Order ID |
client_order_id | String | No | Client-defined Order ID |
Response Data
Response
{
"code": 1000,
"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
"message": "OK",
"data": {
"result": true
}
}
Field | Type | Description |
---|---|---|
result | Boolean | Cancel result - true =Cancel successfully- false =Cancel failed |
Cancel Batch Order(v1) (SIGNED)
Cancel all outstanding orders in the specified side for a trading pair
Request URL
POST https://api-cloud.bitmart.com/spot/v1/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":"BTC_USDT",
"side":"buy"
}'
https://api-cloud.bitmart.com/spot/v1/cancel_orders
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | No | Trading pair (e.g. BTC_USDT) |
side | String | No | Order side - buy - sell |
Response Data
Response
{
"code": 1000,
"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
"message": "OK",
"data": {
}
}
If code value is 1000, it means the order is successfully canceled.
Query Order By Id (v4) (SIGNED)
Query a single order by orderId
Request URL
POST https://api-cloud.bitmart.com/spot/v4/query/order
Request Limit
Refer to Rate Limitation Details
Request Parameter
Request
curl
-H 'X-BM-KEY:{{AccessKey}}'
-H 'X-BM-TIMESTAMP:{{currentTime}}'
-H 'X-BM-SIGN:{{SIGN}}'
-X POST -d '{
"orderId":"118100034543076010",
"queryState":"open",
"recvWindow":5000
}'
https://api-cloud.bitmart.com/spot/v4/query/order
Field | Type | Required? | Description |
---|---|---|---|
orderId | String | Yes | Order id |
queryState | String | No | Query Type - open =Query order state [new, partially_filled] - history =QUery order state [filled, canceled, partially_canceled]) |
recvWindow | Long | No | Trade time limit, allowed range (0,60000], default: 5000 milliseconds |
Note
Response Details
Response
{
"code" : 1000,
"message" : "success",
"data" : {
"orderId" : "118100034543076010",
"clientOrderId" : "118100034543076010",
"symbol" : "BTC_USDT",
"side" : "buy",
"orderMode" : "spot",
"type" : "limit",
"state" : "filled",
"price" : "48800.00",
"priceAvg" : "39999.00",
"size" : "0.10000",
"filledSize" : "0.10000",
"notional" : "4880.00000",
"filledNotional" : "3999.90000",
"createTime" : 1681701557927,
"updateTime" : 1681701559408
},
"trace" : "8aab576e50024648ae45e3cfaf90f9cf.60.16817015721880197"
}
Field | Type | Description |
---|---|---|
orderId | String | Order ID |
clientOrderId | String | User-defined ID |
symbol | String | Trading pair (e.g. BTC_USDT) |
side | String | Order side - buy =buy- sell =sell |
orderMode | String | Order mode - spot =spot- iso_margin =isolated margin |
type | String | Order type - limit =limit order- market =market order- limit_maker =PostOnly order- ioc =IOC order |
state | String | Order status - new =The order has been accepted by the engine.- partially_filled =a part of the order has been filled.- filled =the order has been completed.- canceled =the order has been canceled by the user.- partially_canceled =partially filled canceled |
price | String | Order price |
priceAvg | String | Average execution price of the order |
size | String | Order quantity |
filledSize | String | Actual execution quantity |
notional | String | Order amount |
filledNotional | String | Actual execution amount |
createTime | Long | Order creation time in milliseconds, e.g. 1681701557927 |
updateTime | Long | Last update time in milliseconds, e.g. 1681701557927 |
Query Order By clientOrderId(v4) (SIGNED)
Query a single order by clientOrderId.
Request URL
POST https://api-cloud.bitmart.com/spot/v4/query/client-order
Request Limit
Refer to Rate Limitation Details
Request Parameter
Request
curl
-H 'X-BM-KEY:{{AccessKey}}'
-H 'X-BM-TIMESTAMP:{{currentTime}}'
-H 'X-BM-SIGN:{{SIGN}}'
-X POST -d '{
"clientOrderId":"118100034543076010",
"queryState":"open",
"recvWindow":5000
}'
https://api-cloud.bitmart.com/spot/v4/query/client-order
Field | Type | Required? | Description |
---|---|---|---|
clientOrderId | String | Yes | User-defined order id |
queryState | String | No | Query Type - open =Query order state [new, partially_filled] - history =Query order state [filled, canceled, partially_canceled]) |
recvWindow | Long | No | Trade time limit, allowed range (0,60000], default: 5000 milliseconds |
Note
Response Details
Response
{
"code" : 1000,
"message" : "success",
"data" : {
"orderId" : "118100034543076010",
"clientOrderId" : "118100034543076010",
"symbol" : "BTC_USDT",
"side" : "buy",
"orderMode" : "spot",
"type" : "limit",
"state" : "filled",
"price" : "48800.00",
"priceAvg" : "39999.00",
"size" : "0.10000",
"filledSize" : "0.10000",
"notional" : "4880.00000",
"filledNotional" : "3999.90000",
"createTime" : 1681701557927,
"updateTime" : 1681701559408
},
"trace" : "8aab576e50024648ae45e3cfaf90f9cf.60.16817015721880197"
}
Field | Type | Description |
---|---|---|
orderId | String | Order ID |
clientOrderId | String | User-defined ID |
symbol | String | Trading pair (e.g. BTC_USDT) |
side | String | Order side - buy =buy- sell =sell |
orderMode | String | Order mode - spot =spot- iso_margin =isolated margin |
type | String | Order type - limit =limit order- market =market order- limit_maker =PostOnly order- ioc =IOC order |
state | String | Order status - new =The order has been accepted by the engine.- partially_filled =a part of the order has been filled.- filled =the order has been completed.- canceled =the order has been canceled by the user.- partially_canceled =partially filled canceled |
price | String | Order price |
priceAvg | String | Average execution price of the order |
size | String | Order quantity |
filledSize | String | Actual execution quantity |
notional | String | Order amount |
filledNotional | String | Actual execution amount |
createTime | Long | Order creation time in milliseconds, e.g. 1681701557927 |
updateTime | Long | Last update time in milliseconds, e.g. 1681701557927 |
Current Open Orders(v4) (SIGNED)
Query the current opening order list of the account, only including state=[new, partially_filled] orders
Request URL
POST https://api-cloud.bitmart.com/spot/v4/query/open-orders
Request Limit
Refer to Rate Limitation Details
Request Parameter
Request
curl
-H 'X-BM-KEY:{{AccessKey}}'
-H 'X-BM-TIMESTAMP:{{currentTime}}'
-H 'X-BM-SIGN:{{SIGN}}'
-X POST -d '{
"symbol":"BTC_USDT",
"orderMode":"spot",
"startTime":1682239652931,
"endTime":1682239657931,
"limit":10,
"recvWindow":5000
}'
https://api-cloud.bitmart.com/spot/v4/query/open-orders
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | No | Trading pair (e.g. BTC_USDT) |
orderMode | String | No | Order mode - spot =spot trade - iso_margin =isolated margin trade |
startTime | Long | No | Start time in milliseconds, (e.g. 1681701557927) |
endTime | Long | No | End time in milliseconds, (e.g. 1681701557927) |
limit | Int | No | Number of queries, allowed range [1,200], default 200 |
recvWindow | Long | No | Trade time limit, allowed range (0,60000], default: 5000 milliseconds |
Note
- For high-volume trades, it is strongly recommended that users maintain their own current order list and use websocket to update the order status. You should pull the current order list once before each transaction.
symbol
is not filled in, all trading pairs will be searched by defaultorderMode
is not filled in, and all order modes are searched by defaultlimit
is not filled, the default is 200, if it is filled, it cannot exceed 200- If the time range
startTime
andendTime
are not filled in, the data of the last 7 days will be displayed by default. - When filling in the time range,
endTime
must be greater than the value ofstartTime
. - If only
startTime
is filled in, query the historical records starting from this timestamp. - If only
endTime
is filled in, query the historical records starting from this timestamp.
Response Details
Response
{
"code" : 1000,
"message" : "success",
"data" : [ {
"orderId" : "125213058731346056",
"clientOrderId" : "125213058731346056",
"symbol" : "BTC_USDT",
"side" : "buy",
"orderMode" : "spot",
"type" : "limit",
"state" : "new",
"price" : "800.00",
"priceAvg" : "0.00",
"size" : "0.10000",
"filledSize" : "0.00000",
"notional" : "80.00000000",
"filledNotional" : "0.00000000",
"createTime" : 1681892198608,
"updateTime" : 1681892198946
} ],
"trace" : "5e1c9f98d761443ea559c7af71ca57fa.60.16818922069220005"
}
Field | Type | Description |
---|---|---|
orderId | String | Order ID |
clientOrderId | String | User-defined ID |
symbol | String | Trading pair (e.g. BTC_USDT) |
side | String | Order side - buy =buy- sell =sell |
orderMode | String | Order mode - spot =spot- iso_margin =isolated margin |
type | String | Order type - limit =limit order- market =market order- limit_maker =PostOnly order- ioc =IOC order |
state | String | Order status - new =The order has been accepted by the engine.- partially_filled =a part of the order has been filled. |
price | String | Order price |
priceAvg | String | Average execution price of the order |
size | String | Order quantity |
filledSize | String | Actual execution quantity |
notional | String | Order amount |
filledNotional | String | Actual execution amount |
createTime | Long | Order creation time in milliseconds, e.g. 1681701557927 |
updateTime | Long | Last update time in milliseconds, e.g. 1681701557927 |
Account Orders(v4) (SIGNED)
Query the account history order list, only including state=[filled, canceled, partially_canceled] orders
Request URL
POST https://api-cloud.bitmart.com/spot/v4/query/history-orders
Request Limit
Refer to Rate Limitation Details
Request Parameter
Request
curl
-H 'X-BM-KEY:{{AccessKey}}'
-H 'X-BM-TIMESTAMP:{{currentTime}}'
-H 'X-BM-SIGN:{{SIGN}}'
-X POST -d '{
"symbol":"BTC_USDT",
"orderMode":"spot",
"startTime":1682239502394,
"endTime":1682239507394,
"limit":10,
"recvWindow":5000
}'
https://api-cloud.bitmart.com/spot/v4/query/history-orders
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | No | Trading pair (e.g. BTC_USDT) |
orderMode | String | No | Order mode - spot =spot trade - iso_margin =isolated margin trade |
startTime | Long | No | Start time in milliseconds, (e.g. 1681701557927) |
endTime | Long | No | End time in milliseconds, (e.g. 1681701557927) |
limit | Int | No | Number of queries, allowed range [1,200], default 200 |
recvWindow | Long | No | Trade time limit, allowed range (0,60000], default: 5000 milliseconds |
Note
symbol
is not filled in, all trading pairs will be searched by defaultorderMode
is not filled in, and all order modes are searched by defaultlimit
is not filled, the default is 200, if it is filled, it cannot exceed 200- If the time range
startTime
andendTime
are not filled in, the data of the last 7 days will be displayed by default. - When filling in the time range,
endTime
must be greater than the value ofstartTime
. - If only
startTime
is filled in, query the historical records starting from this timestamp. - If only
endTime
is filled in, query the historical records starting from this timestamp.
Response Details
Response
{
"code" : 1000,
"message" : "success",
"data" : [ {
"orderId" : "118100034543076010",
"clientOrderId" : "118100034543076010",
"symbol" : "BTC_USDT",
"side" : "buy",
"orderMode" : "spot",
"type" : "limit",
"state" : "filled",
"price" : "48800.00",
"priceAvg" : "39999.00",
"size" : "0.10000",
"filledSize" : "0.10000",
"notional" : "4880.00000000",
"filledNotional" : "3999.90000000",
"createTime" : 1681701557927,
"updateTime" : 1681701559408
} ],
"trace" : "acc282ba9e434cc1a90bf6326de9e119.64.16818913787390001"
}
Field | Type | Description |
---|---|---|
orderId | String | Order ID |
clientOrderId | String | User-defined ID |
symbol | String | Trading pair (e.g. BTC_USDT) |
side | String | Order side - buy =buy- sell =sell |
orderMode | String | Order mode - spot =spot- iso_margin =isolated margin |
type | String | Order type - limit =limit order- market =market order- limit_maker =PostOnly order- ioc =IOC order |
state | String | Order status - filled =the order has been completed.- canceled =the order has been canceled by the user.- partially_canceled =partially filled canceled |
price | String | Order price |
priceAvg | String | Average execution price of the order |
size | String | Order quantity |
filledSize | String | Actual execution quantity |
notional | String | Order amount |
filledNotional | String | Actual execution amount |
createTime | Long | Order creation time in milliseconds, e.g. 1681701557927 |
updateTime | Long | Last update time in milliseconds, e.g. 1681701557927 |
Account Trade List(v4) (SIGNED)
Query all transaction records of the account
Request URL
POST https://api-cloud.bitmart.com/spot/v4/query/trades
Request Limit
Refer to Rate Limitation Details
Request Parameter
Request
curl
-H 'X-BM-KEY:{{AccessKey}}'
-H 'X-BM-TIMESTAMP:{{currentTime}}'
-H 'X-BM-SIGN:{{SIGN}}'
-X POST -d '{
"symbol":"BTC_USDT",
"orderMode":"spot",
"startTime":1682239845952,
"endTime":1682239850952,
"limit":10,
"recvWindow":5000
}'
https://api-cloud.bitmart.com/spot/v4/query/trades
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | No | Trading pair (e.g. BTC_USDT) |
orderMode | String | No | Order mode - spot =spot trade - iso_margin =isolated margin trade |
startTime | Long | No | Start time in milliseconds, (e.g. 1681701557927) |
endTime | Long | No | End time in milliseconds, (e.g. 1681701557927) |
limit | Int | No | Number of queries, allowed range [1,200], default 200 |
recvWindow | Long | No | Trade time limit, allowed range (0,60000], default: 5000 milliseconds |
Note
symbol
is not filled in, all trading pairs will be searched by defaultorderMode
is not filled in, and all order modes are searched by defaultlimit
is not filled, the default is 200, if it is filled, it cannot exceed 200- If the time range
startTime
andendTime
are not filled in, the data of the last 7 days will be displayed by default. - When filling in the time range,
endTime
must be greater than the value ofstartTime
. - If only
startTime
is filled in, query the historical records starting from this timestamp. - If only
endTime
is filled in, query the historical records starting from this timestamp.
Response Details
Response
{
"code" : 1000,
"message" : "success",
"data" : [ {
"tradeId" : "125277182593091639",
"orderId" : "125213058731346053",
"clientOrderId" : "125213058731346053",
"symbol" : "BTC_USDT",
"side" : "buy",
"orderMode" : "spot",
"type" : "limit",
"price" : "39999.00",
"size" : "0.10000",
"notional" : "3999.90000000",
"fee" : "9.99975000",
"feeCoinName" : "USDT",
"tradeRole" : "taker",
"createTime" : 1681891896569,
"updateTime" : 1681891896569
} ],
"trace" : "5e1c9f98d761443ea559c7af71ca57fa.61.16819603026240455"
}
Field | Type | Description |
---|---|---|
tradeId | String | Trade id |
orderId | String | Order ID |
clientOrderId | String | User-defined ID |
symbol | String | Trading pair (e.g. BTC_USDT) |
side | String | Order side - buy =buy- sell =sell |
orderMode | String | Order mode - spot =spot- iso_margin =isolated margin |
type | String | Order type - limit =limit order- market =market order- limit_maker =PostOnly order- ioc =IOC order |
price | String | Transaction price |
size | String | Transaction quantity |
notional | String | Transaction amount |
fee | String | Fee amount |
feeCoinName | String | Fee coin name |
tradeRole | String | Trade role - taker =Take orders, take the initiative to deal- maker =Pending order, passive transaction |
createTime | Long | Order creation time in milliseconds, e.g. 1681701557927 |
updateTime | Long | Last update time in milliseconds, e.g. 1681701557927 |
Order Trade List(v4) (SIGNED)
Query all transaction records of a single order
Request URL
POST https://api-cloud.bitmart.com/spot/v4/query/order-trades
Request Limit
Refer to Rate Limitation Details
Request Parameter
Request
curl
-H 'X-BM-KEY:{{AccessKey}}'
-H 'X-BM-TIMESTAMP:{{currentTime}}'
-H 'X-BM-SIGN:{{SIGN}}'
-X POST -d '{
"orderId":"118100034543076010",
"recvWindow":5000
}'
https://api-cloud.bitmart.com/spot/v4/query/order-trades
Field | Type | Required? | Description |
---|---|---|---|
orderId | String | Yes | Order id |
recvWindow | Long | No | Trade time limit, allowed range (0,60000], default: 5000 milliseconds |
Note
orderId
Order number is required.
Response Details
Response
{
"code" : 1000,
"message" : "success",
"data" : [ {
"tradeId" : "122177405911172002",
"orderId" : "118100034543076010",
"clientOrderId" : "118100034543076010",
"symbol" : "BTC_USDT",
"side" : "buy",
"orderMode" : "spot",
"type" : "limit",
"price" : "39999.00",
"size" : "0.10000",
"notional" : "3999.90000000",
"fee" : "9.99975000",
"feeCoinName" : "USDT",
"tradeRole" : "taker",
"createTime" : 1681701559210,
"updateTime" : 1681701559210
} ],
"trace" : "5e1c9f98d761443ea559c7af71ca57fa.62.16818934219090007"
}
Field | Type | Description |
---|---|---|
tradeId | String | Trade id |
orderId | String | Order ID |
clientOrderId | String | User-defined ID |
symbol | String | Trading pair (e.g. BTC_USDT) |
side | String | Order side - buy =buy- sell =sell |
orderMode | String | Order mode - spot =spot- iso_margin =isolated margin |
type | String | Order type - limit =limit order- market =market order- limit_maker =PostOnly order- ioc =IOC order |
price | String | Transaction price |
size | String | Transaction quantity |
notional | String | Transaction amount |
fee | String | Fee amount |
feeCoinName | String | Fee coin name |
tradeRole | String | Trade role - taker =Take orders, take the initiative to deal- maker =Pending order, passive transaction |
createTime | Long | Order creation time in milliseconds, e.g. 1681701557927 |
updateTime | Long | Last update time in milliseconds, e.g. 1681701557927 |
Spot / Margin Trading (History Version)
New Order(v1) (SIGNED)
Send in a new order.
new endpoint /spot/v2/submit_order
Request Format
POST https://api-cloud.bitmart.com/spot/v1/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":"BTC_USDT",
"side":"buy",
"type":"limit",
"size":"10",
"price":"7000"
}'
https://api-cloud.bitmart.com/spot/v1/submit_order
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Trading pair (e.g. BTC_USDT) |
side | String | Yes | Side |
buy =Buy order |
|||
sell =Sell order |
|||
type | String | Yes | Order type |
Yes | limit =Limit order |
||
Yes | market =Market order |
||
Yes | limit_maker =PostOnly order |
||
Yes | ioc =IOC order |
||
clientOrderId | String | No | Client-defined OrderId(A combination of numbers and letters, less than 32 bits) |
Special Parameters for Limit Orders/PostOnly Orders/IOC Orders (type
=limit/limit_maker/ioc)
Field | Type | Required? | Description |
---|---|---|---|
size | String | Yes | Order size |
price | String | Yes | Price |
Special Parameters for Market Orders (type
=market)
Field | Type | Required? | Description |
---|---|---|---|
size | String | Yes | Quantity sold, required when selling at market price size |
notional | String | Yes | Quantity bought, required when buying at market price notional |
Instruction
Buy-limit-maker
When "order price">="market lowest selling price", the system will refuse to accept the order after the order is submitted
When the "order price" <"the lowest selling price in the market", the order will be accepted by the system after the submission is successful
Sell-limit-maker
When "order price" <= "market highest bid price", after the order is submitted, the system will refuse to accept the order
When "order price"> "market highest bid price", the order will be accepted by the system after the submission is successful
Buy-ioc,Sell-ioc
- After the order is placed, all orders that cannot be filled immediately are cancelled immediately
Response Data
Response
{
"code": 1000,
"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
"message": "OK",
"data": {
"order_id":1223181
}
}
Field | Type | Description |
---|---|---|
order_id | Long | Order ID |
New Batch Order(v1) (SIGNED)
Batch order
new endpoint /spot/v2/batch_orders
Request Format
POST https://api-cloud.bitmart.com/spot/v1/batch_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 '{
"orderParams":[
{
"symbol":"BTC_USDT",
"size":"0.1",
"price":"8800",
"side":"buy",
"type":"limit"
},
{
"symbol":"BTC_USDT",
"size":"0.1",
"price":"8800",
"side":"sell",
"type":"limit"
}
]
}'
https://api-cloud.bitmart.com/spot/v1/batch_orders
Field | Type | Required? | Description |
---|---|---|---|
orderParams | List |
Yes | Order parameters, the number of transactions cannot exceed 10 |
orderParam
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Trading pair (e.g. BTC_USDT) |
side | String | Yes | Side |
buy =Buy order |
|||
sell =Sell order |
|||
type | String | Yes | Order type |
Yes | limit =Limit order |
||
Yes | market =Market order |
||
Yes | limit_maker =PostOnly order |
||
Yes | ioc =IOC order |
||
clientOrderId | String | No | Client-defined OrderId(A combination of numbers and letters, less than 32 bits) |
Special Parameters for Limit Orders/PostOnly Orders/IOC Orders (type
=limit/limit_maker/ioc)
Field | Type | Required? | Description |
---|---|---|---|
size | String | Yes | Order size |
price | String | Yes | Price |
Special Parameters for Market Orders (type
=market)
Field | Type | Required? | Description |
---|---|---|---|
size | String | Yes | Quantity sold, required when selling at market price size |
notional | String | Yes | Quantity bought, required when buying at market price notional |
Instruction
Buy-limit-maker
When "order price">="market lowest selling price", the system will refuse to accept the order after the order is submitted
When the "order price" <"the lowest selling price in the market", the order will be accepted by the system after the submission is successful
Sell-limit-maker
When "order price" <= "market highest bid price", after the order is submitted, the system will refuse to accept the order
When "order price"> "market highest bid price", the order will be accepted by the system after the submission is successful
Buy-ioc,Sell-ioc
- After the order is placed, all orders that cannot be filled immediately are cancelled immediately
Response Data
Response
{
"code": 1000,
"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
"message": "OK",
"data": {
"orderResponses": [
{
"code": 11402,
"msg": "Balance not enough"
},
{
"code": 0,
"msg": "SUCCESS",
"data": {
"orderId": 145771
}
}
]
}
}
Field | Type | Description |
---|---|---|
order_id | Long | Order ID |
Cancel Order(v2) (SIGNED)
Cancel an outstanding order
new endpoint /spot/v3/cancel_order
Request Format
POST https://api-cloud.bitmart.com/spot/v2/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 '{
"order_id":112121212
}'
https://api-cloud.bitmart.com/spot/v2/cancel_order
Field | Type | Required? | Description |
---|---|---|---|
order_id | Long | No | Order id |
clientOrderId | String | No | Client-defined OrderId |
Response Data
Response
{
"code": 1000,
"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
"message": "OK",
"data": {
"result": true
}
}
Field | Type | Description |
---|---|---|
result | Boolean | Cancel successfully=true; Cancel failed=false |
Query Order(v2) (KEYED)
Applicable query a specified order detail
new endpoint /spot/v4/query/order
Request Format
GET https://api-cloud.bitmart.com/spot/v2/order_detail
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/spot/v2/order_detail?order_id=1736871726781
Field | Type | Required? | Description |
---|---|---|---|
order_id | String | Yes | Order ID |
Response Data
Response
{
"message":"OK",
"code":1000,
"trace":"a27c2cb5-ead4-471d-8455-1cfeda054ea6",
"data":{
"order_id":"1736871726781",
"client_order_id":"d9850c05-9091-4740-ae07-43e62153e9bd",
"symbol":"BTC_USDT",
"create_time":1591096004000,
"side":"sell",
"order_mode":"spot",
"type":"market",
"price":"0.00",
"price_avg":"0.00",
"size":"0.02000",
"notional":"0.00000000",
"filled_notional":"0.00000000",
"filled_size":"0.00000",
"unfilled_volume":"0.02000",
"status":"8"
}
}
Field | Type | Description |
---|---|---|
order_id | String | Order ID |
client_order_id | String | Client-defined OrderId (If the field is not defined, a random String is returned) |
symbol | String | Trading pair (e.g. BMX_USDT) |
create_time | Long | Timestamp, accurate to milliseconds |
side | String | Side |
buy =Buy order |
||
sell =Sell order |
||
order_mode | String | Order mode |
spot =spot trade |
||
iso_margin =isolated margin trade |
||
type | String | Order type |
limit =Limit order |
||
market =Market order |
||
limit_maker =PostOnly order |
||
ioc =IOC order |
||
price | String | Order price |
price_avg | String | Average filled price |
size | String | Order size (Base currency) |
notional | String | Trade amount, unit is quote currency (special case: base currency when selling market orders) |
filled_notional | String | Filled notional amount |
filled_size | String | Filled amount |
unfilled_volume | String | Unsettled quantity |
status | String | Status |
4 =Order success, Pending for fulfilment |
||
5 =Partially filled |
||
6 =Fully filled |
||
8 =Canceled |
||
11 =Partially filled and canceled |
Account Orders(v3) (KEYED)
Applicable to search for order history within a certain time frame, up to 200 records
(Authentication type:KEYED, See Interface Permission)
new endpoint /spot/v4/query/open-orders new endpoint /spot/v4/query/history-orders
Request Format
GET https://api-cloud.bitmart.com/spot/v3/orders
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/spot/v3/orders?symbol=BTC_USDT&status=4&N=100
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Trading pair (e.g. BTC_USDT) |
order_mode | String | No | Order mode, Default returns spot |
spot =spot trade |
|||
iso_margin =isolated margin trade |
|||
all =all modes |
|||
N | Int | No | Records amount (value range 1-200, default is 200) |
start_time | Long | No | Start time timestamp in millsecond, must be within the last three months |
end_time | Long | No | End time timestamp in millsecond, must be within the last three months |
status | String | Yes | Status |
4 =Order success, Pending for fulfilment |
|||
5 =Partially filled |
|||
6 =Fully filled |
|||
8 =Canceled |
|||
9 =Outstanding (4 and 5) |
|||
10 = 6 and 8 and 11 |
|||
11 =Partially filled and canceled |
Response Data
Response
{
"message":"OK",
"code":1000,
"trace":"70e7d427-7436-4fb8-8cdd-97e1f5eadbe9",
"data":{
"orders":[
{
"order_id":"2147601241",
"symbol":"BTC_USDT",
"create_time":1591099963000,
"side":"sell",
"order_mode":"spot",
"type":"limit",
"price":"9000.00",
"price_avg":"0.00",
"size":"1.00000",
"notional":"9000.00000000",
"filled_notional":"0.00000000",
"filled_size":"0.00000",
"status":"4",
"client_order_id":"bm4877624"
}
]
}
}
Field | Type | Description |
---|---|---|
orders | List | Order list |
order_id | String | Order id |
symbol | String | Trading pair (e.g. BTC_USDT) |
create_time | Long | Timestamp, accurate to milliseconds |
side | String | Side |
buy =Buy order |
||
sell =Sell order |
||
order_mode | String | Order mode |
spot =spot trade |
||
iso_margin =isolated margin trade |
||
type | String | Order type |
limit =Limit order |
||
market =Market order |
||
price | String | Order price |
price_avg | String | Average filled price |
size | String | Order size (Base currency) |
notional | String | Trade amount, unit is quote currency (special case: base currency when selling market orders) |
filled_notional | String | Filled notional amount |
filled_size | String | Filled amount |
status | String | Status |
4 =Order success, Pending for fulfilment |
||
5 =Partially filled |
||
6 =Fully filled |
||
8 =Canceled |
||
11 =Partially filled and canceled |
||
client_order_id | String | Client-defined OrderId (If the field is not defined, a random string is returned) |
Account Trade List(v2) (KEYED)
Applicable for searching the trade history within a certain time frame, up to 200 records
new endpoint /spot/v4/query/trades
Request Format
GET https://api-cloud.bitmart.com/spot/v2/trades
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/spot/v2/trades?symbol=BTC_USDT&N=10
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Trading pair (e.g. BTC_USDT) |
order_mode | String | No | Order mode, Default returns spot |
spot =spot trade |
|||
iso_margin =isolated margin trade |
|||
all =all modes |
Special Parameters for Querying Trade Record of a Single Order
Field | Type | Required? | Description |
---|---|---|---|
order_id | String | No | Order ID |
Special Parameters for Querying Trade Record of All Orders
Field | Type | Required? | Description |
---|---|---|---|
N | Int | No | Records amount (value range 1-200, default is 200) |
start_time | Long | No | Start time timestamp in millsecond, must be within the last three months |
end_time | Long | No | End time timestamp in millsecond, must be within the last three months |
Response Data
Response
{
"message":"OK",
"code":1000,
"trace":"a06a5c53-8e6f-42d6-8082-2ff4718d221c",
"data":{
"trades":[
{
"detail_id":"256348632",
"order_id":"2147484350",
"symbol":"BTC_USDT",
"create_time":1590462303000,
"side":"buy",
"order_mode":"spot",
"fees":"0.00001350",
"fee_coin_name":"BTC",
"notional":"88.00000000",
"price_avg":"8800.00",
"size":"0.01000",
"exec_type":"M",
"client_order_id":"bm476897"
},
...
]
}
}
Field | Type | Description |
---|---|---|
trades | List | Order list |
detail_id | String | Trade id |
order_id | String | Order id |
symbol | String | Trading pair symbol |
create_time | Long | Trade time (in milliseconds) |
side | String | Side |
buy =Buy order |
||
sell =Sell order |
||
order_mode | String | Order mode |
spot =spot trade |
||
iso_margin =isolated margin trade |
||
price_avg | String | Average filled price |
notional | String | Notional amount |
size | String | Order size |
fees | String | Fees |
fee_coin_name | String | Coin used for paying fees |
exec_type | String | Whether the trade was created by a maker or a taker. M means Maker, T means Taker |
client_order_id | String | Client-defined OrderId (If the field is not defined, a random string is returned) |
Margin Loan
Margin Borrow (Isolated) (SIGNED)
Applicable to isolated margin account borrowing operations
Request URL
POST https://api-cloud.bitmart.com/spot/v1/margin/isolated/borrow
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":"BTC_USDT",
"currency":"BTC",
"amount":"1"
}'
https://api-cloud.bitmart.com/spot/v1/margin/isolated/borrow
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Trading pair (e.g. BMX_USDT) |
currency | String | Yes | Borrowing currency, selected according to the borrowing trading pair(like BTC or USDT) |
amount | String | Yes | Amount of borrowing (precision: 8 decimal places) |
Response Data
Response
{
"message":"OK",
"code":1000,
"trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
"data":{
"borrow_id":"113896"
}
}
Field | Type | Description |
---|---|---|
borrow_id | String | Borrowing order ID, only successful borrowing will be returned |
Margin Repay (Isolated) (SIGNED)
Applicable to isolated margin account repayment operations
Request URL
POST https://api-cloud.bitmart.com/spot/v1/margin/isolated/repay
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":"BTC_USDT",
"currency":"BTC",
"amount":"1"
}'
https://api-cloud.bitmart.com/spot/v1/margin/isolated/repay
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Trading pair (e.g. BMX_USDT) |
currency | String | Yes | Repayment currency, selected according to the borrowing trading pair(like BTC or USDT) |
amount | String | Yes | Amount of repayments (precision: 8 decimal places) |
Response Data
Response
{
"message":"OK",
"code":1000,
"trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
"data":{
"repay_id":"123165"
}
}
Field | Type | Description |
---|---|---|
repay_id | String | Repayment order ID, only successful repayment will be returned |
Get Borrow Record(Isolated) (KEYED)
Applicable to the inquiry of borrowing records of an isolated margin account
Request URL
GET https://api-cloud.bitmart.com/spot/v1/margin/isolated/borrow_record
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/spot/v1/margin/isolated/borrow_record?symbol=BTC_USDT
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Trading pair (e.g. BMX_USDT) |
borrow_id | String | No | Borrow order id |
start_time | Long | No | Query start time: Timestamp |
end_time | Long | No | Query end time: Timestamp |
N | Int | No | Query record size, allowed range[1-100]. Default is 50 |
Response Data
Response
{
"message":"OK",
"code":1000,
"trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
"data":{
"records":[
{
"borrow_id": "133425",
"symbol": "BTC_USDT",
"currency": "BTC",
"borrow_amount": "1.23854339",
"daily_interest": "0.05",
"hourly_interest": "0.00208334",
"interest_amount": "0.02398474",
"create_time": 1655345808
},
...
]
}
}
Field | Type | Description |
---|---|---|
borrow_id | String | Borrow order id |
symbol | String | Trading pair |
currency | String | Currency |
borrow_amount | String | The total principal amount borrowed (precision: 8 decimal places) |
daily_interest | String | Daily interest |
hourly_interest | String | Hourly interest |
interest_amount | String | Total interest (precision: 8 decimal places) |
create_time | Long | Order creation time |
Get Repayment Record(Isolated) (KEYED)
Applicable to the inquiry of repayment records of isolated margin account
Request URL
GET https://api-cloud.bitmart.com/spot/v1/margin/isolated/repay_record
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/spot/v1/margin/isolated/repay_record?symbol=BTC_USDT
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | Yes | Trading pair (e.g. BMX_USDT) |
repay_id | String | No | Repayment ID |
currency | String | No | Currency |
start_time | Long | No | Query start time: Timestamp |
end_time | Long | No | Query end time: Timestamp |
N | Int | No | Query record size, allowed range[1-100]. Default is 50 |
Response Data
Response
{
"message":"OK",
"code":1000,
"trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
"data":{
"records":[
{
"repay_id":"118723",
"repay_time":1655345808,
"symbol":"BTC_USDT",
"currency":"BTC",
"repaid_amount":"1.1",
"repaid_principal":"1",
"repaid_interest":"0.1"
},
...
]
}
}
Field | Type | Description |
---|---|---|
repay_id | String | Repayment ID |
repay_time | Long | Repayment Timestamp |
symbol | String | Repayment trading pairs(like BTC_USDT) |
currency | String | Repayment currency |
repaid_amount | String | Repayment amount |
repaid_principal | String | The principal amount returned by this repayment |
repaid_interest | String | Interest returned by this repayment |
Get Trading Pair Borrowing Rate and Amount (KEYED)
Applicable for checking the borrowing rate and borrowing amount of trading pairs
Request URL
GET https://api-cloud.bitmart.com/spot/v1/margin/isolated/pairs
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/spot/v1/margin/isolated/pairs?symbol=BTC_USDT
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | No | It can be multiple-choice; if not filled in, then return all, like BTC_USDT, ETH_USDT |
Response Data
Response
{
"message":"OK",
"code":1000,
"trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
"data":{
"symbols":[
{
"symbol": "BTC_USDT",
"max_leverage": "10",
"symbol_enabled": true,
"base": {
"currency": "BTC",
"daily_interest": "0.05",
"hourly_interest": "0.00208334",
"max_borrow_amount": "1000.00000000",
"min_borrow_amount": "1.00000000",
"borrowable_amount": "955.90221219"
},
"quote": {
"currency": "USDT",
"daily_interest": "0.05",
"hourly_interest": "0.00208334",
"max_borrow_amount": "12000.00000000",
"min_borrow_amount": "0.01000000",
"borrowable_amount": "12000.00000000"
}
},
...
]
}
}
Field | Type | Description |
---|---|---|
symbol | String | Trading pair |
max_leverage | String | Leverage multiplier |
symbol_enabled | Boolean | Whether the trading pair is enabled |
currency | String | Currency |
daily_interest | String | Daily interest |
hourly_interest | String | Hourly interest |
max_borrow_amount | String | The maximum amount of borrowing (precision: 8 decimal places) |
min_borrow_amount | String | The minimum amount of borrowing (precision: 8 decimal places) |
borrowable_amount | String | The current available amount of borrowing (precision: 8 decimal places) |
Sub-Account
Sub-Account to Main-Account (For Main Account) (SIGNED)
Sub-account spot asset transfer to Main-account (For Main Account)
Request URL
POST https://api-cloud.bitmart.com/account/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":"BTC",
"subAccount":"[email protected]"
}'
https://api-cloud.bitmart.com/account/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 | Currency |
subAccount | String | Yes | Sub-Account username |
Response Data
Response
{
"code": 1000,
"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
"message": "OK",
"data": {
}
}
If code value is 1000,it means the transfer is successful.
Sub-Account to Main-Account (For Sub-Account) (SIGNED)
Sub-Account spot asset transfer to Main-Account spot asset (For Sub-Account)
Request URL
POST https://api-cloud.bitmart.com/account/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":"BTC"
}'
https://api-cloud.bitmart.com/account/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 | Currency |
Response Data
Response
{
"code": 1000,
"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
"message": "OK",
"data": {
}
}
If code value is 1000,it means the transfer is successful.
Main-Account to Sub-Account (For Main Account) (SIGNED)
Main-account spot asset transfer to Sub-account spot asset (For Main Account)
Request URL
POST https://api-cloud.bitmart.com/account/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.bitmart.com/account/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 | Currency |
subAccount | String | Yes | Sub-Account username |
Response Data
Response
{
"code": 1000,
"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
"message": "OK",
"data": {
}
}
If code value is 1000,it means the transfer is successful.
Sub-Account to Sub-Account (For Main Account) (SIGNED)
Sub-Account spot asset transfer to Sub-Account spot asset (For Main Account)
Request URL
POST https://api-cloud.bitmart.com/account/sub-account/main/v1/sub-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",
"fromAccount":"subAcc[email protected]",
"toAccount":"[email protected]"
}'
https://api-cloud.bitmart.com/account/sub-account/main/v1/sub-to-sub
Field | Type | Required? | Description |
---|---|---|---|
requestNo | String | Yes | UUID,unique identifier, max length 64 |
amount | String | Yes | Transfer amount |
currency | String | Yes | Currency |
fromAccount | String | Yes | Transfer out Sub-Account username |
toAccount | String | Yes | Transfer to Sub-Account username |
Response Data
Response
{
"code": 1000,
"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
"message": "OK",
"data": {
}
}
If code value is 1000,it means the transfer is successful.
Sub-Account to Sub-Account (For Sub-Account) (SIGNED)
Sub-Account spot asset transfer to Sub-Account spot asset (For Sub-Account)
Request URL
POST https://api-cloud.bitmart.com/account/sub-account/sub/v1/sub-to-sub
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/account/sub-account/sub/v1/sub-to-sub
-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.bitmart.com/account/sub-account/sub/v1/sub-to-sub
Field | Type | Required? | Description |
---|---|---|---|
requestNo | String | Yes | UUID,unique identifier, max length 64 |
amount | String | Yes | Transfer amount |
currency | String | Yes | Currency |
subAccount | String | Yes | Sub-Account username |
Response Data
Response
{
"code": 1000,
"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
"message": "OK",
"data": {
}
}
If code value is 1000,it means the transfer is successful.
Get Sub-Account Transfer History (For Main Account) (KEYED)
Query Sub-Account Spot Asset Transfer History (For Main Account)
Request URL
GET https://api-cloud.bitmart.com/account/sub-account/main/v1/transfer-list
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/account/sub-account/main/v1/transfer-list?moveType=spot to spot
Field | Type | Required? | Description |
---|---|---|---|
moveType | String | Yes | type - spot to spot =Spot wallet transfer to spot wallet |
accountName | String | No | Sub-Account username |
N | Int | Yes | Recent N records, allowed range[1,100] |
Response Data
Response
{
"message": "OK",
"code": 1000,
"trace": "282fd16e-73ee-464f-adb7-7241345929f6",
"data": {
"total": 2,
"historyList": [
{
"fromAccount": "[email protected]",
"fromWalletType": "spot",
"toAccount": "[email protected]",
"toWalletType": "spot",
"currency": "BTC",
"amount": "1",
"submissionTime": 1648471522
},
{
"fromAccount": "[email protected]",
"fromWalletType": "spot",
"toAccount": "[email protected]",
"toWalletType": "spot",
"currency": "BTC",
"amount": "30",
"submissionTime": 1648466178
}
]
}
}
Field | Type | Description |
---|---|---|
fromAccount | String | Transfer out Sub-Account username |
fromWalletType | String | Transfer out wallet type - spot =spot wallet |
toAccount | String | Transfer to Sub-Account username |
toWalletType | String | Transfer to wallet type - spot =spot wallet |
currency | String | currency |
amount | String | Transfer amount |
submissionTime | Long | The request timestamp is accurate to seconds(UTC-0) |
Get Account Spot Asset Transfer History (For Main/Sub Account) (KEYED)
Get account spot asset transfer history (For Main/Sub Account)
Request URL
GET https://api-cloud.bitmart.com/account/sub-account/v1/transfer-history
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/account/sub-account/v1/transfer-history?moveType=spot to spot
Field | Type | Required? | Description |
---|---|---|---|
moveType | String | Yes | type - spot to spot =Spot wallet transfer to spot wallet |
N | Int | Yes | Recent N records, allowed range[1,100] |
Response Data
Response
{
"message": "OK",
"code": 1000,
"trace": "282fd16e-73ee-464f-adb7-7241345929f6",
"data": {
"total": 2,
"historyList": [
{
"fromAccount": "[email protected]",
"fromWalletType": "spot",
"toAccount": "[email protected]",
"toWalletType": "spot",
"currency": "BTC",
"amount": "1",
"submissionTime": 1648471522
},
{
"fromAccount": "[email protected]",
"fromWalletType": "spot",
"toAccount": "[email protected]",
"toWalletType": "spot",
"currency": "BTC",
"amount": "30",
"submissionTime": 1648466178
}
]
}
}
Field | Type | Description |
---|---|---|
fromAccount | String | Transfer out Sub-Account username |
fromWalletType | String | Transfer out wallet type - spot =spot wallet |
toAccount | String | Transfer to Sub-Account username |
toWalletType | String | Transfer to wallet type - spot =spot wallet |
currency | String | currency |
amount | String | Transfer amount |
submissionTime | Long | The request timestamp is accurate to seconds(UTC-0) |
Get Sub-Account Spot Wallet Balance (For Main Account) (KEYED)
Get Sub-Account spot wallet balance (For Main Account)
Request URL
GET https://api-cloud.bitmart.com/account/sub-account/main/v1/wallet
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/account/sub-account/main/v1/wallet?subAccount=[email protected]
Field | Type | Required? | Description |
---|---|---|---|
subAccount | String | Yes | Sub-Account username |
currency | String | No | currency |
Response Data
Response
{
"message":"OK",
"code":1000,
"trace":"ef834248-51d3-4223-9481-f862aa9dd39f",
"data":{
"wallet":[
{
"currency":"USDT",
"name":"Tether USD",
"available":"1000.00000000",
"frozen":"0.00000000"
},
{
"currency":"BTC",
"name":"Bitcoin",
"available":"10000.00000000",
"frozen":"10.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 List (For Main Account) (KEYED)
Get Sub-Account list (For Main Account)
Request URL
GET https://api-cloud.bitmart.com/account/sub-account/main/v1/subaccount-list
Request Limit
Request Parameter
Request
curl -H 'X-BM-KEY:{{AccessKey}}'
https://api-cloud.bitmart.com/account/sub-account/main/v1/subaccount-list
Response Data
Response
{
"message": "OK",
"code": 1000,
"trace": "c03c22c3-75db-4aaa-9500-6dcd63dd9ccf",
"data": {
"subAccountList": [
{
"accountName": "[email protected]",
"status": 1
},
{
"accountName": "[email protected]",
"status": 1
}
]
}
}
Field | Type | Description |
---|---|---|
accountName | String | Sub-Account username |
status | Int | Account Status - 0 =disabled in background- 1 =normal- 2 =frozen by main account |
WebSocket Subscription
Overview
Server URL
Public Channel: wss://ws-manager-compress.bitmart.com/api?protocol=1.1
Private Channel: wss://ws-manager-compress.bitmart.com/user?protocol=1.1
Format
The message format sent by the client to the BitMart server.
{"op":"<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:
{"op": "subscribe", "args": ["spot/ticker:BTC_USDT"]}
- Means to subscribe to the ticker data of the spot trading pair BTC_USDT
- Example 2:
{"op": "login", "args": ["80618e45710812162b04892c7ee5ead4a3cc3e56", "1589267764859", "3ceeb7e1b8cb165a975e28a2e2dfaca4d30b358873c035 1c1a071d8c83314556"]}
- Login request before private channel subscription
Successful Response Format
The format of the success message returned by the BitMart server to the client.
The returned field not contains errorCode
Successful Response Format
When op=login:
{"event":"<operation>"}
When op=unsubscribe:
{"event":"<operation>","topic":"<topic>"}
When op=subscribe:
{"table":"<topic1>","data":"[{"<value1>","<value2>"}]"}
{"table":"<topic2>","data":"[{"<value1>","<value2>"}]"}
Example:
- Example 1:
{"event":"login"}
- Means successful login
- Example 2:
{"event":"unsubscribe","topic":"spot/ticker:BTC_USDT"}
- Means successful cancellation of ticker subscription for spot trading pair BTC_USDT
- Example 3:
{"table":"spot/ticker:BTC_USDT","data":"[{"<value1>","<value2>"}]"}
- Means the ticker subscription of spot trading pair BTC_USDT, 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.
If the returned field contains errorCode
, it means failure. For the reason of failure, please refer to: WebSocket Error Code
Failed Response Format
{"event":"<operation>","errorMessage":"<error_message>","errorCode":"<error_code>"}
- Example 1:
{"event":"login","errorCode":"91002","errorMessage":"API KEY not found"}
- Means login failed, your API KEY does not exist
- Example 2:
{"event":"subscribe","errorCode":"90004","errorMessage":"Invalid channel param"}
- 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("ping");
Connection Limit
- Each IP can maintain up to 20 connections with the BitMart public channel server and 10 connections with the private channel server.
- Once connected, allows clients to subscribe to up to 100 channels per connection.
- Send message rate limit:
- Initiate connection: Clients can initiate a maximum of 30 requests to connect to the BitMart server within 1 minute.
- Once connected: Clients can sending a maximum of 100 subscription messages within 10 seconds, message includes: PING frame, PONG frame, PING text, JSON format messages (subscription and unsubscription).
- Once connected: A maximum of 20 messages arrays can be sent by clients for a single subscription.
- Initiate connection: Clients can initiate a maximum of 30 requests to connect to the BitMart server within 1 minute.
- If the user sends more messages than the limit, the connection will be disconnected. IPs that are repeatedly disconnected will be blocked by the server.
How to subscribe to more than 1000 channels?
Best example of subscribing to 1000 channels or less: Use one IP to establish 10 server connections with BitMart, and each connection initiates 100 channel subscriptions
Best example of subscribing to 1000+ channels: Multiple IPs can be used, and each IP can establish 10 connections, and each connection initiates 100 channel subscriptions
Need to pay attention to?
- Subscribe to fewer channels and respond faster. It is recommended that you only subscribe to the channels you want
- If the number of messages sent exceeds the limit, the connection will be disconnected. IPs that are repeatedly disconnected will be blocked by the server
Lifeless connection
Connection that do not send task subscription data within 5 minutes will be considered lifeless and the server will close the connection.
Data Compression
Only when the market data is returned after subscription, the remote service will compress the data and return it to the client. The remote service returns data in two formats, Binary format and Text format. When the binary format is returned, the data has been compressed by the remote service and the client needs to decompress it.
Compression Introduction
zlib is a library for data compression, developed by Jean-loup Gailly and Mark Adler. The first version (v0.9) was published on May 1, 1995. zlib uses the abstract DEFLATE algorithm, originally written for the libpng library, and later generally used by many software. This library is free. Official link http://zlib.net/
Decompression Example
For more and more complete programming codes, please refer to the Quick Start API
Python
import zlib
def inflate(data):
decompress = zlib.decompressobj(
-zlib.MAX_WBITS
)
inflated = decompress.decompress(data)
inflated += decompress.flush()
return inflated.decode('UTF-8')
Nodejs
const zlib = require('zlib');
zlib.inflateRawSync(data);
Golang
import (
"compress/flate"
)
func zipDecode(in []byte) ([]byte, error) {
reader := flate.NewReader(bytes.NewReader(in))
defer reader.Close()
return ioutil.ReadAll(reader)
}
string(zipDecode(data))
php
@link https://php.net/manual/en/function.gzinflate.php
gzinflate($data)
Java
import java.util.zip.*;
public class StringCompressUtil {
private static String uncompress(ByteBuf buf) {
try {
byte[] temp = new byte[buf.readableBytes()];
ByteBufInputStream bis = new ByteBufInputStream(buf);
bis.read(temp);
bis.close();
Inflater decompresser = new Inflater(true);
decompresser.setInput(temp, 0, temp.length);
StringBuilder sb = new StringBuilder();
byte[] result = new byte[1024];
while (!decompresser.finished()) {
int resultLength = decompresser.inflate(result);
sb.append(new String(result, 0, resultLength, "UTF-8"));
}
decompresser.end();
return sb.toString();
}catch (Exception e) {
e.printStackTrace();
}
return "";
}
public static String decode(ByteBuf content){
byte[] bytes = new byte[content.readableBytes()];
content.readBytes(bytes);
ByteBuf byteBuf = Unpooled.wrappedBuffer(bytes);
String str = uncompress(byteBuf);
return str;
}
}
StringCompressUtil.decode(data)
Subscribe
Users can subscribe to one or more channels, and the total length of multiple channels cannot exceed 4096 bytes
subscribe
{"op": "subscribe", "args": ["<topic>"]}
Parameter Instructions
- op=subscribe
- The content of the args array is the subscribed topic
- topic is composed of
<channel>:<filter>
- channel is composed of business/name
- filter can filter data, refer to the description of each channel for details
Example
Request
{"op": "subscribe", "args": ["spot/ticker:BTC_USDT"]}
Response
{"table":"spot/ticker:BTC_USDT","data":[]}
Unsubscribe
Cancel subscription to one or more channels
unsubscribe
{"op": "unsubscribe", "args": ["<topic>"]}
Parameter Instruction
- op=unsubscribe
- The content of the args array is the subscribed topic
- topic is composed of
<channel>:<filter>
- channel is composed of business/name
- filter can filter data, refer to the description of each channel for details
Example
Request
{"op": "unsubscribe", "args": ["spot/ticker:BTC_USDT", "spot/ticker:ETH_USDT"]}
Response
{"event":"unsubscribe","topic":"spot/ticker:BTC_USDT"}
{"event":"unsubscribe","topic":"spot/ticker:ETH_USDT"}
【Public】Ticker Channel
Get the latest price, bid price, ask price and 24-hour trading volume
Pushing Rules
- No user login required
- After subscribing, the current data will be returned directly, and then the changes will be pushed
Request
Request
{
"op": "subscribe",
"args": ["spot/ticker:BTC_USDT"]
}
Message Format:
{"op":"subscribe","args":["<channel:symbol>","<channel:symbol>"]}
- op:
subscribe
- channel: Channel name
spot/ticker
, fixed value - symbol: Trading pair, such as
BTC_USDT
Response
Response
{
"table":"spot/ticker",
"data":[
{
"symbol":"BTC_USDT",
"last_price":"146.24",
"open_24h":"147.17",
"high_24h":"147.48",
"low_24h":"143.88",
"base_volume_24h":"117387.58",
"s_t": 1610936002
}
]
}
Return data description:
Field | Type | Description |
---|---|---|
symbol | string | Trading pair, BTC_USDT |
last_price | string | Last trading price |
high_24h | string | 24-hour highest price |
low_24h | string | 24-hour lowest price |
open_24h | string | 24-hour open price |
base_volume_24h | string | 24-hour volume in base currency |
s_t | long | timestamp (in seconds) |
Notice: This data is displayed after decompression, Refer to Data Compression for details
【Public】KLine Channel
Get the spot K-line data
Pushing Rules
- No user login required
- After subscribing, the current data will be returned directly, and then the changes will be pushed
Request
Request
{
"op": "subscribe",
"args": ["spot/kline1m:BTC_USDT"]
}
Message Format:
{"op":"subscribe","args":["<channel:symbol>","<channel:symbol>"]}
- op:
subscribe
- channel: Channel name, such as
spot/kline1m
- symbol: Trading pair, such as
BTC_USDT
Parameters Channel Name List
Channel Name | Description |
---|---|
spot/kline1m | 1-min KLine Channel |
spot/kline5m | 5-min KLine Channel |
spot/kline15m | 15-min KLine Channel |
spot/kline30m | 30-min KLine Channel |
spot/kline1H | 1-hour KLine Channel |
spot/kline2H | 2-hour KLine Channel |
spot/kline4H | 4-hour KLine Channel |
spot/kline1D | 1-day KLine Channel |
spot/kline1W | 1-week KLine Channel |
spot/kline1M | 1-month KLine Channel |
Response
Response
{
"table":"spot/kline1m",
"data":[
{
"candle":[
1534141852,
"162.03",
"162.04",
"161.96",
"161.98",
"336.452694"
],
"symbol":"ETH_USDT"
}
]
}
Return data description:
Field | Type | Description |
---|---|---|
symbol | string | Trading pair, BTC_USDT |
candle | List |
KLine data |
Notice: This data is displayed after decompression, Refer to Data Compression for details
【Public】Depth-All Channel
Return depth data, each push is the full data
Pushing Rules
- No user login required
- After subscribing, the current data will be returned directly, and then the changes will be pushed
Request
Request
{
"op": "subscribe",
"args": ["spot/depth5:BTC_USDT"]
}
Message Format:
{"op":"subscribe","args":["<channel:symbol>","<channel:symbol>"]}
- op:
subscribe
- channel: Channel name, such as
spot/depth5
- symbol: Trading pair, such as
BTC_USDT
Parameters Channel Name List
Channel Name | Description |
---|---|
spot/depth5 | 5 Level Depth Channel |
spot/depth20 | 20 Level Depth Channel |
spot/depth50 | 50 Level Depth Channel |
Response
Response
{
"table":"spot/depth5",
"data":[
{
"asks":[
[
"161.96",
"7.37567"
]
],
"bids":[
[
"161.94",
"4.552355"
]
],
"symbol":"ETH_USDT",
"ms_t": 1542337219120
}
]
}
Return data description:
Field | Type | Description |
---|---|---|
symbol | String | Trading pair, BTC_USDT |
asks | List |
Ask depth |
bids | List |
Bid depth |
ms_t | Long | Timestamp (in millisecond) |
Notice:This data is displayed after decompression, Refer to Data Compression for details
【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
{
"op": "subscribe",
"args": ["spot/depth/increase100:BTC_USDT"]
}
Request
{
"op": "request",
"args": ["spot/depth/increase100:BTC_USDT"]
}
Message Format:
{"op": "<op>", "args": ["<channel>:<symbol>"]}
- op:
subscribe
=Subscribe,request
=Single request for the latest depth snapshot - channel: Channel name, fixed value
spot/depth/increase100
, Support 100 levels - symbol: Trading pair, such as
BTC_USDT
Response
Full depth snapshot data
{
"data": [{
"asks": [
["23200", "0.69959"],
["28000.00", "0.20000"]
],
"bids": [
["23105", "1.80114"]
],
"ms_t": 1698292343610,
"symbol": "BTC_USDT",
"type": "snapshot",
"version": 4
}],
"table": "spot/depth/increase100"
}
Incremental depth data
{
"data": [{
"asks": [
["23200", "0.59959"]
],
"bids": [],
"ms_t": 1698292358292,
"symbol": "BTC_USDT",
"type": "update",
"version": 5
}],
"table": "spot/depth/increase100"
}
Return data description:
Field | Type | Description |
---|---|---|
symbol | String | Trading pair, BTC_USDT |
asks | List |
Ask depth |
bids | List |
Bid depth |
ms_t | Long | Timestamp (in millisecond) |
version | String | data version |
type | String | data type - snapshot =Full depth snapshot data - update =Incremental depth data |
Notice:This data is displayed after decompression, Refer to Data Compression for details
How to correctly maintain a copy of OrderBook locally:
- First, the client send a subscription request
{"op": "subscribe", "args": ["spot/depth/increase100:<symbol>"] }
- After successful subscription, you will receive two types of messages,
type=snapshot
(full data) andtype=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
{"op": "request", "args": ["spot/depth/increase100:<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:
- If there is no deep update for a period of time, an empty message 'asks': [], 'bids': [] will be sent to notify the user that the connection is normal. The pushed version is the same as the previous message. The empty message version=local cache version. can be discarded directly
- 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.
Flow Chart
【Public】Trade Channel
Get the latest real-time transaction data
Pushing Rules
- No user login required
- After successful subscription, incremental trade messages will be pushed
Request
Request
{
"op": "subscribe", "args": ["spot/trade:BTC_USDT"]
}
Message Format:
{"op":"subscribe","args":["<channel:symbol>","<channel:symbol>"]}
- op:
subscribe
- channel: Channel name
spot/trade
, fixed value - symbol: Trading pair, such as
BTC_USDT
Response
Response
{
"table": "spot/trade",
"data": [{
"symbol": "ETH_USDT",
"price": "162.12",
"side": "buy",
"size": "11.085",
"s_t": 1542337219
}]
}
Return data description:
Field | Type | Description |
---|---|---|
symbol | string | Trading pair, BTC_USDT |
side | string | Side of trade(buy or sell ) |
price | string | Trade price |
size | string | Trade quantity |
s_t | long | Timestamp (in seconds) |
Notice:This data is displayed after decompression, Refer to Data Compression for details
【Private】Login
Login Subscription Format
Request Format
{"op":"login","args":["<YOUR_API_KEY>", "<timestamp>", "<sign>"]}
- API_KEY: The user's API key
- timestamp: Timestamp, the unit is milliseconds, it will expire after 60 seconds
- sign: Signature, sign=CryptoJS.HmacSHA256(timestamp + "#" + api_memo + "#" + "bitmart.WebSocket", secret)
Example
Login Example
{"op": "login", "args": ["80618e45710812162b04892c7ee5ead4a3cc3e56", "1589267764859", "3ceeb7e1b8cb165a975e28a2e2dfaca4d30b358873c0351c1a071d8c83314556"]}
Response
{"event":"login"}
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:
{"op": "login", "args": ["80618e45710812162b04892c7ee5ead4a3cc3e56", "1589267764859", "3ceeb7e1b8cb165a975e28a2e2dfaca4d30b358873c0351c1a071d8c83314556"]}
Note
【Private】Order Progress
Get user trade data
Pushing Rules
- User login required
- Qualified orders will be pushed (Successfully placed an order, Partially filled, Fully filled, Canceled)
Request
Request
{
"op": "subscribe",
"args": ["spot/user/order:BTC_USDT"]
}
Message Format:
{"op":"subscribe","args":["<channel:symbol>","<channel:symbol>"]}
- op:
subscribe
- channel: Channel name
spot/user/order
, fixed value - symbol: Trading pair, such as
BTC_USDT
Response
Response
{
"data":[
{
"symbol":"BTC_USDT",
"side":"buy",
"type":"market",
"notional":"",
"size":"1.0000000000",
"ms_t":"1609926028000",
"price":"46100.0000000000",
"filled_notional":"46100.0000000000",
"filled_size":"1.0000000000",
"margin_trading":"0",
"state":"4",
"order_id":"2147857398",
"order_type":"0",
"last_fill_time":"1609926039226",
"last_fill_price":"46100.00000",
"last_fill_count":"1.00000",
"exec_type":"M",
"detail_id":"256348632",
"client_order_id":"order4872191"
}
],
"table":"spot/user/order"
}
Return data description:
Field | Type | Description |
---|---|---|
symbol | string | Trading pair, BTC_USDT |
order_id | string | Order ID |
price | string | Order price |
size | string | Order quantity |
notional | string | The purchase amount, returned when buying at market price; otherwise, an empty string is returned |
side | string | Side - buy - sell |
type | string | Type - limit - market |
ms_t | string | Timestamp (in milliseconds) |
filled_size | string | Filled size (Base currency) |
filled_notional | string | Filled notional amount (Quote currency) |
margin_trading | string | 0 :Spot order |
order_type | string | Order type - 0 =Regular- 1 =Maker only(Post only)- 2 =Fill or kill(FOK)- 3 =Immediate or Cancel(IOC) |
state | string | Order state - 4 =Order success, Pending for fulfilment- 5 =Partially filled- 6 =Fully filled- 8 =Canceled- 12 =Canceled after Partially filled |
last_fill_price | string | Latest trade price(0 if not filled) |
last_fill_count | string | Latest trade quantity(0 if not filled) |
last_fill_time | string | Latest trade time(0 if not filled) millisecond |
exec_type | string | Whether the trade was created by a maker or a taker. - M =Maker- T =Taker |
detail_id | string | Trade id |
client_order_id | string | Client-defined OrderId |
Notice:This data is displayed after decompression, Refer to Data Compression for details
【Private】Balance Change
Balance change push
Pushing Rules
- User login required
- Qualified balance changes (recharge, withdrawal, transfer, transaction)
Request
Request
{
"op": "subscribe",
"args": ["spot/user/balance:BALANCE_UPDATE"]
}
Message Format:
{"op": "subscribe", "args": ["<channel>:"<BALANCE_UPDATE>"]}
- op:
subscribe
- channel: Channel name
spot/user/balance:BALANCE_UPDATE
, fixed value
Response
Response
{
"data":[
{
"event_type":"TRANSACTION_COMPLETED ",
"event_time":"1693364237000",
"balance_details":[{
"ccy": "BTC",
"av_bal": "123.22",
"fz_bal": "12.56"
}]
}
],
"table":"spot/user/balance"
}
Return data description:
Field | Type | Description |
---|---|---|
event_type | string | Reason for change. Type - TRANSACTION_COMPLETED =Trade- ACCOUNT_RECHARGE =Recharge- ACCOUNT_WITHDRAWAL =Withdraw- ACCOUNT_TRANSFER =Transfer |
event_time | string | Create time |
balance_details | string | Detail |
>ccy | string | Changing Balance Currency |
>av_bal | string | Available balance after change |
>fz_bal | string | Freeze balance after change |
Notice:This data is displayed after decompression, Refer to Data Compression for details
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 must be long type | 30006 | 401 |
Header X-BM-TIMESTAMP range. Within a minute | 30007 | 401 |
Header X-BM-TIMESTAMP range. Timestamp for this request is outside of the recvWindow. | 30007 | 401 |
Param recvWindow must be long type | 30007 | 401 |
Param recvWindow must be less than 60000 and greater than 0 | 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 |
Funding Account&Sub-Account API Error Code
Example: httpStatus:200, body:{"code": 1000,"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1","message": "OK","data": {}}
error message | code error code | http status code |
---|---|---|
OK | 1000 | 200 |
Invalid request (maybe the body is empty, or the int parameter passes string data) | 60000 | 400 |
Asset account type does not exist | 60001 | 400 |
currency does not exist | 60002 | 400 |
Currency has been closed recharge channel, if there is any problem, please consult customer service | 60003 | 400 |
Currency has been closed withdraw channel, if there is any problem, please consult customer service | 60004 | 400 |
Minimum amount is %s | 60005 | 400 |
Maximum withdraw precision is %d | 60006 | 400 |
Only withdrawals from added addresses are allowed | 60007 | 400 |
Balance not enough | 60008 | 400 |
Beyond the limit | 60009 | 400 |
Withdraw id or deposit id not found | 60010 | 400 |
Address is not valid | 60011 | 400 |
This action is not supported in this currency(If IOTA, HLX recharge and withdraw calls are prohibited) | 60012 | 400 |
Your account is not allowed to recharge | 60020 | 403 |
Your account is not allowed to withdraw | 60021 | 403 |
No withdrawals for 24 hours | 60022 | 403 |
Sub-account does not have permission to operate | 60026 | 403 |
Only supports sub-account calls | 60027 | 403 |
Account is disabled for security reasons, please contact customer service | 60028 | 403 |
The account is frozen by the master account, please contact the master account to unfreeze the account | 60029 | 403 |
Method Not Allowed | 60030 | 405 |
Unsupported Media Type | 60031 | 415 |
User account not found | 60050 | 500 |
Internal Server Error | 60051 | 500 |
The specified sub-account could not be found | 61003 | 400 |
Duplicate requests (such as using an existing requestNo) | 61004 | 400 |
Asset transfer between accounts is not available | 61005 | 403 |
The sub-account api only supports organization accounts | 61006 | 403 |
Please complete your institution verification to enable withdrawal function. | 61007 | 403 |
Suspend transfer out | 61008 | 403 |
Spot Public Mark API Error Code
error message | code error code | http status code |
---|---|---|
OK | 1000 | 200 |
no data | 70000 | 200 |
request param can not be null | 70001 | 200 |
symbol is invalid | 70002 | 200 |
after is invalid | 71001 | 200 |
before is invalid | 71002 | 200 |
request after or before is invalid | 71003 | 200 |
request kline count limit | 71004 | 200 |
request step error | 71005 | 200 |
Spot&Margin API Error Code
Example: httpStatus:200, body:{"code": 1000,"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1","message": "OK","data": {}}
error message | code error code | http status code |
---|---|---|
OK | 1000 | 200 |
Bad Request | 50000 | 400 |
Symbol not found | 50001 | 400 |
From Or To format error | 50002 | 400 |
Step format error | 50003 | 400 |
Kline size over 500 | 50004 | 400 |
Order Id not found | 50005 | 400 |
Minimum size is %s | 50006 | 400 |
Maximum size is %s | 50007 | 400 |
Minimum price is %s | 50008 | 400 |
Minimum count*price is %s | 50009 | 400 |
RequestParam size is required | 50010 | 400 |
RequestParam price is required | 50011 | 400 |
RequestParam notional is required | 50012 | 400 |
Maximum limit*offset is %d | 50013 | 400 |
RequestParam limit is required | 50014 | 400 |
Minimum limit is 1 | 50015 | 400 |
Maximum limit is %d | 50016 | 400 |
RequestParam offset is required | 50017 | 400 |
Minimum offset is 1 | 50018 | 400 |
Invalid status. validate status is [1=Failed, 2=Success, 3=Frozen Failed, 4=Frozen Success, 5=Partially Filled, 6=Fully Fulled, 7=Canceling, 8=Canceled | 50019 | 400 |
Balance not enough | 50020 | 400 |
Invalid %s | 50021 | 400 |
Service unavailable | 50022 | 400 |
This Symbol can't place order by api | 50023 | 400 |
Order book size over 200 | 50024 | 400 |
Maximum price is %s | 50025 | 400 |
The buy order price cannot be higher than the open price | 50026 | 400 |
The sell order price cannot be lower than the open price | 50027 | 400 |
Missing parameters | 50028 | 400 |
The parameters do not match | 50029 | 400 |
Order is already canceled | 50030 | 400 |
Order is already completed | 50031 | 400 |
The order was matched or cancelled | 50032 | 400 |
The order quantity should be greater than 0 and less than or equal to 10 | 50033 | 400 |
The price is high and there is no matching depth | 50034 | 400 |
The price is low and there is no matching depth | 50035 | 400 |
Cancel failed, order is not revocable status | 50036 | 400 |
The maximum length of clientOrderId cannot exceed 32 | 50037 | 400 |
ClientOrderId only allows a combination of numbers and letters | 50038 | 400 |
Order_id and clientOrderId cannot be empty at the same time | 50039 | 400 |
Symbol Not Available | 50040 | 400 |
Out of query time range | 50041 | 400 |
clientOrderId is duplicate | 50042 | 400 |
Currency not found | 51000 | 400 |
Margin Account not Opened | 51001 | 400 |
Margin Account Not Available | 51002 | 400 |
Account Limit | 51003 | 400 |
Exceed the maximum number of borrows available | 51004 | 400 |
Less than the minimum borrowable amount | 51005 | 400 |
Exceeds the amount to be repaid | 51006 | 400 |
order_mode not found | 51007 | 400 |
Operation is limited, please try again later | 51008 | 400 |
Parameter mismatch: limit order/market order quantity should be greater than the minimum number of should buy/sell | 51009 | 400 |
Parameter mismatch: limit order price should be greater than the minimum buy price | 51010 | 400 |
Parameter mismatch: Limit order quantity * price should be greater than the minimum transaction amount | 51011 | 400 |
Participation mismatch: the number of market order buy orders should be greater than the minimum buyable amount | 51012 | 400 |
Parameter mismatch: the price of market order buy order placed is too small | 51013 | 400 |
Parameter mismatch: the amount of market order sell orders placed is too small | 51014 | 400 |
Quantity is too small | 51015 | 400 |
Unsupported OrderMode Type | 52000 | 400 |
Unsupported Trade Type | 52001 | 400 |
Unsupported Side Type | 52002 | 400 |
Unsupported Query State Type | 52003 | 400 |
End time must be greater than or equal to Start time | 52004 | 400 |
Your account is frozen due to security policies. Please contact customer service | 53000 | 403 |
Your kyc country is restricted. Please contact customer service. | 53001 | 403 |
Your account has not yet completed the kyc advanced certification, please complete first | 53002 | 403 |
No permission, please contact the main account | 53003 | 403 |
This trading pair is not available to trade in your region | 53004 | 403 |
Don't have permission to access the interface | 53005 | 403 |
Please complete your personal verification(Starter) | 53006 | 403 |
Please complete your personal verification(Advanced) | 53007 | 403 |
Services is not available in your countries and areas | 53008 | 403 |
Your account has not yet completed the qr code certification, please complete first | 53009 | 403 |
This account is restricted from borrowing | 53010 | 403 |
Method Not Allowed | 57001 | 405 |
Unsupported Media Type | 58001 | 415 |
User account not found | 59001 | 500 |
Internal Server Error | 59002 | 500 |
Spot wallet call fail | 59003 | 500 |
Margin wallet service call exception | 59004 | 500 |
Margin wallet service restricted | 59005 | 500 |
Transfer fail | 59006 | 500 |
Get symbol risk data fail | 59007 | 500 |
Trading order failure | 59008 | 500 |
Loan success,but trading order failure | 59009 | 500 |
Insufficient loan amount. | 59010 | 500 |
The Get Wallet Balance service call fail, please try again later | 59011 | 500 |
WebSocket Error Code
Error Code Format
{"event":"<operation>", "errorMessage":"", "errorCode":""}
Error Code
Error Message | Error Code |
---|---|
Invalid message format | 90001 |
Invalid op param | 90002 |
Invalid args param | 90003 |
Invalid channel param | 90004 |
API KEY is empty | 91001 |
API KEY not found | 91002 |
API KEY has frozen | 91003 |
API KEY over expire time | 91004 |
Already logged in | 91005 |
User not logged in / User must be logged in | 91006 |
Param sign is empty | 91010 |
Param sign is wrong | 91011 |
Param timestamp is empty | 91021 |
Param timestamp range. Within a minute | 91022 |
Param timestamp invalid format | 91023 |
Invalid symbol param | 92001 |
Request frequency exceeds limit | 94001 |
Internal system error | 95000 |