Skip to main content
One access model applies to the REST API, the SDKs, the CLI, and the hosted MCP server. This page defines it once; endpoint pages list only their exceptions. Every curl example in these docs runs without an API key on the current public window.

​
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.

​
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.

​
Pagination

All list endpoints use opaque keyset cursors:
  1. Pass next_cursor as cursor on the next request, with the same filters.
  2. Stop when has_more is false or next_cursor is null.
  3. Never edit a cursor or reuse it with different filters; some cursors are bound to the complete query, so repeat every filter (start, end, types, source, market, instrument, and endpoint-specific IDs such as intent_id).

​
Errors

Error responses share one envelope:
error.resolution states the corrective action; surface it to the user rather than guessing. The SDKs raise typed errors for the common cases (UnauthorizedError, RateLimitedError, and related classes); see the error-handling sections of the Python and TypeScript SDK pages. Rust surfaces the same cases as Result error variants; see the Rust SDK. The authoritative machine-readable contract is the OpenAPI document.