> For the complete documentation index, see [llms.txt](https://docs.x1.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.x1.xyz/build-on-x1/rpc-rate-limits.md).

# RPC Rate Limits

The public X1 RPC endpoints enforce per-IP rate limits to ensure fair access for all users.

## Limits

| Limit                  | Window    | Max requests |
| ---------------------- | --------- | ------------ |
| Short burst            | 5 seconds | 50           |
| Sustained              | 1 hour    | 50,000       |
| Heavy methods          | 5 seconds | 20           |
| Concurrent connections | —         | 15           |

**Heavy methods** — `sendTransaction` and `simulateTransaction` — are subject to a tighter per-window cap due to their higher processing cost.

**CORS preflights** (`OPTIONS` requests) are answered directly by the edge and do not count toward any of these limits.

Requests that exceed any limit receive an HTTP `429 Too Many Requests` response that carries a `Retry-After` header telling you how long to wait before retrying. See [Handling 429 responses](#handling-429-responses) below.

> **Note:** These limits are subject to change. The current values are always reflected in the response headers — see [Rate limit headers](#rate-limit-headers) below.

## Rate limit headers

Every response includes headers so your application can monitor usage and back off gracefully:

| Header                    | Description                                      |
| ------------------------- | ------------------------------------------------ |
| `X-RateLimit-Rate-Short`  | Your request count in the current 5s window      |
| `X-RateLimit-Limit-Short` | Short window cap (50)                            |
| `X-RateLimit-Reset-Short` | Short window duration (5s)                       |
| `X-RateLimit-Rate-Long`   | Your request count in the current 1h window      |
| `X-RateLimit-Limit-Long`  | Long window cap (50000)                          |
| `X-RateLimit-Reset-Long`  | Long window duration (1h)                        |
| `X-RateLimit-Rate-Heavy`  | Your heavy-method count in the current 5s window |
| `X-RateLimit-Limit-Heavy` | Heavy method cap (20)                            |
| `X-RateLimit-Reset-Heavy` | Heavy method window duration (5s)                |
| `X-Conn-Current`          | Your current concurrent connection count         |
| `X-Conn-Limit`            | Concurrent connection cap (15)                   |

## Checking your current usage

```bash
curl -si -X POST https://rpc.mainnet.x1.xyz \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"getSlot"}' \
  | grep -i 'x-ratelimit\|x-conn\|http/'
```

## Handling 429 responses

Every 429 response includes a `Retry-After` header indicating how many seconds to wait before retrying:

| Header        | Description                                            |
| ------------- | ------------------------------------------------------ |
| `Retry-After` | Seconds to wait before retrying. Present on every 429. |

For the short, heavy, and connection caps the value is fixed (5 seconds for short and heavy, 2 seconds for connection). For the sustained 1-hour cap the value is computed from how far over the cap you currently are, using `window_seconds * (rate - cap) / rate`, plus a small floor. A client only slightly over the cap will see a short wait. A client far over will see a wait approaching the full window.

Respecting `Retry-After` is the fastest path back under the cap. Retrying sooner adds to your counter and extends the wait, since both successful and 429-denied requests are counted.

## Tips for staying within limits

* **Poll at a reasonable interval.** Fetching slot or block data every 400ms (roughly one slot) is sufficient for most dashboards.
* **Batch requests** where possible using the JSON-RPC batch format.
* **Reuse connections.** HTTP keep-alive avoids repeated handshakes and reduces connection count.
* **Respect `Retry-After` on 429s.** Wait the suggested duration before retrying. Immediate retries keep your counter elevated and prolong the throttle.
* **Watch the `X-RateLimit-Rate-Long` header** and back off proactively as you approach the cap, rather than waiting for the first 429.

If your application has a legitimate need for higher throughput, reach out to the X1 team.