feat: expose full API params in fetchWallets hook (#5526)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: tomiir

.changeset/four-pans-attend.md

@@ -0,0 +1,14 @@
+---
+'@reown/appkit-adapter-wagmi': patch
+'@reown/appkit-utils': patch
+'@reown/appkit-experimental': patch
+'@reown/appkit-controllers': patch
+'@reown/appkit': patch
+'@reown/appkit-common': patch
+'@reown/appkit-siwe': patch
+'@reown/appkit-siwx': patch
+'@reown/appkit-cdn': patch
+'@reown/appkit-pay': patch
+---
+
+Adds more options to fetchWallets method on useAppKitWallets

packages/controllers/exports/react.ts

@@ -24,6 +24,7 @@ import { ConnectorControllerUtil } from '../src/utils/ConnectorControllerUtil.js
 import { CoreHelperUtil } from '../src/utils/CoreHelperUtil.js'
 import { MobileWalletUtil } from '../src/utils/MobileWallet.js'
 import type {
+  BadgeType,
   NamespaceTypeMap,
   UseAppKitAccountReturn,
   UseAppKitNetworkReturn,
@@ -301,6 +302,23 @@ export function useAppKitConnection({ namespace, onSuccess, onError }: UseAppKit
   }
 }
 
+export interface FetchWalletsOptions {
+  /** Page number to fetch (default: 1) */
+  page?: number
+  /** @deprecated Use `search` instead */
+  query?: string
+  /** Search query to filter wallets. When provided, switches to search mode. */
+  search?: string
+  /** Number of entries per page. Defaults to 40 for list mode, 100 for search mode. */
+  entries?: number
+  /** Filter wallets by badge type ('none' | 'certified') */
+  badge?: BadgeType
+  /** Wallet IDs to include. Overrides the global includeWalletIds config when provided. */
+  include?: string[]
+  /** Wallet IDs to exclude. Overrides the default exclude list when provided. */
+  exclude?: string[]
+}
+
 export interface UseAppKitWalletsReturn {
   /**
    * List of wallets for the initial connect view including WalletConnect wallet and injected wallets together. If user doesn't have any injected wallets, it'll fill the list with most ranked WalletConnect wallets.
@@ -351,10 +369,8 @@ export interface UseAppKitWalletsReturn {
   /**
    * Function to fetch WalletConnect wallets from the explorer API. Allows to list, search and paginate through the wallets.
    * @param options - Options for fetching wallets
-   * @param options.page - Page number to fetch (default: 1)
-   * @param options.query - Search query to filter wallets (default: '')
    */
-  fetchWallets: (options?: { page?: number; query?: string }) => Promise<void>
+  fetchWallets: (options?: FetchWalletsOptions) => Promise<void>
 
   /**
    * Function to connect to a wallet.
@@ -438,16 +454,17 @@ export function useAppKitWallets(): UseAppKitWalletsReturn {
     await ConnectionController.connectWalletConnect({ cache: 'auto' })
   }
 
-  async function fetchWallets(fetchOptions?: { page?: number; query?: string }) {
+  async function fetchWallets(fetchOptions?: FetchWalletsOptions) {
     setIsFetchingWallets(true)
     try {
-      if (fetchOptions?.query) {
-        await ApiController.searchWallet({ search: fetchOptions?.query })
+      const { query, ...options } = fetchOptions ?? {}
+      const search = options.search ?? query
+
+      if (search) {
+        await ApiController.searchWallet({ ...options, search })
       } else {
         ApiController.state.search = []
-        await ApiController.fetchWalletsByPage({
-          page: fetchOptions?.page ?? 1
-        })
+        await ApiController.fetchWalletsByPage({ page: 1, ...options })
       }
     } catch (error) {
       // eslint-disable-next-line no-console

packages/controllers/src/controllers/ApiController.ts

@@ -16,6 +16,7 @@ import type {
   ApiGetUsageResponse,
   ApiGetWalletsRequest,
   ApiGetWalletsResponse,
+  BadgeType,
   ProjectLimits,
   Tier,
   WcWallet
@@ -385,19 +386,31 @@ export const ApiController = {
     }
   },
 
-  async fetchWalletsByPage({ page }: Pick<ApiGetWalletsRequest, 'page'>) {
+  async fetchWalletsByPage({
+    page,
+    entries: entriesOverride,
+    badge,
+    include: includeOverride,
+    exclude: excludeOverride
+  }: Pick<ApiGetWalletsRequest, 'page'> & {
+    entries?: number
+    badge?: BadgeType
+    include?: string[]
+    exclude?: string[]
+  }) {
     const { includeWalletIds, excludeWalletIds, featuredWalletIds } = OptionsController.state
     const chains = ChainController.getRequestedCaipNetworkIds().join(',')
-    const exclude = [
+    const defaultExclude = [
       ...state.recommended.map(({ id }) => id),
       ...(excludeWalletIds ?? []),
       ...(featuredWalletIds ?? [])
     ].filter(Boolean)
     const params = {
       page,
-      entries,
-      include: includeWalletIds,
-      exclude,
+      entries: entriesOverride ?? entries,
+      include: includeOverride ?? includeWalletIds,
+      exclude: excludeOverride ?? defaultExclude,
+      badge_type: badge,
       chains
     }
     const { data, count, mobileFilteredOutWalletsLength } = await ApiController.fetchWallets(params)
@@ -435,18 +448,30 @@ export const ApiController = {
     }
   },
 
-  async searchWallet({ search, badge }: Pick<ApiGetWalletsRequest, 'search' | 'badge'>) {
+  async searchWallet({
+    search,
+    badge,
+    entries: entriesOverride,
+    page: pageOverride,
+    include: includeOverride,
+    exclude: excludeOverride
+  }: Pick<ApiGetWalletsRequest, 'search' | 'badge'> & {
+    entries?: number
+    page?: number
+    include?: string[]
+    exclude?: string[]
+  }) {
     const { includeWalletIds, excludeWalletIds } = OptionsController.state
     const chains = ChainController.getRequestedCaipNetworkIds().join(',')
     state.search = []
 
     const params = {
-      page: 1,
-      entries: 100,
+      page: pageOverride ?? 1,
+      entries: entriesOverride ?? 100,
       search: search?.trim(),
       badge_type: badge,
-      include: includeWalletIds,
-      exclude: excludeWalletIds,
+      include: includeOverride ?? includeWalletIds,
+      exclude: excludeOverride ?? excludeWalletIds,
       chains
     }
 

packages/controllers/tests/hooks/react.test.ts

@@ -938,7 +938,7 @@ describe('useAppKitWallets', () => {
     await result.fetchWallets()
 
     expect(setIsFetchingWallets).toHaveBeenCalledWith(true)
-    expect(fetchWalletsByPageSpy).toHaveBeenCalledWith({ page: 1, entries: undefined })
+    expect(fetchWalletsByPageSpy).toHaveBeenCalledWith({ page: 1 })
     expect(ApiController.state.search).toEqual([])
     expect(setIsFetchingWallets).toHaveBeenCalledWith(false)
   })
@@ -1058,6 +1058,197 @@ describe('useAppKitWallets', () => {
     consoleErrorSpy.mockRestore()
   })
 
+  it('should fetch wallets with search param', async () => {
+    const setIsFetchingWallets = vi.fn()
+    mockedReact.useState.mockReturnValue([false, setIsFetchingWallets])
+
+    useSnapshot
+      .mockReturnValueOnce({
+        features: { headless: true },
+        remoteFeatures: { headless: true }
+      })
+      .mockReturnValueOnce({
+        wcUri: undefined,
+        wcFetchingUri: false
+      })
+      .mockReturnValueOnce({
+        wallets: [],
+        search: [],
+        page: 1,
+        count: 0
+      })
+      .mockReturnValueOnce({
+        initialized: true,
+        connectingWallet: undefined
+      })
+
+    vi.spyOn(ConnectUtil, 'getInitialWallets').mockReturnValue([])
+    vi.spyOn(ConnectUtil, 'getWalletConnectWallets').mockReturnValue([])
+    const searchWalletSpy = vi.spyOn(ApiController, 'searchWallet').mockResolvedValue(undefined)
+
+    const result = useAppKitWallets()
+
+    await result.fetchWallets({ search: 'phantom' })
+
+    expect(searchWalletSpy).toHaveBeenCalledWith({ search: 'phantom' })
+  })
+
+  it('should use search over query when both provided', async () => {
+    const setIsFetchingWallets = vi.fn()
+    mockedReact.useState.mockReturnValue([false, setIsFetchingWallets])
+
+    useSnapshot
+      .mockReturnValueOnce({
+        features: { headless: true },
+        remoteFeatures: { headless: true }
+      })
+      .mockReturnValueOnce({
+        wcUri: undefined,
+        wcFetchingUri: false
+      })
+      .mockReturnValueOnce({
+        wallets: [],
+        search: [],
+        page: 1,
+        count: 0
+      })
+      .mockReturnValueOnce({
+        initialized: true,
+        connectingWallet: undefined
+      })
+
+    vi.spyOn(ConnectUtil, 'getInitialWallets').mockReturnValue([])
+    vi.spyOn(ConnectUtil, 'getWalletConnectWallets').mockReturnValue([])
+    const searchWalletSpy = vi.spyOn(ApiController, 'searchWallet').mockResolvedValue(undefined)
+
+    const result = useAppKitWallets()
+
+    await result.fetchWallets({ search: 'phantom', query: 'metamask' })
+
+    expect(searchWalletSpy).toHaveBeenCalledWith({ search: 'phantom' })
+  })
+
+  it('should pass entries and badge to fetchWalletsByPage', async () => {
+    const setIsFetchingWallets = vi.fn()
+    mockedReact.useState.mockReturnValue([false, setIsFetchingWallets])
+
+    useSnapshot
+      .mockReturnValueOnce({
+        features: { headless: true },
+        remoteFeatures: { headless: true }
+      })
+      .mockReturnValueOnce({
+        wcUri: undefined,
+        wcFetchingUri: false
+      })
+      .mockReturnValueOnce({
+        wallets: [],
+        search: [],
+        page: 1,
+        count: 0
+      })
+      .mockReturnValueOnce({
+        initialized: true,
+        connectingWallet: undefined
+      })
+
+    vi.spyOn(ConnectUtil, 'getInitialWallets').mockReturnValue([])
+    vi.spyOn(ConnectUtil, 'getWalletConnectWallets').mockReturnValue([])
+    const fetchWalletsByPageSpy = vi
+      .spyOn(ApiController, 'fetchWalletsByPage')
+      .mockResolvedValue(undefined)
+
+    const result = useAppKitWallets()
+
+    await result.fetchWallets({ entries: 20, badge: 'certified' })
+
+    expect(fetchWalletsByPageSpy).toHaveBeenCalledWith({
+      page: 1,
+      entries: 20,
+      badge: 'certified'
+    })
+  })
+
+  it('should pass badge and entries to searchWallet', async () => {
+    const setIsFetchingWallets = vi.fn()
+    mockedReact.useState.mockReturnValue([false, setIsFetchingWallets])
+
+    useSnapshot
+      .mockReturnValueOnce({
+        features: { headless: true },
+        remoteFeatures: { headless: true }
+      })
+      .mockReturnValueOnce({
+        wcUri: undefined,
+        wcFetchingUri: false
+      })
+      .mockReturnValueOnce({
+        wallets: [],
+        search: [],
+        page: 1,
+        count: 0
+      })
+      .mockReturnValueOnce({
+        initialized: true,
+        connectingWallet: undefined
+      })
+
+    vi.spyOn(ConnectUtil, 'getInitialWallets').mockReturnValue([])
+    vi.spyOn(ConnectUtil, 'getWalletConnectWallets').mockReturnValue([])
+    const searchWalletSpy = vi.spyOn(ApiController, 'searchWallet').mockResolvedValue(undefined)
+
+    const result = useAppKitWallets()
+
+    await result.fetchWallets({ query: 'safe', badge: 'certified', entries: 50 })
+
+    expect(searchWalletSpy).toHaveBeenCalledWith({
+      search: 'safe',
+      badge: 'certified',
+      entries: 50
+    })
+  })
+
+  it('should pass include and exclude to fetchWalletsByPage', async () => {
+    const setIsFetchingWallets = vi.fn()
+    mockedReact.useState.mockReturnValue([false, setIsFetchingWallets])
+
+    useSnapshot
+      .mockReturnValueOnce({
+        features: { headless: true },
+        remoteFeatures: { headless: true }
+      })
+      .mockReturnValueOnce({
+        wcUri: undefined,
+        wcFetchingUri: false
+      })
+      .mockReturnValueOnce({
+        wallets: [],
+        search: [],
+        page: 1,
+        count: 0
+      })
+      .mockReturnValueOnce({
+        initialized: true,
+        connectingWallet: undefined
+      })
+
+    vi.spyOn(ConnectUtil, 'getInitialWallets').mockReturnValue([])
+    vi.spyOn(ConnectUtil, 'getWalletConnectWallets').mockReturnValue([])
+    const fetchWalletsByPageSpy = vi
+      .spyOn(ApiController, 'fetchWalletsByPage')
+      .mockResolvedValue(undefined)
+
+    const result = useAppKitWallets()
+
+    await result.fetchWallets({ include: ['wallet-1'], exclude: ['wallet-2'] })
+
+    expect(fetchWalletsByPageSpy).toHaveBeenCalledWith({
+      page: 1,
+      include: ['wallet-1'],
+      exclude: ['wallet-2']
+    })
+  })
+
   it('should connect to injected wallet', async () => {
     const mockConnector = {
       id: 'test-connector',