privy-integration

Privy Integration

Privy provides authentication and wallet infrastructure for apps built on crypto rails. Embed self-custodial wallets, authenticate users via email/SMS/socials/passkeys/wallets, and transact on EVM and Solana chains. Also supports agent payment protocols (x402, MPP) and autonomous agentic wallets.

Key packages:

• @privy-io/react-auth - React SDK (auth + wallets + x402)
• @privy-io/react-auth/solana - Solana wallet hooks
• @privy-io/react-auth/smart-wallets - Smart wallets (ERC-4337)
• @privy-io/wagmi - wagmi v2 connector
• @privy-io/node - Server-side SDK (replaces deprecated @privy-io/server-auth)
• mppx - MPP client/server SDK (settles on Tempo)

Docs index: https://docs.privy.io/llms.txt

Workflow Decision Tree

Setting up Privy auth in a React app? -> Quick Start below, then [references/react-sdk.md](references/react-sdk.md) Adding wagmi/viem to a Privy app? -> Wagmi Integration below, then [references/react-sdk.md](references/react-sdk.md) Working server-side (Node.js)? -> Server-Side section below, then [references/server-sdk.md](references/server-sdk.md) Adding x402 or MPP payments? -> x402/MPP sections below, then [references/agent-payments.md](references/agent-payments.md) Building agentic wallets or agent auth? -> Agentic Wallets below, then [references/agent-auth.md](references/agent-auth.md) Solana-specific integration? -> [references/solana.md](references/solana.md) Wallet management (smart wallets, policies, funding)? -> [references/wallets.md](references/wallets.md)

Quick Start (React + Next.js)

1. Install

npm i @privy-io/react-auth

2. Wrap app with PrivyProvider

'use client';
import {PrivyProvider} from '@privy-io/react-auth';

export default function Providers({children}: {children: React.ReactNode}) {
  return (
    <PrivyProvider
      appId={process.env.NEXT_PUBLIC_PRIVY_APP_ID!}
      config={{
        embeddedWallets: {
          ethereum: {createOnLogin: 'users-without-wallets'}
        }
      }}
    >
      {children}
    </PrivyProvider>
  );
}

3. Check readiness before using hooks

import {usePrivy} from '@privy-io/react-auth';

function App() {
  const {ready, authenticated, user} = usePrivy();
  if (!ready) return <div>Loading...</div>;
  // Safe to use Privy hooks now
}

4. Login (email OTP example)

import {useLoginWithEmail} from '@privy-io/react-auth';

function LoginForm() {
  const {sendCode, loginWithCode} = useLoginWithEmail();
  // sendCode({email}) then loginWithCode({code})
}

5. Send a transaction (EVM)

import {useSendTransaction} from '@privy-io/react-auth';

function SendButton() {
  const {sendTransaction} = useSendTransaction();
  return (
    <button onClick={() => sendTransaction({to: '0x...', value: 100000})}>
      Send
    </button>
  );
}

PrivyProvider Config

config={{
  // Auth methods enabled for login
  loginMethods: ['email', 'sms', 'wallet', 'google', 'apple', 'twitter',
                 'github', 'discord', 'farcaster', 'telegram', 'passkey'],

  // Embedded wallet creation
  embeddedWallets: {
    ethereum: {createOnLogin: 'users-without-wallets'}, // or 'all-users' | 'off'
    solana: {createOnLogin: 'users-without-wallets'}
  },

  // UI appearance
  appearance: {
    showWalletLoginFirst: false,
    walletChainType: 'ethereum-and-solana', // or 'ethereum-only' | 'solana-only'
    theme: 'light', // or 'dark'
    accentColor: '#6A6FF5',
    logo: 'https://your-logo.png'
  },

  // External wallet connectors (Solana)
  externalWallets: {
    solana: {connectors: toSolanaWalletConnectors()}
  },

  // Solana RPC config (required for embedded wallet UIs)
  solana: {
    rpcs: {
      'solana:mainnet': {
        rpc: createSolanaRpc('https://api.mainnet-beta.solana.com'),
        rpcSubscriptions: createSolanaRpcSubscriptions('wss://api.mainnet-beta.solana.com')
      }
    }
  }
}}

Wagmi Integration

Import createConfig and WagmiProvider from @privy-io/wagmi (NOT from wagmi).

npm i @privy-io/react-auth @privy-io/wagmi wagmi @tanstack/react-query

import {PrivyProvider} from '@privy-io/react-auth';
import {WagmiProvider, createConfig} from '@privy-io/wagmi';
import {QueryClient, QueryClientProvider} from '@tanstack/react-query';
import {mainnet, base} from 'viem/chains';
import {http} from 'wagmi';

const queryClient = new QueryClient();
const wagmiConfig = createConfig({
  chains: [mainnet, base],
  transports: {[mainnet.id]: http(), [base.id]: http()}
});

// Nesting order: PrivyProvider > QueryClientProvider > WagmiProvider
export default function Providers({children}: {children: React.ReactNode}) {
  return (
    <PrivyProvider appId="your-app-id" config={privyConfig}>
      <QueryClientProvider client={queryClient}>
        <WagmiProvider config={wagmiConfig}>{children}</WagmiProvider>
      </QueryClientProvider>
    </PrivyProvider>
  );
}

Use wagmi hooks (useAccount, useSendTransaction, etc.) for read/write actions. Use Privy hooks for wallet connection/creation.

Server-Side Token Verification

npm i @privy-io/node

import {PrivyClient} from '@privy-io/node';

const privy = new PrivyClient({
  appId: process.env.PRIVY_APP_ID!,
  appSecret: process.env.PRIVY_APP_SECRET!
});

// Verify access token from Authorization header
const {userId} = await privy.verifyAuthToken(accessToken);

Whitelabel Authentication

All auth flows can be fully whitelabeled with custom UI. Key hooks:

| Hook | Auth method | |------|------------| | useLoginWithEmail | Email OTP (sendCode, loginWithCode) | | useLoginWithSms | SMS OTP | | useLoginWithOAuth | Social logins (initOAuth({provider: 'google'})) | | useLoginWithPasskey | Passkeys | | useSignupWithPasskey | Passkey signup | | useLoginWithTelegram | Telegram | | useLogin | General login with callbacks |

x402 Payments (Quick Start)

Built into @privy-io/react-auth since v3.7.0. Handles HTTP 402 payment flows automatically using USDC.

import {useX402Fetch, useWallets} from '@privy-io/react-auth';

function PaidContent() {
  const {wallets} = useWallets();
  const {wrapFetchWithPayment} = useX402Fetch();

  const fetchContent = async () => {
    const fetchWithPayment = wrapFetchWithPayment({
      walletAddress: wallets[0]?.address,
      fetch,
      maxValue: BigInt(1000000) // Max 1 USDC
    });
    const res = await fetchWithPayment('https://api.example.com/premium');
    return res.json();
  };
}

Server-side (Node.js):

import {createX402Client} from '@privy-io/node/x402';
import {wrapFetchWithPayment} from '@x402/fetch';

const x402client = createX402Client(privy, {walletId: wallet.id, address: wallet.address});
const fetchWithPayment = wrapFetchWithPayment(fetch, x402client);
const response = await fetchWithPayment('https://api.example.com/premium');

MPP Payments (Quick Start)

MPP (Machine Payments Protocol) settles on Tempo using stablecoins (PathUSD, USDC, or others). Supports sessions for high-frequency payments.

import {Mppx, tempo} from 'mppx/client';

// Create Privy-backed viem account (see references/agent-payments.md for full pattern)
const account = createPrivyAccount(wallet.id, wallet.address);

const mppx = Mppx.create({polyfill: false, methods: [tempo({account})]});
const response = await mppx.fetch('https://api.example.com/weather');

Agentic Wallets (Quick Start)

Server-controlled wallets with policy-based constraints for autonomous agents.

// Create agent wallet
const wallet = await privy.wallets().create({chain_type: 'ethereum'});

// Execute transactions - validated against attached policies
const {hash} = await privy.wallets().ethereum().sendTransaction(wallet.id, {
  caip2: 'eip155:8453',
  params: {transaction: {to: '0x...', value: '0x1', chain_id: 8453}}
});

Two control models: agent-controlled (fully autonomous, dev