Using external wallets

Connecting the wallet

To prompt a user to connect an external wallet to your app, use the connectWallet method of the usePrivy hook:

const {connectWallet} = usePrivy();

This method will prompt the user to select the wallet they want to connect. You can prompt users to connect as many wallets as you'd like to your app.

For example, you might have a "Connect" button in your app that prompts users to connect their wallet, like so:

import {usePrivy} from '@privy-io/react-auth';

export default function ConnectWalletButton() {
  const {connectWallet} = usePrivy();
  // Prompt user to connect a wallet with Privy modal
  return <button onClick={connectWallet}>Connect wallet</button>;
}

As an optional parameter to connectWallet, you may pass an object with the following optional fields:

Field	Type	Description
suggestedAddress	string	An suggested address for the user to connect, which will be displayed in Privy's UI.
walletList	WalletListEntry[]	A list of wallet options that you would like Privy to display in the connection prompt.

connectWallet({
  suggestedAddress: '0x1234567890abcdef1234567890abcdef12345678',
  walletList: ['metamask', 'safe'],
});

Once a user has connected their external wallet to your app, the wallet will appear in Privy's useWallets array, which you can then use to request signatures and transactions from the connected wallet.

Connecting or creating a wallet

You can also use Privy to connect a user's external wallet if they have one, or to create an embedded wallet for them if they do not. To do so, use the connectOrCreateWallet method of the usePrivy hook:

const {connectOrCreateWallet} = usePrivy();

This method will prompt the user to connect an external wallet, or log in with email, SMS, or socials, depending on your configured loginMethods, to create an embedded wallet.

For example, you might have a "Connect" button in your app that prompts users to connect their wallet, like so:

import {usePrivy} from '@privy-io/react-auth';

export default function ConnectWalletButton() {
  const {connectOrCreateWallet} = usePrivy();
  // Prompt user to connect a wallet with Privy modal
  return <button onClick={connectOrCreateWallet}>Connect wallet</button>;
}

TIP

This method functions exactly the same as Privy's login method, except when users connect their external wallet, they will not automatically be prompted to authenticate that wallet by signing a message

Authenticating a connected wallet

Once a user has connected their wallet to your app, and the wallet is available in the useWallets array, you can also prompt them to login with that wallet or link that wallet to their existing account, instead of prompting the entire login or linkWallet flow.

To do so, find the ConnectedWallet object from Privy's useWallets array, and call the object's loginOrLink method:

const {wallets} = useWallets();
...
wallets[0].loginOrLink();

When called, loginOrLink will directly request a SIWE signature from the user's connected wallet to authenticate the wallet.

If the user was not authenticated when the method was called, the user will become authenticated after signing the SIWE message.

If the user was already authenticated when the method was called, the user will remain authenticated after signing the SIWE message, and the connected wallet will become one of the user's linkedAccounts in their user object.

You might use the methods above to "split up" the connect and sign steps of external wallet login, like so:

import {usePrivy, useWallets} from '@privy-io/react-auth';

export default function WalletButton() {
  const {connectWallet} = usePrivy();
  const {wallets} = useWallets();

  // Prompt user to connect a wallet with Privy modal
  return (
    {/* Button to connect wallet */}
    <button
        onClick={connectWallet}>
        Connect wallet
    </button>
    {/* Button to login with or link the most recently connected wallet */}
    <button
        disabled={!wallets[0]}
        onClick={() => { wallets[0].loginOrLink() }}>
        Login with wallet
    </button>
  );
}