Privy Skill Reference

Product summary

Privy is a programmable wallet infrastructure platform for building financial applications. It provides embedded wallets (created and managed by Privy), authentication (email, social, passkeys, wallets), transaction execution across 50+ blockchains, and policy controls for authorization and spending limits. Use Privy's client-side SDKs (React, React Native, Swift, Android, Flutter, Unity) for frontend integration, server-side SDKs (Node.js, Java, Go, Rust, Ruby) for backend operations, or REST API for direct HTTP requests. Key files: PrivyProvider config in React, app ID and app secret from the Privy Dashboard, API endpoints at https://api.privy.io/v1/. Primary docs: https://docs.privy.io

When to use

Reach for Privy when:

• Building embedded wallets for users, organizations, or AI agents
• Authenticating users with email, SMS, social login, passkeys, or external wallets
• Creating non-custodial or custodial wallets with flexible ownership models
• Executing transactions on Ethereum, Solana, Tempo, Bitcoin, or other blockchains
• Implementing spending policies, transaction limits, or approval workflows
• Managing multi-sig wallets or key quorum approvals
• Building payment flows, onramps, or yield integrations
• Requiring server-side wallet automation with scoped permissions
• Integrating with existing authentication systems via JWT

Do not use Privy for: standalone key management without wallet functionality, or applications that don't need blockchain interaction.

Quick reference

SDKs and platforms

Core API endpoints

Authentication headers (REST API)

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

Wallet ownership models

Common wallet actions

Decision guidance

When to use client-side vs server-side SDKs

When to use embedded vs external wallets

When to use Privy authentication vs JWT-based auth

Workflow

1. Set up Privy app and credentials

• Create app in Privy Dashboard
• Obtain app ID and app secret
• Create app client for mobile/non-web platforms
• Configure login methods (email, social, passkeys, etc.)
• Set allowed domains and redirect URIs

2. Initialize SDK in your application

• React: Wrap app with PrivyProvider, pass appId and clientId
• React Native: Initialize PrivyProvider with app ID and client ID
• Node.js: Create Privy client with app ID and app secret
• REST API: Store app ID and app secret securely, use in Authorization header

3. Authenticate users

• Use usePrivy() hook (React) or equivalent to trigger login
• Configure login methods in dashboard
• Verify user is authenticated before accessing wallets
• Check ready state before consuming Privy state

4. Create or access wallets

• Client-side: Use useCreateWallet() hook or automatic creation on login
• Server-side: Call wallets().create() with user ID as owner
• REST API: POST to /api/v1/wallets with owner and chain type
• Specify wallet owner (user ID, authorization key, or key quorum)

5. Execute transactions

• Ethereum: Use ethsendTransaction or ethsignTransaction + broadcast
• Solana: Use signAndSendTransaction or signTransaction + broadcast
• Populate missing fields (gas, nonce, etc.) automatically
• Handle transaction status via webhooks or polling

6. Implement policies and controls

• Create policies via dashboard or API to define spending limits, recipient whitelists, contract interactions
• Assign policies to wallets at creation or update
• Policies evaluated at request time, enforced in secure enclaves
• Use key quorums for multi-sig approval workflows

7. Monitor and verify

• Subscribe to webhooks for transaction, wallet, and user events
• Poll wallet actions for status updates
• Verify transaction confirmation on-chain
• Log security events (MFA, key export, authentication)

Common gotchas

• HTTPS required: Embedded wallets only work in secure contexts (https://). Localhost is treated as secure by browsers, but deployed apps must use https://.
• Privy not ready: Always check ready state from usePrivy() before accessing wallet state. Accessing state before ready can return stale data.
• User owner required for user wallets: If creating a user wallet, you must specify the user ID as owner. Client-side SDKs do this automatically.
• Policy evaluation timing: Policies are evaluated at request time in secure enclaves. They cannot be changed retroactively for pending transactions.
• Delegated auth security: If using email, SMS, or social login as primary auth, require MFA (passkey or TOTP) to protect wallet access. Account compromise at the delegated provider exposes wallet funds.
• API authentication: REST API requires both Authorization: Basic header and privy-app-id header. Missing either will be rejected.
• Idempotency keys: Use idempotency keys to prevent duplicate wallet creation or transaction submission on retries.
• Wallet export: Private key export is a sensitive operation. Require authorization signature and log all exports.
• Chain-specific signing: Ethereum uses eth_signTransaction, Solana uses signTransaction. Don't mix them up.
• External wallet limitations: External wallets (MetaMask, Phantom) don't support Privy policies or server-side automation. Use embedded wallets for those features.

Verification checklist

Before submitting work with Privy:

• App ID and app secret are stored securely (environment variables, not hardcoded)
• PrivyProvider wraps the entire app and is initialized with correct appId
• ready state is checked before accessing wallet or user state
• Wallet owner is correctly specified (user ID for user wallets, authorization key for app-owned)
• Policies are created and assigned to wallets if spending limits are required
• Transactions include required fields (wallet ID, chain, recipient, amount)
• Error handling covers common cases (user not authenticated, wallet not found, insufficient funds, policy rejection)
• Webhooks are configured for production monitoring (transaction status, wallet events, user events)
• MFA is enabled for delegated login methods (email, SMS, social)
• HTTPS is enforced for production deployment
• Authorization signatures are required for sensitive operations (policy updates, key export)
• Idempotency keys are used for wallet creation and transaction submission
• Transaction status is verified (pending, confirmed, failed) before considering it complete

Resources

• Comprehensive navigation: https://docs.privy.io/llms.txt
• Getting started: https://docs.privy.io/basics/get-started/about
• Wallet infrastructure: https://docs.privy.io/wallets/overview
• Authentication: https://docs.privy.io/authentication/overview
• Controls and policies: https://docs.privy.io/controls/overview
• REST API reference: https://docs.privy.io/api-reference/introduction
• Security implementation guide: https://docs.privy.io/security/implementation-guide/security-checklist

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