Privy

Privy is a third-party service that allows users to login using their email or social accounts (Google, Facebook, Twitter, etc). Upon login, a NEAR wallet is created for the user, which they can fund and use to interact with your dApp.

See full working example here

Web3Auth For an alternative social login method you can check Web3Auth. We have a functional Web3Auth Integration Example to show how to integrate Web3Auth into your web app.

Installation

Choose whether to expose your Privy wallet through NEAR Connect or integrate Privy directly into your application:

NEAR Connect
Direct Privy

Install the plugin, NEAR Connect, and the UI packages used by the signing page:

npm install @peerfolio/privy-near-connect @hot-labs/near-connect @radix-ui/themes @radix-ui/react-collapsible @radix-ui/react-icons

npm install @privy-io/react-auth @near-js/accounts @near-js/providers @near-js/transactions @near-js/tokens @noble/hashes

Which should I choose?

Using NEAR Connect would give your application access to all NEAR Wallets that support NEAR Connect, plus social login with Privy. This will provide an experience closer to Web3 applications. Integrating Privy directly would make your application support only social login (through Privy). This should be the preferred way for applications that want to abstract away the wallet and provide a Web2-like experience to their users.

Setup

NEAR Connect
Direct Privy

privy-near-connect lets you expose a Privy embedded wallet through NEAR Connect.

Create a Privy app

Create an application in the Privy dashboard and copy its App ID and Client ID. Store both values in your application’s environment variables:

VITE_PRIVY_APP_ID=your-privy-app-id
VITE_PRIVY_APP_CLIENT_ID=your-privy-client-id

Publish a wallet manifest

Add manifest.json to your application’s public directory. Replace the example URLs and wallet metadata with your own:

{
  "version": "1.0.0",
  "wallets": [
    {
      "id": "myprivywallet",
      "name": "My Privy Wallet",
      "icon": "https://yourdapp.com/favicon.ico",
      "description": "Web wallet for NEAR",
      "website": "https://yourdapp.com",
      "version": "1.0.0",
      "executor": "https://raw.githubusercontent.com/beneviolabs/privy-near-connect/3d56b782669d242a1ea432921e291abc26b4ebc7/executor.js",
      "type": "sandbox",
      "platform": {
        "web": "https://yourdapp.com"
      },
      "features": {
        "signMessage": true,
        "signInWithoutAddKey": true,
        "signInAndSignMessage": true,
        "signInWithFunctionCallKey": true,
        "signAndSendTransaction": true,
        "signAndSendTransactions": true,
        "mainnet": true,
        "testnet": true
      },
      "permissions": {
        "isPrivyConnect": true,
        "storage": true,
        "allowsOpen": [
          "https://yourdapp.com"
        ]
      },
      "metadata": {
        "signPageURL": "https://yourdapp.com/sign"
      }
    }
  ]
}

Keep the executor URL pinned to an immutable commit SHA. NEAR Connect fetches and runs this script at runtime, so you should update the SHA deliberately when adopting a new executor build.

Create the signing page

Add a /sign route and render the plugin’s signing component there:

import Privy, { LocalStorage } from '@privy-io/js-sdk-core'
import { SignPagePlugin } from '@peerfolio/privy-near-connect/sign-page-plugin'
import '@radix-ui/themes/styles.css'
import '@peerfolio/privy-near-connect/sign-page-plugin/theme.css'

const privy = new Privy({
  appId: import.meta.env.VITE_PRIVY_APP_ID,
  clientId: import.meta.env.VITE_PRIVY_APP_CLIENT_ID,
  storage: new LocalStorage(),
})

export default function SignPage() {
  return (
    <SignPagePlugin
      privy={privy}
      options={{ allowedOrigins: ['https://yourdapp.com'] }}
    />
  )
}

allowedOrigins limits which applications can send requests to the signing page. Add every dApp origin that should be able to use the wallet.

Load the plugin with NEAR Connect

Initialize NearConnector with the manifest you created:

import { NearConnector } from '@hot-labs/near-connect'

const connector = new NearConnector({
  manifest: '/manifest.json',
  network: 'testnet',
})

That’s it! The plugin will now be available in the NEAR Connect modal.

Continue with the wallet login tutorial to connect the wallet and use it from your dApp.

Wrap your application with PrivyProvider and a custom NEARxPrivy context that bridges Privy’s authentication with a NEAR account:

Get a Privy App ID

Sign up at privy.io and create a new app.
Copy the App ID from the dashboard and set it as your appId prop.
Configure your allowed login methods and other settings in the Privy dashboard.

Context

The NEARxPrivy provider listens to Privy’s authentication state. Once the user is logged in, it creates a NEAR wallet (if one doesn’t exist yet) and exposes a nearAccount instance through context:

Value	Type	Description
`walletId`	`string`	The user’s NEAR account address
`nearAccount`	`Account`	A `@near-js/accounts` `Account` ready to sign transactions
`provider`	`JsonRpcProvider`	A read-only RPC provider to query the network

Custom signer

Privy signs transactions through its embedded wallet via signRawHash. The privySigner class adapts that API to the interface expected by @near-js/accounts:

Signing in and out

Use useLogin and useLogout from Privy to open the login modal and sign the user out:

Call read-only methods

Use the provider from context to call view methods — no login required:

const greeting = await provider.callFunction(CONTRACT, 'get_greeting', {})

Call change methods

Use the nearAccount from context to call change methods. The transaction is signed silently by Privy’s embedded wallet, providing a Web2-like UX:

await nearAccount.callFunction({
  contractId: CONTRACT,
  methodName: 'set_greeting',
  args: { greeting: newGreeting },
})

Get balance

import { NEAR } from '@near-js/tokens'

const balance = await nearAccount.getBalance()
const formatted = Number(NEAR.toDecimal(balance)).toFixed(2)
console.log(`Balance: ${formatted} Ⓝ`)

Tutorials

DevKit

Installation

Which should I choose?

Setup

Context

Custom signer

Signing in and out

Call read-only methods

Call change methods

Get balance

​Installation

​Which should I choose?

​Setup

​Context

​Custom signer

​Signing in and out

​Call read-only methods

​Call change methods

​Get balance

Installation

Which should I choose?

Setup

Context

Custom signer

Signing in and out

Call read-only methods

Call change methods

Get balance