Skip to main content
Use a recoverable login before accepting funds into an embedded wallet. A guest account alone depends on local browser credentials. Reconnecting a wallet that funded a deposit does not link that wallet to the guest account automatically. This example uses Privy’s public headless APIs in @privy-io/react-auth@3.51.0. Authentication belongs to Privy and your app. Spice Flow continues to own balances, quotes, fees, funding, execution and transaction recovery.

Configure Privy

Enable wallet authentication and allow the exact origin in your Privy app. SIWE verifies a signed message from the user’s connected Ethereum wallet. It does not require a separate JWT login server or Privy’s login modal. Follow Installation, but disable automatic embedded-wallet creation for this reference:
Keep this setting off for every recovery entry point. createOnLogin: "all-users" could create a missing embedded wallet during authentication, before the reference checks the account. Existing guest wallets remain available. The reference preserves an accessible guest’s wallet and explicitly creates a wallet only when needed in the "new" path for an unfunded account. The "recover" path never creates a replacement wallet. For a new user, start with wallet sign-in through prepare("new") without first creating a guest. The guest-upgrade path requires the original guest wallet to already exist.

Use the reference

Copy the reference files into your application. useRecoverableWallet accepts your actual connected external wallet, including a function that reads its current address and a function that signs the requested message. Do not select wallets[0]: it may be the embedded wallet.
For a returning user who needs recovery, call session.prepare("recover") instead. This sets disableSignup: true on loginWithSiwe, so an unrecognized login cannot silently create a different account. The provider and hook must remain mounted while the SDK uses that session. Render authentication rejection or failure from the hook’s error state; do not continue funding.

Preserve an accessible guest

If the current user is a guest, keep that session authenticated and link the external wallet to it. The reference uses useLinkWithSiwe, then awaits useUser().refreshUser() instead of reading a stale React user value captured before linking. Before allowing funding, it verifies:
  • The Privy user ID and original embedded Ethereum wallet address are unchanged.
  • The external wallet is linked and the account is no longer a guest.
  • The connected embedded wallet matches the current user’s wallet metadata.
If the external wallet already belongs to another Privy account, preserve the guest session and resolve the conflict. Do not log out, delete the guest, or try to merge its funded wallet into the other account. Privy does not support that guest-account merge. useLinkWithSiwe is marked experimental in this Privy version; verify the exact version used by your application.

Return after losing a browser session

Sign in with the external wallet linked to the account. Privy should return the same user and embedded wallet. The recovery path refuses to create a wallet if the existing one is missing. After authentication, let the SDK read that account’s authoritative balance and existing actions. A successful login is not permission to replay an earlier deposit or payout. A submitted action must still be reconciled through its existing SDK/backend recovery path. If an unpaid withdrawal is canceled, its reserved balance becomes available in the same account; a subsequent withdrawal requires a fresh authorized action. See original-operation recovery. If a guest’s credentials are already lost and no recoverable login or other authorized recovery method was established beforehand, this reference cannot restore that anonymous account. Creating a new guest does not regain access to the old wallet. Privy documents a 30-day guest session limit; normal short-lived token refresh is a separate mechanism.

Verify the integration before accepting funds

Test the actual app origin and exact installed Privy package:
  1. Link an accessible guest and confirm that its user ID and embedded wallet remain unchanged.
  2. Close the browser context, then sign in from a clean context with the linked wallet.
  3. Confirm the same embedded wallet can sign a harmless test message and the SDK reads its balance.
  4. Reject an unrecognized recovery login, a rejected signature and a conflicting linked credential without creating another account or discarding the original guest.
The reference’s offline authentication checks run with Node.js 22:
Those checks do not establish the live app’s authentication or financial acceptance. Also test your complete funding, destination delivery and application finalization through the SDK.

Reference files

Copy sequence.ts and useRecoverableWallet.ts into the same directory in your application. The third tab contains the offline authentication tests.

Privy references