Usage
This section provides instructions on how to initialize the WalletKit client, approve sessions with supported namespaces, and respond to session requests, enabling easy integration of Web3 wallets with dapps through a simple and intuitive interface.
Cloud Configuration
Create a new project on Reown Cloud at https://cloud.reown.com and obtain a new project ID.
Initialization
@walletconnect/react-native-compat
must be installed and imported before any @reown/*
dependencies for proper React Native polyfills.
Create a new instance from Core
and initialize it with your projectId
. Next, create a WalletKit instance by calling init
on WalletKit
. Passing in the options object containing metadata about the app.
The pair
function will help us pair between the dapp and wallet and will be used shortly.
Session
A session is a connection between a dapp and a wallet. It is established when a user approves a session proposal from a dapp. A session is active until the user disconnects from the dapp or the session expires.
Namespace Builder
With WalletKit (and @walletconnect/utils) we’ve published a helper utility that greatly reduces the complexity of parsing the required
and optional
namespaces. It accepts as parameters a session proposal
along with your user’s chains/methods/events/accounts
and returns ready-to-use namespaces
object.
Example usage
If your wallet supports multiple namespaces e.g. eip155
,cosmos
& near
Your supportedNamespaces
should look like the following example.
Get Active Sessions
You can get the wallet active sessions using the getActiveSessions
function.
EVM methods & events
In @walletconnect/ethereum-provider, (our abstracted EVM SDK for apps) we support by default the following Ethereum methods and events:
Session Approval
In order to connect with a dapp, you will need to receive a WalletConnect URI (WCURI) and this will talk to our protocol to facilitate a pairing session. Therefore, you will need a test dapp in order to communicate with the wallet. We recommend testing with our React V2 Dapp as this is the most up-to-date development site.
In order to capture the WCURI, recommend having some sort of state management you will pass through a TextInput
or QRcode instance.
The session_proposal
event is emitted when a dapp initiates a new session with a user’s wallet. The event will include a proposal
object with information about the dapp and requested permissions. The wallet should display a prompt for the user to approve or reject the session. If approved, call approveSession
and pass in the proposal.id
and requested namespaces
.
The pair
method initiates a WalletConnect pairing process with a dapp using the given uri
(QR code from the dapps). To learn more about pairing, checkout out the docs.
Session Rejection
You can use the getSDKError
function, which is available in the @walletconnect/utils
for the rejection function library.
Responding to Session requests
session-request-example
The session_request
event is triggered by a dapp when it needs the wallet to perform a specific action, such as signing a transaction. The event contains a topic
and a request
object, which will vary depending on the action requested.
To respond to the request, the wallet can access the topic
and request
object by destructuring them from the event payload. To see a list of possible request
and response
objects, refer to the relevant JSON-RPC Methods for Ethereum, Solana, Cosmos, or Stellar.
As an example, if the dapp requests a personal_sign
method, the wallet can extract the params
array from the request
object. The first item in the array is the hex version of the message to be signed, which can be converted to UTF-8 and assigned to a message
variable. The second item in params
is the user’s wallet address.
To sign the message, the wallet can use the wallet.signMessage
method and pass in the message. The signed message, along with the id
from the event payload, can then be used to create a response
object, which can be passed into respondSessionRequest
.
The wallet then signs the message. signedMessage
, along with the id
from the event payload, can then be used to create a response
object, which can be passed into respondSessionRequest
.
To reject a session request, the response should be similar to this.
Updating a Session
The session_update
event is emitted from the wallet when the session is updated by calling updateSession
. To update a session, pass in the topic and the new namespace.
Extending a Session
To extend the session, call the extendSession
method and pass in the new topic
. The session_update
event will be emitted from the wallet.
Session Disconnect
When either the dapp or the wallet disconnects from a session, a session_delete
event will be emitted. It’s important to subscribe to this event so you could keep your state up-to-date.
To initiate a session disconnect, call the disconnectSession
method and pass in the topic
and reason
. You can use the getSDKError
utility function, which is available in the @walletconnect/utils
library.
Emitting Session Events
To emit session events, call the emitSessionEvent
and pass in the params. If you wish to switch to chain/account that is not approved (missing from session.namespaces
) you will have to update the session first. In the following example, the wallet will emit session_event
that will instruct the dapp to switch the active accounts.
In the following example, the wallet will emit session_event
when the wallet switches chains.
Was this page helpful?