How to get started with WalletConnect on Sui Network

Learn how to use WalletConnect to enable wallet connections and interact with the Sui network.

WalletConnect powers thousands of onchain projects, driving one of the most active, open ecosystems in crypto.

In this tutorial, you will learn how to:

1. Set up Sui network on WalletConnect.
2. Configure a wallet connection modal and enable interactions with the Sui network.

This guide takes approximately 10 minutes to complete.

Let’s get started!

Setup

In this section, you'll learn how to set up the development environment to use WalletConnect App SDK with Sui network.

For this tutorial, we'll be using React, though you can use any other framework compatible with WalletConnect App SDK.

First, create a React app using the command given below:

npm create vite@latest

After setting up your boilerplate React app, you can proceed with configuring the WalletConnect App SDK.

Install WalletConnect App SDK

Now, we need to install the WalletConnect App SDK and other dependencies that we need for our app to function as expected.

npm install @reown/appkit @reown/appkit-universal-connector @reown/appkit-common ethers

You can also use other package managers such as yarn, bun, pnpm, etc.

Create a new project on the Reown Dashboard

Now, we need to get a project ID from Reown Cloud that we will use to set up AppKit with Wagmi config. Navigate to dashboard.reown.com and sign in. If you have not created an account yet, please do so before we proceed.

After you have logged in, please navigate to your team’s section of the Cloud Dashboard and click on “+ Project”.

Now, select the product as “AppKit” and enter the name for your project. Then, click on “Create”.

The Dashboard will now create a new project for you, which will also generate a project ID. You will notice that your project was successfully created.

Scroll down, and at the bottom, you will be able to find your Project ID. Please copy that as you will need it later.

Build the App using WalletConnect App SDK

Before we build the app, let’s first configure our .env file. On the root level of your code directory, create a new file named .env.

Open that file and create a new variable VITE_PROJECT_ID. You will assign the project Id that you copied in the previous step to this environment variable that you just created. This is what it will look like:

VITE_PROJECT_ID = <YOUR_PROJECT_ID_HERE>

Note: Please make sure you follow the best practices when you are working with secret keys and other sensitive information. Environment variables that start with NEXT_PUBLIC will be exposed by your app which can be misused by bad actors.

Configure App SDK

For a quick integration of App SDK you can use the UniversalConnector class, which simplifies the integration of App SDK by providing a single interface for all the blockchain protocols. You can configure the Universal Connector with the networks you want to support. For more information, please visit RPC Reference section from the docs.

It is recommended recommend to create a config file to establish a singleton instance for the Universal Connector as shown below inside your /config/index.tsx file.

import type { AppKitNetwork } from '@reown/appkit/networks'
import type { CustomCaipNetwork } from '@reown/appkit-common'
import { UniversalConnector } from '@reown/appkit-universal-connector'

// Get projectId from https://dashboard.reown.com
export const projectId = import.meta.env.VITE_PROJECT_ID || "b56e18d47c72ab683b10814fe9495694" // this is a public projectId only to use on localhost

if (!projectId) {
  throw new Error('Project ID is not defined')
}

// you can configure your own network
const suiMainnet: CustomCaipNetwork<'sui'> = {
  id: 784,
  chainNamespace: 'sui' as const,
  caipNetworkId: 'sui:mainnet',
  name: 'Sui',
  nativeCurrency: { name: 'SUI', symbol: 'SUI', decimals: 9 },
  rpcUrls: { default: { http: ['https://fullnode.mainnet.sui.io:443'] } }
}

export const networks = [suiMainnet] as [AppKitNetwork, ...AppKitNetwork[]]

export async function getUniversalConnector() {
  const universalConnector = await UniversalConnector.init({
    projectId,
    metadata: {
      name: 'Universal Connector',
      description: 'Universal Connector',
      url: 'https://appkit.reown.com',
      icons: ['https://appkit.reown.com/icon.png']
    },
    networks: [
      {
        methods: ['sui_signPersonalMessage'],
        chains: [suiMainnet as CustomCaipNetwork],
        events: [],
        namespace: 'sui'
      }
    ]
  })

  return universalConnector
}

So what's happening in the above code? Let's understand it step-by-step:

1. First, we import the necessary functions from their respective packages. After this, we need to create the modal component for our app.
2. Custom Network - Defines Sui Mainnet with chain details (ID, RPC URL, native currency)
3. networks - these are the networks that we want our app to support. So we export the configured suiMainnet constant variable inside an array as a WalletConnect network.
4. metadata - This object contains information about our application that will be used by AppKit. This includes the name of the app, the description, the url and the icons representing our app. This is optional.
5. getUniversalConnector() - Initializes the Universal Connector with:
   • Project metadata (metadata).
   • Supported networks with methods (sui_signPersonalMessage), events, chains, and namespace.

This creates a reusable connector instance for your app to handle wallet connections and transactions on the Sui blockchain. You can find the complete list of Sui JSON RPC methods supported by WalletConnect here.

After this, you need to initialize the Universal Connector component. You can do this by adding the code below inside the /App.tsx file (usually located inside the /src folder).

import { useState, useEffect } from 'react'
import { getUniversalConnector } from './config' // previous config file
import { UniversalConnector } from '@reown/appkit-universal-connector'

export function App() {
  const [universalConnector, setUniversalConnector] = useState<UniversalConnector>()
  const [session, setSession] = useState<any>()

  
  // Initialize the Universal Connector on component mount
  useEffect(() => {
    getUniversalConnector().then(setUniversalConnector)
  }, [])

  // Set the session state in case it changes
  useEffect(() => {
    setSession(universalConnector?.provider.session)
  }, [universalConnector?.provider.session])

Create the WalletConnect UI for your app

To open/trigger the WalletConnect modal, you need to call the connect function from the Universal Connector as shown below. You can add this inside your /App.tsx file or create a separate component for this and use it inside the /App.tsx file.

// get the session from the universal connector
    const handleConnect = async () => {
      if (!universalConnector) {
        return
      }
  
      const { session: providerSession } = await universalConnector.connect()
      setSession(providerSession)
    };

    // disconnect the universal connector
    const handleDisconnect = async () => {
      if (!universalConnector) {
        return
      }
      await universalConnector.disconnect()
      setSession(null)
    };

    ...

    return (
    (
    <div>      
        <button onClick={handleConnect}>Open AppKit Core</button>
        <button onClick={handleDisconnect}>Disconnect</button>
    </div>
    )

The code above uses the WalletConnect SDK configuration to handle a user connection and disconnection from your web app.

If you are wondering how you can prompt your users to request sign a message to verify ownership of the connected wallet, please refer to the docs here.

You can now run the app and test it out. In order to do so, run the command given below.

npm run dev

Conclusion

And that’s it! You have now learned how to create a simple app using WalletConnect App SDK that allows users to connect their wallet and interact with the Sui network.

WalletConnect is the decentralized connectivity layer for the financial internet, a universal infrastructure that enables secure, encrypted connections between wallets and applications across any blockchain. With 350M+ connections facilitated, 700+ wallets, and 75,000+ apps connected, WalletConnect provides the essential building block for trusted wallet-to-app experiences through its open standards-based protocol and decentralized relay network.

The ecosystem offers modular products including the App SDK (gateway for apps to access the network with prebuilt wallet connection UX), Wallet SDK (WalletKit for wallets to integrate multichain access with Sign and Auth APIs), and WalletConnect Pay (POS SDK and wallet_pay standard for stablecoin payments); all chain-agnostic, supporting EVM, Solana, Bitcoin, Cosmos, Polkadot, and any network with a CAIP-25 namespace, with end-to-end encryption ensuring privacy and security for DeFi, gaming, payments, and identity use cases across the decentralized web.

You can view the complete code repository here.

What's Next?

If you're wondering how to use WalletConnect for various use cases and build apps with great UX, feel free to check out our other blogs here.

Need help?

For support, please join the official WalletConnect Discord Server.