Prerequisite:
If you haven’t already, check out the External Wallets Overview first, this guide builds on the concepts introduced there.
Setting up wallet authentication
The toggle to enable wallet authentication is available in theTurnkeyProvider
configuration. Wallet authentication can also be set in the dashboard, but the TurnkeyProvider
configuration takes precedence. You can further customize settings, such as which chains are enabled, which providers are supported, and whether WalletConnect is allowed.
Note:
- For authentication 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
).
Wallet authentication
There are two paths you can take: let us handle it for you, or build it yourself. We recommend letting us do the heavy lifting using our built-in modal.Option 1: Use the auth modal
If you want a fully styled, plug-and-play experience, use ourAuth
modal. It handles the entire authentication flow for you.



Note: this UI is customizable. Checkout the UI Customization guide to learn how to customize the look and feel of the Auth modal and other UI components.
Option 2: Build a custom auth flow
There are a few ways to authenticate users with their wallets. We provide several abstraction functions that handle authentication, each with slightly different behavior:loginWithWallet()
signUpWithWallet()
loginOrSignUpWithWallet()
loginOrSignUpWithWallet()
as the reference, since it’s the most commonly used approach.
1
Get the WalletProvider you want to use
2
Log in or sign up with that wallet
How does this look structurally in a Turnkey organization?
If you’re just looking to implement wallet authentication in your app, you don’t need to worry about the internal structure. But if you’re curious about how these flows map to Turnkey’s organization model under the hood, here’s a deeper look: At its core, a wallet is just a key pair. When a user signs up with a wallet, Turnkey creates a sub-org for that user and sets up the public key of the wallet as an authenticator for that sub-org. From then on, whenever the user wants to log in, they callstampLogin()
. This involves signing the login payload with the same wallet key pair.