---
name: privy
description: Use when building wallet infrastructure, authentication systems, or
  financial applications. Reach for Privy when you need to create embedded
  wallets, manage user authentication, enforce transaction policies, handle
  multi-chain transactions, or build treasury/agent wallet systems.
metadata:
  mintlify-proj: privy
  version: "1.0"
---

# Privy Skill

## Product summary

Privy is a programmable wallet infrastructure platform for building financial applications. It provides embedded wallets (non-custodial or custodial), authentication (email, social, passkeys, wallets), transaction signing and execution across 50+ blockchains, and policy controls for restricting wallet actions. Use Privy's REST API, Node.js SDK, React SDK, or mobile SDKs (Swift, Android, React Native, Flutter, Unity) to integrate wallet functionality. Key files: app ID and app secret from the Privy Dashboard. Primary docs: https://docs.privy.io

## When to use

- **Building consumer wallets**: Create embedded wallets for users with familiar login methods (email, social, passkeys)
- **Server-side wallet operations**: Use the Node.js SDK or REST API to create wallets, sign transactions, and manage assets programmatically
- **Multi-chain transactions**: Send transactions on Ethereum, Solana, Tempo, Bitcoin, Tron, XRPL, and other chains
- **Policy enforcement**: Restrict wallet actions with spending limits, recipient allowlists, contract interaction controls
- **Organization/treasury wallets**: Build multi-sig wallets with approval workflows and role-based access
- **Agent wallets**: Create autonomous wallets with scoped permissions and offline signing capabilities
- **Financial flows**: Integrate deposits (fiat/crypto), payouts, swaps, yield farming, or card spend
- **Authentication integration**: Use Privy's auth system or integrate with your existing JWT-based auth

## Quick reference

### SDK Setup

| Platform | Package | Key Method | Config |
|----------|---------|-----------|--------|
| React | `@privy-io/react-auth` | `PrivyProvider` | `appId`, `clientId`, `config` |
| React Native | `@privy-io/expo` | `PrivyProvider` | `appId`, `clientId`, `config` |
| Node.js | `@privy-io/node` | `PrivyClient` | `appId`, `appSecret` |
| Swift | `@privy-io/swift` | `PrivyClient` | `appId`, `clientId` |
| Android | `@privy-io/android` | `PrivyClient` | `appId`, `clientId` |
| REST API | HTTP | Basic Auth | `appId` header + `appSecret` |

### Core Concepts

- **Wallets**: Embedded (Privy-managed) or external (user-managed like MetaMask)
- **Owners**: User, authorization key, or key quorum with full control
- **Signers**: Additional parties with scoped permissions via policies
- **Policies**: Rules defining allowed/denied actions (transfer limits, recipient allowlists, contract interactions)
- **Chains**: Ethereum, Solana, Tempo, Bitcoin, Tron, XRPL, Cosmos, Stellar, Sui, and others

### Common API Endpoints

| Operation | Method | Endpoint |
|-----------|--------|----------|
| Create wallet | POST | `/v1/wallets` |
| Get wallet | GET | `/v1/wallets/{wallet_id}` |
| Send transaction | POST | `/v1/wallets/{wallet_id}/ethereum/eth_sendTransaction` |
| Sign message | POST | `/v1/wallets/{wallet_id}/ethereum/personal_sign` |
| Create policy | POST | `/v1/policies` |
| Get user | GET | `/v1/users/{user_id}` |
| Create user | POST | `/v1/users` |

### Authentication Methods

- Email/SMS/WhatsApp (OTP)
- Social (Google, Discord, Twitter, GitHub, etc.)
- Wallet (MetaMask, Phantom, Farcaster)
- Passkeys
- Custom OAuth
- JWT-based (your own auth system)

## Decision guidance

| Scenario | Use This | Why |
|----------|----------|-----|
| User-controlled wallet | Embedded wallet + user owner | Non-custodial, user has full control |
| Server automation (limit orders, rebalancing) | Embedded wallet + user owner + server signer + policy | User retains control, server has scoped permissions |
| Treasury/agent wallet | Embedded wallet + authorization key owner | Application controls wallet, no user involvement |
| Multi-sig approval | Key quorum owner | Multiple parties must sign |
| Custodial wallet | Custodial wallet type | Licensed third-party manages keys |
| External wallet integration | External wallet connector | User brings existing wallet (MetaMask, Phantom) |
| Policy enforcement | Policies on wallet | Restrict transfer amounts, recipients, contracts |
| Client-side signing | React SDK + useSignMessage/useSignAndSendTransaction | User signs in browser |
| Server-side signing | Node.js SDK + AuthorizationContext | Backend signs with authorization key |

## Workflow

### 1. Set up your Privy app
- Create app in Privy Dashboard
- Get app ID and app secret
- Configure login methods (email, social, passkeys, etc.)
- Set up app clients for mobile/non-web platforms
- Configure appearance and branding

### 2. Initialize SDK in your application
- **React**: Wrap app with `PrivyProvider`, pass `appId` and `clientId`
- **Node.js**: Create `PrivyClient` with `appId` and `appSecret`
- **REST API**: Include `privy-app-id` header and Basic Auth with `appSecret`

### 3. Authenticate users
- Use `usePrivy()` hook (React) or `privy.users.create()` (Node.js)
- Trigger login with `login()` method
- Check `ready` flag before consuming Privy state
- Verify user JWT if needed

### 4. Create or connect wallets
- **Automatic**: Configure `createOnLogin: 'users-without-wallets'` in PrivyProvider
- **Manual**: Call `createWallet()` (React) or `privy.wallets().create()` (Node.js)
- Specify owner (user ID, authorization key, or key quorum)
- Optionally attach policies and signers

### 5. Define policies (if needed)
- Create policy via Dashboard, Node.js SDK, or REST API
- Define rules for each RPC method (eth_sendTransaction, signMessage, etc.)
- Set conditions (transfer limits, recipient allowlists, contract interactions)
- Attach policy to wallet at creation or update

### 6. Execute transactions
- **Client-side**: Use `useSignAndSendTransaction()` or `useSignMessage()` (React)
- **Server-side**: Use `privy.wallets().ethereum.sendTransaction()` (Node.js)
- **REST API**: POST to `/v1/wallets/{wallet_id}/ethereum/eth_sendTransaction`
- Include authorization signatures if wallet has multiple owners/signers

### 7. Monitor and handle events
- Set up webhooks for transaction status, wallet events, user events
- Listen for `transaction.confirmed`, `transaction.failed`, `wallet.funds_deposited`
- Implement retry logic with exponential backoff for rate limits

## Common gotchas

- **HTTPS required**: Embedded wallets only work in secure contexts (https://, not http://). Localhost is an exception.
- **Policy allowlisting**: If a wallet has a policy, the policy must include a rule for every RPC method the wallet will use. Missing methods default to DENY.
- **Authorization signatures**: Requests to wallets with multiple owners/signers require authorization signatures in the `privy-authorization-signature` header. Missing or invalid signatures cause `policy_violation` or `insufficient_correct_authorization_signatures` errors.
- **Rate limits**: REST API has rate limits. Implement exponential backoff and batching. Check `/recipes/dashboard/optimizing` for best practices.
- **Gas sponsorship credits**: If using gas sponsorship, monitor credit balance. Depleted credits cause `insufficient_funds` errors. Enable automated refill in Dashboard.
- **Policy evaluation timing**: Policies are evaluated in secure enclaves before signing. Transaction simulation runs before policy evaluation. Simulation failures return before policy checks.
- **Idempotency keys**: Use idempotency keys to prevent duplicate transactions on network errors. Same key replays cached response.
- **User session keys**: User signing keys expire. Use `AuthorizationContext` in Node.js SDK to auto-refresh, or manually request fresh keys before expiry.
- **Chain-specific fields**: Policy conditions vary by chain. Ethereum uses `ethereum_transaction`, Solana uses `solana_program_instruction`. Check examples for your chain.
- **Entity assignment is permanent**: Once a wallet is assigned to a user/organization entity, it cannot be changed. Plan entity assignment carefully.

## Verification checklist

Before submitting work with Privy:

- [ ] App ID and app secret are correctly configured (not hardcoded in client code)
- [ ] PrivyProvider wraps the app and `ready` flag is checked before using Privy state
- [ ] Wallets are created with appropriate owner (user, authorization key, or key quorum)
- [ ] Policies are attached if wallet actions need to be restricted
- [ ] All RPC methods used by wallet have corresponding policy rules (if policy exists)
- [ ] Authorization signatures are included for multi-owner/signer wallets
- [ ] Idempotency keys are used for transaction creation
- [ ] Webhooks are configured for production (Enterprise plan required)
- [ ] Error handling covers `policy_violation`, `insufficient_funds`, `transaction_broadcast_failure`
- [ ] Rate limit handling includes exponential backoff
- [ ] HTTPS is enforced for production deployments
- [ ] User session keys are refreshed before expiry (or AuthorizationContext is used)
- [ ] Gas sponsorship credits are monitored (if using gas sponsorship)

## Resources

- **Comprehensive page listing**: https://docs.privy.io/llms.txt
- **Key Concepts guide**: https://docs.privy.io/basics/key-concepts
- **API Reference**: https://docs.privy.io/api-reference/introduction
- **Controls & Policies**: https://docs.privy.io/controls/overview

---

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