TypeScript SDK - Polaris

The Polaris TypeScript SDK is available on npm as polaris-data.

Install

npm install polaris-data

Or install with yarn:

yarn add polaris-data

The SDK ships as a dual ESM/CJS build. It requires Node.js 18 or later.

Quickstart

Use replay(...) when you want to stream historical rows in a script or backfill job. You can run this without an API key set.

import { PolarisClient } from "polaris-data";

await using client = new PolarisClient();

for await (const event of client.replay({
  source: "binance",
  market: "BTC-USDT",
  from: "2024-01-01T00:00:00Z",
  to: "2024-01-01T01:00:00Z",
})) {
  console.log(event);
}

Create a client

If you omit apiKey, the client reads POLARIS_API_KEY from the environment.

import { PolarisClient } from "polaris-data";

await using client = new PolarisClient();

console.log(await client.health());

The main constructor is:

new PolarisClient({
  apiKey?: string,
  baseUrl?: string,  // default: "https://api.polaris.supply"
  timeout?: number,   // default: 30_000 (ms)
  datasetRoot?: string,
});

Core methods

Use PolarisClient for discovery, historical replay, and direct query workflows.

Method	Returns	Use it for
`health()`	JSON object	Confirm API availability
`catalog(source?, market?)`	JSON object	Discover sources and exact market IDs
`listSnapshots(source, market, from, to, limit?)`	List of snapshot entries	Find snapshot files for a range
`replay(params)`	Async generator	Stream historical data for replay or backfills
`events(params)`	List of normalized events	Load mixed event types into scripts
`trades(params)`	List of normalized trades	Analyze executions
`raw(params)`	List of raw payloads	Inspect venue-native messages
`ohlcv(params)`	List of bars or TradingView-style JSON	Plot fast market charts

from and to accept ISO 8601 strings, Date objects, or Unix epoch microseconds (number).

Discover a market before you query it

Use catalog(...) to find the exact Polaris market ID for a venue.

import { PolarisClient } from "polaris-data";

await using client = new PolarisClient();

const catalog = await client.catalog({ source: "hyperliquid" });
const markets = catalog.sources[0].markets.map((m) => m.id);
console.log(markets.slice(0, 10));

If you want a high-level view of supported venues and example market IDs before you query the exact pair, start with Market Coverage.

Query events

Use events(...) when you want standardized historical event rows beyond trades alone.

import { PolarisClient } from "polaris-data";

await using client = new PolarisClient();

const rows = await client.events({
  source: "binance",
  market: "BTC-USDT",
  from: "2024-01-01T00:00:00Z",
  to: "2024-01-01T01:00:00Z",
});

console.log(rows.length);
console.log(rows[0]);

Query trades

trades(...) returns a list of normalized trade events. The SDK handles pagination and snapshot-backed historical reads for you.

import { PolarisClient } from "polaris-data";

const end = new Date();
const start = new Date(end.getTime() - 3600_000); // 1 hour ago

await using client = new PolarisClient();

const trades = await client.trades({
  source: "hyperliquid",
  market: "SPX",
  from: start,
  to: end,
});

console.log(trades[0]);

Query OHLCV bars

Use ohlcv(...) when you want interval bars instead of individual trades.

import { PolarisClient } from "polaris-data";

const end = new Date();
const start = new Date(end.getTime() - 6 * 3600_000); // 6 hours ago

await using client = new PolarisClient();

const bars = await client.ohlcv({
  source: "hyperliquid",
  market: "SPX",
  from: start,
  to: end,
  interval: "1m",
});

console.log(bars[0]);

If you pass format: "tradingview", ohlcv(...) returns TradingView-style candle and volume arrays. The OHLCV aggregation engine preserves precision by scaling volume by 1e12 during accumulation to avoid floating-point drift.

Local dataset storage

The SDK stores standardized snapshots and local day files under a shared Polaris app-data root so the TypeScript SDK and other Polaris tools can reuse the same files. Default roots:

macOS: ~/Library/Application Support/polaris
Linux: $XDG_DATA_HOME/polaris or ~/.local/share/polaris
Windows: %APPDATA%\polaris

Within that root, the SDK uses this layout:

<root>/
  data/
  daily/
  tmp/
  cache/
  locks/

Pass datasetRoot to the constructor to override the root explicitly.

Snapshot-first replay

For standardized historical data, replay(...), events(...), trades(...), and default or TradingView ohlcv(...) prefer /snapshots and /snapshots/download, then read local day files when they already exist.

import { PolarisClient } from "polaris-data";

await using client = new PolarisClient();

for await (const event of client.replay({
  source: "binance",
  market: "BTC-USDT",
  from: "2024-01-01T00:00:00Z",
  to: "2024-01-01T01:00:00Z",
})) {
  console.log(event);
}

On first call, the SDK discovers daily .jsonl.zst snapshot files, downloads them once to the local dataset directory, and serves all subsequent queries from the local cache with no additional network round-trips. If the requested standardized range cannot be satisfied from daily snapshots, the SDK falls back to the legacy /events?format=file flow for standardized replay, event, trade, and local OHLCV derivation.

Authentication

Public sources (e.g. Binance BTC-USDT) work without an API key. For premium sources, raw snapshots, or extended history, set your key via the POLARIS_API_KEY environment variable or pass it directly:

import { PolarisClient } from "polaris-data";

await using client = new PolarisClient({ apiKey: "pk_live_your_key" });

const trades = await client.trades({
  source: "hyperliquid",
  market: "SPX",
  from: "2024-01-01T00:00:00Z",
  to: "2024-01-02T00:00:00Z",
});

See Authentication for the full auth model.

Error handling

The SDK uses a custom error class hierarchy rooted at PolarisError.

import {
  PolarisClient,
  PolarisError,
  UnauthorizedError,
  NotFoundError,
  RateLimitedError,
  StreamDecodeError,
  DownloadNotAllowedError,
} from "polaris-data";

await using client = new PolarisClient();

try {
  for await (const event of client.replay({
    source: "binance",
    market: "BTC-USDT",
    from: "2024-01-01T00:00:00Z",
    to: "2024-01-01T01:00:00Z",
  })) {
    console.log(event);
  }
} catch (error) {
  if (error instanceof UnauthorizedError) {
    console.log("API key is required");
  } else if (error instanceof RateLimitedError) {
    console.log(`Rate limited. Reset at: ${error.resetAt}`);
  } else {
    throw error;
  }
}

Error	HTTP status	Meaning
`UnauthorizedError`	401	API key is missing or invalid
`NotFoundError`	404	Requested source or market does not exist
`RateLimitedError`	429	Too many requests — retry after `resetAt`
`StreamDecodeError`	—	Failed to decode a streamed response
`DownloadNotAllowedError`	—	Download is blocked by the server

Next steps

Read Catalog before you hardcode source and market IDs.
Read Authentication if you want the shared auth model behind the SDK.
Read Snapshots if your TypeScript workflow starts from historical files.
Read Trades, Events, or OHLCV for detailed method documentation.

​Install

​Quickstart

​Create a client

​Core methods

​Discover a market before you query it

​Query events

​Query trades

​Query OHLCV bars

​Local dataset storage

​Snapshot-first replay

​Authentication

​Error handling

​Next steps