# Rate limits

> Per-minute buckets, what shares them, the headers to read, and how to stay under.

Source: https://getchord.xyz/docs/concepts/rate-limits/

Limits are per minute and enforced in Redis. Every response carries three headers:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1789891900
```

Over the limit you get `429` with `{ "error": "RATE_LIMIT_EXCEEDED" }`. Wait for `X-RateLimit-Reset` (Unix seconds), then continue. The limiter fails open if the store is unreachable: a store outage never turns into a client outage.

## Buckets

Anonymous traffic is keyed by IP. A key is keyed by the key and gets the plan's limit. Some families are read-heavy by nature and have their own, larger per-IP buckets, so a page that fans out on load cannot starve a swap from the same address.

| Bucket | Applies to | Anonymous limit |
| --- | --- | --- |
| Default | `/quote`, `/swap`, `/arc/*`, `/rh/*`, `/lp/*`, `/smart-money/*`, `/points/*`, `/ask/*`, `/bridge2/*` and everything not below | 60 a minute per IP, or your plan with a key |
| Data reads | `GET /tokens*`, `/portfolio/*`, `/market*`, `/stream/*` | 300 a minute per IP |
| Logos | `GET /logo/*` | 3,000 a minute per IP |
| Bridge polling | `GET /crosschain/status` | 240 a minute per IP |
| Exempt | `/ws/live` upgrades | own connection and channel caps |

The Ask agent adds its own guard: 8 questions a minute per caller, and a daily token budget for the deployment (`GET /v1/ask/status` shows it).

## Staying under

- Poll boards at 10–30 s and token pages at 5–10 s; the answers are memoised server-side, and polling faster returns the same bytes.
- Use `/v1/ws/live` for candles, trades and Arc prices instead of polling `/tokens/chart` and `/tokens/trades`.
- One `/arc/tokens?limit=500` beats 500 token calls; one `/tokens/stats/{address}` beats four windowed calls.
- Cache `/tokens?chain=` (the curated list) for an hour.
- Quotes are the expensive call. Quote on user intent, not on every keystroke; the `fast=1` frame exists for the first paint.

## Capacity, not rate

Two endpoints cap concurrency instead: `/v1/stream/market` at 500 clients and `/v1/ws/live` at 500 connections with 8 channels each. Both answer `503` when full. Reconnect with backoff.