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: "hyperliquid",
  market: "BTC",
  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
`intents(params)`	List of typed intent events	Analyze RFQs, quotes, executable intents, and settlements
`optionTickers(params)`	List of typed option ticker events	Read a whole option chain or one exact contract
`ohlcv(params)`	List of bars or TradingView-style JSON	Plot fast market charts
`l2Snapshots(params)`	List of orderbook snapshot rows	Order book reconstruction and microstructure analysis
`l2Updates(params)`	List of raw orderbook snapshots and deltas	High-throughput application-managed books
`fundingRates(params)`	List of funding-rate point series rows	Perpetual funding studies and carry modeling
`markPrices(params)`	List of mark-price point series rows	Basis analysis, mark tracking, and liquidation-related research
`ohlcvTradingView(params)`	TradingView-shaped OHLCV payload	Feeding TradingView-compatible chart consumers directly
`volume(params)`	Bucketed trade volume series	Volume profiling and participation analysis
`vwap(params)`	Bucketed VWAP series	Execution benchmarking and price smoothing
`volatility(params)`	Bucketed realized volatility series	Risk modeling and intraperiod volatility analysis
`bbo(params)`	Best bid/offer quote series	Spread tracking, quote analytics, and top-of-book monitoring
`depthMetrics(params)`	Derived depth, spread, imbalance, and slippage metrics	Liquidity analysis and market impact estimation

from and to accept ISO 8601 strings, Date objects, or Unix epoch milliseconds (number). stream, replay, events, and l2Snapshots reconstruct standardized orderbooks by default. Snapshots replace the complete state, deltas update listed prices, and zero quantity deletes a price. Books clear across gaps and reconnects, with deltas skipped until a new snapshot. Use l2Updates(...) for raw snapshots and deltas, then feed selected updates into the exported OrderbookBuilder for application-managed books.

Match event schema versions

StandardEvent is the structural LegacyStandardEvent | StandardEventV2 union. Check for collector_timestamp before reading version-specific fields:

if ("collector_timestamp" in event) {
  console.log(event.collector_timestamp, event.exchange_timestamp);
} else {
  console.log(event.timestamp);
}

SDK filters and derivations use collector time for v2. Exchange time is nullable venue provenance and may regress. See Event envelope.

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.markets.map((m) => m.market);
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: "hyperliquid",
  market: "BTC",
  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 intents and RFQs

intents(...) returns typed RFQ, quote, executable-intent, and settlement observations in stored order. Use market: "intents" and correlate rows by their captured rfq_id or intent_id.

import { PolarisClient } from "polaris-data";

await using client = new PolarisClient();

const observations = await client.intents({
  source: "uniswapx",
  market: "intents",
});

console.log(observations[0]);

See the Intents and RFQs guide for lifecycle reconstruction and the schema reference for fields.

Query option tickers

Use optionTickers(...) with an underlying market such as BTC. Omit instrument for the whole option chain, or provide one exact venue-native contract.

import { PolarisClient } from "polaris-data";

await using client = new PolarisClient();

const tickers = await client.optionTickers({
  source: "aevo",
  market: "BTC",
});

console.log(tickers[0]);

Every option ticker event keeps source, the normalized underlying market, and the non-empty exact instrument separate. See Option tickers for the payload fields and realtime filtering behavior.

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.

Query order book snapshots

Use l2Snapshots(...) when you need order book depth data for microstructure analysis.

import { PolarisClient } from "polaris-data";

const end = new Date();
const start = new Date(end.getTime() - 5 * 60_000); // 5 minutes ago

await using client = new PolarisClient();

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

console.log(snapshots[0]);

Use l2Updates(...) when you want to manage reconstruction in your application:

import { OrderbookBuilder, PolarisClient } from "polaris-data";

await using client = new PolarisClient();
const books = new OrderbookBuilder();

for (const update of await client.l2Updates({
  source: "hyperliquid",
  market: "BTC",
})) {
  books.update(update);
}

const completeBook = books.snapshot("hyperliquid", "BTC");
if (completeBook) process(completeBook);

update() changes state without constructing a complete object. snapshot() creates sorted levels only when requested. Use apply() when you need the previous update-and-materialize behavior.

Query funding rates

Use fundingRates(...) to analyze perpetual funding rates and carry modeling.

import { PolarisClient } from "polaris-data";

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

await using client = new PolarisClient();

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

console.log(fundingRates[0]);

Query mark prices

Use markPrices(...) for basis analysis, mark tracking, and liquidation-related research.

import { PolarisClient } from "polaris-data";

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

await using client = new PolarisClient();

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

console.log(markPrices[0]);

Query volume profiles

Use volume(...) for volume profiling and participation analysis.

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 volume = await client.volume({
  source: "hyperliquid",
  market: "SPX",
  from: start,
  to: end,
  interval: "1h",
});

console.log(volume[0]);

Query VWAP series

Use vwap(...) for execution benchmarking and price smoothing.

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 vwap = await client.vwap({
  source: "hyperliquid",
  market: "SPX",
  from: start,
  to: end,
  interval: "1h",
});

console.log(vwap[0]);

Query volatility series

Use volatility(...) for risk modeling and intraperiod volatility analysis.

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 volatility = await client.volatility({
  source: "hyperliquid",
  market: "SPX",
  from: start,
  to: end,
  interval: "1h",
});

console.log(volatility[0]);

Query best bid/offer

Use bbo(...) for spread tracking, quote analytics, and top-of-book monitoring.

import { PolarisClient } from "polaris-data";

const end = new Date();
const start = new Date(end.getTime() - 30 * 60_000); // 30 minutes ago

await using client = new PolarisClient();

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

console.log(bboQuotes[0]);

Query depth metrics

Use depthMetrics(...) for liquidity analysis and market impact estimation.

import { PolarisClient } from "polaris-data";

const end = new Date();
const start = new Date(end.getTime() - 30 * 60_000); // 30 minutes ago

await using client = new PolarisClient();

const depthMetrics = await client.depthMetrics({
  source: "hyperliquid",
  market: "BTC",
  from: start,
  to: end,
  depthPct: 0.01,
  slippageNotional: 10000.0,
});

console.log(depthMetrics[0]);

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 /download, then read local day files when they already exist. See Snapshots for the full flow.

Authentication

Public sources (e.g. Hyperliquid BTC) 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 Quickstart 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: "hyperliquid",
    market: "BTC",
    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 Quickstart 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

​Match event schema versions

​Discover a market before you query it

​Query events

​Query trades

​Query intents and RFQs

​Query option tickers

​Query OHLCV bars

​Query order book snapshots

​Query funding rates

​Query mark prices

​Query volume profiles

​Query VWAP series

​Query volatility series

​Query best bid/offer

​Query depth metrics

​Local dataset storage

​Snapshot-first replay

​Authentication

​Error handling

​Next steps