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

# Rate Limits

API v1 enforces per-minute rate limits. How much you get depends on how you call it: with an API key, without one, or from a browser on an allowed origin.

## Two classes of requests

| Class       | Endpoints                                                                                                                                                                                       |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **quote**   | `POST /v1/quote`, `POST /v1/deposit-address`, `POST /v1/deposit-address/quote` and `GET /v1/deposit-address/status` — they go out to liquidity sources, so they have their own, smaller budget. |
| **default** | Everything else (`/v1/chains`, `/v1/tokens`, `/v1/token`, `/v1/status`).                                                                                                                        |

Each class is counted separately: running out of quotes doesn't block status checks.

## Limits

Requests per minute:

| Caller                                                                                                                                                              | Counted per                                      | quote       | default |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ----------- | ------- |
| **With an API key**                                                                                                                                                 | Your integrator — all your keys share one budget | 600 (≈10/s) | 1,200   |
| **Without a key**                                                                                                                                                   | Client IP                                        | 50          | 300     |
| **Without a key**, naming your `integratorId`                                                                                                                       | Your `integratorId`, across all IPs              | 3,000       | 15,000  |
| **Browser, from Swapper's hosted widget or your** [**allowed origins**](https://docs.swapper.finance/api-v1/authentication.md#browser-requests-and-allowed-origins) | End-user IP                                      | 120         | 600     |

* A keyless request counts against **both** the per-IP limit and, when it names an integrator, that integrator's ceiling. Whichever runs out first applies. The ceiling is high on purpose: your `integratorId` is public, so it only stops someone else's traffic from using up your id.
* Browser traffic from the widget or your allowed origins also has a high per-integrator ceiling (6,000 quote / 30,000 other requests per minute).
* Keyless requests that name no integrator share one global budget across all callers. Send your `integrator` (or an API key) to stay out of it.
* Server-to-server traffic should use an **API key**: a busy backend behind one IP will hit the keyless per-IP limit quickly.
* Windows are fixed one-minute windows aligned to the clock; every counter starts again at the top of the minute.

**Need more?** Limits can be raised per integrator — open a ticket in [Discord](https://discord.gg/y8eevERxBz) (see [Support](https://docs.swapper.finance/resources/support.md)). The dashboard's **API usage** page shows the limits that currently apply to you, including any increases.

## Response headers

v1 responses carry these headers:

| Header                  | Meaning                                            |
| ----------------------- | -------------------------------------------------- |
| `X-RateLimit-Limit`     | The per-minute limit that applies to this request. |
| `X-RateLimit-Remaining` | Requests left in the current window.               |
| `X-RateLimit-Reset`     | When the window resets, in **unix seconds**.       |
| `Retry-After`           | On `429` only: seconds to wait before retrying.    |

When a request counts against more than one limit (keyless with an `integratorId`), the headers describe the one with the least headroom. The headers are exposed to browsers via CORS, so frontend code can read them too. In rare cases (e.g. a request that isn't counted) they can be missing — don't require them.

## When you hit a limit

You get `429` with the [error code](https://docs.swapper.finance/api-v1/errors.md) `RATE_LIMITED`:

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 17
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1791043260
X-Request-Id: 3f9a2c4e-…

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded (publicIp, quote: 50/min)",
    "requestId": "3f9a2c4e-…"
  }
}
```

Good practice:

* **Wait for `Retry-After`** (or until `X-RateLimit-Reset`) instead of retrying immediately — retries inside the same window are rejected too.
* **Cache the catalog.** Chains and tokens change rarely; refresh them every few minutes, not per request.
* **Debounce quotes** in UIs — re-quote when the user stops typing, not on every keystroke.
* **Watch `X-RateLimit-Remaining`** and slow down before you reach zero.
