Skip to main content

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.

​
Overview

This guide shows you how to import existing Bitcoin private keys into Dynamic’s MPC wallet system. This is useful when migrating from traditional Bitcoin wallets or integrating with existing systems.

​
Prerequisites

​
WIF Format

Bitcoin private keys are imported in WIF (Wallet Import Format). WIF is a base58-encoded format that includes:
  • Network identifier (mainnet or testnet)
  • The 32-byte private key
  • Compression flag
  • Checksum
Example WIF formats:
  • Mainnet compressed: L... or K... (52 characters)
  • Testnet compressed: c... (52 characters)

​
Supported Address Types

When importing a private key, you must specify the address type. Currently supported:
  • Native SegWit (P2WPKH): BitcoinAddressType.NATIVE_SEGWIT
  • Taproot (P2TR): BitcoinAddressType.TAPROOT

​
Import Your Bitcoin Private Key

import { authenticatedBtcClient } from './client';
import { ThresholdSignatureScheme } from '@dynamic-labs-wallet/node';
import { BitcoinAddressType } from '@dynamic-labs-wallet/core';

const btcClient = await authenticatedBtcClient();

const wallet = await btcClient.importPrivateKey({
  privateKey: 'L1aW4aubDFB7yfras2S1mN3bqg9nwySY8nkoLmJebSLD5BWv3ENZ', // WIF format
  chainName: 'BTC',
  thresholdSignatureScheme: ThresholdSignatureScheme.TWO_OF_TWO,
  password: 'your-secure-password',
  backUpToClientShareService: true,
  bitcoinConfig: {
    addressType: BitcoinAddressType.NATIVE_SEGWIT,
  },
});

console.log('Bitcoin wallet imported:', wallet.accountAddress);
console.log('Public key:', wallet.publicKeyHex);
console.log('External server key shares:', wallet.externalServerKeyShares);

​
Import with Different Address Types

​
Native SegWit

const segwitWallet = await btcClient.importPrivateKey({
  privateKey: 'YourWifPrivateKey',
  chainName: 'BTC',
  thresholdSignatureScheme: ThresholdSignatureScheme.TWO_OF_TWO,
  backUpToClientShareService: true,
  bitcoinConfig: {
    addressType: BitcoinAddressType.NATIVE_SEGWIT,
  },
});

console.log('Native SegWit address:', segwitWallet.accountAddress);
// Output: bc1q...

​
Taproot

const taprootWallet = await btcClient.importPrivateKey({
  privateKey: 'YourWifPrivateKey',
  chainName: 'BTC',
  thresholdSignatureScheme: ThresholdSignatureScheme.TWO_OF_TWO,
  backUpToClientShareService: true,
  bitcoinConfig: {
    addressType: BitcoinAddressType.TAPROOT,
  },
});

console.log('Taproot address:', taprootWallet.accountAddress);
// Output: bc1p...

​
Export Private Key

You can export an imported wallet’s private key back to WIF format: 
const wifPrivateKey = await btcClient.exportPrivateKey({
  accountAddress: wallet.accountAddress,
  password: 'your-password', // Only if wallet was imported with password
});

console.log('Exported private key (WIF):', wifPrivateKey);

​
Offline Export

If you need to export the private key from existing key shares without a network call, use offlineExportPrivateKey(): 
const wifPrivateKey = await btcClient.offlineExportPrivateKey({
  keyShares: wallet.externalServerKeyShares,
  bitcoinConfig: {
    addressType: BitcoinAddressType.NATIVE_SEGWIT,
  },
});

console.log('Exported private key (WIF):', wifPrivateKey);

​
Error Handling

try {
  const wallet = await btcClient.importPrivateKey({
    privateKey: 'YourWifPrivateKey',
    chainName: 'BTC',
    thresholdSignatureScheme: ThresholdSignatureScheme.TWO_OF_TWO,
    backUpToClientShareService: true,
    bitcoinConfig: {
      addressType: BitcoinAddressType.NATIVE_SEGWIT,
    },
  });
  console.log('Import successful:', wallet.accountAddress);
} catch (error) {
  console.error('Import failed:', error.message);
}

<Note>
The SDK currently supports **Bitcoin Mainnet only**. Testnet support is planned for a future release.
</Note>

​
Security Considerations

  • Private Key Format: Ensure your private key is in valid WIF format
  • Password Security: Use a strong, unique password
  • Key Storage: Never store private keys in plain text after import
  • Backup: Ensure you have a secure backup of your original private key
  • Key Share Backup: Use backUpToClientShareService: true for secure key share storage

​
Threshold Signature Schemes

Choose based on your security and availability needs:
  • TWO_OF_TWO: Maximum security, requires both server and Dynamic
  • TWO_OF_THREE: Balanced security and availability

​
Next Steps