---
name: Privy
description: Use when building authentication systems, creating embedded wallets, managing wallet controls and policies, signing transactions, or integrating wallet infrastructure into applications. Agents should reach for this skill when implementing user onboarding, wallet creation, transaction signing, policy enforcement, or wallet management across multiple blockchains.
metadata:
    mintlify-proj: privy
    version: "1.0"
---

# Privy Skill Reference

## Product summary

Privy is a wallet and authentication infrastructure platform that enables developers to onboard users, create embedded wallets, and manage wallet controls across 50+ blockchains. Use Privy to authenticate users via email, SMS, social login, passkeys, or wallet connections; create self-custodial embedded wallets secured by Privy's key management system; and enforce policies that control what actions wallets can perform.

**Key files and configuration:**
- **App ID and App Secret**: Required credentials from the Privy Dashboard for server-side operations
- **Client ID**: Optional identifier for app clients to customize behavior across environments
- **PrivyProvider** (React): Wraps your app to enable authentication and wallet access
- **PrivyClient** (Node.js/server): Entry point for server-side wallet and user management
- **Webhooks**: Configure at `Configuration > Webhooks` in the dashboard to receive real-time events

**Primary documentation**: https://docs.privy.io

## When to use

Reach for Privy when:
- Building user authentication with multiple login methods (email, social, passkeys, wallets)
- Creating embedded wallets for users without requiring them to manage keys
- Implementing wallet controls and policies to restrict transaction types, amounts, or recipients
- Signing transactions on Ethereum, Solana, Bitcoin, or other supported chains
- Managing user-owned wallets with optional server-side automation via signers
- Integrating external wallets (MetaMask, Phantom) alongside embedded wallets
- Tracking wallet events (deposits, withdrawals, key exports) via webhooks
- Building trading apps, fintech apps, or agent wallets with strict policy controls

Do not use Privy for: managing user accounts without wallet functionality, or applications that don't need blockchain interaction.

## Quick reference

### SDK Installation

| Platform | Command | Entry Point |
|----------|---------|-------------|
| React | `npm install @privy-io/react-auth@latest` | `PrivyProvider` + hooks |
| React Native | `npm install @privy-io/expo@latest` | `PrivyProvider` + hooks |
| Node.js | `npm install @privy-io/node@latest` | `PrivyClient` class |
| Python | `pip install privy-python` | `PrivyClient` class |
| Java | Maven/Gradle dependency | `PrivyClient` class |
| Go | `go get github.com/privy-io/privy-go` | `PrivyClient` |
| REST API | HTTP requests with Basic Auth | `https://api.privy.io/v1/*` |

### Core Concepts

| Concept | Definition | Use Case |
|---------|-----------|----------|
| **User** | Authenticated entity with linked accounts (email, wallet, social) | Identify and manage application users |
| **Embedded wallet** | Wallet created and managed by Privy's infrastructure | Self-custodial wallets for users without key management burden |
| **External wallet** | Third-party wallet (MetaMask, Phantom) connected to Privy | Leverage user's existing assets and identity |
| **Owner** | Entity with full control over a wallet (user, authorization key, or key quorum) | Define who can approve wallet actions |
| **Signer** | Additional party with scoped permissions on a wallet | Delegate limited access (e.g., server automation) |
| **Policy** | Rules that constrain what actions a wallet can perform | Enforce transaction limits, approved recipients, contract interactions |
| **Authorization key** | Server-side credential to control wallets | Backend-managed wallets for treasury, agents, or automation |

### Common Configuration Patterns

**React Setup (Ethereum)**
```tsx
<PrivyProvider
  appId="your-privy-app-id"
  clientId="your-app-client-id"
  config={{
    embeddedWallets: {
      ethereum: {
        createOnLogin: 'users-without-wallets'
      }
    }
  }}
>
  {children}
</PrivyProvider>
```

**Node.js Setup**
```ts
import {PrivyClient} from '@privy-io/node';

const privy = new PrivyClient({
  appId: 'insert-your-app-id',
  appSecret: 'insert-your-app-secret'
});
```

**REST API Authentication**
```bash
curl https://api.privy.io/v1/wallets \
  -u "app-id:app-secret" \
  -H "privy-app-id: app-id"
```

### Wallet Control Models

| Model | Owner | Signers | Best For |
|-------|-------|---------|----------|
| User-owned | User | None | Self-custodial consumer wallets |
| User + server | User | Server (scoped) | Automated trading, limit orders |
| Application-owned | Authorization key | None | Treasury, trading bots, agents |
| Custodial | Licensed custodian | None | Regulated account models |

## Decision guidance

### When to use embedded vs. external wallets

| Scenario | Embedded | External |
|----------|----------|----------|
| New users without wallets | ✓ | ✗ |
| Users with existing assets | ✗ | ✓ |
| Seamless onboarding UX | ✓ | ✗ |
| Power users, crypto-native | ✗ | ✓ |
| Cross-chain support needed | ✓ | ✓ |
| Key export/self-custody | ✓ | ✓ |

### When to use Privy authentication vs. JWT-based auth

| Scenario | Privy Auth | JWT-based |
|----------|-----------|-----------|
| Building from scratch | ✓ | ✗ |
| Existing auth system | ✗ | ✓ |
| Multiple login methods needed | ✓ | ✗ |
| Social login required | ✓ | ✗ |
| Custom auth provider | ✗ | ✓ |

### When to use policies vs. signers

| Scenario | Policies | Signers |
|----------|----------|---------|
| Enforce transaction limits | ✓ | ✗ |
| Restrict recipient addresses | ✓ | ✗ |
| Delegate to server automation | ✗ | ✓ |
| Rate limiting over time | ✓ | ✗ |
| Different permissions per party | ✓ | ✓ |

## Workflow

### 1. Set up your Privy app
- Visit the Privy Dashboard and create a new organization
- Create an app and obtain your **App ID** and **App Secret**
- Configure allowed domains/origins for your app
- Set up login methods (email, social, passkeys, etc.) in the dashboard

### 2. Initialize Privy in your client
- Install the appropriate SDK (React, React Native, etc.)
- Wrap your app with `PrivyProvider` (client-side) or instantiate `PrivyClient` (server-side)
- Pass your App ID and optional Client ID
- Configure wallet creation behavior (automatic on login, manual, etc.)
- Wait for the `ready` state before consuming Privy state

### 3. Authenticate users
- Use Privy's built-in login modal or whitelabel UI components
- Users can authenticate via email, SMS, social login, passkeys, or wallet connection
- Privy returns a user object with linked accounts and access tokens
- Store the access token for authenticated API requests

### 4. Create or retrieve wallets
- **Client-side**: Use `useCreateWallet()` hook to create embedded wallets for authenticated users
- **Server-side**: Use `privy.wallets().create()` with a user ID or authorization key as owner
- Specify the chain type (ethereum, solana, etc.) and optional policies
- Wallets are automatically created on login if `createOnLogin` is configured

### 5. Define policies (if needed)
- Create policies in the dashboard or via API to constrain wallet actions
- Define rules with conditions (transaction amount, recipient, contract, etc.)
- Attach policies to wallets at creation time
- Use condition sets for reusable lists of approved addresses or values

### 6. Sign transactions or messages
- **Client-side**: Use wallet hooks (`useSendTransaction`, `useSignMessage`, etc.) to request signatures
- **Server-side**: Use authorization context to sign requests automatically
- Policies are evaluated at signing time; requests violating policies are rejected
- Transactions are broadcast to the blockchain after signing

### 7. Monitor wallet activity
- Configure webhooks in the dashboard to receive real-time events
- Subscribe to user events (created, authenticated, linked_account)
- Subscribe to wallet events (funds_deposited, private_key_export, recovered)
- Subscribe to transaction events (confirmed, failed, replaced)
- Verify webhook signatures using Privy's signing key before processing

### 8. Verify and test
- Test authentication flows with different login methods
- Verify wallet creation and transaction signing in development
- Test policy enforcement with transactions that violate rules
- Confirm webhooks are received and processed correctly
- Check error handling for rate limits and invalid requests

## Common gotchas

- **Not waiting for `ready`**: Always check `usePrivy().ready` before consuming Privy state; the SDK initializes asynchronously
- **Missing origin allowlist**: Add all domains where your app runs to the allowed origins in the dashboard; `invalid_origin` errors indicate this
- **Automatic wallet creation limitations**: Automatic wallet creation only works with the Privy login modal, not with custom/whitelabel flows or direct login methods
- **Policy evaluation timing**: Policies are evaluated at signing time, not at request time; a transaction may be signed but fail if the policy changes
- **Rate limits on API calls**: Privy rate limits REST API endpoints; implement exponential backoff retry logic for HTTP 429 responses
- **Webhook signature verification**: Always verify webhook signatures using Privy's public key before processing; unsigned webhooks should be rejected
- **User ID format**: User IDs are prefixed with `did:privy:` (e.g., `did:privy:xxxxx`); use the full ID when creating wallets
- **Authorization key vs. user ownership**: Authorization keys are for server-controlled wallets; user IDs are for user-controlled wallets; don't mix them
- **Solana peer dependencies**: If using Solana wallets in React, install peer dependencies (`@solana/kit`, etc.) and configure webpack/Vite externals
- **App client vs. app ID**: App clients customize behavior per environment; if using an app client, set its allowed origins separately in the dashboard
- **Idempotency keys**: Use idempotency keys for wallet creation and user creation to prevent duplicate operations on retries
- **Private key export webhooks**: Private key exports are sensitive; ensure your webhook endpoint is secure and only accessible to your backend

## Verification checklist

Before submitting work with Privy:

- [ ] App ID and App Secret are correctly configured in environment variables
- [ ] `PrivyProvider` wraps the app and `ready` state is checked before using Privy
- [ ] Allowed origins are configured in the dashboard for all domains where the app runs
- [ ] Login methods are enabled in the dashboard and match the UI implementation
- [ ] Wallets are created with the correct owner (user ID or authorization key)
- [ ] Policies are attached to wallets if transaction constraints are needed
- [ ] Webhook endpoint is configured, signed, and verified before processing
- [ ] Error handling covers rate limits (HTTP 429) with exponential backoff
- [ ] Transactions are tested with policies that should allow and deny them
- [ ] User authentication flow works end-to-end (login → wallet creation → transaction)
- [ ] External wallets can be connected and used alongside embedded wallets
- [ ] Private keys can be exported by users if self-custody is required

## Resources

**Comprehensive navigation**: https://docs.privy.io/llms.txt

**Critical documentation pages**:
1. [Key Concepts](https://docs.privy.io/basics/key-concepts) — Understand authentication, wallets, and controls
2. [React Setup & Quickstart](https://docs.privy.io/basics/react/setup) — Initialize Privy and authenticate users
3. [Create a Wallet](https://docs.privy.io/wallets/wallets/create/create-a-wallet) — Programmatically create embedded wallets
4. [Policies Overview](https://docs.privy.io/controls/policies/overview) — Define rules that constrain wallet actions
5. [Webhooks Overview](https://docs.privy.io/api-reference/webhooks/overview) — Subscribe to real-time events
6. [API Reference](https://docs.privy.io/api-reference/introduction) — REST API endpoints for wallets, users, and policies

---

> For additional documentation and navigation, see: https://docs.privy.io/llms.txt