Unlocking the power of Verify API: A step-by-step guide for wallets

WalletConnect’s Verify API is an easy-to-implement security feature that can enable your wallet to help users engage in a safer web3 experience. We have already covered the steps to verify a domain here. Implementing Verify API in your wallet can help your users to better determine the legitimacy of the website they are trying to interact with, using relevant cues and messages you choose to provide. In this guide, I’ll walk you through a step-by-step tutorial on how to integrate Verify API, which should give you a clear and straightforward understanding of how you can distinguish requests more effectively.

What is Verify API?

Verify API is a security-focused feature that allows wallets to notify end users when they may be connecting to a suspicious or malicious domain, helping to prevent phishing attacks across the industry. By combining WalletConnect’s domain registry with industry-leading security tools like Blowfish and BlockAid, Verify API enables wallets to support their users in detecting potentially harmful connections.

The Verify security system discriminates session requests in four different cases.

Domain match: The domain linked to this request has been verified as this application's domain. This interface appears when the domain a user is attempting to connect to has been “verified” in our domain registry as the registered domain of the application. Furthermore, the domain has not been flagged as suspicious by either of the security tools we work with.
Unverified: The domain sending the request cannot be verified. This interface appears when the domain a user is attempting to connect to has not been verified in our domain registry. In this case, the domain has not been flagged as suspicious by either of the security tools we work with.
Mismatch: The application's domain doesn't match the sender of this request. This interface appears when the domain a user is attempting to connect to has been flagged as different from the one this application has verified in our domain registry. In this case, the domain has not been flagged as suspicious by either of the security tools we work with.

Along with these, an isScam field is exposed through verifyContext, which essentially clarifies if a domain is detected as Threat or not.

Threat: This domain is flagged as malicious and potentially harmful. This interface appears when the domain a user is attempting to connect to has been flagged as malicious on one or more of the security tools we work with.

This ensures that Verify API can better distinguish session requests based on their sender.

Implementation

To implement Verify API, we can take three platform-specific routes. In this tutorial, I’ll walk you through each one.

JavaScript (web/React Native)

Create a new file in your utils folder called utils/verify.ts. Use (.js) if you’re using JavaScript.

// utils/verify.js
import { Verify } from '@walletconnect/types''

export function getVerifyStatus(context?: Verify.Context) {
  if (!context) return ''
  switch (context.verified.validation) {
    case 'VALID':
      return '✅'
    case 'INVALID':
      return '❌'
    case 'UNKNOWN':
      return '❓'
    default:
      return ''
  }
}

Here, we have created a switch statement to check for each possible Verify response and return a custom message based on the status. We can customize this further by returning custom elements based on which response is parsed, like this:

// Custom tag for Verified Domains
const VerfiedTag = (): React.FC => {
  return (
    <div className="flex items-center gap-2">
      <CheckIcon />
      <span>Verified Domain</span>
    </div>
  );
};

...
  // Inside getVerifyStatus function
  case 'VALID': 
   return <VerfiedTag/>
...

Now, let’s import this function where we process other requests from Web3Wallet.

// authentication.js
import { getVerifyStatus } from '@/utils/verify'
...
web3wallet.on("auth_request", async (authRequest) => {
  const { id, params, verifyContext } = authRequest
  const validation = getVerifyStatus(verifyContext)
 const isScam = verifyContext.verified.isScam // true if the domain is flagged as malicious

  // if the domain is flagged as malicious, you can should warn the user as they may lose their funds - check the `Threat` case for more info
  if(isScam) {
    // show a warning screen to the user
    // and proceed only if the user accepts the risk
  }

  // 1. prompt the user to approve the auth request
  ...
    <p>{validation}</p>
  ...

  // 2. respond to the auth request
  await web3wallet.respondAuthRequest(...)
})

That’s all you need to do to verify a domain in your wallet! You could take this one step further and add more text or warnings for your users. Wasn’t that easy?

iOS (Swift)

With Swift, we can use the validation enum in VerifyContext to check for the authenticity of requests.

public struct VerifyContext: Equatable, Hashable {
   public enum ValidationStatus {
       case unknown
       case valid
       case invalid
   }

   public let origin: String?
   public let validation: ValidationStatus
   public let verifyUrl: String
}

The validation enum in VerifyContext specifies whether the origin is unknown, valid, or invalid with reference to a verifyURL server. Along with this, the origin of the request is also exposed through VerifyContext.

Android (Kotlin)

Similar to iOS, Wallet.Event.VerifyContext provides domain verification information about SessionProposal, SessionRequest , and AuthRequest.

data class VerifyContext(
    val id: Long,
    val origin: String,
    val validation: Model.Validation,
    val verifyUrl: String
)

enum class Validation {
    VALID, INVALID, UNKNOWN
}

The validation enum in VerifyContext specifies whether the origin is VALID, INVALID, or UNKNOWN, with reference to a verifyURL server. Along with this, the origin of the request is also exposed through VerifyContext.

End result

While overall implementations may differ, it should look something like the visual below once complete.

This example gives you a good idea of how the integration can look with JavaScript. The best part is, you can customize it to fit your wallet’s theme however you like.

For more information, check out our docs on Verify API.

Resources and examples

Verify API documentation
Verify API Implementation (with Web3Wallet Javascript): getVerifyStatus and displaying validation status to users
Live example (use with dapp example to test it out)
Demo malicious app (to test out the "Threat" screen for apps flagged as malicious)

Here’s to a more secure future for wallet users!

As you can see, integrating WalletConnect’s Verify API is rather straightforward, yet the impact on the user experience is significant.

Plus, Verify API’s four-level security system — categorizing session requests as Invalid, Unknown, Valid, and Threat based on their sender’s authenticity — empowers you to customize the cues and messages that you provide to users when they’re connecting to an app or signing a transaction. This gives you the flexibility to shape the UX for your users.

Verify API is a big step forward in the journey to making web3 more secure. As a wallet, you can make a big difference for your users by giving them the information that they need to protect themselves. As we say in this industry, don’t trust — verify.

With Verify API, we now can!

Build what's next.
Build with WalletConnect.

Get started