@pear-protocol/exchanges-sdk 0.18.0 → 0.19.1

package/README.md

@@ -413,6 +413,49 @@ await tracker.disconnect(); // closes the WebSocket opened by start()
 
 Credentials and the trade account are fetched automatically on `connect`; Hyperliquid and Lighter account identifiers come from `connection.account.exchangeIdentifier`.
 
-Pear returns the public trader identity only while its owner enables `sharingEnabled` in
-trade account settings. Disabling it hides future Pear reads; the exchange public APIs
-remain address-based and independent of Pear consent.
+Pear exposes public trader reads for active accounts without separate sharing or copying
+settings. The default leaderboard requires a linked X account; hiding X omits the identity
+without removing the rank. Exchange public APIs remain address-based.
+
+## Hyperliquid subaccount funding
+
+```typescript
+import { createHyperliquidHelper } from '@pear-protocol/exchanges-sdk';
+
+const helper = createHyperliquidHelper();
+await helper.transferSubAccount(ownerWallet, {
+  subAccountAddress: '0x...',
+  direction: 'main-to-subaccount', // use 'subaccount-to-main' to return USDC
+  amount: '1.25',
+});
+```
+
+Supply the owning main account's wallet (a viem wallet client/account or an ethers signer) in both
+directions. Every transfer uses owner-signed `sendAsset` with `sourceDex: "spot"` and
+`destinationDex: "spot"`. An approved API agent cannot sign this action. Browser wallet clients use
+their connected chain for EIP-712 signing.
+
+For standard accounts, this moves the separate spot USDC balance and does not fund perpetual
+collateral. Unified and portfolio-margin accounts use their shared spot balance. The helper checks
+subaccount ownership before signing. It does not read or change either account's mode.
+
+A newly created standard subaccount receives USDC in spot and cannot use that balance as perpetual
+margin. Before trading perps, make a separate owner-signed
+[`usdClassTransfer`](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#transfer-from-spot-account-to-perp-account-and-vice-versa)
+with `toPerp: true` and `subaccount:<address>` appended to the amount. The funding helper does not
+submit this second action. A standard main account with USDC in perps must first move the intended
+amount to spot before calling this helper.
+
+The helper uses a fixed USDC token ID for the selected network without a metadata lookup, and the
+amount stays an exact decimal string. Each successful transfer makes two information reads: the
+signer's role and the subaccount's role and ownership. It then submits one transfer action.
+
+Amounts must be positive decimal strings with at most six fractional digits and must fit the
+existing safe integer micro-USDC limit (`9007199254.740991` USDC). The helper never rounds an amount.
+
+Failures reach the caller without retries or fallback actions. After a timeout or connection loss,
+check transfer history and balances before making another call; submission may have succeeded.
+
+The routing and signing follow Hyperliquid's [Send Asset API](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint#send-asset),
+[account modes](https://hyperliquid.gitbook.io/hyperliquid-docs/trading/account-abstraction-modes),
+and [official signing implementation](https://github.com/hyperliquid-dex/hyperliquid-python-sdk/blob/master/hyperliquid/utils/signing.py).

package/dist/helper/hyperliquid/helper.js

@@ -1,10 +1,16 @@
 import { HttpTransport } from '@nktkas/hyperliquid';
-import { subAccountTransfer, createSubAccount } from '@nktkas/hyperliquid/api/exchange';
+import { sendAsset, createSubAccount } from '@nktkas/hyperliquid/api/exchange';
+import { getWalletAddress } from '@nktkas/hyperliquid/signing';
+import { formatUnits } from 'viem';
 import { fetchInfo, fetchUserRole } from '../../client/hyperliquid/rest';
 import { parseCollateralAmount } from '../subaccount.helper';
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+const USDC_TOKENS = {
+  mainnet: "USDC:0x6d1e7cde53ba9467b783cb7c530ce054",
+  testnet: "USDC:0xeb62eee3685fc4c43992febcd9e75443"
+};
 function createHyperliquidHelper(demo = false) {
   return {
     /**
@@ -33,19 +39,35 @@ function createHyperliquidHelper(demo = false) {
         subAccountAddress: response.response.data
       };
     },
-    /** Moves perpetual USDC between a main account and one of its subaccounts. */
+    /** Moves spot USDC between owned accounts using the owning main wallet. */
     async transferSubAccount(wallet, params) {
       const usd = parseCollateralAmount(params.amount, "USDC");
+      const ownerAddress = await getWalletAddress(wallet);
+      const signerRole = await fetchUserRole(ownerAddress, demo);
+      if (signerRole.role === "agent") {
+        throw new Error("Spot subaccount transfers require the owner wallet; an approved agent cannot sign");
+      }
+      if (signerRole.role !== "user") {
+        throw new Error("Spot subaccount transfers require the owner wallet");
+      }
+      const subAccountRole = await fetchUserRole(params.subAccountAddress, demo);
+      if (subAccountRole.role !== "subAccount" || subAccountRole.data.master.toLowerCase() !== ownerAddress.toLowerCase()) {
+        throw new Error("Subaccount does not belong to the signing main account");
+      }
+      const isDeposit = isMainToSubAccount(params.direction);
       const transport = new HttpTransport({
         isTestnet: demo
       });
-      await subAccountTransfer({
+      await sendAsset({
         transport,
         wallet
       }, {
-        subAccountUser: params.subAccountAddress,
-        isDeposit: isMainToSubAccount(params.direction),
-        usd
+        destination: isDeposit ? params.subAccountAddress : ownerAddress,
+        sourceDex: "spot",
+        destinationDex: "spot",
+        token: demo ? USDC_TOKENS.testnet : USDC_TOKENS.mainnet,
+        amount: formatUnits(BigInt(usd), 6),
+        fromSubAccount: isDeposit ? "" : params.subAccountAddress
       });
     },
     /** Lists a main account's existing subaccounts for transfer-destination selection. */

package/dist/index.d.ts

@@ -429,6 +429,7 @@ type SubAccountTransferDirection = 'main-to-subaccount' | 'subaccount-to-main';
 interface HyperliquidHelper {
     checkAccountActivation(userAddress: `0x${string}`): Promise<boolean>;
     createSubAccount(wallet: AbstractWallet, params: CreateHyperliquidSubAccountParams): Promise<CreateHyperliquidSubAccountResult>;
+    /** Transfers spot USDC in either direction; requires the owning main wallet, never an agent. */
     transferSubAccount(wallet: AbstractWallet, params: HyperliquidSubAccountTransferParams): Promise<void>;
     listSubAccounts(userAddress: `0x${string}`): Promise<HyperliquidSubAccountSummary[]>;
     checkApiWallet(params: CheckApiWalletParams): Promise<boolean>;
@@ -1448,10 +1449,13 @@ declare class LighterAccountSyncer extends BaseAccountSyncer<RawFill$1> {
     protected listExternalFunding({ since, instruments, }: ListExternalFundingParams): Promise<HttpTypes.FundingPaymentEntry[]>;
     protected isReduceOnly(rawFill: RawFill$1): boolean;
     private getAccountSide;
+    /** The client order id on our side of the fill, or null when Lighter reports none. */
     private getClientOrderId;
     private isMaker;
     private getPositionSizeBefore;
+    /** Signed like the rate: positive is a cost, a negative rate a maker rebate (#748). */
     private getTradeFee;
+    /** The integrator's cut, which the wire carries unsigned. */
     private getIntegratorFee;
     /** Prevents testnet reads from silently minting a mainnet auth token. */
     private assertAuthenticatedSyncAvailable;

package/dist/syncer/binance/syncer.js

@@ -1,6 +1,7 @@
 import BigNumber from 'bignumber.js';
 import { fetchAllPositionRisk, fetchUserTradesSince, fetchAllOrdersSince } from '../../client/binance/rest';
 import { BaseAccountSyncer } from '../base';
+import { toSignedTradeFee } from '../trade-fee';
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
@@ -66,7 +67,7 @@ class BinanceAccountSyncer extends BaseAccountSyncer {
         side: rawFill.side,
         reduceOnly: this.isReduceOnly(rawFill),
         timestamp: rawFill.time,
-        tradeFee: new BigNumber(rawFill.commission || 0).abs().toFixed(),
+        tradeFee: toSignedTradeFee("binance", rawFill.commission),
         builderFee: "0",
         liquidation: null
       });

package/dist/syncer/bybit/syncer.js

@@ -1,6 +1,7 @@
 import BigNumber from 'bignumber.js';
 import { fetchPositions, fetchExecutionsSince } from '../../client/bybit/rest';
 import { BaseAccountSyncer } from '../base';
+import { toSignedTradeFee } from '../trade-fee';
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
@@ -36,6 +37,9 @@ class BybitAccountSyncer extends BaseAccountSyncer {
   async listExternalFills({ since }) {
     const executions = await fetchExecutionsSince(this.creds, since, this.demo);
     return executions.reduce((fills, rawFill) => {
+      if (rawFill.execType === "Funding") {
+        return fills;
+      }
       fills.push({
         connector: "bybit",
         exchangeFillId: rawFill.execId,
@@ -46,7 +50,7 @@ class BybitAccountSyncer extends BaseAccountSyncer {
         side: rawFill.side === "Buy" ? "BUY" : "SELL",
         reduceOnly: this.isReduceOnly(rawFill),
         timestamp: Number(rawFill.execTime),
-        tradeFee: new BigNumber(rawFill.execFee || 0).abs().toFixed(),
+        tradeFee: toSignedTradeFee("bybit", rawFill.execFee),
         builderFee: "0",
         liquidation: null
       });

package/dist/syncer/lighter/syncer.js

@@ -119,8 +119,10 @@ class LighterAccountSyncer extends BaseAccountSyncer {
     if (rawFill.bid_account_id === this.accountIndex) return "bid";
     return null;
   }
+  /** The client order id on our side of the fill, or null when Lighter reports none. */
   getClientOrderId(rawFill, side) {
-    return (side === "ask" ? rawFill.ask_client_id_str : rawFill.bid_client_id_str) || null;
+    const clientOrderId = side === "ask" ? rawFill.ask_client_id_str : rawFill.bid_client_id_str;
+    return clientOrderId && clientOrderId !== "0" ? clientOrderId : null;
   }
   isMaker(rawFill, side) {
     return side === "ask" ? rawFill.is_maker_ask : !rawFill.is_maker_ask;
@@ -129,13 +131,15 @@ class LighterAccountSyncer extends BaseAccountSyncer {
     const value = this.isMaker(rawFill, side) ? rawFill.maker_position_size_before : rawFill.taker_position_size_before;
     return new BigNumber(value ?? 0);
   }
+  /** Signed like the rate: positive is a cost, a negative rate a maker rebate (#748). */
   getTradeFee(rawFill, side) {
     const rateTick = this.isMaker(rawFill, side) ? rawFill.maker_fee : rawFill.taker_fee;
-    return this.feeTickToAmount(rateTick, rawFill.usd_amount);
+    return this.feeTickToAmount(rateTick, rawFill.usd_amount).toFixed();
   }
+  /** The integrator's cut, which the wire carries unsigned. */
   getIntegratorFee(rawFill, side) {
     const rateTick = this.isMaker(rawFill, side) ? rawFill.integrator_maker_fee : rawFill.integrator_taker_fee;
-    return this.feeTickToAmount(rateTick, rawFill.usd_amount);
+    return this.feeTickToAmount(rateTick, rawFill.usd_amount).abs().toFixed();
   }
   /** Prevents testnet reads from silently minting a mainnet auth token. */
   assertAuthenticatedSyncAvailable() {
@@ -145,8 +149,8 @@ class LighterAccountSyncer extends BaseAccountSyncer {
   }
   // Lighter fees come as ppm rates (÷1e6), not amounts — the charged fee is that rate times the trade's USD notional.
   feeTickToAmount(rateTick, usdAmount) {
-    const rate = new BigNumber(rateTick ?? 0).abs().div(LIGHTER_FEE_TICK_DENOMINATOR);
-    return rate.times(usdAmount).toFixed();
+    const rate = new BigNumber(rateTick ?? 0).div(LIGHTER_FEE_TICK_DENOMINATOR);
+    return rate.times(usdAmount);
   }
 }
 

package/dist/syncer/okx/syncer.js

@@ -1,6 +1,7 @@
 import BigNumber from 'bignumber.js';
 import { fetchPositions, fetchFillsHistorySince } from '../../client/okx/rest';
 import { BaseAccountSyncer } from '../base';
+import { toSignedTradeFee } from '../trade-fee';
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
@@ -51,7 +52,7 @@ class OkxAccountSyncer extends BaseAccountSyncer {
         side: rawFill.side === "buy" ? "BUY" : "SELL",
         reduceOnly: this.isReduceOnly(rawFill),
         timestamp: Number(rawFill.fillTime || rawFill.ts),
-        tradeFee: new BigNumber(rawFill.fee || 0).abs().toFixed(),
+        tradeFee: toSignedTradeFee("okx", rawFill.fee),
         builderFee: "0",
         liquidation: null
       });

package/dist/syncer/trade-fee.js

@@ -0,0 +1,21 @@
+import { parse, negate } from '@pear-protocol/utils';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+function toSignedTradeFee(connector, rawFee) {
+  const fee = parse(rawFee || "0");
+  switch (connector) {
+    // Binance `userTrades.commission`: a charge is positive. The docs do not state a rebate's sign; it is
+    // taken to be negative, the same convention as ours.
+    case "binance":
+    // Bybit `execution/list.execFee`: positive is an expense, negative a rebate (v5 transaction-log docs).
+    case "bybit":
+      return fee.toFixed();
+    // OKX `fills-history.fee`: a deduction is negative, a rebate positive (v5 docs), the opposite of ours.
+    case "okx":
+      return negate(fee).toFixed();
+  }
+}
+__name(toSignedTradeFee, "toSignedTradeFee");
+
+export { toSignedTradeFee };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pear-protocol/exchanges-sdk",
-  "version": "0.18.0",
+  "version": "0.19.1",
   "description": "Pear Protocol Exchanges SDK",
   "private": false,
   "type": "module",
@@ -28,9 +28,9 @@
   },
   "dependencies": {
     "@nktkas/hyperliquid": "0.33.2",
-    "@pear-protocol/core-sdk": "^2.5.0",
-    "@pear-protocol/types": "^2.12.0",
-    "@pear-protocol/utils": "^1.3.0",
+    "@pear-protocol/core-sdk": "^2.12.0",
+    "@pear-protocol/types": "^2.19.0",
+    "@pear-protocol/utils": "^1.4.0",
     "bignumber.js": "^11.1.1",
     "partysocket": "^1.0.3",
     "viem": "^2.48.8",