# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.x1.xyz/build-on-x1/rpc-rate-limits.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.