> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dynamic.xyz/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Embedded wallets: password & security

> The React SDK popped a password modal for you on the first wallet action. In the JavaScript SDK you check whether a password is needed and run the set, unlock, and change flows yourself.

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)](/docs/javascript/building-ui/embedded-wallet-security) 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`                                   |

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

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.

<Warning>
  `walletReadyState` is a plain string (`'encrypted'` / `'ready'`) — compare against the literals. There is no publicly exported `WalletReadyState` enum to import.
</Warning>

## 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.                           |

## See also

* [Embedded wallet security (Building UI)](/docs/javascript/building-ui/embedded-wallet-security) — the full unlock gate and password screens
* [Embedded wallets: setup & creation](/docs/javascript/migrating-from-react/embedded-wallets-setup) — where the password is first supplied
* Embedded wallets: backup & recovery — recovering access when the password is lost
* [Post-login user setup](/docs/javascript/migrating-from-react/post-login-user-setup) — running the unlock check right after login