Privy Skill Reference

Product summary

Privy is a programmable wallet infrastructure platform for building financial applications. It provides secure, non-custodial embedded wallets, authentication systems, transaction execution, and policy controls across 50+ blockchains (Ethereum, Solana, Bitcoin, Tempo, Tron, and more).

Key files and configuration:

• Dashboard: https://dashboard.privy.io (create apps, configure auth methods, set up webhooks)
• App ID and App Secret: Found in Dashboard > App Settings > Basics (required for all API calls)
• Client ID: Optional, used for app clients to customize behavior per environment
• REST API base: https://api.privy.io/v1/
• SDKs: React (@privy-io/react-auth), React Native (@privy-io/expo), Node.js (@privy-io/node), Java, Go, Python, Ruby, Rust, Swift, Android, Flutter, Unity

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

When to use

Reach for Privy when:

• Building consumer apps with embedded wallets (no separate wallet client needed)
• Creating organization or treasury wallets with multi-sig and approval workflows
• Implementing AI agent wallets with scoped permissions and policies
• Adding authentication to blockchain applications (email, social, passkeys, wallet-based)
• Executing transactions across multiple chains with a unified API
• Enforcing spending limits, recipient whitelists, or time-based restrictions on wallets
• Building financial products (payments, yield, swaps, deposits, payouts)
• Migrating users from other wallet providers (Alchemy, etc.)
• Setting up webhooks to monitor wallet events (deposits, withdrawals, transactions)

Quick reference

Authentication methods (configure in Dashboard)

Wallet types

SDK initialization (React example)

import {PrivyProvider} from '@privy-io/react-auth';

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

REST API authentication

All requests require:

Authorization: Basic <base64(appId:appSecret)>
privy-app-id: <your-app-id>

Common API endpoints

Decision guidance

When to use embedded vs. external wallets

When to use policies vs. signers

When to use wallet actions vs. RPC

Workflow

1. Set up your Privy app

1. Go to https://dashboard.privy.io and create a new app
2. Copy your App ID and App Secret from Dashboard > App Settings > Basics
3. Configure authentication methods in Dashboard > Authentication
4. (Optional) Create app clients for different environments in Dashboard > App Clients
5. (Optional) Set up webhooks in Dashboard > Webhooks

2. Integrate SDK (client-side example with React)

1. Install: npm install @privy-io/react-auth
2. Wrap your app with PrivyProvider at the root
3. Pass appId and clientId to the provider
4. Configure embeddedWallets to auto-create wallets on login
5. Wait for usePrivy().ready before consuming Privy state

3. Authenticate users

1. Use usePrivy().login() to trigger login flow
2. User selects auth method (email, social, wallet, etc.)
3. On success, usePrivy().user contains authenticated user object
4. Access user's wallets via useWallets().wallets

4. Create or access wallets

1. Client-side: Use useCreateWallet().createWallet() to create embedded wallet
2. Server-side: Call POST /v1/wallets with owner (user ID or authorization key)
3. Specify chain_type (ethereum, solana, etc.)
4. Optionally attach policy_ids to restrict wallet actions
5. Response includes wallet id and address

5. Execute transactions

1. Simple flow: Use wallet action APIs (transfer, swap, earn)
2. Custom flow: Use RPC methods (eth_sendTransaction, signTransaction, etc.)
3. Async approval: Create intents for multi-party approval
4. Privy evaluates policies before signing
5. Monitor via webhooks or poll intent/transaction status

6. Set up policies (optional)

1. Define rules in Dashboard or via API
2. Specify chain_type (ethereum, solana, etc.)
3. Add rules for each RPC method (eth_sendTransaction, signMessage, etc.)
4. Define conditions (recipient whitelist, amount limits, time windows)
5. Attach policy to wallet via policy_ids at creation or update

7. Monitor events

1. Configure webhook endpoint in Dashboard > Webhooks
2. Subscribe to event types (user.created, wallet.funds_deposited, transaction.confirmed, etc.)
3. Verify webhook signatures using Privy's public key
4. Implement retry logic for failed deliveries

Common gotchas

• HTTPS required: Embedded wallets only work in secure contexts (https://). Localhost is treated as secure by browsers.
• Policy defaults to DENY: If a wallet has a policy but no rule matches the RPC method, the request is denied. Always include rules for all methods the wallet will use.
• Idempotency keys: Use idempotency keys on wallet creation and transaction endpoints to prevent duplicates on retries.
• Rate limits: REST API endpoints are rate-limited. Implement exponential backoff on HTTP 429 responses.
• Authorization signatures required: If a wallet has an owner, requests must include authorization signatures from the owner. Use authorization context in server SDKs.
• Entity is permanent: Once set on a wallet, the entity (user or organization) cannot be changed.
• External IDs are write-once: External IDs on wallets cannot be updated after creation.
• Policy evaluation timing: Policies are evaluated in secure enclaves before signing. Simulation errors take precedence over policy violations.
• Webhook retries: Privy retries failed webhooks with exponential backoff. Ensure your endpoint is idempotent.
• User JWTs expire: Access tokens from Privy authentication expire. Refresh tokens automatically via the SDK.
• Solana instruction evaluation: Every instruction in a Solana transaction is evaluated against policies. All must pass for the transaction to be allowed.
• Condition set operators: Use in_condition_set to reference reusable condition sets instead of duplicating conditions across policies.

Verification checklist

Before submitting work with Privy:

• App ID and App Secret are correctly configured (not hardcoded in client code)
• PrivyProvider wraps the app at the root level
• ready state from usePrivy() is checked before consuming Privy state
• Authentication methods are enabled in Dashboard > Authentication
• Wallets are created with appropriate owners (user ID for user wallets, authorization key for server wallets)
• Policies are attached to wallets if restrictions are needed
• All RPC methods used by wallets have corresponding policy rules (if policy is attached)
• Idempotency keys are used on wallet creation and transaction endpoints
• Webhook endpoint is configured and signature verification is implemented
• Error handling includes NotFoundError (404) and rate limit (429) cases
• HTTPS is used in production (not http://)
• Authorization signatures are included in server-side requests for owned resources
• External IDs are unique per app and URL-safe (a-z, A-Z, 0-9, _, -, max 64 chars)
• Policies are tested in development before deploying to production

Resources

Comprehensive page listing: https://docs.privy.io/llms.txt

Critical documentation pages:

1. Key Concepts — Understand authentication, wallets, and controls
2. API Reference Introduction — REST API setup and rate limits
3. Policies Overview — Policy engine, rules, and conditions

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