Skip to main content

WalletConnect v2

Prompt users to connect to your app with WalletConnect v2.

Usage​

import { WalletConnect } from "@thirdweb-dev/wallets";

const wallet = new WalletConnect();

wallet.connect();

Configuration​

Optionally, provide a configuration object when instantiating the WalletConnect class.

projectId (recommended)

Your project's unique identifier. It can be obtained at cloud.walletconnect.com. It is highly recommended to use your own project id and only use the default one for testing purposes.

It enables the following functionalities within WalletConnect's web3modal:

  • wallet and chain logos
  • optional WalletConnect RPC
  • support for all wallets from our Explorer and WalletConnect v2 support

Defaults to thirdweb's common project id.

import { WalletConnect } from "@thirdweb-dev/wallets";

const wallet = new WalletConnect(
  {
    projectId: "<PROJECT_ID>",
  },
);
clientId (recommended)

Provide clientId to use the thirdweb RPCs for given chains

You can create a client ID for your application from thirdweb dashboard.

chains

Provide an array of chains you want to support.

Must be an array of Chain objects, from the @thirdweb-dev/chains package.

Defaults to our default chains.

import { WalletConnect } from "@thirdweb-dev/wallets";
import { Ethereum } from "@thirdweb-dev/chains";

const walletWithOptions = new WalletConnect(
  {
    chains: [Ethereum],
  },
);
dappMetadata

Information about your app that the wallet will display when your app tries to connect to it.

Must be an object containing name, url, and optionally description and logoUrl properties.

import { WalletConnect } from "@thirdweb-dev/wallets";

const walletWithOptions = new WalletConnect({
  dappMetadata: {
    name: "thirdweb powered dApp",
    url: "https://thirdweb.com",
    description: "thirdweb powered dApp",
    logoUrl: "https://thirdweb.com/favicon.ico",
  },
});
qrcode

Whether to display the Wallet Connect QR code Modal or not.

Must be a boolean. Defaults to true.

import { WalletConnect } from "@thirdweb-dev/wallets";

const walletWithOptions = new WalletConnect(
  {
    qrcode: false,
  },
);
qrModalOptions

WalletConnect's options to customize the QR Code Modal.

Type​

type QRModalOptions = {
  themeVariables?: {
    "--wcm-z-index"?: string;
    "--wcm-accent-color"?: string;
    "--wcm-accent-fill-color"?: string;
    // ... and more
  };
  themeMode?: "dark" | "light";
  standaloneChains?: string[];
  mobileWallets?: MobileWallet[];
  desktopWallets?: DesktopWallet[];
  walletImages?: Record<string, string>;
  chainImages?: Record<string, string>;
  tokenImages?: Record<string, string>;
  tokenContracts?: Record<number, string>;
  enableNetworkView?: boolean;
  enableAccountView?: boolean;
  enableExplorer?: boolean;
  explorerRecommendedWalletIds?: string[] | "NONE";
  explorerExcludedWalletIds?: string[] | "ALL";
  termsOfServiceUrl?: string;
  privacyPolicyUrl?: string;
};

interface MobileWallet {
  id: string;
  name: string;
  links: {
    universal: string;
    native?: string;
  };
}

interface DesktopWallet {
  id: string;
  name: string;
  links: {
    native: string;
    universal: string;
  };
}
themeVariables

Allows to override Web3Modal's CSS styles. See theming for Info.

themeMode

Puts Modal into dark or light mode. Defaults to the user's system preference.

standaloneChains

When using Web3Modal in standalone mode (without wagmi) you can define an array of custom chains via this option.

Defaults to undefined

Example​

standaloneChains: [
  "eip155:1",
  "cosmos:cosmoshub-4",
  "polkadot:91b171bb158e2d3848fa23a9f1c25182",
];
mobileWallets

You can define an array of custom mobile wallets.

Note: you will also need to add appropriate wallet images in walletImages.

Native link represents deep-linking URL like rainbow:// and Universal link represent webpage link that can redirect to the app or fallback page. Defaults to undefined

mobileWallets: [
  {
    id: string,
    name: string,
    links: {
      native: string
      universal: string,
    },
  },
];
desktopWallets

You can define an array of custom desktop or web-based wallets.

Note: you will also need to add appropriate wallet images in walletImages.

Native link represents deep linking url like ledgerlive:// and Universal link represents webpage link that can redirect to the app or fallback page.

Defaults to undefined

desktopWallets: [
  {
    id: string,
    name: string,
    links: {
      native: string
      universal: string,
    },
  },
];
walletImages

an Array of wallet ids and their logo mappings.

This will override default logos.

Ids in this case can be: Explorer ids, wallet ids you provided in mobileWallets or desktopWallets and Wagmi connector ids.

Defaults to undefined

Example​

walletImages: {
  rainbow: "/images/rainbow.webp",
  metaMask: "/images/metamask.webp",
};
chainImages

an Array of chain ids and their logo mappings.

This will override default logos.

You can find detailed chain data at chainlist.org

Defaults to undefined

Example​

chainImages: {
  1: "/images/ethereum.webp",
  137: "/images/polygon.webp",
};
tokenImages

An array of token symbols and their logo mappings.

Defaults to undefined

Example​

tokenImages: {
  ETH: "/images/eth.webp",
  AVAX: "/images/avax.webp",
};
tokenContracts

Allows to override default token(s) address for each chain to show custom balances in account view.

Defaults to undefined

Example​

tokenContracts: {
  1: '0x1f9840a85d5af5bf1d1762f925bdaddc4201f984',
  137: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174'
}
enableNetworkView

If more than 1 chain is provided in the modal, users will be shown network selection view before selecting a wallet.

This option can enable or disable this behavior.

Defaults to false

enableAccountView

Option to enable or disable the modal's account view.

default is true

enableExplorer

Option to enable or disable wallet fetching from Explorer.

Defaults to true

explorerRecommendedWalletIds

Allows to override default recommended wallets that are fetched from Explorer API.

You can define an array of wallet ids you'd like to prioritize (order is respected).

You can get/copy these ids from the Explorer link mentioned before.

If you want to completely disable recommended wallets, you can set this option to "NONE".

Defaults to undefined

Example​

explorerRecommendedWalletIds: [
  "1ae92b26df02f0abca6304df07debccd18262fdf5fe82daa81593582dac9a369",
  "4622a2b2d6af1c9844944291e5e7351a6aa24cd7b23099efac1b2fd875da31a0",
];
// -- or -- //
explorerRecommendedWalletIds: "NONE";
explorerExcludedWalletIds

Allows to exclude wallets that are fetched from Explorer API.

You can define an array of wallet ids you'd like to exclude.

You can get/copy these ids from the explorer link mentioned before.

If you want to exclude all wallets, you can set this option to "ALL", however, if explorerRecommendedWalletIds are defined, they will still be fetched.

Defaults to undefined

Example​

explorerExcludedWalletIds: [
  "1ae92b26df02f0abca6304df07debccd18262fdf5fe82daa81593582dac9a369",
  "4622a2b2d6af1c9844944291e5e7351a6aa24cd7b23099efac1b2fd875da31a0",
];
// -- or -- //
explorerExcludedWalletIds: "ALL";
termsOfServiceUrl

String URL to your terms of service page, if specified will append a special "legal info" footer to the modal.

Defaults to undefined

privacyPolicyUrl

String URL to your privacy policy page, if specified will append a special "legal info" footer to the modal.

Defaults to undefined

walletStorage

Some wallets need to store data in persistent storage. This is the storage that will be used for that.

Must be an object conforming to the AsyncStorage interface:

export interface AsyncStorage {
  getItem(key: string): Promise<string | null>;
  setItem(key: string, value: string): Promise<void>;
  removeItem(key: string): Promise<void>;
}

Example:

import { WalletConnect } from "@thirdweb-dev/wallets";

const wallet = new WalletConnect(
  {
    walletStorage: {
      getItem: (key) => {
        // Implement your own storage logic here
      },
      removeItem: (key) => {
        // Implement your own storage logic here
      },
      setItem: (key, value) => {
        // Implement your own storage logic here
      },
    },
  },
);
walletId

An ID for the wallet. It is used to store the wallet in the walletStorage.

import { WalletConnect } from "@thirdweb-dev/wallets";

const walletWithOptions = new WalletConnect(
  {
    walletId: "wallet-id",
  },
);

Methods​

Inherits all the public methods from the AbstractClientWallet class.