Connect with WalletConnect

Portal Connect utilizes your existing Portal instance to connect your Portal MPC Wallet to dApps via WalletConnect. When connecting via Portal Connect, a few things happen in the background:

You provide a WalletConnect uri for Portal Connect to connect with
Portal Connect opens a WebSocket connection to the WalletConnect uri
All requests received over the WebSocket are routed to portal.provider to perform the request like normal

This workflow allows for seamless integration between your Portal MPC Wallet and countless dApps that already include support for WalletConnect.

Installing

The PortalConnect class is including in the PortalSwift pod, so no additional steps are required to start using PortalConnect in your app. In the ViewController that segues to your ConnectViewController, you’ll need to set the Portal instance on the destination ViewController.

override func prepare(for segue: UIStoryboardSegue, sender: Any?) {
    if let connectViewController = segue.destination as? ConnectViewController {
        connectViewController.portal = self.portal
    }
}

Initializing PortalConnect

To initialize Portal Connect, call portal.createPortalConnectInstance().

import PortalSwift

class ConnectViewController: UIViewController {
  private var connect: PortalConnect?
  public var portal: Portal?


  // UI Elements
  @IBOutlet weak var connectButton: UIButton!
  @IBOutlet weak var addressTextInput: UITextField!

  override func viewDidLoad() {
    super.viewDidLoad()

    connectButton.isEnabled = false
    connect = portal.createPortalConnectInstance()
  }

Connecting via WalletConnect

To connect to a WalletConnect URI, using the mechanism that makes the most sense for your app, capture the WalletConnect URI. The most common practice is to use a QR Code scanner for this. Once you’ve captured the URI, you can call the connect(uri) function on your PortalConnect instance. This will initialize the WebSocket session with the WalletConnect relay and begin passing messages to your Portal Provider using your Portal MPC Wallet.

@IBAction func connectPressed() {
    let uri = addressTextInput.text
    connect?.connect(uri!)
}

Listen for the connect and disconnect events to get confirmation that you have successfully connected or if the user disconnects.

connect.on(event: Events.Connect.rawValue) { (data: Any) in }

connect.on(event: Events.Disconnect.rawValue) { (data: Any) in }

Once this is done, you’ve got a connection to WalletConnect. All messages sent by the relay will now be processed by the Portal Provider.

Wallet Connect’s Auth API is not currently supported. We have it on our roadmap. Please reach out if this is an urgent feature request.

Handling Session Requests

Session Requests represent the initial connection request from the dApp to create a new session. These are triggered when Portal responds to the dApp after the connect(uri) function is called. These events will be triggered with either a SessionProposal object. These objects can be used to display information about the dApp the user is connecting to and the specific permissions being requested by the dApp.

Accepting the dApps proposal

We have a helper method addChainsToProposal . This can be used to add all the chains in your gateway config to the proposal object.

Binding to Session Requests

In order to bind to Session Requests, add an event handler to your PortalConnect instance.

connect.on("portal_dappSessionRequested") { data in
    // ... your business logic

    if (approved) {
        if var connectData = data as? ConnectData {
          var newConnectData = portalConnect.addChainsToProposal(data: connectData)

          portalConnect.emit(event: Events.PortalDappSessionApproved.rawValue, data: newConnectData)
        } else {
          print("Invalid data type. Expected ConnectData.")
        }
    } else {
        connect.emit("portal_dappSessionRejected", data)
    }
}

Retrieve Session Request

Portal stores session requests for up to 24 hours. This feature can be useful if PortalConnect loses connection with the dApp being used and you want to respond to previous session requests. To retrieve a previous session request, use the emitGetSessionRequest method. You will need to provide both the requestId and the topic.

portalConnect.emitGetSessionRequest(
    requestId: "requestId",
    topic: "topic"
)

Important Notes:

You can only respond to a session request once.
Ensure you have stored the correct requestId and topic values to successfully retrieve the session request.

This functionality helps maintain continuity in dApp interactions by allowing you to handle any outstanding session requests even after a connection disruption.

Handle Signing

Each portal connect instance gets created with its own instance of the Portal Provider. This allows users to connect with different chains to different dApps.

Listen for signing events

Handle signing approval. This is only required if autoApprove is turned off.

portalConnect.on(event: Events.PortalSigningRequested.rawValue) { (data: Any) in }

Listen for confirmation of signing requests

portalConnect.on(event: Events.PortalSignatureReceived.rawValue) { (data: Any) in }

Handle Warnings and Errors

Set up a listener for portal_connectError in order to handle specific errors and warnings from Portal Connect. Check out our Portal Connect Error Codes here.

Handling connection errors

The listener receives an ErrorData whose params is a ConnectError with a message and a code.

connect?.on(event: Events.ConnectError.rawValue) { data in
    guard let error = data as? ErrorData else { return }

    switch error.params.code {
    case 401:
        // The credential was rejected. Terminal — see below.
        promptSignIn()
    default:
        // Transport failure, or reconnect attempts exhausted.
        showRetryButton()
    }
}

Starting in 8.0.0, a dropped connection reconnects on its own, with exponential backoff, up to five attempts (500 ms, growing to a ceiling of 8 s). This also covers a proxy that cannot be reached at all. If all five fail, PortalConnect gives up and emits a ConnectError with code 500 and a message of "Reconnect attempts exhausted". Nothing reconnects after that — call connect(uri) again yourself if you want to keep trying. The attempt counter resets once the proxy confirms the connection, not when the socket opens. A server that completes the upgrade and then immediately drops the connection therefore still reaches the five-attempt ceiling rather than retrying indefinitely. disconnect(), close(), and a new connect(uri) cancel a reconnect that is waiting out its backoff, so a session you ended is not reopened when the delay elapses.

A 401 on the WebSocket upgrade is terminal. Retrying with the same credential can only fail the same way, so PortalConnect emits a ConnectError with code 401 and stops — it does not attempt any of the five reconnects. Under Client Auth the rejection also ends the session and fires onSessionInvalidated on the Portal the credential belongs to. Sign in again and build a new PortalConnect from the new Portal rather than calling connect(uri) again.

Switching Chains

In order to switch the active chain for a portal connect instance use the setChainId method.

You must include that chainId in the gateway config with a gateway url on initialization of your Portal Object, otherwise, you can not switch chains.

connect.setChainId(137) // switches the active chain to polygon mainnet

The final ConnectViewController class

Once you’ve gone through that process, you should have a file that looks something like this.

import PortalSwift

class ConnectViewController: UIViewController {
  private var connect: PortalConnect?
  public var portal: Portal?


  // UI Elements
  @IBOutlet weak var connectButton: UIButton!
  @IBOutlet weak var addressTextInput: UITextField!

  override func viewDidLoad() {
    super.viewDidLoad()

    connectButton.isEnabled = false
    connect = PortalConnect(portal!)
  }

  @IBAction func connectPressed() {
    let uri = addressTextInput.text
    connect?.connect(uri!)
  }

  connect.on("portal_dappSessionRequested") { data in
      // ... your business logic

      if (approved) {
          connect.emit("portal_dappSessionApproved", data)
      } else {
          connect.emit("portal_dappSessionRejected", data)
      }
  }

  @IBAction func uriChanged(_ sender: Any) {
    let uri = addressTextInput.text

    connectButton.isEnabled =
      uri != nil
      && uri?.isEmpty == false
      && uri?.starts(with: "wc:") == true
  }
}

Getting Started

SDKs

APIs

Integrations

Resources

Connect with WalletConnect

Installing

Initializing PortalConnect

Connecting via WalletConnect

Handling Session Requests

Accepting the dApps proposal

Binding to Session Requests

Retrieve Session Request

Handle Signing

Listen for signing events

Handle Warnings and Errors

Handling connection errors

Switching Chains

The final ConnectViewController class

​Installing

​Sharing the Portal instance with your ConnectViewController

​Initializing PortalConnect

​Connecting via WalletConnect

​Handling Session Requests

​Accepting the dApps proposal

​Binding to Session Requests

​Retrieve Session Request

​Handle Signing

​Listen for signing events

​Handle Warnings and Errors

​Handling connection errors

​Switching Chains

​The final ConnectViewController class

Installing

Sharing the Portal instance with your ConnectViewController

Initializing PortalConnect

Connecting via WalletConnect

Handling Session Requests

Accepting the dApps proposal

Binding to Session Requests

Retrieve Session Request

Handle Signing

Listen for signing events

Handle Warnings and Errors

Handling connection errors

Switching Chains

The final ConnectViewController class