feat(perps): add MM Pay token metrics and cancel trade event tracking (#27109)

## **Description**

This PR adds comprehensive event tracking for MM Pay token metrics in
the Perps trading flow. The changes include:

1. **MM Pay Token Metrics Enhancement**: When users trade using their
Perps balance (instead of paying with a token), the
`mm_pay_token_selected` property now includes the value `'Perps
Balance'` in trade transaction events. This provides complete visibility
into payment method selection, whether users pay with tokens or use
their Perps balance.

2. **Cancel Trade with Token Event Tracking**: Added event tracking for
the cancel trade with token flow:
- `PERPS_UI_INTERACTION` event with `interaction_type:
'cancel_trade_with_token'` when the user cancels a trade
- `PERPS_SCREEN_VIEWED` event with `screen_type:
'cancel_trade_with_token_toast'` when the "taking longer" toast is
displayed

These metrics enable better analytics on user behavior, payment method
preferences, and cancellation patterns in the Perps trading experience.

## **Changelog**

CHANGELOG entry: null

## **Related issues**

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

## **Manual testing steps**

```gherkin
Feature: MM Pay token metrics and cancel trade tracking

  Scenario: user trades with Perps balance
    Given user has a Perps account with available balance
    When user places a trade order using Perps balance (not paying with a token)
    Then the PERPS_TRADE_TRANSACTION event should include mm_pay_token_selected: "Perps Balance"

  Scenario: user cancels trade with token during deposit
    Given user has initiated a trade order with token payment
    And the deposit is taking longer than expected
    When the "taking longer" toast appears
    Then the PERPS_SCREEN_VIEWED event should be tracked with screen_type: "cancel_trade_with_token_toast"
    And when user taps the cancel button
    Then the PERPS_UI_INTERACTION event should be tracked with interaction_type: "cancel_trade_with_token"
```

## **Screenshots/Recordings**

### **Before**

N/A (analytics/metrics changes, no UI changes)

### **After**

N/A (analytics/metrics changes, no UI changes)

## **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]
> **Low Risk**
> Low risk: changes are limited to MetaMetrics analytics
properties/events and associated constants/tests, with no changes to
order execution behavior beyond emitting additional tracking calls.
> 
> **Overview**
> Adds new Perps MetaMetrics tracking for the deposit+order cancellation
flow: emits `PERPS_SCREEN_VIEWED` when the "deposit taking longer"
cancel toast is shown and `PERPS_UI_INTERACTION` when the user taps
cancel.
> 
> Extends `PERPS_TRADE_TRANSACTION` analytics so when `trackingData` is
present but `tradeWithToken` is false, `mm_pay_token_selected` is
explicitly reported as `"Perps Balance"` (applied in both
`usePerpsOrderExecution` and `TradingService`). Updates Perps event
constants, tests, and the Perps metametrics reference docs accordingly.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
9a82c62. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: michalconsensys

app/components/UI/Perps/hooks/usePerpsOrderDepositTracking.test.ts

@@ -8,6 +8,7 @@ import { usePerpsOrderDepositTracking } from './usePerpsOrderDepositTracking';
 
 const mockShowToast = jest.fn();
 const mockSubscribe = jest.fn();
+const mockTrack = jest.fn();
 
 jest.mock('./usePerpsToasts', () => ({
   __esModule: true,
@@ -48,6 +49,24 @@ jest.mock('@metamask/perps-controller', () => ({
   PERPS_CONSTANTS: {
     DepositTakingLongerToastDelayMs: 100,
   },
+  PERPS_EVENT_PROPERTY: {
+    SCREEN_TYPE: 'screen_type',
+    INTERACTION_TYPE: 'interaction_type',
+  },
+  PERPS_EVENT_VALUE: {
+    SCREEN_TYPE: {
+      CANCEL_TRADE_WITH_TOKEN_TOAST: 'cancel_trade_with_token_toast',
+    },
+    INTERACTION_TYPE: {
+      CANCEL_TRADE_WITH_TOKEN: 'cancel_trade_with_token',
+    },
+  },
+}));
+
+jest.mock('./usePerpsEventTracking', () => ({
+  usePerpsEventTracking: () => ({
+    track: mockTrack,
+  }),
 }));
 
 describe('usePerpsOrderDepositTracking', () => {
@@ -188,6 +207,13 @@ describe('usePerpsOrderDepositTracking', () => {
       closeButtonOptions?.closeButtonOptions?.onPress?.();
     });
 
+    expect(mockTrack).toHaveBeenCalledWith(
+      expect.objectContaining({ category: 'Perp UI Interaction' }),
+      expect.objectContaining({
+        interaction_type: 'cancel_trade_with_token',
+      }),
+    );
+
     const statusUpdatedHandler = handlers.statusUpdated;
     expect(statusUpdatedHandler).toBeDefined();
     act(() => {
@@ -260,6 +286,13 @@ describe('usePerpsOrderDepositTracking', () => {
       jest.advanceTimersByTime(100);
     });
 
+    expect(mockTrack).toHaveBeenCalledWith(
+      expect.objectContaining({ category: 'Perp Screen Viewed' }),
+      expect.objectContaining({
+        screen_type: 'cancel_trade_with_token_toast',
+      }),
+    );
+
     expect(mockShowToast).toHaveBeenCalled();
     expect(mockShowToast.mock.calls[0][0]).toMatchObject({
       closeButtonOptions: expect.any(Object),

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

@@ -6,8 +6,14 @@ import {
 import { useCallback } from 'react';
 import Engine from '../../../../core/Engine';
 import { strings } from '../../../../../locales/i18n';
-import { PERPS_CONSTANTS } from '@metamask/perps-controller';
+import {
+  PERPS_CONSTANTS,
+  PERPS_EVENT_PROPERTY,
+  PERPS_EVENT_VALUE,
+} from '@metamask/perps-controller';
 import usePerpsToasts from './usePerpsToasts';
+import { MetaMetricsEvents } from '../../../../core/Analytics';
+import { usePerpsEventTracking } from './usePerpsEventTracking';
 
 /**
  * Hook to track deposit status for Perps order view
@@ -23,6 +29,7 @@ import usePerpsToasts from './usePerpsToasts';
  */
 export const usePerpsOrderDepositTracking = () => {
   const { showToast, PerpsToastOptions } = usePerpsToasts();
+  const { track } = usePerpsEventTracking();
 
   const showProgressToast = useCallback(
     (transactionId: string) => {
@@ -57,11 +64,23 @@ export const usePerpsOrderDepositTracking = () => {
         PerpsToastOptions.accountManagement.deposit.takingLonger;
       const cancelTradeOnPress = () => {
         cancelTradeRequested = true;
+
+        track(MetaMetricsEvents.PERPS_UI_INTERACTION, {
+          [PERPS_EVENT_PROPERTY.INTERACTION_TYPE]:
+            PERPS_EVENT_VALUE.INTERACTION_TYPE.CANCEL_TRADE_WITH_TOKEN,
+        });
+
         // Replace current toast with "Trade canceled" (don't close first to avoid race)
         showToast(PerpsToastOptions.accountManagement.deposit.tradeCanceled);
       };
       const depositLongerTimeoutId = setTimeout(() => {
         const baseClose = takingLongerToastOptions.closeButtonOptions;
+
+        track(MetaMetricsEvents.PERPS_SCREEN_VIEWED, {
+          [PERPS_EVENT_PROPERTY.SCREEN_TYPE]:
+            PERPS_EVENT_VALUE.SCREEN_TYPE.CANCEL_TRADE_WITH_TOKEN_TOAST,
+        });
+
         showToast({
           ...takingLongerToastOptions,
           closeButtonOptions: baseClose
@@ -111,7 +130,12 @@ export const usePerpsOrderDepositTracking = () => {
         handleTransactionStatusUpdated,
       );
     },
-    [showToast, showProgressToast, PerpsToastOptions.accountManagement.deposit],
+    [
+      showToast,
+      showProgressToast,
+      PerpsToastOptions.accountManagement.deposit,
+      track,
+    ],
   );
 
   return {

app/components/UI/Perps/hooks/usePerpsOrderExecution.test.ts

@@ -208,6 +208,47 @@ describe('usePerpsOrderExecution', () => {
         }),
       );
     });
+
+    it('tracks success with mm_pay_token_selected Perps Balance when trackingData has tradeWithToken false', async () => {
+      const onSuccess = jest.fn();
+      const paramsWithPerpsBalance: OrderParams = {
+        ...mockOrderParams,
+        size: '0.2',
+        trackingData: {
+          totalFee: 0,
+          marketPrice: 50000,
+          tradeWithToken: false,
+        },
+      };
+
+      mockPlaceOrder.mockResolvedValue({
+        success: true,
+        orderId: 'order123',
+        filledSize: '0.1',
+      });
+      mockGetPositions.mockResolvedValue([mockPosition]);
+
+      const { result } = renderHook(() =>
+        usePerpsOrderExecution({ onSuccess, onError: jest.fn() }),
+      );
+
+      await act(async () => {
+        await result.current.placeOrder(paramsWithPerpsBalance);
+      });
+
+      await waitFor(() => {
+        expect(result.current.isPlacing).toBe(false);
+      });
+
+      expect(mockTrack).toHaveBeenCalledWith(
+        MetaMetricsEvents.PERPS_TRADE_TRANSACTION,
+        expect.objectContaining({
+          [PERPS_EVENT_PROPERTY.TRADE_WITH_TOKEN]: false,
+          [PERPS_EVENT_PROPERTY.MM_PAY_TOKEN_SELECTED]:
+            PERPS_EVENT_VALUE.MM_PAY_TOKEN.PERPS_BALANCE,
+        }),
+      );
+    });
   });
 
   describe('failed order placement', () => {
@@ -280,6 +321,43 @@ describe('usePerpsOrderExecution', () => {
       );
     });
 
+    it('tracks failed order with mm_pay_token_selected Perps Balance when trackingData has tradeWithToken false', async () => {
+      const onError = jest.fn();
+      const paramsWithPerpsBalance: OrderParams = {
+        ...mockOrderParams,
+        trackingData: {
+          totalFee: 0,
+          marketPrice: 50000,
+          tradeWithToken: false,
+        },
+      };
+
+      mockPlaceOrder.mockResolvedValue({
+        success: false,
+        error: 'Insufficient margin',
+      });
+
+      const { result } = renderHook(() => usePerpsOrderExecution({ onError }));
+
+      await act(async () => {
+        await result.current.placeOrder(paramsWithPerpsBalance);
+      });
+
+      await waitFor(() => {
+        expect(result.current.isPlacing).toBe(false);
+      });
+
+      expect(mockTrack).toHaveBeenCalledWith(
+        MetaMetricsEvents.PERPS_TRADE_TRANSACTION,
+        expect.objectContaining({
+          [PERPS_EVENT_PROPERTY.STATUS]: PERPS_EVENT_VALUE.STATUS.FAILED,
+          [PERPS_EVENT_PROPERTY.TRADE_WITH_TOKEN]: false,
+          [PERPS_EVENT_PROPERTY.MM_PAY_TOKEN_SELECTED]:
+            PERPS_EVENT_VALUE.MM_PAY_TOKEN.PERPS_BALANCE,
+        }),
+      );
+    });
+
     it('calls onError with unknown error when order returns success false without error', async () => {
       const onError = jest.fn();
 
@@ -355,6 +433,40 @@ describe('usePerpsOrderExecution', () => {
         }),
       );
     });
+
+    it('tracks exception with mm_pay_token_selected Perps Balance when placeOrder rejects and trackingData has tradeWithToken false', async () => {
+      const onError = jest.fn();
+      const paramsWithPerpsBalance: OrderParams = {
+        ...mockOrderParams,
+        trackingData: {
+          totalFee: 0,
+          marketPrice: 50000,
+          tradeWithToken: false,
+        },
+      };
+
+      mockPlaceOrder.mockRejectedValue(new Error('Network timeout'));
+
+      const { result } = renderHook(() => usePerpsOrderExecution({ onError }));
+
+      await act(async () => {
+        await result.current.placeOrder(paramsWithPerpsBalance);
+      });
+
+      await waitFor(() => {
+        expect(result.current.isPlacing).toBe(false);
+      });
+
+      expect(mockTrack).toHaveBeenCalledWith(
+        MetaMetricsEvents.PERPS_TRADE_TRANSACTION,
+        expect.objectContaining({
+          [PERPS_EVENT_PROPERTY.STATUS]: PERPS_EVENT_VALUE.STATUS.FAILED,
+          [PERPS_EVENT_PROPERTY.TRADE_WITH_TOKEN]: false,
+          [PERPS_EVENT_PROPERTY.MM_PAY_TOKEN_SELECTED]:
+            PERPS_EVENT_VALUE.MM_PAY_TOKEN.PERPS_BALANCE,
+        }),
+      );
+    });
   });
 
   describe('error state management', () => {

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

@@ -109,6 +109,9 @@ export function usePerpsOrderExecution(
                 partialProps[PERPS_EVENT_PROPERTY.MM_PAY_NETWORK_SELECTED] =
                   orderParams.trackingData.mmPayNetworkSelected;
               }
+            } else if (orderParams.trackingData !== undefined) {
+              partialProps[PERPS_EVENT_PROPERTY.MM_PAY_TOKEN_SELECTED] =
+                PERPS_EVENT_VALUE.MM_PAY_TOKEN.PERPS_BALANCE;
             }
             track(MetaMetricsEvents.PERPS_TRADE_TRANSACTION, partialProps);
           }
@@ -172,6 +175,9 @@ export function usePerpsOrderExecution(
               failedProps[PERPS_EVENT_PROPERTY.MM_PAY_NETWORK_SELECTED] =
                 orderParams.trackingData.mmPayNetworkSelected;
             }
+          } else if (orderParams.trackingData !== undefined) {
+            failedProps[PERPS_EVENT_PROPERTY.MM_PAY_TOKEN_SELECTED] =
+              PERPS_EVENT_VALUE.MM_PAY_TOKEN.PERPS_BALANCE;
           }
           track(MetaMetricsEvents.PERPS_TRADE_TRANSACTION, failedProps);
 
@@ -228,6 +234,9 @@ export function usePerpsOrderExecution(
             exceptionProps[PERPS_EVENT_PROPERTY.MM_PAY_NETWORK_SELECTED] =
               orderParams.trackingData.mmPayNetworkSelected;
           }
+        } else if (orderParams.trackingData !== undefined) {
+          exceptionProps[PERPS_EVENT_PROPERTY.MM_PAY_TOKEN_SELECTED] =
+            PERPS_EVENT_VALUE.MM_PAY_TOKEN.PERPS_BALANCE;
         }
         track(MetaMetricsEvents.PERPS_TRADE_TRANSACTION, exceptionProps);
 

app/controllers/perps/constants/eventNames.ts

@@ -305,6 +305,8 @@ export const PERPS_EVENT_VALUE = {
     // Pay-with interactions
     PAYMENT_TOKEN_SELECTOR: 'payment_token_selector',
     PAYMENT_METHOD_CHANGED: 'payment_method_changed',
+    // Deposit + order (pay-with token) cancel
+    CANCEL_TRADE_WITH_TOKEN: 'cancel_trade_with_token',
   },
   ACTION_TYPE: {
     START_TRADING: 'start_trading',
@@ -376,6 +378,8 @@ export const PERPS_EVENT_VALUE = {
     ADD_MARGIN: 'add_margin',
     REMOVE_MARGIN: 'remove_margin',
     GEO_BLOCK_NOTIF: 'geo_block_notif',
+    // Deposit + order (pay-with token) cancel toast
+    CANCEL_TRADE_WITH_TOKEN_TOAST: 'cancel_trade_with_token_toast',
   },
   SETTING_TYPE: {
     LEVERAGE: 'leverage',
@@ -413,6 +417,10 @@ export const PERPS_EVENT_VALUE = {
     FUNDING: 'funding',
     DEPOSITS: 'deposits',
   },
+  /** Value for mm_pay_token_selected when user pays with Perps balance (not a token) */
+  MM_PAY_TOKEN: {
+    PERPS_BALANCE: 'Perps Balance',
+  },
   // A/B testing values
   AB_TEST: {
     // Test IDs

app/controllers/perps/services/TradingService.test.ts

@@ -4,6 +4,7 @@ import {
   createMockPerpsControllerState,
   createMockInfrastructure,
 } from '../../../components/UI/Perps/__mocks__/serviceMocks';
+import { PERPS_EVENT_VALUE } from '../constants/eventNames';
 import { PerpsAnalyticsEvent } from '../types';
 import type {
   PerpsProvider,
@@ -322,6 +323,48 @@ describe('TradingService', () => {
       );
     });
 
+    it('includes mm_pay_token_selected "Perps Balance" when user uses perps balance', async () => {
+      const orderParams: OrderParams = {
+        symbol: 'BTC',
+        isBuy: true,
+        size: '0.1',
+        orderType: 'market',
+        leverage: 10,
+        trackingData: {
+          totalFee: 0,
+          marketPrice: 50000,
+          tradeWithToken: false,
+        },
+      };
+      const mockOrderResult: OrderResult = {
+        success: true,
+        orderId: 'order-123',
+        filledSize: '0.1',
+        averagePrice: '50000',
+      };
+
+      mockProvider.placeOrder.mockResolvedValue(mockOrderResult);
+      mockRewardsIntegrationService.calculateUserFeeDiscount.mockResolvedValue(
+        undefined,
+      );
+
+      await tradingService.placeOrder({
+        provider: mockProvider,
+        params: orderParams,
+        context: mockContext,
+        reportOrderToDataLake: mockReportOrderToDataLake,
+      });
+
+      expect(mockDeps.metrics.trackPerpsEvent).toHaveBeenCalledWith(
+        PerpsAnalyticsEvent.TradeTransaction,
+        expect.objectContaining({
+          status: 'executed',
+          trade_with_token: false,
+          mm_pay_token_selected: PERPS_EVENT_VALUE.MM_PAY_TOKEN.PERPS_BALANCE,
+        }),
+      );
+    });
+
     it('tracks analytics event when order fails', async () => {
       const orderParams: OrderParams = {
         symbol: 'BTC',

app/controllers/perps/services/TradingService.ts

@@ -164,7 +164,7 @@ export class TradingService {
     if (params.trackingData?.tradeAction) {
       properties[PERPS_EVENT_PROPERTY.ACTION] = params.trackingData.tradeAction;
     }
-    // Pay with any token: trade_with_token (boolean); when true, include mm_pay_token_selected and mm_pay_network_selected
+    // Pay with any token: trade_with_token (boolean); when true, include mm_pay_token_selected and mm_pay_network_selected; when false (Perps balance), include mm_pay_token_selected: "Perps Balance"
     properties[PERPS_EVENT_PROPERTY.TRADE_WITH_TOKEN] =
       params.trackingData?.tradeWithToken === true;
     if (params.trackingData?.tradeWithToken === true) {
@@ -176,6 +176,9 @@ export class TradingService {
         properties[PERPS_EVENT_PROPERTY.MM_PAY_NETWORK_SELECTED] =
           params.trackingData.mmPayNetworkSelected;
       }
+    } else if (params.trackingData !== undefined) {
+      properties[PERPS_EVENT_PROPERTY.MM_PAY_TOKEN_SELECTED] =
+        PERPS_EVENT_VALUE.MM_PAY_TOKEN.PERPS_BALANCE;
     }
 
     // Add success-specific properties

docs/perps/perps-metametrics-reference.md

@@ -162,7 +162,7 @@ this.#getMetrics().trackPerpsEvent(PerpsAnalyticsEvent.TradeTransaction, {
 - `input_method` (optional): How value was entered: `'slider' | 'keyboard' | 'preset' | 'manual' | 'percentage_button'`
 - `limit_price` (optional): Limit order price (for limit orders) (number)
 - `trade_with_token` (optional): Whether the user paid with a token other than Perps balance (boolean)
-- `mm_pay_token_selected` (optional): Token symbol selected for pay-with (e.g. `'USDC'`), included when `trade_with_token` is true
+- `mm_pay_token_selected` (optional): Token symbol selected for pay-with (e.g. `'USDC'`); when `trade_with_token` is true, the selected token symbol; when user uses Perps balance, `'Perps Balance'`
 - `mm_pay_network_selected` (optional): Network/chain for pay-with (e.g. `'ethereum'`), included when `trade_with_token` is true
 - `error_message` (optional): Error description when status is 'failed'