Pairing API

The Pairing API is a lightweight API for establishing an encrypted, protocol-agnostic communication layer between peers. Its purpose is to provide a secure channel for proposing protocols or sending requests between dapp and wallet.

Don't have a project ID?

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

Get started

Installation

Web

WalletConnect currently offers Sign and Auth SDKs. To allow a reusable communication channel between peers, the Pairing API exposes a standard interface and allows for sending and receiving multi-protocol requests over a single pairing.

Each SDK uses the same implementation of core/pairing (via @walletconnect/core) to manage pairings. To run multiple SDKs side-by-side (e.g. Sign and Auth), please refer to the [Sharing a Core instance] guide.

iOS

Add SDK for your project.

You can add a WalletConnect Core SDKs to your project with Swift Package Manager. In order to do that:

1. Open XCode
2. Go to File -> Add Packages
3. Paste the repo GitHub URL: https://github.com/WalletConnect/WalletConnectSwiftV2
4. Tap Add Package
5. Select WalletConnectPairing check mark

Android

Kotlin implementation of Android CoreClient for all WalletConnect SDKs. This SDK is developed in Kotlin and usable in both Java and Kotlin files.

Requirements

• Android min SDK 23
• Java 11

Installation

root/build.gradle.kts:

allprojects {
 repositories {
    mavenCentral()
    maven { url "https://jitpack.io" }
 }
}

app/build.gradle

implementation("com.walletconnect:android-core:release_version")

Project set up

To use initialize RelayClient properly you will need a projectId. Go to https://cloud.walletconnect.com/app, register your project and get projectId.

CoreClient initialization

Before using any of the WalletConnect Kotlin SDKs, it is necessary to initialize the CoreClient. The initialization of CoreClient must always happen in the Android Application class. Provide the projectId generated in the WalletConnect Cloud, the WebSocket URL, choose the connection type, and pass the application class. You can also pass your own Relay instance using the RelayConnectionInterface.

val projectId = "" //Get Project ID at https://cloud.walletconnect.com/
val relayUrl = "relay.walletconnect.com"
val serverUrl = "wss://$relayUrl?projectId=${projectId}"
val connectionType = ConnectionType.AUTOMATIC or ConnectionType.MANUAL
val application = //Android Application level class
[Optional] val optionalRelay: RelayConnectionInterface? = /*implement interface*/

CoreClient.initialize(relayServerUrl = serverUrl, connectionType = connectionType, application = application, relay = optionalRelay)

Using your own Relay instance

The CoreClient offers the ability to use a custom Relay client. Just creating an instance of RelayConnectionInterface and passing it to CoreClient.initialize.

...
val optionalRelay: RelayConnectionInterface = /*implement interface*/

CoreClient.initialize(relayServerUrl = serverUrl, connectionType = connectionType, application = application, relay = optionalRelay)

React Native

WalletConnect currently offers Sign and Auth SDKs. To allow a reusable communication channel between peers, the Pairing API exposes a standard interface and allows for sending and receiving multi-protocol requests over a single pairing.

Each SDK uses the same implementation of core/pairing (via @walletconnect/core) to manage pairings. To run multiple SDKs side-by-side (e.g. Sign and Auth), please refer to the [Sharing a Core instance] guide.

Unity

Install the WalletConnect.Core nuget package, which implements the Pairing API

dotnet add package WalletConnect.Core

Once the WalletConnect.Core library is installed, create a Metadata object. It will describe your application and define its appearance in a web browser. Then configure the Pair instance with a metadata object you have instantiated.

var metadata = new Metadata()
{
    Name = "my-app",
    Description = "My app description",
    Icons = new[] { "https://walletconnect.com/meta/favicon.ico" },
    Url = "https://walletconnect.com",
}

var options = new CoreOptions() 
{ 
    ProjectId = "...", 
    Name = "my-app", 
}

var core = new WalletConnectCore(options);
core.Pairing.Configure(metadata);

C#

tip

Since WalletConnectUnity is a wrapper around WalletConnectSharp, usage of the pairing API is identical to C#. Please refer to C# documentation on how to use Pairing inside WalletConnectUnity.

Install the WalletConnectUnity package from the GitHub repo

Once the WalletConnectUnity package is imported, create a new empty Game Object in your scene. This will hold the WalletConnectUnity component and other required components.

Inside the WalletConnectUnity component, you can configure the Metadata and other settings inside to the C# CoreOptions class.

With WalletConnectUnity configured, you can grab WalletConnectUnity.Instance.Core field to access the WalletConnectCore API.

void Start() 
{
  WalletConnectCore core = WalletConnectUnity.Instance.Core

  // ... 
}

info

WalletConnectUnity will automatically initialize the WalletConnectCore module as well as run core.Pairing.Configure(metadata). Therefore, no additional configuration is required. All settings, including Metadata, can be modified in the Unity Editor.

Usage

Web

The methods listed below are limited to only the public methods of the Pairing API that we recommend you interact with directly. For an exhaustive list, please refer to the spec and/or implementation linked under Useful Links above.

The keyword sdkClient is used here as a placeholder for any WalletConnect SDK that implements the Pairing API (e.g. signClient, authClient, etc).

 // Creates a new (inactive) pairing. Returns the URI for a peer to consume via `pair`, as well as the pairing topic.
const {topic, uri} = await sdkClient.core.pairing.create()

// Pair with a peer's proposed pairing, extracted from the provided `uri` parameter.
await sdkClient.core.pairing.pair({ uri: "wc:1b3eda3f4..." })

// Activate a previously created pairing (e.g. after the peer has paired), by providing the pairing topic.
await sdkClient.core.pairing.activate({ topic: "1b3eda3f4..." })

// Updates the expiry of an existing pairing, by providing the pairing topic and an `expiry` in seconds (e.g. `60` for one minute from now)
await sdkClient.core.pairing.updateExpiry({ topic: "1b3eda3f4...", expiry: 60 })

// Updates a pairing's metadata, by providing the pairing topic and the desired metadata.
await sdkClient.core.pairing.updateMetadata({ topic: "1b3eda3f4...", metadata: { name: "MyDapp", ... } })

// Returns an array of all existing pairings.
const pairings = sdkClient.core.pairing.getPairings()

// Pings a pairing's peer, by providing the pairing topic.
await sdkClient.core.pairing.ping({ topic: "1b3eda3f4..." })

// Disconnects/Removes a pairing, by providing the pairing topic.
await sdkClient.core.pairing.disconnect({ topic: "1b3eda3f4..." })

Listeners for pairing-related events

The Pairing API currently emits the following events:

• pairing_ping
• pairing_delete
• pairing_expire

Any of these events can be listened for via the standard Node EventEmitter interface:

sdkClient.core.pairing.events.on("pairing_delete", ({ id, topic }) => {
  // clean up after the pairing for `topic` was deleted.
});

iOS

Create an AppMetadata object. It will describe your application and define its appearance in a web browser.

Starting from WalletConnect SDK version 1.9.5, the redirect field in the AppMetadata object is mandatory. Ensure that the provided value matches your app's URL scheme to prevent redirection-related issues.

Then configure the Pair instance with a metadata object you have instantiated.

let metadata = AppMetadata(name: <String>,
                           description: <String>,
                           url: <String>,
                           icons: <[String]>,
                           redirect: AppMetadata.Redirect(native: "example://", universal: nil))

Pair.configure(metadata: metadata)

Pairing Wallet Usage

In pair wallet with dapp, the user needs to scan a QR code or open a deep link generated by dapp, then instantiate WalletConnectURI from the scanned QR code string and call the pair() function as follows.

let uri WalletConnectURI(string: <String>)
try! await Pair.instance.pair(uri: uri)

Now wallet and a dapp have a secure communication channel that will be used by top level APIs.

Pairing Dapp Usage

In order to pair dapp and a wallet, dapp needs to generate and share a uri with wallet. To generate a uri call create() function on Pair instance as follows.

let uri = try await Pair.instance.create()

Now you can share the uri with the wallet.

Android

Create Pairing

val pairing: Pairing? = CoreClient.Pairing.create() { error -> }

When first establishing a pairing with a Peer, call CoreClient.Pairing.create. This will try and generate a new pairing with a URI parameter that can be used to establish a connection with the other Peer as well as other meta data related to the pairing.

Pair Clients

val pairingParams = Core.Params.Pair(pairingUri)
CoreClient.Pairing.pair(pairingParams) { error -> }

To pair the wallet with the Dapp, call the CoreClient.Pairing's pair function which needs a Core.Params.Pair parameter. Core.Params.Pair is where the WC Uri will be passed.

Get List of Active Pairings

val listOfActivePairings: List<Core.Model.Pairing> = CoreClient.Pairing.getPairings()

To get a list of the most current active pairings, call CoreClient.Pairing.getPairings() which will return a list of type Core.Model.Pairing.

Disconnect a Pairing

CoreClient.Pairing.disconnect(topic = /*Pairing topic*/") { error -> }

To disconnect from a pairing, just pass the topic of the pairing to disconnect from (use getPairings() to get a list of all active pairings and their topics).

React Native

The methods listed below are limited to only the public methods of the Pairing API that we recommend you interact with directly. For an exhaustive list, please refer to the spec and/or implementation linked under Useful Links above.

The keyword sdkClient is used here as a placeholder for any WalletConnect SDK that implements the Pairing API (e.g. signClient, authClient, etc).

 // Creates a new (inactive) pairing. Returns the URI for a peer to consume via `pair`, as well as the pairing topic.
const {topic, uri} = await sdkClient.core.pairing.create()

// Pair with a peer's proposed pairing, extracted from the provided `uri` parameter.
await sdkClient.core.pairing.pair({ uri: "wc:1b3eda3f4..." })

// Activate a previously created pairing (e.g. after the peer has paired), by providing the pairing topic.
await sdkClient.core.pairing.activate({ topic: "1b3eda3f4..." })

// Updates the expiry of an existing pairing, by providing the pairing topic and an `expiry` in seconds (e.g. `60` for one minute from now)
await sdkClient.core.pairing.updateExpiry({ topic: "1b3eda3f4...", expiry: 60 })

// Updates a pairing's metadata, by providing the pairing topic and the desired metadata.
await sdkClient.core.pairing.updateMetadata({ topic: "1b3eda3f4...", metadata: { name: "MyDapp", ... } })

// Returns an array of all existing pairings.
const pairings = sdkClient.core.pairing.getPairings()

// Pings a pairing's peer, by providing the pairing topic.
await sdkClient.core.pairing.ping({ topic: "1b3eda3f4..." })

// Disconnects/Removes a pairing, by providing the pairing topic.
await sdkClient.core.pairing.disconnect({ topic: "1b3eda3f4..." })

Listeners for pairing-related events

The Pairing API currently emits the following events:

• pairing_ping
• pairing_delete
• pairing_expire

Any of these events can be listened for via the standard Node EventEmitter interface:

sdkClient.core.pairing.events.on("pairing_delete", ({ id, topic }) => {
  // clean up after the pairing for `topic` was deleted.
});

C#

Pairing Wallet Usage

When paring a wallet with a dapp, the user needs to scan a QR code or open a deep link generated by the dapp. Grab the string from the scanned QR code string or from the deep link and call the Pair() function as follows.

var uri = "...";
PairingStruct pairingData = await core.Pairing.Pair(uri);

Now the wallet and a dapp have a secure communication channel that will be used by top level APIs.

Pairing Dapp Usage

In order to pair dapp and a wallet, dapp needs to generate and share a uri with wallet. To generate a uri call create() function on Pair instance as follows.

var pairData = await core.Pairing.Create();
string topic = pairData.Topic;
string uri = pairData.Uri;

Now you can share the uri with the wallet either through a QR Code or by using a deep link.

Message Sending / Handling

Once a wallet and dapp has been paired, they can send messages securely to the pairing topic.

Requests can be received from the dapp by handling the message callback in the MessageHandler module.

core.MessageHandler.MessageEventHandler<MyRequest, MyResponse>()
    .FilterRequests(r => r.Topic == pairingData.Topic)
    .OnRequest +=
        async delegate(RequestEventArgs<MyRequest, MyResponse> eventArgs)
        {
            Console.WriteLine(eventArgs.Request);
            eventArgs.Response = new MyResponse()
            {
                // ...
            };
        };

A response can be sent for any request by setting the Response field in the eventArgs parameter.

Receiving responses is handled the same way, but instead of the OnRequest event you would use the OnResponse event.

Request, Responses and Errors can be sent using the SendRequest , SendResult and SendError functions in the MessageHandler module.

long id = await core.MessageHandler.SendRequest<MyRequest, MyResponse>(pairingTopic, data);