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

# Rate Limits and User Limits

Per-minute REST weight budgets by plan (5,000 / 20,000 / 50,000) and the weight of each endpoint.

#### Rest APIs

Aggregated weight limit per minute:

| Starter | Growth | Scale  |
| ------- | ------ | ------ |
| 5000    | 20,000 | 50,000 |

Every request draws its weight from this per-minute budget, except the [windowed endpoints](#windowed-endpoints) below. Requests have a default weight of 2 points except for the following:

| Endpoint                                                                                                                                                                                                      | Weight     | Notes                                                                                                                   |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------- |
| `userPnlSummary`                                                                                                                                                                                              | 20         |                                                                                                                         |
| `userPnlLeaderboard`                                                                                                                                                                                          | 200        |                                                                                                                         |
| `userCompletedTrades`                                                                                                                                                                                         | 20         |                                                                                                                         |
| `userCompletedTradesByTime`                                                                                                                                                                                   | 20         |                                                                                                                         |
| `userFills`                                                                                                                                                                                                   | 10         |                                                                                                                         |
| `userFillsByTime`                                                                                                                                                                                             | 10         |                                                                                                                         |
| `fillsByTime`                                                                                                                                                                                                 | 10         |                                                                                                                         |
| `tradesByTime`                                                                                                                                                                                                | 10         |                                                                                                                         |
| `userTwapSliceFills`                                                                                                                                                                                          | 10         |                                                                                                                         |
| `userTwapSummaries`                                                                                                                                                                                           | 10         |                                                                                                                         |
| `userTwapStatusesByTime`                                                                                                                                                                                      | 20         |                                                                                                                         |
| `userLeverageUpdatesByTime`                                                                                                                                                                                   | 20         |                                                                                                                         |
| `userIsolatedMarginUpdatesByTime`                                                                                                                                                                             | 20         |                                                                                                                         |
| `historicalOrders`                                                                                                                                                                                            | 10         |                                                                                                                         |
| `orderStatusByOid`                                                                                                                                                                                            | 10         |                                                                                                                         |
| `userFunding`                                                                                                                                                                                                 | 10         |                                                                                                                         |
| `userNonFundingLedgerUpdates`                                                                                                                                                                                 | 10         |                                                                                                                         |
| `metaAndAssetCtxs`                                                                                                                                                                                            | 20         |                                                                                                                         |
| `candleSnapshot`                                                                                                                                                                                              | 20         |                                                                                                                         |
| `registeredOutcomes`                                                                                                                                                                                          | 20         |                                                                                                                         |
| `registeredOutcomesById`                                                                                                                                                                                      | 20         |                                                                                                                         |
| `settledOutcomes`                                                                                                                                                                                             | 20         |                                                                                                                         |
| `settledOutcomesById`                                                                                                                                                                                         | 20         |                                                                                                                         |
| `outcomeVenueStats`                                                                                                                                                                                           | 20         |                                                                                                                         |
| `marketLiquidity`                                                                                                                                                                                             | 10         |                                                                                                                         |
| `marketLiquidityHistory`                                                                                                                                                                                      | 10         |                                                                                                                         |
| `slippageHistory`                                                                                                                                                                                             | 10         |                                                                                                                         |
| `perpPriceHistoryByTime`                                                                                                                                                                                      | 10         |                                                                                                                         |
| `allPerpMetas`                                                                                                                                                                                                | 10         | Full universe and margin tables across all perp DEXes.                                                                  |
| `builderFills`                                                                                                                                                                                                | 5          |                                                                                                                         |
| `builderFillsByTime`                                                                                                                                                                                          | 5          |                                                                                                                         |
| `builderApprovedFillsByTime`                                                                                                                                                                                  | 100        | Joins the approval index against `fills`.                                                                               |
| `builderApprovedFundingByTime`                                                                                                                                                                                | 100        | Joins the approval index against `funding_events`; a full page touches a granule per user, so it is priced accordingly. |
| `builderApprovedNonFundingLedgerUpdatesByTime`                                                                                                                                                                | 100        | Joins the approval index against `ledger_events`; priced like the funding sibling.                                      |
| `builderOrdersByTime`                                                                                                                                                                                         | 5          |                                                                                                                         |
| `fundingHistory`                                                                                                                                                                                              | 5          |                                                                                                                         |
| `liquidationHistoryByTime`                                                                                                                                                                                    | 5          |                                                                                                                         |
| `openInterestHistory`                                                                                                                                                                                         | 5          |                                                                                                                         |
| `currentDepth`                                                                                                                                                                                                | 5          |                                                                                                                         |
| `portfolioState`                                                                                                                                                                                              | 5          |                                                                                                                         |
| `apiUsage`                                                                                                                                                                                                    | 5          |                                                                                                                         |
| `stakingEvents`                                                                                                                                                                                               | 5          |                                                                                                                         |
| `validatorAprHistory`                                                                                                                                                                                         | 5          |                                                                                                                         |
| `delegatorHistory`                                                                                                                                                                                            | 5          |                                                                                                                         |
| `delegatorRewards`                                                                                                                                                                                            | 5          |                                                                                                                         |
| `perpSnapshotTimestamp`, `spotSnapshotTimestamp`, `perpTwapSnapshotTimestamp`, `spotTwapSnapshotTimestamp`, `accountValueSnapshotTimestamp`, `fundingPaymentTimestamp`, `registeredOutcomesSnapshotTimestamp` | 1          |                                                                                                                         |
| `batchClearinghouseStates`                                                                                                                                                                                    | 2 per user | Max 100 points. Up to 1000 users (100 with `ALL_DEXES`). Cost multiplied by number of dexes with `ALL_DEXES`.           |
| `batchPortfolioStates`                                                                                                                                                                                        | 3 per user | Max 200 points. Up to 500 users (100 with `ALL_DEXES`). Cost multiplied by number of dexes with `ALL_DEXES`.            |
| `batchPerpAnnotations`                                                                                                                                                                                        | 1 per user | Max 25 points.                                                                                                          |

#### Windowed endpoints

These endpoints have their own per-endpoint limit and do **not** draw from the per-minute budget above:

| Endpoint                                                                                                                                                                     | Limit                      |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| `perpSnapshots`, `spotSnapshots`, `perpTwapSnapshots`, `spotTwapSnapshots`, `accountValueSnapshots`, `fundingPayments`, `registeredOutcomesSnapshot`, `globalStakingSummary` | 5 requests per 10 minutes  |
| `l4Book`                                                                                                                                                                     | 20 requests per 5 minutes  |
| `tpslBook`                                                                                                                                                                   | 10 requests per 5 minutes  |
| `walletLabels` (add-on)                                                                                                                                                      | 10 requests per 10 minutes |
| `l2Book`                                                                                                                                                                     | 60 requests per 5 minutes  |
| `l2BookDiffSnapshot`                                                                                                                                                         | 300 requests per 5 minutes |

## Handling rate limits

Responses admitted by the REST limiter, including downstream errors, and its 429 rejections include:

| Header                  | Meaning                                                                                                                                             |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-RateLimit-Limit`     | Governing bucket capacity in weight points.                                                                                                         |
| `X-RateLimit-Remaining` | Points remaining immediately after admission; rejection consumes no points.                                                                         |
| `X-RateLimit-Reset`     | Whole seconds, rounded up, until all usage recorded in the admission snapshot expires. Handler elapsed time is deducted; an empty bucket reports 0. |
| `X-RateLimit-Cost`      | Weight consumed by this request; 0 on limiter rejection. This is independent of billed tokens.                                                      |
| `Retry-After`           | On 429 only: whole seconds, rounded up, until enough weight expires for this request.                                                               |

Windowed endpoints report their own weighted bucket, rather than the shared tier budget. For example, `exportLabels` costs 20 points and has a 100-point capacity: five requests per minute.

The limiter uses a sliding window: capacity returns as individual requests expire. `Reset` describes full restoration and can be longer than `Retry-After`. Remaining is an admission snapshot, not a reservation; concurrent requests can invalidate either estimate. State belongs to the enforcing process and can reset on restart.

The budget headers are omitted for keys permitted to bypass enforcement. Authentication, permission or JSON errors before the limiter, health checks and preflights have no budget snapshot. Missing headers alone do not imply unlimited access. `Access-Control-Expose-Headers` exposes these names for browser clients already permitted by the origin's CORS policy.

A 429 preserves the existing `error` string and adds retry metadata:

```json
{
  "error": "Rate limit exceeded. You have 8 points remaining. This request requires more points.",
  "code": "rate_limited",
  "message": "Rate limit exceeded. You have 8 points remaining. This request requires more points.",
  "retryAfterSecs": 12,
  "remaining": 8,
  "required": 20,
  "correlationId": "AB12CD34"
}
```

Honor `Retry-After` before retrying, optionally adding positive jitter. If unavailable, use the body's `retryAfterSecs`; otherwise use bounded exponential backoff with jitter. Limit attempts and total elapsed time to avoid retry storms. Do not retry 400s unchanged: oversized batches and requests whose weight exceeds total capacity must be corrected.

The SDK retries HTTP 429 by default, with at most three retries (four total attempts) and a 90-second total HTTP call budget. All REST, snapshot, L2/L4, TP/SL, asset-context and perp-price clients accept `max_rate_limit_retries` and `http_call_budget_seconds`; `OrderbookStream` forwards the same options. Set `max_rate_limit_retries=0` to disable retries. Longer-window customers can increase the call budget.

The SDK prefers a valid `Retry-After` integer or HTTP date, then body `retryAfterSecs`, otherwise exponential backoff starting at one second and capped at 30 seconds. Server guidance receives up to one second of positive jitter and is never shortened to that fallback ceiling. A delay that cannot fit the remaining budget raises immediately. Attempts and waits share the same budget, including injected sessions and per-request timeouts. Responses are released before waiting; cancellation propagates.

Exhausted HTTP `RateLimitError` exposes `http_status`, `retry_after_secs`, `remaining`, `required`, `limit`, `reset_secs`, `cost`, and `correlation_id` when available. Only exhausted HTTP 429s escape streaming `run()`/bootstrap instead of restarting the HTTP retry cycle. Other errors, including other HTTP 4xx responses and malformed successful snapshots, retain their previous reconnect behavior. Other HTTP errors and transport failures are not automatically retried by the HTTP helper. WebSocket reconnect options, including `max_retries=0` meaning unlimited WebSocket reconnects, retain their existing meaning.