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. For more information on how to set up a Clerk application, check out the setup guide. To enable Metamask authentication, check out this guide.

Please ensure that you have downloaded the Metamask plugin 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 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, 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 (
          display: "flex",
          justifyContent: "space-between",
          padding: "1rem",
        <span>My first App</span>
        <UserButton />
      <main style={{ padding: "1rem" }}>
          Address:{" "}
          {primaryWeb3Wallet ? primaryWeb3Wallet.web3Wallet : "Not found"}
        <SignOutButton />

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 user = userId ? await clerkClient.users.getUser(userId) : null;

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

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

      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:

Customization & Localization

Learn how to customize and localize the Clerk components.

Authentication Components

Learn more about all our authentication components.

Client Side Helpers

Learn more about our client side helpers and how to use them.

Next.js SDK Reference

Learn more about additional Next.js methods.


What did you think of this content?