useDynamicWaas

Recommended: JavaScript SDK with React Hooks

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) to get started.

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

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 for details.

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:

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:

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

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.

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

importPrivateKey

Imports a private key for a specific chain.

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.

const { getWaasWallets } = useDynamicWaas();
const waasWallets = getWaasWallets();

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

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

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.

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.

const { dynamicWaasIsEnabled } = useDynamicWaas();
if (dynamicWaasIsEnabled) {
  // Dynamic WaaS is available
}

shouldAutoCreateDynamicWaasWallet

Indicates whether a Dynamic WaaS wallet should be automatically created.

const { shouldAutoCreateDynamicWaasWallet } = useDynamicWaas();
if (shouldAutoCreateDynamicWaasWallet) {
  // Auto-create wallet logic
}

Important Notes

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.
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.
Version Compatibility:
- Dynamic WaaS is only enabled when using EmbeddedWalletVersionEnum.V3.
- The hook will not function with older wallet versions (V1 or V2).
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.
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

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>
  );
}

Implementation Guides

SDK Reference

Recommended: JavaScript SDK with React Hooks

Summary

Return Value

Functions

createWalletAccount

getWaasWalletConnector

Password-protected wallets

importPrivateKey

getWaasWallets

upgradeToDynamicWaas

Properties

dynamicWaasIsEnabled

shouldAutoCreateDynamicWaasWallet

Important Notes

Example Usage

Recommended: JavaScript SDK with React Hooks

​Summary

​Return Value

​Functions

​createWalletAccount

​getWaasWalletConnector

​Password-protected wallets

​importPrivateKey

​getWaasWallets

​upgradeToDynamicWaas

​Properties

​dynamicWaasIsEnabled

​shouldAutoCreateDynamicWaasWallet

​Important Notes

​Example Usage

Summary

Return Value

Functions

createWalletAccount

getWaasWalletConnector

Password-protected wallets

importPrivateKey

getWaasWallets

upgradeToDynamicWaas

Properties

dynamicWaasIsEnabled

shouldAutoCreateDynamicWaasWallet

Important Notes

Example Usage