privy

Privy Skill Reference

Product summary

Privy is a programmable wallet infrastructure platform that provides secure, non-custodial embedded wallets, authentication, and transaction execution across 50+ blockchains. Use Privy to build consumer apps with embedded wallets, trading platforms with server-side automation, treasury management systems, or AI agent wallets with policy controls.

Key files and configuration:

• Dashboard: https://dashboard.privy.io (manage apps, authentication, policies, webhooks)
• App ID and App Secret: Found in Dashboard > App Settings > Basics
• Client SDKs: React (@privy-io/react-auth), React Native (@privy-io/expo), Node.js (@privy-io/node), Swift, Android, Java, Go, Python, Ruby
• REST API: https://api.privy.io/v1/ (requires Basic Auth with app ID and app secret)
• Webhooks: Subscribe in Dashboard > Configuration > Webhooks

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

When to use

Reach for Privy when:

• Building consumer apps that need embedded wallets without blockchain complexity
• Creating trading or fintech apps with server-side transaction automation
• Managing organization or treasury wallets with multi-sig approval workflows
• Building AI agents that need scoped wallet permissions and policy controls
• Implementing user authentication with wallet provisioning
• Executing transactions across multiple chains with consistent APIs
• Setting up role-based access controls and spending policies
• Monitoring wallet activity and transaction lifecycle with webhooks

Do not use Privy for: managing external wallets users already own (use connectors instead), pure authentication without wallets, or non-financial applications.

Quick reference

SDK initialization

React:

<PrivyProvider appId="your-app-id" clientId="your-client-id" config={{embeddedWallets: {ethereum: {createOnLogin: 'users-without-wallets'}}}}>
  {children}
</PrivyProvider>

Node.js:

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

REST API:

curl -X POST https://api.privy.io/v1/wallets \
  -H "Authorization: Basic $(echo -n 'app-id:app-secret' | base64)" \
  -H "privy-app-id: app-id"

Common operations

Task	Method	Notes
Create user wallet	useCreateWallet() (React) or privy.wallets().create() (Node.js)	Specify owner as user ID for user wallets
Get wallet	useWallets() hook (React) or privy.wallets().get() (Node.js)	Returns wallet address, chain type, policies
Send transaction	wallet.sendTransaction() (React) or privy.wallets().ethereum().sendTransaction() (Node.js)	Respects wallet policies; returns transaction ID
Sign message	wallet.signMessage() (React) or privy.wallets().ethereum().personalSign() (Node.js)	For authentication or verification
Create policy	Dashboard or privy.policies().create()	Define transaction limits, recipient whitelist, contract restrictions
Add signer	privy.wallets().update() with additional_signers	Grant scoped permissions to server or third party
Subscribe to events	Dashboard > Webhooks or privy.webhooks().subscribe()	Track user auth, wallet creation, transaction status

Wallet control models

Model	Owner	Use case	Setup
User-owned	User (via auth)	Self-custodial consumer wallets	Create wallet with owner: {user_id}
User + server	User + authorization key	Automated trading, limit orders	Add server as additional signer with policy
App-owned	Authorization key	Treasury, agents, bots	Create wallet with owner: {public_key}
Custodial	Third-party custodian	Regulated accounts	Use custodial wallet API

Authentication methods

Privy supports: email, SMS/WhatsApp, passkeys, Google, Discord, Twitter, Farcaster, Telegram, custom OAuth, or your own JWT-based auth.

Configure in Dashboard > Authentication or via config.loginMethods in SDK.

Transaction status lifecycle

Status	Terminal	Meaning
queued	No	Waiting for prior step
preparing	No	Building transaction data
pending	No	Broadcast to network, awaiting inclusion
confirmed	Yes	Mined and executed successfully
rejected	Yes	Failed before broadcast (policy, simulation, signing error)
reverted	Yes	Mined but execution failed on-chain
replaced	Yes	Different tx confirmed at same nonce
abandoned	Yes	Broadcast but never included on-chain

Decision guidance

When to use embedded wallets vs external wallets

Scenario	Embedded	External
New users, consumer app	✓
Users bring existing wallets		✓
Need server-side automation	✓
Power users, crypto-native		✓
Seamless onboarding priority	✓
User controls keys directly		✓

When to use policies vs signers

Need	Use policies	Use signers
Enforce transaction limits	✓
Whitelist recipient addresses	✓
Restrict contract interactions	✓
Delegate signing to third party		✓
Require approval from multiple parties		✓
Combine both	✓	✓

When to use intents vs direct transactions

Scenario	Intents	Direct
Multi-party approval required	✓
Need to propose before executing	✓
Simple user transaction		✓
Server automation		✓
Require rejection capability	✓

Workflow

1. Set up your Privy app

• Create app in Dashboard
• Copy app ID and app secret
• Configure authentication methods (email, social, passkeys, etc.)
• Set up app clients for different environments if needed
• Configure allowed domains and OAuth redirect URLs

2. Initialize SDK in your application

• React: Wrap app with PrivyProvider at root
• Node.js: Create PrivyClient instance with app ID and secret
• Configure wallet creation behavior (auto-create on login, manual, etc.)
• Set up error boundaries and loading states

3. Authenticate users

• Use Privy's login UI or custom authentication
• Verify user is authenticated before accessing wallets
• Check ready state before consuming Privy hooks/state
• Handle MFA if configured

4. Create or retrieve wallets

• For new users: auto-create on login or call createWallet()
• For existing users: retrieve via useWallets() or privy.wallets().get()
• Specify owner (user ID, authorization key, or key quorum)
• Optionally attach policies and signers at creation

5. Configure controls and policies

• Define policies for transaction limits, recipient whitelists, contract restrictions
• Add additional signers for delegated permissions
• Create key quorums for multi-sig approval
• Test policies in development before production

6. Execute transactions

• Call wallet signing/transaction methods with transaction data
• Privy evaluates policies before signing
• Monitor transaction status via returned ID or webhooks
• Handle rejected (policy violation) vs failed (on-chain revert) states

7. Monitor and react to events

• Subscribe to webhooks in Dashboard
• Listen for user.authenticated, wallet.created, transaction.confirmed, etc.
• Implement retry logic for failed transactions
• Track wallet actions (swaps, transfers, earn) via webhooks

8. Verify and test

• Test authentication flow with all configured login methods
• Verify wallet creation and transaction signing
• Test policy enforcement (attempt violating transaction)
• Confirm webhooks are received and processed
• Check error handling for edge cases

Common gotchas

• HTTPS required for embedded wallets: Embedded wallets use browser WebCrypto API, which only works in secure contexts (https://). Localhost is treated as secure by browsers. http:// deployments will silently fail to create wallets.

• Privy SDK must be ready before use: Always check ready state from usePrivy() before consuming wallet state. Accessing state during initialization can return stale data.

• App ID vs App Secret: App ID is public (used in client SDKs). App Secret is private (server-side only). Never expose app secret in client code.

• Policies are evaluated at request time: Policies prevent signing/broadcast, not on-chain execution. A transaction can still revert on-chain if contract logic fails.

• Wallet owners cannot be changed: Owner is set at wallet creation and is immutable. Plan ownership model carefully.

• Idempotency keys prevent duplicate transactions: Use idempotency keys for critical operations to safely retry without double-sending.

• Rate limits on API calls: Implement exponential backoff for 429 responses. Batch operations when possible.

• Webhooks are delivery notifications, not source of truth: Use webhook history and execution list APIs as authoritative records. Webhooks may be retried or delayed.

• External wallets require explicit configuration: To use external wallets (MetaMask, Phantom), pass externalWallets config to PrivyProvider.

• User export is permanent: Once a user exports their wallet key, Privy loses control. Plan key export policies carefully.

• Policies cannot be updated on existing wallets: Create new wallet with updated policy or use intent-based workflows for policy changes.

Verification checklist

Before submitting work with Privy:

• App ID and app secret are correctly configured (secret never in client code)
• PrivyProvider wraps entire app (React) or PrivyClient initialized (Node.js)
• Checked ready state before consuming Privy state
• Tested authentication with at least one login method
• Wallet creation succeeds and wallet address is returned
• Transaction signing works and respects policies
• Attempted policy violation is correctly rejected
• Webhooks are subscribed and receiving events
• Error handling covers network failures, policy violations, and signing errors
• Tested on https:// (not http://) for embedded wallets
• Idempotency keys used for critical operations
• Transaction status is monitored via returned ID or webhooks
• Sensitive operations (exports, policy changes) require explicit user action

Resources

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

Critical documentation:

1. Key Concepts — Understand authentication, wallets, and controls
2. Wallets Overview — Embedded wallet architecture and capabilities
3. Controls and Policies — Authorization models and policy enforcement
4. API Reference — REST API authentication and endpoints

---

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