Importing & exporting embedded wallet keys

Import a raw private key into a WaaS wallet, or let users export their embedded wallet private keys in the Flutter SDK.

Importing a private key

Use wallets.waas.importPrivateKey to import an existing raw private key into a Dynamic WaaS (MPC) wallet. The key is forwarded to the WaaS connector, which generates the MPC key shares for the wallet’s chain. The connector is resolved from the supplied chain, so no wallet id is required, and the raw key never leaves the webview after the call returns.

import 'package:dynamic_sdk/dynamic_sdk.dart';

Future<void> importKey(String privateKey) async {
  final result = await DynamicSDK.instance.wallets.waas.importPrivateKey(
    chain: WaasChain.evm,
    privateKey: privateKey,
  );
  print('Imported wallet ${result.walletId} at ${result.accountAddress}');
}

Parameters

chain · WaasChain · required

The WaaS connector to import into: WaasChain.evm, WaasChain.svm, WaasChain.btc, WaasChain.sui, or WaasChain.ton.

privateKey · String · required

The raw private key to import.

thresholdSignatureScheme · ThresholdSignatureScheme

Optionally override the signature scheme: twoOfTwo (default), twoOfThree, or threeOfFive.

addressType · BtcAddressType

Bitcoin address type: nativeSegwit or taproot. Required when chain is WaasChain.btc; ignored for other chains.

publicAddressCheck · String

Optionally assert the resulting public address. The import is rejected when the derived address does not match.

password · String

Optionally password-protect the newly created WaaS wallet. This does not unlock an existing wallet.

Return value

importPrivateKey resolves with an ImportPrivateKeyResult:

walletId · String?

The Dynamic wallet id of the wallet the imported key now backs, when the webview reported it.

accountAddress · String?

The public address derived from the imported key, when reported.

alreadyImported · bool

true when the key already backed one of the user’s wallets. In that case the server answers 409 duplicate_wallet_import and the call resolves with the existing wallet’s id instead of throwing, so a resumed migration can safely re-fire imports.

isConfirmed · bool

true when walletId is present. A false value does not mean the import failed: older bundles resolve without a payload, which yields an unconfirmed result. In that case confirm the import through auth.refreshUser() and wallets.userWallets.

raw · Map<String, dynamic>

The resolve payload, verbatim. Empty when the webview resolved with no payload.

Importing a Bitcoin key

When importing into WaasChain.btc, an addressType is required:

await DynamicSDK.instance.wallets.waas.importPrivateKey(
  chain: WaasChain.btc,
  privateKey: privateKey,
  addressType: BtcAddressType.nativeSegwit,
);

Exporting embedded wallet keys

Dynamic allows users to export their embedded wallet private keys for maximum control and portability. 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, ensure you surface this flow to your end-users so 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.

Revealing the private key

To open the export wallet flow on behalf of your users, call revealEmbeddedWalletPrivateKey() on the SDK’s UI module. This presents a secure flow where only the end-user can see their private key.

final sdk = DynamicSDK.instance;

sdk.ui.revealEmbeddedWalletPrivateKey();

Example

import 'package:dynamic_sdk/dynamic_sdk.dart';
import 'package:flutter/material.dart';

class RevealPrivateKeyButton extends StatelessWidget {
  const RevealPrivateKeyButton({super.key});

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: () {
        final sdk = DynamicSDK.instance;
        sdk.ui.revealEmbeddedWalletPrivateKey();
      },
      child: const Text('Reveal Private Key'),
    );
  }
}

You should always provide your end-users with a path to reveal and replicate their keys from their embedded wallet. When using a custom UI embedded wallet flow, ensure you add a path for users to complete this step using the method 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.