feat(controllers): add includePayOnly and sort options to fetchWallets

Surface wallets that support WalletConnect Pay but are not v2-compatible
(filtered out by default) and allow sorting WCP-supporting wallets to the
top, via two new useAppKitWallets().fetchWallets() options:

- includePayOnly -> include_pay_only=true query param
- sort: 'wcpay' -> sort=wcpay query param

Both flow through fetchWalletsByPage and searchWallet into the /getWallets
request. Default behavior is unchanged when the options are omitted, so
general AppKit consumers keep hiding WCP-only wallets.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: enesozturk

.changeset/wcpay-fetch-wallets-filter.md

@@ -0,0 +1,5 @@
+---
+'@reown/appkit-controllers': minor
+---
+
+Add `includePayOnly` and `sort` options to `useAppKitWallets().fetchWallets()`. `includePayOnly` surfaces wallets that support WalletConnect Pay but are not v2-compatible (filtered out by default), and `sort: 'wcpay'` bubbles WalletConnect Pay-supporting wallets to the top.

packages/controllers/exports/react.ts

@@ -325,6 +325,13 @@ export interface FetchWalletsOptions {
   include?: string[]
   /** Wallet IDs to exclude. Overrides the default exclude list when provided. */
   exclude?: string[]
+  /**
+   * Include wallets that support WalletConnect Pay but are not v2-compatible.
+   * By default these are filtered out. Enable for WalletConnect Pay surfaces.
+   */
+  includePayOnly?: boolean
+  /** Sort mode. 'wcpay' bubbles WalletConnect Pay-supporting wallets to the top. */
+  sort?: 'default' | 'wcpay'
 }
 
 export interface UseAppKitWalletsReturn {

packages/controllers/src/controllers/ApiController.ts

@@ -281,7 +281,8 @@ export const ApiController = {
         page: String(params.page),
         entries: String(params.entries),
         include: params.include?.join(',') || undefined,
-        exclude: exclude.join(',') || undefined
+        exclude: exclude.join(',') || undefined,
+        include_pay_only: params.include_pay_only ? 'true' : undefined
       }
     })
 
@@ -391,12 +392,15 @@ export const ApiController = {
     entries: entriesOverride,
     badge,
     include: includeOverride,
-    exclude: excludeOverride
-  }: Pick<ApiGetWalletsRequest, 'page'> & {
+    exclude: excludeOverride,
+    includePayOnly,
+    sort
+  }: Pick<ApiGetWalletsRequest, 'page' | 'sort'> & {
     entries?: number
     badge?: BadgeType
     include?: string[]
     exclude?: string[]
+    includePayOnly?: boolean
   }) {
     const { includeWalletIds, excludeWalletIds, featuredWalletIds } = OptionsController.state
     const chains = ChainController.getRequestedCaipNetworkIds().join(',')
@@ -411,6 +415,8 @@ export const ApiController = {
       include: includeOverride ?? includeWalletIds,
       exclude: excludeOverride ?? defaultExclude,
       badge_type: badge,
+      include_pay_only: includePayOnly,
+      sort,
       chains
     }
     const { data, count, mobileFilteredOutWalletsLength } = await ApiController.fetchWallets(params)
@@ -454,12 +460,15 @@ export const ApiController = {
     entries: entriesOverride,
     page: pageOverride,
     include: includeOverride,
-    exclude: excludeOverride
-  }: Pick<ApiGetWalletsRequest, 'search' | 'badge'> & {
+    exclude: excludeOverride,
+    includePayOnly,
+    sort
+  }: Pick<ApiGetWalletsRequest, 'search' | 'badge' | 'sort'> & {
     entries?: number
     page?: number
     include?: string[]
     exclude?: string[]
+    includePayOnly?: boolean
   }) {
     const { includeWalletIds, excludeWalletIds } = OptionsController.state
     const chains = ChainController.getRequestedCaipNetworkIds().join(',')
@@ -472,6 +481,8 @@ export const ApiController = {
       badge_type: badge,
       include: includeOverride ?? includeWalletIds,
       exclude: excludeOverride ?? excludeWalletIds,
+      include_pay_only: includePayOnly,
+      sort,
       chains
     }
 

packages/controllers/src/utils/TypeUtil.ts

@@ -192,6 +192,13 @@ export interface ApiGetWalletsRequest {
   exclude?: string[]
   names?: string
   rdns?: string
+  /**
+   * Include wallets that support WalletConnect Pay but are not v2-compatible.
+   * By default the API returns only v2-compatible wallets, which filters these out.
+   */
+  include_pay_only?: boolean
+  /** Sort mode. 'wcpay' bubbles WalletConnect Pay-supporting wallets to the top. */
+  sort?: 'default' | 'wcpay'
 }
 
 export interface ApiGetWalletsResponse {