Skip to main content


This Quickstart guide will help you hit the ground running with Privy. By the end of it, you will have a working sample project (with a frontend and backend component) that uses Privy to store sensitive data. Before starting, make sure you have:

  • A Privy account. If you don't have one, get one here.
  • The MetaMask browser extension and a wallet.
  • Node.js and npm installed.

What are we building? โ€‹

We're going to walk through a simple app that lets you log in with MetaMask and associate some user data with your wallet off-chain using Privy.

You can also see the quickstart running live.

Step 0: Clone the Privy-Quickstart repo โ€‹

Start by cloning the Privy Quickstart repo on your local machine. Run npm install in the project directory to install the dependencies. Notice that both the privy-browser (frontend) and privy-node (backend) libraries are installed.

We only need to worry about 2 files in the whole project:

  • pages/index.js This is the frontend code. It handles signing in with MetaMask, collecting user data, and writing it to Privy using the privy-browser library.
  • .env.local Don't see this file? That's because you have to create it! It will hold your Privy API key.

So let's start off creating .env.local in your top-level repo. You can do this by copying .env.local.example so as follows

cp .env.local.example .env.local

Step 1: Set up your schema in the Privy consoleโ€‹

The first step is to tell Privy what kinds of data you want to collect and who should have access to it. To do so, log in to your Privy console.

In the Access Groups section, click the Create New Access Group button.

We're going to make an access group that grants read and write permissions to both self and admin. Let's call it self-and-admin.

Next, we'll set up our fields. In the Fields section, click the Create New Field button.

We're going to store two pieces of user data: their first name and their favorite color. Go ahead and create two new fields first-name and fav-color. Let's set their default access group to be self-and-admin, as shown below.

This tells Privy to only allow users with either the self or admin roles to read and write this field.

Step 2: Grab your Privy API keyโ€‹

Head over to the API Settings section of the console. Click Roll Keys to generate a new Privy key. Remember that .env.local file you created in Step 0? Go ahead and add your API key to it as shown below (replace the TODOs with your key).


You don't have to use the API secret in this demo since it uses SIWE to authenticate users with the quickstart app.

The API secret is used in backends to programatically update permissions or authenticate users with custom auth.

You won't be able to retrieve it later if you don't copy it now.

Step 3: Run the project!โ€‹

Let's go ahead and run it!. Simply run npm run dev or yarn dev in the project directory. The project should be running on localhost:3000.

Start by connecting with your MetaMask wallet. Note, if you don't have the MetaMask browser extension, you'll see an alert asking you to install it.

Once you're connected, you'll see the following page:

Go ahead and fill out the fields. You can write in either a basic color like "blue" or a hexadecimal color value like "FF0000" for the favorite color input field. Hit submit!

Two things will happen:

  1. The app should be personalized based on the data. The text at the top will include your name and the background color will reflect your favorite color.
  2. The data will appear in your Privy console in the View Data section. Notice that the user_id is the MetaMask ethereum address you connect to the app with.

Congratulations! Your name and favorite color have been associated with your MetaMask wallet and safely stored off-chain with Privy. Now, even if you restart the server, the app will automatically be personalized with your name and favorite color when you connect.


Bonus: Try connecting with different MetaMask accounts! You'lll see that preferences for each individual account are stored in Privy. When you switch accounts, the app is automatically personalized to that account.

Step 4: Understand the codeโ€‹

Let's walk through the essential parts of the code.

Initialize the Privy client on the frontendโ€‹

To start, we initialize the Privy client on the frontend (see pages/index.js) . The Privy client handles fetching and writing data to Privy.

const session = new SiweSession(process.env.NEXT_PUBLIC_PRIVY_API_KEY, provider);
const client = new PrivyClient({
session: session,

The client is initialized using your Privy API key. We create a SIWE session to have the user authenticate directly with Privy using Sign in with Ethereum. The session is then loaded into a new Privy client which can be used to access data. Any request made by the client will be identified by the user's wallet address thereafter.

Read and write data to and from Privyโ€‹

With auth out of the way, the rest is a breeze. Privy essentially boils down to two calls: saving data to Privy and fetching data from Privy.

You can see an example of a put() and a get() call in pages/index.js

// Fetch user's name and fav color from Privy
const [firstName, favColor] = await client.get(address, ['first-name', 'fav-color']);
// set first name in page if set in Privy
if (firstName) setNameInput(firstName.text());
// Save data into Privy drawing values from frontend fields
await client.put(userId, [
field: 'first-name',
value: nameInput,
field: 'fav-color',
value: colorInput,

Step 5: Next Stepsโ€‹

That's it! Privy is meant to be powerful but simple. You're ready to start taking on user data safely and securely. Not sure what to do next? Try building on top of this starter project. Some ideas:

  • Add another user data field to the project
  • Play with the privy-node client on the backend to edit permissions and set up a custom role
  • Explore the rest of the privy-browser and privy-node client interfaces.
  • Run through our hackathon guide for project ideas.
  • Check out more use cases here!

If you have any questions or feedback, please reach out at