Appearance

The useWallets hook ​

Both external wallets (that users connect to your site) and embedded wallets (that users create within your app) result in a unified ConnectedWallet object representing the wallet.

To get all of the wallets (external or embedded) that a user has connected to your app, use the useWallets hook:

tsx
const {ready, wallets} = useWallets();

The hook returns:

  • a boolean ready indicating whether Privy has fully processed all active wallet connections
  • a wallets array of ConnectedWallet objects that you may request signatures or transactions from

Waiting for wallets to be ready ​

When your page loads in the user's browser, the Privy SDK determines what wallets the user has connected to your app in two ways:

  • For external wallets, Privy determines what wallets are connected via EIP-6963 for injected wallets (e.g. browser extension wallets) and via WalletConnect for mobile wallets.
  • For embedded wallets, Privy determines if the user has an embedded wallet by loading the Privy iframe which stores the private key material used for the wallet.

To determine if Privy has fully processed all external and embedded wallet connections, use the ready boolean returned by the useWallets hook.

Concretely, ready will be false while Privy is determining what wallets are available for the user, and will be true once Privy has settled on the current set of connected wallets.

Getting a specific wallet ​

To get a specific wallet that the user has connected to your site, parse the wallets array returned by the useWallets hook:

tsx
const {wallets} = useWallets();

The wallets array includes a ConnectedWallet object for all wallets a user has connected to your site. The array is ordered from most recently connected to least recently connected.

To find the most recently connected wallet, get the first element of the wallets array:

tsx
const wallet = wallets[0];

To find a wallet with a specific address, filter the wallets array on the wallets' address field:

tsx
// Replace the string below with your desired address
const address = '0xTheseAreNotTheWalletsYouAreLookingFor';
const wallet = wallets.find((wallet) => wallet.address === address);

To find the embedded wallet, filter the wallets array for the wallet with a walletClientType of 'privy':

tsx
const embeddedWallet = wallets.find((wallet) => wallet.walletClientType === 'privy');

The embedded wallet will always have a walletClientType of 'privy'. The walletClientType for an external wallet will vary on the wallet client the user is actively using, and may include 'metamask', 'rainbow', 'coinbase_wallet', and more.

useWallets vs. usePrivy ​

Both the useWallets and usePrivy hook return information about a user's wallets. The key difference between the two is:

  • useWallets will return all connected wallets, which you can use to request signatures or take onchain actions (via transactions).
  • usePrivy will return all linked wallets, which you can use to verify that a user owns a given wallet address.

Linked wallets are not necessarily actively connected to your site, so you may not always be able to request a signature or transaction from them. Similarly, connected wallets are not necessarily linked, as a user may have connected their wallet without signing a message to verify that they own the wallet addresss.

Concretely, if your use case only requires you to verify that a user owns a given wallet address, you should use the wallets information returned by the usePrivy hook.

Otherwise, if your use case requires you to take actions on a connected wallet, such as getting its network or requesting a signature or transaction, you should use the wallets information returned by the useWallets hook instead.