WalletConnect Chat Integration

WalletConnect Chat Integration

WalletConnect Chat (renamed to WalletConnect Notify / Push — part of the WalletConnect v2 ecosystem) is a protocol for encrypted peer-to-peer messaging between wallets. Unlike XMTP or Push Protocol, the Chat API is integrated directly into the WalletConnect SDK, which simplifies adding messaging to a dApp that already uses WalletConnect for wallet connection.

What it is and why you need it

Main use case: a dApp wants to send notifications to users directly in their wallet (MetaMask, Rainbow, Coinbase Wallet), without email or phone number. Examples:

• A DeFi protocol notifies about approaching liquidation
• An NFT marketplace announces a new offer on a token
• A DAO notifies about a new proposal

Second use case: wallet-to-wallet messaging — users communicate using ENS names or wallet addresses as identifiers.

Setting up WalletConnect Notify

import { NotifyClient } from "@walletconnect/notify-client";

const notifyClient = await NotifyClient.init({
  projectId: process.env.NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID,
  relayUrl: "wss://relay.walletconnect.com",
  logger: "error",
});

// Subscribe a wallet to notifications from the dApp
const subscription = await notifyClient.subscribe({
  appDomain: "yourdapp.com",
  account: `eip155:1:${walletAddress}`, // CAIP-10 format
});

For a dApp to send notifications, domain verification through the WalletConnect Cloud Dashboard is required — place a .well-known/walletconnect.txt file.

Sending notifications from the backend

Notifications are sent through the WalletConnect REST API, not through the client SDK:

// Backend: send notification
async function sendNotification(
  account: string,
  type: string,
  title: string,
  body: string,
  url?: string
) {
  const response = await fetch(
    `https://notify.walletconnect.com/${projectId}/notify`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${process.env.WALLETCONNECT_NOTIFY_SECRET}`,
      },
      body: JSON.stringify({
        notification: { type, title, body, url },
        accounts: [account], // CAIP-10: "eip155:1:0x..."
      }),
    }
  );
  
  return response.json();
}

// Example: liquidation risk notification
await sendNotification(
  `eip155:1:${userAddress}`,
  "liquidation-warning",
  "Liquidation Risk",
  `Your position is approaching the liquidation threshold. Health factor: 1.05`,
  "https://yourdapp.com/position/123"
);

Notification types

Notification types are registered in WalletConnect Cloud and displayed to users as categories they can enable/disable:

{
  "types": [
    {
      "name": "Liquidation Warning",
      "description": "Warnings about approaching liquidation",
      "id": "liquidation-warning"
    },
    {
      "name": "New Offer",
      "description": "New offers on your NFTs",
      "id": "new-offer"
    },
    {
      "name": "Governance",
      "description": "New proposals for voting",
      "id": "governance"
    }
  ]
}

Receiving and displaying notifications in a dApp

import { useNotifications } from "@walletconnect/notify-react";

function NotificationBell() {
  const { address } = useAccount();
  const { data: notifications } = useNotifications({
    account: address ? `eip155:1:${address}` : undefined,
  });
  
  const unreadCount = notifications?.filter(n => !n.isRead).length ?? 0;
  
  return (
    <div>
      <BellIcon />
      {unreadCount > 0 && <Badge>{unreadCount}</Badge>}
    </div>
  );
}

Alternatives and comparison

WalletConnect Notify is not the only option. The choice depends on your requirements:

For most dApps, I recommend WalletConnect Notify if you're already using WC for connection — minimal additional work. For rich messaging (chat, files, group channels) — XMTP.