Import BTC Private Keys

Learn how to import existing Bitcoin private keys into Dynamic’s MPC wallet system

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

• Set up your Dynamic project
• Have your existing Bitcoin private key ready in WIF format

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: process.env.BTC_WIF_PRIVATE_KEY!, // WIF format
  chainName: 'BTC',
  thresholdSignatureScheme: ThresholdSignatureScheme.TWO_OF_TWO,
  password: process.env.WALLET_PASSWORD!,
  backUpToDynamic: true,
  bitcoinConfig: {
    addressType: BitcoinAddressType.NATIVE_SEGWIT,
  },
});

console.log('Bitcoin wallet imported:', wallet.walletMetadata.accountAddress);
console.log('Public key:', wallet.publicKeyHex);

Keep the returned wallet.walletMetadata. You pass it to signMessage, signTransaction and exportPrivateKey. Read the private key from a secret store or an environment variable, and never hard-code it.

Import with Different Address Types

Native SegWit

const segwitWallet = await btcClient.importPrivateKey({
  privateKey: process.env.BTC_WIF_PRIVATE_KEY!,
  chainName: 'BTC',
  thresholdSignatureScheme: ThresholdSignatureScheme.TWO_OF_TWO,
  password: process.env.WALLET_PASSWORD!,
  backUpToDynamic: true,
  bitcoinConfig: {
    addressType: BitcoinAddressType.NATIVE_SEGWIT,
  },
});

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

Taproot

const taprootWallet = await btcClient.importPrivateKey({
  privateKey: process.env.BTC_WIF_PRIVATE_KEY!,
  chainName: 'BTC',
  thresholdSignatureScheme: ThresholdSignatureScheme.TWO_OF_TWO,
  password: process.env.WALLET_PASSWORD!,
  backUpToDynamic: true,
  bitcoinConfig: {
    addressType: BitcoinAddressType.TAPROOT,
  },
});

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

Export Private Key

You can export an imported wallet’s private key back to WIF format:

const wifPrivateKey = await btcClient.exportPrivateKey({
  walletMetadata: wallet.walletMetadata,
  password: process.env.WALLET_PASSWORD, // Only if wallet was imported with password
});

exportPrivateKey returns the key in mainnet WIF format (starting with K or L), including for a wallet you use on testnet. Treat the exported key as highly sensitive and don’t log it.

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

offlineExportPrivateKey needs the full set of key shares. In @dynamic-labs-wallet/node-btc 1.1.52, passing the externalServerKeyShares returned for a wallet that is backed up to Dynamic fails with Must provide at least min threshold of key shares.

Error Handling

try {
  const wallet = await btcClient.importPrivateKey({
    privateKey: process.env.BTC_WIF_PRIVATE_KEY!,
    chainName: 'BTC',
    thresholdSignatureScheme: ThresholdSignatureScheme.TWO_OF_TWO,
    password: process.env.WALLET_PASSWORD!,
    backUpToDynamic: true,
    bitcoinConfig: {
      addressType: BitcoinAddressType.NATIVE_SEGWIT,
    },
  });
  console.log('Import successful:', wallet.walletMetadata.accountAddress);
} catch (error) {
  console.error('Import failed:', error instanceof Error ? error.message : String(error));
}

The SDK supports both Bitcoin Mainnet and Testnet. Use BitcoinNetwork.MAINNET for production and BitcoinNetwork.TESTNET for development and testing.

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

• Sign Bitcoin transactions
• Sign Bitcoin messages
• Use imported Bitcoin wallets