@pear-protocol/exchanges-sdk 0.1.6 → 0.1.8

package/README.md

@@ -27,8 +27,15 @@ import { ExchangesSDK } from '@pear-protocol/exchanges-sdk';
 const sdk = new PearSDK({ /* ... */ });
 const exchanges = new ExchangesSDK({ sdk });
 
-const connection = await exchanges.connect(tradeAccountId, 'binance');
+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) => {
@@ -51,6 +58,59 @@ 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.
+
+```typescript
+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:
+
+```typescript
+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.
+
+```typescript
+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.
@@ -143,6 +203,7 @@ ACCOUNT_TYPE_LABELS[balance.accountType]; // "Cross Margin", "Portfolio Margin",
 
 ```typescript
 await tracker.disconnect();
+connection.ws.destroy();
 ```
 
-Credentials are fetched automatically on `connect`; for Hyperliquid and Lighter the account index is resolved from the backend.
+Credentials and the trade account are fetched automatically on `connect`; Hyperliquid and Lighter account identifiers come from `connection.account.exchangeIdentifier`.

package/dist/client/lighter/rest.js

@@ -16,6 +16,23 @@ async function fetchAccount(accountIndex) {
   if (!res.ok) throw new Error(`Lighter /account returned ${res.status}`);
   return res.json();
 }
+async function fetchAccountMetadata(accountIndex, authToken) {
+  const res = await fetch(`${LIGHTER_BASE_URL}/api/v1/accountMetadata?by=index&value=${accountIndex}`, {
+    headers: {
+      accept: "application/json",
+      authorization: authToken
+    }
+  });
+  if (!res.ok) throw new Error(`Lighter /accountMetadata returned ${res.status}`);
+  const data = await res.json();
+  if (data.code !== 200) {
+    throw new Error(`Lighter /accountMetadata returned ${data.code}: ${data.message ?? "unknown error"}`);
+  }
+  const matchesAccount = data.account_metadatas?.some((metadata) => metadata.account_index === accountIndex);
+  if (!matchesAccount) {
+    throw new Error(`Lighter /accountMetadata did not return account ${accountIndex}`);
+  }
+}
 async function fetchOrderBookDetails() {
   const res = await fetch(`${LIGHTER_BASE_URL}/api/v1/orderBookDetails?filter=perp`);
   if (!res.ok) throw new Error(`Lighter /orderBookDetails returned ${res.status}`);
@@ -58,4 +75,4 @@ async function fetchTradesSince(accountIndex, authToken, since) {
   return Array.from(byId.values());
 }
 
-export { fetchAccount, fetchAccountsByL1Address, fetchApiKeys, fetchOrderBookDetails, fetchTradesSince };
+export { fetchAccount, fetchAccountMetadata, fetchAccountsByL1Address, fetchApiKeys, fetchOrderBookDetails, fetchTradesSince };

package/dist/helper/factory.js

@@ -1,11 +1,12 @@
+import { createHyperliquidHelper } from './hyperliquid';
 import { createLighterHelper } from './lighter';
 
-function createExchangeHelper(exchange, sdk) {
-  switch (exchange) {
+function createExchangeHelper(config) {
+  switch (config.exchange) {
+    case "hyperliquid":
+      return createHyperliquidHelper();
     case "lighter":
-      return createLighterHelper(sdk);
-    default:
-      throw new Error(`Helpers not available for exchange: ${exchange}`);
+      return createLighterHelper(config.sdk);
   }
 }
 

package/dist/helper/hyperliquid/helper.js

@@ -0,0 +1,23 @@
+import { fetchInfo } from '../../client/hyperliquid/rest';
+
+function createHyperliquidHelper() {
+  return {
+    async checkApiWallet(params) {
+      const agents = await fetchInfo({
+        type: "extraAgents",
+        user: params.userAddress
+      });
+      return agents.some((agent) => agent.address.toLowerCase() === params.agentWalletAddress.toLowerCase());
+    },
+    async checkBuilderFeeApproval(userAddress, builderAddress) {
+      const maxBuilderFee = await fetchInfo({
+        type: "maxBuilderFee",
+        user: userAddress,
+        builder: builderAddress
+      });
+      return Number(maxBuilderFee) > 0;
+    }
+  };
+}
+
+export { createHyperliquidHelper };

package/dist/helper/hyperliquid/index.js

@@ -0,0 +1 @@
+export { createHyperliquidHelper } from './helper';

package/dist/helper/hyperliquid/types.js

@@ -0,0 +1 @@
+

package/dist/helper/index.js

@@ -1,2 +1,3 @@
+export * from './hyperliquid';
 export * from './lighter';
 export * from './types';