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: Privy ships an official agent skill - npx skills add https://docs.privy.io (or fetch https://docs.privy.io/skill.md). The machine-readable doc index is https://docs.privy.io/llms-full.txt (plus sitemap.xml); llms.txt now only points to the skill installer. Privy restructures docs often - do not guess URLs, they 404.

Workflow Decision Tree

Setting up Privy auth in a React app? -> Quick Start below, then references/react-sdk.md Adding wagmi/viem to a Privy app? -> Wagmi Integration below, then references/react-sdk.md Working server-side (Node.js)? -> Server-Side section below, then references/server-sdk.md Adding x402 or MPP payments? -> x402/MPP sections below, then references/agent-payments.md Building agentic wallets or agent auth? -> Agentic Wallets below, then references/agent-auth.md Solana-specific integration? -> references/solana.md Wallet management (smart wallets, policies, funding)? -> references/wallets.md Wallet actions (DeFi earn, swap, cross-chain transfer/bridge)? -> Wallet Actions in 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 (
    
      {children}
    
  );
}

3. Check readiness before using hooks

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

function App() {
  const {ready, authenticated, user} = usePrivy();
  if (!ready) return Loading...;
  // 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 (
     sendTransaction({to: '0x...', value: 100000})}>
      Send
    
  );
}

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 (
    
      
        {children}
      
    
  );
}

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
// (top-level privy.verifyAuthToken is deprecated - use utils().auth())
const {userId} = await privy.utils().auth().verifyAccessToken(accessToken);

Whitelabel Authentication

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

Footgun: whitelabel flows (useLoginWithEmail, etc.) call Privy directly from the app domain, so they silently fail if that domain is not in the Dashboard's Allowed Origins/Domains - the hosted modal (usePrivy().login()) still works, masking the issue. Add every local dev port (e.g. localhost:5173) too. useLoginWithEmail's onError returns a rich object, not {message} - log the whole thing to see the real rejection.

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, developer-owned) and user-owned with agent signers (user retains revocation authority). See references/agent-auth.md for policy examples and setup.

Reference Docs

Read the appropriate reference file for detailed integration guides:

• references/react-sdk.md - All React hooks, PrivyProvider config, wagmi/viem setup, appearance config, whitelabel patterns, wallet UI components
• references/server-sdk.md - Node.js SDK (@privy-io/node), token types and verification, user management API, REST API, webhooks
• references/wallets.md - Embedded wallets (EVM + Solana), smart wallets (ERC-4337), gas sponsorship, external connectors, policies and controls, funding, wallet export
• references/solana.md - Solana-specific setup, connectors, @solana/kit and @solana/web3.js integration, transaction signing, gas sponsorship via fee payer
• references/agent-payments.md - x402 protocol (React + Node.js), MPP with mppx SDK (client + server), Tempo blockchain (PathUSD, TIP-20), sessions, facilitators, x402 vs MPP comparison
• references/agent-auth.md - Agentic wallets (policies, authorization keys, OpenClaw), Agent Auth Protocol (per-agent identity, capabilities), MCP authorization, Better Auth bridge

Key Documentation URLs