privy-integration

What this skill does

# 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

```bash
npm i @privy-io/react-auth
```

### 2. Wrap app with PrivyProvider

```tsx
'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

```tsx
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)

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

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

### 5. Send a transaction (EVM)

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

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

## PrivyProvider Config

```tsx
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`).

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

```tsx
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

```bash
npm i @privy-io/node
```

```ts
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:

| 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 |

**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.

```tsx
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):
```ts
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 stablec