/privy-integration

name: privy-integration
description: Integrates Privy authentication, embedded wallets, and agent payment protocols into web and agentic apps. Covers React SDK (PrivyProvider, hooks, wagmi), Node.js SDK, smart wallets (ERC-4337), x402 and MPP machine payments, Tempo chain, and agentic wallets with policies. Use when setting up Privy auth, creating embedded or agentic wallets, adding x402 or MPP payments, integrating with Tempo, configuring wallet policies, or connecting Privy to MCP/Agent Auth flows.
metadata:
  version: "0.4.2"
  upstream: "@privy-io/react-auth@3.29.1, @privy-io/node@0.20.0, @privy-io/wagmi@4.0.11, mppx@0.6.30, @x402/fetch@2.14.0"
  openclaw:
    homepage: https://github.com/tenequm/skills/tree/main/skills/privy-integration
    emoji: "🔐"
    primaryEnv: PRIVY_APP_SECRET
    envVars:
      - name: PRIVY_APP_ID
        required: false
        description: Privy App ID (server-side).
      - name: PRIVY_APP_SECRET
        required: false
        description: Privy App Secret for server SDK auth.
      - name: PRIVY_WEBHOOK_SIGNING_SECRET
        required: false
        description: Secret for verifying inbound Privy webhooks.
      - name: MPP_RECIPIENT
        required: false
        description: MPP payment recipient address (Tempo).
      - name: NEXT_PUBLIC_PRIVY_APP_ID
        required: false
        description: Public Privy App ID for client SDK.

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](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) **Wallet actions (DeFi earn, swap, cross-chain transfer/bridge)?** -> Wallet Actions in [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