Introduction

info

Web3Modal SDK v3 is out! Learn how to integrate it here

WalletConnectModal is a simple ui library intended for advanced use cases where users manage connections strings and associated WalletConnect API's themselves.

Don't have a project ID?

Head over to WalletConnect Cloud and create a new project now!

Get started

Installation

Web

Add packages (NPM)

npm

npm install @walletconnect/modal

Yarn

yarn add @walletconnect/modal

Bun

bun add @walletconnect/modal

pnpm

pnpm add @walletconnect/modal

Add packages (CDN)

WalletConnectModal uses unpkg as its official CDN provider. Instead of using the npm package, you can simply import it from their CDN and use it in the same way.

<script type="module">
  import { WalletConnectModal } from 'https://unpkg.com/@walletconnect/modal'
</script>

iOS

caution

The WalletConnectModal SDK is currently in Alpha and is not production-ready.

It's public API and associated documentation may still see significant and breaking changes.

SwiftPackageManager

You can add a WalletConnect SDK to your project with Swift Package Manager. In order to do that:

1. Open XCode
2. Go to File -> Add Packages
3. Paste the repo GitHub url: https://github.com/WalletConnect/WalletConnectSwiftV2
4. Tap Add Package
5. Choose the WalletConnectV2 products that you want installed in your app.

Alternatively, add WalletConnectModal to a Package.swift manifest

To integrate via a Package.swift manifest instead of Xcode, you can add WalletConnectModal to the dependencies array of your package:

dependencies: [
  .package(
    name: "WalletConnectV2",
    url: "https://github.com/WalletConnectV2/WalletConnectSwiftV2.git",
    .upToNextMajor(from: "1.6.4")
  ),

  // Any other dependencies you have...
],

Then, in any target that depends on a WalletConnectV2 product, add it to the dependencies array of that target:

.target(
  name: "MyTargetName",
  dependencies: [
    // The product(s) you want (e.g. WalletConnectModal).
    .product(name: "WalletConnectModal", package: "WalletConnectV2"),
  ]
),

Android

caution

The WalletConnectModal SDK is currently in Alpha and is not production-ready.

It's public API and associated documentation may still see significant and breaking changes.

Kotlin implementation of WalletConnectModal for Android applications.

Android Core

WalletConnectModal

Requirements

• Android min SDK 23
• Java 11

Installation

root/build.gradle.kts:

allprojects {
   repositories {
      mavenCentral()
      maven { url "https://jitpack.io" }
   }
}

app/build.gradle.kts

implementation(platform("com.walletconnect:android-bom:$BOM_VERSION"))
implementation("com.walletconnect:android-core")
implementation("com.walletconnect:walletconnect-modal")

Flutter

React Native CLI

npm

npm install @walletconnect/modal-react-native

Yarn

yarn add @walletconnect/modal-react-native

Bun

bun add @walletconnect/modal-react-native

pnpm

pnpm add @walletconnect/modal-react-native

Additionally add these extra packages to help with async storage, polyfills, modals and SVG's.

npm

npm install @react-native-async-storage/async-storage react-native-get-random-values react-native-modal react-native-svg @react-native-community/netinfo @walletconnect/react-native-compat

Yarn

yarn add @react-native-async-storage/async-storage react-native-get-random-values react-native-modal react-native-svg @react-native-community/netinfo @walletconnect/react-native-compat

Bun

bun add @react-native-async-storage/async-storage react-native-get-random-values react-native-modal react-native-svg @react-native-community/netinfo @walletconnect/react-native-compat

pnpm

pnpm add @react-native-async-storage/async-storage react-native-get-random-values react-native-modal react-native-svg @react-native-community/netinfo @walletconnect/react-native-compat

On iOS, use CocoaPods to add the native modules to your project:

npx pod-install

(Optional) Enable Wallet Detection

To enable WalletConnectModal to detect wallets installed on the device, you need to make specific changes to the native code of your project.

For iOS:

1. Open your Info.plist file.
2. Locate the <key>LSApplicationQueriesSchemes</key> section.
3. Add the desired wallet schemes as string entries within the <array>. These schemes represent the wallets you want to detect.
4. Refer to our Info.plist example file for a detailed illustration.

Example:

<key>LSApplicationQueriesSchemes</key>
<array>
  <string>metamask</string>
  <string>trust</string>
  <string>safe</string>
  <string>rainbow</string>
  <string>uniswap</string>
  <!-- Add other wallet schemes names here -->
</array>

For Android:

1. Open your AndroidManifest.xml file.
2. Locate the <queries> section.
3. Add the desired wallet package names as <package> entries within the <queries>. These package names correspond to the wallets you want to detect.
4. Refer to our AndroidManifest.xml example file for detailed guidance.

Example:

<queries>
  <package android:name="io.metamask"/>
  <package android:name="com.wallet.crypto.trustapp"/>
  <package android:name="io.gnosis.safe"/>
  <package android:name="me.rainbow"/>
  <!-- Add other wallet package names here -->
</queries>

Important Note: The WalletConnect SDK will only be able to detect the wallets that you explicitly list in your native files. Make sure to include all the relevant wallet schemes/packages you want to support.

For additional wallet schemes and package names, you can explore our Explorer API. This API offers an up-to-date list of wallet identifiers that you can integrate into your project for enhanced wallet detection.

Expo

npx expo install @walletconnect/modal-react-native

Additionally add these extra packages to help with async storage, polyfills, modals and SVG's.

npx expo install @react-native-async-storage/async-storage react-native-get-random-values react-native-modal react-native-svg @react-native-community/netinfo @walletconnect/react-native-compat

Additional setup for Expo SDK 48 only

If you are using Expo SDK 48, you also need to polyfill crypto with expo-crypto library.

1. Add expo-crypto

npx expo install expo-crypto

2. Create a file named crypto-polyfill.js

// src/crypto-polyfill.js

// Apply only with Expo SDK 48
import { getRandomValues as expoCryptoGetRandomValues } from 'expo-crypto'

class Crypto {
  getRandomValues = expoCryptoGetRandomValues
}

// eslint-disable-next-line no-undef
const webCrypto = typeof crypto !== 'undefined' ? crypto : new Crypto()

;(() => {
  if (typeof crypto === 'undefined') {
    Object.defineProperty(window, 'crypto', {
      configurable: true,
      enumerable: true,
      get: () => webCrypto
    })
  }
})()

3. Import crypto-polyfill.js in your App root file

import './crypto-polyfill.js'
...
import { useWalletConnectModal } from '@walletconnect/modal-react-native';

(Optional) Enable Wallet Detection (iOS Only)

To enable WalletConnectModal to detect wallets installed on the device in your Expo project for iOS, follow these steps:

1. Open your app.json (or app.config.js) file.
2. Locate the ios section within the configuration.
3. Add the infoPlist object if it doesn't exist, and within it, include the LSApplicationQueriesSchemes array. This array will contain the desired wallet schemes you want to detect.
4. Add the wallet schemes to the LSApplicationQueriesSchemes array.

Your configuration should look like this:

{
  "expo": {
    "ios": {
      "bundleIdentifier": "com.your.app",
      "infoPlist": {
        "LSApplicationQueriesSchemes": [
          "metamask",
          "trust",
          "safe",
          "rainbow",
          "uniswap"
          // Add other wallet schemes names here
        ]
      }
    }
  }
}

Configuring wallet detection for Android is not supported through Expo, as there's no direct way to add the required queries. This configuration is specifically for iOS in an Expo project.

Important Note: The WalletConnect SDK will only be able to detect the wallets that you explicitly list in your native files. Make sure to include all the relevant wallet schemes you want to support.

For additional wallet schemes, you can explore our Explorer API. This API offers an up-to-date list of wallet identifiers that you can integrate into your project for enhanced wallet detection.

React Native

Install the WalletConnect Modal package.

flutter pub add walletconnect_modal_flutter

Unity

Prerequisites

• Unity 2021.3 or above
• IL2CPP code stripping level: Minimal (or lower)

OpenUPM CLI

To install packages via OpenUPM, you need to have Node.js and openupm-cli installed. Once you have them installed, you can run the following commands:

openupm add com.walletconnect.modal

Package Manager with OpenUPM

1. Open Advanced Project Settings from the gear ⚙ menu located at the top right of the Package Manager’s toolbar
2. Add a new scoped registry with the following details:
   • Name: OpenUPM
   • URL: https://package.openupm.com
   • Scope(s): com.walletconnect
3. Press plus ➕ and then Save buttons
4. In the Package Manager windows open the add ➕ menu from the toolbar
5. Select Add package by name...
6. Enter the package name:
   • com.walletconnect.modal
7. Press Add button

Package Manager with Git URL

1. Open the add ➕ menu in the Package Manager’s toolbar
2. Select Add package from git URL...
3. Enter the package URL. You will need to install 3 packages in the following order:

WalletConnectUnity Core

https://github.com/WalletConnect/WalletConnectUnity.git?path=Packages/com.walletconnect.core

WalletConnectUnity UI

https://github.com/WalletConnect/WalletConnectUnity.git?path=Packages/com.walletconnect.ui

WalletConnectUnity Modal

https://github.com/WalletConnect/WalletConnectUnity.git?path=Packages/com.walletconnect.modal

4. Press Add button

(Optional) Installed Wallet Detection

To enable WalletConnect Modal to detect wallets installed on the device, you need to make specific changes to the native sides of the project.

Android

1. In Unity override Android Manifest.
2. Add your <queries>...</queries> schemes outside of <application /> scope in the manifest file.
3. Refer to Android Specs for more information.

Example:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <queries>
        <package android:name="io.metamask"/>
        <package android:name="com.wallet.crypto.trustapp"/>
        <package android:name="io.gnosis.safe"/>
        <package android:name="me.rainbow"/>
        <!-- Add other wallet schemes names here -->
    </queries>

    <application>
        ...
    </application>
</manifest>

More wallet package names can be found in our sample AndroidManifest.xml.

iOS

Wallet detection may produce inaccurate results on iOS Simulator. It is recommended to test on a real device.

1. Make an iOS build.
2. In the generated Xcode project, find Info.plist file and open it with a external editor (i.e. not Xcode).
3. Locate or create <key>LSApplicationQueriesSchemes</key> section.
4. Add the desired wallet schemes as string entries within the <array>. These schemes represent the wallets you want to detect.

Example:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
        ...

        <key>LSApplicationQueriesSchemes</key>
        <array>
            <string>metamask</string>
            <string>trust</string>
            <string>safe</string>
            <string>rainbow</string>
            <string>uniswap</string>
            <string>zerion</string>
            <string>imtokenv2</string>
            <string>spot</string>
            <string>omni</string>
            <string>dfw</string>
            <string>tpoutside</string>
            <string>robinhood-wallet</string>
        </array>

        ...
    </dict>
</plist>

Important Note: The WalletConnect SDK will only be able to detect the wallets that you explicitly list in your native files. Make sure to include all the relevant wallet schemes/packages you want to support.

For additional wallet schemes and package names, you can explore our Explorer API. This API offers an up-to-date list of wallet identifiers that you can integrate into your project for enhanced wallet detection.

Next Steps

Now that you've installed WalletConnectModal, you're ready to start integrating it. The next section will walk you through the process of setting up your project to use the library.