Sign BTC Messages

Learn how to sign messages using Dynamic’s Node SDK for Bitcoin

Overview

This guide shows you how to sign messages with your Bitcoin wallet. Message signing uses the BIP-322 standard, which provides a unified way to sign messages across all Bitcoin address types. The signature is returned as a base64 string.

Prerequisites

• Created a Bitcoin wallet

Basic Message Signing

walletMetadata is the object returned by createWalletAccount (or importPrivateKey), and password is the password you set when you created the wallet. network is required: use BitcoinNetwork.MAINNET or BitcoinNetwork.TESTNET.

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

const btcClient = await authenticatedBtcClient();

const signature = await btcClient.signMessage({
  message: 'Hello, Bitcoin!',
  walletMetadata,
  network: BitcoinNetwork.MAINNET,
  password: process.env.WALLET_PASSWORD!,
});

console.log('Message signed (base64):', signature);

Simple Message Signing

Whether you need to provide externalServerKeyShares depends on how you created your wallet:

With Automatic Backup (Recommended)

If you created your wallet with backUpToDynamic: true, you don’t need to provide external key shares. A password is required for these wallets, so pass it:

import { BitcoinNetwork } from '@dynamic-labs-wallet/core';

// Simple signing - no externalServerKeyShares needed
const signature = await btcClient.signMessage({
  message: 'Hello, Bitcoin!',
  walletMetadata,
  network: BitcoinNetwork.MAINNET,
  password: process.env.WALLET_PASSWORD!,
});

console.log('Message signed (base64):', signature);

With Manual Backup

If you created your wallet with backUpToDynamic: false, you must provide external key shares:

// First, retrieve your stored key shares
const keyShares = await retrieveStoredKeyShares('bc1q...your-wallet-address');

// Must provide externalServerKeyShares
const signature = await btcClient.signMessage({
  message: 'Hello, Bitcoin!',
  walletMetadata,
  network: BitcoinNetwork.MAINNET,
  externalServerKeyShares: keyShares, // Required for manual backup!
  password: process.env.WALLET_PASSWORD, // Only if wallet was created with password
});

console.log('Message signed (base64):', signature);

Password Handling Notes:

• If your wallet was created without a password, omit the password parameter
• If your wallet was created with a password, you must provide it for all operations
• Wallets created with backUpToDynamic: true always have a password, because one is required at creation

BIP-322 Message Signing

The SDK automatically uses BIP-322 for message signing, which works with both Native SegWit and Taproot addresses:

Native SegWit (P2WPKH)

// Native SegWit wallet — walletMetadata.addressType is 'native_segwit'
const signature = await btcClient.signMessage({
  message: 'Verify my ownership',
  walletMetadata,
  network: BitcoinNetwork.MAINNET,
});
// Returns BIP-322 signature in base64 format

Taproot (P2TR)

// Taproot wallet — walletMetadata.addressType is 'taproot'
const signature = await btcClient.signMessage({
  message: 'Verify my ownership',
  walletMetadata,
  network: BitcoinNetwork.MAINNET,
});
// Returns BIP-322 signature with Schnorr (BIP-340) in base64 format

Taproot message signing requires @dynamic-labs-wallet/node-btc 1.1.59 or later. In earlier versions it fails with Invalid type: Expected bigint but received 0 or Uint8Array expected.

Common Use Cases

Authentication

const nonce = Date.now().toString();
const message = `Sign this message to authenticate: ${nonce}`;
const signature = await btcClient.signMessage({
  message,
  walletMetadata,
  network: BitcoinNetwork.MAINNET,
  password: process.env.WALLET_PASSWORD!,
});
// signature is a BIP-322 encoded signature in base64

Data Integrity

const data = { userId: 123, action: 'transfer', amount: '100000' };
const message = JSON.stringify(data);
const signature = await btcClient.signMessage({
  message,
  walletMetadata,
  network: BitcoinNetwork.MAINNET,
  password: process.env.WALLET_PASSWORD!,
});

Proof of Ownership

const walletAddress = walletMetadata.accountAddress;
const proofMessage = `I own this Bitcoin address: ${walletAddress}`;
const signature = await btcClient.signMessage({
  message: proofMessage,
  walletMetadata,
  network: BitcoinNetwork.MAINNET,
  password: process.env.WALLET_PASSWORD!,
});

Signing on Testnet

Pass BitcoinNetwork.TESTNET as network and keep passing the walletMetadata you got from createWalletAccount, unchanged:

const signature = await btcClient.signMessage({
  message: 'Hello, Bitcoin!',
  walletMetadata,
  network: BitcoinNetwork.TESTNET,
  password: process.env.WALLET_PASSWORD!,
});

walletMetadata.accountAddress is always the mainnet-encoded address (bc1q...), and signing on testnet works with it. If you omit network, or pass BitcoinNetwork.MAINNET with a wallet whose address you replaced with its tb1q... form, you get Address verification failed: expected tb1q..., got bc1q.... See Working with testnet.

Understanding BIP-322

BIP-322 (Generic Signed Message Format) provides a standardized way to sign and verify messages for all Bitcoin address types:

• Native SegWit (P2WPKH): Uses ECDSA signatures
• Taproot (P2TR): Uses Schnorr signatures (BIP-340)

The signature format encodes the signed message in a way that can be verified by any BIP-322 compatible verifier.

Error Handling

try {
  const signature = await btcClient.signMessage({
    message: 'Test message',
    walletMetadata,
    network: BitcoinNetwork.MAINNET,
    password: process.env.WALLET_PASSWORD!,
  });
  console.log('Signature:', signature);
} catch (error) {
  console.error('Message signing failed:', error instanceof Error ? error.message : String(error));
}

Next Steps

• Sign Bitcoin transactions