Embedded wallets: password & security

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

React SDK	JavaScript SDK
automatic password prompt on first wallet action	check `getWalletRecoveryState()`, then `unlockWallet()` yourself
`useWalletPassword().setPassword(...)`	`setWaasWalletAccountPassword()` / `useSetWaasWalletAccountPassword()`
`useWalletPassword().updatePassword(...)`	`updateWaasPassword()` / `useUpdateWaasPassword()`
`useWalletPassword().unlockWallet(...)`	`unlockWallet()` / `useUnlockWallet()`
`useWalletPassword().isLoading` / `.error`	the mutation’s `isPending` / `error`

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

Situation	What to do
Wrong password on unlock	The mutation rejects — surface the error and let the user retry.
Wrong `currentPassword` on change	`updateWaasPassword` rejects — keep the form open and show the error.
Action attempted before unlock	Check `getWalletRecoveryState()` after sign-in; if `'encrypted'`, prompt and `unlockWallet()`.
Password mismatch across wallets	Use one password per user — the same one protects every WaaS wallet.

JavaScript SDK Reference

Embedded wallets: password & security

What maps to what

Prompting for the password (what the widget did for you)

Errors you now own

See also

​What maps to what

​Prompting for the password (what the widget did for you)

​Errors you now own

​See also

What maps to what

Prompting for the password (what the widget did for you)

Errors you now own

See also