@pear-protocol/market-sdk 0.0.4 → 0.0.6

package/README.md

@@ -1,6 +1,6 @@
 # @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.
+SDK for real-time market data across cryptocurrency derivative exchanges. Provides charting with multiple visualization modes (weighted ratio, price ratio, performance), aggregated order book depth, and historical funding rate analysis through a unified, exchange-agnostic interface.
 
 ## Supported Exchanges
 
@@ -10,6 +10,7 @@ SDK for real-time market data across cryptocurrency derivative exchanges. Provid
 | Bybit | `bybit` |
 | Hyperliquid | `hyperliquid` |
 | OKX | `okx` |
+| Lighter | `lighter` |
 
 ## Installation
 
@@ -20,7 +21,7 @@ npm install @pear-protocol/market-sdk
 ## Quick Start
 
 ```typescript
-import { Chart, Orderbook, CreateTransport } from '@pear-protocol/market-sdk';
+import { Chart, FundingRate, Orderbook, CreateTransport } from '@pear-protocol/market-sdk';
 
 const transport = CreateTransport('hyperliquid');
 
@@ -38,6 +39,17 @@ const subId = chart.subscribeRealtimeBars('weighted-ratio', (bar) => {
   console.log(bar.time, bar.open, bar.high, bar.low, bar.close);
 });
 
+// Funding rates
+const fundingRate = new FundingRate({
+  transport,
+  longTokens: [{ symbol: 'ETH', weight: 0.6 }],
+  shortTokens: [{ symbol: 'BTC', weight: 0.4 }],
+  interval: '1d',
+});
+
+const rates = await fundingRate.getAssetRates('ETH');
+const basketRates = await fundingRate.getBasketRates();
+
 // Order book
 const orderbook = new Orderbook({
   transport,
@@ -53,6 +65,7 @@ orderbook.subscribe((snapshot) => {
 // Cleanup
 chart.unsubscribeRealtimeBars(subId);
 chart.destroy();
+fundingRate.destroy();
 orderbook.destroy();
 transport.destroy();
 ```
@@ -299,21 +312,133 @@ orderbook.destroy();
 
 The underlying transport is owned by the caller and must be destroyed separately.
 
-## Transport
+## Funding Rate
 
-Both `Chart` and `Orderbook` require a `Transport` instance for WebSocket communication. A single transport can be shared across multiple consumers on the same exchange.
+### Initialization
 
 ```typescript
-import { CreateTransport } from '@pear-protocol/market-sdk';
+import { FundingRate, 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' });
+const fundingRate = new FundingRate({
+  transport,
+  longTokens: [{ symbol: 'ETH', weight: 0.6 }],
+  shortTokens: [{ symbol: 'BTC', weight: 0.4 }],
+});
+```
+
+#### `FundingRateConfig`
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `transport` | `Transport` | — | Transport instance (used to determine the exchange) |
+| `longTokens` | `TokenSelection[]` | `[]` | Tokens on the long side with weights |
+| `shortTokens` | `TokenSelection[]` | `[]` | Tokens on the short side with weights |
+
+### Aggregation and Duration
+
+Aggregation level and lookback duration are passed per call to `getAssetRates` and `getBasketRates`.
+
+#### `FundingRateAggregation`
+
+```typescript
+'none' | '1d' | '1w' | '1M'
+```
+
+When set to `'none'`, raw funding rates are returned at each exchange's native settlement frequency (1h for Hyperliquid, 8h for Binance/Bybit/OKX). For `'1d'`, `'1w'`, and `'1M'`, rates are summed within each period.
+
+#### `FundingRateDuration`
+
+```typescript
+'1w' | '1m' | '1y'
+```
+
+The lookback window for fetching data, ending at the current time.
+
+#### Minimum Duration per Aggregation
+
+To avoid returning too few data points, each aggregation level enforces a minimum duration. If the requested duration is shorter than the minimum, it is automatically bumped up.
+
+| Aggregation | Minimum Duration |
+|-------------|------------------|
+| `'none'`    | `'1w'`           |
+| `'1d'`      | `'1m'`           |
+| `'1w'`      | `'1y'`           |
+| `'1M'`      | `'1y'`           |
+
+### Per-Asset Funding Rates
+
+Fetch funding rates for a single token.
+
+```typescript
+// Defaults: aggregation='none', duration='1m'
+const rates = await fundingRate.getAssetRates('ETH');
+
+// Daily aggregation over the last year
+const dailyRates = await fundingRate.getAssetRates('ETH', '1d', '1y');
+```
+
+#### Signature
+
+```typescript
+getAssetRates(
+  symbol: string,
+  aggregation?: FundingRateAggregation,  // default: 'none'
+  duration?: FundingRateDuration,        // default: '1m'
+): Promise<FundingRateEntry[]>
+```
+
+### Basket Funding Rates
+
+Compute the weighted net funding rate across all configured tokens. Positive rate = user earns funding, negative = user pays.
+
+```typescript
+const basketRates = await fundingRate.getBasketRates();
+
+const monthlyBasket = await fundingRate.getBasketRates('1M', '1y');
+```
+
+The net rate at each time point is calculated as:
 
-// Cleanup — destroy transport after all consumers
-chart.destroy();
-orderbook.destroy();
-transport.destroy();
 ```
+netRate = sum(shortWeight × rate) - sum(longWeight × rate)
+```
+
+Only time points where all tokens have data are included.
+
+#### Signature
+
+```typescript
+getBasketRates(
+  aggregation?: FundingRateAggregation,  // default: 'none'
+  duration?: FundingRateDuration,        // default: '1m'
+): Promise<FundingRateEntry[]>
+```
+
+### `FundingRateEntry`
+
+```typescript
+{
+  time: number;             // bucket start timestamp (ms)
+  rate: number;             // summed rate for the bucket (raw rate when aggregation='none')
+  annualizedRate?: number;  // rate annualized to a yearly figure
+}
+```
+
+For fixed aggregations the annualization multiplier is `365` (`1d`), `52` (`1w`), or `12` (`1M`). For `'none'`, the multiplier is inferred from the average gap between raw entries (`MS_PER_YEAR / avgGapMs`); if there are fewer than two entries to infer from, `annualizedRate` is omitted.
+
+### Updating Tokens
+
+```typescript
+fundingRate.setTokens(
+  [{ symbol: 'ETH', weight: 0.5 }, { symbol: 'SOL', weight: 0.5 }],
+  [{ symbol: 'BTC', weight: 1.0 }],
+);
+```
+
+### Cleanup
+
+```typescript
+fundingRate.destroy();
+```

package/dist/funding-rate/fetcher/binance.d.ts

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

package/dist/funding-rate/fetcher/binance.js

@@ -0,0 +1,26 @@
+import { httpGet } from './http-client';
+
+const BINANCE_FUTURES_URL = "https://fapi.binance.com/fapi/v1/fundingRate";
+const MAX_LIMIT = 1e3;
+async function fetchHistoricalFundingRates(symbol, startTime, endTime) {
+  const allRates = [];
+  let cursor = startTime;
+  while (cursor < endTime) {
+    const data = await httpGet(BINANCE_FUTURES_URL, {
+      symbol,
+      startTime: String(cursor),
+      endTime: String(endTime),
+      limit: String(MAX_LIMIT)
+    });
+    if (data.length === 0) break;
+    for (const entry of data) {
+      allRates.push({ time: entry.fundingTime, rate: Number(entry.fundingRate) });
+    }
+    const lastTime = data[data.length - 1]?.fundingTime;
+    if (!lastTime || lastTime <= cursor) break;
+    cursor = lastTime + 1;
+  }
+  return allRates.sort((a, b) => a.time - b.time);
+}
+
+export { fetchHistoricalFundingRates };

package/dist/funding-rate/fetcher/bybit.d.ts

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

package/dist/funding-rate/fetcher/bybit.js

@@ -0,0 +1,32 @@
+import { httpGet } from './http-client';
+
+const BYBIT_URL = "https://api.bybit.com/v5/market/funding/history";
+const MAX_LIMIT = 200;
+async function fetchHistoricalFundingRates(symbol, startTime, endTime) {
+  const allRates = [];
+  let cursor = endTime;
+  const validate = (d) => d.retCode !== 0 ? `Bybit API error: ${d.retMsg}` : void 0;
+  while (cursor > startTime) {
+    const data = await httpGet(
+      BYBIT_URL,
+      {
+        category: "linear",
+        symbol,
+        startTime: String(startTime),
+        endTime: String(cursor),
+        limit: String(MAX_LIMIT)
+      },
+      validate
+    );
+    if (data.result.list.length === 0) break;
+    for (const entry of data.result.list) {
+      allRates.push({ time: Number(entry.fundingRateTimestamp), rate: Number(entry.fundingRate) });
+    }
+    const oldestTime = Number(data.result.list[data.result.list.length - 1]?.fundingRateTimestamp);
+    if (!oldestTime || oldestTime >= cursor) break;
+    cursor = oldestTime - 1;
+  }
+  return allRates.sort((a, b) => a.time - b.time);
+}
+
+export { fetchHistoricalFundingRates };

package/dist/funding-rate/fetcher/http-client.d.ts

@@ -0,0 +1,5 @@
+type ResponseValidator<T> = (data: T) => string | undefined;
+declare function httpGet<T>(url: string, params: Record<string, string>, validate?: ResponseValidator<T>): Promise<T>;
+declare function httpPost<T>(url: string, body: unknown, validate?: ResponseValidator<T>): Promise<T>;
+
+export { type ResponseValidator, httpGet, httpPost };

package/dist/funding-rate/fetcher/http-client.js

@@ -0,0 +1,40 @@
+const BASE_DELAY_MS = 1e3;
+const MAX_DELAY_MS = 6e4;
+async function httpGet(url, params, validate) {
+  const qs = new URLSearchParams(params).toString();
+  return httpFetch(`${url}?${qs}`, void 0, validate);
+}
+async function httpPost(url, body, validate) {
+  return httpFetch(
+    url,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    },
+    validate
+  );
+}
+async function httpFetch(url, init, validate) {
+  let attempt = 0;
+  while (true) {
+    const response = await fetch(url, init);
+    if (response.status === 429) {
+      const delay = Math.min(BASE_DELAY_MS * 2 ** attempt, MAX_DELAY_MS);
+      attempt++;
+      await new Promise((resolve) => setTimeout(resolve, delay));
+      continue;
+    }
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status} ${response.statusText} from ${url}`);
+    }
+    const data = await response.json();
+    if (validate) {
+      const error = validate(data);
+      if (error) throw new Error(error);
+    }
+    return data;
+  }
+}
+
+export { httpGet, httpPost };

package/dist/funding-rate/fetcher/hyperliquid.d.ts

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

package/dist/funding-rate/fetcher/hyperliquid.js

@@ -0,0 +1,25 @@
+import { httpPost } from './http-client';
+
+async function fetchHistoricalFundingRates(symbol, startTime, endTime) {
+  const allRates = [];
+  let cursor = startTime;
+  while (cursor < endTime) {
+    const data = await httpPost("https://api.hyperliquid.xyz/info", {
+      type: "fundingHistory",
+      coin: symbol,
+      startTime: cursor,
+      endTime
+    });
+    if (data.length === 0) break;
+    for (const entry of data) {
+      if (entry.time >= endTime) continue;
+      allRates.push({ time: entry.time, rate: Number(entry.fundingRate) });
+    }
+    const lastTime = data[data.length - 1]?.time;
+    if (!lastTime || lastTime <= cursor) break;
+    cursor = lastTime + 1;
+  }
+  return allRates.sort((a, b) => a.time - b.time);
+}
+
+export { fetchHistoricalFundingRates };

package/dist/funding-rate/fetcher/index.d.ts

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

package/dist/funding-rate/fetcher/index.js

@@ -0,0 +1,24 @@
+import { fetchHistoricalFundingRates as fetchHistoricalFundingRates$4 } from './binance';
+import { fetchHistoricalFundingRates as fetchHistoricalFundingRates$3 } from './bybit';
+import { fetchHistoricalFundingRates as fetchHistoricalFundingRates$5 } from './hyperliquid';
+import { fetchHistoricalFundingRates as fetchHistoricalFundingRates$1 } from './lighter';
+import { fetchHistoricalFundingRates as fetchHistoricalFundingRates$2 } from './okx';
+
+async function fetchHistoricalFundingRates(connector, symbol, startTime, endTime, duration) {
+  switch (connector) {
+    case "hyperliquid":
+      return fetchHistoricalFundingRates$5(symbol, startTime, endTime);
+    case "binance":
+      return fetchHistoricalFundingRates$4(symbol, startTime, endTime);
+    case "bybit":
+      return fetchHistoricalFundingRates$3(symbol, startTime, endTime);
+    case "okx":
+      return fetchHistoricalFundingRates$2(symbol, startTime, endTime);
+    case "lighter":
+      return fetchHistoricalFundingRates$1(symbol, startTime, endTime, duration);
+    default:
+      throw new Error(`Unsupported connector: ${connector}`);
+  }
+}
+
+export { fetchHistoricalFundingRates };

package/dist/funding-rate/fetcher/lighter.d.ts

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

package/dist/funding-rate/fetcher/lighter.js

@@ -0,0 +1,35 @@
+import BigNumber from 'bignumber.js';
+import { httpGet } from './http-client';
+
+const BASE_URL = "https://mainnet.zklighter.elliot.ai";
+const MAX_LIMIT = 500;
+async function fetchHistoricalFundingRates(symbol, startTime, endTime, _duration) {
+  const intervalMs = 60 * 60 * 1e3;
+  const allRates = [];
+  let cursor = startTime;
+  while (cursor < endTime) {
+    const countBack = Math.min(Math.ceil((endTime - cursor) / intervalMs) + 1, MAX_LIMIT);
+    const data = await httpGet(`${BASE_URL}/api/v1/fundings`, {
+      market_id: symbol,
+      resolution: "1h",
+      start_timestamp: String(cursor),
+      end_timestamp: String(endTime),
+      count_back: String(countBack)
+    });
+    const entries = data.fundings ?? [];
+    if (entries.length === 0) break;
+    for (const entry of entries) {
+      const timeMs = entry.timestamp * 1e3;
+      const rate = entry.rate ? new BigNumber(entry.rate).dividedBy(100).times(entry.direction === "long" ? -1 : 1).toNumber() : 0;
+      allRates.push({ time: timeMs, rate });
+    }
+    const lastTimestamp = entries[entries.length - 1]?.timestamp;
+    if (!lastTimestamp) break;
+    const lastTimeMs = lastTimestamp * 1e3;
+    if (lastTimeMs <= cursor) break;
+    cursor = lastTimeMs + 1;
+  }
+  return allRates.sort((a, b) => a.time - b.time);
+}
+
+export { fetchHistoricalFundingRates };

package/dist/funding-rate/fetcher/okx.d.ts

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

package/dist/funding-rate/fetcher/okx.js

@@ -0,0 +1,33 @@
+import { httpGet } from './http-client';
+
+const OKX_URL = "https://www.okx.com/api/v5/public/funding-rate-history";
+const MAX_LIMIT = 400;
+async function fetchHistoricalFundingRates(instId, startTime, endTime) {
+  const allRates = [];
+  let cursor = endTime;
+  const validate = (d) => d.code !== "0" ? `OKX API error: ${d.msg}` : void 0;
+  while (cursor > startTime) {
+    const data = await httpGet(
+      OKX_URL,
+      {
+        instId,
+        before: String(startTime),
+        after: String(cursor),
+        limit: String(MAX_LIMIT)
+      },
+      validate
+    );
+    if (data.data.length === 0) break;
+    let oldestTime = Infinity;
+    for (const entry of data.data) {
+      const time = Number(entry.fundingTime);
+      allRates.push({ time, rate: Number(entry.realizedRate) });
+      if (time < oldestTime) oldestTime = time;
+    }
+    if (oldestTime >= cursor) break;
+    cursor = oldestTime - 1;
+  }
+  return allRates.filter((r) => r.time >= startTime && r.time < endTime).sort((a, b) => a.time - b.time);
+}
+
+export { fetchHistoricalFundingRates };

package/dist/funding-rate/funding-rate.d.ts

@@ -0,0 +1,28 @@
+import { FundingRateConfig, TokenSelection, FundingRateAggregation, FundingRateDuration, FundingRateEntry } from './types.js';
+import '../transport/index.js';
+import '@pear-protocol/types';
+import '../transport/base-transport.js';
+import 'partysocket';
+import '../shared/types.js';
+
+declare class FundingRate {
+    private transport;
+    private longTokens;
+    private shortTokens;
+    private cache;
+    constructor(config: FundingRateConfig);
+    setTokens(longTokens: TokenSelection[], shortTokens: TokenSelection[]): void;
+    clearCache(): void;
+    destroy(): void;
+    getAssetRates(symbol: string, aggregation?: FundingRateAggregation, duration?: FundingRateDuration): Promise<FundingRateEntry[]>;
+    getBasketRates(aggregation?: FundingRateAggregation, duration?: FundingRateDuration): Promise<FundingRateEntry[]>;
+    private resolveAggregation;
+    private loadRates;
+    private getUncachedTokens;
+    private sliceCache;
+    private refetch;
+    private getAllTokens;
+    private assertTokenExists;
+}
+
+export { FundingRate };

package/dist/funding-rate/funding-rate.js

@@ -0,0 +1,117 @@
+import { fetchHistoricalFundingRates } from './fetcher';
+import { aggregateRates, annualizeRates, computeBasketRates, computeStartTime } from './utils';
+
+const DEFAULT_AGGREGATION = "1d";
+const DEFAULT_DURATION = "1m";
+class FundingRate {
+  transport;
+  longTokens;
+  shortTokens;
+  cache = {};
+  constructor(config) {
+    this.transport = config.transport;
+    this.longTokens = config.longTokens ?? [];
+    this.shortTokens = config.shortTokens ?? [];
+  }
+  setTokens(longTokens, shortTokens) {
+    const prevSymbols = new Set(this.getAllTokens().map((t) => t.symbol));
+    this.longTokens = longTokens;
+    this.shortTokens = shortTokens;
+    const nextSymbols = new Set(this.getAllTokens().map((t) => t.symbol));
+    for (const symbol of Object.keys(this.cache)) {
+      if (!nextSymbols.has(symbol)) {
+        delete this.cache[symbol];
+      }
+    }
+    for (const symbol of nextSymbols) {
+      if (!prevSymbols.has(symbol)) {
+        delete this.cache[symbol];
+      }
+    }
+  }
+  clearCache() {
+    this.cache = {};
+  }
+  destroy() {
+    this.clearCache();
+  }
+  async getAssetRates(symbol, aggregation = DEFAULT_AGGREGATION, duration = DEFAULT_DURATION) {
+    this.assertTokenExists(symbol);
+    const resolvedAgg = this.resolveAggregation(aggregation, duration);
+    const rawByToken = await this.loadRates(duration);
+    const raw = rawByToken[symbol] ?? [];
+    const aggregated = aggregateRates(raw, resolvedAgg);
+    return annualizeRates(aggregated, resolvedAgg, raw);
+  }
+  async getBasketRates(aggregation = DEFAULT_AGGREGATION, duration = DEFAULT_DURATION) {
+    const resolvedAgg = this.resolveAggregation(aggregation, duration);
+    const rawByToken = await this.loadRates(duration);
+    const aggregatedByToken = {};
+    for (const [symbol, entries] of Object.entries(rawByToken)) {
+      aggregatedByToken[symbol] = aggregateRates(entries, resolvedAgg);
+    }
+    const basket = computeBasketRates(this.longTokens, this.shortTokens, aggregatedByToken);
+    const rawSample = Object.values(rawByToken)[0];
+    return annualizeRates(basket, resolvedAgg, rawSample);
+  }
+  resolveAggregation(aggregation, duration) {
+    if (duration === "1y" && aggregation === "none") return "1d";
+    return aggregation;
+  }
+  async loadRates(duration) {
+    const end = Math.floor(Date.now() / 36e5) * 36e5;
+    const start = computeStartTime(end, duration);
+    const uncached = this.getUncachedTokens(start, end);
+    if (uncached.length > 0) {
+      await this.refetch(uncached, start, end, duration);
+    }
+    return this.sliceCache(start, end);
+  }
+  getUncachedTokens(start, end) {
+    return this.getAllTokens().filter((t) => {
+      const cached = this.cache[t.symbol];
+      if (!cached) return true;
+      return cached.start > start || cached.end < end;
+    });
+  }
+  sliceCache(start, end) {
+    const result = {};
+    for (const [symbol, cached] of Object.entries(this.cache)) {
+      result[symbol] = cached.entries.filter((r) => r.time >= start && r.time <= end);
+    }
+    return result;
+  }
+  async refetch(tokens, start, end, duration) {
+    if (tokens.length === 0) return;
+    await Promise.all(
+      tokens.map(async (token) => {
+        const existing = this.cache[token.symbol];
+        const fetchStart = existing ? Math.min(start, existing.start) : start;
+        const fetchEnd = existing ? Math.max(end, existing.end) : end;
+        try {
+          const rates = await fetchHistoricalFundingRates(
+            this.transport.connector,
+            token.symbol,
+            fetchStart,
+            fetchEnd,
+            duration
+          );
+          this.cache[token.symbol] = { entries: rates, start: fetchStart, end: fetchEnd };
+        } catch (error) {
+          console.warn(`Failed to fetch funding rate data for ${token.symbol}:`, error);
+          this.cache[token.symbol] = { entries: [], start: fetchStart, end: fetchEnd };
+        }
+      })
+    );
+  }
+  getAllTokens() {
+    return [...this.longTokens, ...this.shortTokens];
+  }
+  assertTokenExists(symbol) {
+    if (!this.getAllTokens().some((t) => t.symbol === symbol)) {
+      throw new Error(`Symbol "${symbol}" is not part of the configured long or short tokens`);
+    }
+  }
+}
+
+export { FundingRate };

package/dist/funding-rate/types.d.ts

@@ -0,0 +1,29 @@
+import { Transport } from '../transport/index.js';
+import '@pear-protocol/types';
+import '../transport/base-transport.js';
+import 'partysocket';
+import '../shared/types.js';
+
+interface TokenSelection {
+    symbol: string;
+    weight: number;
+}
+type FundingRateAggregation = 'none' | '1d' | '1w' | '1M';
+type FundingRateDuration = '1w' | '1m' | '1y';
+interface FundingRateEntry {
+    time: number;
+    rate: number;
+    annualizedRate?: number;
+}
+interface FundingRateCacheEntry {
+    entries: FundingRateEntry[];
+    start: number;
+    end: number;
+}
+interface FundingRateConfig {
+    transport: Transport;
+    longTokens?: TokenSelection[];
+    shortTokens?: TokenSelection[];
+}
+
+export type { FundingRateAggregation, FundingRateCacheEntry, FundingRateConfig, FundingRateDuration, FundingRateEntry, TokenSelection };

package/dist/funding-rate/types.js

@@ -0,0 +1 @@
+

package/dist/funding-rate/utils.d.ts

@@ -0,0 +1,13 @@
+import { FundingRateEntry, FundingRateAggregation, TokenSelection, FundingRateDuration } from './types.js';
+import '../transport/index.js';
+import '@pear-protocol/types';
+import '../transport/base-transport.js';
+import 'partysocket';
+import '../shared/types.js';
+
+declare function computeStartTime(endTime: number, duration: FundingRateDuration): number;
+declare function aggregateRates(rawRates: FundingRateEntry[], aggregation: FundingRateAggregation): FundingRateEntry[];
+declare function annualizeRates(entries: FundingRateEntry[], aggregation: FundingRateAggregation, rawEntriesForInference?: FundingRateEntry[]): FundingRateEntry[];
+declare function computeBasketRates(longTokens: TokenSelection[], shortTokens: TokenSelection[], tokenRates: Record<string, FundingRateEntry[]>): FundingRateEntry[];
+
+export { aggregateRates, annualizeRates, computeBasketRates, computeStartTime };

package/dist/funding-rate/utils.js

@@ -0,0 +1,120 @@
+import BigNumber from 'bignumber.js';
+
+function computeStartTime(endTime, duration) {
+  const date = new Date(endTime);
+  switch (duration) {
+    case "1w":
+      return endTime - 7 * 864e5;
+    case "1m":
+      date.setUTCMonth(date.getUTCMonth() - 1);
+      return date.getTime();
+    case "1y":
+      date.setUTCFullYear(date.getUTCFullYear() - 1);
+      return date.getTime();
+  }
+}
+function getBucketStart(timestamp, aggregation) {
+  const date = new Date(timestamp);
+  switch (aggregation) {
+    case "1d":
+      return Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate());
+    case "1w": {
+      const mondayOffset = (date.getUTCDay() + 6) % 7;
+      const monday = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
+      monday.setUTCDate(monday.getUTCDate() - mondayOffset);
+      return monday.getTime();
+    }
+    case "1M":
+      return Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), 1);
+  }
+}
+function aggregateRates(rawRates, aggregation) {
+  if (aggregation === "none") {
+    return [...rawRates].sort((a, b) => a.time - b.time);
+  }
+  const buckets = /* @__PURE__ */ new Map();
+  for (const rate of rawRates) {
+    const key = getBucketStart(rate.time, aggregation);
+    buckets.set(key, (buckets.get(key) ?? new BigNumber(0)).plus(rate.rate));
+  }
+  return Array.from(buckets.entries()).map(([time, rate]) => ({ time, rate: rate.toNumber() })).sort((a, b) => a.time - b.time);
+}
+function inferAvgIntervalMs(entries) {
+  if (entries.length < 2) return null;
+  const sorted = [...entries].sort((a, b) => a.time - b.time);
+  let totalGap = new BigNumber(0);
+  let count = 0;
+  for (let i = 1; i < sorted.length; i++) {
+    const prev = sorted[i - 1];
+    const curr = sorted[i];
+    if (prev === void 0 || curr === void 0) continue;
+    const gap = curr.time - prev.time;
+    if (gap > 0) {
+      totalGap = totalGap.plus(gap);
+      count++;
+    }
+  }
+  return count > 0 ? totalGap.div(count) : null;
+}
+const MS_PER_YEAR = 365 * 864e5;
+function annualizeRates(entries, aggregation, rawEntriesForInference) {
+  let multiplier;
+  if (aggregation === "none") {
+    const sample = rawEntriesForInference ?? entries;
+    const avgMs = inferAvgIntervalMs(sample);
+    if (avgMs === null) return entries;
+    multiplier = new BigNumber(MS_PER_YEAR).div(avgMs);
+  } else {
+    const fixed = {
+      "1d": 365,
+      "1w": 52,
+      "1M": 12
+    };
+    multiplier = new BigNumber(fixed[aggregation]);
+  }
+  return entries.map((e) => ({
+    ...e,
+    annualizedRate: new BigNumber(e.rate).times(multiplier).toNumber()
+  }));
+}
+function computeBasketRates(longTokens, shortTokens, tokenRates) {
+  const allSymbols = [...longTokens, ...shortTokens].map((t) => t.symbol);
+  if (allSymbols.length === 0) return [];
+  const lookups = {};
+  const allTimestamps = /* @__PURE__ */ new Set();
+  for (const [symbol, entries] of Object.entries(tokenRates)) {
+    const lookup = /* @__PURE__ */ new Map();
+    for (const entry of entries) {
+      lookup.set(entry.time, entry.rate);
+      allTimestamps.add(entry.time);
+    }
+    lookups[symbol] = lookup;
+  }
+  const sorted = Array.from(allTimestamps).sort((a, b) => a - b);
+  const result = [];
+  for (const time of sorted) {
+    if (!allSymbols.every((s) => lookups[s]?.has(time))) continue;
+    let total = new BigNumber(0);
+    let count = 0;
+    for (const t of longTokens) {
+      const rate = lookups[t.symbol]?.get(time);
+      if (rate !== void 0 && t.weight > 0) {
+        total = total.plus(new BigNumber(rate).negated().times(new BigNumber(t.weight).div(100)));
+        count++;
+      }
+    }
+    for (const t of shortTokens) {
+      const rate = lookups[t.symbol]?.get(time);
+      if (rate !== void 0 && t.weight > 0) {
+        total = total.plus(new BigNumber(rate).times(new BigNumber(t.weight).div(100)));
+        count++;
+      }
+    }
+    if (count > 0) {
+      result.push({ time, rate: total.toNumber() });
+    }
+  }
+  return result;
+}
+
+export { aggregateRates, annualizeRates, computeBasketRates, computeStartTime };

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { Chart } from './chart/chart.js';
 export { Bar, CandleData, CandleInterval, ChartConfig, ChartType, RealtimeBarCallback, RealtimeCandleCallback, TokenSelection } from './chart/types.js';
+export { FundingRate } from './funding-rate/funding-rate.js';
+export { FundingRateAggregation, FundingRateConfig, FundingRateDuration, FundingRateEntry } from './funding-rate/types.js';
 export { Orderbook } from './orderbook/orderbook.js';
 export { AggregationConfig, BBO, CexAggregationConfig, HyperliquidAggregationConfig, OrderbookCallback, OrderbookConfig, OrderbookLevel, OrderbookSnapshot } from './orderbook/types.js';
 export { getAvailableAggregations } from './orderbook/utils.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { Chart } from './chart/chart';
+export { FundingRate } from './funding-rate/funding-rate';
 export { Orderbook } from './orderbook/orderbook';
 export { getAvailableAggregations } from './orderbook/utils';
 export { BaseTransport, CreateTransport } from './transport';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pear-protocol/market-sdk",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Pear Protocol Market SDK",
   "private": false,
   "type": "module",
@@ -25,7 +25,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@pear-protocol/types": "0.0.15",
+    "@pear-protocol/types": "0.0.16",
     "bignumber.js": "^9.1.2",
     "partysocket": "^1.0.3"
   },