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 domain =  'app.mydomain.com', // pass the domain (i.e. the hostname) where your dapp is hosted.
const allApps =  false // The user will be prompted to authorize this dapp to send and receive messages on their behalf for only this specific domain using their WalletConnect identity.


// No need to register and sign message if already registered.
if (notifyClient.isRegistered({ account, domain, allApps })) return;

const {registerParams, message}  = notifyClient.prepareRegistration({
  account,
  domain,
  allApps
});

const signature = await ethersWallet.signMessage(message);

await notifyClient.register({
  registerParams,
  signature,
})

Registering as a wallet​

const account = `eip155:1:0x63Be2c680685d2A9620c11b0068291261aa62d76`
const domain =  'app.mydomain.com', // pass the domain (i.e. the hostname) where your dapp is hosted.
const allApps =  true // The user will be prompted to authorize this wallet to send and receive messages on their behalf for ALL domains using their WalletConnect identity.

// No need to register and sign message if already registered.
if (notifyClient.isRegistered({ account, domain, allApps })) return;

const {registerParams, message}  = notifyClient.prepareRegistration({
  account,
  domain,
  allApps
});

const signature = await ethersWallet.signMessage(message);

await notifyClient.register({
  registerParams,
  signature,
})

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.

// get notification types by accessing `scope` member of a dapp's subscription
const notificationTypes = notifyClient
  .getActiveSubscriptions({ account })
  .filter(subscription => subscription.topic === topic).scope

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 past messages for a given subscription​

// Will return all past Notify messages for the provided subscription topic, keyed by messageId.
const messageHistory = notifyClient.getNotificationHistory({
  topic,
  limit: 10,
  startingAfter: 'notification-id',
  unreadFirst: true
})

Marking notification as read​

// Will mark the 2 specific notifications as read
const messageHistory = notifyClient.markNotificationsAsRead({
  topic,
  notificationIds: ['notification-1', 'notification-2']
})