Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.dynamic.xyz/docs/llms.txt

Use this file to discover all available pages before exploring further.

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 (deeplinking 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

NameTypeDefaultDescription
includeMobileOptionsbooleanfalseWhen true, additionally includes URI-based connection options (deeplinking 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.
The client instance is the second positional argument — only required when using multiple Dynamic clients.

​
Return value

An array of WalletOption. Each WalletOption has:
FieldTypeDescription
keystringStable identifier (e.g. "metamask").
namestringDisplay name.
iconUrlstringFull URL to the wallet’s icon.
primaryColorstring | undefinedBrand color in hex.
connectionOptionsWalletConnectionOption[]Ordered connection options for this wallet. Sorted by priority — see below. May be empty when only installationUrls is available (install-only wallets).
installationUrlsInstallationUrls | undefinedInstall / 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.
    • Resolve via getWalletProviderByKey({ key: walletProviderKey }) and call .connect().
  2. URI deeplink (type: 'walletConnect' | 'metamaskSdkUri') — drive the connection yourself via a URI that you either render as a QR (desktop) or append onto a deeplink (mobile).
    • Fields: chain, deeplinks: { native?, universal? }, type.
    • For 'walletConnect': mint the URI with connectWithWalletConnect<Chain>. For 'metamaskSdkUri': mint the URI with connectWithMetaMaskUri<Chain>. Either way, append it to the deeplink with appendConnectionUriToDeeplink for the mobile case.
  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. 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 deeplink 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 deeplink > inAppBrowser). With walletOptionOrdering: 'alphabetical', the outer list is sorted by name only — no tiering. The inner ordering is unchanged.

​
See also