feat: price alert percentage feature

[bergarces]

Description

Adds percent-change price alerts so users can get notified when a token moves up or down by a chosen percentage over a rolling 1h or 24h window, alongside existing absolute price-target alerts.

The create screen is refactored into a thin shell with an alert-type toggle (Price target / Price change) and dedicated forms (AbsolutePriceAlertForm, PercentChangeAlertForm). Shared save behavior lives in useAlertSaveFlow. Manage alerts lists both types, and the API layer adds /v1/alerts/percent-change CRUD with alert-type routing and backward-compatible normalization (alerts missing type default to absolute_price).

Changelog

CHANGELOG entry: Added percent-change price alerts so users can be notified when a token moves up or down by a set percentage over 1 hour or 24 hours

Related issues

Fixes: https://consensyssoftware.atlassian.net/browse/ASSETS-3593

Manual testing steps

Feature: Percent-change price alerts

  Scenario: user creates a percent-change alert
    Given the user is signed in and price alerts are available for a token
    And the user opens Create price alert for that token
    When the user selects "Price change"
    And chooses direction (up or down), period (1hr or 24hr), and a percent threshold
    And optionally enables Recurring
    And taps Set price alert
    Then the alert is saved successfully
    And the alert appears in Manage price alerts with the correct percent summary

  Scenario: user creates an absolute price-target alert
    Given the user is on Create price alert for a token
    When the user leaves "Price target" selected
    And enters a target price (or uses a quick % pill)
    And taps Set price alert
    Then the absolute price alert is saved successfully
    And existing absolute-target behavior still works (including duplicate threshold messaging)

  Scenario: user cannot switch alert type while editing
    Given the user opens an existing alert in edit mode
    When the create/edit screen is shown
    Then the alert type toggle is locked to the alert's existing type
    And the user can update that alert's fields and save

  Scenario: user manages mixed alert types
    Given the user has both price-target and percent-change alerts for a token
    When the user opens Manage price alerts
    Then both alert types are listed with the correct titles and subtitles
    And the user can toggle, edit, and delete each type

Screenshots/Recordings

Before

N/A — percent-change alerts were not available (Price change was under development / placeholder). Absolute price-target create/manage unchanged in concept; attach prior screenshots if useful for comparison.

After

Simulator.Screen.Recording.-.iPhone.16.Pro.-.2026-07-15.at.15.57.34.mov

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
  • Ideally on a mid-range device; emulator is acceptable
• I've tested with a power user scenario
  • Use these power-user SRPs to import wallets with many accounts and tokens
• I've instrumented key operations with Sentry traces for production performance metrics
  • See trace() for usage and addToken for an example

For performance guidelines and tooling, see the Performance Guide.

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
Touches authenticated price-alert API calls, navigation params, and a large refactor of create/save paths; regression risk is mitigated by tests but absolute-target behavior should be smoke-tested end-to-end.

Overview
Introduces percent-change price alerts (up/down % over 1h or 24h) next to existing absolute price target alerts.

Create flow: CreatePriceAlertView is slimmed to header, Price target / Price change toggle, and routing into AbsolutePriceAlertForm or PercentChangeAlertForm. Absolute-target UI logic moves out of the monolithic view; shared keypad, recurring toggle, and save button live in AlertFormShell / useAlertSaveFlow. Edit mode locks alert type; percent edits lock period and direction.

API & types: Alerts are modeled as absolute_price | percent_change with normalizeAlerts (missing type → absolute). New /v1/alerts/percent-change CRUD, useSubmitPercentAlert, and updateAlertByType / deleteAlertByType route by type.

Manage: Lists both kinds with percent-specific copy; navigation passes existingAbsoluteAlerts / existingPercentAlerts instead of flat existingThresholds. Duplicate checks use full alert objects (percent: threshold + period + direction).

Tests & copy: Broad unit/component-view coverage; new i18n strings replace the old “under development” placeholder.

^{Reviewed by Cursor Bugbot for commit f134fe5. 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.

[metamask-ci]

PR template — items to address before "Ready for review"

Warnings — informational, address before merging:

• Pre-merge author checklist has unchecked items (e.g. "I've tested on Android"). Every box must be consciously checked — see docs/readme/ready-for-review.md.

See docs/readme/ready-for-review.md for the full Definition of Ready for Review.

[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 9f071af. Configure here.}

[bergarces]

This is a common component to handle the input for both threshold and percent (the percent has a prefix and suffix).

[bergarces]

Dropped most of the code here and created new components for each alert type.

[github-actions]

🔍 Smart E2E Test Selection

• Selected E2E tags: None (no tests recommended)
• Selected Performance tags: None (no tests recommended)
• Risk Level: low
• AI Confidence: 92%

click to see 🤖 AI reasoning details

E2E Test Selection:
The PR changes are entirely contained within the PriceAlerts feature area:

1. app/components/UI/Assets/PriceAlerts/** - New/updated PriceAlerts UI components (forms, views, hooks, utilities, constants). This is a new feature under development with no existing E2E smoke tests covering it.

2. tests/component-view/api-mocking/priceAlerts.ts - This is a component-view test mock/utility file (not an E2E smoke spec). The tests/component-view/ directory is a Jest-based component testing framework used exclusively by .view.test.tsx files, not by Detox/WDIO E2E smoke tests.

3. locales/languages/en.json - Minor string additions for the price alerts feature (new keys like moves_up, moves_down, period_1h, etc.) and one rename (price_reaches → price_target). No strings used by other features are modified.

No E2E smoke tests exist for PriceAlerts - grep searches confirmed zero matches for PriceAlert/price-alert patterns in tests/smoke/ or tests/ directories.

No shared components are affected - No changes to TabBar, navigation, modals, confirmations, or any other shared infrastructure that could break existing tests.

No Engine/Controller changes - The API layer uses Engine.context.AuthenticationController.getBearerToken() but doesn't modify any controller.

The changes are self-contained new feature development with unit/component tests only. No E2E smoke tags are warranted.

Performance Test Selection:
The PriceAlerts feature is a new UI feature for setting price alerts on tokens. It does not affect any performance-sensitive flows measured by the available performance test tags (account list rendering, onboarding, login, swaps, app launch, asset loading, predict markets, or perpetuals trading). No performance test tags are warranted.

View GitHub Actions results

[sonarqubecloud]

Quality Gate passed

Issues
5 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud