Introduction

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 install @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 install @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

Yarn

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

Bun

bun install @react-native-async-storage/async-storage react-native-get-random-values react-native-modal react-native-svg @react-native-community/netinfo

pnpm

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

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

Expo 48

Additional Setup for Expo SDK 48

If you are using Expo SDK 48, there's an issue with react-native-get-random-values, so we need to temporarily fix this by installing expo-crypto library and copying this file in your root folder.

npx expo install expo-crypto

Apply Polyfill

In your root file, add this line:

// Only for Expo SDK 48
import './expo-crypto-shim.js'

...

import { useWalletConnectModal } from '@walletconnect/modal-react-native';

• Make sure this line executes before the first @walletconnect/modal-react-native import.

Expo 49

Additional Setup for Expo SDK 49

If you are using Expo SDK 49, there's an issue with react-native-get-random-values, so we need to manually update it's version to v1.9.0 and exclude this package from expo validations. For more info, read Selectively opt out of package version validations

Modify your package.json

Exclude react-native-get-random-values in your package.json to install a different from the version recommended by Expo.

"dependencies": {
  ...
},
"expo": {
  "install": {
    "exclude": [
      "react-native-get-random-values"
    ]
  }
},
"devDependencies": {
  ...
}

Install latest version of "react-native-get-random-values"

npm

npm install react-native-get-random-values@1.9.0

Yarn

yarn add react-native-get-random-values@1.9.0

Bun

bun install react-native-get-random-values@1.9.0

pnpm

pnpm add react-native-get-random-values@1.9.0

(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

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.