> ## Documentation Index
> Fetch the complete documentation index at: https://www.dynamic.xyz/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```typescript theme={"system"}
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](/node/btc/create-wallet) - Step-by-step wallet creation
* [Import Private Keys](/node/btc/import-private-keys) - Import existing BTC keys
* [Sign Transactions](/node/btc/sign-transactions) - Sign Bitcoin PSBTs
* [Sign Messages](/node/btc/sign-messages) - Sign messages with your wallet
* [Use Imported Wallets](/node/btc/use-imported-wallets) - Work with imported wallets
* [Complete Example](/node/btc/example-usage) - Full working example

<Warning>
  **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.
</Warning>

## Prerequisites

Before using the BTC SDK, ensure you have:

1. **Dynamic Project Setup**: [Set up your Dynamic project](/node/quickstart)
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

```bash theme={"system"}
bun add @dynamic-labs-wallet/node-btc @dynamic-labs-wallet/node @dynamic-labs-wallet/core
```

## Environment Variables

```bash theme={"system"}
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

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

## Error Handling

Always implement proper error handling:

```typescript theme={"system"}
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](/node/btc/create-wallet)
* [Explore the complete example](/node/btc/example-usage)
* [Learn about EVM support](/node/evm/)
* [Learn about SVM support](/node/svm/)
* [Learn about TON support](/node/ton/overview)