From 5dacc19f9d5dce5a3f7b2767c6f27a505959902e Mon Sep 17 00:00:00 2001
From: Haris Chaniotakis <haris@clerk.dev>
Date: Fri, 20 Dec 2024 23:27:12 +0200
Subject: [PATCH] feat: MetaMask Web3 authentication guide (#1818)

Co-authored-by: victoria <github@victoriahchang.com>
Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com>
---
 docs/authentication/web3/metamask.mdx | 47 +++++++++++++++++++++++++++
 docs/manifest.json                    |  4 +++
 2 files changed, 51 insertions(+)
 create mode 100644 docs/authentication/web3/metamask.mdx

diff --git a/docs/authentication/web3/metamask.mdx b/docs/authentication/web3/metamask.mdx
new file mode 100644
index 0000000000..172ecf7bd7
--- /dev/null
+++ b/docs/authentication/web3/metamask.mdx
@@ -0,0 +1,47 @@
+---
+title: MetaMask
+description: Learn how to set up Web3 authentication with MetaMask.
+---
+
+<TutorialHero
+  beforeYouStart={[
+    {
+      title: "A Clerk application is required.",
+      link: "/docs/quickstarts/setup-clerk",
+      icon: "clerk",
+    },
+  ]}
+>
+  - Use MetaMask to authenticate users with Web3
+</TutorialHero>
+
+Enabling [MetaMask](https://metamask.io/) as a Web3 provider allows your users to sign in and  up to your Clerk application with their MetaMask wallet.
+
+## Enable MetaMask as a Web3 provider
+
+1. In the Clerk Dashboard, navigate to the [**Web3**](https://dashboard.clerk.com/last-active?path=user-authentication/web3) page.
+1. From the list of web3 providers, enable **MetaMask**.
+
+## Test authentication
+
+The simplest way to test authentication is to visit your Clerk application's [Account Portal](/docs/customization/account-portal/overview), which is available for all Clerk applications out-of-the-box.
+
+1. In the Clerk Dashboard, navigate to the [**Account Portal**](https://dashboard.clerk.com/last-active?path=account-portal) page.
+1. Next to the **Sign-in** URL, select **Visit**. The URL should resemble:
+   - **For development** – `https://your-domain.accounts.dev/sign-in`
+   - **For production** – `https://accounts.your-domain.com/sign-in`
+1. On the sign-in page, you should see **MetaMask** as an option. Use it to sign in.
+
+## Collect additional user information during sign-up (optional)
+
+Web3 applications typically use a hexadecimal wallet address to identify users, which offers a high level of privacy. However, when bridging the gap between Web3 and Web2, it's often necessary to gather human-readable information about the user, such as their email address, phone number, or a username.
+
+To collect additional information about your user during sign-up:
+
+1. In the Clerk Dashboard, navigate to the [**Email, phone, username**](https://dashboard.clerk.com/last-active?path=user-authentication/email-phone-username) page.
+1. On this page, toggle on attributes you wish to collect from your user during sign up.
+1. To set an attribute as required, select the settings icon next to the enabled attribute. Clerk will automatically prompt the user for this information after authenticating with MetaMask.
+
+## Connect MetaMask to existing account
+
+Users can connect their MetaMask wallet to their account at any time through their user profile page. You can configure your application to use the [Account Portal user profile page](/docs/customization/account-portal/overview#user-profile) or the prebuilt [`<UserProfile />`](/docs/components/user/user-profile) component.
diff --git a/docs/manifest.json b/docs/manifest.json
index 35e16b2594..2d49a465e3 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -608,6 +608,10 @@
                           "title": "Coinbase Wallet",
                           "href": "/docs/authentication/web3/coinbase-wallet"
                         },
+                        {
+                          "title": "MetaMask",
+                          "href": "/docs/authentication/web3/metamask"
+                        },
                         {
                           "title": "OKX Wallet",
                           "href": "/docs/authentication/web3/okx-wallet"