Rate limits
5 requests per second per IP with a burst of 20; X-RateLimit headers and Retry-After.
# Rate limits
There are **no API keys and no billing**. Every client is limited **per IP address**, and the limit depends on the kind of call: its **rate class**. Each endpoint page shows its class.
## The classes
| Class | Endpoints | Limit |
| --- | --- | --- |
| **read** | v1 reads, [Address UTXOs](https://docs.rarebl.com/api/address/utxos), [Address nonce](https://docs.rarebl.com/api/address/nonce), [Address resources](https://docs.rarebl.com/api/address/resources), [Output spend status](https://docs.rarebl.com/api/tx/outspends), [Signer key](https://docs.rarebl.com/api/tx/signer-key), [Market](https://docs.rarebl.com/api/market/price) endpoints, [Get a webhook](https://docs.rarebl.com/api/hooks/get), [Webhook deliveries](https://docs.rarebl.com/api/hooks/deliveries) | 5 per second, burst 20 (the v1 bucket) |
| **compute** | [Decode](https://docs.rarebl.com/api/tx/decode), [Estimate](https://docs.rarebl.com/api/tx/estimate), [Build](https://docs.rarebl.com/api/tx/build), [Assemble](https://docs.rarebl.com/api/tx/assemble) (without broadcast), [Validate an address](https://docs.rarebl.com/api/address/validate) | 2 per second, burst 10 |
| **write** | [Broadcast](https://docs.rarebl.com/api/tx/broadcast), [Assemble](https://docs.rarebl.com/api/tx/assemble) with `broadcast: true`, hosted [Sign](https://docs.rarebl.com/api/tx/sign), [Send](https://docs.rarebl.com/api/tx/send) and [New address](https://docs.rarebl.com/api/address/new) | 6 per minute, burst 3; 300 per day |
| **watch** | [Watch addresses](https://docs.rarebl.com/api/address/watch) | 30 per minute; 2,000 addresses per day |
| **hooks** | [Create](https://docs.rarebl.com/api/hooks/create), [Update](https://docs.rarebl.com/api/hooks/update), [Pause](https://docs.rarebl.com/api/hooks/pause), [Resume](https://docs.rarebl.com/api/hooks/resume), [Delete](https://docs.rarebl.com/api/hooks/delete), [Test](https://docs.rarebl.com/api/hooks/test), [Replay](https://docs.rarebl.com/api/hooks/replay) | 10 per minute; at most 100 active subscriptions per IP |
| **stream** | `wss://api.rarebl.com/ws` ([WebSocket stream](https://docs.rarebl.com/api/websocket)) | 3 connections per IP; 200 channel subscriptions per connection |
Each class is a separate bucket: a burst of builds does not use up your reads. The read bucket is separate from the explorer website's.
## Headers
Every reply carries:
| Header | Meaning |
| --- | --- |
| `X-RateLimit-Limit` | The size of the bucket for this call (the burst limit). |
| `X-RateLimit-Remaining` | How many requests are left in the bucket right now. |
| `X-Request-Id` | An id for the request, the same value as `meta.requestid` in the reply body. Quote it when you ask for support. |
| `Retry-After` | Only on `API429`: seconds to wait before retrying. |
Requests past a limit are answered with **`API429`** (HTTP 429).
## Handling `API429`
~~~js
async function call(url, options, tries = 3) {
for (let i = 0; i < tries; i++) {
const res = await fetch(url, options);
if (res.status !== 429) return res.json();
const wait = Number(res.headers.get('Retry-After') ?? 1);
await new Promise((r) => setTimeout(r, wait * 1000));
}
throw new Error('rate limited');
}
~~~
## Staying under the limits
- **Reads:** use [Live stats](https://docs.rarebl.com/api/stats/live) to watch all chains in one call; cache what does not change; poll no faster than the data changes ([Data freshness](https://docs.rarebl.com/data-freshness)). Prefer [webhooks](https://docs.rarebl.com/guides/webhooks) or the [WebSocket](https://docs.rarebl.com/guides/websocket) to polling.
- **Compute:** build once and reuse the reply; the builds an SDK makes count. Use [Estimate](https://docs.rarebl.com/api/tx/estimate) sparingly in loops.
- **Write:** this is the tight one. A broadcast is 1 of 6 per minute (burst 3) and 300 per day per IP. Batch your outputs where the chain allows, send an `Idempotency-Key` so a retry is not a second broadcast, and queue payouts instead of firing them in a burst.
- **Watch:** up to 100 addresses per call; 2,000 addresses per day. Watch only what you need. Address webhooks and WebSocket address channels on BTC, LTC and BCH watch for you, and count.
- **Hooks:** create one subscription per thing you follow and delete the ones you no longer need (100 active per IP).
- **Stream:** one connection per app, up to 3 per IP.
## Per IP, behind NAT
The limit is per IP address. Many users behind one address (an office, a mobile carrier, your own backend) share the bucket. Run heavy workloads from your own server, and cache.
## Higher limits
`X-API-KEY` is reserved. There are no keyed plans and no billing today; a key sent is ignored. See [Authentication](https://docs.rarebl.com/authentication).