@pear-protocol/exchanges-sdk

@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.