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

const status = await exchanges.status(connection);
if (status.status === 'warning') {
  console.warn(status.reasons);
}

const tracker = exchanges.createTracker(connection);
const syncer = exchanges.createSyncer(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 });

Connection

connect(tradeAccountId) fetches decrypted credentials and the trade account from the core API, then opens the exchange websocket.

The connector comes from the backend trade account.

const connection = await exchanges.connect(tradeAccountId);

connection.exchange; // "hyperliquid"
connection.account.exchangeIdentifier;
connection.credentials;
connection.ws;

For exchanges that need account health checks, pass status options when creating the SDK:

const exchanges = new ExchangesSDK({
  sdk,
  options: {
    builderAddress: '0x...',
    integratorAccountIndex: 1234,
  },
});

builderAddress is used to check Hyperliquid builder fee approval. integratorAccountIndex is used to check Lighter integrator approval.

Account Status

Use status(connection) to check whether the account is ready for trading through PEAR.

const status = await exchanges.status(connection);

if (status.status === 'warning') {
  for (const reason of status.reasons) {
    console.warn(reason);
  }
}

Possible warning reasons:

| Reason | Meaning | |--------|---------| | api_key_invalid | API credentials failed the exchange account check | | hyperliquid_api_wallet_invalid | Hyperliquid agent wallet is missing or invalid | | hyperliquid_builder_fee_not_approved | Hyperliquid builder fee approval is missing | | lighter_api_key_invalid | Lighter API key cannot create an auth token | | lighter_integrator_not_approved | Lighter integrator approval is missing |

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();
connection.ws.destroy();

Credentials and the trade account are fetched automatically on connect; Hyperliquid and Lighter account identifiers come from connection.account.exchangeIdentifier.