feat: fetch balances accout api array (#6487)

## Explanation

Previously, the TokenBalancesController used a simple boolean
useAccountAPI configuration that applied an all-or-nothing approach -
either all chains would use the Accounts API for balance fetching, or
none would. This lacked the flexibility needed for real-world scenarios
where different chains have different levels of Accounts API support.

<!--
Thanks for your contribution! Take a moment to answer these questions so
that reviewers have the information they need to properly understand
your changes:

* What is the current state of things and why does it need to change?
* What is the solution your changes offer and how does it work?
* Are there any changes whose purpose might not obvious to those
unfamiliar with the domain?
* If your primary goal was to update one package but you found you had
to update another one along the way, why did you do so?
* If you had to upgrade a dependency, why did you do so?
-->

## References

<!--
Are there any issues that this pull request is tied to?
Are there other links that reviewers should consult to understand these
changes better?
Are there client or consumer pull requests to adopt any breaking
changes?

For example:

* Fixes #12345
* Related to #67890
-->

## Checklist

- [ ] I've updated the test suite for new or updated code as appropriate
- [ ] I've updated documentation (JSDoc, Markdown, etc.) for new or
updated code as appropriate
- [ ] I've communicated my changes to consumers by [updating changelogs
for packages I've
changed](https://github.com/MetaMask/core/tree/main/docs/contributing.md#updating-changelogs),
highlighting breaking changes as necessary
- [ ] I've prepared draft pull requests for clients and consumer
packages to resolve any breaking changes

Author: salimtb

packages/assets-controllers/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **BREAKING:** Replace `useAccountAPI` boolean with `accountsApiChainIds` array in `TokenBalancesController` for granular per-chain Accounts API configuration ([#6487](https://github.com/MetaMask/core/pull/6487))
+
 ## [74.3.3]
 
 ### Changed

packages/assets-controllers/src/AccountTrackerController.test.ts

@@ -16,6 +16,7 @@ import type {
   AllowedEvents,
 } from './AccountTrackerController';
 import { AccountTrackerController } from './AccountTrackerController';
+import { AccountsApiBalanceFetcher } from './multi-chain-accounts-service/api-balance-fetcher';
 import { getTokenBalancesForMultipleAddresses } from './multicall';
 import { FakeProvider } from '../../../tests/fake-provider';
 import { advanceTime } from '../../../tests/helpers';
@@ -867,7 +868,7 @@ describe('AccountTrackerController', () => {
                   },
                 },
               },
-              useAccountsAPI: false, // Disable API balance fetchers to force RPC usage
+              accountsApiChainIds: [], // Disable API balance fetchers to force RPC usage
             },
             isMultiAccountBalancesEnabled: true,
             selectedAccount: ACCOUNT_1,
@@ -910,7 +911,7 @@ describe('AccountTrackerController', () => {
         await withController(
           {
             options: {
-              useAccountsAPI: true,
+              accountsApiChainIds: ['0x1'],
               // allowExternalServices not provided - should default to () => true (line 390)
             },
             isMultiAccountBalancesEnabled: true,
@@ -924,7 +925,7 @@ describe('AccountTrackerController', () => {
             // Refresh balances for mainnet (supported by API)
             await refresh(clock, ['mainnet']);
 
-            // Since allowExternalServices defaults to () => true (line 390), and useAccountsAPI is true,
+            // Since allowExternalServices defaults to () => true (line 390), and accountsApiChainIds includes '0x1',
             // the API fetcher should be used, which means fetch should be called
             expect(fetchSpy).toHaveBeenCalled();
 
@@ -943,7 +944,7 @@ describe('AccountTrackerController', () => {
         await withController(
           {
             options: {
-              useAccountsAPI: true,
+              accountsApiChainIds: ['0x1'],
               allowExternalServices: () => true, // Explicitly set to true
             },
             isMultiAccountBalancesEnabled: true,
@@ -957,7 +958,7 @@ describe('AccountTrackerController', () => {
             // Refresh balances for mainnet (supported by API)
             await refresh(clock, ['mainnet']);
 
-            // Since allowExternalServices is true and useAccountsAPI is true,
+            // Since allowExternalServices is true and accountsApiChainIds includes '0x1',
             // the API fetcher should be used, which means fetch should be called
             expect(fetchSpy).toHaveBeenCalled();
 
@@ -976,7 +977,7 @@ describe('AccountTrackerController', () => {
         await withController(
           {
             options: {
-              useAccountsAPI: true,
+              accountsApiChainIds: ['0x1'],
               allowExternalServices: () => false, // Explicitly set to false
             },
             isMultiAccountBalancesEnabled: true,
@@ -1001,6 +1002,79 @@ describe('AccountTrackerController', () => {
         );
       });
     });
+
+    it('should continue to next fetcher when current fetcher supports no chains', async () => {
+      // Spy on the AccountsApiBalanceFetcher's supports method to return false
+      const supportsSpy = jest
+        .spyOn(AccountsApiBalanceFetcher.prototype, 'supports')
+        .mockReturnValue(false);
+
+      await withController(
+        {
+          options: {
+            accountsApiChainIds: ['0x1'], // Configure to use AccountsAPI for mainnet
+            allowExternalServices: () => true,
+          },
+          isMultiAccountBalancesEnabled: true,
+          selectedAccount: ACCOUNT_1,
+          listAccounts: [ACCOUNT_1],
+        },
+        async ({ controller, refresh }) => {
+          // Mock RPC query to return balance (this should be used since AccountsAPI supports nothing)
+          mockedQuery.mockResolvedValue('0x123456');
+
+          // Refresh balances for mainnet
+          await refresh(clock, ['mainnet']);
+
+          // Verify that the supports method was called (meaning we reached the continue logic)
+          expect(supportsSpy).toHaveBeenCalledWith('0x1');
+
+          // Verify that state was still updated via RPC fetcher fallback
+          expect(
+            controller.state.accountsByChainId['0x1'][CHECKSUM_ADDRESS_1]
+              .balance,
+          ).toBeDefined();
+
+          supportsSpy.mockRestore();
+        },
+      );
+    });
+
+    it('should log warning when balance fetcher throws an error', async () => {
+      const consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation();
+
+      // Mock AccountsApiBalanceFetcher to throw an error
+      const fetchSpy = jest
+        .spyOn(AccountsApiBalanceFetcher.prototype, 'fetch')
+        .mockRejectedValue(new Error('API request failed'));
+
+      await withController(
+        {
+          options: {
+            accountsApiChainIds: ['0x1'], // Configure to use AccountsAPI for mainnet
+            allowExternalServices: () => true,
+          },
+          isMultiAccountBalancesEnabled: true,
+          selectedAccount: ACCOUNT_1,
+          listAccounts: [ACCOUNT_1],
+        },
+        async ({ refresh }) => {
+          // Mock RPC query to return balance (fallback after API fails)
+          mockedQuery.mockResolvedValue('0x123456');
+
+          // Refresh balances for mainnet
+          await refresh(clock, ['mainnet']);
+
+          // Verify that console.warn was called with the error message
+          expect(consoleWarnSpy).toHaveBeenCalledWith(
+            expect.stringContaining('Balance fetcher failed for chains 0x1:'),
+          );
+
+          fetchSpy.mockRestore();
+          consoleWarnSpy.mockRestore();
+        },
+      );
+    });
   });
 
   describe('syncBalanceWithAddresses', () => {
@@ -1051,6 +1125,41 @@ describe('AccountTrackerController', () => {
         },
       );
     });
+
+    it('should handle timeout in syncBalanceWithAddresses gracefully', async () => {
+      await withController(
+        {
+          isMultiAccountBalancesEnabled: true,
+          selectedAccount: ACCOUNT_1,
+          listAccounts: [],
+        },
+        async ({ controller }) => {
+          // Mock safelyExecuteWithTimeout to return undefined (timeout case)
+          mockedSafelyExecuteWithTimeout.mockImplementation(
+            async () => undefined, // Simulates timeout behavior
+          );
+
+          const result = await controller.syncBalanceWithAddresses([
+            ADDRESS_1,
+            ADDRESS_2,
+          ]);
+
+          // Verify that the result is an empty object when all operations timeout
+          expect(result).toStrictEqual({});
+
+          // Restore the mock
+          mockedSafelyExecuteWithTimeout.mockImplementation(
+            async (operation: () => Promise<unknown>) => {
+              try {
+                return await operation();
+              } catch {
+                return undefined;
+              }
+            },
+          );
+        },
+      );
+    });
   });
 
   it('should call refresh every interval on polling', async () => {

packages/assets-controllers/src/AccountTrackerController.ts

@@ -219,6 +219,8 @@ export class AccountTrackerController extends StaticIntervalPollingController<Ac
 
   readonly #includeStakedAssets: boolean;
 
+  readonly #accountsApiChainIds: ChainIdHex[];
+
   readonly #getStakedBalanceForChain: AssetsContractController['getStakedBalanceForChain'];
 
   readonly #balanceFetchers: BalanceFetcher[];
@@ -232,7 +234,7 @@ export class AccountTrackerController extends StaticIntervalPollingController<Ac
    * @param options.messenger - The controller messaging system.
    * @param options.getStakedBalanceForChain - The function to get the staked native asset balance for a chain.
    * @param options.includeStakedAssets - Whether to include staked assets in the account balances.
-   * @param options.useAccountsAPI - Enable Accounts‑API strategy (if supported chain).
+   * @param options.accountsApiChainIds - Array of chainIds that should use Accounts-API strategy (if supported by API).
    * @param options.allowExternalServices - Disable external HTTP calls (privacy / offline mode).
    */
   constructor({
@@ -241,15 +243,15 @@ export class AccountTrackerController extends StaticIntervalPollingController<Ac
     messenger,
     getStakedBalanceForChain,
     includeStakedAssets = false,
-    useAccountsAPI = false,
+    accountsApiChainIds = [],
     allowExternalServices = () => true,
   }: {
     interval?: number;
     state?: Partial<AccountTrackerControllerState>;
     messenger: AccountTrackerControllerMessenger;
     getStakedBalanceForChain: AssetsContractController['getStakedBalanceForChain'];
     includeStakedAssets?: boolean;
-    useAccountsAPI?: boolean;
+    accountsApiChainIds?: ChainIdHex[];
     allowExternalServices?: () => boolean;
   }) {
     const { selectedNetworkClientId } = messenger.call(
@@ -275,11 +277,12 @@ export class AccountTrackerController extends StaticIntervalPollingController<Ac
     this.#getStakedBalanceForChain = getStakedBalanceForChain;
 
     this.#includeStakedAssets = includeStakedAssets;
+    this.#accountsApiChainIds = [...accountsApiChainIds];
 
     // Initialize balance fetchers - Strategy order: API first, then RPC fallback
     this.#balanceFetchers = [
-      ...(useAccountsAPI && allowExternalServices()
-        ? [new AccountsApiBalanceFetcher('extension', this.#getProvider)]
+      ...(accountsApiChainIds.length > 0 && allowExternalServices()
+        ? [this.#createAccountsApiFetcher()]
         : []),
       createAccountTrackerRpcBalanceFetcher(
         this.#getProvider,
@@ -390,6 +393,31 @@ export class AccountTrackerController extends StaticIntervalPollingController<Ac
     );
   };
 
+  /**
+   * Creates an AccountsApiBalanceFetcher that only supports chains in the accountsApiChainIds array
+   *
+   * @returns A BalanceFetcher that wraps AccountsApiBalanceFetcher with chainId filtering
+   */
+  readonly #createAccountsApiFetcher = (): BalanceFetcher => {
+    const originalFetcher = new AccountsApiBalanceFetcher(
+      'extension',
+      this.#getProvider,
+    );
+
+    return {
+      supports: (chainId: ChainIdHex): boolean => {
+        // Only support chains that are both:
+        // 1. In our specified accountsApiChainIds array
+        // 2. Actually supported by the AccountsApi
+        return (
+          this.#accountsApiChainIds.includes(chainId) &&
+          originalFetcher.supports(chainId)
+        );
+      },
+      fetch: originalFetcher.fetch.bind(originalFetcher),
+    };
+  };
+
   /**
    * Resolves a networkClientId to a network client config
    * or globally selected network config if not provided