feat(perps): show a trading halt notice when the deviation is above threshold (MetaMask#23242)

<!--
Please submit this PR as a draft initially.
Do not mark it as "Ready for review" until the template has been
completely filled out, and PR status checks have passed at least once.
-->

## **Description**

This PR adds a price deviation warning feature to the Perps trading
interface. When the perps price deviates more than 10% from the spot
price (mark price), a warning banner is displayed to inform users that
new positions cannot be opened at that time. This helps protect users
from executing trades at unfavorable prices during periods of
significant price divergence.


## **Changelog**

CHANGELOG entry: Added price deviation warning to Perps trading
interface to prevent opening positions when perps price deviates
significantly from spot price

## **Related issues**

Fixes: https://consensyssoftware.atlassian.net/browse/TAT-2047

## **Manual testing steps**

```gherkin
Feature: Perps Price Deviation Warning

  Scenario: user views market details when price deviation is within threshold
    Given user is on the Perps Market Details view for BTC
    And the asset price is within 10% of the spot price
    When user views the market details page
    Then no price deviation warning should be displayed

  Scenario: user views market details when price deviation exceeds threshold
    Given user is on the Perps Market Details view for BTC
    And the perps price deviates more than 10% from the spot price
    When user views the market details page
    Then a price deviation warning banner should be displayed
    And the warning message should indicate that new positions cannot be opened

  Scenario: warning updates dynamically as price changes
    Given user is on the Perps Market Details view for BTC
    And the perps price initially deviates more than 10% from spot price
    When the price deviation decreases below 10%
    Then the warning banner should disappear
```

## **Screenshots/Recordings**

<!-- If applicable, add screenshots and/or recordings to visualize the
before and after of your change. -->

### **Before**

No notice shown

### **After**
Notice shown

<img width="1170" height="2532" alt="Simulator Screenshot - iPhone 16e -
2025-11-25 at 11 17 03"
src="https://github.com/user-attachments/assets/02cfb5d5-f57f-4101-8e8c-a852af73b606"
/>


## **Pre-merge author checklist**

- [x] I’ve followed [MetaMask Contributor
Docs](https://github.com/MetaMask/contributor-docs) and [MetaMask Mobile
Coding
Standards](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/CODING_GUIDELINES.md).
- [x] I've completed the PR template to the best of my ability
- [x] I’ve included tests if applicable
- [x] I’ve documented my code using [JSDoc](https://jsdoc.app/) format
if applicable
- [x] I’ve applied the right labels on the PR (see [labeling
guidelines](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/LABELING_GUIDELINES.md)).
Not required for external contributors.

## **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.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Introduces a price deviation check and warning banner that disables
trade actions when perps price deviates beyond a configured threshold
from spot.
> 
> - **UI**
> - Add `PerpsPriceDeviationWarning` component and render it in
`PerpsMarketDetailsView` when `useIsPriceDeviatedAboveThreshold` signals
trading halt.
> - Hide fixed actions footer (Add Funds / Long / Short / Modify /
Close) while trading is halted.
> - Minor cleanup: remove unnecessary fragment around
`TradingViewChart`.
> - **Hooks**
> - New `useIsPriceDeviatedAboveThreshold(symbol)` leveraging
`usePerpsPrices` to detect deviation; exported via `hooks/index`.
> - **Config**
>   - Add `VALIDATION_THRESHOLDS.PRICE_DEVIATION` (10%).
> - **i18n**
>   - Add `perps.price_deviation_warning.message` copy.
> - **Tests**
> - Add comprehensive unit tests for `useIsPriceDeviatedAboveThreshold`.
> - Update `PerpsMarketDetailsView.test.tsx` with mocks for new hook and
connections; ensure rendering compatibility.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
81d14af. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: michalconsensys

app/components/UI/Perps/Views/PerpsMarketDetailsView/PerpsMarketDetailsView.test.tsx

@@ -182,13 +182,32 @@ jest.mock('react-redux', () => ({
   useSelector: jest.fn(),
 }));
 
+// Mock usePerpsConnection hook directly to ensure all hooks that import it get the mock
+jest.mock('../../hooks/usePerpsConnection', () => ({
+  usePerpsConnection: () => ({
+    isConnected: true,
+    isConnecting: false,
+    isInitialized: true,
+    error: null,
+    connect: jest.fn(),
+    disconnect: jest.fn(),
+    resetError: jest.fn(),
+    reconnectWithNewContext: jest.fn(),
+  }),
+}));
+
 jest.mock('../../providers/PerpsConnectionProvider', () => ({
   PerpsConnectionProvider: ({ children }: { children: React.ReactNode }) =>
     children,
   usePerpsConnection: () => ({
     isConnected: true,
     isConnecting: false,
+    isInitialized: true,
     error: null,
+    connect: jest.fn(),
+    disconnect: jest.fn(),
+    resetError: jest.fn(),
+    reconnectWithNewContext: jest.fn(),
   }),
 }));
 
@@ -266,12 +285,28 @@ jest.mock('../../hooks/usePerpsEventTracking', () => ({
   })),
 }));
 
+jest.mock('../../hooks/usePerpsPrices', () => ({
+  usePerpsPrices: jest.fn(() => ({})),
+}));
+
+jest.mock('../../hooks/useIsPriceDeviatedAboveThreshold', () => ({
+  useIsPriceDeviatedAboveThreshold: jest.fn(() => ({
+    isDeviatedAboveThreshold: false,
+    isLoading: false,
+  })),
+}));
+
 jest.mock('../../hooks', () => ({
   usePerpsLiveAccount: () => mockUsePerpsAccount(),
   usePerpsConnection: () => ({
     isConnected: true,
     isConnecting: false,
+    isInitialized: true,
     error: null,
+    connect: jest.fn(),
+    disconnect: jest.fn(),
+    resetError: jest.fn(),
+    reconnectWithNewContext: jest.fn(),
   }),
   usePerpsOpenOrders: () => ({
     orders: [],

app/components/UI/Perps/Views/PerpsMarketDetailsView/PerpsMarketDetailsView.tsx

@@ -68,6 +68,7 @@ import {
   usePerpsDataMonitor,
   type DataMonitorParams,
 } from '../../hooks/usePerpsDataMonitor';
+import { useIsPriceDeviatedAboveThreshold } from '../../hooks/useIsPriceDeviatedAboveThreshold';
 import { usePerpsMeasurement } from '../../hooks/usePerpsMeasurement';
 import {
   usePerpsLiveAccount,
@@ -81,6 +82,7 @@ import PerpsPositionCard from '../../components/PerpsPositionCard';
 import PerpsMarketStatisticsCard from '../../components/PerpsMarketStatisticsCard';
 import type { PerpsTooltipContentKey } from '../../components/PerpsBottomSheetTooltip/PerpsBottomSheetTooltip.types';
 import PerpsOICapWarning from '../../components/PerpsOICapWarning';
+import PerpsPriceDeviationWarning from '../../components/PerpsPriceDeviationWarning';
 import PerpsNotificationTooltip from '../../components/PerpsNotificationTooltip';
 import PerpsNavigationCard, {
   type NavigationItem,
@@ -295,6 +297,12 @@ const PerpsMarketDetailsView: React.FC<PerpsMarketDetailsViewProps> = () => {
   // Check if market is at open interest cap
   const { isAtCap: isAtOICap } = usePerpsOICap(market?.symbol);
 
+  // Check if trading is halted due to price deviation
+  const {
+    isDeviatedAboveThreshold: isTradingHalted,
+    isLoading: isLoadingTradingHalted,
+  } = useIsPriceDeviatedAboveThreshold(market?.symbol);
+
   // Handle data-driven monitoring when coming from order success
   // Clear monitoringIntent after processing to allow fresh monitoring next time
   const handleDataDetected = useCallback(() => {
@@ -894,21 +902,19 @@ const PerpsMarketDetailsView: React.FC<PerpsMarketDetailsViewProps> = () => {
               )}
 
               {hasHistoricalData ? (
-                <>
-                  <TradingViewChart
-                    ref={chartRef}
-                    candleData={candleData}
-                    height={PERPS_CHART_CONFIG.LAYOUT.DETAIL_VIEW_HEIGHT}
-                    visibleCandleCount={visibleCandleCount}
-                    tpslLines={tpslLines}
-                    symbol={market?.symbol}
-                    showOverlay={false}
-                    coloredVolume
-                    onOhlcDataChange={setOhlcData}
-                    onNeedMoreHistory={fetchMoreHistory}
-                    testID={`${PerpsMarketDetailsViewSelectorsIDs.CONTAINER}-tradingview-chart`}
-                  />
-                </>
+                <TradingViewChart
+                  ref={chartRef}
+                  candleData={candleData}
+                  height={PERPS_CHART_CONFIG.LAYOUT.DETAIL_VIEW_HEIGHT}
+                  visibleCandleCount={visibleCandleCount}
+                  tpslLines={tpslLines}
+                  symbol={market?.symbol}
+                  showOverlay={false}
+                  coloredVolume
+                  onOhlcDataChange={setOhlcData}
+                  onNeedMoreHistory={fetchMoreHistory}
+                  testID={`${PerpsMarketDetailsViewSelectorsIDs.CONTAINER}-tradingview-chart`}
+                />
               ) : (
                 <Skeleton
                   height={PERPS_CHART_CONFIG.LAYOUT.DETAIL_VIEW_HEIGHT}
@@ -925,6 +931,13 @@ const PerpsMarketDetailsView: React.FC<PerpsMarketDetailsViewProps> = () => {
               onMorePress={handleMorePress}
               testID={`${PerpsMarketDetailsViewSelectorsIDs.CONTAINER}-candle-period-selector`}
             />
+
+            {/* Price Deviation Warning - Shows when price has deviated too much from spot price */}
+            {market?.symbol && isTradingHalted && !isLoadingTradingHalted && (
+              <PerpsPriceDeviationWarning
+                testID={`${PerpsMarketDetailsViewSelectorsIDs.CONTAINER}-price-deviation-warning`}
+              />
+            )}
           </View>
 
           {/* OI Cap Warning - Shows when market is at capacity */}
@@ -1035,7 +1048,7 @@ const PerpsMarketDetailsView: React.FC<PerpsMarketDetailsViewProps> = () => {
       </View>
 
       {/* Fixed Actions Footer */}
-      {(hasAddFundsButton || hasLongShortButtons) && (
+      {(hasAddFundsButton || hasLongShortButtons) && !isTradingHalted && (
         <View style={styles.actionsFooter}>
           {hasAddFundsButton && (
             <View style={styles.singleActionContainer}>

app/components/UI/Perps/components/PerpsPriceDeviationWarning/PerpsPriceDeviationWarning.styles.ts

@@ -0,0 +1,25 @@
+import { StyleSheet } from 'react-native';
+import type { Theme } from '../../../../../util/theme/models';
+
+const styleSheet = (params: { theme: Theme }) => {
+  const { colors } = params.theme;
+
+  return StyleSheet.create({
+    container: {
+      flexDirection: 'row',
+      alignItems: 'center',
+      gap: 8,
+      backgroundColor: colors.background.muted,
+      borderRadius: 12,
+      padding: 12,
+      marginTop: 8,
+    },
+    icon: {},
+    textContainer: {
+      flex: 1,
+      gap: 4,
+    },
+  });
+};
+
+export default styleSheet;

app/components/UI/Perps/components/PerpsPriceDeviationWarning/PerpsPriceDeviationWarning.tsx

@@ -0,0 +1,52 @@
+import React, { memo } from 'react';
+import { View } from 'react-native';
+import { useStyles } from '../../../../../component-library/hooks';
+import Text, {
+  TextVariant,
+  TextColor,
+} from '../../../../../component-library/components/Texts/Text';
+import Icon, {
+  IconName,
+  IconSize,
+  IconColor,
+} from '../../../../../component-library/components/Icons/Icon';
+import { strings } from '../../../../../../locales/i18n';
+import type { PerpsPriceDeviationWarningProps } from './PerpsPriceDeviationWarning.types';
+import styleSheet from './PerpsPriceDeviationWarning.styles';
+
+/**
+ * Component that displays a warning when the perps price has deviated too much from the spot price
+ * This prevents users from opening new positions when the price is significantly different from the spot price
+ *
+ * **Performance:**
+ * - Memoized to prevent unnecessary re-renders
+ *
+ * @example
+ * ```tsx
+ * <PerpsPriceDeviationWarning />
+ * ```
+ */
+const PerpsPriceDeviationWarning: React.FC<PerpsPriceDeviationWarningProps> =
+  memo(({ testID = 'perps-price-deviation-warning' }) => {
+    const { styles } = useStyles(styleSheet, {});
+
+    return (
+      <View style={styles.container} testID={testID}>
+        <Icon
+          name={IconName.Info}
+          size={IconSize.Md}
+          color={IconColor.Default}
+          style={styles.icon}
+        />
+        <View style={styles.textContainer}>
+          <Text variant={TextVariant.BodyMD} color={TextColor.Default}>
+            {strings('perps.price_deviation_warning.message')}
+          </Text>
+        </View>
+      </View>
+    );
+  });
+
+PerpsPriceDeviationWarning.displayName = 'PerpsPriceDeviationWarning';
+
+export default PerpsPriceDeviationWarning;

app/components/UI/Perps/components/PerpsPriceDeviationWarning/PerpsPriceDeviationWarning.types.ts

@@ -0,0 +1,4 @@
+export interface PerpsPriceDeviationWarningProps {
+  /** Optional test ID for testing */
+  testID?: string;
+}

app/components/UI/Perps/components/PerpsPriceDeviationWarning/index.ts

@@ -0,0 +1,2 @@
+export { default } from './PerpsPriceDeviationWarning';
+export type { PerpsPriceDeviationWarningProps } from './PerpsPriceDeviationWarning.types';

app/components/UI/Perps/constants/perpsConfig.ts

@@ -71,6 +71,9 @@ export const VALIDATION_THRESHOLDS = {
 
   // Limit price difference threshold (as decimal, 0.1 = 10%)
   LIMIT_PRICE_DIFFERENCE_WARNING: 0.1, // Warn if limit price differs by >10% from current price
+
+  // Price deviation threshold (as decimal, 0.1 = 10%)
+  PRICE_DEVIATION: 0.1, // Warn if perps price deviates by >10% from spot price
 } as const;
 
 /**

app/components/UI/Perps/hooks/index.ts

@@ -63,6 +63,7 @@ export { usePerpsOrderForm } from './usePerpsOrderForm';
 export { usePerpsOrderValidation } from './usePerpsOrderValidation';
 export { usePerpsClosePositionValidation } from './usePerpsClosePositionValidation';
 export { usePerpsOrderExecution } from './usePerpsOrderExecution';
+export { useIsPriceDeviatedAboveThreshold } from './useIsPriceDeviatedAboveThreshold';
 export { usePerpsFirstTimeUser } from './usePerpsFirstTimeUser';
 export { usePerpsTPSLForm } from './usePerpsTPSLForm';
 export { default as usePerpsToasts } from './usePerpsToasts';