To ensure fair usage and maintain the stability of our services, the CVEX API implements a rate limiting mechanism for both HTTP requests and WebSocket connections. This section provides a detailed explanation of how these rate limits are enforced and how you can interact with the API within these constraints.
Special Terms for API Credits
Designated Market Makers and professional traders are invited to contact the CVEX team to discuss specific requirements. We offer tailored options including special initial balances and enhanced credit limits for higher throughput. Please reach out to us at [email protected] to explore these opportunities.
Limiting HTTP requests
Each API key is assigned to a tier with specific rate limits. By default, all API keys are subject to a rate limit of 60 credits per minute. This rate limit defines the maximum number of credits that can be spent on requests per minute on average, as well as the total number of credits allowed to be spent in burst period each 10 minutes. You can find the specific rate limits applicable to your API key on the My API Key page.
Each request to the CVEX API consumes a predetermined number of API credits. Common requests cost 1 credit, although requests that require more data processing or retrieval may consume more credits. The credit cost for each type of request is detailed in the reference documentation.
- Limit: The maximum amount of credits an account can hold at any time. By default, this is set to 600 credits. Your initial credit balance will also be set to this value.
- Rate: The number of credits replenished each minute. By default, this is 60 credits, which means you can spend an average of 1 credit per second. However, instead of replenishing at the end of each minute, credits are replenished continuously based on the time elapsed since your last request. For example, if 30 seconds have passed since your last request, 30 credits will be added to your balance before the cost of the new request is subtracted. This ensures that your available credits are always up-to-date based on real-time usage.
- Burst Capability: At any time, the total balance of credits in an account cannot exceed the limit. By default, this setup allows you to burst up to 10 times your per-minute quota. However, if you fully utilize all 600 credits, you must wait until the balance replenishes before continuing to make requests.
Response Headers
To help you manage your requests and understand your current rate limit status, the following headers are included in the response of each API request:
| Header | Description |
|---|---|
X-RateLimit-Limit | The maximum amount of credits an account can hold at any time. |
X-RateLimit-Remaining | The number of remaining credits available for making requests. |
X-RateLimit-Reset | The time remaining, in seconds, before the rate limit resets to the full limit. |
Exceeding Credit Limits
If the rate limit is exceeded, the server will return a response with the HTTP status code 429 Too Many Requests. The response will indicate that the rate limit has been exceeded and show the time until the limit resets. Here is an example of such a response:
{
"status": "error",
"code": 429,
"message": "Rate limit exceeded. Try again in 58 seconds."
}
Limiting WebSocket connections
For the WebSocket service, the limiting strategy is straightforward: each API key is allowed to maintain up to three simultaneous WebSocket connections. When a user attempts to open more WebSocket connections than the permitted limit, the server will respond with a message indicating that the connection limit has been exceeded. Here’s an example of such a response:
{
"status": "error",
"code": 429,
"message": "Connection limit exceeded. Maximum of 3 simultaneous connections allowed."
}
Managing Rate Limits
To ensure uninterrupted operation of your services, it's important to carefully manage the rate limits imposed by the CVEX API. Here are some detailed strategies and tips:
- Monitor Rate Limit Headers: Adjust your request frequency based on the rate limit headers in the responses. Ensure that you are not making more than one request per second on average.
- Optimize API Usage: Be aware of the credit costs for different types of requests to better plan and distribute your API usage. Since some requests cost more than others, utilize endpoints that allow batching of requests and provide all required data at once to reduce the total number of requests made.
- Efficient Utilization of Connections: Given that the number of simultaneous WebSocket connections is limited, use each connection efficiently. Aggregate data streams where possible and avoid opening multiple connections.
- Close Unused Connections: Gracefully close WebSocket connections that are no longer needed to free up resources for new connections.
- Implement Retry Mechanisms: Use the
X-RateLimit-Resetheader to determine the optimal time to retry after hitting a rate limit. Wait until the reset period has passed before making a new request.
If you require higher rate limits than those provided by default, please contact us at [email protected] to discuss your needs and explore available options.