Rate Limit
Rate limits are mainly divided into two types.
IP Rate Limit, which is based on the user's IP address and limits the access rate from that IP. Currently, the limit setting is relatively high, and users generally will not trigger such limits.
User Rate Limit, which is based on the user's trading account. It includes a Short Cycle Rate Limit and a Long Cycle Rate Limit. Their differences are as follows:
Short Cycle Rate Limit: The main account and its created sub-accounts are independently subject to theShort Cycle Rate Limit. This means that each account has its own limits and quotas, which are independent of other accounts.Long Cycle Rate Limit: The main account and its created sub-accounts share the same rate limit quota. This means that requests from all accounts will affect this shared quota, and requests from all accounts will be deducted from the same quota.
IP Rate Limit
Rate limit: 400/s
User Rate Limit
User Rate Limit is divided into two modes: Short Cycle Rate Limit and Long Cycle Rate Limit.
Short Cycle Rate limittends to control the short-term request volume and prevent malicious use of the API.Long Cycle Rate Limittends to control the long-term request volume and prevent abuse of API resources.
For batch requests that contain a specified number of sub-requests, the request quota consumed will be determined by the number of sub-requests included. An example is as follows:
In a batch spot order request sent to POST /spot/batch-order that includes 5 order requests, the request will consume a quota of 5. The 'short-term rate limit' and 'long-term rate limit' rules will be based on this quantity for consumption tracking.
Currently, the endpoints for calculating request margin by sub-request are listed as follows:
Spot module:
- Batch place orders
POST /spot/batch-order - Batch place stop orders
POST /spot/batch-stop-order - Batch cancel orders
POST /spot/cancel-batch-order - Batch cancel stop orders
POST /spot/cancel-batch-stop-order
Futures module:
- Batch place orders
POST /futures/batch-order - Batch place stop orders
POST /futures/batch-stop-order - Batch cancel orders
POST /futures/cancel-batch-order - Batch cancel stop orders
POST /futures/cancel-batch-stop-order
The current rate limits are based on groups, and the corresponding relationships between groups can be seen in the following section.The 'short-term rate limit' and 'long-term rate limit' will be applied simultaneously in groups.
Short Cycle Rate Limit
This rate limit strategy is based on grouped request paths to control the request frequency on specific paths. Here is a detailed description:
Grouping: Request paths are divided into multiple groups, each group containing a set of related paths. Paths with similar functions or characteristics are grouped together.
Request Quota: Each group has a shared request quota that represents the number of requests allowed for that group within a specific period. The quota is dynamically restored based on the rate-limiting frequency.
Rate Limiting Frequency: Each group will have a rate-limiting frequency, which is the maximum amount of request quota that can be recovered per second. For example, if the rate limiting frequency is 20r/s, it means that the request quota recovers by 20 requests per second.
Rate Limiting Strategy: When a request is received, the system first determines the group to which the request belongs. Then, the system checks if the request quota for that group allows processing of the request.
a. If the request quota is higher than zero, the request is allowed to be processed and the quota is reduced. After the request is processed, the system can return the corresponding results.
b. If the request margin is zero, the request will be refused. The system will return an error code indicating that the request has exceeded the usage limit.
- Account Short Cycle Rate Limit (Spot)
- The main and sub-accounts are separately rate-limited and do not affect each other.
| Endpoint type | Rate limit | Endpoint path included |
|---|---|---|
| Place & edit spot order | 30r/1s | POST /spot/order *Place order |
| POST /spot/stop-order *Place stop order | ||
| POST /spot/modify-order *Edit order | ||
| POST /spot/modify-stop-order *Edit stop order | ||
| POST /spot/batch-order *Batch place orders | ||
| POST /spot/batch-stop-order *Batch place stop orders | ||
| Cancel spot order | 60r/1s | POST /spot/cancel-order *Cancel order |
| POST /spot/cancel-stop-order *Cancel stop order | ||
| POST /spot/cancel-batch-order *Batch cancel orders | ||
| POST /spot/cancel-batch-stop-order *Batch cancel stop orders | ||
| Batch cancel spot orders | 40r/1s | POST /spot/cancel-all-order *Cancel all orders |
| POST /spot/cancel-order-by-client-id *Cancel order by client_id | ||
| POST /spot/cancel-stop-order-by-client-id *Cancel stop order by client_id | ||
| Query spot order | 50r/1s | GET /spot/order-status *Query order status |
| GET /spot/batch-order-status *Batch query order status | ||
| GET /spot/pending-order *Get unfilled order | ||
| GET /spot/pending-stop-order *Get unfilled stop order | ||
| Query spot order history | 10r/1s | GET /spot/order-deals *Get user order execution |
| GET /spot/user-deals *Get user execution | ||
| GET /spot/finished-order *Get filled order | ||
| GET /spot/finished-stop-order *Get filled stop order | ||
| Spot account change | 10r/1s | POST /account/settings *Edit account settings |
| POST /assets/margin/borrow *Margin borrowing | ||
| POST /assets/margin/repay *Margin repayment | ||
| POST /assets/transfer *Asset transfer | ||
| POST /account/subs *Create sub-account | ||
| POST /account/subs/frozen *Disable sub-account | ||
| POST /account/subs/unfrozen *Cancel disable sub-account | ||
| POST /account/subs/api *Create sub-account APIKEY | ||
| POST /account/subs/edit-api *Edit sub-account APIKEY | ||
| POST /account/subs/delete-api *Delete sub-account APIKEY | ||
| POST /account/subs/transfer *Asset transfer between sub-accounts | ||
| POST /assets/renewal-deposit-address *Update deposit address | ||
| POST /assets/withdraw *Submit withdrawal request | ||
| POST /assets/cancel-withdraw *Cancel withdrawal request | ||
| POST /assets/amm/add-liquidity *Add liquidity to AMM account | ||
| POST /assets/amm/remove-liquidity *Remove liquidity to AMM account | ||
| Spot account query | 10r/1s | GET /assets/spot/balance *Get spot account balance |
| GET /account/trade-fee-rate *Get account trading fee rate | ||
| GET /assets/amm/liquidity *Get liquidity in AMM account | ||
| GET /assets/financial/balance *Get financial account balance | ||
| GET /assets/credit/info *Get credit account info | ||
| GET /assets/margin/balance *Get margin account balance | ||
| GET /account/subs *Get sub-account list | ||
| GET /account/subs/api *Get sub-account APIKEY list | ||
| GET /account/subs/api-detail *Get sub-account APIKEY detail | ||
| GET /account/subs/spot-balance *Get sub-account spot balance | ||
| GET /account/subs/info *Get sub-account info | ||
| GET /assets/deposit-address *Get deposit address | ||
| GET /assets/deposit-withdraw-config *Get deposit and withdrawal configuration | ||
| Spot account history data query | 10r/1s | GET /assets/withdraw *Get withdrawal records |
| GET /assets/deposit-history *Get deposit records | ||
| GET /assets/statement *Get user asset history | ||
| GET /assets/transfer-history *Get asset transfer records | ||
| GET /assets/margin/borrow-history *Get margin borrowing records | ||
| GET /assets/margin/interest-limit *Get margin borrowing quota | ||
| GET /account/subs/transfer-history *Get transfer records between sub-accounts |
- Account Short Cycle Rate Limit (Futures)
- The main and sub-accounts are separately rate-limited and do not affect each other.
| Endpoint type | Rate limit | Endpoint path included |
|---|---|---|
| Place & edit futures orders & adjust position | 20r/1s | POST /futures/order *Place order |
| POST /futures/stop-order *Place stop order | ||
| POST /futures/close-position *Market close all positions | ||
| POST /futures/adjust-position-margin *Adjust position margin | ||
| POST /futures/adjust-position-leverage *Adjust position leverage | ||
| POST /futures/set-position-stop-loss *Set position stop loss | ||
| POST /futures/set-position-take-profit *Set position take profit | ||
| POST /futures/modify-order *Edit order | ||
| POST /futures/modify-stop-order *Edit stop order | ||
| POST /futures/batch-order *Batch place orders | ||
| POST /futures/batch-stop-order *Batch place stop orders | ||
| Cancel futures order | 40r/1s | POST /futures/cancel-order *Cancel order |
| POST /futures/cancel-stop-order *Cancel stop order | ||
| POST /futures/cancel-batch-order *Batch cancel orders | ||
| POST /futures/cancel-batch-stop-order *Batch cancel stop orders | ||
| Batch cancel futures orders | 20r/1s | POST /futures/cancel-all-order *Cancel all orders |
| POST /futures/cancel-order-by-client-id *Cancel order by client_id | ||
| POST /futures/cancel-stop-order-by-client-id *Cancel stop order by client_id | ||
| Futures query order | 50r/1s | GET /futures/pending-order *Get unfilled order |
| GET /futures/pending-stop-order *Get unfilled stop order | ||
| GET /futures/order-status *Query order status | ||
| GET /futures/batch-order-status *Batch query order status | ||
| Query futures order history | 10r/1s | GET /futures/finished-order *Get filled order |
| GET /futures/finished-stop-order *Get filled stop order | ||
| GET /futures/finished-position *Get history position | ||
| GET /futures/user-deals *Get user execution | ||
| GET /futures/order-deals *Get user order execution | ||
| Futures account query | 10r/1s | GET /assets/futures/balance *Get futures account balance |
| GET /futures/position-funding-history *Get position funding rate history | ||
| GET /futures/pending-position *Get current position | ||
| GET /futures/position-adl-history *Get position adl history | ||
| GET /futures/position-margin-history *Get position margin change history | ||
| GET /futures/position-settle-history *Get position auto settlement history |
When accessing an endpoint that triggers rate limit, the following two Header will be returned in the HTTP response header.
X-RateLimit-Limit. This value indicates the maximum number of accesses per second allowed by the group to which the endpoint belongs.X-RateLimit-Remaining. This value indicates the current number of remaining accesses for the group to which the endpoint belongs.X-RateLimit-LongPeriod-{period}-Remaining.This value indicates the number of remaining accesses in the currently configured long period of the group to which the endpoint belongs, and period indicates the limit period, such as 1H, 4H, 8H or 24H.
Long Cycle Rate Limit
Long Cycle Rate Limit primarily evaluates the user's request volume and request quality to determine whether to restrict the total volume of requests within a longer cycle. Among them, request quality mainly includes other reference indicators such as effective trading rate and average order survival time.
The concepts mentioned above are explained as follows:
Cycle. Unlike short cycle rate limit, the cycle here refers to a longer statistical cycle, such as 1h, 4h, 8h, or 24h.Request Volume. The total sum of all requests within onecyclefor a specificgroup.Request Quality. It mainly includes other reference indicators such aseffective trading rateandaverage order lifespan.Effective Trading Rate. Theeffective trading ratein a cycle = the number of valid orders (completed orders with executive trading) / the total number of orders.Average Order Lifespan. The average lifespan of orders within a cycle, calculated as the difference between the creation time and completion time of each order.
Only when both the request volume and request quality indicators exceed the limit will it be affected by long cycle rate limit.
The long cycle rate limit will be reset after the end of a cycle and the statistics of the cycle are based on whole hours. For example, assuming that the period of the long cycle rate limit is 8h, then there will be three statistical cycles in a day, namely 0~8h , 8~16h, 16~24h.
After the long cycle rate limit is triggered, API requests will be placed in low-speed mode, where the allowed rate for each group will be significantly reduced. However, it will not restrict users from canceling orders.
When accessing an endpoint that triggers long-term rate limit, the following Header will be returned in the HTTP response header.
X-RateLimit-LongPeriod-{period}-Remaining.This value indicates the number of remaining accesses in the currently configured long period of the group to which the endpoint belongs, and period indicates the limit period, such as 1H, 4H, 8H or 24H.For example: X-RateLimit-LongPeriod-24H-Remaining.In addition, there may be multiple long-period frequency limiting rules in effect at the same time, that is, multiple headers with different periods will be returned at the same time.
- Common error codes and processing methods after the rate limit is triggered.
| Error Code | Method |
|---|---|
| 3008 | Service busy, please try again later. |
| 4001 | Service unavailable, please try again later. |
| 4213 | Rate limit triggered. Please adjust your strategy and reduce the request rate. |
- Other error handling
If you encounter other errors, you can refer to Error Handling.