Usage - Reown Docs

Overview

WalletConnect makes distributing your Web wallet (such as Safe, Abstract Global Wallet, and many more) much faster. By integrating the WalletKit SDK, your web wallet will be able to connect to any dApp that supports WalletConnect and will be available in the list of wallets on both WalletConnect, Reown AppKit, and others.

Web Wallet in Reown AppKit & WalletButtons

Additionally, you don’t need to build SDKs in native languages such as Swift, Kotlin, Flutter, Unity, or React Native. This means your wallet can be available not just for web dApps, but also for native dApps, all from a single codebase. This section provides instructions on how to initialize the WalletKit client, approve sessions with supported namespaces, and respond to session requests, enabling easy integration of Web3 wallets with dApps through a simple and intuitive interface.

User Experience

Default Integration

This integration automatically opens a new web wallet tab when a user clicks “Connect” in a dApp. The wallet handles the WalletConnect URI automatically, meaning users don’t need to manually copy and paste the URI. This provides a seamless, one-click connection experience.

Abstract Global Wallet to Wolfswap

QR Code Integration

This integration only handles the session proposal and approval via the WalletConnect QR code. The user will need to manually copy and paste the WalletConnect URI into the wallet.

Safe Wallet Connecting to AppKit Lab

Cloud Configuration

Create a new project on Reown Dashboard at https://dashboard.reown.com and obtain a new project ID.

Don’t have a project ID?Head over to Reown Dashboard and create a new project now!

Get started

Initialization

Create a new instance from Core and initialize it with a projectId created from installation. Next, create WalletKit instance by calling init on walletKit. Passing in the options object containing metadata about the app and an optional relay URL.

Make sure you initialize walletKit globally and use the same instance for all your sessions. For React-based apps, you can initialize it in the root component and export it to use in other components.

import { Core } from "@walletconnect/core";
import { WalletKit } from "@reown/walletkit";

const core = new Core({
  projectId: process.env.PROJECT_ID,
});

const walletKit = await WalletKit.init({
  core, // <- pass the shared `core` instance
  metadata: {
    name: "Demo app",
    description: "Demo Client as Wallet/Peer",
    url: "https://reown.com/walletkit",
    icons: [],
  },
});

Starting from newer versions of WalletKit, Core instances are shared globally by default to optimize resource usage. This means that multiple Core instances with the same configuration will reuse the same underlying Core. For parallel testing scenarios where you need isolated Core instances, you have two options:

Option 1: Use customStoragePrefix

const core = new Core({
  projectId: process.env.PROJECT_ID,
  customStoragePrefix: `test-${Date.now()}`, // Unique prefix for each test
});

Don’t use randomly generated customStoragePrefix in production - this will cause the client to create new storage each time it is initialized. The client will not be able to persist/read existing data and all existing sessions will be lost after each reload.

// Set environment variable before initializing Core
process.env.DISABLE_GLOBAL_CORE = "true";

const core = new Core({
  projectId: process.env.PROJECT_ID,
});

The global Core sharing behavior was introduced to prevent resource waste when multiple SDK instances are created. If you’re running parallel tests and experiencing cross-test interference, use one of the solutions above to ensure proper test isolation.

Session

A session is a connection between a dapp and a wallet. It is established when a user approves a session proposal from a dapp. A session is active until the user disconnects from the dapp or the session expires.

Handling Session Proposals

You can connect your web wallet to a dApp in three ways:

Retrieve the WC URI from the dApp via query parameters
Implement a scanner to read the WC URI from a WalletConnect QR code
Allow users to manually enter the WC URI in an input field

When opening the wallet directly from the dApp, the WC_URI will be in the following format in the query parameters:

{YOUR_WALLET_URL}/wc?uri={WC_URI}

We recommend closing the web wallet tab after the user approves the request and redirecting back to the dApp. For web requests, redirect to the original browser tab, and for mobile requests, redirect to the native mobile dApp.

To test your web wallet connection flow, use our Appkit Laboratory by adding a custom wallet with your web wallet URL.

Handling Session Requests

When a dApp sends a session request to your wallet, the request will be available in the following format in the query parameters:

{YOUR_WALLET_URL}/wc?requestId={requestId}&sessionTopic={session.Topic}

This format allows your wallet to identify both the specific request and the session it belongs to.

To test your web wallet connection flow, use our Appkit Laboratory by adding a custom wallet with your web wallet URL.

Handling Redirects

When handling redirects after session approval or request completion, you should:

For web dApps:
- Redirect back to the original browser tab using window.opener.location.href
- Close the current wallet tab using window.close()
For native dApps:
- Check the peer metadata for a redirect URL in the session proposal
- If available, use deep linking to redirect to the native app
- If no redirect URL is found, display a “Return to App” message to the user

Example implementation:

function handleRedirect(session) {
  // Check if this is a native app
  const isNativeApp = session.peer.metadata.redirect !== undefined;
  
  if (isNativeApp) {
    // Redirect to native app if URL is available
    if (session.peer.metadata.redirect) {
      window.location.href = session.peer.metadata.redirect;
    } else {
      // Show "Return to App" message
      showReturnToAppMessage();
    }
  } else {
    // For web dApps, redirect back to original tab
    if (window.opener) {
      window.opener.location.href = session.peer.metadata.url;
      window.close();
    }
  }
}

Namespace Builder

With WalletKit (and @walletconnect/utils) we’ve published a helper utility that greatly reduces the complexity of parsing the required and optional namespaces. It accepts as parameters a session proposal along with your user’s chains/methods/events/accounts and returns ready-to-use namespaces object.

// util params
{
  proposal: ProposalTypes.Struct; // the proposal received by `.on("session_proposal")`
  supportedNamespaces: Record< // your Wallet's supported namespaces
    string, // the supported namespace key e.g. eip155
    {
      chains: string[]; // your supported chains in CAIP-2 format e.g. ["eip155:1", "eip155:2", ...]
      methods: string[]; // your supported methods e.g. ["personal_sign", "eth_sendTransaction"]
      events: string[]; // your supported events e.g. ["chainChanged", "accountsChanged"]
      accounts: string[] // your user's accounts in CAIP-10 format e.g. ["eip155:1:0x453d506b1543dcA64f57Ce6e7Bb048466e85e228"]
      }
  >;
};

Example usage

// import the builder util
import { WalletKit, WalletKitTypes } from '@reown/walletkit'
import { buildApprovedNamespaces, getSdkError } from '@walletconnect/utils'

async function onSessionProposal({ id, params }: WalletKitTypes.SessionProposal){
  try{
    // ------- namespaces builder util ------------ //
    const approvedNamespaces = buildApprovedNamespaces({
      proposal: params,
      supportedNamespaces: {
        eip155: {
          chains: ['eip155:1', 'eip155:137'],
          methods: ['eth_sendTransaction', 'personal_sign'],
          events: ['accountsChanged', 'chainChanged'],
          accounts: [
            'eip155:1:0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb',
            'eip155:137:0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb'
          ]
        }
      }
    })
    // ------- end namespaces builder util ------------ //

    const session = await walletKit.approveSession({
      id,
      namespaces: approvedNamespaces
    })
  }catch(error){
    // use the error.message to show toast/info-box letting the user know that the connection attempt was unsuccessful
    ....
    await walletKit.rejectSession({
      id: proposal.id,
      reason: getSdkError("USER_REJECTED")
    })
  }
}


walletKit.on('session_proposal', onSessionProposal)

If your wallet supports multiple namespaces e.g. eip155,cosmos & near Your supportedNamespaces should look like the following example.

// ------- namespaces builder util ------------ //
const approvedNamespaces = buildApprovedNamespaces({
    proposal: params,
    supportedNamespaces: {
        eip155: {...},
        cosmos: {...},
        near: {...}
    },
});
// ------- end namespaces builder util ------------ //

Get Active Sessions

You can get the wallet active sessions using the getActiveSessions function.

const activeSessions = walletKit.getActiveSessions();

EVM methods & events

In @walletconnect/ethereum-provider, (our abstracted EVM SDK for apps) we support by default the following Ethereum methods and events:

{
  //...
  methods: [
    "eth_accounts",
    "eth_requestAccounts",
    "eth_sendRawTransaction",
    "eth_sign",
    "eth_signTransaction",
    "eth_signTypedData",
    "eth_signTypedData_v3",
    "eth_signTypedData_v4",
    "eth_sendTransaction",
    "personal_sign",
    "wallet_switchEthereumChain",
    "wallet_addEthereumChain",
    "wallet_getPermissions",
    "wallet_requestPermissions",
    "wallet_registerOnboarding",
    "wallet_watchAsset",
    "wallet_scanQRCode",
    "wallet_sendCalls",
    "wallet_getCallsStatus",
    "wallet_showCallsStatus",
    "wallet_getCapabilities",
  ],
  events: [
    "chainChanged",
    "accountsChanged",
    "message",
    "disconnect",
    "connect",
  ]
}

Session Approval

The session_proposal event is emitted when a dapp initiates a new session with a user’s wallet. The event will include a proposal object with information about the dapp and requested permissions. The wallet should display a prompt for the user to approve or reject the session. If approved, call approveSession and pass in the proposal.id and requested namespaces. The pair method initiates a WalletConnect pairing process with a dapp using the given uri (QR code from the dapps). To learn more about pairing, checkout out the docs.

walletKit.on(
  "session_proposal",
  async (proposal: WalletKitTypes.SessionProposal) => {
    const session = await walletKit.approveSession({
      id: proposal.id,
      namespaces,
    });
  }
);
await walletKit.pair({ uri });

🛠️ Usage examples

⚠️ Expected Errors

No matching key. proposal id doesn't exist: 1

This rejection means the SDK can’t find a record with the given proposal.id - in this example 1. This can happen when the proposal has expired (by default 5 minutes) or if you attempt to respond to a proposal that has already been approved/rejected. If you are seeing this error, please make sure that you are calling approveSession with the correct proposal.id that is available within the proposal payload.

Error: Missing or invalid. approve(), namespaces should be an object with data

This error means that the namespaces parameter passed to approveSession is either missing or invalid. Please check that you are passing a valid namespaces object that satisfies all required properties.

Non conforming namespaces. approve() namespaces <property> don't satisfy required namespaces.

This error indicates that some value(s) in your namespaces object do not satisfy the required namespaces requested by the dapp. To provide additional guidance, the message might include info about the exact property that is missing or invalid e.g. Required: eip155:1 Approved: eip155:137. Please check CAIP-25 to familiarize yourself with the standard and it’s nuances. Additionally, we highly recommend you to use our namespace builder utility that would greatly simplify the process of parsing & building a valid namespaces object.

Session Rejection

In the event you want to reject the session proposal, call the rejectSession method. The getSDKError function comes from the @walletconnect/utils library.

walletKit.on(
  "session_proposal",
  async (proposal: WalletKitTypes.SessionProposal) => {
    await walletKit.rejectSession({
      id: proposal.id,
      reason: getSdkError("USER_REJECTED_METHODS"),
    });
  }
);

🛠️ Usage examples

⚠️ Expected Errors

No matching key. proposal id doesn't exist: 1

This rejection means the SDK can’t find a record with the given proposal.id - in this example 1. This can happen when the proposal has expired (by default 5 minutes) or if you attempt to respond to a proposal that has already been approved/rejected. If you are seeing this error, please make sure that you are calling rejectSession with the correct proposal.id that is available within the proposal payload.

Error: Missing or invalid. reject() reason:

This rejection means the reason parameter passed to rejectSession is either missing or invalid. We recommend using the getSDKError function from the @walletconnect/utils library that will populate & format the parameter for you.

Responding to Session requests

The session_request event is emitted when the SDK received a request from the peer and it needs the wallet to perform a specific action, such as signing a transaction. The event contains a topic and a request object, which will vary depending on the action requested. To respond to the request, you can access the topic and request object by destructuring them from the event payload. To see a list of possible request and response objects, refer to the relevant JSON-RPC Methods for Ethereum, Solana, Cosmos, or Stellar. As an example, if the dapp requests a personal_sign method, you can extract the params array from the request object. The first item in the array is the hex version of the message to be signed, which can be converted to UTF-8 and assigned to a message variable. The second item in params is the user’s wallet address. To sign the message, you can use your wallet’s signMessage method and pass in the message. The signed message, along with the id from the event payload, can then be used to create a response object, which can be passed into respondSessionRequest.

walletKit.on(
  "session_request",
  async (event: WalletKitTypes.SessionRequest) => {
    const { topic, params, id } = event;
    const { request } = params;
    const requestParamsMessage = request.params[0];

    // convert `requestParamsMessage` by using a method like hexToUtf8
    const message = hexToUtf8(requestParamsMessage);

    // sign the message
    const signedMessage = await wallet.signMessage(message);

    const response = { id, result: signedMessage, jsonrpc: "2.0" };

    await walletKit.respondSessionRequest({ topic, response });
  }
);

To reject a session request, the response should be similar to this.

const response = {
  id,
  jsonrpc: "2.0",
  error: {
    code: 5000,
    message: "User rejected.",
  },
};

🛠️ Usage examples

⚠️ Expected Errors

Error: No matching key. session topic doesn't exist: 'xyz...'

This rejection means the SDK can’t find a session with the given topic - in this example xyz.... This can happen when the session has been disconnected by either the wallet or the dapp while the session request was being processed or if a session with such topic doesn’t exist. If you are seeing this error, please make sure that you are using a correct topic that is available within the request payload.

Error: Missing or invalid. respond() response:

This rejection means the response parameter passed to respondSessionRequest is either missing or invalid. The response should be a valid JSON-RPC 2.0 response object. We recommend you to use our formatJsonRpcResult utility from "@walletconnect/jsonrpc-utils" that will format the response for you. Example usage: id argument being the request id from the request payload.

import { formatJsonRpcResult } from "@walletconnect/jsonrpc-utils";

const signature = await cryptoWallet.signTransaction(signTransaction);
const response = await walletKit.respondSessionRequest({
  topic: session.topic,
  response: formatJsonRpcResult(id, signature),
});

Updating a Session

If you wish to include new accounts or chains or methods in an existing session, updateSession allows you to do so. You need pass in the topic and a new Namespaces object that contains all of the existing namespaces as well as the new data you wish to include. After you update the session, the other peer will receive a session_update event. An example adding a new account to an existing session:

const namespaces = session.namespaces;
const accounts = [
  "eip155:1:0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb",
  "eip155:1:0x1234567890123456789012345678901234567890",
];
const updatedNamespaces = {
  ...namespaces,
  eip155: {
    ...namespaces.eip155,
    accounts,
  },
};
const { acknowledged } = await walletKit.updateSession({
  topic: session.topic,
  namespaces: updatedNamespaces,
});
// If you wish to be notified when the dapp acknowledges the update.
// note that if the dapp is offline `acknowledged` will not resolve until it comes back online
await acknowledged();

An example adding a new chain to an existing session:

const namespaces = session.namespaces;
const chains = ["eip155:1", "eip155:137"];
const accounts = [
  "eip155:1:0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb",
  "eip155:137:0x1234567890123456789012345678901234567890",
];
const updatedNamespaces = {
  ...namespaces,
  eip155: {
    ...namespaces.eip155,
    accounts,
    chains,
  },
};
await walletKit.updateSession({
  topic: session.topic,
  namespaces: updatedNamespaces,
});

🛠️ Usage examples

⚠️ Expected Errors

Note that all namespaces validation applies and you still have to satisfy the required namespaces requested by the dapp.

Error: No matching key. session topic doesn't exist: 'xyz...'

This rejection means the SDK can’t find a session with the given topic - in this example xyz.... This can happen when the session you’re trying to update has already been disconnected by either the wallet or the dapp or if a session with such topic doesn’t exist. If you are seeing this error, please make sure that you are using a correct topic of an active session.

Error: Missing or invalid. update(), namespaces should be an object with data

This error means that the namespaces parameter passed to updateSession is either missing or invalid. Please check that you are passing a valid namespaces object that satisfies all required properties.

Non conforming namespaces. update() namespaces <property> don't satisfy required namespaces.

Extending a Session

Sessions have a default expiry of 7 days. To extend a session by an additional 7 days, call .extendSession method and pass in the topic of the session you wish to extend.

const { acknowledged } = await walletKit.extendSession({ topic });
// if you wish to be notified when the dapp acks the extend
// note that if the dapp is offline `acknowledged` will not resolve until it comes back online
await acknowledged();

🛠️ Usage examples

in integration tests

⚠️ Expected Errors

Error: No matching key. session topic doesn't exist: 'xyz...'

Session Disconnect

To initiate disconnect from a session(think session delete), call .disconnectSession by passing a topic & reason for the disconnect. The other peer will receive a session_delete and be notified that the session has been disconnected.

NoteIt’s important that you’re subscribed to the session_delete event as well, to be notified when the other peer initiates a disconnect.

We recommend using the getSDKError utility function, that will provide ready-to-use reason payloads and is available in the @walletconnect/utils library.

await walletKit.disconnectSession({
  topic,
  reason: getSdkError("USER_DISCONNECTED"),
});

🛠️ Usage examples

in integration tests

⚠️ Expected Errors

Error: No matching key. session topic doesn't exist: 'xyz...'

Emitting Session Events

To emit session events, call the emitSessionEvent and pass in the params. If you wish to switch to chain/account that is not approved (missing from session.namespaces) you will have to update the session first. In the following example, the wallet will emit session_event that will instruct the dapp to switch the active accounts.

await walletKit.emitSessionEvent({
  topic,
  event: {
    name: "accountsChanged",
    data: ["0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb"],
  },
  chainId: "eip155:1",
});

In the following example, the wallet will emit session_event when the wallet switches chains.

await walletKit.emitSessionEvent({
  topic,
  event: {
    name: "chainChanged",
    data: 1,
  },
  chainId: "eip155:1",
});

Cloud

​Overview

​User Experience

​Default Integration

​QR Code Integration

​Cloud Configuration

Get started

​Initialization

​Core Instance Sharing

​Option 1: Use customStoragePrefix

​Option 2: Disable global Core sharing

​Session

​Handling Session Proposals

​Handling Session Requests

​Handling Redirects

​Namespace Builder

​Get Active Sessions

​EVM methods & events

​Session Approval

​🛠️ Usage examples

​⚠️ Expected Errors

​Session Rejection

​🛠️ Usage examples

​⚠️ Expected Errors

​Responding to Session requests

​🛠️ Usage examples

​⚠️ Expected Errors

​Updating a Session

​🛠️ Usage examples

​⚠️ Expected Errors

​Extending a Session

​🛠️ Usage examples

​⚠️ Expected Errors

​Session Disconnect

​🛠️ Usage examples

​⚠️ Expected Errors

​Emitting Session Events

Overview

User Experience

Default Integration

QR Code Integration

Cloud Configuration

Initialization

Core Instance Sharing

Option 1: Use customStoragePrefix

Option 2: Disable global Core sharing

Session

Handling Session Proposals

Handling Session Requests

Handling Redirects

Namespace Builder

Get Active Sessions

EVM methods & events

Session Approval

🛠️ Usage examples

⚠️ Expected Errors

Session Rejection

🛠️ Usage examples

⚠️ Expected Errors

Responding to Session requests

🛠️ Usage examples

⚠️ Expected Errors

Updating a Session

🛠️ Usage examples

⚠️ Expected Errors

Extending a Session

🛠️ Usage examples

⚠️ Expected Errors

Session Disconnect

🛠️ Usage examples

⚠️ Expected Errors

Emitting Session Events