fix(ramps): Single-owner React Query fetching for providers, tokens, and payment methods (#28224)

## **Description**

Payment methods, providers, and tokens were being fetched redundantly
from two independent paths (controller `fireAndForget` + React Query),
causing 2–3 duplicate API calls per user action with a ~10s spinner.

This PR makes the mobile client the single fetch owner for all ramp
data. React Query handles providers and payment methods with proper
caching and invalidation. Tokens are fetched directly from
RampsBootstrap. Screens that don't need payment methods no longer
trigger fetches.

Changes:

1. **`RampsBootstrap.tsx`** — Now fetches all three data sources at app
root: `useRampsProviders` (React Query), `useRampsPaymentMethods` (React
Query), and `getTokens` (direct controller call on region change). This
follows the agreed flow: app loads → fetch providers and tokens →
provider selected → fetch payment methods.

2. **`useRampsProviders.ts`** — Reads provider list from React Query
cache (not controller state). Invalidates all ramp queries on region
change to force fresh fetches. Passes full `Provider` object to
`setSelectedProvider` for auto-selection (avoids crash when controller
state is empty).

3. **`useRampsPaymentMethods.ts`** — Query key reduced to `[regionCode,
providerId]` only. Token/fiat are passed to the API call but not the
key, so token changes don't trigger refetches. Passes full
`PaymentMethod` object to controller (avoids crash when controller state
is empty).

4. **`paymentMethods.ts` (query config)** — `staleTime: 5min`. Query key
only includes `regionCode` and `providerId`.

5. **`providers.ts` (query config)** — `staleTime: 15min`. Removed
`forceRefresh: true` from queryFn (controller's own cache handles it).

6. **`SettingsModal.tsx`** — Uses `useRampsProviders` instead of
`useRampsController` (no more payment methods fetch on settings screen).

7. **`TokenNotAvailableModal.tsx`** — Uses `useRampsProviders` +
`useRampsTokens` instead of `useRampsController`.

8. **`RegionSelector.tsx`** — Uses `useRampsUserRegion` +
`useRampsCountries` instead of `useRampsController`.

9. **`PaymentSelectionModal.tsx`** — Filters out payment methods with no
available quote once quotes load, preventing dead-end options (e.g.
Apple Pay shown but no provider returns a quote for it).

10. **Tests updated** — Removed `tokenSupportedByProvider` test, updated
query key and staleTime assertions.

## **Changelog**

CHANGELOG entry: Fixed duplicate payment method, provider, and token API
calls during buy flow; React Query is now the single fetch owner for
ramp data

## **Related issues**

Fixes:
[TRAM-3398](https://consensyssoftware.atlassian.net/browse/TRAM-3398)

Depends on core PR:
[MetaMask/core#8354](MetaMask/core#8354)
(removes `fireAndForget` calls from controller)

## **Manual testing steps**

```gherkin
Feature: Single-owner fetching for ramp data

  Scenario: App load fetches providers, tokens, and payment methods
    Given user opens the app (password screen)
    When the app loads
    Then getProviders, getTokens, and getPaymentMethods each fire once
    And providers, tokens, and payment methods are populated in state

  Scenario: Token selection does not trigger payment methods fetch
    Given user is on the token selection screen
    When user selects a token (e.g. Ethereum)
    Then getPaymentMethods is NOT called
    And the BuildQuote screen loads with cached payment methods

  Scenario: Provider change triggers a single payment methods fetch
    Given user is on the BuildQuote screen with a provider selected
    When user changes the provider (e.g. Transak -> Coinbase)
    Then getPaymentMethods fires exactly once for the new provider
    And the payment method pill auto-switches to Debit or Credit

  Scenario: Region switch refreshes all data
    Given user is on the settings screen
    When user changes region (e.g. France -> Finland -> France)
    Then getProviders and getPaymentMethods fire for each new region
    And switching back to a previous region also triggers fresh fetches

  Scenario: Settings screen does not trigger payment methods fetch
    Given user navigates to the Buy & Sell settings screen
    Then getPaymentMethods is NOT called
    And no unnecessary API calls appear in the debug dashboard

  Scenario: Payment selection modal hides dead-end options
    Given user taps the payment method pill
    When quotes load for all payment methods
    Then payment methods with no available quote are filtered out
```

## **Screenshots/Recordings**

### **Before**

<!-- 2-3 getPaymentMethods calls per token selection visible in debug
dashboard -->

### **After**

<!-- Single getPaymentMethods call only on provider change; no calls on
settings/navigation -->

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

## **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]
> **Medium Risk**
> Changes ramp buy-flow data fetching/caching and controller interaction
patterns (query keys, invalidation, and provider/payment-method
selection), which could affect availability/performance across regions
and providers. UI impact is limited but touches core buy-flow bootstrap
and selection logic.
> 
> **Overview**
> **Makes the mobile client the single fetch owner for ramps buy data.**
`RampsBootstrap` now preloads providers (with side effects), payment
methods, and triggers token fetching on region availability so
downstream screens don’t cause redundant requests.
> 
> **Reworks React Query behavior for providers and payment methods.**
`useRampsProviders` reads the provider list from the React Query cache,
adds optional `enableSideEffects` to avoid duplicate
invalidation/auto-selection, and invalidates all `ramps` queries on
region changes. `useRampsPaymentMethods` simplifies the query to be
provider-scoped (query key is `regionCode` + `providerId`, 5-min
`staleTime`) and updates controller setters to accept full objects/null.
> 
> **UI behavior tweaks and hook decoupling.** `PaymentSelectionModal`
now hides payment methods that have no non-custom-action quote once
quotes load, showing the “no payment methods available” state instead.
Several screens (`SettingsModal`, `TokenNotAvailableModal`,
`RegionSelector`) switch from `useRampsController` to narrower hooks
(`useRampsProviders`, `useRampsTokens`, `useRampsUserRegion`,
`useRampsCountries`) to prevent unrelated fetches. Dependency bump
updates `@metamask/ramps-controller` to `^13.0.0`.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
75f85ca. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: imyugioh

app/components/UI/Ramp/RampsBootstrap.test.tsx

@@ -1,9 +1,13 @@
 import React from 'react';
 import { render } from '@testing-library/react-native';
+import { Provider } from 'react-redux';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { configureStore } from '@reduxjs/toolkit';
 import RampsBootstrap from './RampsBootstrap';
 
 const mockUseRampsSmartRouting = jest.fn();
 const mockUseRampsProviders = jest.fn();
+const mockUseRampsPaymentMethods = jest.fn();
 
 jest.mock('./hooks/useRampsSmartRouting', () => ({
   __esModule: true,
@@ -15,26 +19,72 @@ jest.mock('./hooks/useRampsProviders', () => ({
   default: (...args: unknown[]) => mockUseRampsProviders(...args),
 }));
 
+jest.mock('./hooks/useRampsPaymentMethods', () => ({
+  __esModule: true,
+  default: (...args: unknown[]) => mockUseRampsPaymentMethods(...args),
+}));
+
+jest.mock('../../../core/Engine', () => ({
+  context: {
+    RampsController: {
+      getTokens: jest.fn().mockResolvedValue({ topTokens: [], allTokens: [] }),
+    },
+  },
+}));
+
+const createMockStore = () =>
+  configureStore({
+    reducer: {
+      engine: () => ({
+        backgroundState: {
+          RampsController: {
+            userRegion: {
+              regionCode: 'us',
+              country: { currency: 'USD' },
+            },
+          },
+        },
+      }),
+    },
+  });
+
+const queryClient = new QueryClient({
+  defaultOptions: { queries: { retry: false } },
+});
+
+const renderBootstrap = () => {
+  const store = createMockStore();
+  return render(
+    <Provider store={store}>
+      <QueryClientProvider client={queryClient}>
+        <RampsBootstrap />
+      </QueryClientProvider>
+    </Provider>,
+  );
+};
+
 describe('RampsBootstrap', () => {
   afterEach(() => {
     jest.clearAllMocks();
   });
 
   it('calls useRampsSmartRouting on mount', () => {
-    render(<RampsBootstrap />);
-
+    renderBootstrap();
     expect(mockUseRampsSmartRouting).toHaveBeenCalledTimes(1);
   });
 
   it('calls useRampsProviders on mount', () => {
-    render(<RampsBootstrap />);
-
+    renderBootstrap();
     expect(mockUseRampsProviders).toHaveBeenCalledTimes(1);
   });
 
-  it('renders null', () => {
-    const { toJSON } = render(<RampsBootstrap />);
+  it('calls useRampsPaymentMethods on mount', () => {
+    renderBootstrap();
+    expect(mockUseRampsPaymentMethods).toHaveBeenCalledTimes(1);
+  });
 
+  it('renders null', () => {
+    const { toJSON } = renderBootstrap();
     expect(toJSON()).toBeNull();
   });
 });

app/components/UI/Ramp/RampsBootstrap.tsx

@@ -1,5 +1,10 @@
+import { useEffect } from 'react';
+import { useSelector } from 'react-redux';
 import useRampsSmartRouting from './hooks/useRampsSmartRouting';
 import useRampsProviders from './hooks/useRampsProviders';
+import useRampsPaymentMethods from './hooks/useRampsPaymentMethods';
+import { selectUserRegion } from '../../../selectors/rampsController';
+import Engine from '../../../core/Engine';
 
 /**
  * Ramps app bootstrap: runs smart routing, controller hydration, and provider
@@ -11,10 +16,25 @@ import useRampsProviders from './hooks/useRampsProviders';
  *
  * V2: RampsController is initialized by Engine (rampsControllerInit). Provider
  * auto-selection runs when providers load. Mount at app root.
+ *
+ * Tokens, providers, and payment methods are all fetched here so they are
+ * ready when the user enters the buy flow.
  */
 function RampsBootstrap(): null {
   useRampsSmartRouting();
-  useRampsProviders();
+  useRampsProviders({ enableSideEffects: true });
+  useRampsPaymentMethods();
+
+  // Fetch tokens when region is available. Tokens don't use React Query
+  // (they're needed for controller-side validation in setSelectedToken),
+  // so we trigger the fetch directly.
+  const userRegion = useSelector(selectUserRegion);
+  useEffect(() => {
+    if (userRegion?.regionCode) {
+      Engine.context.RampsController.getTokens(userRegion.regionCode, 'buy');
+    }
+  }, [userRegion?.regionCode]);
+
   return null;
 }
 

app/components/UI/Ramp/Views/Modals/PaymentSelectionModal/PaymentSelectionModal.test.tsx

@@ -362,7 +362,7 @@ describe('PaymentSelectionModal', () => {
     });
   });
 
-  it('shows payment method without quote when only custom-action quote matches', () => {
+  it('filters out payment method when only custom-action quote matches', () => {
     const customActionQuote = {
       provider: '/providers/transak',
       quote: {
@@ -381,7 +381,11 @@ describe('PaymentSelectionModal', () => {
       loading: false,
     }));
 
-    const { getAllByText } = renderWithProvider(PaymentSelectionModal);
-    expect(getAllByText('Debit or Credit').length).toBeGreaterThan(0);
+    const { queryAllByText, getByText } = renderWithProvider(
+      PaymentSelectionModal,
+    );
+    // Payment methods with only custom-action quotes are filtered out
+    expect(queryAllByText('Debit or Credit').length).toBe(0);
+    expect(getByText('fiat_on_ramp.no_payment_methods_available')).toBeTruthy();
   });
 });

app/components/UI/Ramp/Views/Modals/PaymentSelectionModal/PaymentSelectionModal.tsx

@@ -219,7 +219,18 @@ function PaymentSelectionModal() {
         </ScrollView>
       );
     }
-    if (paymentMethods.length === 0) {
+    // Filter out payment methods that have no available quote once quotes
+    // have loaded. This avoids showing dead-end options to the user.
+    const visiblePaymentMethods =
+      !quotesLoading && quotes
+        ? paymentMethods.filter((pm) =>
+            quotes.success?.some(
+              (q) => q.quote?.paymentMethod === pm.id && !isCustomAction(q),
+            ),
+          )
+        : paymentMethods;
+
+    if (visiblePaymentMethods.length === 0) {
       return (
         <ScrollView
           style={styles.list}
@@ -235,7 +246,7 @@ function PaymentSelectionModal() {
     return (
       <FlatList
         style={styles.list}
-        data={paymentMethods}
+        data={visiblePaymentMethods}
         renderItem={renderPaymentMethod}
         keyExtractor={(item) => item.id}
         keyboardDismissMode="none"

app/components/UI/Ramp/Views/Modals/SettingsModal/SettingsModal.test.tsx

@@ -121,8 +121,8 @@ const mockInAppBrowser = InAppBrowser as jest.Mocked<typeof InAppBrowser>;
 let mockSelectedProvider: Provider | null = createMockProvider();
 const mockSetSelectedProvider = jest.fn();
 
-jest.mock('../../../hooks/useRampsController', () => ({
-  useRampsController: () => ({
+jest.mock('../../../hooks/useRampsProviders', () => ({
+  useRampsProviders: () => ({
     selectedProvider: mockSelectedProvider,
     setSelectedProvider: mockSetSelectedProvider,
   }),

app/components/UI/Ramp/Views/Modals/SettingsModal/SettingsModal.tsx

@@ -25,7 +25,7 @@ import {
 import Logger from '../../../../../../util/Logger';
 import HeaderCompactStandard from '../../../../../../component-library/components-temp/HeaderCompactStandard';
 import MenuItem from '../../../components/MenuItem';
-import { useRampsController } from '../../../hooks/useRampsController';
+import { useRampsProviders } from '../../../hooks/useRampsProviders';
 import { useAnalytics } from '../../../../../hooks/useAnalytics/useAnalytics';
 import { MetaMetricsEvents } from '../../../../../../core/Analytics';
 import {
@@ -53,7 +53,7 @@ function SettingsModal() {
   const sheetRef = useRef<BottomSheetRef>(null);
   const navigation = useNavigation();
   const { toastRef } = useContext(ToastContext);
-  const { selectedProvider, setSelectedProvider } = useRampsController();
+  const { selectedProvider, setSelectedProvider } = useRampsProviders();
 
   const [isAuthenticatedWithProvider, setIsAuthenticatedWithProvider] =
     useState<boolean>(false);

app/components/UI/Ramp/Views/Modals/TokenNotAvailableModal/TokenNotAvailableModal.test.tsx

@@ -58,9 +58,14 @@ let mockSelectedToken: unknown = {
   symbol: 'USDC',
 };
 
-jest.mock('../../../hooks/useRampsController', () => ({
-  useRampsController: () => ({
+jest.mock('../../../hooks/useRampsProviders', () => ({
+  useRampsProviders: () => ({
     selectedProvider: mockSelectedProvider,
+  }),
+}));
+
+jest.mock('../../../hooks/useRampsTokens', () => ({
+  useRampsTokens: () => ({
     selectedToken: mockSelectedToken,
   }),
 }));

app/components/UI/Ramp/Views/Modals/TokenNotAvailableModal/TokenNotAvailableModal.tsx

@@ -21,7 +21,8 @@ import {
 import Routes from '../../../../../../constants/navigation/Routes';
 import styleSheet from './TokenNotAvailableModal.styles';
 import { useStyles } from '../../../../../hooks/useStyles';
-import { useRampsController } from '../../../hooks/useRampsController';
+import { useRampsProviders } from '../../../hooks/useRampsProviders';
+import { useRampsTokens } from '../../../hooks/useRampsTokens';
 import { createProviderSelectionModalNavigationDetails } from '../ProviderSelectionModal';
 import { useAnalytics } from '../../../../../hooks/useAnalytics/useAnalytics';
 import { MetaMetricsEvents } from '../../../../../../core/Analytics';
@@ -48,7 +49,8 @@ function TokenNotAvailableModal() {
   const sheetRef = useRef<BottomSheetRef>(null);
   const { styles } = useStyles(styleSheet, {});
 
-  const { selectedProvider, selectedToken } = useRampsController();
+  const { selectedProvider } = useRampsProviders();
+  const { selectedToken } = useRampsTokens();
 
   const tokenName = selectedToken?.name ?? '';
   const providerName = selectedProvider?.name ?? '';