@pear-protocol/exchanges-sdk 0.0.1

package/README.md

@@ -0,0 +1,187 @@
+# @backend/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.
+
+## Supported Exchanges
+
+| Exchange | Connector Name | Market Type |
+|----------|---------------|-------------|
+| Binance | `binanceusdm` | USDM Futures |
+| Bybit | `bybit` | Linear Perpetuals |
+
+## Installation
+
+```json
+{
+  "dependencies": {
+    "@backend/exchanges-sdk": "workspace:*"
+  }
+}
+```
+
+Requires `@pear-protocol/core-sdk` and `@backend/shared` as peer dependencies.
+
+## Quick Start
+
+```typescript
+import PearSDK from '@pear-protocol/core-sdk';
+import { ExchangesSDK } from '@backend/exchanges-sdk';
+
+const sdk = new PearSDK({ /* ... */ });
+const exchanges = new ExchangesSDK({ sdk });
+
+await exchanges.account.connect(tradeAccountId, 'binanceusdm');
+
+const balanceTracker = exchanges.account.trackBalance((balance) => {
+  console.log(balance.totalEquity);
+});
+
+const positionsTracker = exchanges.account.trackPositions((positions) => {
+  for (const pos of positions) {
+    console.log(pos.symbol, pos.side, pos.size);
+  }
+});
+
+// Cleanup
+balanceTracker.untrack();
+positionsTracker.untrack();
+exchanges.destroy();
+```
+
+## Usage
+
+### Initialization
+
+```typescript
+// Production
+const exchanges = new ExchangesSDK({ sdk });
+
+// Testnet / demo
+const exchanges = new ExchangesSDK({ sdk, demo: true });
+```
+
+### Connecting to an Exchange
+
+Credentials are fetched automatically from the backend when you call `connect`.
+
+```typescript
+await exchanges.account.connect(tradeAccountId, 'binanceusdm');
+await exchanges.account.connect(tradeAccountId, 'bybit');
+```
+
+Check connection status:
+
+```typescript
+exchanges.account.isConnected;    // WebSocket is active
+exchanges.account.isInitialized;  // First state snapshot received
+```
+
+### Tracking Balance
+
+Subscribe to real-time balance updates. The callback fires on every balance change.
+
+```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.marginRatio;       // current margin ratio
+
+  // Per-asset breakdown
+  for (const asset of balance.assets) {
+    asset.asset;          // "USDT", "BTC", etc.
+    asset.usdValue;       // USD equivalent
+    asset.isCollateral;   // whether the asset is used as collateral
+  }
+});
+
+// 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.
+
+```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
+  }
+});
+
+const current = tracker.get();
+tracker.untrack();
+```
+
+### Tracking a Specific Asset
+
+Retrieve leverage, margin type, and trade size constraints for a specific coin. Useful when preparing to place a trade.
+
+```typescript
+const tracker = exchanges.account.trackAsset('ETH', (info) => {
+  info.coin;             // "ETH"
+  info.leverage;         // "20"
+  info.marginType;       // "cross" | "isolated"
+  info.availableToTrade; // [min, max] or null
+  info.maxTradeSzs;      // [min, max] or null
+  info.collateralToken;  // "USDT" or null
+});
+
+const current = tracker.get();
+tracker.untrack();
+```
+
+### Managing Leverage
+
+```typescript
+await exchanges.account.setLeverage('BTCUSDT', '10');
+
+// Read cached leverage (returns null if not yet fetched)
+const leverage = exchanges.account.getLeverage('BTCUSDT');
+```
+
+### Reading Full State
+
+Access a read-only snapshot of the complete account state at any time.
+
+```typescript
+const state = exchanges.account.getState();
+if (state) {
+  state.balance;          // latest balance or null
+  state.positions;        // Map of all open positions
+  state.leverageSettings; // Map of symbol to leverage
+  state.trackedAssets;    // Map of coin to asset info
+  state.lastUpdated;      // timestamp of last update
+  state.initialized;      // true after first snapshot
+}
+```
+
+### Disconnecting
+
+```typescript
+// Disconnect but keep credentials cached for reconnection
+exchanges.account.disconnect();
+
+// Full teardown: disconnect and clear all credentials
+exchanges.destroy();
+```
+
+## Behavior Notes
+
+- The WebSocket connection starts lazily when the first tracker is registered and stops when all trackers are removed.
+- On unexpected disconnection, the SDK reconnects automatically with exponential backoff (1s to 30s).
+- Reconnection is suppressed after explicit `disconnect()` or `destroy()` calls.
+- Credentials are held in memory only and never persisted to disk.
+- All numeric values (balances, sizes, prices, PnL) are returned as strings to preserve decimal precision.

package/dist/account/account-manager.d.ts

@@ -0,0 +1,34 @@
+import { Connector } from '@pear-protocol/types';
+import { Credentials } from '../credentials.js';
+import { BalanceCallback, Tracker, AccountBalance, PositionsCallback, AccountPosition, TrackedAssetCallback, TrackedAssetInfo, ExchangeState } from './types.js';
+import '@pear-protocol/core-sdk';
+
+declare class AccountManager {
+    private credentials;
+    private demo;
+    private activeAccount;
+    private pendingExchange;
+    private pendingTradeAccountId;
+    private balanceListeners;
+    private positionListeners;
+    private assetListeners;
+    constructor(credentials: Credentials, demo?: boolean);
+    connect(tradeAccountId: string, exchange: Connector): Promise<void>;
+    trackBalance(cb: BalanceCallback): Tracker<AccountBalance | null>;
+    trackPositions(cb: PositionsCallback): Tracker<AccountPosition[]>;
+    trackAsset(coin: string, cb: TrackedAssetCallback): Tracker<TrackedAssetInfo | null>;
+    setLeverage(symbol: string, leverage: string): Promise<void>;
+    getLeverage(symbol: string): string | null;
+    getState(): Readonly<ExchangeState> | null;
+    disconnect(): void;
+    destroy(): void;
+    get isConnected(): boolean;
+    get isInitialized(): boolean;
+    private get hasListeners();
+    private disconnectWs;
+    private maybeDisconnectWs;
+    private ensureWsStarted;
+    private startWs;
+}
+
+export { AccountManager };

package/dist/account/account-manager.js

@@ -0,0 +1,140 @@
+import { ExchangeAccount } from './exchange-account';
+
+class AccountManager {
+  credentials;
+  demo;
+  activeAccount = null;
+  pendingExchange = null;
+  pendingTradeAccountId = null;
+  balanceListeners = /* @__PURE__ */ new Map();
+  positionListeners = /* @__PURE__ */ new Map();
+  assetListeners = /* @__PURE__ */ new Map();
+  constructor(credentials, demo = false) {
+    this.credentials = credentials;
+    this.demo = demo;
+  }
+  async connect(tradeAccountId, exchange) {
+    const creds = await this.credentials.getOrFetch(tradeAccountId);
+    this.disconnectWs();
+    this.pendingTradeAccountId = tradeAccountId;
+    this.pendingExchange = exchange;
+    if (this.hasListeners) {
+      await this.startWs(exchange, creds);
+    }
+  }
+  trackBalance(cb) {
+    const id = Math.random().toString(36).slice(2);
+    this.balanceListeners.set(id, cb);
+    if (this.activeAccount) {
+      this.activeAccount.trackBalance(cb);
+    } else {
+      this.ensureWsStarted();
+    }
+    return {
+      get: () => this.activeAccount?.getBalance() ?? null,
+      untrack: () => {
+        this.balanceListeners.delete(id);
+        this.activeAccount?.untrackBalance(id);
+        this.maybeDisconnectWs();
+      }
+    };
+  }
+  trackPositions(cb) {
+    const id = Math.random().toString(36).slice(2);
+    this.positionListeners.set(id, cb);
+    if (this.activeAccount) {
+      this.activeAccount.trackPositions(cb);
+    } else {
+      this.ensureWsStarted();
+    }
+    return {
+      get: () => this.activeAccount?.getPositions() ?? [],
+      untrack: () => {
+        this.positionListeners.delete(id);
+        this.activeAccount?.untrackPositions(id);
+        this.maybeDisconnectWs();
+      }
+    };
+  }
+  trackAsset(coin, cb) {
+    const id = Math.random().toString(36).slice(2);
+    this.assetListeners.set(id, { coin, cb });
+    if (this.activeAccount) {
+      this.activeAccount.trackAsset(coin, cb);
+    } else {
+      this.ensureWsStarted();
+    }
+    return {
+      get: () => this.activeAccount?.getTrackedAsset(coin) ?? null,
+      untrack: () => {
+        this.assetListeners.delete(id);
+        this.activeAccount?.untrackAsset(id);
+        this.maybeDisconnectWs();
+      }
+    };
+  }
+  async setLeverage(symbol, leverage) {
+    if (!this.activeAccount) throw new Error("No active account");
+    await this.activeAccount.setLeverage(symbol, leverage);
+  }
+  getLeverage(symbol) {
+    return this.activeAccount?.getLeverage(symbol) ?? null;
+  }
+  getState() {
+    return this.activeAccount?.getState() ?? null;
+  }
+  disconnect() {
+    this.disconnectWs();
+    this.pendingExchange = null;
+    this.pendingTradeAccountId = null;
+    this.balanceListeners.clear();
+    this.positionListeners.clear();
+    this.assetListeners.clear();
+  }
+  destroy() {
+    this.disconnect();
+    this.credentials.clear();
+  }
+  get isConnected() {
+    return this.activeAccount?.isConnected ?? false;
+  }
+  get isInitialized() {
+    return this.activeAccount?.isInitialized ?? false;
+  }
+  get hasListeners() {
+    return this.balanceListeners.size > 0 || this.positionListeners.size > 0 || this.assetListeners.size > 0;
+  }
+  disconnectWs() {
+    if (this.activeAccount) {
+      this.activeAccount.destroy();
+      this.activeAccount = null;
+    }
+  }
+  maybeDisconnectWs() {
+    if (!this.hasListeners) {
+      this.disconnectWs();
+    }
+  }
+  ensureWsStarted() {
+    if (this.activeAccount || !this.pendingExchange || !this.pendingTradeAccountId) return;
+    const exchange = this.pendingExchange;
+    const tradeAccountId = this.pendingTradeAccountId;
+    this.credentials.getOrFetch(tradeAccountId).then((creds) => this.startWs(exchange, creds)).catch((err) => console.warn("[AccountManager] Failed to start WS:", err));
+  }
+  async startWs(exchange, creds) {
+    const account = new ExchangeAccount({ exchange, demo: this.demo });
+    await account.connect(creds);
+    this.activeAccount = account;
+    for (const cb of this.balanceListeners.values()) {
+      account.trackBalance(cb);
+    }
+    for (const cb of this.positionListeners.values()) {
+      account.trackPositions(cb);
+    }
+    for (const { coin, cb } of this.assetListeners.values()) {
+      account.trackAsset(coin, cb);
+    }
+  }
+}
+
+export { AccountManager };

package/dist/account/exchange-account.d.ts

@@ -0,0 +1,36 @@
+import { Connector } from '@pear-protocol/types';
+import { AccountConfig, SupportedCredentials, BalanceCallback, AccountBalance, PositionsCallback, AccountPosition, TrackedAssetCallback, TrackedAssetInfo, ExchangeState } from './types.js';
+
+declare class ExchangeAccount {
+    private exchange;
+    private demo;
+    private orchestrator;
+    private state;
+    private balanceListeners;
+    private positionListeners;
+    private assetListeners;
+    private onAuthError?;
+    constructor(config: AccountConfig);
+    connect(credentials: SupportedCredentials): Promise<void>;
+    disconnect(): void;
+    destroy(): void;
+    get isConnected(): boolean;
+    get isInitialized(): boolean;
+    get hasListeners(): boolean;
+    trackBalance(cb: BalanceCallback): string;
+    untrackBalance(id: string): void;
+    getBalance(): AccountBalance | null;
+    trackPositions(cb: PositionsCallback): string;
+    untrackPositions(id: string): void;
+    getPositions(): AccountPosition[];
+    trackAsset(coin: string, cb: TrackedAssetCallback): string;
+    untrackAsset(id: string): void;
+    getTrackedAsset(coin: string): TrackedAssetInfo | null;
+    getLeverage(symbol: string): string | null;
+    setLeverage(symbol: string, leverage: string): Promise<void>;
+    getState(): Readonly<ExchangeState>;
+    getExchange(): Connector;
+    private applyStateUpdate;
+}
+
+export { ExchangeAccount };

package/dist/account/exchange-account.js

@@ -0,0 +1,185 @@
+import { createOrchestrator } from './exchanges';
+import { createEmptyState } from './utils';
+
+class ExchangeAccount {
+  exchange;
+  demo;
+  orchestrator = null;
+  state;
+  balanceListeners = /* @__PURE__ */ new Map();
+  positionListeners = /* @__PURE__ */ new Map();
+  assetListeners = /* @__PURE__ */ new Map();
+  onAuthError;
+  constructor(config) {
+    this.exchange = config.exchange;
+    this.demo = config.demo ?? false;
+    this.onAuthError = config.onAuthError;
+    this.state = createEmptyState();
+  }
+  async connect(credentials) {
+    this.disconnect();
+    this.state = createEmptyState();
+    this.orchestrator = createOrchestrator(this.exchange, {
+      onError: (error) => {
+        console.warn(`[ExchangeAccount] ${this.exchange} error:`, error.message);
+        if (error.message.includes("auth") || error.message.includes("login")) {
+          this.onAuthError?.();
+        }
+      },
+      onStateUpdate: (update) => this.applyStateUpdate(update),
+      demo: this.demo
+    });
+    await this.orchestrator.start(credentials);
+  }
+  disconnect() {
+    if (this.orchestrator) {
+      this.orchestrator.stop();
+      this.orchestrator = null;
+    }
+  }
+  destroy() {
+    this.disconnect();
+    this.balanceListeners.clear();
+    this.positionListeners.clear();
+    this.assetListeners.clear();
+    this.state = createEmptyState();
+  }
+  get isConnected() {
+    return this.orchestrator?.isConnected ?? false;
+  }
+  get isInitialized() {
+    return this.state.initialized;
+  }
+  get hasListeners() {
+    return this.balanceListeners.size > 0 || this.positionListeners.size > 0 || this.assetListeners.size > 0;
+  }
+  trackBalance(cb) {
+    const id = Math.random().toString(36).slice(2);
+    this.balanceListeners.set(id, cb);
+    if (this.state.balance) {
+      try {
+        cb(this.state.balance);
+      } catch {
+      }
+    }
+    return id;
+  }
+  untrackBalance(id) {
+    this.balanceListeners.delete(id);
+  }
+  getBalance() {
+    return this.state.balance;
+  }
+  trackPositions(cb) {
+    const id = Math.random().toString(36).slice(2);
+    this.positionListeners.set(id, cb);
+    if (this.state.initialized) {
+      try {
+        cb(Array.from(this.state.positions.values()));
+      } catch {
+      }
+    }
+    return id;
+  }
+  untrackPositions(id) {
+    this.positionListeners.delete(id);
+  }
+  getPositions() {
+    return Array.from(this.state.positions.values());
+  }
+  trackAsset(coin, cb) {
+    const id = Math.random().toString(36).slice(2);
+    this.assetListeners.set(id, { coin, cb });
+    this.orchestrator?.trackAsset(coin);
+    const existing = this.state.trackedAssets.get(coin);
+    if (existing) {
+      try {
+        cb(existing);
+      } catch {
+      }
+    }
+    return id;
+  }
+  untrackAsset(id) {
+    const entry = this.assetListeners.get(id);
+    if (!entry) return;
+    this.assetListeners.delete(id);
+    const hasOtherListeners = Array.from(this.assetListeners.values()).some((l) => l.coin === entry.coin);
+    if (!hasOtherListeners) {
+      this.orchestrator?.untrackAsset(entry.coin);
+    }
+  }
+  getTrackedAsset(coin) {
+    return this.state.trackedAssets.get(coin) ?? null;
+  }
+  getLeverage(symbol) {
+    const setting = this.state.leverageSettings.get(symbol);
+    if (setting !== void 0) return setting;
+    for (const pos of this.state.positions.values()) {
+      if (pos.symbol === symbol) return pos.leverage;
+    }
+    return null;
+  }
+  async setLeverage(symbol, leverage) {
+    if (!this.orchestrator) throw new Error("Not connected");
+    await this.orchestrator.setLeverage(symbol, leverage);
+  }
+  getState() {
+    return this.state;
+  }
+  getExchange() {
+    return this.exchange;
+  }
+  // --- private ---
+  applyStateUpdate(update) {
+    if (update.balance) {
+      this.state.balance = update.balance;
+      for (const cb of this.balanceListeners.values()) {
+        try {
+          cb(update.balance);
+        } catch {
+        }
+      }
+    }
+    if (update.positions) {
+      for (const [key, pos] of update.positions) {
+        if (pos.size === "0") {
+          this.state.positions.delete(key);
+        } else {
+          this.state.positions.set(key, pos);
+        }
+      }
+      const positions = Array.from(this.state.positions.values());
+      for (const cb of this.positionListeners.values()) {
+        try {
+          cb(positions);
+        } catch {
+        }
+      }
+    }
+    if (update.leverageSettings) {
+      for (const [symbol, lev] of update.leverageSettings) {
+        this.state.leverageSettings.set(symbol, lev);
+      }
+    }
+    if (update.trackedAssets) {
+      for (const [coin, info] of update.trackedAssets) {
+        this.state.trackedAssets.set(coin, info);
+        for (const listener of this.assetListeners.values()) {
+          if (listener.coin === coin) {
+            try {
+              listener.cb(info);
+            } catch {
+            }
+          }
+        }
+      }
+    }
+    this.state.lastUpdated = Date.now();
+    if (!this.state.initialized) {
+      this.state.initialized = true;
+    }
+  }
+}
+
+export { ExchangeAccount };

package/dist/account/exchanges/base.d.ts

@@ -0,0 +1,49 @@
+import { SupportedCredentials, StateUpdate } from '../types.js';
+import '@pear-protocol/types';
+
+type StateUpdateHandler = (update: StateUpdate) => void;
+type ErrorHandler = (error: Error) => void;
+type OrchestratorConfig = {
+    onStateUpdate: StateUpdateHandler;
+    onError: ErrorHandler;
+    demo: boolean;
+};
+interface Orchestrator {
+    start: (credentials: SupportedCredentials) => Promise<void>;
+    stop: () => void;
+    isConnected: boolean;
+    onAssetTracked: (coin: string) => void;
+    onAssetUntracked: (coin: string) => void;
+    setLeverage: (symbol: string, leverage: string) => Promise<void>;
+    trackAsset: (coin: string) => void;
+    untrackAsset: (coin: string) => boolean;
+    getTrackedCoins: () => ReadonlySet<string>;
+}
+declare abstract class BaseOrchestrator implements Orchestrator {
+    protected onStateUpdate: StateUpdateHandler;
+    protected onError: ErrorHandler;
+    protected demo: boolean;
+    protected credentials: SupportedCredentials | null;
+    protected manualClose: boolean;
+    protected reconnectAttempts: number;
+    protected reconnectTimer: ReturnType<typeof setTimeout> | null;
+    protected trackedCoins: Set<string>;
+    protected startGeneration: number;
+    private starting;
+    constructor(config: OrchestratorConfig);
+    abstract start(credentials: SupportedCredentials): Promise<void>;
+    abstract stop(): void;
+    abstract get isConnected(): boolean;
+    abstract onAssetTracked(coin: string): void;
+    abstract onAssetUntracked(coin: string): void;
+    abstract setLeverage(symbol: string, leverage: string): Promise<void>;
+    trackAsset(coin: string): void;
+    untrackAsset(coin: string): boolean;
+    getTrackedCoins(): ReadonlySet<string>;
+    protected canUntrackAsset(_coin: string): boolean;
+    protected scheduleReconnect(): void;
+    protected clearReconnectTimer(): void;
+    private guardedStart;
+}
+
+export { BaseOrchestrator, type Orchestrator, type OrchestratorConfig };

package/dist/account/exchanges/base.js

@@ -0,0 +1,63 @@
+import { reconnectDelay, clearTimer } from '../../utils/ws';
+
+class BaseOrchestrator {
+  onStateUpdate;
+  onError;
+  demo;
+  credentials = null;
+  manualClose = false;
+  reconnectAttempts = 0;
+  reconnectTimer = null;
+  trackedCoins = /* @__PURE__ */ new Set();
+  startGeneration = 0;
+  starting = false;
+  constructor(config) {
+    this.onStateUpdate = config.onStateUpdate;
+    this.onError = config.onError;
+    this.demo = config.demo;
+  }
+  trackAsset(coin) {
+    if (this.trackedCoins.has(coin)) return;
+    this.trackedCoins.add(coin);
+    if (this.isConnected) {
+      this.onAssetTracked(coin);
+    }
+  }
+  untrackAsset(coin) {
+    if (!this.trackedCoins.has(coin)) return true;
+    if (!this.canUntrackAsset(coin)) return false;
+    this.trackedCoins.delete(coin);
+    if (this.isConnected) {
+      this.onAssetUntracked(coin);
+    }
+    return true;
+  }
+  getTrackedCoins() {
+    return this.trackedCoins;
+  }
+  canUntrackAsset(_coin) {
+    return true;
+  }
+  scheduleReconnect() {
+    if (this.manualClose || !this.credentials) return;
+    this.reconnectAttempts += 1;
+    const delay = reconnectDelay(this.reconnectAttempts);
+    this.reconnectTimer = setTimeout(() => {
+      if (this.credentials && !this.starting) {
+        this.guardedStart(this.credentials);
+      }
+    }, delay);
+  }
+  clearReconnectTimer() {
+    this.reconnectTimer = clearTimer(this.reconnectTimer);
+  }
+  guardedStart(credentials) {
+    if (this.starting) return;
+    this.starting = true;
+    this.start(credentials).catch((err) => this.onError(err instanceof Error ? err : new Error(String(err)))).finally(() => {
+      this.starting = false;
+    });
+  }
+}
+
+export { BaseOrchestrator };