Introduction

API Introduction

Welcome to the BitV API!

This document is the only official API document of BitV. The features and services provided will be continuously updated here.

You can switch to get the API for different services by clicking the menu above, and you can also switch the language of the document by clicking the language button on the top right.

Examples of request parameters and response results are shown on the right side of the document.

Update Subscription

We will notify you in advance about API additions, updates and downgrades. We suggest you pay attention to and subscribe to our announcements to get relevant information in time.

Contact us

If you have any questions or inquiries regarding the use of the API, please refer to the Q&A for inquiries.

Quick Start

Access Preparation

To use the API, please log in to the web terminal and complete the API key application and permission configuration before developing and trading according to the details in this document.

You can create an API key by clicking here .

Each parent user can create 3 groups of API Key, and each API Key can set two kinds of permissions: read and trade.

Permissions are described as follows:

• Read permission: Read permission is used for the query interface of data, such as: order query, transaction query, etc.
• Trading permission: Trading permission is used for placing, withdrawing and transferring orders.

After successful creation, please make sure to remember the following information:

• Access Key API access key

• Secret Key The key used for signature authentication encryption (only visible when applying)

Interface Types

We provide two kinds of interfaces for users, you can choose the suitable way to check the quotes or trade according to your usage scenarios and preferences.

REST API

REST, which stands for Representational State Transfer, is a popular HTTP-based communication mechanism, where each URL represents a resource.

For one-time operations such as trading, developers are recommended to use the REST API for operations.

WebSocket API

WebSocket is a new protocol (Protocol) for HTML5. It implements full-duplex communication between client and server. A client-server connection can be established through a simple handshake, and the server can actively push information to the client according to business rules.

It is recommended that developers use the WebSocket API to obtain information such as market quotes and buying and selling depth.

Interface Authentication

Both of the above interfaces contain two types of public and private interfaces.

The public interface can be used to obtain basic information and quotation data. The public interface can be called without authentication.

The private interface can be used for trade management and account management. Each private request must be signed and authenticated using your API Key.

Access URLs

REST API

https://api.bitv.com

Websocket Feed (quotes)

wss://api.bitv.com/ws

Websocket Feed (assets and orders)

*wss://api.bitv.com/ws/v2

Signature Authentication

Signature Description

To ensure that requests are not altered, private interfaces other than public interfaces (base information, ticker data) must be signed and authenticated with your API Key to verify that parameters or parameter values have not been altered in transit.
Each API Key requires the appropriate permissions to access the corresponding interface, and each newly created API Key needs to be assigned permissions. Before using an interface, check the permission type for each interface and make sure your API Key has the appropriate permissions.

A legitimate request consists of the following components:

• Method request address: that is, access to the server address https://api.bitv.com
• API AccessId (AccessKeyId): The Access Key in the API Key you requested.
• SignatureMethod: The hash-based protocol used by the user to calculate the signature, here HmacSHA256 is used.
• SignatureVersion: The version of the signature protocol, here 2 is used.
• Timestamp: The time you sent the request (UTC time). For example: 2017-05-11T16:22:06. Including this value in the query request helps prevent third parties from intercepting your request.
• Required and Optional Parameters: Each method has a set of required and optional parameters that are used to define the API call. You can see these parameters and their meaning in the description of each method.
  • For GET requests, each method comes with its own parameters that require a signature operation.
  • For POST requests, each method’s own parameters are not signed and need to be placed in the body.
• Signature: The value resulting from the signature calculation, which is used to ensure that the signature is valid and has not been tampered with.

Signing steps

Because when using HMAC for signature computation, the result of the computation can be completely different using different content. Therefore, please normalize the request before performing the signature calculation. The following is an example of a request for order details:

The full request URL for an order detail query

https://api.bitv.com/v1/order/orders?

AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx

&SignatureMethod=HmacSHA256

&SignatureVersion=2

&Timestamp=2017-05-11T15:19:30

&order-id=1234567890

1. request method (GET or POST, GET for WebSocket), followed by the newline character “\n”

For example: GET\n

2. add the access domain name in lowercase, followed by the newline character “\n”

For example: api.bitv.com\n

3. add the path to the access method, followed by a line break “\n”

For example, to check orders:
/v1/order/orders\n

For example WebSocket v2
/ws/v2

4. URL encoding of the parameters and sorting them in ASCII order

For example, here is the original order of the request parameters and after URL encoding

AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx

order-id=1234567890

SignatureMethod=HmacSHA256

SignatureVersion=2

Timestamp=2017-05-11T15%3A19%3A30

After sorting

AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx

SignatureMethod=HmacSHA256

SignatureVersion=2

Timestamp=2017-05-11T15%3A19%3A30

order-id=1234567890

5. In the above order, connect the parameters using the character “&”

AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2017-05-11T15% 3A19%3A30&order-id=1234567890

6. compose the final string for the signature calculation as follows

GET\n

api.bitv.com\n

/v1/order/orders\n

AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2017-05-11T15% 3A19%3A30&order-id=1234567890

7. Generate a digital signature with the “request string” created in the previous step and your Secret Key

1. Use the request string from the previous step and the API private key as two parameters, call the HmacSHA256 hash function to obtain the hash value.
2. Base-64 encode this hash value to get the digital signature for this API call.

4F65x5A2bLyMWVQj3Aqp+B4w+ivaA7n5Oi2SuYtCJ9o=

8. Include the generated digital signature in your request

For Rest API:

1. Add all required authentication parameters to the path parameters of the interface call
2. URL encode the digital signature and add it to the path parameters, with the parameter name as “Signature”.

Ultimately, the API request sent to the server should look like this:

https://api.bitv.com/v1/order/orders?AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx&order-id=1234567890&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2017-05-11T15%3A19%3A30&Signature=4F65x5A2bLyMWVQj3Aqp%2BB4w%2BivaA7n5Oi2SuYtCJ9o%3D

For WebSocket interface:

1. Fill in the parameters and signature as per the required JSON format.
2. The parameters in the JSON request do not need to be URL-encoded.

For example:

` { “action”: “req”, “ch”: “auth”, “params”: { “authType”:”api”, “accessKey”: “e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx”, “signatureMethod”: “HmacSHA256”, “signatureVersion”: “2.1”, “timestamp”: “2019-09-01T18:16:16”, “signature”: “4F65x5A2bLyMWVQj3Aqp+B4w+ivaA7n5Oi2SuYtCJ9o=” } } `

Business Glossary

Trading Pairs

Trading pairs consist of a base currency and a quote currency. For example, in the trading pair BTC/USDT, BTC is the base currency, and USDT is the quote currency.

The field corresponding to the base currency is called base-currency.

The field corresponding to the quote currency is called quote-currency.

Accounts

Different businesses require different types of accounts. The account-id is a unique identifier for each business account.

The account-id can be obtained through the /v1/account/accounts interface, and the specific account type can be determined based on the account-type.

Account types include:

• Spot: Spot trading account

Order and Trade-related ID Explanation

• order-id: A unique identifier for an order.
• client-order-id: A customer-defined ID that is passed in during order placement. It corresponds to the order-id returned after a successful order placement. This ID is valid for 24 hours. Allowed characters include letters (case-sensitive), numbers, underscores (_), and dashes (-), with a maximum length of 64 characters.
• match-id: A sequential number assigned to an order during the matching process.
• trade-id: A unique identifier for a trade.

Order Types

The order type is determined by the combination of the trade direction and the order operation type. For example, “buy-market” consists of the buy direction and the market operation type.

Trade directions:

• Buy: Buy
• Sell: Sell

Order types:

• Limit: A limit order requires specifying the order price and quantity.
• Market: A market order only requires specifying the order amount or quantity, without specifying a price. The order is matched directly with the counterparty until the amount or quantity is lower than the minimum trade amount or quantity.
• Limit-maker: A limit order that can only enter the market depth as a maker. If the order would result in a match, the matching process will directly reject the order.
• IOC: Immediate or cancel. After entering the matching process, if the order cannot be immediately matched, it will be canceled (the remaining part will also be canceled after partial fulfillment).
• Stop-limit: A stop-loss or take-profit order that is set above or below the market price. The order is only officially placed in the matching queue when the trigger price is reached.

Order Status

• Submitted: Waiting for fulfillment. Orders in this status have entered the matching queue.
• Partial-filled: Partially filled. Orders in this status are in the matching queue, and a portion of the order quantity has been filled by the market, waiting for the remaining part to be filled.
• Filled: Filled. Orders in this status are not in the matching queue anymore, and the entire order quantity has been filled by the market.
• Partial-canceled: Partially filled and canceled. Orders in this status are not in the matching queue anymore. They transition from the partial-filled status, where a portion of the order quantity was filled but later canceled.
• Canceled: Canceled. Orders in this status are not in the matching queue anymore. They have not been filled and have been successfully canceled.
• Canceling: Canceling. Orders in this status are in the process of being canceled. The order needs to be removed from the matching queue to be completely canceled, so this status serves as an intermediate state.

Integration Guide

API Overview

This categorization provides a general overview, but some APIs may not follow this convention. Please refer to the corresponding API documentation based on your specific needs.

New Rate Limit Rules

• Currently, the new rate limit rules are gradually being implemented. APIs that have a separate rate limit value and are marked as “NEW” are subject to the new rate limit rules.

• The new rate limit rules adopt a frequency limit mechanism based on the UID. This means that the total frequency of requests from all API keys under the same UID to a single node cannot exceed the maximum allowed access times within a unit time period.

• Users can check the current rate limit usage and the expiration time of the time window by referring to the “X-HB-RateLimit-Requests-Remain” (remaining rate limit count) and “X-HB-RateLimit-Requests-Expire” (window expiration time) in the HTTP header. Adjust your request frequency dynamically based on this value.

Rate Limit Rules

Except for APIs that have a separate rate limit value marked as “NEW” -

• Each API Key is limited to 10 requests within 1 second.
• If an API does not require an API Key, each IP is limited to 10 requests within 1 second.

For example:

• Asset and order APIs are rate-limited based on the API Key: 10 requests per second.
• Market APIs are rate-limited based on the IP: 10 requests per second.

Request Format

All API requests are RESTful and currently support two methods: GET and POST.

• GET requests: All parameters are passed in the path parameters.
• POST requests: All parameters are sent in the request body as JSON format.

Response Format

All APIs return data in JSON format. There are slight differences in the JSON structure between v1 and v2 APIs.

v1 API response format: The top-level structure consists of four fields: status, ch, ts, and data. The first three fields represent the request status and attributes, and the actual business data is contained in the data field.

Here is an example of the response format:

{
  "status": "ok",
  "ch": "market.btcusdt.kline.1day",
  "ts": 1499223904680,
  "data": // per API response data in nested JSON object
}

v2 API response format: The top-level structure consists of three fields: code, message, and data. The first two fields represent the response code and the error message, respectively. The actual business data is contained in the data field.

Here is an example of the response format:

{
  "code": 200,
  "message": "",
  "data": // per API response data in nested JSON object
}

Data Types

This document describes the conventions for data types in the JSON format:

• string: String type, enclosed in double quotation marks (“)
• int: 32-bit integer, mainly used for status codes, sizes, counts, etc.
• long: 64-bit integer, mainly used for IDs and timestamps.
• float: Floating-point number, mainly used for amounts and prices. It is recommended to use high-precision floating-point types in your program.
• object: Object, containing a sub-object {}
• array: Array, containing multiple objects

Best Practices

Security

• Strongly recommended: When applying for an API Key, bind it to your IP address to ensure that your API Key can only be used from your own IP.
• Strongly recommended: Do not expose your API Key to anyone, including third-party software or organizations. The API Key represents your account privileges, and its exposure may result in loss of information and funds. If your API Key is compromised, please delete it promptly and create a new one.

Public

New Rate Limit Rules

• The latest rate limit rules are gradually being implemented. The interfaces with the rate limit value specifically marked are subject to the new rate limit rules.
• Users can check the current rate limit usage and the expiration time of the time window using the “X-HB-RateLimit-Requests-Remain” and “X-HB-RateLimit-Requests-Expire” fields in the HTTP header. Adjust your request frequency dynamically based on these values.
• The frequency of requests from different API Keys under the same UID to a single node must not exceed the maximum allowed access limit within a unit time.

Market Data

Obtaining Market Data

• For market data, it is recommended to use WebSocket to receive real-time data updates and cache the data in your program. WebSocket provides higher real-time performance and is not subject to rate limits.
• It is recommended not to subscribe to too many topics and currency pairs on the same WebSocket connection. Excessive data volume from the upstream provider may lead to network congestion and connection interruptions.

Obtaining Latest Trade Price

• It is recommended to subscribe to the market.$symbol.trade.detail topic via WebSocket. This topic provides tick-by-tick trade information, and the price in this data represents the latest trade price with higher real-time accuracy.

Obtaining Order Book Depth

• If you only need the best bid and ask prices (level 1) for the order book, you can subscribe to the market.$symbol.bbo topic via WebSocket. This topic will push updates when the best bid or ask price changes.
• If you need multiple levels of data and real-time accuracy is not critical, you can subscribe to the market.$symbol.depth.$type topic via WebSocket. This topic provides updates every 1 second.
• If you need multiple levels of data with high real-time accuracy, you can subscribe to the market.$symbol.mbp.$levels topic via WebSocket and send a req request. You can build and update the local order book based on the incremental updates received from this topic. The fastest update frequency for this topic is 100ms.
• It is recommended to use the Rest API (/market/depth) and WebSocket full data push (market.$symbol.depth.$type) to obtain the order book depth. When using these methods, you can deduplicate the data based on the version field (discard the smaller version). When using WebSocket incremental updates (market.$symbol.mbp.$levels), you can deduplicate the data based on the seqNum field (discard the smaller seqNum).

Obtaining Latest Trades

• When subscribing to the WebSocket trade details (market.$symbol.trade.detail) topic, it is recommended to deduplicate the data based on the tradeId field.

Order Management

Placing Orders (/v1/order/orders/place)

• It is recommended to validate the order price, quantity, and other parameters against the currency pair data returned by the /v1/common/symbols API before placing an order. This helps to avoid sending invalid order requests.
• It is recommended to include the client-order-id parameter when placing an order. Ensure that this parameter is unique for each request. The client-order-id can be used to verify the order information received via WebSocket in case the API times out or fails to respond. You can also use the /v1/order/orders/getClientOrder API to query the order details based on the client-order-id.

Search Historical Orders (/v1/order/orders)

• It is recommended to use the start-time and end-time parameters for querying historical orders. The parameter value should be a 13-digit timestamp (accurate to milliseconds). The maximum time window for querying is 48 hours (2 days). It is recommended to query hourly. The smaller the time range, the higher the timestamp accuracy, and the more efficient the query. You can iterate the query based on the timestamp of the last query.

Account Management

Asset Changes

• Use WebSocket to subscribe to both the orders#$symbol and accounts.update#${mode} topics. The orders#$symbol topic is used to receive order status changes (creation, execution, cancellation) and related trade price and quantity information. Since this topic pushes data without clearing, it has faster timeliness. You can receive asset changes related to your account using the accounts.update#${mode} topic to maintain an updated view of your account funds.

common problem

API information notification

Announcements will be issued in advance to notify you of new API additions, updates, and offline information. It is recommended that you pay attention to and subscribe to our announcements to obtain relevant information in a timely manner.

Access and signature related

Q1: How many Api Keys can a user apply for?

A: Each parent user can create 3 groups of API Keys, and each API Key can be set with two permissions: reading and trading. Each parent user can also create 200 sub-users, and each sub-user can create 3 sets of API Keys, and each API Key can be set with two permissions for reading and trading.

The following are descriptions of the two permissions:

• Read permission: read permission is used for data query interface, such as: order query, transaction query, etc.
• Transaction authority: transaction authority is used for placing orders, canceling orders, and transferring interfaces.

Q2: Why do disconnections and timeouts often occur?

A: Please check whether it belongs to the following situations:

1. If the client server is located in mainland China, it is difficult to guarantee the stability of the connection.

Q3: Why is WebSocket always disconnected?

A: The common reasons are:

1. If Pong is not replied, the WebSocket connection needs to reply Pong after receiving the Ping message sent by the server to ensure the stability of the connection.

2. Due to network reasons, the client sent a Pong message, but the server did not receive it.

3. The connection is disconnected due to network reasons.

4. It is recommended that users implement a WebSocket connection disconnection and reconnection mechanism. After ensuring that the heartbeat (Ping/Pong) message is correctly replied, if the connection is accidentally disconnected, the program can automatically reconnect.

Q4: Why does the signature verification always fail?

A: Please compare the difference between the string before signing with Secret Key and the following string

Please note the following points when comparing:

1. Signature parameters should be sorted according to ASCII code. For example, the following are the original parameters:

AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx

order-id=1234567890

SignatureMethod=HmacSHA256

SignatureVersion=2

Timestamp=2017-05-11T15%3A19%3A30

After sorting it should be:

AccessKeyId=e2xxxxxx-99xxxxxx-84xxxxxx-7xxxx

SignatureMethod=HmacSHA256

SignatureVersion=2

Timestamp=2017-05-11T15%3A19%3A30

order-id=1234567890

1. The signature string needs to be URL-encoded. for example:

• A colon : will be encoded as %3A and a space will be encoded as %20
• Timestamp needs to be formatted as YYYY-MM-DDThh:mm:ss and URL-encoded as 2017-05-11T15%3A19%3A30

1. The signature needs to be base64 encoded

2. Get request parameters need to be in the signature string

3. The time is UTC time converted to YYYY-MM-DDTHH:mm:ss

4. Check whether there is a deviation between the local time and the standard time (the deviation should be less than 1 minute)

5. When WebSocket sends a signature verification and authentication message, the message body does not need URL encoding

6. The Host in the signature should be the same as the Host in the request interface

If you use a proxy, the proxy may change the request Host, you can try to remove the proxy;

The network connection library you use may include the port in the Host, you can try to include the port in the Host used in the signature

1. Whether there are hidden special characters in Api Key and Secret Key, which will affect the signature

Q5: Why is the gateway-internal-error error returned by calling the interface?

A: Please check whether it belongs to the following situations:

1. Whether the account-id is correct or not requires the data returned by the GET /v1/account/accounts interface.

2. It may be caused by the network, please try again later.

3. Whether the format of the sent data is correct (standard JSON format is required).

4. The POST request header needs to be declared as Content-Type: application/json.

Q6: What is the reason why the call interface returns a login-required error?

A: Please check whether it belongs to the following situations:

1. The AccessKey parameter should be brought into the URL.
2. The Signature parameter should be brought into the URL.
3. Whether the account-id is correct or not is the data returned by GET /v1/account/accounts interface.
4. This error may be triggered when the request is made again after the frequency limit occurs.

Q7: What is the reason for calling the Rest interface and returning HTTP 405 error method-not-allowed?

A: This error indicates that a Rest interface that does not exist has been called. Please check whether the path of the Rest interface is accurate. Due to the settings of Nginx, the request path (Path) is case-sensitive, please strictly follow the case stated in the document.

market related

Q1: How often is the current handicap data updated?

A: The current handicap data is updated once a second, whether it is a RESTful query or a Websocket push, it is updated once a second. If you need real-time bid, sell, and price data, you can use WebSocket to subscribe to the topic market.$symbol.bbo, which will push the latest bid, sell, and price data in real time.

Q2: Will the trading volume of the 24-hour market interface (/market/detail) data interface experience negative growth?

A: The transaction volume and transaction amount in the /market/detail interface are 24-hour rolling data (the size of the translation window is 24 hours), and the cumulative transaction volume and transaction amount in the latter window may be smaller than the previous window.

Q3: How to get the latest transaction price?

A: It is recommended to use the REST API GET /market/trade interface to request the latest transaction, or use WebSocket to subscribe to the market.$symbol.trade.detail topic, and obtain it according to the price in the returned data.

Q4: When is the K-line calculated?

A: The K-line period is calculated based on Singapore time. For example, the starting period of the daily K-line is from 0:00 Singapore time to 0:00 Singapore time the next day.

Transaction related

Q1: What is account-id?

A: account-id corresponds to the ID of different business accounts of the user, which can be obtained through the /v1/account/accounts interface, and specific accounts are distinguished according to account-type.

Account types include:

• spot spot account

Q2: What is client-order-id?

A: The client-order-id is a parameter of the order request identification, the type is a string, and the length is 64. This id is generated by the user and is valid within 24 hours.

Q3: How to obtain the order quantity, amount, decimal limit, precision information?

A: You can use the Rest API GET /v1/common/symbols to obtain relevant currency pair information. When placing an order, pay attention to the difference between the minimum order quantity and the minimum order amount.

Common return errors are as follows:

• order-value-min-error: The order amount is less than the minimum transaction amount
• order-orderprice-precision-error : limit order price precision error
• order-orderamount-precision-error : Order quantity precision error
• order-limitorder-price-max-error : The limit order price is higher than the limit price threshold
• order-limitorder-price-min-error : The limit order price is lower than the limit price threshold
• order-limitorder-amount-max-error : The limit order amount is higher than the limit price threshold
• order-limitorder-amount-min-error : The limit order quantity is lower than the limit price threshold

Q4: Why is the balance insufficient when placing an order again after receiving the message that the order has been successfully filled?

A: In order to ensure the timely delivery of orders and low latency, the result of order push is pushed directly after matching. At this time, the order may not have completed the liquidation of assets.

It is recommended to use the following methods to ensure that funds can be placed correctly:

1. Combined with the asset push topic accounts, receive asset change messages synchronously to ensure that funds have been cleared.

2. When receiving the order push message, use the Rest interface to call the account balance to verify whether the account funds are sufficient.

3. Keep a relatively sufficient fund balance in the account.

Q5: What is the difference between filled-fees and filled-points in the matching results?

A: There are two types of transaction fees in matchmaking transactions: ordinary fees and deductible fees, and the two types will not exist at the same time.

1. Ordinary handling fee means that the deduction is not enabled at the time of the transaction, and the original currency is used for the deduction of the handling fee. For example: when purchasing BTC under the BTCUSDT currency pair, the filled-fees field is not empty, indicating that the normal handling fee has been deducted, and the unit is BTC.

2. The deduction of handling fee means that when the transaction is completed, the deduction is turned on, and the deduction asset is used as the deduction of the handling fee. For example, when purchasing BTC under the BTCUSDT currency pair, when the deduction assets are sufficient, filled-fees is empty, and filled-points is not empty, indicating that the deduction assets are deducted as a handling fee. The deduction unit needs to refer to the fee-deduct-currency field

Q6: What is the difference between match-id and trade-id in the matching results?

A: match-id indicates the sequence number of the order in matching, and trade-id indicates the sequence number at the time of transaction. A match-id may have multiple trade-ids (at the time of transaction), or may not have trade-id (creating order, canceling Order)

Q7: Why does placing an order based on the price of buying one or selling one in the current market trigger an order limit error?

A: Currently, there is price limit protection based on the latest transaction price. For coins with poor liquidity, placing an order based on market data may trigger price limit protection. It is recommended to place an order based on the transaction price + handicap data information pushed by ws

basic information

Introduction

The basic information Rest interface provides public reference information such as market status, transaction pair information, currency information, currency chain information, and server timestamp.

Get all trading pairs

This interface returns all supported trading pairs.

curl "https://api.bitv.com/v1/common/symbols"

HTTP requests

• GET /v1/common/symbols

Request parameters

This interface does not accept any parameters.

Responses:

{
     "status": "ok",
     "data": [
         {
             "base-currency": "btc",
             "quote-currency": "usdt",
             "price-precision": 2,
             "amount-precision": 6,
             "symbol-partition": "main",
             "symbol": "btcusdt",
             "state": "online",
             "value-precision": 8,
             "min-order-amt": 0.0001,
             "max-order-amt": 1000,
             "min-order-value": 5,
             "limit-order-min-order-amt": 0.0001,
             "limit-order-max-order-amt": 1000,
             "sell-market-min-order-amt": 0.0001,
             "sell-market-max-order-amt": 100,
             "buy-market-max-order-value": 1000000,
             "api-trading": "enabled",
             "limit-order-max-buy-amt": 50,
             "limit-order-max-sell-amt": 50,
             "buy-limit-must-less-than": 1.3,
             "sell-limit-must-greater-than": 0.7,
             "market-sell-order-rate-must-less-than": 0.05,
             "market-buy-order-rate-must-less-than": 0.05,
             "max-order-value": 3000000,
             "tags": ""
         },
      …
     ]
}

return fields

Get all currencies

This interface returns all supported currencies.

curl "https://api.bitv.com/v1/common/currencys"

HTTP requests

• GET /v1/common/currencys

Request parameters

This interface does not accept any parameters.

Response:

  {
    "status": "ok",
     "data": [
       "usdt",
       "eth",
       "etc"
     ]
  }

return fields

APIv2 coin chain reference information

This node is used to query the static reference information (public data) of each currency and its blockchain

HTTP requests

• GET /v2/reference/currencies

curl "https://api.bitv.com/v2/reference/currencies?currency=usdt"

Request parameters

Response:

{
     "code":200,
     "data":[
         {
             "chains":[
                 {
                     "chain": "trc20usdt",
                     "displayName": "",
                     "fullName":"",
                     "baseChain": "TRX",
                     "baseChainProtocol": "TRC20",
                     "isDynamic": false,
                     "depositStatus": "allowed",
                     "maxTransactFeeWithdraw": "1.00000000",
                     "maxWithdrawAmt": "280000.00000000",
                     "minDepositAmt": "100",
                     "minTransactFeeWithdraw": "0.10000000",
                     "minWithdrawAmt": "0.01",
                     "numOfConfirmations": 999,
                     "numOfFastConfirmations": 999,
                     "withdrawFeeType": "circulated",
                     "withdrawPrecision": 5,
                     "withdrawQuotaPerDay": "280000.00000000",
                     "withdrawStatus": "allowed",
                     "transactFeeWithdraw":"",
                     "addrWithTag": false,
                     "addrDepositTag": false
                 },
                 {
                     "chain": "usdt",
                     "displayName": "",
                     "fullName":"",
                     "baseChain": "BTC",
                     "baseChainProtocol": "OMNI",
                     "isDynamic": false,
                     "depositStatus": "allowed",
                     "maxWithdrawAmt": "19000.00000000",
                     "minDepositAmt": "0.0001",
                     "minWithdrawAmt": "2",
                     "numOfConfirmations": 30,
                     "numOfFastConfirmations": 15,
                     "transactFeeRateWithdraw": "0.00100000",
                     "withdrawFeeType": "ratio",
                     "withdrawPrecision": 7,
                     "withdrawQuotaPerDay": "90000.00000000",
                     "withdrawStatus": "allowed",
                     "transactFeeWithdraw":"",
                     "addrWithTag": false,
                     "addrDepositTag": false
                 },
                 {
                     "chain": "usdterc20",
                     "displayName": "",
                     "fullName":"",
                     "baseChain": "ETH",
                     "baseChainProtocol": "ERC20",
                     "isDynamic": false,
                     "depositStatus": "allowed",
                     "maxWithdrawAmt": "18000.00000000",
                     "minDepositAmt": "100",
                     "minWithdrawAmt": "1",
                     "numOfConfirmations": 999,
                     "numOfFastConfirmations": 999,
                     "transactFeeWithdraw": "0.10000000",
                     "withdrawFeeType": "fixed",
                     "withdrawPrecision": 6,
                     "withdrawQuotaPerDay": "180000.00000000",
                     "withdrawStatus": "allowed",
                     "transactFeeWithdraw":"",
                     "addrWithTag": false,
                     "addrDepositTag": false
                 }
             ],
             "currency": "usdt",
             "assetType": 1,
             "instStatus": "normal"
         }
         ]
}

Response data

status code

Get the current system timestamp

This interface returns the current system timestamp, that is, the total milliseconds from UTC January 1, 1970 0:00:00:00 milliseconds to the present.

curl "https://api.bitv.com/v1/common/timestamp"

HTTP requests

• GET /v1/common/timestamp

Request parameters

This interface does not accept any parameters.

Response:

  {
    "status": "ok",
    "data": 1494900087022
  }

market data

Introduction

The market data interface provides market data such as various K-lines, depth and latest transaction records.

The following are the error codes, error messages and descriptions returned by the market data interface.

K-line data (candle chart)

This interface returns historical K-line data.

curl "https://api.bitv.com/market/history/kline?period=1day&size=200&symbol=btcusdt"

HTTP requests

• GET /market/history/kline

Request parameters

Response:

{
    "ch": "market.btcusdt.kline.1day",
    "status": "ok",
    "ts": 1761127929978,
    "data":[
       {
         "id": 1499184000,
         "amount": 37593.0266,
         "count": 0,
         "open": 1935.2000,
         "close": 1879.0000,
         "low": 1856.0000,
         "high": 1940.0000,
         "vol": 71031537.97866500
       }
    ]
}

Response data

Aggregation Quotes (Ticker)

This interface obtains ticker information and provides transaction aggregation information in the last 24 hours.

curl "https://api.bitv.com/market/detail/merged?symbol=ethusdt"

HTTP requests

• GET /market/detail/merged

Request parameters

Response:

{
    "ch": "market.ethhkd.detail.merged",
    "status": "ok",
    "ts": 1761185653396,
    "tick": {
       "id": 1499225271,
       "version":5104471,
       "close": 1885.0000,
       "open": 1960.0000,
       "high": 1985.0000,
       "low": 1856.0000,
       "amount":81486.2926,
       "count": 42122,
       "vol":157052744.85708200,
       "ask":[1885.0000,21.8804],
       "bid": [1884.0000,1.6702]
    }
}

Response data

Depth of Market Data

This interface returns the current market depth data for the specified trading pair.

curl "https://api.bitv.com/market/depth?symbol=btcusdt&type=step2"

HTTP requests

• GET /market/depth

Request parameters

Description of each value for parameter type

Response:

{
    "ch": "market.ethhkd.depth.step2",
    "status": "ok",
    "ts": 1761186823791,
    "tick": {
       "version": 31615843081,
       "ts": 1489464585407,
       "bids": [
         [7964, 0.0678], // [price, size]
         [7963, 0.9162],
         [7961, 0.1],
         [7960, 12.8898],
         [7958, 1.2],
         ...
       ],
       "asks": [
         [7979, 0.0736],
         [7980, 1.0292],
         [7981, 5.5652],
         [7986, 0.2416],
         [7990, 1.9970],
         ...
       ]
     }
}

Response data

Recent market transaction records

This interface returns the latest transaction record of the specified trading pair.

curl "https://api.bitv.com/market/trade?symbol=ethusdt"

HTTP requests

• GET /market/trade

Request parameters

Response:

{
    "ch": "market.ethhkd.trade.detail",
    "status": "ok",
    "ts": 1761187323300,
    "tick": {
         "id": 600848670,
         "ts": 1489464451000,
         "data": [
           {
             "id": 600848670,
             "trade-id": 102043494568,
             "price": 7962.62,
             "amount": 0.0122,
             "direction": "buy",
             "ts": 1489464451000
           }
         ]
    }
}

Response data

Get recent transaction records

This interface returns all recent transaction records of the specified trading pair.

curl "https://api.bitv.com/market/history/trade?symbol=ethusdt&size=2"

HTTP requests

• GET /market/history/trade

Request parameters

Response:

{
    "ch": "market.ethhkd.trade.detail",
    "status": "ok",
    "ts": 1761187576005,
    "data": [
        {
           "id": 31618787514,
           "ts":1544390317905,
           "data":[
              {
                 "amount":9.000000000000000000,
                 "ts":1544390317905,
                 "trade-id": 102043483472,
                 "id":3161878751418918529341,
                 "price": 94.6900000000000000000,
                 "direction": "sell"
              },
              {
                 "amount":73.771000000000000000,
                 "ts":1544390317905,
                 "trade-id": 102043483473
                 "id":3161878751418918532514,
                 "price": 94.6600000000000000000,
                 "direction": "sell"
              }
           ]
        },
        {
           "id":31618776989,
           "ts":1544390311353,
           "data":[
              {
                 "amount": 1.0000000000000000000,
                 "ts":1544390311353,
                 "trade-id": 102043494568,
                 "id":3161877698918918522622,
                 "price":94.710000000000000000,
                 "direction": "buy"
              }
           ]
        }
    ]
}

Response data

Last 24 hours market data

This interface returns the summary of market data in the last 24 hours.

curl "https://api.bitv.com/market/detail?symbol=ethusdt"

HTTP requests

• GET /market/detail

Request parameters

Response:

{
    "ch": "market.ethhkd.detail",
    "status": "ok",
    "ts": 1761188787410,
    "tick": {
        "amount":613071.438479561,
        "open":86.21,
        "close": 94.35,
        "high": 98.7,
        "id": 31619471534,
        "count": 138909,
        "low": 84.63,
        "version":31619471534,
        "vol":5.6617373443873316E7
    }
}

Response data

Account related

Introduction

The account-related interface provides functions such as account, balance, history query and asset transfer.

The following are the error codes, error messages and descriptions returned by account-related interfaces.

account information

API Key Permission: Read
Frequency limit value (NEW): 100 times/2s

Query all account ID account-id and related information of the current user

HTTP requests

• GET /v1/account/accounts

Request parameters

none

Response:

{
   "status": "ok",
   "data": [
     {
       "id": 100001,
       "type": "spot",
       "state": "working"
     }
   ]
}

Response data

Account Balance

API Key Permission: Read
Frequency limit value (NEW): 100 times/2s

Query the balance of the specified account, the following accounts are supported:

spot: spot account

HTTP requests

• GET /v1/account/accounts/{account-id}/balance

Request parameters

Response:

{
   "status": "ok",
   "data": {
     "id": 100009,
     "type": "spot",
     "state": "working",
     "list": [
       {
         "currency": "usdt",
         "type": "trade",
         "balance": "5007.4362812650",
         "available": "0",
         "debt": "0",
         "seq-num": "0"
       },
       {
         "currency": "usdt",
         "type": "frozen",
         "balance": "348.11999203300",
         "available": "0",
         "debt": "0",
         "seq-num": "0"
       }
     ]
   }
}

Response data

list field description:

Account History

API Key Permission: Read
Frequency limit value (NEW): 5 times/2s

This node returns the account history based on the user account ID.

###HTTP Request

• GET /v1/account/history

Request parameters

Response:

{
     "status": "ok",
     "data": [
         {
             "account-id": 5260185,
             "currency": "btc",
             "transact-amt": "0.002393000000000000",
             "transact-type": "transfer",
             "record-id": 89373333576,
             "avail-balance": "0.002393000000000000",
             "acct-balance": "0.002393000000000000",
             "transact-time": 1571393524526
         },
         {
             "account-id": 5260185,
             "currency": "btc",
             "transact-amt": "-0.002393000000000000",
             "transact-type": "transfer",
             "record-id": 89373382631,
             "avail-balance": "0E-18",
             "acct-balance": "0E-18",
             "transact-time": 1571393578496
         }
     ]
}

Response data

Spot Trading

Introduction

The spot trading interface provides functions such as order placement, order cancellation, order query, transaction query, and commission rate query.

place an order

API Key Permissions: Transactions Frequency limit value; 100 times/2s

Send a new order for matching.

HTTP requests

• POST /v1/order/orders/place

Request:

{
   "account-id": "100009",
   "amount": "10.1",
   "price": "100.1",
   "source": "api",
   "symbol": "ethusdt",
   "type": "buy-limit",
   "client-order-id": "a0001"
}

Request parameters

Response:

{
   "status": "ok",
   "data": "59378"
}

Response data

The returned master data object is a string corresponding to the order number.

If the client order ID is reused (within 24 hours), the node will return an error message invalid.client.order.id.

Batch order

API Key Permissions: Transaction
Frequency limit (NEW): 50 times/2s

A batch of up to 10 orders

HTTP requests

• POST /v1/order/batch-orders

Request:

[
{
     "account-id": "123456",
     "price": "7801",
     "amount": "0.001",
     "symbol": "btcusdt",
     "type": "sell-limit",
     "client-order-id": "c1"
},
{
     "account-id": "123456",
     "price": "7802",
     "amount": "0.001",
     "symbol": "btcusdt",
     "type": "sell-limit",
     "client-order-id": "d2"
}
]

Request parameters

Response:

{
     "status": "ok",
     "data": [
         {
             "order-id": 61713400772,
             "client-order-id": "c1"
         },
         {
             "order-id": 61713400940,
             "client-order-id": "d2"
         }
     ]
}

Response data

If the client order ID is reused (within 24 hours), the node returns the order ID and client order ID of the previous order.

Cancel order

API Key Permissions: Transaction
Frequency limit value (NEW): 100 times/2s

This interface sends a request to cancel an order.

HTTP requests

• POST /v1/order/orders/{order-id}/submitcancel

Request parameters

Success response:

{
   "status": "ok",
   "data": "59378"
}

Response data

The returned master data object is a string corresponding to the order number.

error code

Failure response:

{
   "status": "error",
   "err-code": "order-orderstate-error",
   "err-msg": "Order status error",
   "order-state":-1 // current order state
}

In the returned field list, the possible values of order-state include -

Cancel order (based on client order ID)

API Key Permissions: Transaction
Frequency limit value (NEW): 100 times/2s

This interface sends a request to cancel an order.

HTTP requests

• POST /v1/order/orders/submitCancelClientOrder

Request:

{
   "client-order-id": "a0001"
}

Request parameters

Response:

{
   "status": "ok",
   "data": "10"
}

Response data

Query current unfilled orders

API Key Permission: Read
Frequency limit value (NEW): 50 times/2s

Query the orders that have been submitted but have not been fully executed or canceled.

HTTP requests

• GET /v1/order/openOrders

Request:

{
    "account-id": "100009",
    "symbol": "ethusdt",
    "side": "buy"
}

Request parameters

Response:

{
   "status": "ok",
   "data": [
     {
       "id": 5454937,
       "symbol": "ethusdt",
       "account-id": 30925,
       "amount": "1.0000000000000000000",
       "price": "0.453000000000000000",
       "created-at": 1530604762277,
       "type": "sell-limit",
       "filled-amount": "0.0",
       "filled-cash-amount": "0.0",
       "filled-fees": "0.0",
       "source": "web",
       "client-order-id": "",
       "state": "submitted"
     }
   ]
}

Response data

Cancel orders in batches (open orders)

API Key Permissions: Transaction
Frequency limit value (NEW): 50 times/2s

This interface sends a request to cancel orders in batches.

HTTP requests

• POST /v1/order/orders/batchCancelOpenOrders

Request parameters

Response:

{
   "status": "ok",
   "data": {
     "success-count": 2,
     "failed-count": 0,
     "next-id": 5454600
   }
}

Response data

Cancel orders in bulk

API Key Permissions: Transaction
Frequency limit value (NEW): 50 times/2s

This interface sends cancellation requests for multiple orders (based on id) at the same time.

HTTP requests

• POST /v1/order/orders/batchcancel

Request:

{
   "client-order-ids": [
    "5983466", "5722939", "5721027", "5719487"
   ]
}

Request parameters

Response:

{
     "status": "ok",
     "data": {
         "success": [
             "5983466"
         ],
         "failed": [
             {
               "err-msg": "Incorrect order state",
               "order-state": 7,
               "order-id": "",
               "err-code": "order-orderstate-error",
               "client-order-id": "first"
             },
             {
               "err-msg": "Incorrect order state",
               "order-state": 7,
               "order-id": "",
               "err-code": "order-orderstate-error",
               "client-order-id": "second"
             },
             {
               "err-msg": "The record is not found.",
               "order-id": "",
               "err-code": "base-not-found",
               "client-order-id": "third"
             }
           ]
     }
}

Response data

Failed order list:

Possible values for order-state:

Query order details

API Key Permission: Read
Frequency limit value (NEW): 50 times/2s

This interface returns the latest status and details of the specified order. Orders created through the API cannot be queried after being canceled for more than 2 hours.

HTTP requests

• GET /v1/order/orders/{order-id}

Request parameters

Response:

{  
  "status": "ok",
  "data": 
  {
    "id": 59378,
    "symbol": "ethusdt",
    "account-id": 100009,
    "amount": "10.1000000000",
    "price": "100.1000000000",
    "created-at": 1494901162595,
    "type": "buy-limit",
    "field-amount": "10.1000000000",
    "field-cash-amount": "1011.0100000000",
    "field-fees": "0.0202000000",
    "finished-at": 1494901400468,
    "source": "api",
    "state": "filled",
    "canceled-at": 0,
    "client-order-id": ""
  }
}

Response data

Query order details (based on client order ID)

API Key Permission: Read
Frequency limit value (NEW): 50 times/2s

This interface returns the latest order status and details of the specified user-defined order number (within 24 hours). Orders created through the API cannot be queried after being canceled for more than 2 hours.

HTTP requests

• GET /v1/order/orders/getClientOrder

Request parameters

Response:

{  
  "status": "ok",
  "data": 
  {
    "id": 59378,
    "symbol": "ethusdt",
    "account-id": 100009,
    "amount": "10.1000000000",
    "price": "100.1000000000",
    "created-at": 1494901162595,
    "type": "buy-limit",
    "field-amount": "10.1000000000",
    "field-cash-amount": "1011.0100000000",
    "field-fees": "0.0202000000",
    "finished-at": 1494901400468,
    "source": "api",
    "state": "filled",
    "canceled-at": 0,
    "client-order-id": ""
  }
}

Response data

If the client order ID does not exist, the following error message will be returned { “status”: “error”, “err-code”: “base-record-invalid”, “err-msg”: “record invalid”, “data”: null }

transaction details

API Key Permission: Read
Frequency limit value (NEW): 50 times/2s

This interface returns the transaction details of the specified order.

HTTP requests

• GET /v1/order/orders/{order-id}/matchresults

Request parameters

Response:

{  
  "status": "ok",
  "data": [
    {
      "id": 29553,
      "order-id": 59378,
      "match-id": 59335,
      "trade-id": 100282808529,
      "symbol": "ethusdt",
      "type": "buy-limit",
      "source": "api",
      "price": "100.1000000000",
      "filled-amount": "9.1155000000",
      "filled-fees": "0.0182310000",
      "created-at": 1494901400435,
      "role": "maker",
      "filled-points": "0.0",
      "fee-deduct-currency": "",
      "fee-currency": "usdt",
      "fee-deduct-state": "done"
    }
    ...
  ]
}

Response data

Note:

• The transaction rebate amount in filled-fees may not arrive in real time.
  

Search history orders

API Key Permission: Read
Frequency limit value (NEW): 50 times/2s

This interface queries historical orders based on search conditions. Orders created through the API cannot be queried after being canceled for more than 2 hours.

Users can choose to query historical orders by “time range” instead of the original query method of “date range”.

• If the user fills in start-time AND/OR end-time to query historical orders, the server will query and return according to the “time range” specified by the user, and ignore the start-date/end-date parameters. The query window size of this method is limited to a maximum of 48 hours, and the window translation range is the last 180 days.

• If the user does not fill in the start-time/end-time parameters, but fills in start-date AND/OR end-date to query historical orders, the server will query and return according to the “date range” specified by the user. The query window size of this method is limited to a maximum of 2 days, and the window translation range is the last 180 days.

• If the user neither fills in the start-time/end-time parameter nor the start-date/end-date parameter, the server will default to the current time as the end-time and return the historical orders within the last 48 hours.

It is recommended that users query historical orders by “time range”.

HTTP requests

• GET /v1/order/orders

Request parameters

Response:

{  
  "status": "ok",
  "data": [
    {
      "id": 59378,
      "symbol": "ethusdt",
      "account-id": 100009,
      "client-order-id": "",
      "amount": "10.1000000000",
      "price": "100.1000000000",
      "created-at": 1494901162595,
      "type": "buy-limit",
      "field-amount": "10.1000000000",
      "field-cash-amount": "1011.0100000000",
      "field-fees": "0.0202000000",
      "finished-at": 1494901400468,
      "source": "api",
      "state": "filled",
      "canceled-at": 0
    }
    ...
  ]
}

Response data

Error codes related to start-date and end-date:

Search historical orders within the last 48 hours

API Key Permission: Read
Frequency limit value (NEW): 20 times/2s

This interface queries historical orders within the last 48 hours based on search criteria. Orders created through the API cannot be queried after being canceled for more than 2 hours.

HTTP requests

• GET /v1/order/history

Request:

{
    "symbol": "btcusdt",
    "start-time": "1556417645419",
    "end-time": "1556533539282",
    "direct": "prev",
    "size": "10"
}

Request parameters

Response:

{
    "status": "ok",
    "data": [
        {
            "id": 31215214553,
            "symbol": "btcusdt",
            "account-id": 4717043,
            "client-order-id": "",
            "amount": "1.000000000000000000",
            "price": "1.000000000000000000",
            "created-at": 1556533539282,
            "type": "buy-limit",
            "field-amount": "0.0",
            "field-cash-amount": "0.0",
            "field-fees": "0.0",
            "finished-at": 1556533568953,
            "source": "web",
            "state": "canceled",
            "canceled-at": 1556533568911
        }
    ]
}

Response data

Current and historical transactions

API Key Permission: Read
Frequency limit value (NEW): 20 times/2s

This interface queries current and historical transaction records based on search criteria.

HTTP requests

• GET /v1/order/matchresults

Request parameters

Response:

{  
  "data": [
    {
      "id": 29553,
      "order-id": 59378,
      "match-id": 59335,
      "symbol": "ethusdt",
      "type": "buy-limit",
      "source": "api",
      "price": "100.1000000000",
      "filled-amount": "9.1155000000",
      "filled-fees": "0.0182310000",
      "created-at": 1494901400435,
      "trade-id": 100282808529,
      "role": taker,
      "filled-points": "0.0",
      "fee-currency": "eth",
      "fee-deduct-state": "done",
      "fee-deduct-currency": ""
    }
    ...
  ]
}

Response data

Note:

• The transaction rebate amount in filled-fees may not arrive in real time;
  

  start-date, end-date related error codes

Websocket market data

Introduction

Access URL

Quotation request address

wss://api.bitv.com/ws

data compression

All data returned by the WebSocket market interface is compressed by GZIP, and the client needs to decompress it after receiving the data.

Heartbeat message

{"ping": 1492420473027}

When the user’s Websocket client connects to the Websocket server, the server will periodically (currently set to 5 seconds) send a ping message to it and include an integer value.

{"pong": 1492420473027}

When the user’s Websocket client receives this heartbeat message, it should return a pong message containing the same integer value.

Subscribe to topics

Sub request:

{
   "sub": "market.btcusdt.kline.1min",
   "id": "id1"
}

After successfully establishing a connection to the Websocket server, the Websocket client sends a request to subscribe to a specific topic:

{ “sub”: “topic to sub”, “id”: “id generate by client” }

Sub response:

{
   "id": "id1",
   "status": "ok",
   "subbed": "market.btcusdt.kline.1min",
   "ts": 1489474081631
}

After successfully subscribing, the Websocket client will receive an acknowledgment.

After that, once the subscribed topic is updated, the Websocket client will receive the update message (push) pushed by the server.

unsubscribe

UnSub request:

{
   "unsub": "market.btcusdt.trade.detail",
   "id": "id4"
}

The format for unsubscribing is as follows:

{ “unsub”: “topic to unsub”, “id”: “id generate by client” }

UnSub response:

{
   "id": "id4",
   "status": "ok",
   "unsubbed": "market.btcusdt.trade.detail",
   "ts": 1494326028889
}

Successful unsubscribe confirmation.

request data

The Websocket server also supports one-time request data (pull).

The format of a one-time request is as follows:

{ “req”: “topic to req”, “id”: “id generate by client” }

For the specific format of the data returned at one time, see each topic.

Frequency Limit

Data request (req) frequency limit rules

Every two requests for a single connection cannot be less than 100ms.

error code

The following are the error codes, error messages and descriptions of the WebSocket market interface.

K line data

Topic Subscription

Once the K-line data is generated, the Websocket server will push it to the client through this subscription topic interface:

market.$symbol$.kline.$period$

Subscription Request

{
   "sub": "market.ethbtc.kline.1min",
   "id": "id1"
}

parameters

Response

{
  "id": "id1",
  "status": "ok",
  "subbed": "market.ethbtc.kline.1min",
  "ts": 1489474081631 //system response time
}

Update example

{
  "ch": "market.ethbtc.kline.1min",
  "ts": 1489474082831, //system update time
  "tick": {
    "id": 1489464480,
    "amount": 0.0,
    "count": 0,
    "open": 7962.62,
    "close": 7962.62,
    "low": 7962.62,
    "high": 7962.62,
    "vol": 0.0
  }
}

Data update field list

Data Request

To obtain K-line data at one time by request, the following parameters need to be provided additionally: (Up to 300 items can be returned each time)

{
   "req": "market.$symbol.kline.$period",
   "id": "id generated by client",
   "from": "from time in epoch seconds",
   "to": "to time in epoch seconds"
}

Depth of market market data

This topic sends the latest Depth of Market snapshot. The snapshot frequency is 1 time per second.

Topic Subscription

market.$symbol.depth.$type

Subscribe request

{
   "sub": "market.btcusdt.depth.step0",
   "id": "id1"
}

parameters

“type” merge depth type

When the type value is ‘step0’, the default depth is 150 steps; When the type value is ‘step1’, ‘step2’, ‘step3’, ‘step4’, ‘step5’, the default depth is 20 steps.

Response

{
  "id": "id1",
  "status": "ok",
  "subbed": "market.btcusdt.depth.step0",
  "ts": 1489474081631 //system response time
}

Update example

{
  "ch": "market.htusdt.depth.step0",
  "ts": 1572362902027, //system update time
  "tick": {
    "bids": [
      [3.7721, 344.86],// [price, size]
      [3.7709, 46.66] 
    ],
    "asks": [
      [3.7745, 15.44],
      [3.7746, 70.52]
    ],
    "version": 100434317651,
    "ts": 1572362902012 //quote time
  }
}

Data update field list

Data Request

Support data request method to obtain market depth data at one time:

{
   "req": "market.btcusdt.depth.step0",
   "id": "id10"
}

Market depth MBP market data (incremental push)

Users can subscribe to this channel to receive the incremental data push of the latest in-depth market Market By Price (MBP); at the same time, this channel supports users to request full data in the form of req.

Suggested downstream data processing methods:
1) Subscribe to incremental data and start caching;
2) Request the full amount of data (equal number of gears) and align with the prevSeqNum in the buffered incremental data according to the seqNum of the full amount of message;
3) Start continuous incremental data reception and calculation, construct and continuously update the MBP order book;
4) The prevSeqNum of each incremental data must be consistent with the seqNum of the previous incremental data, otherwise it means that there is incremental data loss, and the full amount of data must be reacquired and aligned;
5) If the incremental data received includes a new price gear, the price gear must be inserted into the appropriate position in the MBP order book;
6) If the incremental data received includes an existing price gear, but the size is different, the size of the price gear in the MBP order book must be replaced;
7) If the size of a certain price gear in the incremental data is 0, the price gear must be deleted from the MBP order book;
8) If an update of two or more price levels is received in a single piece of incremental data, these price levels must be updated in the MBP order book at the same time.

Currently only supports the push of 5-file/20-file MBP step-by-step increments and 150-file MBP snapshot increments, the difference between the two is -
1) The depth is different;
2) 5 files/20 files are incremental MBP quotations one by one, and 150 files are 100 millisecond timed snapshot incremental MBP quotations;
3) When only one-sided market changes occur in the 5-level/20-level order book, the incremental push only includes unilateral market updates. For example, the push message contains the array of asks, but not the array of bids;

{
    "ch": "market.btcusdt.mbp.5",
    "ts": 1573199608679,
    "tick": {
        "seqNum": 100020146795,
        "prevSeqNum": 100020146794,
        "asks": [
            [645.140000000000000000, 26.755973959140651643]
        ]
    }
}

When the 150-level order book only has a unilateral market change, the incremental push includes a bilateral market update, but one side of the market is empty, for example, the push message contains the update of the array asks and also includes an empty array of bids;

{
    "ch":"market.btcusdt.mbp.150",
    "ts":1573199608679,
    "tick":{
        "seqNum":100020146795,
        "prevSeqNum":100020146794,
        "bids":[ ],
        "asks":[
            [645.14,26.75597395914065]
        ]
    }
}

In the future, the data behavior of the 150-level incremental push will be consistent with that of the 5-level/20-level increment, that is, when the unilateral market depth changes, the push message will not include the other side’s market depth;
4) When the 150 order books have not changed within the 100 millisecond interval, the incremental push contains bids and asks empty arrays;

{
    "ch":"market.zecusdt.mbp.150",
    "ts":1585074391470,
    "tick":{
        "seqNum":100772868478,
        "prevSeqNum":100772868476,
        "bids":[  ],
        "asks":[  ]
    }
}

However, the 5-level/20-level MBP is incremented one by one, and no data is pushed when the order book does not change;
In the future, the data behavior of 150 increments will be consistent with that of 5 increments, that is, when the order book has not changed, empty messages will no longer be pushed;
5) Only some trading pairs (btcusdt, ethusdt, xrpusdt, eosusdt, ltcusdt, etcusdt, adausdt, dashusdt, bsvusdt) are supported in the 5-level/20-level incremental market, and 150-level snapshot increments support all trading pairs.

The REQ channel supports the acquisition of full data of 5 files/20 files/150 files.

Subscribe to incremental push

market.$symbol.mbp.$levels

Sub request

{
   "sub": "market.btcusdt.mbp.5",
   "id": "id1"
}

Request full data

market.$symbol.mbp.$levels

Req request

{
   "req": "market.btcusdt.mbp.5",
   "id": "id2"
}

parameters

Response (incremental subscription)

{
   "id": "id1",
   "status": "ok",
   "subbed": "market.btcusdt.mbp.5",
   "ts": 1489474081633 //system response time
}

Incremental Update (incremental subscription)

{
"ch": "market.btcusdt.mbp.5",
"ts": 1573199608679, //system update time
   "tick": {
            "seqNum": 100020146795,
            "prevSeqNum": 100020146794,
            "asks": [
                  [645.140000000000000000, 26.755973959140651643] // [price, size]
            ]
       }
}

Response (full request)

{
"id": "id2",
"rep": "market.btcusdt.mbp.150",
"status": "ok",
"data": {
"seqNum": 100020142010,
"bids": [
[618.37, 71.594], // [price, size]
[423.33, 77.726],
[223.18, 47.997],
[219.34, 24.82],
[210.34, 94.463]
     ],
"asks": [
[650.59, 14.909733438479636],
[650.63, 97.996],
[650.77, 97.465],
[651.23, 83.973],
[651.42, 34.465]
]
}
}

Data update field list

Market depth MBP market data (full push)

Users can subscribe to this channel to receive the full data push of the latest in-depth market Market By Price (MBP). The push frequency is about once every 100 milliseconds.

Subscribe to incremental push

market.$symbol.mbp.refresh.$levels

Sub request

{
"sub": "market.btcusdt.mbp.refresh.20",
"id": "id1"
}

parameters

Response

{
"id": "id1",
"status": "ok",
"subbed": "market.btcusdt.mbp.refresh.20",
"ts": 1489474081631 //system response time
}