Setup Embedded Wallets

If you are a current user of our legacy embedded wallets, you can find the migration guide here and any legacy documentation here (only creating and reveal/unlinking are different).

General Setup

Enable in Dashboard

Navigate to the Dynamic Dashboard > Developers and enable Embedded Wallets, then click settings and choose the chains you’d like wallets created on.

Using your UI

React

Only supported on React SDK v4.20.0 and later versions

Reference example: https://github.com/dynamic-labs/examples/tree/main/examples/nextjs-mpc-demo

1. Install Wallet Connectors

   Note: You only need to install the connectors for the chains you want to support.

   npm i @dynamic-labs/sdk-react-core
   npm i @dynamic-labs/ethereum
   npm i @dynamic-labs/solana
   npm i @dynamic-labs/sui
   

2. Configure CSP

   You must whitelist the dynamic auth URL for the iframe connection to work. Here’s how:

   In an HTTP header (e.g., Express.js)

   res.setHeader("Content-Security-Policy", "frame-src https://app.dynamicauth.com 'self';");
   

   ⚠️ If you’re already setting CSP, append https://app.dynamicauth.com to the existing frame-src list rather than replacing it.

   ---

   In an HTML `<meta>` tag

   <meta http-equiv="Content-Security-Policy" content="frame-src https://app.dynamicauth.com 'self';">
   

   In NGINX config

   add_header Content-Security-Policy "frame-src https://app.dynamicauth.com 'self';";
   

   In Vercel or Netlify (via headers file)

   vercel.json

   {
     "headers": [
       {
         "source": "/(.*)",
         "headers": [
           {
             "key": "Content-Security-Policy",
             "value": "frame-src https://app.dynamicauth.com 'self';"
           }
         ]
       }
     ]
   }
   

   In _headers (Netlify)

   _headers

     Content-Security-Policy: frame-src https://app.dynamicauth.com 'self';
   

3. Configure Your Provider

   Include the appropriate connectors inside your provider settings:

   import { EthereumWalletConnectors } from '@dynamic-labs/ethereum';
   import { SolanaWalletConnectors } from '@dynamic-labs/solana';
   import { SuiWalletConnectors } from '@dynamic-labs/sui';
   
   const connectors: [
       EthereumWalletConnectors,
       SolanaWalletConnectors,
       SuiWalletConnectors,
     ],
   
   return (
     <DynamicContextProvider
       settings={{
         walletConnectors: connectors,
       }}
     >
       {/* Your app components */}
     </DynamicContextProvider>
   );
   

   Now, once logged in, users will have an embedded wallet for each chain you have enabled. For more detailed options around wallet creation, see the Creating Wallets guide.

4. Use the Wallet Just Like Any Other

   You can find plenty of examples in Using Wallets. Here’s a simple example of fetching the public and wallet client on Ethereum.

   import { useDynamicContext } from '@dynamic-labs/sdk-react-core';
   import { isEthereumWallet } from '@dynamic-labs/ethereum';
   
   const { primaryWallet } = useDynamicContext();
   
   if (!isEthereumWallet(primaryWallet)) return;
   
   const publicClient = await primaryWallet.getPublicClient();
   const walletClient = await primaryWallet.getWalletClient();
   

5. Access Functionality Through the Connector Directly

   For certain functionality, you will need to access the connector directly and type it as a DynamicWaasEVMConnector, DynamicWaasSVMConnector or DynamicWaasSuiConnector.

   Here’s an example for Ethereum.

   import { isDynamicWaasConnector } from '@dynamic-labs/wallet-connector-core';
   
   if(!primaryWallet || !isDynamicWaasConnector(primaryWallet.connector)) {
     return;
   }
   
   const waasConnector = primaryWallet.connector;
   
   const walletAccount = await waasConnector.createWalletAccount();
   
   //  get a wallet client for the wallet account by address
   await waasConnector.getWalletClientByAddress({
     accountAddress: walletAccount.accountAddress,
   });
   
    // Export the client keyshares, a txt file will be downloaded on the client
   await waasConnector.exportClientKeyshares({
     accountAddress: walletAccount.accountAddress,
   });
   
   // Export the private key (requires a display container for security)
   await waasConnector.exportPrivateKey({
     accountAddress: walletAccount.accountAddress,
     displayContainer: document.createElement('iframe'), // Replace with your secure container
   });
   
   // Import a private key to create a new wallet
   const importedWallet = await waasConnector.importPrivateKey({
     privateKey: 'your-private-key-here', // Replace with actual private key
   });