Yvaine - Onboarding Web2 and Web3 Users Seamlessly with Privy

May 05, 2025

Onboarding Web2 and Web3 Users Seamlessly with Privy

Recently, I developed a dApp, and to accommodate both Web2 and Web3 users, I chose Privy as the solution, because its doc states:

Privy builds authentication and wallet infrastructure to enable better products built on crypto rails. Get started in minutes to onboard users with wallets, spin up self-custodial wallets for users, and securely sign transactions through your app.

Requirements

Although the docs mention that users can link multiple wallets and social accounts to a single Privy identity, my use case is much more straightforward:

Users should be able to log in with an external wallet or social account (Google, Twitter, Telegram, Farcaster).
They should be able to start transacting right away without managing accounts.
It’s best to offer onramp first, since new wallets often start with no tokens. (especially for web2 users)

Reference

The Privy Demo is a great way for new developers. It allows anyone to explore Privy's capabilities and ease of use through the official app.

For those working with Ethereum wallets, I recommend checking out the Wagmi Demo, which integrates Privy with Wagmi’s React hooks to provide a smooth developer experience.

Usage

In my setup, I created three files in the providers folder: privyConfig.ts, wagmiConfig.ts, and PrivyProvider.tsx.

PrivyProvider.tsx

import privyConfig from "./privyConfig"
import wagmiConfig from "./wagmiConfig"

const queryClient = new QueryClient()

export default function PiggyPrivyProvider({ children }: { children: React.ReactNode }) {
  return (
    <PrivyProvider
      appId={process.env.NEXT_PUBLIC_PRIVY_APP_ID as string}
      config={privyConfig}
    >
      <QueryClientProvider client={queryClient}>
        <WagmiProvider config={wagmiConfig}>{children}</WagmiProvider>
      </QueryClientProvider>
    </PrivyProvider>
  )
}

Since it’s the entry point for Privy, it should be concise. Configuration files are separated to make them easier to review and update.

privyConfig.ts

import { type PrivyClientConfig, type WalletListEntry } from "@privy-io/react-auth"
import isMobile from "is-mobile"

import Logo from "@/assets/svgs/logo.svg"
import { isCoinbaseWallet } from "@/utils"

import { SCROLL_CHAIN } from "./wagmiConfig"

const walletList: WalletListEntry[] = [
  "metamask",
  "okx_wallet",
  "coinbase_wallet",
  "wallet_connect",
  "detected_ethereum_wallets",
]

const mobileWalletList: WalletListEntry[] = isCoinbaseWallet()
  ? ["coinbase_wallet", "detected_ethereum_wallets"]
  : ["detected_ethereum_wallets"]

export const socialLoginMethodList: PrivyClientConfig["loginMethods"] = [
  "farcaster",
  "google",
  "twitter",
  "telegram",
]

const privyConfig: PrivyClientConfig = {
  appearance: {
    theme: "dark",
    accentColor: "#F30378",
    logo: Logo.src,
    walletList: isMobile({ tablet: true }) ? mobileWalletList : walletList,
  },
  loginMethods: ["wallet", ...socialLoginMethodList],
  embeddedWallets: {
    ethereum: {
      createOnLogin: "users-without-wallets",
    },
  },
  externalWallets: {
    coinbaseWallet: {
      connectionOptions: "eoaOnly",
    },
  },
  defaultChain: SCROLL_CHAIN,
  supportedChains: [SCROLL_CHAIN],
}

export default privyConfig

walletList

They are grouped by device type. Specifically, it depends on whether the browser supports wallet plugins. As we all know (well, maybe just me) using WalletConnect on a mobile device can be a hassle. Mobile browsers like Chrome need to call the wallet app to connect and sign transactions. WalletConnect handles this reasonably well, but the overall experience still isn’t great.

On one hand, I prefer users on mobile browsers to use embedded wallets, which provide a more seamless user experience. On the other hand, if the user opens the app in the built-in browser of a wallet app, detected_ethereum_wallets will work, allowing them to use external wallets as well.

Then, a bug occurs.

In the Coinbase built-in browser, detected_ethereum_wallets doesn’t work as expected. The login modal doesn’t show the Coinbase Wallet option. Logs confirmed that window.ethereum is present in the Coinbase browser environment.

Finally, I decided to detect whether the user is in the Coinbase built-in browser with the following code:

export const isCoinbaseWallet = () => {
  if (typeof window === "undefined") {
    return false
  }
  return typeof window.ethereum !== "undefined" && window.ethereum?.isCoinbaseWallet
}

It works.

loginMethods

I chose Farcaster, Google, Twitter, and Telegram as the supported social accounts for my dapp. Interactions with Google and Twitter are smooth and reliable. However, there are issues when interacting with Telegram and Farcaster.

Telegram

According to the instructions, I created a Telegram bot and entered the bot token in the Privy dashboard.

I was able to see the Twitter OAuth page, successfully entered my phone number, and submitted the verification code I received.

However, I never received the confirmation message on Telegram, like this:

However, after logging in via yellow (thanks a lot!), I was able to authorize my website to access the user’s Telegram information. This means I can now use Telegram login on my website.

So weird. After a lot of research, I found the issue was caused by the domain I was using, which ended with vercel.app.

Here’s a Stack Overflow post describing the same problem.

After switching to the official domain, everything started working.

Farcaster

When you create a Farcaster account on Warpcast, the system automatically generates an Ethereum wallet for you.

This wallet is mainly used for in-app actions on Warpcast, such as interacting with Frames.

You can also import other wallet accounts into Warpcast and link them to your current Farcaster account.

Now, let’s take a closer look at this option under Farcaster.

When this option is enabled(Automatically link connected wallets when logging in with Farcaster), it means that all wallets linked to the user’s Farcaster account will automatically be added to user.linkedAccounts during login.

It’s worth noting that user.wallet.address will be set to the default wallet address associated with the Farcaster account.

It’s frustrating, because I applied createOnLogin: "users-without-wallets", which means Privy should only create an embedded wallet if the user doesn’t already have one.

However, in this case, the wallet linked through Farcaster isn’t usable in the browser, and it also prevents Privy from creating a new embedded wallet.

As a result, the user can’t do anything.

Since the default wallet of a Farcaster account has no walletClientType value—whereas embedded wallets use privy, and others might use metamask, rainbow, coinbase_wallet, and so on—here’s one way to handle the issue.

import { useCreateWallet, useLogin } from "@privy-io/react-auth"

const { createWallet } = useCreateWallet()
const { login: privyLogin } = useLogin({
  onComplete: ({ user, isNewUser, loginMethod }) => {
    if (user.linkedAccounts.every((account: any) => !account.walletClientType)) {
      createWallet()
    }
  },
})

Looking back at the goal, I mainly wanted users to be able to send transactions as quickly as possible, so linking additional accounts wasn’t a priority.

That’s why I didn’t enable this option.

As a result, Privy does create an embedded wallet for the Farcaster account.

Nice.

wagmiConfig.ts

import { createConfig } from "@privy-io/wagmi"
import { scroll, scrollSepolia } from "viem/chains"
import { Transport, http } from "wagmi"

export const SCROLL_CHAIN =
  process.env.NEXT_PUBLIC_SCROLL_CHAIN_TYPE === "mainnet" ? scroll : scrollSepolia

const transports = {
  [SCROLL_CHAIN.id]: http(),
} as Record<534351 | 534352, Transport>

export const wagmiConfig = createConfig({
  chains: [SCROLL_CHAIN],
  transports,
})

It’s better to place the wagmiConfig in a separate file.

In addition to using it with PrivyProvider, I also use it to build a contract.ts file that centralizes all on-chain interactions.

This setup centralizes contract addresses, keeping the codebase cleaner, more maintainable, and easier to reference.

import {
  readContract,
  simulateContract,
  waitForTransactionReceipt,
  writeContract,
} from "@wagmi/core"

import ProxyABI from "@/assets/abis/proxy.json"
import wagmiConfig from "@/providers/wagmiConfig"

// read contract
export const getData = async (param1: number, param2: boolean): Promise<Data> => {
  const data = await readContract(wagmiConfig, {
    address: process.env.NEXT_PUBLIC_PROXY_ADDRESS as Address,
    abi: ProxyABI,
    functionName: "getData",
    args: [param1, param2],
  })
  return data
}

// write contract

export const sendTransaction = async (walletAddress: Address, data: number) => {
  try {
    const { request } = await simulateContract(wagmiConfig, {
      account: walletAddress,
      address: process.env.NEXT_PUBLIC_PROXY_ADDRESS as Address,
      abi: ProxyABI,
      functionName: "sendTransaction",
      args: [walletAddress, data],
    })

    const hash = await writeContract(wagmiConfig, request)
    const isConfirmed = await waitForTransaction(hash)

    if (!isConfirmed) {
      throw new Error("Failed to buy a ticket")
    }
    return true
  } catch (error: any) {
    if (isUserRejectedError(error)) {
      return false
    }
    throw error
  }
}

// wait for tx receipt
export const waitForTransaction = async (hash) => {
  const receipt = await waitForTransactionReceipt(wagmiConfig, { hash })
  if (receipt.status === "success") {
    return true
  }
  return false
}

In client components, we only need to focus on front-end interactions, handling loading states, success, and errors.

The actual business logic(related to contract) is imported from contract.ts, which keeps the components clean and focused.

import { useMutation } from "@tanstack/react-query"
import { sendTransaction } from "@/services/contract"

const { mutateAsync: handleEvent, isPending } = useMutation({
  mutationFn: async ({ walletAddress, data }: { walletAddress: Address; roundData?: RoundData }) => {
    const isSuccess = await sendTransaction(walletAddress, data)
    if (isSuccess) {
      ...
    }
  },
  onError: error => {
      console.log(error)
      ...
  }
})

Privy login vs Wagmi connect

As shown clearly in the wagmi online demo, Privy login and wagmi connect are two separate flows.

Logging out from Privy does not automatically mean disconnecting from wagmi.

There are three hooks to pay attention to:

import { usePrivy, useWallets } from "@privy-io/react-auth"
import { useAccount } from "wagmi"

const { ready, user } = usePrivy()
const { ready: connectorReady, wallets } = useWallets()
const { address } = useAccount()

usePrivy

ready indicates whether the Privy SDK is ready to use. user contains user data fetched from Privy backend.
useWallets

ready tells whether Privy has fully processed all external and embedded EVM wallet connections. When it’s true, wallets contains the list of all currently connected wallets.
useAccount

address represents the address of the currently active wallet address. The corresponding wallet (from wallets) is used by wagmi as the active walletClient. You can switch the active wallet using useSetActiveWallet.

import { useWallets } from "@privy-io/react-auth"
import { useSetActiveWallet } from "@privy-io/wagmi"

const { wallets } = useWallets()

const embeddedWallet = wallets.find((wallet) => wallet.walletClientType === "privy")

// Switch to embedded wallet
await setActiveWallet(embeddedWallet)

When user exists, wallets may not necessarily be available.

Even when wallets are present, address can still be undefined.

Since some on-chain actions require the active address as a parameter, I use !address as one of the conditions for disabling buttons.

As a result, after logging out, it’s necessary to manually call the disconnect function to ensure that useAccount returns undefined for address.

import { useLogout } from "@privy-io/react-auth"
import { useDisconnect } from "wagmi"

const { disconnect } = useDisconnect()
const { logout } = useLogout({
  onSuccess: () => {
    disconnect()
  },
})

Additionally, I added a global check to ensure that the active address truly belongs to the currently logged-in Privy user.

Given my use case,

Each Privy user is associated with only one wallet, either external or embedded

the following check is sufficient.

import { usePrivy, useWallets } from "@privy-io/react-auth"
import { SCROLL_CHAIN } from "@/providers/wagmiConfig"
import { useAccount } from "wagmi"

...

const { user } = usePrivy()
const { ready: walletsReady, wallets } = useWallets()

const { chainId } = useAccount()

useEffect(() => {
  if (user && walletsReady && !wallets.find(wallet => wallet.address === user?.wallet?.address)) {
    changeAccountWarningModalVisible(true)
  } else {
    changeAccountWarningModalVisible(false)
  }
}, [user, walletsReady, wallets])


useEffect(() => {
  if (chainId && chainId !== SCROLL_CHAIN.id) {
    changeNetworkWarningModalVisible(true)
  } else {
    changeNetworkWarningModalVisible(false)
  }
}, [chainId])

Wrapping up

So far, we’ve explored Privy’s core features in action. It’s a solid demonstration of how new users can quickly log in to a dApp and start sending transactions with minimal friction.

By integrating with wagmi and organizing on-chain logic within a dedicated contract.ts file, we’ve also achieved a clean separation between front-end interactions and business logic, making the codebase easier to maintain and scale in the future.

What's Next

All of Privy’s login methods converge into a single, unified Privy user.

Once logged in, users can sign in again on a new device without needing to import a private key or go through extra steps (yes, I’m looking at you, most Web3 wallets).

I’m genuinely curious about the magic behind it all. To use Privy more effectively, I will dive into how it works under the hood.