# Privy React SDK Integration in a Next.js App ## Introduction Privy provides infrastructure for user onboarding and embedded wallets, enabling applications to seamlessly integrate crypto functionality. By embedding asset control directly within applications, Privy allows users, businesses, or even autonomous systems like you to interact with digital assets through smooth and intuitive experiences. You will be instructed on how to integrate Privy using the `@privy-io/react-auth` package. This package is designed to handle user authentication, set up embedded wallets, and manage wallet interactions. When paired with a Next.js app, it provides a full suite of tools for authentication, wallet management, and asset control, allowing you to securely enable these features within the application. ## Implementation Note When implementing Privy authentication in a project, ALWAYS start by creating the PrivyProvider wrapper component and setting it up in the root layout BEFORE implementing any components that use Privy hooks. The PrivyProvider must be initialized with valid appId and clientId credentials, and should wrap the entire application at the root level (typically in layout.tsx). This ensures that the authentication context is available throughout your application's component tree. ## Wallet Types Overview Privy enables users to connect external wallets to your app, or to create secure, self-custodial embedded wallets, on both EVM networks (Ethereum, L2s, and EVM-compatible chains) and Solana. With both kinds of wallets, you can easily request signatures and transactions from your users to have them interact with your product onchain. The logic for making these requests is similar across wallet types, though embedded wallets allow for extra customization in terms of how signature and transaction prompts are presented to users. ### External Wallets External wallets are managed by a third-party client, such as MetaMask, Phantom, or Rainbow. All browser extension wallets, hardware wallets, and mobile app wallets fall into this category. If they choose, users may use multiple external wallets within your app and may link these wallets to their account. You can request signatures and transactions from an external wallet directly, or by integrating Privy alongside a library like wagmi, viem, or @solana/web3.js. ### Embedded Wallets Embedded wallets are self-custodial wallets provisioned by Privy itself for a wallet experience that is directly embedded in your application. Embedded wallets do not require a separate wallet client, like a browser extension or a mobile app, and can be accessed directly from your product. These are primarily designed for users of your app who may not already have an external wallet, or don't want to connect their external wallet. You can choose exactly when to create an embedded wallet for your user, and can request signatures and transactions from the wallet using Privy's native signature and transaction methods, requesting the wallet provider directly, or using a library wagmi, viem, or @solana/web3.js. You can use Privy embedded wallets on EVM networks, Solana, or both within your application. ## Instructions You are to follow the steps below to integrate Privy into your Next.js app. It involves setting up Privy, initializing the Privy provider, and context of the top-level hooks and components provided by the package. You will also find common workflows for authentication and wallet management that you may reference as needed. - **CRITICAL**: You are to replace the placeholders with the actual values in your codebase. - **CRITICAL**: You are to follow the setup instructions, and do as it says without failure. This must be done as you first priority. ## Variables Please use the following variables to initialize Privy in your Next.js app: ```plaintext PRIVY_APP_ID="cm5yjbh8z01lv6heoze3v3ep5" CLIENT_ID="client-WY5fRbUUsnYnSBnU7hp47apYGAdUgABi38uhK4PxBYLpx" ``` ## Setting Up Privy 1. Create the following wrapper component to initialize Privy in your lib/privy directory: ```tsx 'use client' // lib/privy/provider.tsx import { PrivyProvider, PrivyProviderProps } from '@privy-io/react-auth'; const PRIVY_APP_ID = "cm5yjbh8z01lv6heoze3v3ep5" // Replace with above app ID const CLIENT_ID = "client-WY5fRbUUsnYnSBnU7hp47apYGAdUgABi38uhK4PxBYLpx" // Replace with above client ID const PrivyWrapper: React.FC = ({ children, ...props }) => { return ( {children} ) } export { PrivyWrapper } ``` 2. Wrap your app with the `PrivyWrapper` component in your root layout file, and don't forget to import the global styles: ```tsx import './globals.css' import { PrivyWrapper } from '@/lib/privy/provider' import { type PropsWithChildren } from 'react' export default function RootLayout({ children }: PropsWithChildren) { return ( {children} ) } ``` ## Embedded Wallet Configuration The `embeddedWallets.createOnLogin` configuration accepts one of three string values: - `'off'` (default): Privy will not automatically create embedded wallets for users. You can still manually create wallets later. - `'users-without-wallets'`: Privy will automatically create an embedded wallet only for users who don't have any external wallets linked to their account. - `'all-users'`: Privy will automatically create an embedded wallet for all users, regardless of whether they have external wallets linked. ## Implementation Guidelines When implementing Privy wallet integration, always use numerical chainIds instead of chain names (e.g., use 137 for Polygon, 1 for Ethereum mainnet). The PrivyProvider requires only the appId and a config object with specific properties: loginMethods (array of strings), appearance (theme configuration), embeddedWallets (wallet creation settings), defaultChainId (number), and supportedChainIds (array of numbers). Remove the fundWallet integration if it's not explicitly supported by the current Privy SDK version, and ensure wallet connection methods (connectWallet, linkWallet) are handled with proper loading states and error boundaries. The provider should be configured before any wallet-related functionality is implemented, and all wallet operations should be wrapped in try-catch blocks to handle potential connection errors. ## Top Level Hooks/Components At a high-level, there are two major integration surfaces between your app and Privy: - The `PrivyProvider`: A React component that loads the SDK and manages state through React Context - The `usePrivy`: A React hook that returns the SDK's key methods and state variables Both can be imported directly from the SDK: ```tsx import {PrivyProvider, usePrivy} from '@privy-io/react-auth'; ``` ### PrivyProvider Component The `PrivyProvider` is a React component that loads the Privy SDK in your app. It renders a React Context that manages your app's interactions with the Privy API and iframe and stores state about the current user and their wallet(s). This component must wrap any component that will use Privy in your app. It is recommended to render this component as close to the root of your application as possible to ensure your app's components and pages have sufficient access to the SDK. The `PrivyProvider` accepts a config property for customizing Privy's appearance, login methods, wallet configurations, and more. ### usePrivy The main hook you'll use to interact with Privy is the `usePrivy` hook. This hook provides access to the user's current authentication state, wallet signing, wallet transfer, etc. Please refer to the `PrivyInterface` type below for more information. There are important rules for using the `usePrivy` hook: 1. The hook must be called from within a React component. It will throw an error if invoked outside of the scope of a component. 2. The component calling the hook must be wrapped by the `PrivyProvider`. Otherwise, the hook cannot access Privy's React Context. Note that the Privy React SDK also exports other hooks like `useWallets`, `useLogin`, etc. While these hooks can be used as needed, `usePrivy` is the primary integration point between your components and Privy. Please have the user login using the `login` method before using any other methods provided by this package. Below is an example of how you can use the `usePrivy` hook: ```tsx import { usePrivy } from '@privy-io/react-auth' function LoginButton() { const { ready, authenticated, login } = usePrivy() // Disable login when Privy is not ready or the user is already authenticated const disableLogin = !ready || (ready && authenticated) return ( ) } ``` ### useFundWallet Once invoked, the fundWallet method will open a modal that contains a list of funding options the user can take. If only one funding method was enabled for your app, Privy will navigate the user directly to that specific flow. Please refer to the `UseFundWalletInterface` type below for more information. Package definition: ```tsx /** * Hook to fund a wallet via Privy's fiat on-ramp integration given the wallet address. * * @param callbacks.onUserExited {@link PrivyEvents} Callback that will execute when a funding flow is exited. This fires when a user closes a funding flow modal, for any reason. * @returns fundWallet - function to on-ramp funds to any given wallet */ declare const useFundWallet: ( callbacks?: PrivyEvents['fundWallet'], ) => UseFundWalletInterface ``` Example usage: ```tsx import { useFundWallet } from '@privy-io/react-auth' function FundWalletButton() { const { fundWallet } = useFundWallet() const WALLET_ADDRESS = 'WALLET_ADDRESS' return ( ) } ``` ### useWallets The `useWallets` hook allows you to manage the user's "connected" wallets. You can access the user's connected wallets and their readiness status using this hook. Please refer to the `UseWalletsInterface` & `ConnectedWallet` types below for more information. Package definition: ```tsx /** * Allows you to manage the user's currently connected wallets. * You can access the fields and methods documented here via the {@link useWallets} hook. */ interface UseWalletsInterface { /** * The user's connected wallets. */ wallets: ConnectedWallet[] /** * Whether the wallets are ready to be used. */ ready: boolean } declare function useWallets(): UseWalletsInterface ``` Example usage: ```tsx import { useWallets } from '@privy-io/react-auth' const Wallets = () => { const { wallets, ready } = useWallets() if (!ready) { return

} return (

{wallets.map((wallet) => (

{wallet.address}

))}

) } ``` ## Types ### PrivyInterface ```ts /** * Allows you to manage the user's current authentication state and access their linked accounts. * You can access the fields and methods documented here via the {@link usePrivy} hook. */ interface PrivyInterface { /** * Check whether the `PrivyProvider` is ready to be used. You should wait for this to * be true before using values such as `authenticated` and `user`. */ ready: boolean /** * True if the user is authenticated, false otherwise. * * You should always check that `ready` is true before using this value. Otherwise, * the value may outdated while the Privy client fetches fresh tokens. * */ authenticated: boolean /** * The user object, or null if the user is not authenticated. */ user: User | null /** * Opens the Privy modal and prompts the user to connect a wallet. * @param options.suggestedAddress {string} (optional) wallet address that you wish to prompt the user to explicitly connect, if included */ connectWallet: ( options?: ConnectWalletModalOptions | MouseEvent, ) => void /** * Opens the Privy login modal and prompts the user to login. * @param options.loginMethods {LoginMethod[]} custom login methods to display in the login modal. This will overwrite the value provider to the client config. * @param options.prefill {PrefillLoginOptions} prefill the login modal with the provided email or phone number. */ login: (options?: LoginModalOptions | MouseEvent) => void /** * Opens the Privy login modal and prompts the user to login or connect a wallet. */ connectOrCreateWallet: () => void /** * For users who are authenticated, opens the Privy modal and prompts the user to link an email. * This will open the Privy Modal which will guide the user through this action. */ linkEmail: () => void /** * For users who are authenticated, opens the Privy modal and prompts the user to link a phone number. * This will open the Privy Modal which will guide the user through this action. */ linkPhone: () => void /** * For users who are authenticated, opens the Privy modal and prompts the user to link a wallet. * This will open the Privy Modal which will guide the user through this action. */ linkWallet: () => void /** * For users who are authenticated, prompts the user to link a Google OAuth account. * This will directly initiate the OAuth flow for Google. */ linkGoogle: () => void /** * For users who are authenticated, prompts the user to link Apple OAuth account * This will directly initiate the OAuth flow for Apple. */ linkApple: () => void /** * For users who are authenticated, prompts the user to link a Passkey account * This will open the Privy Modal which will guide the user through this action. */ linkPasskey: () => void /** * For users who are authenticated and have already linked an email address, prompts the user to update their email address. * This will open the Privy Modal which will guide the user through this action. * */ updateEmail: () => void /** * For users who are authenticated and have already linked a phone number, prompts the user to update their phone number. * This will open the Privy Modal which will guide the user through this action. */ updatePhone: () => void /** * Log the current user out and clears their authentication state. `authenticated` will become false, `user` will become null, and the Privy Auth tokens will be deleted from the browser's local storage. * * You may await this call to take an action once logout is complete (e.g. redirecting to a specific page). */ logout: () => Promise /** * Get the Privy access token ([JWT](https://jwt.io/)) for an authenticated user. Returns null for an unauthenticated user. * * You may use this token to authorize requests sent from your frontend, and can validate it in your backend against your app's Privy verification key. * * This will automatically attempt to refresh the session if the token is expired or about to expire. * * @returns Promise for the user's access token as a string if they are authenticated, null if they are unauthenticated. */ getAccessToken: () => Promise /** * Unlink an email account from a user, by passing the email address. Note that you can only unlink an email account if the user has at least one other account. * * @param address {string} email address to be unlinked * @returns Promise for the {@link User} object after the provided email has been unlinked */ unlinkEmail: (address: string) => Promise /** * Unlink a phone account from a user, by passing the phone number. Note that you can only unlink a phone account if the user has at least one other account. * * @param phoneNumber {string} phone number to be unlinked * @returns Promise for the {@link User} object after the provided phone number has been unlinked */ unlinkPhone: (phoneNumber: string) => Promise /** * Unlink a wallet account from a user, by passing the public address. Note that you can only unlink a wallet account if the user has at least one other account. * If the unlinked wallet was the active one, and more wallets are linked to the user, then we attempt to make the most recently linked wallet active. * * @param address {string} wallet address to be unlinked * @returns Promise for the {@link User} object after the provided wallet has been unlinked */ unlinkWallet: (address: string) => Promise /** * Unlink a Google social account from a user, by passing the google subject ID. Note that you can only unlink a social account if the user has at least one other account. * * @param subject {string} google account's subject ID * @returns Promise for the {@link User} object after the provided Google account has been unlinked */ unlinkGoogle: (subject: string) => Promise /** * Unlink a Apple social account from a user, by passing the apple subject ID. Note that you can only unlink a social account if the user has at least one other account. * * @param subject {string} apple account's subject ID * @returns Promise for the {@link User} object after the provided Apple account has been unlinked */ unlinkApple: (subject: string) => Promise /** * Unlink a Passkey account from a user, by passing the credential ID. Note that you can only unlink a passkey account if the user has at least one other account. * * @param credentialId {string} Passkey Credential ID * @returns Promise for the {@link User} object after the provided passkey account has been unlinked */ unlinkPasskey: (credentialId: string) => Promise /** * Creates an embedded wallet for the current user. * * This method will error if the user already has an embedded wallet or if they * exit in the middle of the flow. * * If the `config.embeddedWallets.requireUserOwnedRecoveryOnCreate` property is set to true, * this will prompt the user to complete a recovery flow to secure the recovery * share of their embedded wallet. * * Otherwise (the default), Privy will secure the recovery share, and the embedded wallet * will be created without showing any UIs to the user. * * @returns Promise for the {@link Wallet} object for the newly created embedded wallet */ createWallet: ( options?: CreateWalletOptions | MouseEvent, ) => Promise /** * Prompt the user to enable wallet recovery. Current recovery options include password, Google Drive, and iCloud. * * This method will error if the user does not have an embedded wallet, if the user's * embedded wallet already has a cloud-based recovery set, or if the user exits in the middle of the flow. * * @returns Promise for the {@link Wallet} object for the updated embedded wallet */ setWalletRecovery: (o?: SetWalletRecoveryOptions) => Promise /** * Prompts a user to sign a message using their embedded wallet using EIP-191's `personal_sign` * method (0x45). * * This method will error if the user is not authenticated or does not have an embedded wallet. * * If the `config.embeddedWallets.showWalletUIs` property is set to false, the signature will * be computed without prompting the user. Otherwise (the default), Privy will show the user a modal * to prompt them for a signature. This can be customized via the {@link SignMessageModalUIOptions}. * * @param input.message {string} message to be signed * @param options.uiOptions {@link SignMessageModalUIOptions} (optional) UI options to customize the signature prompt modal * @param options.address {optional} address for the embedded wallet signing the message. You should ONLY set this parameter if using imported * embedded wallets or multiple HD embedded wallets for the same user. Defaults to the user's embedded wallet at HD index 0. * @returns Promise for the signature as a string */ signMessage: ( input: { message: string }, options?: { uiOptions?: SignMessageModalUIOptions address?: string }, ) => Promise<{ signature: string }> /** * Prompts a user to sign a message using their embedded wallet using EIP-712's `eth_signTypedData_v4`. * * This method will error if the user is not authenticated or does not have an embedded wallet. * * @param input {SignTypedDataParams} typed data payload to be signed * @param options.uiOptions {@link SignMessageModalUIOptions} (optional) UI options to customize the signature prompt modal * @param options.address {optional} address for the embedded wallet signing the message. You should ONLY set this parameter if using imported * embedded wallets or multiple HD embedded wallets for the same user. Defaults to the user's embedded wallet at HD index 0. * @returns Promise for the signature as a string */ signTypedData: ( input: SignTypedDataParams, options?: { uiOptions?: SignMessageModalUIOptions address?: string }, ) => Promise<{ signature: string }> /** * Prompts a user to send a transaction using their embedded wallet. * * This method will error if the user is not authenticated or does not have an ethereum embedded wallet. * * If no `chainId` is specified as part of the {@link UnsignedTransactionRequest}, Privy will default * to the embedded wallet's current chain ID. * * If the `config.embeddedWallets.showWalletUIs` property is set to false, the wallet will * attempt to send the transaction without prompting the user. Otherwise (the default), Privy * will show the user a modal to have them confirm the transaction. This can be customized via * the {@link SendTransactionModalUIOptions}. * * @param input {@link UnsignedTransactionRequest} transaction to be sent * @param options.uiOptions {@link SendTransactionModalUIOptions} (optional) UI options to customize the transaction request modal * @param options.fundWalletConfig {@link FundWalletConfig} (optional) Funding configuration to specify chain and funding amount (if enabled), in the case of insufficient funds * @param options.address {optional} address for the embedded wallet signing the message. You should ONLY set this parameter if using imported * embedded wallets or multiple HD embedded wallets for the same user. Defaults to the user's embedded wallet at HD index 0. * @returns Promise for the transaction's hash as a hexadecimal string */ sendTransaction: ( input: UnsignedTransactionRequest, options?: { uiOptions?: SendTransactionModalUIOptions fundWalletConfig?: FundWalletConfig address?: string }, ) => Promise<{ hash: `0x${string}` }> /** * Prompts a user to sign a transaction using their embedded wallet. * * This method will error if the user is not authenticated or does not have an ethereum embedded wallet. * * If no `chainId` is specified as part of the {@link UnsignedTransactionRequest}, Privy will default * to the embedded wallet's current chain ID. * * If the `config.embeddedWallets.showWalletUIs` property is set to false, the wallet will * attempt to sign the transaction without prompting the user. Otherwise (the default), Privy * will show the user a modal to have them confirm the transaction. This can be customized via * the {@link SendTransactionModalUIOptions}. * * @param input {@link UnsignedTransactionRequest} transaction to be signed * @param options.uiOptions {@link SendTransactionModalUIOptions} (optional) UI options to customize the transaction request modal * @param options.address {optional} address for the embedded wallet signing the message. You should ONLY set this parameter if using imported * embedded wallets or multiple HD embedded wallets for the same user. Defaults to the user's embedded wallet at HD index 0. * @returns Promise for the signature as a hexadecimal string */ signTransaction: ( input: UnsignedTransactionRequest, options?: { uiOptions?: SendTransactionModalUIOptions address?: string }, ) => Promise<{ signature: `0x${string}` }> /** * Shows the user a Privy modal, from which they can copy their embedded wallet's private * key or seed phrase for easy export to another wallet client (e.g. MetaMask). The private key is loaded * on an iframe running on a separate domain from your app, meaning your app cannot access it. * * This method will error if the user is not authenticated or does not have an embedded wallet. * @param options {@link {address: string}} (optional) wallet address to export the private key for * @returns Promise that resolves once the user exits the modal */ exportWallet: ( options?: | { address: string } | MouseEvent, ) => Promise /** * Check whether the Privy Modal is visible. */ isModalOpen: boolean } ``` ### User ```ts interface User { /** The Privy-issued DID for the user. If you need to store additional information * about a user, you can use this DID to reference them. */ id: string /** The datetime of when the user was created. */ createdAt: Date /** The user's most recently linked wallet, if they have linked at least one wallet. * It cannot be linked to another user. * This wallet is the wallet that will be used for transactions and signing if it is connected. **/ wallet?: Wallet /** * The user's smart wallet, if they have set up through the Privy Smart Wallet SDK. */ smartWallet?: SmartWallet /** The list of accounts associated with this user. Each account contains additional metadata * that may be helpful for advanced use cases. */ linkedAccounts: Array /** * Whether or not the user has explicitly accepted the Terms and Conditions * and/or Privacy Policy */ hasAcceptedTerms: boolean /** Whether or not the user is a guest */ isGuest: boolean /** Custom metadata field for a given user account */ customMetadata?: CustomMetadataType } ``` ### Wallet ```ts /** * Object representation of a user's wallet. */ interface Wallet { /** The wallet address. */ address: string /** * Chain type of the wallet address. */ chainType: 'ethereum' | 'solana' /** * The wallet client used for this wallet during the most recent verification. * * If the value is `privy`, then this is a privy embedded wallet. * * Other values include but are not limited to `metamask`, `rainbow`, `coinbase_wallet`, etc. */ walletClientType?: string /** * The connector type used for this wallet during the most recent verification. * * This includes but is not limited to `injected`, `wallet_connect`, `coinbase_wallet`, `embedded`. */ connectorType?: string /** * If this is a 'privy' embedded wallet, stores the recovery method: * * 1. 'privy': privy escrow of the recovery material * 2. 'user-passcode': recovery protected by user-input passcode */ recoveryMethod?: 'privy' /** Whether the wallet is imported. Only applies to embedded wallets (`walletClientType === 'privy'`). */ imported: boolean /** Whether the wallet is delegated. Only applies to embedded wallets (`walletClientType === 'privy'`). */ delegated: boolean /** HD index for the wallet. Only applies to embedded wallets (`walletClientType === 'privy'`). */ walletIndex: number | null } ``` ### CreateWalletOptions ```ts /** Options for Privy's `createWallet` method */ type CreateWalletOptions = | { /** * Whether or not to create an additional Ethereum embedded wallet for a user that already has * an Ethereum embedded wallet. If this is set to `true` and the user does not already have an Ethereum * embedded wallet, `createWallet` will throw an error. * * Defaults to `false`. */ createAdditional?: boolean } | { /** * Specify the hierarchical deterministic (HD) index of the embedded wallet to create. * **A wallet with HD index 0 must be created before creating a wallet at greater HD indices.** * If a value < 0 is passed in, `createWallet` will throw an error. * If a value > 1 is passed in, and the user does not have a primary wallet (HD index == 0), * `createWallet` will throw an error. * */ walletIndex: number } ``` ### UseFundWalletInterface ```ts /** * Method to fund a user's wallet via Privy's funding feature by inputting a valid wallet address. * You can access the fields and methods documented here via the `useFundWallet` hook. */ interface UseFundWalletInterface { /** * Prompt the user to go through the funding flow and for a specified wallet. * * This will open the modal with a prompt for the user to select a funding method (if multiple are enabled). * * Once the user continues to the funding flow, Privy will display the funding status screen, and wait * for the transaction to complete. * * Note: Even after a successful funding, funds can take a few minutes to arrive in the user's wallet. * * Privy currently supports funding via external wallets and Moonpay. * * @param address typed data payload to be signed * @param fundWalletConfig {@link FundWalletConfig} Funding configuration to specify chain and funding amount (if enabled) */ fundWallet: ( address: string, fundWalletConfig?: FundWalletConfig, ) => Promise } ``` ### ConnectedWallet ```ts /** * Object representation of a connected wallet, with additional Privy flows */ interface ConnectedWallet extends BaseConnectedEthereumWallet, PrivyConnectedWallet { /** * Prompt the user to go through the funding flow and for the connected wallet. * * This will open the modal with a prompt for the user to select a funding method (if multiple are enabled). * * Once the user continues to the funding flow, Privy will display the funding status screen, and wait * for the transaction to complete. * * Note: Even after a successful funding, funds can take a few minutes to arrive in the user's wallet. * * Privy currently supports funding via external wallets and Moonpay. * * @param {FundWalletConfig} fundWalletConfig Funding configuration to specify chain and funding amount (if enabled) * **/ fund: (fundWalletConfig?: FundWalletConfig) => Promise } ``` ### PrivyConnectedWallet ```ts interface PrivyConnectedWallet { /** True if this wallet is linked to the authenticated user. False if it is not yet linked or * the user has not yet authenticated. */ linked: boolean /** Login with this wallet or link this wallet to the authenticated user. * * Throws a PrivyClientError if the wallet is not connected. */ loginOrLink: () => Promise /** Unlink this wallet to the authenticated user. Throws a PrivyClientError if the user is not * authenticated. */ unlink: () => Promise /** The HD wallet index */ walletIndex?: number } ``` ### BaseConnectedEthereumWallet ```ts /** * Object representation of a base connected Ethereum wallet from a wallet connector. */ interface BaseConnectedEthereumWallet extends BaseConnectedWallet { type: 'ethereum' /** The current chain ID with CAIP-2 formatting. */ chainId: string /** * Switch the network chain to a specified ID. * Note: The chainId must be a supported network: https://docs.privy.io/guide/frontend/embedded/networks * Note: This will not update any existing provider instances, re-request `wallet.getEthereumProvider` (e.g.) * to get a provider with the updated chainId. * * @param targetChainId The specified chain ID to switch to, as a number or 0x prefixed string. * @returns void */ switchChain: (targetChainId: `0x${string}` | number) => Promise /** Helper methods to build providers for interfacing with this wallet. */ getEthereumProvider: () => Promise /** * Perform personal_sign with the user's wallet. * * @param {string} message The message to sign. * @returns {string} The resulting signature. */ sign: (message: string) => Promise } ``` ### BaseConnectedWallet ```ts /** * Object representation of a base connected wallet from a wallet connector. */ interface BaseConnectedWallet { type: 'ethereum' | 'solana' /** The wallet address. */ address: string /** The first time this wallet was connected without break. */ connectedAt: number /** * The wallet client where this key-pair is stored. * e.g. metamask, rainbow, coinbase_wallet, etc. */ walletClientType: WalletClientType /** * The connector used to initiate the connection with the wallet client. * e.g. injected, wallet_connect, coinbase_wallet, etc. */ connectorType: ConnectorType /** Whether the wallet is imported. */ imported: boolean /** * Metadata for the wallet. */ meta: ConnectedWalletMetadata /** Returns true if the wallet is connected, false otherwise */ isConnected: () => Promise /** * @experimental **Experimental**: This property is subject to change at any time. * * Not all wallet clients support programmatic disconnects (e.g. MetaMask, Phantom). * In kind, if the wallet's client does not support programmatic disconnects, * this method will no-op. */ disconnect: () => void } ``` ### Waiting for Privy to be Ready When the `PrivyProvider` is first rendered on your page, the Privy SDK will initialize some state about the current user. This initialization process includes: - Checking if the user has a wallet connected - Refreshing expired auth tokens - Fetching up-to-date user data It's crucial to wait until the `PrivyProvider` has finished initializing before consuming Privy's state and interfaces to ensure that the state you consume is accurate and not stale. To determine whether the Privy SDK has fully initialized on your page, check the `ready` Boolean returned by the `usePrivy` hook: ```tsx const { ready } = usePrivy(); ``` When `ready` is `true`, Privy has completed initialization, and your app can safely consume Privy's state and interfaces. You should wait for `ready` to be `true` before using any other methods or variables returned by the `usePrivy` hook. Here's an example of properly handling the initialization state: ```tsx import { usePrivy } from '@privy-io/react-auth' function PrivyComponent() { const { ready, authenticated, login } = usePrivy() if (!ready) { return

} return (

{authenticated ? (

Welcome back!

) : ( )}

) } ``` ## Common Workflows ### Authentication #### Login and Sign Up ```tsx import { usePrivy } from '@privy-io/react-auth' function LoginButton() { const { ready, authenticated, login } = usePrivy() // Disable login when Privy is not ready or the user is already authenticated const disableLogin = !ready || (ready && authenticated) return ( ) } ``` #### Logout ```tsx import { usePrivy } from '@privy-io/react-auth' function LogoutButton() { const { logout } = usePrivy() return } ``` ### Wallet Management #### Linked Wallets ##### Link a Wallet ```tsx import { usePrivy } from '@privy-io/react-auth' function LinkWalletButton() { const { linkWallet } = usePrivy() return } ``` ##### List Linked Wallets ```tsx import { useWallets } from '@privy-io/react-auth' const Wallets = () => { const { wallets, ready } = useWallets() if (!ready) { return

} return (

{wallets.map((wallet) => (

{wallet.address}

))}

) } ``` ##### Fund Linked Wallet ```tsx import { useFundWallet } from '@privy-io/react-auth' function FundWalletButton() { const { fundWallet } = useFundWallet() const WALLET_ADDRESS = 'WALLET_ADDRESS' return ( ) } ``` ##### Initiate Linked Wallet Transfer To request a transaction from a wallet, first find your desired wallet from the wallets array and get its EIP-1193 provider via its `getEthereumProvider` method. Then, use the provider to send a transaction request. ```tsx import { useWallets } from '@privy-io/react-auth' function SendTransactionButton() { const { wallets } = useWallets() const sendTransaction = async () => { const wallet = wallets[0] // Replace this with your desired wallet const provider = await wallet.getEthereumProvider() const transactionRequest = { to: '0xTheRecipientAddress', // Replace with recipient address value: 100000, } const transactionHash = await provider.request({ method: 'eth_sendTransaction', params: [transactionRequest], }) console.log('Transaction Hash:', transactionHash) } return } ``` #### Embedded Wallet ##### Create Embedded Wallet This will create a new embedded wallet for the user. If the user already has an embedded wallet, this will throw an error. ```tsx import { usePrivy } from '@privy-io/react-auth' function CreateWalletButton() { const { createWallet } = usePrivy() return } ``` ##### Sign Embedded Wallet Message ```tsx import { usePrivy } from '@privy-io/react-auth' function SignMessageButton() { const { signMessage } = usePrivy() // Whatever message you'd like to sign const message = 'Hello, world!' return ( ) } ``` ```tsx import { usePrivy } from '@privy-io/react-auth' function SendTransactionButton() { const { sendTransaction } = usePrivy() const sendTransaction = async () => { const transactionRequest = { to: '0xTheRecipientAddress', // Replace with recipient address value: 100000, } const { hash } = await sendTransaction(transactionRequest) console.log('Transaction Hash:', hash) } return } ``` ## Additional Resources - [Privy Documentation](https://docs.privy.io/guide/react/) - [privy-io/react-auth](https://www.npmjs.com/package/@privy-io/react-auth) - [Next.js Documentation](https://nextjs.org/docs) --- This was a guide on integrating Privy SDK (@privy-io/react-auth) in a Next.js app. For more information, refer to the official documentation.

CoinPlexity