BTC SDK Overview

Complete guide to using Dynamic’s Node SDK for Bitcoin blockchain operations

Overview

Dynamic’s Node SDK provides comprehensive support for Bitcoin blockchain operations, including wallet creation, transaction signing (PSBT), message signing (BIP-322), and key management. The SDK implements Multi-Party Computation (MPC) for enhanced security.

Key Features

• MPC Wallet Creation: Create secure Bitcoin wallets with threshold signature schemes
• Multiple Address Types: Support for Legacy, SegWit, Native SegWit, and Taproot addresses
• Transaction Signing: Sign PSBTs (Partially Signed Bitcoin Transactions) without exposing private keys
• Message Signing: Sign messages using BIP-322 standard
• Key Import/Export: Import existing private keys (WIF format) and export wallet data
• Multiple Security Models: Choose between different threshold signature schemes

Available Threshold Signature Schemes

• TWO_OF_TWO: Maximum security - requires both server and Dynamic infrastructure
• TWO_OF_THREE: Balanced security and availability - requires 2 out of 3 shares

Quick Start

import { DynamicBtcWalletClient } from '@dynamic-labs-wallet/node-btc';
import { ThresholdSignatureScheme } from '@dynamic-labs-wallet/node';
import { BitcoinAddressType } from '@dynamic-labs-wallet/core';

const client = new DynamicBtcWalletClient({
  environmentId: process.env.DYNAMIC_ENVIRONMENT_ID!,
});

await client.authenticateApiToken(process.env.DYNAMIC_AUTH_TOKEN!);

// Create a new wallet
const wallet = await client.createWalletAccount({
  thresholdSignatureScheme: ThresholdSignatureScheme.TWO_OF_TWO,
  backUpToDynamic: true,
  bitcoinConfig: {
    addressType: BitcoinAddressType.NATIVE_SEGWIT,
  },
});

console.log('Wallet created:', wallet.accountAddress);

Core Functions

Wallet Management

• createWalletAccount() - Create new Bitcoin wallet
• importPrivateKey() - Import existing private key (WIF format)
• getBitcoinWallets() - Get all Bitcoin wallets
• deriveAccountAddress() - Derive Bitcoin address from a public key

Signing Operations

• signMessage() - Sign messages using BIP-322
• signTransaction() - Sign PSBTs (Partially Signed Bitcoin Transactions)

Key Management

• exportPrivateKey() - Export wallet private key in WIF format
• offlineExportPrivateKey() - Export private key from key shares offline

Backup and Recovery

• storeEncryptedBackupByWallet() - Store encrypted backup
• recoverEncryptedBackupByWallet() - Recover encrypted backup
• refreshWalletAccountShares() - Refresh wallet shares

Guides

• Create BTC Wallet - Step-by-step wallet creation
• Import Private Keys - Import existing BTC keys
• Sign Transactions - Sign Bitcoin PSBTs
• Sign Messages - Sign messages with your wallet
• Use Imported Wallets - Work with imported wallets
• Complete Example - Full working example

BTC addressType must be persisted on the cached walletMetadata. storeEncryptedBackupByWallet reads addressType (taproot or native_segwit) directly from walletMetadata — there is no server-side fallback. fetchWalletMetadata does not return it. Cache the full walletMetadata object returned from createWalletAccount / importPrivateKey; if you store wallet fields à la carte, make sure addressType is one of them.

Prerequisites

Before using the BTC SDK, ensure you have:

1. Dynamic Project Setup: Set up your Dynamic project
2. Environment Configuration: Configure your environment ID and auth token
3. BTC Chain Enabled: Enable Bitcoin chain in your Dynamic dashboard
4. Dependencies Installed: Install required packages

Installation

bun add @dynamic-labs-wallet/node-btc @dynamic-labs-wallet/node @dynamic-labs-wallet/core

Environment Variables

DYNAMIC_AUTH_TOKEN=your_auth_token_here
DYNAMIC_ENVIRONMENT_ID=your_environment_id_here

Bitcoin-Specific Concepts

Address Types

Bitcoin supports multiple address types, each with different features:

Address Type	Prefix	Description
Legacy (P2PKH)	1...	Original Bitcoin address format
SegWit (P2SH)	3...	Backwards-compatible SegWit
Native SegWit (P2WPKH)	bc1q...	Modern, lower fees
Taproot (P2TR)	bc1p...	Latest, privacy-enhanced, Schnorr signatures

Native Unit

Bitcoin uses satoshis as its smallest unit: 1 BTC = 100,000,000 satoshis.

Transaction Format

Bitcoin transactions use PSBT (Partially Signed Bitcoin Transactions) for signing. The signTransaction() method accepts a PSBT as a base64 string and returns the signed PSBT.

Message Signing

The SDK uses BIP-322 for message signing, which provides a standardized way to sign messages that works across all address types.

WIF Format

Private keys are imported and exported in WIF (Wallet Import Format), a base58-encoded format that includes the network and compression flag.

Security Considerations

• MPC Architecture: Private keys are never stored in plain text
• Threshold Signing: Multiple parties must collaborate to sign transactions
• Key Share Backup: Use backUpToDynamic: true for secure storage
• Password Protection: Implement strong passwords for additional security layers

Network Support

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

Error Handling

Always implement proper error handling:

try {
  const result = await btcClient.someFunction(params);
  console.log('Operation successful:', result);
} catch (error) {
  console.error('Operation failed:', error instanceof Error ? error.message : String(error));
}

Next Steps

• Get started with wallet creation
• Explore the complete example
• Learn about EVM support
• Learn about SVM support
• Learn about TON support