> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polaris.supply/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication & Rate Limits

> Authenticate requests, choose public data windows, and handle rate limits and errors across REST, SDKs, CLI, and MCP.

One access model applies to the REST API, SDKs, CLI, and hosted MCP server. Public data is available without an API key; add a key when you need older history or restricted data.

## Authentication

| Method | Use |
| - | - |
| No key (anonymous) | Public windows below, on open sources |
| `POLARIS_API_KEY` environment variable | SDKs and CLI read this automatically |
| Bearer header / `api_key` constructor argument | REST `Authorization: Bearer $POLARIS_API_KEY`; SDK client argument |

Manage keys and plans at [polaris.supply/keys](https://www.polaris.supply/keys). Live keys have the form `pk_live_...`; treat them as secrets and never embed them in source code.

The hosted MCP server at `https://mcp.polaris.supply` offers the same queries with anonymous public access, optional API-key authentication, or per-call x402 payment for restricted tools — see [MCP server setup](https://polaris.supply/mcp-server).

## Access states

Each [Catalog](/endpoints/catalog) market carries `access.status` and an optional `public_cutoff_date`:

| Status | Meaning |
| - | - |
| `open` | Current data is broadly accessible without a key |
| `preview` | A bounded public window around `public_cutoff_date`; wider history needs an API key |
| `restricted` | Requires an API key with the appropriate entitlement |

## Public windows per endpoint

For anonymous requests, most standardized routes expose a rolling latest-hour window; preview sources clamp their public range around `public_cutoff_date`. A Polaris API key unlocks older history.

| Endpoint | Anonymous (no key) | With a key |
| - | - | - |
| [Trades](/endpoints/trades), [L2 Deltas](/endpoints/l2-updates), [L2 orderbooks](/endpoints/l2-orderbooks), [Funding rates](/endpoints/funding-rates), [Perpetual ticker](/endpoints/perpetual-ticker), [Options ticker](/endpoints/options-ticker), [OHLCV](/endpoints/ohlcv) | Rolling latest hour | Full covered history |
| [Intents](/endpoints/intents), [Quotes](/endpoints/quotes) | Rolling latest hour | Full covered history |
| [Events](/endpoints/events) | Not available — key and both time bounds required | Bounded mixed-event queries |
| [Raw data](/endpoints/raw) | Latest seven days; `start` and `end` required | Full capture history |
| [Catalog](/endpoints/catalog), [Instruments](/endpoints/catalog-instruments), [Counts](/endpoints/count) | Fully public | Fully public |

Bounds behavior shared by the latest-hour routes:

* No bounds: the query covers the latest hour.
* Only `start` (inside the rolling hour): queries through now.
* Only `end` (inside the rolling hour): covers the preceding hour, clamped to the cutoff.
* Explicit bounds entirely inside the rolling hour are public; older rows require a key.
* During anonymous pagination, rows that age out of the public hour are skipped.

Preview sources expose only the bounded range around `public_cutoff_date` — the UTC day it names. Read each Catalog row's `start`, `end`, and `access` before choosing a time range.

## Rate limits

Anonymous reads are capped at 1 GiB per request and two concurrent queries per API replica. Requests that exceed a limit or burst rate return `429` with a `Retry-After` header; honor it before retrying.

Reconstruction work has its own caps: [L2 orderbooks](/endpoints/l2-orderbooks) replays at most 100,000 matching raw captures, 1 GiB of reads, and 30 seconds per request, and returns `422` when a query exceeds them. Narrow the range or use [L2 Deltas](/endpoints/l2-updates) for larger scans.

## Errors

Error responses share one envelope:

```json theme={null}
{
  "error": {
    "code": "...",
    "message": "...",
    "resolution": "..."
  }
}
```

`error.resolution` states the corrective action; surface it to the user rather than guessing.

| Status | Meaning | Recovery |
| - | - | - |
| `400` | Malformed request | Check parameter names, types, and formats |
| `401` | Missing or invalid API key | Set `POLARIS_API_KEY` or pass a valid key |
| `404` | Unknown source, channel, or route | Resolve identifiers from [Catalog](/endpoints/catalog) |
| `422` | Query refused as too expensive or unbounded | Narrow `start`/`end` or reduce `limit` |
| `429` | Rate limit exceeded | Wait for `Retry-After`, then retry |
| `503` | Service temporarily unavailable | Retry with backoff |

The Python and TypeScript SDKs raise typed errors such as `UnauthorizedError` and `RateLimitedError`. Rust returns `Result` errors. Handle authentication failures by setting a valid key, and honor the rate-limit reset time before retrying.

The authoritative machine-readable contract is the [OpenAPI document](https://api.polaris.supply/openapi.json).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.