@pear-protocol/exchanges-sdk 0.0.18 → 0.1.3

package/README.md

@@ -1,15 +1,16 @@
 # @pear-protocol/exchanges-sdk
 
-Unified SDK for connecting to cryptocurrency derivative exchanges. Provides real-time account state tracking including balances, positions, and leverage management through a single, exchange-agnostic interface with automatic WebSocket streaming and credential resolution.
+Unified SDK for real-time account state (balance, positions, per-asset leverage) across supported derivative exchanges.
 
 ## Supported Exchanges
 
-| Exchange | Connector Name | Market Type |
-|----------|---------------|-------------|
+| Exchange | Connector | Market |
+|----------|-----------|--------|
 | Binance | `binance` | USDM Futures |
 | Bybit | `bybit` | Linear Perpetuals |
 | Hyperliquid | `hyperliquid` | Perpetuals |
-| OKX | `okx` | Linear SWAP Perpetuals |
+| Lighter | `lighter` | Perpetuals |
+| OKX | `okx` | Linear SWAP |
 
 ## Installation
 
@@ -26,187 +27,122 @@ import { ExchangesSDK } from '@pear-protocol/exchanges-sdk';
 const sdk = new PearSDK({ /* ... */ });
 const exchanges = new ExchangesSDK({ sdk });
 
-await exchanges.account.connect(tradeAccountId, 'binanceusdm');
+const connection = await exchanges.connect(tradeAccountId, 'binance');
+const tracker = exchanges.createTracker(connection);
+await tracker.start();
 
-// Track balance and positions
-const balanceTracker = exchanges.account.trackBalance((balance) => {
+const offBalance = tracker.trackBalance((balance) => {
   console.log(balance.totalEquity, balance.unrealizedPnl);
 });
 
-const positionsTracker = exchanges.account.trackPositions((positions) => {
-  for (const pos of positions) {
-    console.log(pos.symbol, pos.side, pos.size, pos.entryPrice);
-  }
+const offPositions = tracker.trackPosition((positions) => {
+  for (const p of positions) console.log(p.symbol, p.side, p.size);
 });
 
 // Cleanup
-balanceTracker.untrack();
-positionsTracker.untrack();
-exchanges.destroy();
+offBalance();
+offPositions();
+await tracker.disconnect();
 ```
 
-## Usage
-
-### Initialization
+Pass `demo: true` to target testnet:
 
 ```typescript
-// Production
-const exchanges = new ExchangesSDK({ sdk });
-
-// Testnet / demo
 const exchanges = new ExchangesSDK({ sdk, demo: true });
 ```
 
-The `ExchangesSDK` exposes three top-level modules:
-
-| Module | Description |
-|--------|-------------|
-| `exchanges.account` | Account connection, balance/position tracking, leverage management |
-| `exchanges.credentials` | Exchange API credential fetching and caching |
-| `exchanges.sdk` | Reference to the underlying `PearSDK` instance |
-
-### Connecting to an Exchange
-
-Credentials are fetched automatically from the backend when you call `connect`. One exchange connection is active at a time.
-
-```typescript
-await exchanges.account.connect(tradeAccountId, 'binance');
-await exchanges.account.connect(tradeAccountId, 'bybit');
-await exchanges.account.connect(tradeAccountId, 'hyperliquid');
-```
-
-Check connection status:
-
-```typescript
-exchanges.account.isConnected;    // WebSocket is active
-exchanges.account.isInitialized;  // first state snapshot received
-```
+## Tracking
 
-### Tracking Balance
+Each `track*` method returns an unsubscribe function. Callbacks fire with the current snapshot on subscribe (if available) and on every update.
 
-Subscribe to real-time balance updates. The callback fires on every balance change from the exchange.
+### Balance
 
 ```typescript
-const tracker = exchanges.account.trackBalance((balance) => {
-  balance.totalEquity;       // total account equity
-  balance.walletBalance;     // wallet balance excluding unrealized PnL
-  balance.unrealizedPnl;     // total unrealized PnL
-  balance.availableToTrade;  // available margin for new trades
-  balance.initialMarginUsed; // margin used by open positions
-  balance.maintenanceMargin; // maintenance margin requirement
-  balance.marginRatio;       // current margin ratio
-
-  // Per-asset breakdown
-  for (const asset of balance.assets) {
-    asset.asset;          // "USDT", "BTC", etc.
-    asset.free;           // available amount
-    asset.used;           // amount in use
-    asset.total;          // total amount
-    asset.walletBalance;  // wallet balance
-    asset.usdValue;       // USD equivalent
+tracker.trackBalance((balance) => {
+  balance.totalEquity;
+  balance.walletBalance;
+  balance.unrealizedPnl;
+  balance.availableToTrade;
+  balance.initialMarginUsed;
+  balance.maintenanceMargin;
+  balance.marginRatio;
+  balance.accountType;
+
+  for (const a of balance.assets) {
+    a.asset;         // "USDT", "USDC", ...
+    a.free;
+    a.used;
+    a.total;
+    a.usdValue;
   }
 });
-
-// Read the latest value without waiting for a callback
-const current = tracker.get();
-
-// Stop receiving updates
-tracker.untrack();
 ```
 
-### Tracking Positions
-
-Subscribe to real-time position updates. The callback fires with the full list of open positions on every change.
+### Positions
 
 ```typescript
-const tracker = exchanges.account.trackPositions((positions) => {
-  for (const pos of positions) {
-    pos.symbol;           // "BTCUSDT"
-    pos.side;             // "long" | "short" | "both"
-    pos.size;             // "0.5"
-    pos.entryPrice;       // "65000.00"
-    pos.unrealizedPnl;    // "120.50"
-    pos.leverage;         // "10"
-    pos.marginType;       // "cross" | "isolated"
-    pos.liquidationPrice; // "58000.00" or null
+tracker.trackPosition((positions) => {
+  for (const p of positions) {
+    p.symbol;
+    p.side;             // "long" | "short" | "both"
+    p.size;
+    p.entryPrice;
+    p.unrealizedPnl;
+    p.leverage;
+    p.marginType;       // "cross" | "isolated"
+    p.liquidationPrice; // string | null
   }
 });
-
-const current = tracker.get();
-tracker.untrack();
 ```
 
-Positions with a size of `"0"` are automatically removed from the tracked state.
-
-### Tracking a Specific Asset
+Closed positions (`size === '0'`) are dropped automatically.
 
-Retrieve leverage, margin type, and trade size constraints for a specific coin. Useful when preparing to place a trade.
+### Per-Asset Leverage & Margin
 
 ```typescript
-const tracker = exchanges.account.trackAsset('ETH', (info) => {
-  info.coin;        // "ETH"
-  info.leverage;    // "20"
-  info.marginType;  // "cross" | "isolated"
+tracker.trackAsset('ETH', (info) => {
+  info.coin;
+  info.leverage;
+  info.marginType;
 });
-
-const current = tracker.get();
-tracker.untrack();
 ```
 
-> **Symbol format per exchange:** `trackAsset` takes the exchange's native symbol:
-> - Binance / Bybit: `BTCUSDT`
-> - Hyperliquid: `BTC`
-> - OKX: `BTC-USDT-SWAP`
+Asset symbol format per exchange:
 
-### Managing Leverage
+| Exchange | Format | Example |
+|----------|--------|---------|
+| Binance | `<BASE><QUOTE>` | `BTCUSDT` |
+| Bybit | `<BASE><QUOTE>` | `BTCUSDT` |
+| Hyperliquid | base coin | `BTC` |
+| Lighter | base coin | `BTC` |
+| OKX | `instId` | `BTC-USDT-SWAP` |
 
-```typescript
-// Read cached leverage (returns null if not yet fetched)
-const leverage = exchanges.account.getLeverage('BTCUSDT');
-```
-
-### Reading Full State
+## Snapshot Reads
 
-Access a read-only snapshot of the complete account state at any time.
+Synchronous getters for the latest cached state:
 
 ```typescript
-const state = exchanges.account.getState();
-if (state) {
-  state.balance;          // latest AccountBalance or null
-  state.positions;        // Map<"SYMBOL:side", AccountPosition>
-  state.leverageSettings; // Map<symbol, leverage>
-  state.trackedAssets;    // Map<coin, TrackedAssetInfo>
-  state.lastUpdated;      // timestamp of last update
-  state.initialized;      // true after first snapshot
-}
+tracker.getBalance();            // AccountBalance | null
+tracker.getPositions();          // AccountPosition[]
+tracker.getTrackedAsset('ETH');  // TrackedAssetInfo | null
+tracker.isConnected;
+tracker.isInitialized;           // true after first snapshot
 ```
 
-### Credential Management
+## Account Type Labels
 
-Credentials are resolved automatically on `connect`, but you can manage them directly:
+`balance.accountType` is an exchange-specific enum. Render with:
 
 ```typescript
-// Fetch credentials from the backend
-const creds = await exchanges.credentials.fetch(tradeAccountId);
+import { ACCOUNT_TYPE_LABELS } from '@pear-protocol/exchanges-sdk';
 
-// Get cached credentials (null if not fetched)
-const cached = exchanges.credentials.get(tradeAccountId);
-
-// Get from cache or fetch if missing
-const creds = await exchanges.credentials.getOrFetch(tradeAccountId);
-
-// Clear cached credentials
-exchanges.credentials.clear(tradeAccountId); // specific account
-exchanges.credentials.clear();               // all accounts
+ACCOUNT_TYPE_LABELS[balance.accountType]; // "Cross Margin", "Portfolio Margin", ...
 ```
 
-### Cleanup
+## Cleanup
 
 ```typescript
-// Disconnect but keep credentials cached for reconnection
-exchanges.account.disconnect();
-
-// Full teardown: disconnect and clear all credentials
-exchanges.destroy();
+await tracker.disconnect();
 ```
 
+Credentials are fetched automatically on `connect`; for Hyperliquid and Lighter the account index is resolved from the backend.

package/dist/client/base-ws.d.ts

@@ -0,0 +1,30 @@
+import { WebSocket } from 'partysocket';
+
+interface WsMessage {
+    [key: string]: unknown;
+}
+type MessageListener = (data: string) => void;
+type OpenListener = () => void;
+declare abstract class BaseWs {
+    protected ws: WebSocket | null;
+    protected pingTimer: ReturnType<typeof setInterval> | null;
+    private messageListeners;
+    private openListeners;
+    private nextListenerId;
+    protected abstract getWsUrl(): string;
+    protected abstract getPingIntervalMs(): number;
+    protected abstract buildPingMessage(): WsMessage | string | null;
+    connect(): Promise<void>;
+    disconnect(): void;
+    get connected(): boolean;
+    send(msg: WsMessage | string): void;
+    addMessageListener(listener: MessageListener): string;
+    removeMessageListener(id: string): void;
+    addOpenListener(listener: OpenListener): string;
+    removeOpenListener(id: string): void;
+    destroy(): void;
+    private startPing;
+    private stopPing;
+}
+
+export { BaseWs, type MessageListener, type OpenListener, type WsMessage };

package/dist/client/base-ws.js

@@ -0,0 +1,113 @@
+import { WebSocket } from 'partysocket';
+
+class BaseWs {
+  ws = null;
+  pingTimer = null;
+  messageListeners = /* @__PURE__ */ new Map();
+  openListeners = /* @__PURE__ */ new Map();
+  nextListenerId = 0;
+  async connect() {
+    if (this.ws) return;
+    const ws = new WebSocket(this.getWsUrl(), [], {
+      maxReconnectionDelay: 3e4,
+      minReconnectionDelay: 1e3,
+      reconnectionDelayGrowFactor: 2,
+      connectionTimeout: 1e4
+    });
+    ws.addEventListener("open", () => {
+      this.startPing();
+      for (const listener of this.openListeners.values()) {
+        try {
+          listener();
+        } catch (error) {
+          console.warn("Error in ws open listener", error);
+        }
+      }
+    });
+    ws.addEventListener("message", (event) => {
+      const data = event.data;
+      if (typeof data !== "string") return;
+      for (const listener of this.messageListeners.values()) {
+        try {
+          listener(data);
+        } catch (error) {
+          console.warn("Error in ws message listener", error);
+        }
+      }
+    });
+    ws.addEventListener("close", () => {
+      this.stopPing();
+    });
+    ws.addEventListener("error", () => {
+    });
+    this.ws = ws;
+    await new Promise((resolve, reject) => {
+      if (ws.readyState === WebSocket.OPEN) {
+        resolve();
+        return;
+      }
+      const onOpen = () => {
+        ws.removeEventListener("error", onError);
+        resolve();
+      };
+      const onError = () => {
+        ws.removeEventListener("open", onOpen);
+        reject(new Error("WebSocket connection failed"));
+      };
+      ws.addEventListener("open", onOpen, { once: true });
+      ws.addEventListener("error", onError, { once: true });
+    });
+  }
+  disconnect() {
+    this.stopPing();
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+  }
+  get connected() {
+    return this.ws?.readyState === WebSocket.OPEN;
+  }
+  send(msg) {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(typeof msg === "string" ? msg : JSON.stringify(msg));
+    }
+  }
+  addMessageListener(listener) {
+    const id = String(++this.nextListenerId);
+    this.messageListeners.set(id, listener);
+    return id;
+  }
+  removeMessageListener(id) {
+    this.messageListeners.delete(id);
+  }
+  addOpenListener(listener) {
+    const id = String(++this.nextListenerId);
+    this.openListeners.set(id, listener);
+    return id;
+  }
+  removeOpenListener(id) {
+    this.openListeners.delete(id);
+  }
+  destroy() {
+    this.disconnect();
+    this.messageListeners.clear();
+    this.openListeners.clear();
+  }
+  startPing() {
+    this.stopPing();
+    const intervalMs = this.getPingIntervalMs();
+    if (intervalMs <= 0) return;
+    const pingMsg = this.buildPingMessage();
+    if (pingMsg === null) return;
+    this.pingTimer = setInterval(() => this.send(pingMsg), intervalMs);
+  }
+  stopPing() {
+    if (this.pingTimer) {
+      clearInterval(this.pingTimer);
+      this.pingTimer = null;
+    }
+  }
+}
+
+export { BaseWs };

package/dist/client/binance/exchange-ws.d.ts

@@ -0,0 +1,19 @@
+import { BinanceCredentialsDTO } from '@pear-protocol/types';
+import { BaseWs } from '../base-ws.js';
+import { ExchangeWs } from '../exchange-ws.js';
+import { BinanceUserDataWs, BinanceWsApi } from './ws.js';
+import 'partysocket';
+
+declare class BinanceExchangeWs extends ExchangeWs {
+    userData: BinanceUserDataWs;
+    wsApi: BinanceWsApi;
+    readonly exchange: "binance";
+    constructor(userData: BinanceUserDataWs, wsApi: BinanceWsApi);
+    protected connections(): BaseWs[];
+    static create(config: {
+        demo: boolean;
+        credentials: BinanceCredentialsDTO;
+    }): Promise<BinanceExchangeWs>;
+}
+
+export { BinanceExchangeWs };

package/dist/client/binance/exchange-ws.js

@@ -0,0 +1,26 @@
+import { ExchangeWs } from '../exchange-ws';
+import { createListenKey } from './rest';
+import { BinanceUserDataWs, BinanceWsApi } from './ws';
+
+class BinanceExchangeWs extends ExchangeWs {
+  constructor(userData, wsApi) {
+    super();
+    this.userData = userData;
+    this.wsApi = wsApi;
+  }
+  userData;
+  wsApi;
+  exchange = "binance";
+  connections() {
+    return [this.userData, this.wsApi];
+  }
+  static async create(config) {
+    const listenKey = await createListenKey(config.credentials.read.api_key, config.demo);
+    const userData = new BinanceUserDataWs({ listenKey, demo: config.demo });
+    const wsApi = new BinanceWsApi({ demo: config.demo });
+    await Promise.all([userData.connect(), wsApi.connect()]);
+    return new BinanceExchangeWs(userData, wsApi);
+  }
+}
+
+export { BinanceExchangeWs };

package/dist/{account/exchanges → client}/binance/rest.d.ts

@@ -1,8 +1,5 @@
 import { BinanceCredentialsDTO } from '@pear-protocol/types';
-import { j as BinanceRawAccountStatus, k as BinanceRawPositionRisk, l as BinanceAssetIndex } from '../../../types-Caz2X4h0.js';
-import '../bybit/types.js';
-import '../hyperliquid/types.js';
-import '../okx/types.js';
+import { BinanceRawAccountStatus, BinanceRawPositionRisk } from './types.js';
 
 declare function createListenKey(apiKey: string, demo?: boolean): Promise<string>;
 declare function keepAliveListenKey(apiKey: string, demo?: boolean): Promise<void>;
@@ -10,6 +7,5 @@ declare function fetchAccountStatus(creds: BinanceCredentialsDTO, demo: boolean)
 declare function fetchPositionRisk(creds: BinanceCredentialsDTO, symbol: string, demo: boolean): Promise<BinanceRawPositionRisk | undefined>;
 declare function fetchAllPositionRisk(creds: BinanceCredentialsDTO, demo: boolean): Promise<BinanceRawPositionRisk[]>;
 declare function fetchMultiAssetsMargin(creds: BinanceCredentialsDTO, demo: boolean): Promise<boolean>;
-declare function fetchAssetIndex(demo: boolean): Promise<BinanceAssetIndex[]>;
 
-export { createListenKey, fetchAccountStatus, fetchAllPositionRisk, fetchAssetIndex, fetchMultiAssetsMargin, fetchPositionRisk, keepAliveListenKey };
+export { createListenKey, fetchAccountStatus, fetchAllPositionRisk, fetchMultiAssetsMargin, fetchPositionRisk, keepAliveListenKey };

package/dist/{account/exchanges → client}/binance/rest.js

@@ -1,6 +1,7 @@
-import { hmacSha256Hex } from '../../../utils/hmac';
-import { BASE_URL_TESTNET, BASE_URL } from './const';
+import { hmacSha256Hex } from '../hmac';
 
+const BASE_URL = "https://fapi.binance.com";
+const BASE_URL_TESTNET = "https://testnet.binancefuture.com";
 async function signedGet(creds, path, params, demo) {
   const baseUrl = demo ? BASE_URL_TESTNET : BASE_URL;
   const timestamp = Date.now().toString();
@@ -53,13 +54,5 @@ async function fetchMultiAssetsMargin(creds, demo) {
   const res = await signedGet(creds, "/fapi/v1/multiAssetsMargin", {}, demo);
   return res.multiAssetsMargin;
 }
-async function fetchAssetIndex(demo) {
-  const baseUrl = demo ? BASE_URL_TESTNET : BASE_URL;
-  const response = await fetch(`${baseUrl}/fapi/v1/assetIndex`);
-  if (!response.ok) {
-    throw new Error(`Binance API error: ${response.status} ${response.statusText}`);
-  }
-  return await response.json();
-}
 
-export { createListenKey, fetchAccountStatus, fetchAllPositionRisk, fetchAssetIndex, fetchMultiAssetsMargin, fetchPositionRisk, keepAliveListenKey };
+export { createListenKey, fetchAccountStatus, fetchAllPositionRisk, fetchMultiAssetsMargin, fetchPositionRisk, keepAliveListenKey };

package/dist/client/binance/types.d.ts

@@ -0,0 +1,68 @@
+import { MarginMode } from '@pear-protocol/types';
+
+interface BinanceRawPositionRisk {
+    symbol: string;
+    leverage: string;
+    marginType: MarginMode;
+    isAutoAddMargin: string;
+    isolatedMargin: string;
+    positionAmt: string;
+    entryPrice: string;
+    breakEvenPrice: string;
+    unRealizedProfit: string;
+    liquidationPrice: string;
+    markPrice: string;
+    maxNotionalValue: string;
+    positionSide: string;
+    notional: string;
+    isolatedWallet: string;
+    updateTime: number;
+}
+interface BinanceRawAsset {
+    asset: string;
+    walletBalance: string;
+    availableBalance: string;
+    unrealizedProfit: string;
+    marginBalance: string;
+    initialMargin: string;
+    maintMargin: string;
+    marginAvailable: boolean;
+}
+interface BinanceRawAccountStatus {
+    totalWalletBalance: string;
+    totalMarginBalance: string;
+    availableBalance: string;
+    totalUnrealizedProfit: string;
+    totalInitialMargin: string;
+    totalMaintMargin: string;
+    assets?: BinanceRawAsset[];
+}
+interface BinanceMultiAssetsMarginResponse {
+    multiAssetsMargin: boolean;
+}
+interface BinanceAssetIndex {
+    symbol: string;
+    time: number;
+    index: string;
+    bidBuffer: string;
+    askBuffer: string;
+    bidRate: string;
+    askRate: string;
+    autoExchangeBidBuffer: string;
+    autoExchangeAskBuffer: string;
+    autoExchangeBidRate: string;
+    autoExchangeAskRate: string;
+}
+interface BinanceRawUserDataEvent {
+    e?: string;
+    ac?: {
+        s: string;
+        l: string;
+    };
+    a?: {
+        B?: unknown[];
+        P?: unknown[];
+    };
+}
+
+export type { BinanceAssetIndex, BinanceMultiAssetsMarginResponse, BinanceRawAccountStatus, BinanceRawAsset, BinanceRawPositionRisk, BinanceRawUserDataEvent };

package/dist/client/binance/types.js

@@ -0,0 +1 @@
+

package/dist/client/binance/ws.d.ts

@@ -0,0 +1,30 @@
+import { BinanceCredentialsDTO } from '@pear-protocol/types';
+import { BaseWs } from '../base-ws.js';
+import 'partysocket';
+
+type BinanceUserDataWsConfig = {
+    listenKey: string;
+    demo: boolean;
+};
+declare class BinanceUserDataWs extends BaseWs {
+    private readonly listenKey;
+    private readonly demo;
+    constructor(config: BinanceUserDataWsConfig);
+    protected getWsUrl(): string;
+    protected getPingIntervalMs(): number;
+    protected buildPingMessage(): null;
+}
+type BinanceWsApiConfig = {
+    demo: boolean;
+};
+declare class BinanceWsApi extends BaseWs {
+    private readonly demo;
+    private requestId;
+    constructor(config: BinanceWsApiConfig);
+    protected getWsUrl(): string;
+    protected getPingIntervalMs(): number;
+    protected buildPingMessage(): null;
+    sendSignedRequest(creds: BinanceCredentialsDTO, method: string, params?: Record<string, unknown>): Promise<number>;
+}
+
+export { BinanceUserDataWs, type BinanceUserDataWsConfig, BinanceWsApi, type BinanceWsApiConfig };

package/dist/client/binance/ws.js

@@ -0,0 +1,54 @@
+import { BaseWs } from '../base-ws';
+import { hmacSha256Hex } from '../hmac';
+
+const USER_DATA_URL = "wss://fstream.binance.com/ws";
+const USER_DATA_URL_TESTNET = "wss://stream.binancefuture.com/ws";
+const WS_API_URL = "wss://ws-fapi.binance.com/ws-fapi/v1";
+const WS_API_URL_TESTNET = "wss://testnet.binancefuture.com/ws-fapi/v1";
+class BinanceUserDataWs extends BaseWs {
+  listenKey;
+  demo;
+  constructor(config) {
+    super();
+    this.listenKey = config.listenKey;
+    this.demo = config.demo;
+  }
+  getWsUrl() {
+    const base = this.demo ? USER_DATA_URL_TESTNET : USER_DATA_URL;
+    return `${base}/${this.listenKey}`;
+  }
+  getPingIntervalMs() {
+    return 0;
+  }
+  buildPingMessage() {
+    return null;
+  }
+}
+class BinanceWsApi extends BaseWs {
+  demo;
+  requestId = 1;
+  constructor(config) {
+    super();
+    this.demo = config.demo;
+  }
+  getWsUrl() {
+    return this.demo ? WS_API_URL_TESTNET : WS_API_URL;
+  }
+  getPingIntervalMs() {
+    return 0;
+  }
+  buildPingMessage() {
+    return null;
+  }
+  async sendSignedRequest(creds, method, params = {}) {
+    const id = this.requestId++;
+    const timestamp = Date.now();
+    const allParams = { ...params, apiKey: creds.read.api_key, timestamp };
+    const queryString = Object.keys(allParams).sort().map((k) => `${k}=${allParams[k]}`).join("&");
+    const signature = await hmacSha256Hex(creds.read.api_secret, queryString);
+    this.send({ id, method, params: { ...allParams, signature } });
+    return id;
+  }
+}
+
+export { BinanceUserDataWs, BinanceWsApi };