fix(perps): default spot-funded order entry to perps balance cp-7.72.2

[geositta]

Description

HyperLiquid users in Unified Account Mode whose collateral is spot USDC (withdrawable = 0, spot USDC > 0) can't place orders in MetaMask Mobile even though Phantom and HL web correctly treat the same account as tradeable. Incident: TAT-3016.

What the fix does

• Introduces AccountState.availableToTradeBalance?: string = withdrawable + getSpotBalance(spotState) (USDC + USDH via SPOT_COLLATERAL_COINS allowlist, USDC-only today).
• Gates order-entry UI surfaces on availableToTradeBalance ?? availableBalance (market-details balance row, Long/Short CTA vs Add-Funds CTA, order-form submit gate).
• Preserves availableBalance = withdrawable on the withdraw path. Critical non-regression — users must never see the spot fold offered as withdrawable.
• HyperLiquid-only surface. MYX providers receive the trivial availableToTradeBalance = availableBalance field.

Matches HyperLiquid's documented unified account / portfolio margin integration pattern: reconcile clearinghouseState with spotClearinghouseState, keep availableBalance as raw withdrawable, use synthesized availableToTradeBalance for order-entry funding decisions. Also matches observed behaviour in Phantom.

Product assumption (explicit)

Spot USDC is treated as interchangeable with Perps trading collateral for the markets we currently surface.

Correct for the current USDC-only market surface and acceptable for current pre-alpha scope. Revisit when HIP-3 / non-USDC markets roll out — tracked as TAT-3047.

Shape of the change

• app/controllers/perps/types/index.ts — new optional availableToTradeBalance field on AccountState.
• app/controllers/perps/utils/accountUtils.ts — addSpotBalanceToAccountState now bumps both totalBalance and availableToTradeBalance using getSpotBalance (USDC + USDH allowlist). Wrapper helpers deleted.
• app/controllers/perps/utils/hyperLiquidAdapter.ts, providers/HyperLiquidProvider.ts, services/HyperLiquidSubscriptionService.ts — call sites updated to the folded helper; WebSocket #hashAccountState includes the new field so subscribers re-notify on change.
• app/components/UI/Perps/hooks/useDefaultPayWithTokenWhenNoPerpsBalance.ts — balance gate reads availableToTradeBalance ?? availableBalance. One internal helper + three tiny exports (useHasNativeTradeablePerpsBalance, usePreferredFallbackPayTokenCandidate, arePaymentTokensEqual) consumed by useInitPerpsPaymentToken.
• app/components/UI/Perps/Views/PerpsOrderView/useInitPerpsPaymentToken.ts — simple inference: clear saved token iff hasNativeTradeablePerpsBalance && arePaymentTokensEqual(savedToken, fallbackCandidate); else restore. No state machine, no selectedPaymentTokenSource tag.
• app/components/UI/Perps/hooks/usePerpsOrderForm.ts, Views/PerpsOrderView/PerpsOrderView.tsx, hooks/usePerpsPaymentTokens.ts, hooks/usePerpsBalanceTokenFilter.ts, components/PerpsMarketBalanceActions/PerpsMarketBalanceActions.tsx, Views/PerpsMarketDetailsView/PerpsMarketDetailsView.tsx — consume the fallback pattern.
• app/components/UI/Perps/Views/PerpsWithdrawView/PerpsWithdrawView.tsx + Perps.testIds.ts — adds perps-withdraw-available-balance-text testID on the displayed balance so automation can assert the withdraw path does not leak the fold.
• app/controllers/perps/providers/HyperLiquidProvider.ts — new getExchangeClient() public escape hatch used by admin/test flows (e.g. driving userSetAbstraction/usdClassTransfer from the agentic recipe). Not on the PerpsProvider interface.

Validation harness

scripts/perps/agentic/teams/perps/flows/:

• hl-balance-validation — captures AccountState + PerpsMarketListView balance text + PerpsWithdrawView balance text + PerpsOrderView Pay-with symbol with deterministic wait_for gates. Asserts fold invariant and no-fold-leak on withdraw.
• hl-provision-fixture — wraps exchangeClient.userSetAbstraction and exchangeClient.usdClassTransfer so recipes can cycle HL abstraction modes programmatically.

Plus hl-fixture-state eval ref in scripts/perps/agentic/teams/perps/evals.json exposing the shared balance snapshot. Every timing gate is wait_for polling a deterministic condition — no arbitrary wait: Nms.

Out of scope (deliberate)

• No contract reshape (availableBalance → spendableBalance / withdrawableBalance) — TAT-3047.
• No withdraw-path logic edits. availableBalance semantics preserved.
• No MYX logic beyond the trivial availableToTradeBalance = availableBalance field.
• No upstream @metamask/perps-controller changes.
• Mode-aware fold gating (honour Unified vs Standard on the mobile side) — TAT-3047.
• Cross-account selectedPaymentToken reset — pre-existing bug discovered during validation, filed as TAT-3050.

Known behavioural change

totalBalance on HyperLiquid AccountState now reflects withdrawable + allowlisted spot (USDC + USDH) only, not the sum of all spot coin totals. Non-stable spot holdings (e.g. HYPE) no longer contribute to the displayed total on perps surfaces. This matches the fold allowlist SPOT_COLLATERAL_COINS. Worth confirming with product if portfolio totals were relied on to include non-collateral spot.

Changelog

CHANGELOG entry: Fixed Perps order entry for HyperLiquid Unified Mode users whose collateral is spot USDC.

Related issues

Fixes: TAT-3016

Context:

• Prior merged fix (complementary): #29110
• Review strip PR (layered cleanup): #29171 — merged into this branch
• Follow-up (contract reshape): TAT-3047
• Follow-up (pay-with leak): TAT-3050

Manual testing steps

The useful validation is automated. Run bash scripts/perps/agentic/validate-recipe.sh <artifacts-dir> with the recipe below against the shared Trading account (currently in the exact "Unified Mode + spot-only" state that triggered the incident).

Feature: TAT-3016 HL abstraction cycle

  Scenario: Spot-funded Trading account cycled through Unified / Standard / Unified
    Given the Trading account (0x316B…01fA) is in Unified Mode with spot USDC collateral
    And all open positions have been closed

    When the recipe captures AccountState + PerpsMarketListView balance + PerpsWithdrawView balance + PerpsOrderView Pay-with
    And flips HL abstraction to Standard via userSetAbstraction
    And re-captures
    And flips back to Unified
    And captures once more

    Then availableToTradeBalance >= availableBalance in every phase
    And PerpsMarketListView shows the fold (≈ $100.76) in every phase
    And PerpsWithdrawView shows "Available Perps balance: $0" in every phase
    And PerpsOrderView Pay-with row shows "Perps balance" in every phase
    And teardown leaves the account in Unified Mode

Observed values on the shared Trading account (last run: 105/105 PASS):

Phase	availableBalance	availableToTradeBalance	Market-list balance	Withdraw balance	Order-form Pay-with
Initial (Unified)	$0.00	$100.75	$100.76	Available Perps balance: $0	Perps balance
After flip → Standard	$0.00	$100.75	$100.76	Available Perps balance: $0	Perps balance
Restored (Unified)	$0.00	$100.75	$100.76	Available Perps balance: $0	Perps balance

Identical balances across Unified / Standard flips are intentional per the product assumption above.

Screenshots/Recordings

Before

User cannot place orders on HL Unified Mode account with spot USDC collateral — the balance card displays $0 and the order form auto-selects an external USDC pay token with submit disabled.

After

Three-phase cycle evidence. Each phase captures market-list balance (shows fold), withdraw balance (shows withdrawable-only), and order-form Pay-with (shows Perps balance by default).

	Market list	Withdraw	Order form (Pay-with)
Initial (Unified)
After flip → Standard
Restored (Unified)

Pre-merge author checklist

• I've followed MetaMask Contributor Docs and MetaMask Mobile Coding Standards.
• I've completed the PR template to the best of my ability
• I've included tests if applicable
• I've documented my code using JSDoc format if applicable
• I've applied the right labels on the PR (see labeling guidelines). Not required for external contributors.

Performance checks (if applicable)

• I've tested on Android
• I've tested with a power user scenario
• I've instrumented key operations with Sentry traces for production performance metrics

Pre-merge reviewer checklist

• I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed).
• I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots.

---

Note

Medium Risk
Changes how perps buying power is computed and propagated (new availableToTradeBalance, spot hold handling, subscription hashing), which can affect order-entry gating and displayed balances across providers and UI surfaces.

Overview
Fixes HyperLiquid unified-mode accounts where withdrawable is 0 but spot USDC collateral exists by introducing AccountState.availableToTradeBalance and using it (fallbacking to availableBalance) to gate order-entry flows.

Controllers/adapters now compute tradeable balance by adding supported spot collateral (USDC) minus hold to perps withdrawable, aggregate it across DEX subaccounts, and include it in subscription hashing so UI updates when it changes; MYX returns a trivial availableToTradeBalance = availableBalance. UI hooks/views (market details CTA, order form validation/max, payment token lists/filtering, balance header) now prefer this tradeable balance while keeping withdraw flows pinned to availableBalance, with additional test coverage and a new withdraw-screen testID to assert the invariant.

^{Reviewed by Cursor Bugbot for commit 3c56fde. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

CLA Signature Action: All authors have signed the CLA. You may need to manually re-run the blocking PR check if it doesn't pass in a few minutes.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 7a22ab7. Configure here.}

[github-actions]

AI PR Analysis

🚫 Merge safe: false | 🟠 Risk: high

Merge decision: AI analysis did not complete — manual review required before merging.

AI analysis did not complete. Manual review recommended.

View run

[github-actions]

🔍 Smart E2E Test Selection

• Selected E2E tags: SmokePerps, SmokeWalletPlatform, SmokeConfirmations
• Selected Performance tags: @PerformancePreps
• Risk Level: medium
• AI Confidence: 88%

click to see 🤖 AI reasoning details

E2E Test Selection:
The PR introduces a new availableToTradeBalance field to the Perps account state system across providers, adapters, subscription services, and UI hooks/components. This is a focused but impactful change to the Perps feature:

1. SmokePerps (primary): The changes directly affect the Add Funds flow, balance verification, deposit flows, and balance display in the Perps interface. The availableToTradeBalance field is now used for:

   • Order form initialization (max amount, balance percentage calculations)
   • Payment token selection (whether to auto-select a custom token when perps balance is low)
   • Balance display in PerpsMarketBalanceActions
   • "Add Funds" CTA visibility in PerpsMarketDetailsView
   • Token filter for payment options
     All SmokePerps test scenarios (Add Funds flow, balance verification, balance updates) are directly impacted.

2. SmokeWalletPlatform (required per SmokePerps tag description): Perps is a section inside the Trending tab. Changes to Perps views (PerpsMarketDetailsView, PerpsWithdrawView, PerpsMarketBalanceActions) affect Trending. Per the tag description: "When selecting SmokePerps, also select SmokeWalletPlatform (Trending section)."

3. SmokeConfirmations (required per SmokePerps tag description): The Add Funds flow involves on-chain transactions (deposits). Per the tag description: "When selecting SmokePerps, also select SmokeConfirmations (Add Funds deposits are on-chain transactions)."

The changes are well-scoped to the Perps feature domain. No changes to core Engine, navigation, browser, accounts, networks, or other unrelated features. The new getExchangeClient() method in HyperLiquidProvider is an admin/test escape hatch that doesn't affect production flows. The test ID addition to PerpsWithdrawView is a minor enhancement for test automation.

Performance Test Selection:
The changes modify how the Perps account balance is calculated and displayed (availableToTradeBalance vs availableBalance). This affects the PerpsMarketBalanceActions component (balance display), PerpsMarketDetailsView (Add Funds CTA), and the order form initialization. The @PerformancePreps tag covers perps market loading, position management, add funds flow, and balance display - all of which are directly impacted by this balance calculation change. The new getAvailableToTradeSpotBalance() utility function adds computation to the account state aggregation path which could affect rendering performance.

View GitHub Actions results

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
88.7% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[github-actions]

✅ E2E Fixture Validation — Schema is up to date
12 value mismatches detected (expected — fixture represents an existing user).
View details

[geositta]

Closing in favor of starting new branch to handle through spotState websocket subscription.