Skip to main content

Wallet Usage

Don't have a project ID?

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

Get startedcloud illustration

Implementation

Install the WalletConnect client package.

npm install @walletconnect/notify-client

If you are using the SDK on a server (such as Node.js), you will need to install an additional package:

npm install lokijs --save

The above step is not required if you are using the SDK on the browser-side.

Initialize the SDK clients

import { NotifyClient } from '@walletconnect/notify-client'

const notifyClient = await NotifyClient.init({
projectId: '<YOUR PROJECT ID>'
})

Add listeners for relevant events

// Handle response to a `notifyClient.subscribe(...)` call
notifyClient.on('notify_subscription', async ({ params }) => {
const { error } = params

if (error) {
// Setting up the subscription failed.
// Inform the user of the error and/or clean up app state.
console.error('Setting up subscription failed: ', error)
} else {
// New subscription was successfully created.
// Inform the user and/or update app state to reflect the new subscription.
console.log(`Subscribed successfully.`)
}
})

// Handle an incoming notification
notifyClient.on('notify_message', ({ params }) => {
const { message } = params
// e.g. build a notification using the metadata from `message` and show to the user.
})

// Handle response to a `notifyClient.update(...)` call
notifyClient.on('notify_update', ({ params }) => {
const { error } = params

if (error) {
// Updating the subscription's scope failed.
// Inform the user of the error and/or clean up app state.
console.error('Setting up subscription failed: ', error)
} else {
// Subscription's scope was updated successfully.
// Inform the user and/or update app state to reflect the updated subscription.
console.log(`Successfully updated subscription scope.`)
}
})

// Handle a change in the existing subscriptions (e.g after a subscribe or update)
notifyClient.on('notify_subscriptions_changed', ({ params }) => {
const { subscriptions } = params
// `subscriptions` will contain any *changed* subscriptions since the last time this event was emitted.
// To get a full list of subscriptions for a given account you can use `notifyClient.getActiveSubscriptions({ account: 'eip155:1:0x63Be...' })`
})

Register an identity key for cross-device account syncing

note

This is a one-time action per account. It does not need to be repeated after initial registration of the new account.

To register an identity key, you must provide a callback to the onSign: (message: string) => string parameter of the register method. In order to authorize the Notify subscription, the SDK will trigger this callback with a message to sign, expecting the signature for that message to be returned.

Some suggested ways to implement the onSign callback are via:

Registering as a dapp

const account = `eip155:1:0x63Be2c680685d2A9620c11b0068291261aa62d76`
const onSign = (message: string) => ethersWallet.signMessage(message)

await notifyClient.register({
account,
onSign,
domain: 'app.example.com', // pass the domain (i.e. the hostname) where your dapp is hosted.
isLimited: true // The user will be prompted to authorize this dapp to send and receive messages on their behalf for this domain using their WalletConnect identity.
})

Registering as a wallet

const account = `eip155:1:0x63Be2c680685d2A9620c11b0068291261aa62d76`
const onSign = (message: string) => ethersWallet.signMessage(message)

await notifyClient.register({
account,
onSign,
domain: 'com.example.app.rn', // pass your app's bundle identifier.
isLimited: false // The user will be prompted to authorize this wallet to send and receive messages on their behalf for ALL domains using their WalletConnect identity.
})

Unregistering

Any identity registered can be unregistered via the unregister method.

const account = `eip155:1:0x63Be2c680685d2A9620c11b0068291261aa62d76`

await notifyClient.unregister({
account
})

Managing Subscriptions

Creating a new subscription

info

To identify dapps that can be subscribed to via Notify, we can query the following Explorer API endpoint:

https://explorer-api.walletconnect.com/v3/dapps?projectId=YOUR_PROJECT_ID&is_notify_enabled=true

// Get the domain of the target dapp from the Explorer API response
const appDomain = new URL(fetchedExplorerDapp.platform_browser).hostname

// Subscribe to `fetchedExplorerDapp` by passing the account to be subscribed and the domain of the target dapp.
await notifyClient.subscribe({
account,
appDomain
})

// -> Success/Failure will be received via the `notify_update` event registered previously.
// -> New subscription will be emitted via the `notify_subscriptions_changed` watcher event.

Updating notification types on an existing subscription

// `topic` - subscription topic of the subscription that should be updated.
// `scope` - an array of notification types that should be enabled going forward. The current scopes can be found under `subscription.scope`.
await notifyClient.update({
topic,
scope: ['alerts']
})

// -> Success/Failure will be received via the `notify_update` event registered previously.
// -> Updated subscription will be emitted via the `notify_subscriptions_changed` watcher event.

Removing an existing subscription

// `topic` - subscription topic of the subscription that should be deleted.
await notifyClient.deleteSubscription({ topic })

Retrieving all currently active subscriptions

// Will return all active subscriptions for the provided account, keyed by subscription topic.
const accountSubscriptions = notifyClient.getActiveSubscriptions({
account: `eip155:1:0x63Be...`
})

Retrieving all past messages for a given subscription

// Will return all past Notify messages for the provided subscription topic, keyed by messageId.
const messageHistory = notifyClient.getMessageHistory({ topic })