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

# useWalletPassword

<Card title="Recommended: JavaScript SDK with React Hooks" icon="react" color="#4779FE">
  For new React apps, we recommend the JavaScript SDK with React Hooks (`@dynamic-labs-sdk/react-hooks`) instead of the legacy React SDK documented here. The JS SDK comes with many benefits such as a much smaller bundle size and other optimizations. Use the [React quickstart (JavaScript SDK)](/javascript/reference/react-quickstart) to get started.
</Card>

<Warning>
  Only available from v4.61.0 onwards.
</Warning>

### Summary

The `useWalletPassword` hook provides methods to manage wallet password functionality for Dynamic WaaS embedded wallets, allowing users to update passwords, unlock wallets, and check wallet lock states.

To create a wallet with a password, use the [`createWalletAccount`](/react/reference/hooks/embedded-wallets/usedynamicwaas#createwalletaccount) function with the `password` parameter.

The hook needs to be initialized within a child of [DynamicContextProvider](/react/reference/providers/dynamiccontextprovider).

### Functions

#### `updatePassword`

Updates the password for an embedded wallet. Can be used to set an initial password or change an existing one.

**Parameters:**

* `params`: Object containing:
  * `accountAddress`: string - The wallet address
  * `chainName`: ChainEnum - The chain the wallet is associated with
  * `newPassword`: string - The new password to set
  * `existingPassword` (optional): string - The current password (required when changing an existing password)

**Returns:** `Promise<boolean>` - `true` if password update was successful, `false` otherwise.

**Example:**

```typescript theme={"system"}
import { ChainEnum } from '@dynamic-labs/sdk-api-core';
const { updatePassword } = useWalletPassword();

// Set initial password
const success = await updatePassword({
  accountAddress: '0x123...',
  chainName: ChainEnum.Evm,
  newPassword: 'mySecurePassword123',
});

// Change existing password
const changed = await updatePassword({
  accountAddress: '0x123...',
  chainName: ChainEnum.Evm,
  newPassword: 'newSecurePassword456',
  existingPassword: 'mySecurePassword123',
});

if (success) {
  console.log('Password updated successfully');
}
```

#### `unlockWallet`

Unlocks a wallet using the provided password. Once unlocked, the wallet remains unlocked for the rest of the user session.

**Parameters:**

* `params`: Object containing:
  * `accountAddress`: string - The wallet address
  * `chainName`: ChainEnum - The chain the wallet is associated with
  * `password`: string - The password to unlock the wallet

**Returns:** `Promise<boolean>` - `true` if wallet was unlocked successfully, `false` otherwise.

**Example:**

```typescript theme={"system"}
import { ChainEnum } from '@dynamic-labs/sdk-api-core';
const { unlockWallet } = useWalletPassword();

const success = await unlockWallet({
  accountAddress: '0x123...',
  chainName: ChainEnum.Evm,
  password: 'mySecurePassword123',
});

if (success) {
  console.log('Wallet unlocked successfully');
}
```

#### `checkWalletLockState`

Checks the current lock/recovery state of a wallet.

**Parameters:**

* `params`: Object containing:
  * `accountAddress`: string - The wallet address
  * `chainName`: ChainEnum - The chain the wallet is associated with

**Returns:** `Promise<WalletRecoveryState | null>` - The wallet's recovery state, or `null` if the check failed.

**Example:**

```typescript theme={"system"}
import { ChainEnum } from '@dynamic-labs/sdk-api-core';
const { checkWalletLockState } = useWalletPassword();

const recoveryState = await checkWalletLockState({
  accountAddress: '0x123...',
  chainName: ChainEnum.Evm,
});

if (recoveryState) {
  console.log('Wallet recovery state:', recoveryState);
}
```

#### `resetState`

Resets the hook's state back to its initial values, clearing any errors and loading states.

**Returns:** `void`

**Example:**

```typescript theme={"system"}
const { resetState } = useWalletPassword();

// Clear any previous errors or state
resetState();
```

### Properties

#### `state`

An object containing the current state of wallet password operations.

**Type:** `WalletPasswordState`

```typescript theme={"system"}
interface WalletPasswordState {
  isLoading: boolean;
  error: string | null;
  recoveryState: WalletRecoveryState | null;
}
```

**Example:**

```typescript theme={"system"}
const { state } = useWalletPassword();

if (state.isLoading) {
  console.log('Operation in progress...');
}

if (state.error) {
  console.error('Error:', state.error);
}

if (state.recoveryState) {
  console.log('Recovery state:', state.recoveryState);
}
```

### Usage

```typescript theme={"system"}
import { useWalletPassword } from '@dynamic-labs/sdk-react-core';
import { ChainEnum } from '@dynamic-labs/sdk-api-core';

const MyComponent = () => {
  const { 
    updatePassword,
    unlockWallet,
    checkWalletLockState,
    state,
    resetState
  } = useWalletPassword();

  const handleSetPassword = async () => {
    const success = await updatePassword({
      accountAddress: '0x123...',
      chainName: ChainEnum.Evm,
      newPassword: 'mySecurePassword',
    });

    if (success) {
      console.log('Password set successfully');
    }
  };

  const handleUnlock = async () => {
    const success = await unlockWallet({
      accountAddress: '0x123...',
      chainName: ChainEnum.Evm,
      password: 'mySecurePassword',
    });

    if (success) {
      console.log('Wallet unlocked');
    }
  };

  return (
    <div>
      <button onClick={handleSetPassword} disabled={state.isLoading}>
        Set Password
      </button>
      
      <button onClick={handleUnlock} disabled={state.isLoading}>
        Unlock Wallet
      </button>
      
      {state.isLoading && <p>Processing...</p>}
      
      {state.error && (
        <div>
          <p>Error: {state.error}</p>
          <button onClick={resetState}>Clear Error</button>
        </div>
      )}
    </div>
  );
};
```

### Return Value

The hook returns an object with the following properties:

```typescript theme={"system"}
{
  updatePassword: (params: UpdatePasswordParams) => Promise<boolean>;
  unlockWallet: (params: UnlockWalletParams) => Promise<boolean>;
  checkWalletLockState: (params: CheckWalletLockStateParams) => Promise<WalletRecoveryState | null>;
  state: WalletPasswordState;
  resetState: () => void;
}
```

### Types

```typescript theme={"system"}
type UpdatePasswordParams = {
  accountAddress: string;
  chainName: ChainEnum;
  newPassword: string;
  existingPassword?: string;
};

type UnlockWalletParams = {
  accountAddress: string;
  chainName: ChainEnum;
  password: string;
};

type CheckWalletLockStateParams = {
  accountAddress: string;
  chainName: ChainEnum;
};

type WalletPasswordState = {
  isLoading: boolean;
  error: string | null;
  recoveryState: WalletRecoveryState | null;
};
```