walletconnect-notify

WalletConnect Notify API

• Name: WalletConnect Notify API
• URL: https://github.com/WalletConnect/walletconnect-specs/blob/main/docs/specs/clients/notify/README.md
• Category: wallet-to-dapp notification protocol / scoped push-subscription middleware / DID-web-discovered relay messaging layer
• Summary: WalletConnect Notify is a scoped notification branch off the WalletConnect stack, not a general messaging network. What matters is app identity discovery, notification-type scoping, topic derivation, long-lived subscription state, and who gets to deliver which messages to a wallet.
• What it does:
  • Lets wallet users subscribe to app-defined notification types such as promotional, transactional, private, or alerts instead of granting one undifferentiated notification permission
  • Uses did:web discovery and X25519 key material so wallets can derive request, response, and long-lived notify topics without visiting the dapp directly
  • Authenticates subscription, update, delete, watch, and message flows with DID JWTs tied to client identity keys, dapp authentication keys, and Notify Server authentication keys
  • Defines relay-based methods for subscription lifecycle management, notification delivery, notification retrieval, and marking notifications as read
  • Adds watcher semantics so wallets can keep subscription state synchronized and receive wc_notifySubscriptionsChanged updates, with explicit timeout and refresh behavior
  • Supports both cloud-hosted config lookup and a more decentralized .well-known/wc-notify-config.json path for exposing app metadata and available notification types
• Key claims:
  • The overview spec says Notify allows wallet users to register subscriptions for blockchain, application, or off-chain events relevant to the user, which is already a broader and more structured role than ordinary OS push notifications.
  • The most important design move is the split between app identity and user consent. Wallets discover app keys from did:web, while users separately authorize a scoped set of notification types through the scp claim instead of granting blanket message rights.
  • The subscription flow is a real protocol surface, not just a webhook. The spec derives request, response, and notify topics from X25519 key exchange material and hashes, which makes routing and long-lived delivery part of the design rather than implementation trivia.
  • Authentication is layered and role-specific. The spec distinguishes client identity keys, dapp authentication keys, and Notify Server authentication keys, which makes sender identity and trust boundaries more explicit than a simple app-server push model.
  • The watcher model is analytically useful because it reveals that subscription state is not static. Wallets must periodically refresh watchers, receive full-state updates rather than deltas, and treat long-lived notification access as an actively maintained relationship.
  • The .well-known/wc-notify-config.json format and notification-type schema matter because they make message taxonomy, app metadata, and consent scope part of the protocol’s public control surface rather than something hidden inside one vendor dashboard.
  • WalletConnect Notify belongs in the corpus because it turns “wallet notifications” into a comparison-ready stack: app discovery, public-key publication, JWT-authenticated subscription rights, scoped message classes, relay delivery, state watchers, and notification archive/read-state APIs.
• Whitepaper: No standalone WalletConnect Notify whitepaper or litepaper surfaced in this pass. The clearest primary materials were the Notify spec documents and config/authentication references collected in ../whitepapers/walletconnect-notify-primary-sources-2026-05-12.md.
• Sources:
  • https://github.com/WalletConnect/walletconnect-specs/blob/main/docs/specs/clients/notify/README.md
  • https://raw.githubusercontent.com/WalletConnect/walletconnect-specs/main/docs/specs/clients/notify/README.md
  • https://raw.githubusercontent.com/WalletConnect/walletconnect-specs/main/docs/specs/clients/notify/notify-subscription.md
  • https://raw.githubusercontent.com/WalletConnect/walletconnect-specs/main/docs/specs/clients/notify/authentication.md
  • https://raw.githubusercontent.com/WalletConnect/walletconnect-specs/main/docs/specs/clients/notify/notify-config.md
  • https://raw.githubusercontent.com/WalletConnect/walletconnect-specs/main/docs/specs/clients/notify/rpc-methods.md

Internal linkages

• Keep the budget tight.
• Best anchors: walletconnect, walletconnect-auth, and push-protocol.

Control surface

• The real leverage sits in app key publication, consent scopes, watcher refresh, relay delivery, and wallet-side retrieval defaults.

• Useful because it makes wallet notifications legible as policy and routing infrastructure instead of as a vague push feature.

• Last reviewed: 2026-05-26 UTC