Skip to main content
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

Manage keys and plans at 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.

​
Access states

Each Catalog market carries access.status and an optional public_cutoff_date:

​
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. 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 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 for larger scans.

​
Errors

Error responses share one envelope:
error.resolution states the corrective action; surface it to the user rather than guessing. 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.