Introduction
Getting Started
Welcome to the developer documentation.
Instruction For Calling Endpoints
developers can choose their own way to query the market, trade or withdraw according to their usage scenarios and preferences.
Contact Us
Join our Telegram API Group
Product Dictionary
Trade
Field | Description | Details |
---|---|---|
currency | Currency | Currency refers to the basic unit that can be transferred in and out, such as BTC, ETH, EOS, etc |
symbol_id | Trading pair id | The unique number of the trading pair, such as the ID of BTC_USDT is 53, mainly used in the Websocket interface |
symbol | Trading pair name | Consists of base and quote currency. Taking BTC_USDT as an example, BTC is the base currency, and USDT is the quote currency. Trading pairs are mainly used in spot trading |
Contract
Field | Description | Details |
---|---|---|
symbol | Trading pair name | Consists of base and quote currency. Taking BTCUSDT as an example, BTC is the base currency, and USDT is the quote currency. Trading pairs are mainly used in contract trading |
Order and Trade ID
Field | Description |
---|---|
order_id | Order number, the order ID under the same currency pair of each business line is unique |
trade_id | The unique number of the trade |
Time
The time returned by the system is all in the form of time pinches.
Field | Description |
---|---|
s_t | accurate to seconds of timestamp |
ms_t | accurate to milliseconds of timestamp |
Standard Rules
This chapter is mainly divided into the following three aspects for the details of standard specifications:
Numbers ID
Numbers
To maintain the integrity and accuracy across platforms, decimal numbers are returned as strings. It is recommended that you also convert numbers to strings when making requests to avoid truncation and precision errors.
Integers (such as transaction ID and order) are not quoted.
ID
Unless otherwise stated, most identifiers are UUIDs. When making a request that requires a UUID, the following two formats (with and without dashes) are accepted.
132fb6ae-456b-4654-b4e0-d681ac05cea1 or 132fb6ae456b4654b4e0d681ac05cea1
Update Plan
Change Log
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
Basic Information
API Basic Information
- The interface may require the user's API Key. For how to create an API-KEY, please refer to here API KEY Interface Authentication.
- RESTful API URL: https://api-cloud.bitmart.com
- The responses of all interfaces are in JSON format.
HTTP Response Codes
- HTTP 4XX Error codes are used to indicate wrong request content, behavior, and format. The problem is from the request sender.
- HTTP 403 The error code indicates a violation of the restriction (prohibited call).
- HTTP 429 The error code indicates that the access frequency is overrun and the IP will be blocked.
- HTTP 418 The error code indicates that the IP has been blocked after error code 429.
- HTTP 5XX Error codes are used to indicate problems with BitMart server.
API Returned Codes
When using the interface, HTTP 200 means that the client has submitted a request to the business core through the gateway and it has returned information, but it does not mean that the business request is successful. It may have been executed, or the execution may fail, and further confirmation is required at this time. Please pay attention to the code field in the returned data.
For details, please refer to Error Code List
Authentication and Signature
In order to facilitate access, we provide SDK in some languages for reference
* bitmart-go-sdk-api
* bitmart-python-sdk-api
* bitmart-java-sdk-api
* bitmart-php-sdk-api
This chapter mainly divides the verification details into the following four aspects:
- Generate API Key
- Make a request
- Signature
- Timestamp
1. Generate API Key
Before signing any request, you must create an API Key through the BitMart website. After creating the API Key, you will get 3 pieces of information you must remember:
- Access Key
- Secret Key
- Memo
Access Key and Secret Key will be randomly generated and provided by BitMart, and Memo will be provided by you to ensure the security of API access. BitMart will store the encrypted hash value of the Secret Key for verification, but if you forget the Secret Key, it cannot be recovered. Please regenerate the new API Key through the BitMart website.
Example
Login Bitmart website and enter the account page
Click the API Settings button to enter the CREATE API page
2. Make a Request
The request contains two parts, one is header and the other is queryString
Interface Header Parameters
All REST request headers must include the following:
X-BM-KEY: Access Key of type string.
X-BM-SIGN: Use HmacSHA256 signature (see Signature).
X-BM-TIMESTAMP: The timestamp of the request. (UTC0 time zone timestamp, accurate to milliseconds)
Interface Content Type
Request Example: GET/DELETE
curl {{host}}/v1/goto?symbol=BMXBTC&side=BUY
# queryString: symbol=BMXBTC&side=BUY
- For interfaces using the GET and DELETE methods, the content can be sent in two forms: application/json or application/x-www-form-urlencoded. The parameter must be sent in the query string. (The order of the parameters is not required.)
Request Example: POST/PUT
curl -X POST {{host}}/v1/goto -H "Content-type: application/json" -d '{"symbol":"BMX","side":"BUY"}'
# queryString: {"symbol":"BMX","side":"BUY"}
- For interfaces using the POST and PUT methods, the content can be sent in application/json form. (The order of the parameters is not required.)
Special Note: In the example on the right,
The request method of GET/DELETE, the query string is the form type of key1=value2&key2=value2
The request method of POST/PUT, the query string is the json type of {"symbol":"BMX","side":"BUY"}
3.Signature
Signature Algorithm Example: In the example below, param variable message=
timestamp + "#" + memo + "#" + queryString
// javascript language
sign=CryptoJS.HmacSHA256(message, YourSecretKey)
// python language
def sign(message, your_secret_key):
mac = hmac.new(bytes(your_secret_key, encoding='utf8'), bytes(message, encoding='utf-8'), digestmod='sha256')
return mac.hexdigest()
// java language
import org.apache.commons.codec.binary.Hex;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
public final class CloudSignature {
static final String HMAC_SHA256 = "HmacSHA256";
static String createSha256Signature(String yourSecretKey, String message) {
try {
Mac sha256 = Mac.getInstance(HMAC_SHA256);
SecretKeySpec secretKeySpec = new SecretKeySpec(yourSecretKey.getBytes(), HMAC_SHA256);
sha256.init(secretKeySpec);
return Hex.encodeHexString(sha256.doFinal(message.getBytes()));
} catch (Exception ex) {
ex.printStackTrace();
}
return null;
}
}
// go language
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
)
func HmacSha256Base64Signer(message string, yourSecretKey string) (string, error) {
mac := hmac.New(sha256.New, []byte(yourSecretKey))
_, err := mac.Write([]byte(message))
if err != nil {
return "", err
}
return hex.EncodeToString(mac.Sum(nil)), nil
}
The request header of X-BM-SIGN is signed by the HMAC SHA256 algorithm and converted to lowercase hexadecimal (toHexString) encoding. Among them, the key of the algorithm is your api secret key, and the signed content is timestamp + "#" + memo + "#" + queryString
.
Among them, the value of timestamp is the same as the X-BM-TIMESTAMP in request header.
Note: If the length of your sign is not equal to 64, or if the sign is uppercase, it is wrong.
4.Timestamp
Unix timestamps accurate to milliseconds using UTC0 time zone
Example: If the current time: 2020-04-28 09:21:30.000, then timestamp=1588065690000
Example
The keys are as follows: Note that the following two interfaces are deployed in the production environment, and users can directly test and call after replacing with their own KEY.
Key | Value |
---|---|
accessKey | 80618e45710812162b04892c7ee5ead4a3cc3e56 |
secretKey | 6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9 |
memo | test001 |
Example: /spot/v1/test-get
echo -n "1589793795969#test001#symbol=BTC_USDT" | openssl dgst -sha256 -hmac "6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9"
(stdin)= 118eb558afa7d84e8710004f8416ddb771f50718c85f60a45069d0ccbe6ee1e0
curl --location --request GET 'localhost:8080/spot/v1/test-get?symbol=BTC_USDT'
--header 'Content-Type: application/json'
--header 'X-BM-KEY: 80618e45710812162b04892c7ee5ead4a3cc3e56'
--header 'X-BM-SIGN: 118eb558afa7d84e8710004f8416ddb771f50718c85f60a45069d0ccbe6ee1e0'
--header 'X-BM-TIMESTAMP: 1589793795969'
{"message":"OK","code":1000,"trace":"17105b32-cc5b-406a-ab6e-6d9ed0fa4fd8","data":{}}
Request interface: /spot/v1/test-get
Request method: GET
Current timestamp: timestamp=1589793795969
Parameter | Value |
---|---|
symbol | BTC_USDT |
Returned data: The request is a success if code=1000 in returned data.
Example: /spot/v1/test-post
echo -n '1589793796145#test001#{"symbol":"BTC_USDT","price":"8600","count":"100"}' | openssl dgst -sha256 -hmac "6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9"
(stdin)= c31dc326bf87f38bfb49a3f8494961abfa291bd549d0d98d9578e87516cee46d
curl --location --request POST 'localhost:8080/spot/v1/test-post'
--header 'Content-Type: application/json'
--header 'X-BM-KEY: 80618e45710812162b04892c7ee5ead4a3cc3e56'
--header 'X-BM-SIGN: c31dc326bf87f38bfb49a3f8494961abfa291bd549d0d98d9578e87516cee46d'
--header 'X-BM-TIMESTAMP: 1589793796145'
--d '{"symbol":"BTC_USDT","price":"8600","count":"100"}'
{"message":"OK","code":1000,"trace":"17105b32-cc5b-406a-ab6e-6d9ed0fa4fd8","data":{}}
Request interface: /spot/v1/test-post
Request method: POST
Current timestamp: timestamp=1589793796145
Parameter | Value |
---|---|
symbol | BTC_USDT |
price | 8600 |
count | 100 |
Returned data: The request is a success if code=1000 in returned data.
RequestFormat
This article mainly describes some specifications of the interface from the following two aspects. * Request standard * Authentication type
Request Standard
1.Rest Interface
1.1 Request parameter and format
GET/DELETE
curl https://api-cloud.bitmart.com/contract/v1/ifcontract/contracts?contractID=1
For interfaces using GET, DELETE methods, the parameters should be sent via query string.
POST/PUT
curl https://api-cloud.bitmart.com/contract/v1/ifcontract/submitOrder
body: {"contract_id":1,"category":1,"way":1,"open_type":1,"leverage":10,"custom_id":1,"price":5000,"vol":10,"nonce":1589266686}
For interfaces using POST, PUT methods, the parameters should be sent in the request body for concent type of application/json.
1.2 Reponse
Response:
{
"code": 1000,
"trace":"886fb6ae-456b-4654-b4e0-d681ac05cea1",
"message": "OK",
"data": [
{
"low": "130",
"high": "130",
"open": "130",
"close": "130",
"last_price": "130",
"avg_price": "130",
"volume": "0",
"timestamp": 1532610000,
"rise_fall_rate": "0",
"rise_fall_value": "0"
}
]
}
The server response data format is JSON.
Field | Description |
---|---|
code | Error code,See Details |
message | Error message |
trace | Each request event tracking ID, the server will return for each request |
data | Data returned by the server |
2.WebSocket Interface
No description.
Authentication Type
This chapter is mainly divided into the following two aspects of interface type details:
- Public interface
- Private interface
1. Public Interface
The public interface can be used to obtain configuration information and market data. Public requests can be called without authentication.
2. Private Interface
The private interface can be used for order and account management. Each private request must be signed using a standardized authentication method. The private interface needs to be verified with your API key.
Interface Permission
Whether you have permission to call the interface requires attention to the following two aspects:
* Interface authentication
* API Permission
Interface authentication
When the user calls, APIKEY and verification parameters need to be passed in the way specified by the interface. The first line of each interface will have a description of what authentication the interface needs.
Simply put, the interface authentication is divided into the following three cases:
Interface Type | Authentication Type | Description |
---|---|---|
Public | NONE | X-BM-KEY is not required, X-BM-SIGN is not required |
Private | KEYED | X-BM-KEY is required, X-BM-SIGN is not required |
Private | SIGNED | X-BM-KEY is required, X-BM-SIGN is required |
API KEY Permission
Refers to the user specified authorization to the API when applying for the API. That is, when users apply for API KEY on the BitMart website page, they can check API permissions, such as: trading permissions (including contract transactions and spot transactions). (Default: read-only permission).
Details:
Spot Interface | Description | Authentication Type | Permissions |
---|---|---|---|
/contract/public/details | Get a detailed list of all trading pairs | NONE | No permission required |
/contract/public/depth | Get full depth of trading pairs | NONE | No permission required |
/contract/public/open-interest | Get Contract Openinterest | NONE | No permission required |
/contract/private/submit-order | Submit Contract Order | SIGNED | Trading Permission |
/contract/private/cancel-order | Cancel Contract Order | SIGNED | Trading Permission |
/contract/private/cancel-orders | Batch Cancel Contract Orders | SIGNED | Trading Permission |
/contract/private/order | Get Contract Order Detail | KEYED | Read-Only Permission |
/contract/private/order-history | Get Contract Order History | KEYED | Read-Only Permission |
/contract/private/trades | Get Contract Order Trade Detail | KEYED | Read-Only Permission |
/contract/private/assets-detail | Get Contract Assets Detail | KEYED | Read-Only Permission |
/contract/private/position | Get Current Position Detail | KEYED | Read-Only Permission |
/contract/public/funding-rate | Get Current Funding Rate | NONE | No permission required |
/contract/public/kline | Get K-line | NONE | No permission required |
Spot Interface | Description | Authentication Type | Permissions |
---|---|---|---|
/spot/v1/currencies | Get a list of all cryptocurrencies on the platform | NONE | No permission required |
/spot/v1/symbols | Get a list of all trading pairs on the platform | NONE | No permission required |
/spot/v1/symbols/details | Get a detailed list of all trading pairs on the platform | NONE | No permission required |
/spot/v1/ticker | Get ticker | NONE | No permission required |
/spot/v1/steps | Get K-Line steps | NONE | No permission required |
/spot/v1/symbols/kline | Get K-Line | NONE | No permission required |
/spot/v1/symbols/book | Get orderbook | NONE | No permission required |
/spot/v1/symbols/trades | Get recent trades | NONE | No permission required |
/spot/v1/wallet | Get user wallet | KEYED | Read-Only Permission |
/spot/v1/submit_order | Place order | SIGNED | Trading Permission |
/spot/v1/cancel_order | Cancel order | SIGNED | Trading Permission |
/spot/v1/cancel_orders | Cancel all orders | SIGNED | Trading Permission |
/spot/v1/order_detail | Get order detail | KEYED | Read-Only Permission |
/spot/v1/orders | Get user orders | KEYED | Read-Only Permission |
/spot/v1/trades | Get user trades | KEYED | Read-Only Permission |
API Broker Interface | Description | Authentication Type | Permissions |
---|---|---|---|
/spot/v1/broker/rebate | Applicable to query API Broker's rebate records | KEYED | Read-Only Permission |
Rate Limit
When the requests exceed the rate limit, the 429 status will be returned: the request is too frequent.
REST API
If a valid API key is passed in, the user id will be used to limit the rate; if not, the public IP will be used to limit the rate.
Rate limit rules: There is a separate description on each interface. If there is not, the rate limit is 25 times/5 sec in general.
Each call to the interface will return 3 Response Headers with limit tags, as shown below:
Example:
X-BM-RateLimit-Remaining: 10
X-BM-RateLimit-Limit: 600
X-BM-RateLimit-Reset: 60
The above setting means that it can be called 600 times within 60 seconds, and currently has been called 10 times
Response Header | Description |
---|---|
X-BM-RateLimit-Remaining | The number of requests left in the current time window |
X-BM-RateLimit-Limit | The max number of requests in the current time window |
X-BM-RateLimit-Reset | Current time window, in seconds |
The specific interface limits are as follows:
System Interface | Interface Name | Limit Target | Rate |
---|---|---|---|
/system/time | Get system time | IP | 10 times/sec |
/system/service | Get system service status | IP | 10 times/sec |
Funding Account Interface | Interface Name | Limit Target | Rate | Special Remarks |
---|---|---|---|---|
/account/v1/currencies | Get currencies | IP | 2 times/2 sec | |
/account/v1/wallet | Get account balance | X-BM-KEY | 12 times/2 sec | |
/account/v1/deposit/address | Deposit address | X-BM-KEY | 2 times/2 sec | |
/account/v1/withdraw/charge | Withdraw quota | X-BM-KEY | 2 times/2 sec | |
/account/v1/withdraw/apply | Withdraw | X-BM-KEY | 8 times/2 sec | |
/account/v2/deposit-withdraw/history | Get deposit and withdraw history V2 | X-BM-KEY | 8 times/2 sec | |
/account/v1/deposit-withdraw/detail | Get a deposit Or withdraw detail | X-BM-KEY | 8 times/2 sec | |
/spot/v1/margin/isolated/account | Get Margin Account Details(Isolated) | X-BM-KEY | 12 times/2 sec | |
/spot/v1/margin/isolated/transfer | Margin Asset Transfer | X-BM-KEY | 2 times/2 sec | |
/spot/v1/user_fee | Basic Fee Rate | X-BM-KEY | 2 times/2 sec | |
/spot/v1/trade_fee | Actual Trade Fee Rate | X-BM-KEY | 2 times/2 sec |
Contract Interface | Interface Name | Limit Target | Rate | Special Remarks |
---|---|---|---|---|
/contract/public/details | Get a detailed list of all trading pairs | IP | 12 times/2 sec | |
/contract/public/depth | Get full depth of trading pairs | IP | 12 times/2 sec | |
/contract/public/open-interest | Get Contract Openinterest | IP | 2 times/2 sec | |
/contract/private/submit-order | Submit Contract Order | X-BM-KEY | 24 times/2 sec | |
/contract/private/cancel-order | Cancel Contract Order | X-BM-KEY | 40 times/2 sec | |
/contract/private/cancel-orders | Batch Cancel Contract Orders | X-BM-KEY | 2 times/2 sec | |
/contract/private/submit-plan-order | Submit Contract Plan Order | X-BM-KEY | 24 times/2 sec | |
/contract/private/cancel-plan-order | Cancel Contract Plan Order | X-BM-KEY | 40 times/2 sec | |
/contract/private/order | Get Contract Order Detail | X-BM-KEY | 50 times/2 sec | |
/contract/private/order-history | Get Contract Order History | X-BM-KEY | 6 times/2 sec | |
/contract/private/trades | Get Contract Order Trade Detail | X-BM-KEY | 6 times/2 sec | |
/contract/private/assets-detail | Get Contract Assets Detail | X-BM-KEY | 12 times/2 sec | |
/contract/private/position | Get Current Position Detail | X-BM-KEY | 6 times/2 sec | |
/contract/public/funding-rate | Get Current Funding Rate | IP | 2 times/2 sec | |
/contract/public/kline | Get K-line | IP | 12 times/2 sec |
Spot Interface | Interface Name | Limit Target | Rate | Special Remarks |
---|---|---|---|---|
/spot/v1/currencies | Get a list of all cryptocurrencies | IP | 8 times/2 sec | |
/spot/v1/symbols | Get a list of all trading pairs | IP | 8 times/2 sec | |
/spot/v1/symbols/details | Get a detailed list of all trading pairs | IP | 12 times/2 sec | |
/spot/v1/ticker | Get ticker | IP | 12 times/2 sec | |
/spot/v2/ticker | Get Ticker of All Pairs | IP | 2 times/2 sec | |
/spot/v1/ticker_detail | Get Ticker of a Trading Pair | IP | 12 times/2 sec | |
/spot/v1/steps | Get K-Line steps | IP | 2 times/2 sec | |
/spot/v1/symbols/kline | Get k-Line | IP | 12 times/2 sec | |
/spot/v1/symbols/book | Get orderbook | IP | 12 times/2 sec | |
/spot/v1/symbols/trades | Get the latest trades | IP | 12 times/2 sec | |
/spot/v1/wallet | Get the user's wallet balance | X-BM-KEY | 12 times/2 sec | |
/spot/v1/submit_order | Place spot order | X-BM-KEY | 60 times/2 sec | |
/spot/v2/submit_order | Place spot order | X-BM-KEY | 60 times/2 sec | |
/spot/v1/margin/submit_order | Place margin order | X-BM-KEY | 60 times/2 sec | |
/spot/v2/cancel_order | Cancel order | X-BM-KEY | 60 times/2 sec | |
/spot/v3/cancel_order | Cancel order | X-BM-KEY | 60 times/2 sec | |
/spot/v1/cancel_orders | Cancel all orders in the specified direction of the specified trading pair | X-BM-KEY | 4 times/2 sec | |
/spot/v1/order_detail | Get order details | X-BM-KEY | 60 times/2 sec | |
/spot/v2/order_detail | Get order details | X-BM-KEY | 60 times/2 sec | |
/spot/v2/orders | Get user's recent orders V2 | X-BM-KEY | 12 times/2 sec | |
/spot/v3/orders | Get user's recent orders | X-BM-KEY | 12 times/2 sec | |
/spot/v1/trades | User trade records | X-BM-KEY | 12 times/2 sec | |
/spot/v2/trades | User trade records | X-BM-KEY | 12 times/2 sec | |
/spot/v1/batch_orders | Batch order | X-BM-KEY | 60 times/2 sec | |
/spot/v2/batch_orders | Batch order | X-BM-KEY | 60 times/2 sec |
Sub-Account Interface | Interface Name | Limit Target | Rate | Special Remarks |
---|---|---|---|---|
/account/sub-account/main/v1/sub-to-main | Sub-Account Spot Asset Transfer (For Main Account) | X-BM-KEY | 2 times/2 sec | |
/account/sub-account/sub/v1/sub-to-main | Sub-Account Spot Asset Transfer (For Sub-Account) | X-BM-KEY | 2 times/2 sec | |
/account/sub-account/main/v1/main-to-sub | Main Account Spot Asset Transfer (For Main Account) | X-BM-KEY | 2 times/2 sec | |
/account/sub-account/sub/v1/sub-to-sub | Sub-Account to Sub-Account Spot Asset Transfer (For Sub-Account) | X-BM-KEY | 2 times/2 sec | |
/account/sub-account/main/v1/sub-to-sub | Sub-account to Sub-Account Spot Asset Transfer (For Main Account) | X-BM-KEY | 2 times/2 sec | |
/account/sub-account/main/v1/transfer-list | Query Sub-account Spot Asset Transfer History (For Main Account) | X-BM-KEY | 8 times/2 sec | |
/account/sub-account/v1/transfer-history | Get Account Spot Asset Transfer History | X-BM-KEY | 8 times/2 sec | |
/account/sub-account/main/v1/wallet | Get Sub-Account Spot Wallet Balance (For Main Account) | X-BM-KEY | 12 times/2 sec | |
/account/sub-account/main/v1/subaccount-list | Get Sub-account List (For Main Account) | X-BM-KEY | 8 times/2 sec |
Margin Loan Interface | Interface Name | Limit Target | Rate | Special Remarks |
---|---|---|---|---|
/spot/v1/margin/isolated/borrow | Margin Borrow (Isolated) | X-BM-KEY | 2 times/2 sec | |
/spot/v1/margin/isolated/repay | Margin Repay (Isolated) | X-BM-KEY | 2 times/2 sec | |
/spot/v1/margin/isolated/borrow_record | Get Borrow Record(Isolated) | X-BM-KEY | 60 times/2 sec | |
/spot/v1/margin/isolated/repay_record | Get Repayment Record(Isolated) | X-BM-KEY | 60 times/2 sec | |
/spot/v1/margin/isolated/pairs | Get Trading Pair Borrowing Rate and Amount | X-BM-KEY | 2 times/2 sec |
API Broker Interface | Interface Name | Limit Target | Rate | Special Remarks |
---|---|---|---|---|
/spot/v1/broker/rebate | Applicable to query API Broker's rebate records | X-BM-KEY | 1 times/1 sec |
System Status
Get System Time
Get system time
(Authentication type:NONE, See Interface Permission)
Request Format
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
(Authentication type:NONE, See Interface Permission)
Request Format
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 |
Restful Public Market Data
Get Currency List
Get a list of all cryptocurrencies on the platform
(Authentication type:NONE, See Interface Permission)
Request Format
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-not |
Get List of Trading Pairs
Get a list of all trading pairs on the platform
(Authentication type:NONE, See Interface Permission)
Request Format
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 |
Get List of Trading Pair Details
Get a detailed list of all trading pairs on the platform
(Authentication type:NONE, See Interface Permission)
Request Format
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 |
Instruction
Description of the trading pair details field:
Trading pair details | 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 | ’trading’,is trading;’pre-trade’,pre-open |
Get Ticker of All Pairs
Ticker is an overview of the market status of a trading pair, including the latest trade price, top bid and ask prices and 24-hour trading volume
(Authentication type:NONE, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/spot/v1/ticker
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v1/ticker?symbol=BTC_USDT
Field | Type | Required? | Description |
---|---|---|---|
symbol | String | No | Trading pair symbol (Optional, return ticker data of all trading pairs by default) |
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"
}
]
}
}
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 |
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
(Authentication type:NONE, See Interface Permission)
Request Format
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
Applicable for querying aggregated tickers of a particular trading pair
(Authentication type:NONE, See Interface Permission)
Request Format
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, like (BTC_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
Get all k-line steps supported by the platform, expressed in minutes, minimum 1 minute.
(Authentication type:NONE, See Interface Permission)
Request Format
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
Get k-line data within a specified time range of a specified trading pair
(Authentication type:NONE, See Interface Permission)
Request Format
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 symbol |
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
Get full depth of trading pairs.
(Authentication type:NONE, See Interface Permission)
Request Format
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 symbol |
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
Get the latest trade records of the specified trading pair
(Authentication type:NONE, See Interface Permission)
Request Format
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 type (buy or sell ) |
Sub-Account Endpoints
Sub-Account Spot Asset Transfer (For Main Account)
Sub-Account Spot Asset Transfer (For Main Account)
(Authentication type:SIGNED, See Interface Permission)
Request Format
POST https://api-cloud.bitmart.com/account/sub-account/main/v1/sub-to-main
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/account/sub-account/main/v1/sub-to-main
{
"requestNo":"4e2adcff-2122-1ce7-2557-4f65d2ce1ca2",
"amount":"1",
"currency":"BTC",
"subAccount":"[email protected]"
}
Field | Type | Required? | Description |
---|---|---|---|
requestNo | string | Yes | UUID,unique identifier |
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 Spot Asset Transfer (For Sub-Account)
Sub-Account Spot Asset Transfer (For Sub-Account)
(Authentication type:SIGNED, See Interface Permission)
Request Format
POST https://api-cloud.bitmart.com/account/sub-account/sub/v1/sub-to-main
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/account/sub-account/sub/v1/sub-to-main
{
"requestNo":"4e2adcff-2122-1ce7-2557-4f65d2ce1ca2",
"amount":"1",
"currency":"BTC"
}
Field | Type | Required? | Description |
---|---|---|---|
requestNo | string | Yes | UUID,unique identifier |
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 Spot Asset Transfer (For Main Account)
Main Account Spot Asset Transfer (For Main Account)
(Authentication type:SIGNED, See Interface Permission)
Request Format
POST https://api-cloud.bitmart.com/account/sub-account/main/v1/main-to-sub
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/account/sub-account/main/v1/main-to-sub
{
"requestNo":"4e2adcff-2122-1ce7-2557-4f65d2ce1ca2",
"amount":"1",
"currency":"BTC",
"subAccount":"[email protected]"
}
Field | Type | Required? | Description |
---|---|---|---|
requestNo | string | Yes | UUID,unique identifier |
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 Spot Asset Transfer (For Sub-Account)
Sub-Account to Sub-Account Spot Asset Transfer (For Sub-Account)
(Authentication type:SIGNED, See Interface Permission)
Request Format
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
{
"requestNo":"4e2adcff-2122-1ce7-2557-4f65d2ce1ca2",
"amount":"1",
"currency":"BTC",
"subAccount":"[email protected]"
}
Field | Type | Required? | Description |
---|---|---|---|
requestNo | string | Yes | UUID,unique identifier |
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 Spot Asset Transfer (For Main Account)
Sub-Account to Sub-Account Spot Asset Transfer (For Main Account)
(Authentication type:SIGNED, See Interface Permission)
Request Format
POST https://api-cloud.bitmart.com/account/sub-account/main/v1/sub-to-sub
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/account/sub-account/main/v1/sub-to-sub
{
"requestNo":"4e2adcff-2122-1ce7-2557-4f65d2ce1ca2",
"amount":"1",
"currency":"BTC",
"fromAccount":"[email protected]",
"toAccount":"[email protected]"
}
Field | Type | Required? | Description |
---|---|---|---|
requestNo | string | Yes | UUID,unique identifier |
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.
Query Sub-Account Spot Asset Transfer History (For Main Account)
Query Sub-Account Spot Asset Transfer History (For Main Account)
(Authentication type:KEYED, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/account/sub-account/main/v1/transfer-list
Request Limit
Request Parameter
Request
curl 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 (value 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
Get Account Spot Asset Transfer History
(Authentication type:KEYED, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/account/sub-account/v1/transfer-history
Request Limit
Request Parameter
Request
curl 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 (value 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)
Get Sub-Account Spot Wallet Balance (For Main Account)
(Authentication type:KEYED, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/account/sub-account/main/v1/wallet
Request Limit
Request Parameter
Request
curl 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)
Get Sub-account List (For Main Account)
(Authentication type:KEYED, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/account/sub-account/main/v1/subaccount-list
Request Limit
Request Parameter
Request
curl 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 |
'1' = normal | ||
'0' = disabled in background | ||
'2' = frozen by main account |
Funding Account
Get Account Balance
Gets Account Balance
(Authentication type:KEYED, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/account/v1/wallet
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/account/v1/wallet
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"
},
{
"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 Currencies
Gets the currency of the asset for withdrawal
(Authentication type:None, See Interface Permission)
Request Format
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
Get the user's wallet balance for all currencies
(Authentication type:NONE, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/spot/v1/wallet
Request Limit
Request Parameter
Request
curl 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
Gets Deposit Address
(Authentication type:KEYED, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/account/v1/deposit/address
Request Format
Request Parameter
Request
curl 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
Query withdraw quota for currencies
(Authentication type:KEYED, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/account/v1/withdraw/charge
Request Limit
Request Parameter
Request
curl 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
Creates a withdraw request from spot account to an external address
(Authentication type:SIGNED, See Interface Permission)
Request Format
POST https://api-cloud.bitmart.com/account/v1/withdraw/apply
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/account/v1/withdraw/apply
{
"currency": "USDT",
"amount": "100.000",
"destination": "To Digital Address",
"address": "0x1EE6FA5A3803608fc22a1f3F76ea9447D2E8b335",
"address_memo": ""
}
Field | Type | Required? | Description |
---|---|---|---|
currency | string | Yes | Token symbol, e.g., 'BTC' |
amount | string | Yes | The amount of currency to withdraw |
destination | string | Yes | withdrawal address |
To Digital Address =Withdraw to the digital currency address |
|||
address | string | Yes | Address (only the address added on the official website is supported) |
address_memo | string | No | 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 |
Get Deposit And Withdraw History
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.
(Authentication type:KEYED, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/account/v2/deposit-withdraw/history
Request Limit
Request Parameter
Request
curl 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 -Success |
||
4 -Cancel |
||
5 -Fail |
||
address | string | Address |
address_memo | string | Address tag |
tx_id | string | Hash record |
Get A Deposit Or Withdraw Detail
Query a single charge record
(Authentication type:KEYED, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/account/v1/deposit-withdraw/detail
Request Limit
Request Parameter
Request
curl 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 -Success |
||
4 -Cancel |
||
5 -Fail |
||
address | string | address |
address_memo | string | address tag |
tx_id | string | Hash record |
Get Margin Account Details(Isolated)
Applicable for isolated margin account inquiries
(Authentication type:KEYED, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/spot/v1/margin/isolated/account
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v1/margin/isolated/account
Field | Type | Required? | Description |
---|---|---|---|
symbol | string | No | Trading pair, like (BTC_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
For fund transfers between a margin account and spot account
(Authentication type:SIGNED, See Interface Permission)
Request Format
POST https://api-cloud.bitmart.com/spot/v1/margin/isolated/transfer
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v1/margin/isolated/transfer
{
"symbol":"BTC_USDT",
"currency":"BTC",
"amount":"1",
"side":"in"
}
Field | Type | Required? | Description |
---|---|---|---|
symbol | string | Yes | Trading pair(Like BTC_USDT) |
currency | string | Yes | Currency |
amount | string | Yes | Amount of transfers (precision: 8 decimal places) |
side | string | Yes | Transfer direction |
Yes | in =Transfer in |
||
Yes | 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
For querying the base rate of the current user
(Authentication type:KEYED, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/spot/v1/user_fee
Request Limit
Request Parameter
Request
curl 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
For the actual fee rate of the trading pairs
(Authentication type:KEYED, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/spot/v1/trade_fee
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v1/trade_fee?symbol=BTC_USDT
Field | Type | Required? | Description |
---|---|---|---|
symbol | string | Yes | Trading pair, like (BTC_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
Place Spot Order
Applicable for spot order placement
(Authentication type:SIGNED, See Interface Permission)
Request Format
POST https://api-cloud.bitmart.com/spot/v1/submit_order
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v1/submit_order
{
"symbol":"BTC_USDT",
"side":"buy",
"type":"limit",
"size":"10",
"price":"7000"
}
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 |
Place Spot Order (V2)
Applicable for spot order placement
(Authentication type:SIGNED, See Interface Permission)
Request Format
POST https://api-cloud.bitmart.com/spot/v2/submit_order
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v2/submit_order
{
"symbol":"BTC_USDT",
"side":"buy",
"type":"limit",
"size":"10",
"price":"7000"
}
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 |
||
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 |
Place Margin Order
Applicable for margin order placement
(Authentication type:SIGNED, See Interface Permission)
Request Format
POST https://api-cloud.bitmart.com/spot/v1/margin/submit_order
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v1/margin/submit_order
{
"symbol":"BTC_USDT",
"side":"buy",
"type":"limit",
"size":"10",
"price":"7000"
}
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
{
"message":"OK",
"code":1000,
"trace":"f7f74924-14da-42a6-b7f2-d3799dd9a612",
"data":{
"order_id":1223181
}
}
Field | Type | Description |
---|---|---|
order_id | long | Order ID |
Batch Order
Batch order
(Authentication type:SIGNED, See Interface Permission)
Request Format
POST https://api-cloud.bitmart.com/spot/v1/batch_orders
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v1/batch_orders
{
"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"
}
]
}
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 |
Batch Order (V2)
Batch order
(Authentication type:SIGNED, See Interface Permission)
Request Format
POST https://api-cloud.bitmart.com/spot/v2/batch_orders
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v2/batch_orders
{
"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"
}
]
}
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 |
Yes | limit =Limit order |
||
Yes | market =Market order |
||
Yes | limit_maker =PostOnly order |
||
Yes | 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
Cancel an outstanding order
(Authentication type:SIGNED, See Interface Permission)
Request Format
POST https://api-cloud.bitmart.com/spot/v2/cancel_order
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v2/cancel_order
{
"order_id":112121212
}
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 | bool | Cancel successfully=true; Cancel failed=false |
Cancel an Order (V3)
Applicable to the cancellation of a specified unfinished order
(Authentication type:SIGNED, See Interface Permission)
Request Format
POST https://api-cloud.bitmart.com/spot/v3/cancel_order
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v3/cancel_order
{
"symbol": "BTC_USDT",
"order_id": "112121212"
}
Field | Type | Required? | Description |
---|---|---|---|
symbol | string | Yes | Trading pairs(e.g. BTC_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 | bool | Cancel successfully=true; Cancel failed=false |
Cancel All Orders
Cancel all outstanding orders in the specified side for a trading pair
(Authentication type:SIGNED, See Interface Permission)
Request Format
POST https://api-cloud.bitmart.com/spot/v1/cancel_orders
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v1/cancel_orders
{
"symbol":"BTC_USDT",
"side":"buy"
}
Field | Type | Description |
---|---|---|
symbol | string | Trading pair (e.g. BTC_USDT) |
side | string | buy or 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.
Get Order Detail
Get order detail
(Authentication type:KEYED, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/spot/v1/order_detail
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v1/order_detail?order_id=1736871726781
Field | Type | Required? | Description |
---|---|---|---|
order_id | long | No | Order id |
clientOrderId | string | No | Client-defined OrderId |
Response Data
Response
{
"message":"OK",
"code":1000,
"trace":"a27c2cb5-ead4-471d-8455-1cfeda054ea6",
"data":{
"order_id":1736871726781,
"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",
"clientOrderId":"d9850c05-9091-4740-ae07-43e62153e9bd"
}
}
Field | Type | Description |
---|---|---|
order_id | long | Order ID |
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 |
||
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 |
||
clientOrderId | string | Client-defined OrderId (If the field is not defined, a random string is returned) |
Get Order Detail (V2)
Applicable query a specified order detail
(Authentication type:KEYED, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/spot/v2/order_detail
Request Limit
Request Parameter
Request
curl 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 |
Get User Order History
Get a list of user orders
(Authentication type:KEYED, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/spot/v2/orders
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v2/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 | Yes | Recent N records (value range 1-100) |
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 |
Response Data
Response
{
"message":"OK",
"code":1000,
"trace":"70e7d427-7436-4fb8-8cdd-97e1f5eadbe9",
"data":{
"current_page":1,
"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",
"clientOrderId":"d9850c05-9091-4740-ae07-43e62153e9bd"
}
]
}
}
Field | Type | Description |
---|---|---|
orders | List | Order list |
order_id | long | 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 |
||
clientOrderId | string | Client-defined OrderId (If the field is not defined, a random string is returned) |
Get User Order History (V3)
Applicable to search for order history within a certain time frame, up to 200 records
(Authentication type:KEYED, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/spot/v3/orders
Request Limit
Request Parameter
Request
curl 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) |
Get User Trade History
Get user trade history
(Authentication type:KEYED, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/spot/v1/trades
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v1/trades?symbol=BTC_USDT&limit=10&offset=1
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 | long | No | Order id |
Special Parameters for Querying Trade Record of All Orders
Field | Type | Required? | Description |
---|---|---|---|
offset | int | No | Current page, starts from 1 |
limit | int | No | Records returned per page (value range 1-100) |
Response Data
Response
{
"message":"OK",
"code":1000,
"trace":"a06a5c53-8e6f-42d6-8082-2ff4718d221c",
"data":{
"current_page":1,
"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",
"clientOrderId":"d9850c05-9091-4740-ae07-43e62153e9bd"
},
...
]
}
}
Field | Type | Description |
---|---|---|
trades | List | Order list |
detail_id | long | Trade id |
order_id | long | 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 |
clientOrderId | string | Client-defined OrderId (If the field is not defined, a random string is returned) |
Get User Trade History (V2)
Applicable for searching the trade history within a certain time frame, up to 200 records
(Authentication type:KEYED, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/spot/v2/trades
Request Limit
Request Parameter
Request
curl 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)
Applicable to isolated margin account borrowing operations
(Authentication type:SIGNED, See Interface Permission)
Request Format
POST https://api-cloud.bitmart.com/spot/v1/margin/isolated/borrow
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v1/margin/isolated/borrow
{
"symbol":"BTC_USDT",
"currency":"BTC",
"amount":"1"
}
Field | Type | Required? | Description |
---|---|---|---|
symbol | string | Yes | Borrowing trading pairs(like BTC_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)
Applicable to isolated margin account repayment operations
(Authentication type:SIGNED, See Interface Permission)
Request Format
POST https://api-cloud.bitmart.com/spot/v1/margin/isolated/repay
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v1/margin/isolated/repay
{
"symbol":"BTC_USDT",
"currency":"BTC",
"amount":"1"
}
Field | Type | Required? | Description |
---|---|---|---|
symbol | string | Yes | Repayment trading pairs(like BTC_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)
Applicable to the inquiry of borrowing records of an isolated margin account
(Authentication type:KEYED, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/spot/v1/margin/isolated/borrow_record
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v1/margin/isolated/borrow_record?symbol=BTC_USDT
Field | Type | Required? | Description |
---|---|---|---|
symbol | string | Yes | Trading pair(like BTC_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 (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)
Applicable to the inquiry of repayment records of isolated margin account
(Authentication type:KEYED, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/spot/v1/margin/isolated/repay_record
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v1/margin/isolated/repay_record?symbol=BTC_USDT
Field | Type | Required? | Description |
---|---|---|---|
symbol | string | Yes | Trading pair(like BTC_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 (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
Applicable for checking the borrowing rate and borrowing amount of trading pairs
(Authentication type:KEYED, See Interface Permission)
Request Format
GET https://api-cloud.bitmart.com/spot/v1/margin/isolated/pairs
Request Limit
Request Parameter
Request
curl https://api-cloud.bitmart.com/spot/v1/margin/isolated/pairs
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) |
WebSocket Subscription
Overview
Address
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
Request Format
{"op":"<operation>", "args":["<topic1>","<topic2>"]}
Terminology
operation: Request action, value
Subscribe=subscribe
Unsubscribe=unsubscribe
Login=login
args: Request parameter, value: channel array or parameters required for login
topic: Channel topic, composed of <channel>:<filter>
channel is composed of business/name
filter can filter data, refer to the description of each channel for details
Example: spot/ticker: BTC_USDT, which means ticker data of BTC/USDT spot trading pair
errorCode: When sending a subscription or login operation generates an error, the error code will be returned
errorMessage: When an error occurs when sending a subscription or a login operation, the error message will be returned
Successful Response Format
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>"}]"}
When return data does not contain the error_code field, it indicates success
Failed Response Format
Failed Response Format
{"event":"<operation>","errorMessage":"<error_message>","errorCode":"<error_code>"}
If the error_code field is returned, it means failure. For the reason of failure, please refer to: WebSocket error code
Stay Connected And Limit
Stay Connected
WebSocket uses the Ping/Pong mechanism to maintain the connection. Once the connection is opened, a Ping frame is sent every N seconds, and the remote endpoint will return a Pong frame to keep responding. This is an approach to stay active. It helps to keep the connection open, especially if there is a short timeout proxy on an inactive connection.
If no data is returned after connecting to WebSocket, the link will be automatically disconnected after 20s. It is recommended that the user do the following:
1.After each message is received, the user sets a timer for N seconds (N<20).
2.If the timer is triggered (no new message is received within N seconds), send a ping frame or send a string 'ping'.
3.Expect for a text string 'pong' as a response. If not received within N seconds, please issue an error or reconnect.
4.We do not actively disconnect when there is a continuous message interaction between the two parties.
The following is the data format of ping:
- Standard Ping frame
ws.send(new PingWebSocketFrame();
- Ping Text
ws.send(new TextWebSocketFrame("ping");
Connection Limit
Public Channel
Channel | limit |
---|---|
Numbers of connections per IP. | 10 |
Times of connections request per minute | 30 |
Minimum message pushing frequency | 0.5 second |
Message limit sent to the server | 100/10 seconds |
Maximum number of batch subscriptions at a time | 20 topics |
Subscription limit for each connection | 100 topics |
Private Channel
Channel | limit |
---|---|
Numbers of connections per account | 10 |
Times of connections request per minute | 30 |
Minimum message pushing frequency | 0.5 second |
Message limit sent to the server | 100/10 seconds |
Maximum number of batch subscriptions at a time | 20 topics |
Subscription limit for each connection | 100 topics |
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
python
import zlib
message = b'abcd1234'
compressed = zlib.compress(message)
decompressed = zlib.decompress(compressed).decode('UTF-8')
print(decompressed) # abcd1234
java
import java.util.zip.*;
try {
// Encode a String into bytes
String inputString = "blahblahblah";
byte[] input = inputString.getBytes("UTF-8");
// Compress the bytes
byte[] output = new byte[100];
Deflater compresser = new Deflater(true);
compresser.setInput(input);
compresser.finish();
int compressedDataLength = compresser.deflate(output);
compresser.end();
// Decompress the bytes
Inflater decompresser = new Inflater(true);
decompresser.setInput(output, 0, compressedDataLength);
byte[] result = new byte[100];
int resultLength = decompresser.inflate(result);
decompresser.end();
// Decode the bytes into a String
String outputString = new String(result, 0, resultLength, "UTF-8");
} catch(java.io.UnsupportedEncodingException ex) {
// handle
} catch (java.util.zip.DataFormatException ex) {
// handle
}
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
Example
Request
{"op": "subscribe", "args": ["spot/ticker:BTC_USDT"]}
spot/ticker
is the channel name, BTC_USDT
is the trading pair
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
}
]
}
notice: This data is displayed after decompression, Refer to Data Compression for details)
Return Parameter Description:
Parameter | 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) |
【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
Example
Request
{"op": "subscribe", "args": ["spot/kline1m:BTC_USDT"]}
spot/kline1m
is the channel name, BTC_USDT
is the trading pair
Channel List
Channel Name | Description |
---|---|
spot/kline1m | 1-min KLine Channel |
spot/kline3m | 3-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
{
"table":"spot/kline1m",
"data":[
{
"candle":[
1534141852,
"162.03",
"162.04",
"161.96",
"161.98",
"336.452694"
],
"symbol":"ETH_USDT"
}
]
}
notice: This data is displayed after decompression, Refer to Data Compression for details
Return Parameter Description:
Parameter | Type | Description |
---|---|---|
symbol | string | Trading pair, BTC_USDT |
candle | List |
KLine data |
【Public】Depth Channel
Return the depth data
Pushing Rules
- No user login required
- After subscribing, the current data will be returned directly, and then the changes will be pushed
Example
Request
{"op": "subscribe", "args": ["spot/depth5:BTC_USDT"]}
spot/depth5
is the channel name and BTC_USDT
is the trading pair
Channel List
Channel Name | Description |
---|---|
spot/depth5 | 5 Level Depth Channel |
spot/depth20 | 20 Level Depth Channel |
spot/depth50 | 50 Level Depth Channel |
Response
{
"table":"spot/depth5",
"data":[
{
"asks":[
[
"161.96",
"7.37567"
]
],
"bids":[
[
"161.94",
"4.552355"
]
],
"symbol":"ETH_USDT",
"ms_t": 1542337219120
}
]
}
notice:This data is displayed after decompression, Refer to Data Compression for details
Return Parameter Description:
Parameter | Type | Description |
---|---|---|
symbol | string | Trading pair, BTC_USDT |
asks | List |
Ask depth |
bids | List |
Bid depth |
ms_t | long | Timestamp (in millisecond) |
【Public】Trade Channel
Get the latest trade data
Pushing Rules
- No user login required
- After subscribing, the current data will be returned directly, and then the changes will be pushed
Example
Request
{"op": "subscribe", "args": ["spot/trade:BTC_USDT"]}
spot/trade
is the channel name, BTC_USDT
is the trading pair
Response
{
"table": "spot/trade",
"data": [{
"symbol": "ETH_USDT",
"price": "162.12",
"side": "buy",
"size": "11.085",
"s_t": 1542337219
}]
}
notice:This data is displayed after decompression, Refer to Data Compression for details
Return Parameter Description:
Parameter | 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) |
【Private】Login
Login Subscription Format
Request
{"op":"login","args":["<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("
Example
sign
sign=
echo -n '1589267764859#test001#bitmart.WebSocket' | openssl dgst -sha256 -hmac "6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9"
(stdin)= 3ceeb7e1b8cb165a975e28a2e2dfaca4d30b358873c0351c1a071d8c83314556
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";
If return data does not contain the error_code field, it indicates success
【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)
Example
Request
{"op": "subscribe", "args": ["spot/user/order:BTC_ USDT"]}
spot/user/order
is the channel name, BTC_USDT
is the trading pair
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"
}
notice:This data is displayed after decompression, Refer to Data Compression for details
Return Parameter Description:
Parameter | 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 | buy or sell |
type | string | limit or 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 means Maker, T means Taker |
detail_id | string | Trade id |
client_order_id | string | Client-defined OrderId |
Error Code
Restful Error Code
List of global HTTP return codes
HTTP | Description |
---|---|
404 | Not Found-The requested interface could not be found |
403 | Forbidden-No permission to access the resource (KEY may not have permission, or it may be IP restrictions) |
401 | Unauthorized-Authentication failed (there are problems with the 3 header parameters, failed) |
500 | Internal Server Error-Server exception, BitMart service problem |
Authentication Error Code
Example: httpStatus:200, body:{"code": 1000, "message": "OK", "trace": "12323-3243242-34334534-4353","data":{}}
error message | code error code | http status code |
---|---|---|
Not found | 30000 | 404 |
Header X-BM-KEY is empty | 30001 | 401 |
Header X-BM-KEY not found | 30002 | 401 |
Header X-BM-KEY has frozen | 30003 | 401 |
Header X-BM-SIGN is empty | 30004 | 401 |
Header X-BM-SIGN is wrong | 30005 | 401 |
Header X-BM-TIMESTAMP is empty | 30006 | 401 |
Header X-BM-TIMESTAMP range. Within a minute | 30007 | 401 |
Header X-BM-TIMESTAMP invalid format | 30008 | 401 |
IP is forbidden. We recommend enabling IP whitelist for API trading. After that reauth your account | 30010 | 403 |
Header X-BM-KEY over expire time | 30011 | 403 |
Header X-BM-KEY is forbidden to request it | 30012 | 403 |
Request too many requests | 30013 | 429 |
Service unavailable | 30014 | 503 |
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 |
The specified sub-account could not be found | 61003 | 400 |
Duplicate requests (such as using an existing requestNo) | 61004 | 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 |
Asset transfer between accounts is not available | 61005 | 403 |
The sub-account api only supports organization accounts | 61006 | 403 |
Method Not Allowed | 60030 | 405 |
Unsupported Media Type | 60031 | 415 |
User account not found | 60050 | 500 |
Internal Server Error | 60051 | 500 |
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 |
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 |
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 |
Questions And Answers
This is the Q&A section. If you cannot find answer to your question, please join us Telegram API Group in time.
APIKey Q&A
1. How to apply for APIKEY?
API application site: https://www.bitmart.com/api
After successful application on the website, please keep your access key, secret key and memo.
2. Can I retrieve the secret key of APIKEY?
No, you will need to create new APIKEY.
3. Is there any risk of authorizing APIKEY to a third party?
This will create some risk, and it is recommended to keep it yourself for account security.
4. Can I apply for APIKEY without binding my phone or Google?
No, you must bind more than 2 security items to apply for APIKEY.
5. When creating an APIKEY, do I have to bind an IP address?
It is not necessary. The option to bind IP when applying for APIKEY is optional, but in order to increase the security of user accounts, it is recommended to bind the IP address.
6. Will different APIKEYs in the same account return different data?
Different APIKEY data under the same account is the same.
7. How many Api Keys can I apply for in one account?
Each account can create 5 sets of Api keys, and each Api Key can be set up with 3 permissions, namely read-only, trade and withdrawal, three types of permissions.
Details:
1) Read-only permission: Read the user's own trading information, order information, account capital information, etc.
2) Trade permission: Users can place orders and cancel orders in spot and contract.
3) Withdrawal permission: The user can withdraw the balance of the wallet to the digital currency address outside the exchange.
8. How to fill information in when applying for APIKEY?
Fill in according to the prompt on the web page, and the memo can be filled in at will by the user; the secret key must be remembered, and it will be used when calling the API interface; binding IP is not required, but it is recommended for account security; API permissions can be checked based on user needs.
9. What is memo?
Memo is provided by users themselves. It will be used in the signing of the interface.
Authentication Q&A
1. What is the maximum difference between the timestamp parameter of the request interface and the time to reach the server?
Requests that differ by more than 1 minute between the timestamp and the API server time will be considered expired by the system and rejected. If there is a large time deviation between the user server and the API server, it is recommended that the user use the "Get Server Time" interface to query the API server time.
2. How to solve error "The request header "X-BM-TIMESTAMP" cannot be empty", which occurs from time to time?
First of all, it is recommended that the user print out whether the request header parameter X-BM-TIMESTAMP has a value. In addition, it is recommended that the user code be optimized. Before each request, determine whether X-BM-TIMESTAMP is empty.
3. What is the time used as the timestamp in the API?
UTC 0 timestamp。
4. Why does signature authentication always return invalid signatures?
Caused by incorrect signatures:
You can use the following SDK, the signature part has been packaged, you can directly debug and call:
If you are writing your own signature function, please refer to the following description step by step:
The request header of X-BM-SIGN is obtained by encrypting the timestamp + "#" + memo + "#" + queryString, and the secret key using the HMAC SHA256 method.
When checking, you can print out the request header information and the pre-signature string, focusing on the following points:
Whether the APIKey is correctly configured in the code
Your KEY is as follows:
API_KEY = "80618e45710812162b04892c7ee5ead4a3cc3e56";
API_SECRET = "6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9";
API_MEMO = "test001";
Please confirm that the settings are correct:
Content-Type: application/json
X-BM-KEY: 80618e45710812162b04892c7ee5ead4a3cc3e56
Check whether the string before signing conforms to the standard format, the order of all elements must be consistent, you can use the following example to compare with your string before signing:
GET
X-BM-SIGN=
echo -n '1589267764859#test001#contract_id=1&category=1' | openssl dgst -sha256 -hmac "6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9"
(stdin)= 6d5e774446448073f68e99c28ace86503451bed1fd44e43f80b9b518937c4ef1
Request:
Host: {{host}}/v1
Content-Type: application/json
X-BM-KEY: 80618e45710812162b04892c7ee5ead4a3cc3e56
X-BM-SIGN: 6d5e774446448073f68e99c28ace86503451bed1fd44e43f80b9b518937c4ef1
X-BM-TIMESTAMP: 1589267764859
GET Example: Request address is {{host}}/v1?contract_id=1&category=1, the current timestamp=1589267764859, so queryString=1589267764859#test001#contract_id=1&category=1
POST
X-BM-SIGN=
echo -n '1589267764859#test001#{"contract_id":1,"category":1,"way":1,"open_type":1,"leverage":10,"custom_id":1,"price":5000,"vol":10,"nonce":1589267764}' | openssl dgst -sha256 -hmac "6c6c98544461bbe71db2bca4c6d7fd0021e0ba9efc215f9c6ad41852df9d9df9"
(stdin)= 595a00aa2ecbd2f7e857909497e3aa8b222da6b6055411c7f4dfce0e7dc6c6ae
Request:
HOST: {{host}}/v1
Body: {"contract_id":1,"category":1,"way":1,"open_type":1,"leverage":10,"custom_id":1,"price":5000,"vol":10,"nonce":1589267764}
Content-Type: application/json
X-BM-KEY: 80618e45710812162b04892c7ee5ead4a3cc3e56
X-BM-SIGN: 595a00aa2ecbd2f7e857909497e3aa8b222da6b6055411c7f4dfce0e7dc6c6ae
X-BM-TIMESTAMP: 1589267764859
POST Example: Request address is {{host}}/v1?contract_id=1&category=1, the current timestamp=1589267764859, so queryString=1589267764859#test001#{"contract_id":1,"category":1,"way":1,"open_type":1,"leverage":10,"custom_id":1,"price":5000,"vol":10,"nonce":1589267764}
Rate Limit Q&A
1.Is there a limit to how often the API is called per second?
There are limits, specific can see the menu bar 'Rate Limit' in each interface access frequency limit.
2."why do I have to complete a CAPTCHA?" comes up on the call
This time, the IP was intercepted because it was accessed too much from a different environment and was considered an attack by the system. It is recommended that you do not share IP and that applications be accessed using a separate IP.Second, use the browser to call the interface and select 'I am Human' to submit to unrestrict as prompted on the page.
3.How is the HTTP status code 429 created?
The request interface exceeds the access frequency limit. It is recommended to reduce the access frequency.
4.Will API call interfaces be blocked if they exceed the access frequency? How long letter?
No, just reduce the access frequency.
5.Access interface error overclocking, how to solve?
Reduce the frequency of access. Each interface of the document has a frequency description. You need to lower the request frequency to the frequency description.
Interface Q&A
1. When does the K-Line start to calculate?
The start time of the K-Line interface is the UTC time, which is 8 hours different from Beijing time.
Spot Q&A
1. Why cancel the spot order will return failure?
Because when the cancellation is requested, this order may have been successfully matched.
2. How are the highest, lowest and volume calculated?
The highest price, the lowest price and the turnover are calculated according to the dimension of the last 24 hours.
The 24 hour opening price takes its value from the opening price of the K line at the last minute of the 24 hour period. That is, at 11:23:45 on July 23, 2019, the rise and fall depends on the opening price at 11:23:00 on July 22, 2019.
Contract Q&A
1. What does the request field errno mean?
This is a legacy field, please ignore it, the returned field code
shall prevail.
Contact Us
If you have any api related questions, comments or suggestions, join us Telegram API Group: (please indicate whether it is a contract interface or a spot interface), we will reply to your problem in a timely manner.