Allow users to connect external wallets like MetaMask, Phantom, or WalletConnect alongside Turnkey’s embedded wallets in your React app.
Prerequisite:
If you haven’t already, check out the External Wallets Overview first, this guide builds on the concepts introduced there.
TurnkeyProvider
configuration. You can further customize settings, such as which chains are enabled, which providers are supported, and whether WalletConnect is allowed.
Note:
- For wallet connecting to work, you must define at least one
ethereum
orsolana
chain, either asnative
or withwalletConnectNamespaces
.
- To enable WalletConnect, you must configure both the
walletConnect
object and definewalletConnectNamespaces
in at least one chain (e.g.,ethereum
orsolana
).- For EVM chain switching on WalletConnect, all supported chain namespaces must be listed in
walletConnectNamespaces
underethereum
. Attempting to switch to a chain not listed here will result in an error. The first chain in the array is the default chain you will be connected to.
Wallet Provider is Connected
WalletProvider
you connected to now shows in the connectedAddresses
property of the provider.Wallets state includes that connected wallet
wallets
state.Wallet
object representing that provider. This wallet contains one or more WalletAccount
entries, each representing a connected address on a specific chain (e.g., Ethereum or Solana).For example, if the user connects to MetaMask with an Ethereum address, a Wallet named “MetaMask” is created, and a corresponding Ethereum account is added. If the user then connects to MetaMask with a Solana address, that address appears as an additional account within the same wallet.In short:Wallet
represents the external provider (e.g., “MetaMask”).WalletAccounts
represent the connected addresses, one per namespace (Ethereum, and or Solana) under that provider.Example connected wallet structure
Abstracted Signing
Connect External Wallet
Note: this UI is customizable. Checkout the UI Customization guide to learn how to customize the look and feel of the Connect External Wallet modal and other UI components.
Get the WalletProvider you want to use
Connect the wallet account
Disconnect the wallet account