@pear-protocol/market-sdk 0.0.1-preview.0

package/README.md

@@ -0,0 +1,319 @@
+# @pear-protocol/market-sdk
+
+SDK for real-time market data across cryptocurrency derivative exchanges. Provides charting with multiple visualization modes (weighted ratio, price ratio, performance) and aggregated order book depth through a unified, exchange-agnostic interface with automatic WebSocket streaming.
+
+## Supported Exchanges
+
+| Exchange | Connector Name |
+|----------|---------------|
+| Binance | `binance` |
+| Bybit | `bybit` |
+| Hyperliquid | `hyperliquid` |
+| OKX | `okx` |
+
+## Installation
+
+```bash
+npm install @pear-protocol/market-sdk
+```
+
+## Quick Start
+
+```typescript
+import { Chart, Orderbook, CreateTransport } from '@pear-protocol/market-sdk';
+
+const transport = CreateTransport('hyperliquid');
+
+// Chart
+const chart = new Chart({
+  transport,
+  longTokens: [{ symbol: 'BTC', weight: 50 }, { symbol: 'ETH', weight: 50 }],
+  shortTokens: [{ symbol: 'SOL', weight: 100 }],
+  candleInterval: '1h',
+});
+
+const bars = await chart.getBars('weighted-ratio', startTime, endTime);
+
+const subId = chart.subscribeRealtimeBars('weighted-ratio', (bar) => {
+  console.log(bar.time, bar.open, bar.high, bar.low, bar.close);
+});
+
+// Order book
+const orderbook = new Orderbook({
+  transport,
+  symbol: 'BTC',
+  aggregation: 10,
+  depth: 15,
+});
+
+orderbook.subscribe((snapshot) => {
+  console.log('bids:', snapshot.bids, 'asks:', snapshot.asks);
+});
+
+// Cleanup
+chart.unsubscribeRealtimeBars(subId);
+chart.destroy();
+orderbook.destroy();
+transport.destroy();
+```
+
+## Chart
+
+### Initialization
+
+```typescript
+import { Chart, CreateTransport } from '@pear-protocol/market-sdk';
+
+const transport = CreateTransport('binance');
+
+const chart = new Chart({
+  transport,
+  longTokens: [{ symbol: 'BTC', weight: 60 }, { symbol: 'ETH', weight: 40 }],
+  shortTokens: [{ symbol: 'SOL', weight: 100 }],
+  candleInterval: '1h',
+});
+```
+
+#### `ChartConfig`
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `transport` | `Transport` | — | WebSocket transport instance |
+| `longTokens` | `TokenSelection[]` | `[]` | Tokens on the long side with weights |
+| `shortTokens` | `TokenSelection[]` | `[]` | Tokens on the short side with weights |
+| `candleInterval` | `CandleInterval` | `'1h'` | Candle timeframe |
+
+#### `TokenSelection`
+
+```typescript
+{ symbol: string; weight: number }
+```
+
+#### `CandleInterval`
+
+```typescript
+'1m' | '3m' | '5m' | '15m' | '30m' | '1h' | '2h' | '4h' | '8h' | '12h' | '1d' | '3d' | '1w' | '1M'
+```
+
+### Updating Tokens and Interval
+
+Change the tokens or candle interval at any time. Both clear cached data and baseline prices.
+
+```typescript
+chart.setTokens(
+  [{ symbol: 'BTC', weight: 100 }],
+  [{ symbol: 'ETH', weight: 100 }],
+);
+
+chart.setCandleInterval('15m');
+```
+
+### Fetching Historical Bars
+
+Fetch historical OHLC bars for a given chart type and time range.
+
+```typescript
+const bars = await chart.getBars('weighted-ratio', startTime, endTime);
+
+for (const bar of bars) {
+  bar.time;   // timestamp (ms)
+  bar.open;   // open price
+  bar.high;   // high price
+  bar.low;    // low price
+  bar.close;  // close price
+}
+```
+
+#### Chart Types
+
+| Type | Description |
+|------|-------------|
+| `'weighted-ratio'` | Geometric mean ratio using token weights as exponents |
+| `'price-ratio'` | Weighted sum of long prices divided by weighted sum of short prices |
+| `'performance'` | Percentage performance relative to the earliest bar in the range |
+
+#### Single-Asset Bars
+
+Fetch bars for one specific symbol in the configured token set.
+
+```typescript
+const bars = await chart.getAssetBars('BTC', startTime, endTime);
+```
+
+### Subscribing to Real-Time Bars
+
+Subscribe to live bar updates. The WebSocket connection is established automatically on the first subscription.
+
+```typescript
+const subId = chart.subscribeRealtimeBars('weighted-ratio', (bar) => {
+  console.log(bar.time, bar.open, bar.high, bar.low, bar.close);
+});
+
+// Single-asset real-time bars
+const assetSubId = chart.subscribeRealtimeAssetBars('ETH', (bar) => {
+  console.log(bar.time, bar.close);
+});
+
+// Stop receiving updates
+chart.unsubscribeRealtimeBars(subId);
+chart.unsubscribeRealtimeBars(assetSubId);
+```
+
+### Data Boundary
+
+Get the earliest timestamp for which historical data is available.
+
+```typescript
+const boundary = chart.getEffectiveDataBoundary(); // number | null
+```
+
+### Cache Management
+
+```typescript
+// Clear all cached historical data and baseline prices
+chart.clearCache();
+```
+
+### Cleanup
+
+```typescript
+chart.destroy();
+```
+
+## Order Book
+
+### Initialization
+
+The `Orderbook` connects to the exchange WebSocket immediately on construction and begins receiving depth updates.
+
+```typescript
+import { Orderbook, CreateTransport } from '@pear-protocol/market-sdk';
+
+const transport = CreateTransport('hyperliquid');
+
+const orderbook = new Orderbook({
+  transport,
+  symbol: 'BTC',
+  aggregation: 10,
+  depth: 15,
+});
+```
+
+#### `OrderbookConfig`
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `transport` | `Transport` | — | WebSocket transport instance |
+| `symbol` | `string` | — | Trading pair symbol |
+| `aggregation` | `number` | `0` | Bucket size for price aggregation (0 = no aggregation) |
+| `depth` | `number` | `10` | Number of price levels per side |
+| `snapshottedPrice` | `number` | — | Current mid-price for server-side aggregation params |
+
+### Subscribing to Updates
+
+Subscribe to real-time order book snapshots. The callback fires on every depth update from the exchange.
+
+```typescript
+const subId = orderbook.subscribe((snapshot) => {
+  snapshot.symbol;       // "BTC"
+  snapshot.aggregation;  // active bucket size
+  snapshot.ts;           // last update timestamp (ms)
+
+  for (const bid of snapshot.bids) {  // price-descending
+    bid.price;  // price level
+    bid.size;   // base-asset quantity
+  }
+
+  for (const ask of snapshot.asks) {  // price-ascending
+    ask.price;
+    ask.size;
+  }
+});
+
+// Stop receiving updates
+orderbook.unsubscribe(subId);
+```
+
+### Reading the Current Snapshot
+
+Access the latest order book state without subscribing. Returns `null` if no data has been received yet.
+
+```typescript
+const snapshot = orderbook.getSnapshot();
+if (snapshot) {
+  console.log(snapshot.bids, snapshot.asks);
+}
+```
+
+### Changing Aggregation
+
+Change the price aggregation bucket size at any time. Listeners are notified immediately with a re-aggregated snapshot.
+
+```typescript
+orderbook.setAggregation(100);  // aggregate to $100 buckets
+orderbook.setAggregation(0);    // disable aggregation
+
+const current = orderbook.getAggregation();
+```
+
+### Best Bid / Offer (BBO)
+
+Access the current best bid, best ask, spread, and spread percentage. Returns `null` values when the book has not loaded yet.
+
+```typescript
+const { bestBid, bestAsk, spread, spreadPct } = orderbook.bbo;
+// bestBid:    "65000.5" | null
+// bestAsk:    "65001.0" | null
+// spread:     "0.5"     | null
+// spreadPct:  "0.00077" | null
+```
+
+### Available Aggregation Levels
+
+Compute recommended aggregation bucket sizes for a given connector and price level.
+
+```typescript
+import { getAvailableAggregations } from '@pear-protocol/market-sdk';
+
+// CEX exchanges (Binance, Bybit, OKX) — uses tick size
+const levels = getAvailableAggregations('binance', { tickSize: 0.1, midPrice: 65000 });
+// e.g. [0.1, 1, 10, 100, 1000]
+
+// Hyperliquid — uses max decimal places
+const levels = getAvailableAggregations('hyperliquid', { maxDecimals: 2, midPrice: 65000 });
+```
+
+### Updating Snapshotted Price
+
+Update the mid-price used for server-side aggregation parameters (e.g. Hyperliquid).
+
+```typescript
+orderbook.setSnapshottedPrice(65250.5);
+```
+
+### Cleanup
+
+```typescript
+orderbook.destroy();
+```
+
+The underlying transport is owned by the caller and must be destroyed separately.
+
+## Transport
+
+Both `Chart` and `Orderbook` require a `Transport` instance for WebSocket communication. A single transport can be shared across multiple consumers on the same exchange.
+
+```typescript
+import { CreateTransport } from '@pear-protocol/market-sdk';
+
+const transport = CreateTransport('hyperliquid');
+
+// Use with Chart and Orderbook
+const chart = new Chart({ transport, /* ... */ });
+const orderbook = new Orderbook({ transport, symbol: 'BTC' });
+
+// Cleanup — destroy transport after all consumers
+chart.destroy();
+orderbook.destroy();
+transport.destroy();
+```

package/dist/chart/cache/index.d.ts

@@ -0,0 +1,21 @@
+import { CandleInterval, CandleData, HistoricalRange } from '../types.js';
+import '../../transport/index.js';
+import '@pear-protocol/types';
+import '../../transport/base-transport.js';
+import 'partysocket';
+import '../../shared/types.js';
+
+declare class CandleCache {
+    private historicalPriceData;
+    private loadingTokens;
+    addLoadingToken(symbol: string): void;
+    removeLoadingToken(symbol: string): void;
+    addHistoricalPriceData(symbol: string, interval: CandleInterval, candles: CandleData[], range: HistoricalRange): void;
+    hasData(symbol: string, interval: CandleInterval, startTime: number, endTime: number): boolean;
+    getData(symbol: string, interval: CandleInterval, startTime: number, endTime: number): CandleData[];
+    getEffectiveBoundary(symbols: string[], interval: CandleInterval): number | null;
+    removeToken(symbol: string, interval: CandleInterval): void;
+    clear(): void;
+}
+
+export { CandleCache };

package/dist/chart/cache/index.js

@@ -0,0 +1,101 @@
+import { createKey, mergeRanges, getIntervalSeconds } from '../utils';
+
+class CandleCache {
+  historicalPriceData = {};
+  loadingTokens = /* @__PURE__ */ new Set();
+  addLoadingToken(symbol) {
+    this.loadingTokens.add(symbol);
+  }
+  removeLoadingToken(symbol) {
+    this.loadingTokens.delete(symbol);
+  }
+  addHistoricalPriceData(symbol, interval, candles, range) {
+    const key = createKey(symbol, interval);
+    const existing = this.historicalPriceData[key];
+    if (!existing) {
+      const sortedCandles = [...candles].sort((a, b) => a.t - b.t);
+      const noDataBefore2 = sortedCandles.length === 0 ? range.end : null;
+      this.historicalPriceData[key] = {
+        symbol,
+        interval,
+        candles: sortedCandles,
+        oldestTime: sortedCandles.length > 0 ? sortedCandles[0]?.t ?? null : null,
+        latestTime: sortedCandles.length > 0 ? sortedCandles[sortedCandles.length - 1]?.t ?? null : null,
+        requestedRanges: [range],
+        noDataBefore: noDataBefore2
+      };
+      return;
+    }
+    const existingTimes = new Set(existing.candles.map((c) => c.t));
+    const newCandles = candles.filter((c) => !existingTimes.has(c.t));
+    const mergedCandles = [...existing.candles, ...newCandles].sort((a, b) => a.t - b.t);
+    const oldestTime = mergedCandles.length > 0 ? mergedCandles[0]?.t ?? null : null;
+    const latestTime = mergedCandles.length > 0 ? mergedCandles[mergedCandles.length - 1]?.t ?? null : null;
+    const mergedRanges = mergeRanges(existing.requestedRanges, range);
+    let noDataBefore = existing.noDataBefore;
+    if (candles.length === 0 && existing.oldestTime !== null && range.end <= existing.oldestTime) {
+      noDataBefore = existing.oldestTime;
+    }
+    this.historicalPriceData[key] = {
+      ...existing,
+      candles: mergedCandles,
+      oldestTime,
+      latestTime,
+      requestedRanges: mergedRanges,
+      noDataBefore
+    };
+  }
+  hasData(symbol, interval, startTime, endTime) {
+    const key = createKey(symbol, interval);
+    const tokenData = this.historicalPriceData[key];
+    if (!tokenData) return false;
+    if (tokenData.noDataBefore !== null && endTime <= tokenData.noDataBefore) {
+      return true;
+    }
+    for (const range of tokenData.requestedRanges) {
+      if (range.start <= startTime && range.end >= endTime) {
+        return true;
+      }
+    }
+    if (tokenData.oldestTime === null || tokenData.latestTime === null) {
+      return false;
+    }
+    const intervalMs = getIntervalSeconds(interval) * 1e3;
+    const hasStartCoverage = tokenData.oldestTime <= startTime;
+    const hasEndCoverage = tokenData.latestTime >= endTime || tokenData.latestTime + intervalMs >= endTime;
+    return hasStartCoverage && hasEndCoverage;
+  }
+  getData(symbol, interval, startTime, endTime) {
+    const key = createKey(symbol, interval);
+    const tokenData = this.historicalPriceData[key];
+    if (!tokenData) return [];
+    return tokenData.candles.filter((candle) => candle.t >= startTime && candle.t < endTime);
+  }
+  getEffectiveBoundary(symbols, interval) {
+    if (symbols.length === 0) return null;
+    let maxBoundary = null;
+    for (const symbol of symbols) {
+      const key = createKey(symbol, interval);
+      const tokenData = this.historicalPriceData[key];
+      if (!tokenData) continue;
+      const boundary = tokenData.noDataBefore ?? tokenData.oldestTime;
+      if (boundary !== null) {
+        if (maxBoundary === null || boundary > maxBoundary) {
+          maxBoundary = boundary;
+        }
+      }
+    }
+    return maxBoundary;
+  }
+  removeToken(symbol, interval) {
+    const key = createKey(symbol, interval);
+    delete this.historicalPriceData[key];
+    this.loadingTokens.delete(symbol);
+  }
+  clear() {
+    this.historicalPriceData = {};
+    this.loadingTokens = /* @__PURE__ */ new Set();
+  }
+}
+
+export { CandleCache };

package/dist/chart/chart.d.ts

@@ -0,0 +1,25 @@
+import { ChartConfig, TokenSelection, CandleInterval, ChartType, Bar, RealtimeBarCallback } from './types.js';
+import '../transport/index.js';
+import '@pear-protocol/types';
+import '../transport/base-transport.js';
+import 'partysocket';
+import '../shared/types.js';
+
+declare class Chart {
+    private collector;
+    private baselinePrices;
+    constructor(config: ChartConfig);
+    setTokens(longTokens: TokenSelection[], shortTokens: TokenSelection[]): void;
+    setCandleInterval(interval: CandleInterval): void;
+    getBars(chartType: ChartType, startTime: number, endTime: number): Promise<Bar[]>;
+    getAssetBars(symbol: string, startTime: number, endTime: number): Promise<Bar[]>;
+    getEffectiveDataBoundary(): number | null;
+    subscribeRealtimeBars(chartType: ChartType, callback: RealtimeBarCallback): string;
+    subscribeRealtimeAssetBars(symbol: string, callback: RealtimeBarCallback): string;
+    unsubscribeRealtimeBars(id: string): void;
+    private assertTokenExists;
+    clearCache(): void;
+    destroy(): void;
+}
+
+export { Chart };

package/dist/chart/chart.js

@@ -0,0 +1,141 @@
+import { DataCollector } from './collector';
+import { computePerformanceCandles, computePriceRatioCandles, computeWeightedRatioCandles, computeAssetBars, computeRealtimePerformanceBar, computeRealtimePriceRatioBar, computeRealtimeWeightedRatioBar, computeRealtimeAssetBar } from './compute/index';
+
+class Chart {
+  collector;
+  baselinePrices = {};
+  constructor(config) {
+    this.collector = new DataCollector(config);
+  }
+  setTokens(longTokens, shortTokens) {
+    this.collector.setTokens(longTokens, shortTokens);
+    this.baselinePrices = {};
+  }
+  setCandleInterval(interval) {
+    this.collector.setCandleInterval(interval);
+    this.baselinePrices = {};
+  }
+  async getBars(chartType, startTime, endTime) {
+    const interval = this.collector.getCandleInterval();
+    const tokenCandles = await this.collector.fetchHistoricalPriceData(startTime, endTime, interval);
+    switch (chartType) {
+      case "weighted-ratio": {
+        return computeWeightedRatioCandles(
+          this.collector.getLongTokens(),
+          this.collector.getShortTokens(),
+          tokenCandles
+        );
+      }
+      case "price-ratio": {
+        return computePriceRatioCandles(this.collector.getLongTokens(), this.collector.getShortTokens(), tokenCandles);
+      }
+      case "performance": {
+        const result = computePerformanceCandles(
+          this.collector.getLongTokens(),
+          this.collector.getShortTokens(),
+          tokenCandles
+        );
+        if (result.bars.length > 0) {
+          this.baselinePrices = result.baselinePrices;
+        }
+        return result.bars;
+      }
+      default:
+        throw new Error(`Unsupported chart type: ${chartType}`);
+    }
+  }
+  async getAssetBars(symbol, startTime, endTime) {
+    this.assertTokenExists(symbol);
+    const interval = this.collector.getCandleInterval();
+    const tokenCandles = await this.collector.fetchHistoricalPriceData(startTime, endTime, interval);
+    return computeAssetBars(tokenCandles, symbol);
+  }
+  getEffectiveDataBoundary() {
+    return this.collector.getEffectiveDataBoundary(this.collector.getCandleInterval());
+  }
+  subscribeRealtimeBars(chartType, callback) {
+    if (!this.collector.isWsAttached) {
+      this.collector.attachCandleWs();
+    }
+    const formatTokens = (tokens) => tokens.map((t) => `${t.symbol}:${t.weight}`).join(",");
+    const id = `${chartType}-${formatTokens(this.collector.getLongTokens())}-${formatTokens(this.collector.getShortTokens())}`;
+    this.collector.addRealtimeListener(id, () => {
+      const snapshot = this.collector.getLatestCandles();
+      if (!snapshot) return;
+      let bar = null;
+      switch (chartType) {
+        case "weighted-ratio":
+          bar = computeRealtimeWeightedRatioBar(
+            this.collector.getLongTokens(),
+            this.collector.getShortTokens(),
+            snapshot
+          );
+          break;
+        case "price-ratio":
+          bar = computeRealtimePriceRatioBar(this.collector.getLongTokens(), this.collector.getShortTokens(), snapshot);
+          break;
+        case "performance":
+          if (Object.keys(this.baselinePrices).length === 0) break;
+          bar = computeRealtimePerformanceBar(
+            this.collector.getLongTokens(),
+            this.collector.getShortTokens(),
+            snapshot,
+            this.baselinePrices
+          );
+          break;
+      }
+      if (bar) {
+        try {
+          callback(bar);
+        } catch (error) {
+          console.warn("Error in realtime bar callback, skipping this update", {
+            chartType,
+            error
+          });
+        }
+      }
+    });
+    return id;
+  }
+  subscribeRealtimeAssetBars(symbol, callback) {
+    this.assertTokenExists(symbol);
+    if (!this.collector.isWsAttached) {
+      this.collector.attachCandleWs();
+    }
+    const id = `price-${symbol}`;
+    this.collector.addRealtimeListener(id, () => {
+      const snapshot = this.collector.getLatestCandles();
+      if (!snapshot) return;
+      const bar = computeRealtimeAssetBar(snapshot, symbol);
+      if (bar) {
+        try {
+          callback(bar);
+        } catch (error) {
+          console.warn("Error in realtime asset bar callback, skipping this update", {
+            symbol,
+            error
+          });
+        }
+      }
+    });
+    return id;
+  }
+  unsubscribeRealtimeBars(id) {
+    this.collector.removeRealtimeListener(id);
+  }
+  assertTokenExists(symbol) {
+    const allTokens = [...this.collector.getLongTokens(), ...this.collector.getShortTokens()];
+    if (!allTokens.some((t) => t.symbol === symbol)) {
+      throw new Error(`Symbol "${symbol}" is not part of the configured long or short tokens`);
+    }
+  }
+  clearCache() {
+    this.collector.clearCache();
+    this.baselinePrices = {};
+  }
+  destroy() {
+    this.collector.destroy();
+  }
+}
+
+export { Chart };

package/dist/chart/collector/binance.d.ts

@@ -0,0 +1,10 @@
+import { CandleInterval, CandleData } from '../types.js';
+import '../../transport/index.js';
+import '@pear-protocol/types';
+import '../../transport/base-transport.js';
+import 'partysocket';
+import '../../shared/types.js';
+
+declare function fetchHistoricalCandles(symbol: string, startTime: number, endTime: number, interval: CandleInterval): Promise<CandleData[]>;
+
+export { fetchHistoricalCandles };

package/dist/chart/collector/binance.js

@@ -0,0 +1,27 @@
+const BINANCE_FUTURES_URL = "https://fapi.binance.com/fapi/v1/klines";
+const MAX_LIMIT = 1e3;
+function toCandleData(kline) {
+  return {
+    t: kline[0],
+    T: kline[6],
+    o: Number(kline[1]),
+    h: Number(kline[2]),
+    l: Number(kline[3]),
+    c: Number(kline[4])
+  };
+}
+async function fetchHistoricalCandles(symbol, startTime, endTime, interval) {
+  const params = new URLSearchParams({
+    symbol,
+    interval,
+    startTime: String(startTime),
+    endTime: String(endTime),
+    limit: String(MAX_LIMIT)
+  });
+  const response = await fetch(`${BINANCE_FUTURES_URL}?${params}`);
+  if (!response.ok) throw new Error(`Binance API error: ${response.status} ${response.statusText}`);
+  const data = await response.json();
+  return data.map(toCandleData);
+}
+
+export { fetchHistoricalCandles };

package/dist/chart/collector/bybit.d.ts

@@ -0,0 +1,10 @@
+import { CandleInterval, CandleData } from '../types.js';
+import '../../transport/index.js';
+import '@pear-protocol/types';
+import '../../transport/base-transport.js';
+import 'partysocket';
+import '../../shared/types.js';
+
+declare function fetchHistoricalCandles(symbol: string, startTime: number, endTime: number, interval: CandleInterval): Promise<CandleData[]>;
+
+export { fetchHistoricalCandles };

package/dist/chart/collector/bybit.js

@@ -0,0 +1,39 @@
+const BYBIT_URL = "https://api.bybit.com/v5/market/kline";
+const MAX_LIMIT = 1e3;
+const intervalMap = {
+  "1m": "1",
+  "3m": "3",
+  "5m": "5",
+  "15m": "15",
+  "30m": "30",
+  "1h": "60",
+  "2h": "120",
+  "4h": "240",
+  "8h": "480",
+  "12h": "720",
+  "1d": "D",
+  "3d": "D",
+  "1w": "W",
+  "1M": "M"
+};
+function toCandleData(item) {
+  const startMs = Number(item[0]);
+  return { t: startMs, T: startMs, o: Number(item[1]), h: Number(item[2]), l: Number(item[3]), c: Number(item[4]) };
+}
+async function fetchHistoricalCandles(symbol, startTime, endTime, interval) {
+  const params = new URLSearchParams({
+    category: "linear",
+    symbol,
+    interval: intervalMap[interval],
+    start: String(startTime),
+    end: String(endTime),
+    limit: String(MAX_LIMIT)
+  });
+  const response = await fetch(`${BYBIT_URL}?${params}`);
+  if (!response.ok) throw new Error(`Bybit API error: ${response.status} ${response.statusText}`);
+  const data = await response.json();
+  if (data.retCode !== 0) throw new Error(`Bybit API error: ${data.retMsg}`);
+  return data.result.list.reverse().map((item) => toCandleData(item));
+}
+
+export { fetchHistoricalCandles };