Importing & Exporting Embedded Wallets

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.

General Setup

Formatting

Chain	✅ Import Format	✅ Export Format
EVM	Hexadecimal with or without 0x	Hexadecimal without 0x
Solana	Base58-encoded private key	Base58-encoded private key
Sui	Bech32-encoded private key	Bech32-encoded private key

Importing Wallet Keys

When importing an existing private key into Dynamic’s TSS-MPC system, we use Shamir Secret Sharing (SSS) to securely split the key into multiple shares. This process:

1. Takes your existing private key as input
2. Uses SSS to split it into either 2 or 3 shares (depending on your configuration)
3. Distributes the shares between the relevant parties (user, server, and optionally a backup)
4. Securely destroys the original private key

After import, the key exists solely in its distributed form, and all future operations are performed using TSS-MPC. The complete private key is never reconstructed, preserving the security benefits of TSS-MPC while enabling seamless migration from traditional wallets.

Using your UI

importPrivateKey(options) imports a private key. Available from the useDynamicWaas hook.

Parameters:

• privateKey: string - The private key to import
• thresholdSignatureScheme: ThresholdSignatureScheme - Defaults to ThresholdSignatureScheme.TWO_OF_TWO

import { useDynamicWaas } from "@dynamic-labs/sdk-react-core";
import { ThresholdSignatureScheme } from "@dynamic-labs-wallet/node";

const { importPrivateKey } = useDynamicWaas();

const privateKeyInput = "0x...";

await importPrivateKey({
  chainName: "EVM",
  privateKey: privateKeyInput,
  thresholdSignatureScheme: ThresholdSignatureScheme.TWO_OF_TWO,
});

Exporting Wallet Keys

For maximum user control and portability, Dynamic allows users to export their private keys. During export:

1. The key shares are temporarily recombined on the user’s device using secure MPC
2. The private key is constructed client side and provided to the user

This ensures users maintain true self-custody and can always access their assets, even outside of Dynamic’s ecosystem.

When implementing Dynamic in a custom UI, please ensure you are surfacing this flow to your end-users, so that they always maintain control of their wallet.

Private Key Export Settings

By default, users can export their private keys from embedded wallets. You can control this setting in the Embedded Wallets dashboard. Navigate to the Security section and toggle Private Key Exports to enable or disable private key exports.

Consider disabling private key exports if your use case requires additional security controls. Disabling exports prevents users from exporting keys, which can reduce the risk of key exposure but limits user portability. See Best Practices - Private Key Export Controls for guidance.

Using our UI

The Dynamic export flow reveals the private key/seed phrase in an secure isolated iFrame to limit the ability of Dynamic, the developer, or anyone in the flow to view the exported key. For more details on the security of the iframe and cryptographic flows go to our FAQs.

To open the export wallet flow on behalf of your users, you can call the initExportProcess method from the useEmbeddedReveal hook. This will open the flow described above. Only the end-user will be able to see the private key or seed phrase.

import { useEmbeddedReveal } from "@dynamic-labs/sdk-react-core";

const { initExportProcess } = useEmbeddedReveal();

<button onClick={() => initExportProcess()}>Export Wallet</button>;

You can see the experience by going to demo.dynamic.xyz and creating an embedded wallet.

You should always provide your end-users with a path to reveal and replicate their keys from their embedded wallet. When using the custom UI embedded wallet flow, please ensure you add a path for users to complete this step using the programmatic option described above.

End-users should be aware that replicating their wallet credentials can expose their wallet to risk if the credentials are not stored securely. Users are advised to store their credentials in a secure location and not share them with anyone. When implementing Dynamic in a custom UI, we recommend communicating these warnings to users.

Using your UI

exportPrivateKey(options)

The exportPrivateKey method uses the SDK to render into a secure, sandboxed, cross‑origin iframe you don’t control in order to display the private key in a secure manner. You cannot access or manipulate the iframe content.

Parameters:

• accountAddress: string - The address of the account to export
• displayContainer: HTMLIFrameElement - The container to display the private key in

import { useDynamicContext } from "@dynamic-labs/sdk-react-core";
import { DynamicWaasEVMConnector } from "@dynamic-labs/waas-evm";

 const containerRef = useRef<HTMLDivElement | null>(null);

const { primaryWallet } = useDynamicContext();

const handleExportPrivateKey = async () => {
  if (!primaryWallet?.address) {
    setErrorMessage("Please create a wallet first");
    return;
  }

 if (!containerRef.current) {
   setErrorMessage("Secure container is not ready");
   return;
 }

  const connector = primaryWallet?.connector as DynamicWaasEVMConnector;
  const privateKey = await connector.exportPrivateKey({
    accountAddress: primaryWallet?.address,
    displayContainer: containerRef.current
  });
};

exportClientKeyshares(options)

Exports client keyshares for a specific account as a download through a secure iframe.

Parameters:

• accountAddress: string - The address of the account to export keyshares for

import { useDynamicContext } from "@dynamic-labs/sdk-react-core";
import { DynamicWaasEVMConnector } from "@dynamic-labs/waas-evm";

const { primaryWallet } = useDynamicContext();

const handleExportKeyShares = async () => {
  if (!primaryWallet?.address) {
    setErrorMessage("Please create a wallet first");
    return;
  }

  const connector = primaryWallet?.connector as DynamicWaasEVMConnector;
  const keyShares = await connector.exportClientKeyshares({
    accountAddress: primaryWallet?.address,
  });
};