Get Wallet Options Catalogue

Get every wallet a user can sign in with — installed providers, WalletConnect, MetaMask SDK URI, in-app browsers, and install links — in a single ordered list.

getWalletOptionsCatalogue returns the catalogue of external wallet options a user can sign in with through this client. It collapses what used to be multiple per-source calls (installed providers, URI-based connection options, in-app browser entries, install links) into one ordered list, where each entry already carries every connection path the user can take for that wallet.

Use it to render a single, canonical wallet picker without writing per-source merging or deduplication logic.

Usage

import { getWalletOptionsCatalogue } from '@dynamic-labs-sdk/client';

const walletOptions = await getWalletOptionsCatalogue({
  includeMobileOptions: true,
});

for (const walletOption of walletOptions) {
  console.log(walletOption.name, walletOption.connectionOptions);
}

getWalletOptionsCatalogue always includes installed wallet providers. Set includeMobileOptions: true to additionally surface URI-based connection options (mobile handoff and QR code), in-app browser entries, and install links. This adds one network round-trip, so prefer skipping it if you only ever show installed wallets.

Parameters

Name	Type	Default	Description
includeMobileOptions	boolean	false	When true, additionally includes URI-based connection options (mobile handoff and QR code), in-app browser entries, and install links. Adds one network round-trip.
walletOptionOrdering	'relevance' | 'alphabetical'	'relevance'	'relevance' buckets wallets into three tiers (installed → connectable → install-only) and ranks each tier with Dynamic’s curated priority list. 'alphabetical' sorts by display name only.

Return value

An array of WalletOption. Each WalletOption has:

Field	Type	Description
key	string	Stable identifier (e.g. "metamask").
name	string	Display name.
iconUrl	string	Full URL to the wallet’s icon.
primaryColor	string | undefined	Brand color in hex.
connectionOptions	WalletConnectionOption[]	Ordered connection options for this wallet. Sorted by priority; see below. May be empty when only installationUrls is available (install-only wallets).
installationUrls	InstallationUrls | undefined	Install / download links per platform (android, chrome, edge, firefox, ios, native, opera, safari). Present only when includeMobileOptions: true and the wallet has at least one install target.

Connection options

Each WalletConnectionOption is a discriminated union by type, ordered within connectionOptions from best to worst:

1. withWalletProvider — connect through a wallet provider already registered with the SDK (browser extension, vendor SDK, etc.).
   • Fields: chain, source ('selfAnnounced' | 'windowInjected' | 'sdk'), walletProviderKey.
   • Call connectWithWalletProvider({ walletProviderKey }) to connect, or connectAndVerifyWithWalletProvider({ walletProviderKey }) to connect and verify the wallet account in one step.
2. URI connection (type: 'walletConnect' | 'metamaskSdkUri'): start a mobile wallet handoff or render a desktop QR code.
   • Fields: chain, deeplinks: { native?, universal? }, type.
   • For 'walletConnect', mint the URI with connectWithWalletConnect<Chain>. On mobile, append it to the wallet’s deeplink with appendConnectionUriToDeeplink.
   • For 'metamaskSdkUri', call connectWithMetaMaskUri<Chain>. The SDK opens MetaMask on mobile. Use the returned URI only for a desktop QR code.
3. inAppBrowser — a mobile wallet that exposes an in-app browser entry URL.
   • Fields: chain, url (template containing {{encodedDappURI}}).
   • Substitute {{encodedDappURI}} with encodeURIComponent(window.location.href) before opening.

When connectionOptions is empty but installationUrls is populated, the wallet is install-only — render an install affordance using the appropriate platform link rather than a connect button.

Picking an install link for the current platform

For install-only wallets (and the “install” fallback path on any other wallet), the SDK ships a small helper that picks the most relevant install URL from installationUrls for the platform the user is on right now:

import { getInstallationLinkForCurrentPlatform } from '@dynamic-labs-sdk/client';

const url = getInstallationLinkForCurrentPlatform({
  installationUrls: walletOption.installationUrls,
});

if (url) {
  window.open(url, '_blank');
}

The helper detects the platform (iOS, Android, Edge, Opera, Firefox, Safari, or Chrome) and returns exactly the field that matches it, with no fallback to a different platform. If the wallet’s manifest doesn’t ship a link for the detected platform, the helper returns undefined so you don’t end up handing a Firefox user a Chrome Web Store URL.

That said, installationUrls exposes every link the wallet’s manifest publishes — android, chrome, edge, firefox, ios, native, opera, safari — and you’re free to surface several of them at once so the user picks where to install. The helper is a convenience for the common single-button case, not a constraint.

Ordering

With walletOptionOrdering: 'relevance' (default), wallets are bucketed into three tiers, in this order:

1. Installed — has at least one withWalletProvider connection option.
2. Connectable: has at least one URI connection or in-app browser option, but no installed provider.
3. Install-only — only installationUrls is populated.

Within each tier, well-known wallets (MetaMask, Coinbase, Phantom, …) rank above unknown wallets, which fall through to alphabetical order at the tail of their tier. The inner connectionOptions array is always ordered by option-type priority (withWalletProvider > URI connection > inAppBrowser).

With walletOptionOrdering: 'alphabetical', the outer list is sorted by name only — no tiering. The inner ordering is unchanged.

React

useGetWalletOptionsCatalogue fetches on mount and re-renders when the catalogue changes:

import { useGetWalletOptionsCatalogue } from '@dynamic-labs-sdk/react-hooks';

function WalletPicker() {
  const { data: walletOptions = [], isLoading } = useGetWalletOptionsCatalogue({
    includeMobileOptions: true,
  });

  if (isLoading) return <p>Loading wallets...</p>;

  return (
    <ul>
      {walletOptions.map((wallet) => (
        <li key={wallet.key}>
          <img src={wallet.iconUrl} alt={wallet.name} width={24} />
          {wallet.name}
        </li>
      ))}
    </ul>
  );
}

See also

• Build a wallet picker — end-to-end pattern that uses this function.
• MetaMask Connection Guide: route metamaskSdkUri options on web and React Native.
• Authenticate with WalletConnect — lower-level WalletConnect flow.
• Get Available Wallets to Connect — installed-providers-only alternative.