Skip to main content

Push Server

The Push Server sends WalletConnect protocol activity using FCM or APNs to users. The Push Server can be used with our WalletKit SDK.

Several options exist for setting up the Push Server:

  1. Using WalletConnect Cloud (recommended)
  2. Self-host the Push Server
  3. Write your own implementation using the spec

It is recommended that you use WalletConnect Cloud for simplicity and ease of integration. Typically you only need to self-host if you have concerns about our hosted platform having access to your FCM or APNs server credentials, such as for regulatory reasons. If you want to self-host or implement against the spec, please reach out to devrel@walletconnect.com for assistance.

Setup in WalletConnect Cloud​

  1. Create a Project in the Cloud App. Go to WalletConnect Cloud and sign up for an account.

  2. To get your project's Push URL, from the Cloud App, go into the settings tab and click on Create Push URL.

create-push-url

  1. From the same settings tab, you will see the FCM and the APNS settings becomes available to setup. Add your [FCM](#Firebase Cloud Messaging API (FCM v1)) and/or APNs details.

fmc-and-apns-details-form

Firebase Cloud Messaging API (FCM v1)​

info

If you already have FCM Legacy enabled and then enable FCM v1, push notifications will automatically be sent with the newer FCM v1 API automatically. No migration of devices/apps is necessary.

  • In your Firebase project settings, under Firebase Cloud Messaging API (V1), click the Manage Service Accounts link Manage service accounts link
  • You may use the default firebase-adminsdk service account, but we recommend making a new, minimally privileged, service account. Eg a ready-made role from Firebase Firebase Cloud Messaging API Admin would only give access to messaging and notifications:
    • Click the Create service account button Create service account button
    • Provide an arbitrary name and ID. E.g. WalletConnect Cloud Push Server and click Create and Continue Provide a name
    • Select the Firebase Cloud Messaging API Admin role and click Continue Select the Firebase Cloud Messaging API Admin role
    • Click Done
  • Next create keys for the service account by clicking on the ⋮ button next to the service account and selecting Manage keys
    Manage keys
    • Click Add key -> Create new key
      Create new key
    • Select JSON and click Create
    • A .json file containing the service account credentials will be automatically downloaded to your computer
  • Upload the credentaials JSON file to your Cloud project's FCM V1 settings and click Save

You should now see a green checkbox indicating that FCM V1 has been enabled! Now any clients that register themselves on the Push Server will receive FCM push notifications for relay messages to that client.

Cloud Messaging API (FCM Legacy)​

caution

FCM Legacy is deprecated and will be removed June 20, 2024. We strongly encourage you to setup FCM v1 (above) instead.

FCM legacy deprecated

When FCM v1 is enabled in WalletConnect Cloud, it will replace the use of the legacy FCM API. No migration of devices/apps is necessary.

Google's FCM allows you to use send notifications to both Android and Apple devices. At this time, we only support apps using the FCM client API.

Apple Push Notifications (APNs)​

Apple recommends using a Token-Based Connection for APNS over a Certificate-Based connection. Please refer to their documentation for instructions on obtaining either.