When a project protects embedded (WaaS) wallets with a password, the React SDK handled it invisibly: the widget prompted on the first wallet action of a session and exposed useWalletPassword() for setting and changing it. The JavaScript SDK gives you the same operations as functions and React hooks and leaves the prompting to you.
Building the password screens (set during setup, unlock on a new device, change) is the same in any JavaScript SDK app, so it isn’t repeated here: Embedded wallet security (Building UI) covers it with full code. This page is the React→JavaScript translation plus the migration-specific behavior.
What maps to what
The widget prompted automatically on the first wallet action; you now do it yourself, once per session:
- Decide if this session is locked with
getWalletRecoveryState({ walletAccount }). Its walletReadyState is 'encrypted' when this device’s key share is still locked (prompt for the password) and 'ready' once unlocked. Run it after sign-in — the moment the widget used to prompt.
- Unlock once, not per action. After a successful
unlockWallet() the state flips to 'ready', so the same check stops prompting. Don’t gate every wallet action on it — unlock once and keep signing.
isPasswordRequiredForWaasWallets() answers a different question — whether the user has set a password at all, not whether this session is unlocked. Use it to decide whether to offer the “set a password” flow; use getWalletRecoveryState() to gate unlocking.
walletReadyState is a plain string ('encrypted' / 'ready') — compare against the literals. There is no publicly exported WalletReadyState enum to import.
Errors you now own
See also
