Use Clerk with Web3

Learn how to use Clerk to quickly and easily add secure authentication and user management to your Web3 application.

Before you start

You need to create a Clerk application in the Clerk Dashboard⁠ and configure the application to use Sign in with Metamask, Sign in with Coinbase Wallet or Sign in with OKX Wallet. For more information on how to set up a Clerk application, see the setup guide. To enable Metamask, Coinbase Wallet, or OKX Wallet authentication, see the dedicated guide.

Ensure that you've installed the Metamask⁠, Coinbase Wallet⁠, or OKX Wallet⁠ plugins for a seamless sign-in experience.

Creating a new Next.js app

Once you have a Clerk application set up in the dashboard, it's time to create a Next.js application. Clerk provides a detailed guide on how to create a new Next.js app with Clerk.

Accessing the Web3 address from the frontend

At this point, your Next.js application should be integrated with Clerk and configured for authentication using Metamask, Coinbase Wallet, or OKX Wallet. Run npm run dev and visit localhost:3000. If you followed the guide, all pages in your application will be protected, and you should see your sign-in page.

After signing in with your Web3 provider, you'll be presented with the Next.js default start screen. Let's modify the start screen to display a user's primary Web3 address on the page.

In this example, the User object for the current user can be accessed through the useUser() hook. The user's primary Web3 address can then be retrieved from the User object.

import { SignIn, SignOutButton, UserButton, useUser } from '@clerk/nextjs'

export default function Home() {
  const { user } = useUser()

  if (!user) {
    return <SignIn />
  }

  const primaryWeb3Wallet = user?.primaryWeb3Wallet

  return (
    <>
      <header
        style={{
          display: 'flex',
          justifyContent: 'space-between',
          padding: '1rem',
        }}
      >
        <span>My first App</span>
        <UserButton />
      </header>
      <main style={{ padding: '1rem' }}>
        <p>Address: {primaryWeb3Wallet ? primaryWeb3Wallet.web3Wallet : 'Not found'}</p>
        <SignOutButton />
      </main>
    </>
  )
}

Accessing the Web3 address from the backend

Add authentication to a serverless API route

A new Next.js app using Pages Router comes with a sample API route in /pages/api/hello.js. Let's modify it to retrieve the user's Web3 address:

import type { NextApiRequest, NextApiResponse } from 'next'
import { getAuth } from '@clerk/nextjs/server'
import { clerkClient } from '@clerk/nextjs'

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  try {
    const { userId } = getAuth(req)

    if (!userId) {
      return res.status(401).json({ error: 'Unauthorized' })
    }

    const client = await clerkClient()

    const user = userId ? await client.users.getUser(userId) : null

    // Retrieve the user's web3Wallet
    const walletId = user ? user.primaryWeb3WalletId : null
    const address = user ? user.web3Wallets.find((wallet) => wallet.id === walletId) : null

    res.status(200).json({ address: address })
  } catch (e) {
    console.log(e)

    res.status(500).json({
      error: 'Something went wrong retrieving the web3wallet from Clerk',
    })
  }
}

Next steps

Now that you have Web3 authentication in a new Next.js application, and you know how to retrieve the user's Web3 address from both the frontend and the backend, you will want to read the following documentation: