Privy

# Privy Skill Reference

## Product summary

Privy is a programmable wallet infrastructure platform for building financial applications. It provides embedded wallets, authentication, transaction execution, and policy controls across 50+ blockchains including Ethereum, Solana, Bitcoin, and Tempo. Agents use Privy to authenticate users, create and manage wallets, execute transactions, enforce spending policies, and build complete financial products without building wallet infrastructure from scratch.

**Key files and commands:**
- Dashboard: https://dashboard.privy.io (configure apps, login methods, policies)
- App ID and App Secret: Found in Dashboard > App Settings > Basics
- Client ID: Required for mobile/non-web platforms (Dashboard > App Settings > Clients)
- REST API: `https://api.privy.io/v1/` (requires Basic Auth with app ID:secret)
- SDKs: React (`@privy-io/react-auth`), Node.js (`@privy-io/node`), Swift, Android, Flutter, Java, Go, Rust, Ruby
- Primary docs: https://docs.privy.io

## When to use

Reach for Privy when:
- Building consumer apps that need user authentication + embedded wallets
- Creating organization or treasury wallets with multi-sig controls
- Building AI agents that need to hold assets and transact autonomously
- Implementing spending policies, transaction limits, or approval workflows
- Executing transactions across multiple blockchains from a single interface
- Migrating users from another wallet provider
- Setting up funding flows (fiat onramps, crypto deposits, card spend)
- Implementing yield integrations or token swaps
- Requiring role-based access control or delegation patterns

Do not use Privy for: pure authentication without wallets (use Auth0, Firebase instead), or if you need complete control over key management without any abstraction.

## Quick reference

### SDK Installation

| Platform | Package | Command |
|----------|---------|---------|
| React | `@privy-io/react-auth` | `npm install @privy-io/react-auth` |
| Node.js | `@privy-io/node` | `npm install @privy-io/node` |
| React Native | `@privy-io/react-native-auth` | `npm install @privy-io/react-native-auth` |
| Swift | Privy Swift SDK | Via Swift Package Manager |
| Android | Privy Android SDK | Via Gradle |

### Core Concepts

| Concept | Definition | Use case |
|---------|-----------|----------|
| **User** | Individual authenticated in your app | Consumer wallets, personal accounts |
| **Wallet** | Blockchain account (embedded or external) | Holding assets, signing transactions |
| **Owner** | Entity with full control (user, auth key, or quorum) | Determines who can modify wallet |
| **Signer** | Additional party with scoped permissions | Server automation, delegated access |
| **Policy** | Rules constraining wallet actions | Spending limits, recipient whitelists |
| **Authorization Key** | P256 cryptographic key for server control | Backend wallet management |
| **Key Quorum** | M-of-K multi-sig approval | Shared control, treasury operations |

### Authentication Methods

Configure in Dashboard > Configuration > Authentication:
- Email / SMS / WhatsApp
- Social (Google, Discord, Twitter, Farcaster, etc.)
- Passkeys (WebAuthn)
- External wallets (MetaMask, Phantom)
- Custom JWT (bring your own auth provider)
- Guest accounts (instant sign-in)

### Wallet Control Models

| Model | Owner | Signers | Use case |
|-------|-------|---------|----------|
| User-owned | User | None | Self-custodial consumer wallets |
| User + server | User | Server (scoped) | Automated trading, limit orders |
| App-owned | Auth key | None | Treasury, bots, agents |
| Custodial | Licensed custodian | None | Institutional FBO accounts |

### REST API Headers (Required)

```
Authorization: Basic <base64(app_id:app_secret)>
privy-app-id: <app_id>
Content-Type: application/json
```

### Common Wallet Actions

| Action | Endpoint | Purpose |
|--------|----------|---------|
| Create wallet | `POST /v1/wallets` | Provision new wallet |
| Get wallet | `GET /v1/wallets/{id}` | Fetch wallet details |
| Send transaction | `POST /v1/wallets/{id}/rpc` | Execute blockchain action |
| Get balance | `GET /v1/wallets/{id}/balance` | Check asset holdings |
| Create policy | `POST /v1/policies` | Define spending rules |
| Create user | `POST /v1/users` | Onboard new user |

## Decision guidance

### When to use embedded vs external wallets

| Scenario | Embedded | External |
|----------|----------|----------|
| New users, no existing wallet | ✓ | ✗ |
| Users have MetaMask/Phantom | ✗ | ✓ |
| Need full control over UX | ✓ | ✗ |
| Users want to bring existing assets | ✗ | ✓ |
| Mobile app | ✓ | Limited |
| Require key export | ✓ | ✗ |

### When to use client-side vs server-side SDKs

| Scenario | Client SDK | Server SDK |
|----------|-----------|-----------|
| User authentication | ✓ | ✗ |
| Wallet creation for users | ✓ | ✓ |
| Server-controlled wallets | ✗ | ✓ |
| Transaction signing | ✓ | ✓ |
| Policy management | ✗ | ✓ |
| User management | ✗ | ✓ |

### When to use policies vs key quorums

| Need | Policies | Key Quorums |
|------|----------|-------------|
| Spending limits | ✓ | ✗ |
| Recipient whitelists | ✓ | ✗ |
| Multi-sig approval | ✗ | ✓ |
| Time-based rules | ✓ | ✗ |
| Contract interaction control | ✓ | ✗ |
| Shared ownership | ✗ | ✓ |

## Workflow

### 1. Set up your Privy app

1. Go to https://dashboard.privy.io and create an app
2. Copy your App ID and App Secret from App Settings > Basics
3. For mobile/non-web: Create an app client in App Settings > Clients
4. Configure login methods in Configuration > Authentication
5. (Optional) Configure appearance in Configuration > Appearance

### 2. Integrate authentication (client-side)

1. Install the appropriate SDK (`@privy-io/react-auth` for React, etc.)
2. Wrap your app with `PrivyProvider`, passing `appId` and `clientId`
3. Use `usePrivy()` hook to access `login()`, `logout()`, and `user` state
4. Wait for `ready === true` before consuming Privy state
5. Call `login()` to trig