BTC SDK Overview

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 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, requiring both server and Dynamic infrastructure
TWO_OF_THREE: Balanced security and availability, requiring 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,
  password: process.env.WALLET_PASSWORD!,
  backUpToDynamic: true,
  bitcoinConfig: {
    addressType: BitcoinAddressType.NATIVE_SEGWIT,
  },
});

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

A password is required when backUpToDynamic is true. walletMetadata.accountAddress is always the mainnet address (bc1q...), including for wallets you use on testnet.

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:

Dynamic Project Setup: Set up your Dynamic project
Environment Configuration: Configure your environment ID and auth token
BTC Chain Enabled: Enable Bitcoin chain in your Dynamic Console
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
WALLET_PASSWORD=your_wallet_password_here

Bitcoin-Specific Concepts

Address Types

The SDK supports two address types, each with different features:

Address Type	Mainnet prefix	Testnet prefix	Description
Native SegWit (P2WPKH)	`bc1q...`	`tb1q...`	Modern, lower fees
Taproot (P2TR)	`bc1p...`	`tb1p...`	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.signMessage, signTransaction and deriveAccountAddress require a network argument. The wallet’s walletMetadata.accountAddress is always the mainnet address; derive the testnet address with deriveAccountAddress. See Working with testnet.

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

Learn

Build on the client

Build on the server

Configure

BTC SDK Overview

Overview

Key Features

Available Threshold Signature Schemes

Quick Start

Core Functions

Wallet Management

Signing Operations

Key Management

Backup and Recovery

Guides

Prerequisites

Installation

Environment Variables

Bitcoin-Specific Concepts

Address Types

Native Unit

Transaction Format

Message Signing

WIF Format

Security Considerations

Network Support

Error Handling

Next Steps

​Overview

​Key Features

​Available Threshold Signature Schemes

​Quick Start

​Core Functions

​Wallet Management

​Signing Operations

​Key Management

​Backup and Recovery

​Guides

​Prerequisites

​Installation

​Environment Variables

​Bitcoin-Specific Concepts

​Address Types

​Native Unit

​Transaction Format

​Message Signing

​WIF Format

​Security Considerations

​Network Support

​Error Handling

​Next Steps

Overview

Key Features

Available Threshold Signature Schemes

Quick Start

Core Functions

Wallet Management

Signing Operations

Key Management

Backup and Recovery

Guides

Prerequisites

Installation

Environment Variables

Bitcoin-Specific Concepts

Address Types

Native Unit

Transaction Format

Message Signing

WIF Format

Security Considerations

Network Support

Error Handling

Next Steps