The Neutron API enforces rate limits to protect platform stability and ensure fair access for all users. Understanding these limits helps you design resilient integrations that operate smoothly at scale.
Rate Limit Tiers
| Tier | Requests per minute | Burst (per second) | Who |
|---|---|---|---|
| Standard | 60 | 5 | Default for all accounts |
| Premium | 300 | 20 | High-volume accounts (contact sales) |
Rate limits apply per account and are shared across all API keys associated with that account.
Rate Limit Headers
Every API response includes headers to help you track your usage:
| Header | Description | Example |
|---|---|---|
X-RateLimit-Limit | Maximum requests allowed per window | 60 |
X-RateLimit-Remaining | Requests remaining in the current window | 45 |
X-RateLimit-Reset | Unix timestamp (seconds) when the window resets | 1707393600 |
Example Response Headers
HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1707393600
Content-Type: application/jsonWhen You're Rate Limited
If you exceed the limit, the API returns a 429 Too Many Requests response:
{
"error": "rate_limit_exceeded",
"message": "Too many requests. Please retry after the reset window."
}The X-RateLimit-Reset header tells you exactly when you can resume making requests.
Which Endpoints Count
All authenticated API calls count toward your rate limit, including:
- ✅ Authentication token requests
- ✅ Transaction create, confirm, and status checks
- ✅ Account and wallet queries
- ✅ Webhook management
- ✅ Reference data lookups (exchange rates, fiat institutions)
Best Practices
1. Use Webhooks Instead of Polling
Don't poll transaction status in a loop. Do set up webhooks to receive real-time notifications when transactions change state. This is both faster and uses zero rate limit.
❌ Loop: GET /api/v2/transaction/{id} every 5 seconds
✅ Set up webhook → receive POST to your callback URL on state change2. Implement Exponential Backoff
When you hit a 429, don't immediately retry. Wait and increase the delay:
Attempt 1: wait 1 second
Attempt 2: wait 2 seconds
Attempt 3: wait 4 seconds
Attempt 4: wait 8 seconds
(cap at 60 seconds)3. Cache Responses Where Possible
Some data changes infrequently and can be cached locally:
| Data | Suggested Cache TTL |
|---|---|
| Exchange rates | 30–60 seconds |
| Fiat institution lists | 24 hours |
| Account info | 5 minutes |
| Wallet balances | 30 seconds |
4. Batch Your Requests
If you need to check multiple transactions, use the list transactions endpoint instead of making individual requests for each one.
5. Monitor Your Usage
Track the X-RateLimit-Remaining header in your code. If it drops below 10%, slow down your request rate proactively rather than waiting to get blocked.
6. Token Reuse
Don't request a new authentication token for every API call. Tokens have a lifespan — reuse them until they're close to expiring, then refresh. Check the expiredAt field from the authentication response.
Need Higher Limits?
If your integration requires more throughput, contact us to discuss premium rate limits tailored to your use case.