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 your Clerk Dashboard and configure the application to use Sign in with Metamask or Sign in with Coinbase Wallet. For more information on how to set up a Clerk application, see the setup guide. To enable Metamask or Coinbase Wallet authentication, see the dedicated guide.

Ensure that you have downloaded the Metamask or Coinbase Wallet plugins and installed it on your browser to ensure a seamless sign-in flow.

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, you should have a Next.js application integrated with Clerk and with Metamask or Coinbase Wallet authentication enabled. Run npm run dev and visit localhost:3000. If you followed the guide, all of the pages to your application should be protected, and you should see your sign-in page.

After signing in with Metamask or Coinbase Wallet, 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: