@pear-protocol/exchanges-sdk

Unified SDK for real-time account state (balance, positions, per-asset leverage) across supported derivative exchanges.

Supported Exchanges

| Exchange | Connector | Market | |----------|-----------|--------| | Binance | binance | USDM Futures | | Bybit | bybit | Linear Perpetuals | | Hyperliquid | hyperliquid | Perpetuals | | Lighter | lighter | Perpetuals | | OKX | okx | Linear SWAP |

Installation

npm install @pear-protocol/exchanges-sdk

Quick Start

import PearSDK from '@pear-protocol/core-sdk';
import { ExchangesSDK } from '@pear-protocol/exchanges-sdk';

const sdk = new PearSDK({ /* ... */ });
const exchanges = new ExchangesSDK({ sdk });

const connection = await exchanges.connect(tradeAccountId, 'binance');
const tracker = exchanges.createTracker(connection);
await tracker.start();

const offBalance = tracker.trackBalance((balance) => {
  console.log(balance.totalEquity, balance.unrealizedPnl);
});

const offPositions = tracker.trackPosition((positions) => {
  for (const p of positions) console.log(p.symbol, p.side, p.size);
});

// Cleanup
offBalance();
offPositions();
await tracker.disconnect();

Pass demo: true to target testnet:

const exchanges = new ExchangesSDK({ sdk, demo: true });

Tracking

Each track* method returns an unsubscribe function. Callbacks fire with the current snapshot on subscribe (if available) and on every update.

Balance

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;
  }
});

Positions

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
  }
});

Closed positions (size === '0') are dropped automatically.

Per-Asset Leverage & Margin

tracker.trackAsset('ETH', (info) => {
  info.coin;
  info.leverage;
  info.marginType;
});

Asset symbol format per exchange:

| Exchange | Format | Example | |----------|--------|---------| | Binance | <BASE><QUOTE> | BTCUSDT | | Bybit | <BASE><QUOTE> | BTCUSDT | | Hyperliquid | base coin | BTC | | Lighter | base coin | BTC | | OKX | instId | BTC-USDT-SWAP |

Snapshot Reads

Synchronous getters for the latest cached state:

tracker.getBalance();            // AccountBalance | null
tracker.getPositions();          // AccountPosition[]
tracker.getTrackedAsset('ETH');  // TrackedAssetInfo | null
tracker.isConnected;
tracker.isInitialized;           // true after first snapshot

Account Type Labels

balance.accountType is an exchange-specific enum. Render with:

import { ACCOUNT_TYPE_LABELS } from '@pear-protocol/exchanges-sdk';

ACCOUNT_TYPE_LABELS[balance.accountType]; // "Cross Margin", "Portfolio Margin", ...

Cleanup

await tracker.disconnect();

Credentials are fetched automatically on connect; for Hyperliquid and Lighter the account index is resolved from the backend.