MetaMask
diff --git a/‎app/components/UI/Perps/Perps.testIds.ts‎
Lines changed: 6 additions & 0 deletions b/‎app/components/UI/Perps/Perps.testIds.ts‎
Lines changed: 6 additions & 0 deletions
diff --git a/‎app/components/UI/Perps/Views/PerpsMarketDetailsView/PerpsMarketDetailsView.tsx‎
Lines changed: 5 additions & 3 deletions b/‎app/components/UI/Perps/Views/PerpsMarketDetailsView/PerpsMarketDetailsView.tsx‎
Lines changed: 5 additions & 3 deletions
diff --git a/‎app/components/UI/Perps/Views/PerpsWithdrawView/PerpsWithdrawView.tsx‎
Lines changed: 5 additions & 1 deletion b/‎app/components/UI/Perps/Views/PerpsWithdrawView/PerpsWithdrawView.tsx‎
Lines changed: 5 additions & 1 deletion
diff --git a/‎app/components/UI/Perps/components/PerpsMarketBalanceActions/PerpsMarketBalanceActions.tsx‎
Lines changed: 7 additions & 1 deletion b/‎app/components/UI/Perps/components/PerpsMarketBalanceActions/PerpsMarketBalanceActions.tsx‎
Lines changed: 7 additions & 1 deletion
diff --git a/‎app/components/UI/Perps/hooks/useDefaultPayWithTokenWhenNoPerpsBalance.ts‎
Lines changed: 6 additions & 7 deletions b/‎app/components/UI/Perps/hooks/useDefaultPayWithTokenWhenNoPerpsBalance.ts‎
Lines changed: 6 additions & 7 deletions
diff --git a/‎app/components/UI/Perps/hooks/usePerpsOrderForm.ts‎
Lines changed: 3 additions & 1 deletion b/‎app/components/UI/Perps/hooks/usePerpsOrderForm.ts‎
Lines changed: 3 additions & 1 deletion
diff --git a/‎app/components/UI/Perps/utils/hyperLiquidAdapter.test.ts‎
Lines changed: 3 additions & 0 deletions b/‎app/components/UI/Perps/utils/hyperLiquidAdapter.test.ts‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎app/controllers/perps/providers/HyperLiquidProvider.test.ts‎
Lines changed: 17 additions & 2 deletions b/‎app/controllers/perps/providers/HyperLiquidProvider.test.ts‎
Lines changed: 17 additions & 2 deletions
diff --git a/‎app/controllers/perps/providers/HyperLiquidProvider.ts‎
Lines changed: 14 additions & 0 deletions b/‎app/controllers/perps/providers/HyperLiquidProvider.ts‎
Lines changed: 14 additions & 0 deletions
diff --git a/‎app/controllers/perps/services/HyperLiquidSubscriptionService.test.ts‎
Lines changed: 121 additions & 0 deletions b/‎app/controllers/perps/services/HyperLiquidSubscriptionService.test.ts‎
Lines changed: 121 additions & 0 deletions
@@ -323,6 +323,12 @@ export const PerpsWithdrawViewSelectorsIDs = {
   DEST_TOKEN_AREA: 'dest-token-area',
   CONTINUE_BUTTON: 'continue-button',
   BOTTOM_SHEET_TOOLTIP: 'withdraw-bottom-sheet-tooltip',
+  RECEIVE_VALUE: 'perps-withdraw-receive-value',
+  FEE_VALUE: 'perps-withdraw-fee-value',
+  TIME_VALUE: 'perps-withdraw-time-value',
+  // Must render availableBalance only (not availableToTradeBalance):
+  // withdraw does not offer spot collateral.
+  AVAILABLE_BALANCE_TEXT: 'perps-withdraw-available-balance-text',
 };
 
 // ========================================
 
@@ -436,12 +436,14 @@ const PerpsMarketDetailsView: React.FC<PerpsMarketDetailsViewProps> = () => {
     useDefaultPayWithTokenWhenNoPerpsBalance();
   const { depositWithConfirmation } = usePerpsTrading();
   const { navigateToConfirmation } = useConfirmNavigation();
-  const availableBalance = Number.parseFloat(
-    account?.availableBalance?.toString() ?? '0',
+  const tradeableBalance = Number.parseFloat(
+    account?.availableToTradeBalance?.toString() ??
+      account?.availableBalance?.toString() ??
+      '0',
   );
   const hasDirectOrderFundingPath =
     !isLoadingAccount &&
-    (availableBalance >= PERPS_MIN_BALANCE_THRESHOLD ||
+    (tradeableBalance >= PERPS_MIN_BALANCE_THRESHOLD ||
       defaultPayTokenWhenNoPerpsBalance !== null);
 
   const handleAddFunds = useCallback(async () => {
 
@@ -406,7 +406,11 @@ const PerpsWithdrawView: React.FC = () => {
                 ]}
               />
             </Box>
-            <Text variant={TextVariant.BodyMD} color={TextColor.Alternative}>
+            <Text
+              variant={TextVariant.BodyMD}
+              color={TextColor.Alternative}
+              testID={PerpsWithdrawViewSelectorsIDs.AVAILABLE_BALANCE_TEXT}
+            >
               {strings('perps.withdrawal.available_balance', {
                 amount: formattedBalance,
               })}
 
@@ -182,7 +182,13 @@ const PerpsMarketBalanceActions: React.FC<PerpsMarketBalanceActionsProps> = ({
     [stopBalanceAnimation],
   );
 
-  const availableBalance = perpsAccount?.availableBalance || '0';
+  // Order-entry surface reads availableToTradeBalance (withdrawable +
+  // unreserved spot collateral). Withdraw surfaces keep reading
+  // availableBalance directly.
+  const availableBalance =
+    perpsAccount?.availableToTradeBalance ??
+    perpsAccount?.availableBalance ??
+    '0';
 
   // Show skeleton while loading initial account data
   if (isInitialLoading) {
 
@@ -39,15 +39,13 @@ export function useDefaultPayWithTokenWhenNoPerpsBalance(): PerpsSelectedPayment
     if (!featureEnabled) {
       return null;
     }
-    // Gate on availableBalance (spendable): order-form pay-token preselection
-    // must fire when withdrawable is 0 but totalBalance > 0 (spot-funded or
-    // margin-locked). The CTA consumer layers its own totalBalance guard on
-    // top of this hook's result to hide "Add Funds" for spot-funded accounts.
-    const availableBalance = Number.parseFloat(
-      perpsAccount?.availableBalance?.toString() ?? '0',
+    const tradeableBalance = Number.parseFloat(
+      perpsAccount?.availableToTradeBalance?.toString() ??
+        perpsAccount?.availableBalance?.toString() ??
+        '0',
     );
 
-    if (availableBalance > PERPS_MIN_BALANCE_THRESHOLD) {
+    if (tradeableBalance > PERPS_MIN_BALANCE_THRESHOLD) {
       return null;
     }
     if (!allowlistAssets?.length) {
@@ -97,6 +95,7 @@ export function useDefaultPayWithTokenWhenNoPerpsBalance(): PerpsSelectedPayment
   }, [
     featureEnabled,
     perpsAccount?.availableBalance,
+    perpsAccount?.availableToTradeBalance,
     allowlistAssets,
     activeProvider,
     currentNetwork,
 
@@ -92,7 +92,9 @@ export function usePerpsOrderForm(
   const availableBalance = Number.parseFloat(
     effectiveAvailableBalanceParam != null
       ? effectiveAvailableBalanceParam.toString()
-      : (account?.availableBalance?.toString() ?? '0'),
+      : (account?.availableToTradeBalance?.toString() ??
+          account?.availableBalance?.toString() ??
+          '0'),
   );
 
   // When paying with a custom token, use selected token amount in USD (including 0); otherwise use Perps balance
 
@@ -1077,6 +1077,7 @@ describe('hyperLiquidAdapter', () => {
 
       expect(result).toEqual({
         availableBalance: '700.25',
+        availableToTradeBalance: '700.25', // withdrawable + free spot (no spot provided)
         marginUsed: '300.25',
         unrealizedPnl: '24.5', // 50.0 + (-25.5)
         returnOnEquity: '7.991673605328893', // Calculated from weighted return and margin
@@ -1120,6 +1121,7 @@ describe('hyperLiquidAdapter', () => {
 
       expect(result).toEqual({
         availableBalance: '350.0',
+        availableToTradeBalance: '850.5', // withdrawable 350 + free spot 500.5 (hold = 0)
         marginUsed: '150.0',
         unrealizedPnl: '100',
         returnOnEquity: '0',
@@ -1158,6 +1160,7 @@ describe('hyperLiquidAdapter', () => {
 
       expect(result).toEqual({
         availableBalance: '800.0',
+        availableToTradeBalance: '800', // withdrawable + 0 (no spot totals)
         marginUsed: '200.0',
         unrealizedPnl: '0',
         returnOnEquity: '0',
 
@@ -2148,7 +2148,7 @@ describe('HyperLiquidProvider', () => {
       const accountState = await provider.getAccountState();
 
       expect(accountState).toBeDefined();
-      expect(accountState.totalBalance).toBe('20500'); // 10000 (spot) + 10500 (perps marginSummary)
+      expect(accountState.totalBalance).toBe('19500'); // 10500 (perps) + 10000 (spot.total) - 1000 (spot.hold, double-counted in accountValue)
       expect(
         mockClientService.getInfoClient().clearinghouseState,
       ).toHaveBeenCalled();
@@ -3786,7 +3786,7 @@ describe('HyperLiquidProvider', () => {
 
         const accountState = await hip3Provider.getAccountState();
 
-        expect(parseFloat(accountState.totalBalance)).toBe(20500);
+        expect(parseFloat(accountState.totalBalance)).toBe(19500); // perps 10500 + spot.total 10000 - spot.hold 1000
         expect(parseFloat(accountState.marginUsed)).toBe(500);
         expect(mockInfoClient.clearinghouseState).toHaveBeenCalledWith({
           user: '0x123',
@@ -9821,4 +9821,19 @@ describe('HyperLiquidProvider', () => {
       expect(Array.isArray(markets)).toBe(true);
     });
   });
+
+  describe('getExchangeClient escape hatch', () => {
+    it('delegates to the client service and resolves with the underlying ExchangeClient', async () => {
+      const sentinel = mockClientService.getExchangeClient();
+      await expect(provider.getExchangeClient()).resolves.toBe(sentinel);
+    });
+
+    it('propagates errors thrown by the client service', async () => {
+      const bomb = new Error('client not initialized');
+      mockClientService.getExchangeClient = jest.fn(() => {
+        throw bomb;
+      });
+      await expect(provider.getExchangeClient()).rejects.toBe(bomb);
+    });
+  });
 });
@@ -1,5 +1,6 @@
 import { CaipAccountId, hasProperty } from '@metamask/utils';
 import type { Hex } from '@metamask/utils';
+import type { ExchangeClient } from '@nktkas/hyperliquid';
 import { v4 as uuidv4 } from 'uuid';
 
 import type { CandlePeriod } from '../constants/chartConfig';
@@ -7772,6 +7773,19 @@ export class HyperLiquidProvider implements PerpsProvider {
     }
   }
 
+  /**
+   * Escape hatch for agentic validation flows and test harnesses that drive
+   * HL mutations directly. NOT part of the PerpsProvider interface.
+   * Production code paths must go through the provider's own methods.
+   *
+   * @returns A promise resolving to the underlying HyperLiquid SDK
+   * ExchangeClient. Promise shape matches the existing agentic flows
+   * (hl-provision-fixture) that chain `.then` on the result.
+   */
+  public async getExchangeClient(): Promise<ExchangeClient> {
+    return this.#clientService.getExchangeClient();
+  }
+
   /**
    * Disconnect provider
    *
 
@@ -283,6 +283,12 @@ describe('HyperLiquidSubscriptionService', () => {
         }, 0);
         return Promise.resolve(mockSubscription);
       }),
+      spotState: jest.fn((_params: any, _callback: any) =>
+        // Default: subscribe resolves but never emits. Tests that need the
+        // push-driven path call mockSubscriptionClient.spotState.mock.calls[0][1]
+        // manually to drive the handler.
+        Promise.resolve(mockSubscription),
+      ),
       l2Book: jest.fn((_params: any, callback: any) => {
         // Simulate l2Book data
         setTimeout(() => {
@@ -3684,6 +3690,121 @@ describe('HyperLiquidSubscriptionService', () => {
     });
   });
 
+  describe('spotState WebSocket Subscription', () => {
+    it('establishes a spotState subscription on subscribeToAccount', async () => {
+      const unsubscribe = service.subscribeToAccount({
+        callback: jest.fn(),
+      });
+      await jest.runAllTimersAsync();
+
+      expect(mockSubscriptionClient.spotState).toHaveBeenCalledWith(
+        expect.objectContaining({ user: expect.stringMatching(/^0x/) }),
+        expect.any(Function),
+      );
+
+      unsubscribe();
+    });
+
+    it('does not re-subscribe spotState for the same user', async () => {
+      const unsubscribe1 = service.subscribeToAccount({
+        callback: jest.fn(),
+      });
+      const unsubscribe2 = service.subscribeToAccount({
+        callback: jest.fn(),
+      });
+      await jest.runAllTimersAsync();
+
+      expect(mockSubscriptionClient.spotState).toHaveBeenCalledTimes(1);
+
+      unsubscribe1();
+      unsubscribe2();
+    });
+
+    it('re-notifies account subscribers when a spotState push arrives', async () => {
+      // Seed aggregation with a perps tick so #dexAccountCache is non-empty,
+      // which is the guard the handler uses before calling
+      // #aggregateAndNotifySubscribers.
+      const firstCallback = jest.fn();
+      const firstUnsubscribe = service.subscribeToAccount({
+        callback: firstCallback,
+      });
+      await jest.runAllTimersAsync();
+
+      const notifyCallback = jest.fn();
+      const unsubscribe = service.subscribeToAccount({
+        callback: notifyCallback,
+      });
+      await jest.runAllTimersAsync();
+
+      const callsBefore = notifyCallback.mock.calls.length;
+
+      const spotListener = mockSubscriptionClient.spotState.mock.calls[0][1];
+      spotListener({
+        user: '0x123',
+        spotState: {
+          balances: [
+            {
+              coin: 'USDC',
+              token: 0,
+              hold: '0',
+              total: '123.45',
+              entryNtl: '123.45',
+            },
+          ],
+        },
+      });
+
+      expect(notifyCallback.mock.calls.length).toBeGreaterThan(callsBefore);
+
+      firstUnsubscribe();
+      unsubscribe();
+    });
+
+    it('ignores spotState events for a different user', async () => {
+      // First seed perps state so the handler's re-aggregate guard could fire.
+      const unsubscribe = service.subscribeToAccount({
+        callback: jest.fn(),
+      });
+      await jest.runAllTimersAsync();
+
+      const observerCallback = jest.fn();
+      const observerUnsubscribe = service.subscribeToAccount({
+        callback: observerCallback,
+      });
+      await jest.runAllTimersAsync();
+
+      const callsBefore = observerCallback.mock.calls.length;
+
+      const spotListener = mockSubscriptionClient.spotState.mock.calls[0][1];
+      spotListener({
+        user: '0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef',
+        spotState: { balances: [] },
+      });
+
+      expect(observerCallback.mock.calls.length).toBe(callsBefore);
+
+      observerUnsubscribe();
+      unsubscribe();
+    });
+
+    it('unsubscribes spotState when the last account subscriber leaves', async () => {
+      const unsubSpot = jest.fn().mockResolvedValue(undefined);
+      mockSubscriptionClient.spotState.mockResolvedValueOnce({
+        unsubscribe: unsubSpot,
+      });
+
+      const unsubscribe = service.subscribeToAccount({
+        callback: jest.fn(),
+      });
+      await jest.runAllTimersAsync();
+
+      unsubscribe();
+      await jest.runAllTimersAsync();
+
+      expect(unsubSpot).toHaveBeenCalled();
+    });
+  });
+
   describe('spot-adjusted account balance parity', () => {
     it('includes spot balance exactly once in streamed totalBalance across multiple DEXs', async () => {
       jest.mocked(adaptAccountStateFromSDK).mockImplementation(() => ({