Multiple Wallet Connections (Multi-Wallet)

Recommended: JavaScript SDK with React Hooks

For new React apps, we recommend the JavaScript SDK with React Hooks (@dynamic-labs-sdk/react-hooks) instead of the legacy React SDK documented here. The JS SDK comes with many benefits such as a much smaller bundle size and other optimizations. Use the React quickstart (JavaScript SDK) to get started.

Summary

Lots of users have multiple wallets but managing multiple wallets and multiple accounts for each wallet is challenging. You have to manage event listeners, various connection states, wallets shared across accounts, and much much more. If you want to learn more about our multi-wallet solution, check out our blog post.

Our multiwallet widget allows your users to easily:

1. Add multiple wallets
2. Add multiple accounts from the same wallet
3. Transfer wallets between accounts
4. It is mobile friendly
5. Keep track of the active account in a wallet
6. Swap primary wallets
7. and so much more.

To simplify management of these scenarios and the resulting edge cases, we’ve released a widget that does it for you. You can see it in action on our demo site.

Setup

To enable multiwallet, simply visit the Log in & User Profile section of the dashboard and toggle it on in the “External Wallets” section.

How it works

Connect-only

When a user initially connects an additional wallet, they go through the normal wallet connection flow.

Once connected, the wallet is added to the Wallets list and the user can switch between wallets as needed.

If the user manually disconnects a wallet from the extension/app, the wallet gets removed from the Wallets list (unless the no disconnect event is emitted by the wallet extension/app).

If the user manually disconnects their primary wallet, they get logged out.

If a wallet gets disconnected while the user is not in the app using Dynamic (or we don’t detect any disconnect events), the wallet will remain in the Wallets list, and once the user tries to take any action with it (e.g. send a transaction), we’ll check the state and prompt them to re-connect.

When a user connects a wallet, they cannot connect another wallet from the same provider through the widget. However, if they switch account in the wallet extension/app while in the app that is using Dynamic, we’ll detect this account change and automatically switch the previously connected wallet to the new one (unless no accountChange event is emitted by the wallet extension/app).

Example: If the user initially connects with MetaMask account 1, they cannot connect another MetaMask account. However, it they switch to MetaMask account 2, that will be the account connected to Dynamic and the address that they’ll see in the widget, not account 1 anymore.

Connect-and-sign

When a user initially links an additional wallet, they go through the normal wallet connection flow i.e. connect and sign a message.

Once connected, the wallet is added to the user’s profile and they can switch between wallets as needed.

When unused, we do not keep track of the wallets states once they are linked, meaning the user can lock their wallets, change accounts and so on. This avoids extra friction for the user, as the wallets are not in use at that time, and all that matters is that they have a valid JWT.

However, once the user is ready to take action using a linked wallet, we check the state and can prompt them to unlock, change back to the connected account etc.

Custom UI Multi-Wallet

Multi-wallet functionality comes bundled as part of the user profile, and we have a guide to achieve every aspect of this in a hooks only manner here.