@pear-protocol/exchanges-sdk 0.18.0 → 0.19.0

package/README.md

@@ -416,3 +416,46 @@ Credentials and the trade account are fetched automatically on `connect`; Hyperl
 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.
+
+## 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>;

package/package.json

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