Set up Privy with an AI agent

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