> ## 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.

# Connect a Wallet by Catalogue Key

> Connect an external wallet through the best available path for the user's device.

`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

<Tabs>
  <Tab title="JavaScript">
    ```typescript theme={"system"}
    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);
    ```
  </Tab>

  <Tab title="React">
    ```tsx theme={"system"}
    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>
      );
    }
    ```
  </Tab>
</Tabs>

Before this: create and initialize a Dynamic client (see [Creating a Dynamic Client](/docs/javascript/reference/client/create-dynamic-client), [Initializing the Dynamic Client](/docs/javascript/reference/client/initialize-dynamic-client)).

## Parameters

| Name                          | Type                                                   | Default | 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`](/docs/javascript/reference/wallets/connect-and-verify-wallet) 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`](/docs/javascript/reference/wallets/connect-and-verify-wallet) to verify it and link it to the user.

## See also

* [Build a wallet picker](/docs/javascript/reference/wallets/build-wallet-picker)
* [Get wallet options catalogue](/docs/javascript/reference/wallets/get-wallet-options-catalogue)
* [Connect and verify a wallet](/docs/javascript/reference/wallets/connect-and-verify-wallet)