Connect a Wallet by Catalogue Key

connectWalletOption connects an external wallet by its wallet options catalogue key. It resolves the connection path for that wallet, so you do not need to route by connection option type. The SDK uses an installed wallet provider when the user has the wallet. Otherwise, it uses a URI pairing through WalletConnect or the MetaMask SDK and passes the URI to onConnectionUri while the promise stays pending until the user approves. If the wallet only provides its own in-app browser, the SDK opens that browser instead.

Usage

JavaScript
React

import {
  connectWalletOption,
  isMobile,
  redirectToInAppBrowser,
} from '@dynamic-labs-sdk/client';

const walletAccount = await connectWalletOption({
  handleWalletBrowserRedirect: ({ chain, walletKey }) =>
    redirectToInAppBrowser({
      appUrl: window.location.href,
      chain,
      walletKey,
    }),
  onConnectionUri: ({ uri }) => {
    if (isMobile()) {
      window.location.href = uri;
      return;
    }

    renderQrCode(uri);
  },
  walletKey: 'metamask',
});

console.log(walletAccount.address);

import { isMobile } from '@dynamic-labs-sdk/client';
import { useConnectWalletOption } from '@dynamic-labs-sdk/react-hooks';

function ConnectWalletButton() {
  const { mutate: connect, isPending } = useConnectWalletOption();

  return (
    <button
      onClick={() =>
        connect({
          onConnectionUri: ({ uri }) => {
            if (isMobile()) {
              window.location.href = uri;
              return;
            }

            renderQrCode(uri);
          },
          walletKey: 'metamask',
        })
      }
      disabled={isPending}
    >
      {isPending ? 'Connecting...' : 'Connect MetaMask'}
    </button>
  );
}

Before this: create and initialize a Dynamic client (see Creating a Dynamic Client, Initializing the Dynamic Client).

Parameters

Name	Type	Description
`walletKey`	`string`	Required. The wallet options catalogue key, such as `'metamask'`.
`chain`	`Chain`	The chain to connect on. Required only when the wallet resolves on more than one enabled chain.
`onConnectionUri`	`(params: ConnectionUriHandlerParams) => void`	Called with `{ uri }` for a URI pairing. Required for wallets whose only connection path is a URI pairing.
`handleWalletBrowserRedirect`	`(params: WalletBrowserRedirectHandlerParams) => void`	Called with `{ chain, walletKey }` when the wallet only provides its own in-app browser.

Return value

connectWalletOption returns a promise for the connected WalletAccount. The account is not verified. Use verifyWalletAccount or useVerifyWalletAccount to link it to the user. The promise remains pending for a wallet’s in-app-browser path. The connection completes after the next page load inside the wallet’s browser.

Connection paths

Installed wallet provider

When the user has the wallet installed and the client has a matching wallet provider, the SDK connects through that provider.

URI pairing

When an installed provider is not available, the SDK can use WalletConnect or the MetaMask SDK. It calls onConnectionUri with a URI while the connection promise remains pending. The promise resolves after the user approves the connection in the wallet. The uri is already the wallet’s own deeplink carrying the pairing. The SDK selects the variant the current platform can open for you: the native scheme on mobile, the universal link on desktop, and the other variant as a fallback. For a MetaMask SDK pairing, the URI is MetaMask’s launch link. If a wallet does not publish a deeplink, the URI is the bare pairing URI. Open the URI on mobile. On desktop, render it as a QR code for the user to scan with the wallet.

Wallet in-app browser

When the wallet has no installed provider or URI pairing, the SDK uses the wallet’s own in-app browser. It calls handleWalletBrowserRedirect with the wallet key and chain. Leave for that browser with redirectToInAppBrowser({ appUrl, chain, walletKey }). Without the handler, the SDK redirects the current page into the wallet’s browser itself. You only need the handler when you want to choose a different return page or when there is no current page URL, such as in React Native or server-side rendering. Either way, the returned promise never settles. The connection completes on the next page load inside the wallet’s browser, where the wallet provider is available.

Errors

Error	Condition
`WalletOptionNotFoundError`	No wallet option matches `walletKey`.
`AmbiguousWalletChainError`	The wallet resolves on more than one chain and `chain` was not passed.
`NoConnectionOptionAvailableError`	The wallet has no connection option that this client can drive on the requested chain.
`ConnectionUriHandlerMissingError`	The wallet resolves to a URI pairing and `onConnectionUri` was not passed.
`WalletBrowserRedirectHandlerMissingError`	The wallet resolves to its in-app browser, no `handleWalletBrowserRedirect` handler was passed, and there is no current page URL to redirect.
`UnsafeDeeplinkUrlError`	The wallet’s in-app-browser URL has a scheme that can execute script.

React

useConnectWalletOption wraps connectWalletOption as a mutation. Pass the connection parameters to connect, not to the hook. The mutation returns the connected, unverified wallet account in data. Use useVerifyWalletAccount to verify it and link it to the user.

Installation & Configuration

Chains & Networks

Authenticate

User & Session Management

Business Accounts

Wallets

Flow

Swaps

Earn

Funding & Onramp

Events

Building UI

Migrating from React

Extension Development

Connect a Wallet by Catalogue Key

Usage

Parameters

Return value

Connection paths

Installed wallet provider

URI pairing

Wallet in-app browser

Errors

React

See also

​Usage

​Parameters

​Return value

​Connection paths

​Installed wallet provider

​URI pairing

​Wallet in-app browser

​Errors

​React

​See also

Usage

Parameters

Return value

Connection paths

Installed wallet provider

URI pairing

Wallet in-app browser

Errors

React

See also