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

# useDynamicWaas

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

## Summary

A React hook that provides functionality for managing Dynamic MPC wallets. This hook enables wallet creation, management, and interaction with Dynamic's embedded wallet system.

## Return Value

```typescript theme={"system"}
type WalletCreationRequirement = {
  chain: ChainEnum;
  bitcoinConfig?: { addressType?: string; network?: string };
};

{
  createWalletAccount: (
    requirementsOrChainNames?: WalletCreationRequirement[] | ChainEnum[],
    password?: string,
    bitcoinConfig?: { addressType?: string; network?: string },
  ) => Promise<Array<WalletAccount | undefined>>;
  dynamicWaasIsEnabled: boolean;
  getWaasWallets: () => Array<Wallet>;
  getWaasWalletConnector: (chainName: string) => IDynamicWaasConnector | undefined;
  importPrivateKey: (params: { chainName: string; privateKey: string }) =>
    Promise<void>;
  shouldAutoCreateDynamicWaasWallet: boolean;
  upgradeToDynamicWaas: (params: { privateKey: string, wallet: Wallet }) => Promise<void>;
}
```

## Functions

### createWalletAccount

Creates wallet accounts for enabled chains in the project settings. This function can create wallets for one or more specified chains. Optionally accepts a password to create a password-protected wallet. See [Password encryption](/react/wallets/embedded-wallets/mpc/password-encryption) for details.

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

// Create wallets for all enabled chains
const wallets = await createWalletAccount();

// Create wallet for a specific chain
const evmWallet = await createWalletAccount([ChainEnum.Evm]);

// Create wallets for multiple chains
const wallets = await createWalletAccount([ChainEnum.Evm, ChainEnum.Sol]);

// Create a password-protected wallet for a specific chain
const secureEvmWallet = await createWalletAccount(
  [ChainEnum.Evm],
  'your-strong-password'
);
```

**Parameters:**

* `requirementsOrChainNames?`: `WalletCreationRequirement[] | ChainEnum[]` - Optional. When omitted, creates wallets for all enabled chains. Pass `WalletCreationRequirement[]` to attach per-chain config (e.g. `bitcoinConfig` for BTC), or `ChainEnum[]` for the legacy form.
* `password?`: string - Optional password to protect the wallet.
* `bitcoinConfig?`: `{ addressType?: string; network?: string }` - Optional. Applied to any `ChainEnum.Btc` entry when using the legacy `ChainEnum[]` form. Ignored when using `WalletCreationRequirement[]` (set `bitcoinConfig` per-requirement instead).

**Bitcoin example:**

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

// Recommended: per-requirement config
await createWalletAccount([
  {
    chain: ChainEnum.Btc,
    bitcoinConfig: {
      addressType: 'native_segwit', // or 'taproot'
      network: 'mainnet',
    },
  },
]);

// Legacy form: bitcoinConfig as third arg
await createWalletAccount(
  [ChainEnum.Btc],
  undefined,
  { addressType: 'taproot', network: 'mainnet' },
);
```

**Returns:** Promise resolving to an array of created wallet accounts. Each wallet account in the array will have the following structure:

```typescript theme={"system"}
{
  id: string;
  chainName: string;
  provider: WalletProviderEnum.EmbeddedWallet;
  accountAddress?: string;
}
```

**Behavior:**

* Creates wallet accounts for the specified chains in parallel
* After creation, it will:
  1. Find the primary wallet account (based on the chain marked as primary in settings)
  2. Refresh the user data to get the latest wallet information
  3. Update the primary wallet to the newly created wallet
  4. Close any open auth flow modals

**Throws:**

* `NO_ENABLED_CHAINS_ERROR` if no chains are enabled in the project settings
* `DYNAMIC_WAAS_CONNECTOR_NOT_FOUND_ERROR` if a wallet connector is not found for an enabled chain
* Any errors from the underlying wallet creation process

**Example:**

```typescript theme={"system"}
try {
  // Create wallets for all enabled chains
  const wallets = await createWalletAccount();
  // Example return value:
  // [
  //   {
  //     id: "wallet-1",
  //     chainName: "EVM",
  //     provider: WalletProviderEnum.EmbeddedWallet,
  //     accountAddress: "0x123..."
  //   },
  //   {
  //     id: "wallet-2",
  //     chainName: "SOL",
  //     provider: WalletProviderEnum.EmbeddedWallet,
  //     accountAddress: "0x456..."
  //   }
  // ]

  // Create wallet for EVM chain only
  const evmWallet = await createWalletAccount([ChainEnum.Evm]);
  // Example return value:
  // [
  //   {
  //     id: "wallet-1",
  //     chainName: "EVM",
  //     provider: WalletProviderEnum.EmbeddedWallet,
  //     accountAddress: "0x123..."
  //   }
  // ]
} catch (error) {
  if (error.message === NO_ENABLED_CHAINS_ERROR) {
    // Handle no enabled chains error
  } else if (error.message === DYNAMIC_WAAS_CONNECTOR_NOT_FOUND_ERROR) {
    // Handle missing wallet connector error
  } else {
    // Handle other errors
  }
}
```

### getWaasWalletConnector

Retrieves a configured wallet connector for a specific chain.

```typescript theme={"system"}
const { getWaasWalletConnector } = useDynamicWaas();
const connector = getWaasWalletConnector('EVM');
```

**Parameters:**

* `chainName`: string - The name of the chain to get the connector for.

**Returns:** A configured `IDynamicWaasConnector` or `undefined` if:

* Cookie auth is disabled and no auth token is present
* No wallet connector options are available
* The environment ID is not set

**Throws:**

* `DYNAMIC_WAAS_CONNECTOR_NOT_FOUND_ERROR` if the wallet connector is not found.

## Password-protected wallets

For managing password-protected wallets (unlocking, updating passwords, checking recovery state), see the [useWalletPassword](/react/reference/hooks/embedded-wallets/usewalletpassword) hook.

### importPrivateKey

Imports a private key for a specific chain.

```typescript theme={"system"}
const { importPrivateKey } = useDynamicWaas();
await importPrivateKey({
  chainName: 'EVM',
  privateKey: '0x123...',
});
```

**Parameters:**

* `chainName`: string - The name of the chain to import the private key for.
* `privateKey`: string - The private key to import.

**Behavior:**

* Imports the private key for the specified chain
* Refreshes the user data after successful import
* Returns undefined if the wallet connector is not found

### getWaasWallets

Finds all Dynamic WaaS wallets associated with the user.

```typescript theme={"system"}
const { getWaasWallets } = useDynamicWaas();
const waasWallets = getWaasWallets();
```

**Returns:** Array of Dynamic WaaS wallets. Each wallet in the array will have the following structure:

```typescript theme={"system"}
{
  key: 'dynamicwaas';
  address: string;
  chain: string;
  isAuthenticated: boolean;
  // ... other wallet properties
}
```

**Behavior:**

* Filters the user's wallets to only return those with `key === 'dynamicwaas'`
* Returns an empty array if no Dynamic WaaS wallets are found
* The returned wallets can be used for chain-specific operations (e.g., transactions)

**Example:**

```typescript theme={"system"}
const waasWallets = getWaasWallets();
// Example return value:
// [
//   {
//     key: 'dynamicwaas',
//     address: '0x123...',
//     chain: 'EVM',
//     isAuthenticated: true
//   },
//   {
//     key: 'dynamicwaas',
//     address: '0x456...',
//     chain: 'SOL',
//     isAuthenticated: true
//   }
// ]
```

### upgradeToDynamicWaas

Upgrades the users current primary wallet (assuming it's legacy) to a Dynamic WaaS wallet.

```typescript theme={"system"}
const { upgradeToDynamicWaas } = useDynamicWaas();
await upgradeToDynamicWaas({
  privateKey: '0x123...',
  wallet: Wallet
});
```

**Parameters:**

* `privateKey`: string - The private key of the legacy embedded wallet to upgrade, must be associated with the user's current primary wallet.
* `wallet`: Wallet - The wallet to upgrade.

**Throws:**

* `Primary wallet not found` if the primary wallet is not found
* `Wallet connector not found` if the wallet connector is not found
* `Upgrade failed` if there are any errors from the underlying wallet upgrade process

**Behavior:**

* Upgrades the legacy embedded wallet associated with the private key to a Dynamic MPC wallet
* Removes access to the previous legacy embedded wallet and replaces it with a new Dynamic embedded wallet

**Notes:**

* This is a one-way upgrade. Once a user has upgraded to v3 and received a new v3 wallet, they will lose access to their v1 or v2 embedded wallet.
* We recommend that you prompt your user to confirm they do not have any funds in their wallet before making this switch.
* The user must be logged in, and the private key must be associated with the user's current primary wallet.

## Properties

### dynamicWaasIsEnabled

Indicates whether Dynamic WaaS is enabled in the project settings.

```typescript theme={"system"}
const { dynamicWaasIsEnabled } = useDynamicWaas();
if (dynamicWaasIsEnabled) {
  // Dynamic WaaS is available
}
```

### shouldAutoCreateDynamicWaasWallet

Indicates whether a Dynamic WaaS wallet should be automatically created.

```typescript theme={"system"}
const { shouldAutoCreateDynamicWaasWallet } = useDynamicWaas();
if (shouldAutoCreateDynamicWaasWallet) {
  // Auto-create wallet logic
}
```

## Important Notes

1. **Authentication Requirements:**

   * The hook requires either cookie authentication or a valid auth token to function properly.
   * Wallet connector operations will return undefined if authentication is not available.

2. **Chain Configuration:**

   * Wallet creation and operations require properly configured chains in the project settings.
   * At least one chain must be enabled for wallet creation to work.

3. **Version Compatibility:**

   * Dynamic WaaS is only enabled when using EmbeddedWalletVersionEnum.V3.
   * The hook will not function with older wallet versions (V1 or V2).

4. **Auto-Creation Behavior:**

   * Auto-creation of wallets is controlled by project settings.
   * Separate settings exist for external wallet users.
   * Auto-creation will not occur if the user already has a Dynamic WaaS wallet.

5. **Relay Configuration:**
   * The hook uses a relay URL for wallet operations, which can be configured in project settings.
   * If not specified, it defaults to 'relay.dynamic-preprod.xyz'.

## Example Usage

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

function WalletManager() {
  const {
    createWalletAccount,
    dynamicWaasIsEnabled,
    getWaasWallets,
    importPrivateKey,
    shouldAutoCreateDynamicWaasWallet,
  } = useDynamicWaas();

  const handleCreateWallet = async () => {
    if (dynamicWaasIsEnabled) {
      // Create wallets for all enabled chains
      const wallets = await createWalletAccount();
      console.log('Created wallets:', wallets);

      // Or create wallet for a specific chain
      const evmWallet = await createWalletAccount([ChainEnum.Evm]);
      console.log('Created EVM wallet:', evmWallet);
    }
  };

  const handleImportKey = async () => {
    await importPrivateKey({
      chainName: 'EVM',
      privateKey: '0x123...',
    });
  };

  // Example of using getWaasWallets
  const waasWallets = getWaasWallets();
  const evmWallets = waasWallets.filter((wallet) => wallet.chain === 'EVM');

  return (
    <div>
      {shouldAutoCreateDynamicWaasWallet && (
        <button onClick={handleCreateWallet}>Create Wallet</button>
      )}
      <button onClick={handleImportKey}>Import Private Key</button>
      {evmWallets.length > 0 && (
        <div>
          <h3>Your EVM Wallets:</h3>
          {evmWallets.map((wallet) => (
            <div key={wallet.address}>Address: {wallet.address}</div>
          ))}
        </div>
      )}
    </div>
  );
}
```