Skip to main content

Bitcoin Basics: Getting Started with Bitcoin Integration

This guide covers how to use the VerifiedX Web SDK for Bitcoin operations. The SDK provides a comprehensive Bitcoin client that supports wallet management, transactions, and mempool interactions through the Mempool.space API.

Prerequisites​

  • Node.js 18+ or a modern browser
  • Basic understanding of Bitcoin concepts
  • vfx-web-sdk installed in your project

Understanding Bitcoin Networks​

The SDK supports both Bitcoin networks:

  • Mainnet: The production Bitcoin network with real BTC
  • Testnet: The test network with test BTC (recommended for development)

Step 1: Initialize the Bitcoin Client​

The BtcClient provides all Bitcoin functionality in a single interface:

import { btc } from 'vfx-web-sdk';

// Initialize for testnet (recommended for development)
const client = new btc.BtcClient('testnet');

// For mainnet (production)
// const client = new btc.BtcClient('mainnet');

Step 2: Generate Bitcoin Wallets​

The SDK supports multiple ways to create Bitcoin wallets:

Method 1: Generate Random Wallet​

// Generate a completely random wallet
const keypair = client.generatePrivateKey();

console.log('Bitcoin Addresses:');
console.log('- Legacy (P2PKH):', keypair.addresses.p2pkh);
console.log('- Nested SegWit (P2SH):', keypair.addresses.p2sh);
console.log('- Native SegWit (Bech32):', keypair.addresses.bech32);
console.log('- Taproot (Bech32m):', keypair.addresses.bech32m);
console.log('- Default Address:', keypair.address);
console.log('- WIF:', keypair.wif);

Method 2: Generate from Mnemonic​

// Generate wallet with mnemonic for recovery
const mnemonicWallet = client.generateMnemonic();

console.log('Mnemonic Wallet:');
console.log('- Mnemonic:', mnemonicWallet.mnemonic);
console.log('- Address:', mnemonicWallet.address);
console.log('- WIF:', mnemonicWallet.wif);

Method 3: Restore from Mnemonic​

// Restore an existing wallet from mnemonic
const restoredWallet = client.privateKeyFromMnemonic(
  'your twelve word mnemonic phrase goes here like this example',
  0 // account index
);

console.log('Restored wallet address:', restoredWallet.address);

Method 4: Import from WIF or Private Key​

// Import from Wallet Import Format (WIF)
const wifWallet = client.addressFromWif('your-wif-string-here');

// Import from private key hex
const privateKeyWallet = client.publicFromPrivate('your-private-key-hex');

Method 5: Email-Based Wallet (Cross-Platform)​

For cross-platform compatibility with web wallets:

// Generate deterministic wallet from email/password
const emailWallet = client.generateEmailKeypair(
  'user@example.com',
  'secure-password',
  0 // index
);

console.log('Email-based wallet:', emailWallet.address);

Step 3: Check Account Information​

Get detailed information about any Bitcoin address:

async function getAccountInfo(address: string) {
  try {
    const info = await client.getAddressInfo(address);

    console.log('Account Information:');
    console.log('- Balance:', info.balance, 'satoshis');
    console.log('- Balance (BTC):', info.balance / 100000000, 'BTC');
    console.log('- Total Received:', info.totalRecieved, 'satoshis');
    console.log('- Total Sent:', info.totalSent, 'satoshis');
    console.log('- Transaction Count:', info.txCount);

    return info;
  } catch (error) {
    console.error('Error fetching account info:', error.message);
  }
}

// Check your wallet balance
const wallet = client.generatePrivateKey();
await getAccountInfo(wallet.address);

Step 4: Get Transaction History​

Retrieve transaction history for any address:

async function getTransactionHistory(address: string) {
  try {
    const transactions = await client.getTransactions(address);

    console.log(`Found ${transactions.length} transactions:`);

    transactions.forEach((tx, index) => {
      console.log(`\nTransaction ${index + 1}:`);
      console.log('- TX ID:', tx.txid);
      console.log('- Confirmed:', tx.status.confirmed);
      console.log('- Block Height:', tx.status.block_height);
      console.log('- Fee:', tx.fee, 'satoshis');
      console.log('- Size:', tx.size, 'bytes');
    });

    return transactions;
  } catch (error) {
    console.error('Error fetching transactions:', error.message);
  }
}

await getTransactionHistory(wallet.address);

Step 5: Check Current Fee Rates​

Before sending transactions, check current network fee rates:

async function getCurrentFees() {
  try {
    const fees = await client.getFeeRates();

    if (fees) {
      console.log('Current Fee Rates (sat/vB):');
      console.log('- Fastest (next block):', fees.fastestFee);
      console.log('- Half hour:', fees.halfHourFee);
      console.log('- One hour:', fees.hourFee);
      console.log('- Economy:', fees.economyFee);
      console.log('- Minimum:', fees.minimumFee);
    }

    return fees;
  } catch (error) {
    console.error('Error fetching fees:', error.message);
  }
}

await getCurrentFees();

Step 6: Send Bitcoin Transactions​

The easiest way to send Bitcoin:

async function sendBitcoin(senderWif: string, recipientAddress: string, amountSats: number) {
  try {
    console.log(`Sending ${amountSats} satoshis to ${recipientAddress}`);

    // This method handles transaction creation and broadcasting
    const txId = await client.sendBtc(
      senderWif,
      recipientAddress,
      amountSats,
      20 // fee rate in sat/vB (optional)
    );

    console.log('Transaction sent successfully!');
    console.log('Transaction ID:', txId);

    return txId;
  } catch (error) {
    console.error('Transaction failed:', error.message);
  }
}

// Send 50,000 satoshis (0.0005 BTC)
const wallet = client.generatePrivateKey();
await sendBitcoin(
  wallet.wif,
  'recipient-bitcoin-address',
  50000
);

Advanced Send (Manual Control)​

For more control over the transaction process:

async function advancedSend(senderWif: string, recipientAddress: string, amountSats: number) {
  try {
    // Step 1: Create the transaction
    const createResult = await client.createTransaction(
      senderWif,
      recipientAddress,
      amountSats,
      15 // custom fee rate
    );

    if (!createResult.success) {
      console.error('Failed to create transaction:', createResult.error);
      return;
    }

    console.log('Transaction created successfully');
    console.log('Raw transaction:', createResult.result);

    // Step 2: Broadcast the transaction
    const broadcastResult = await client.broadcastTransaction(createResult.result!);

    if (!broadcastResult.success) {
      console.error('Failed to broadcast transaction:', broadcastResult.error);
      return;
    }

    console.log('Transaction broadcast successfully');
    console.log('Transaction ID:', broadcastResult.result);

    return broadcastResult.result;
  } catch (error) {
    console.error('Advanced send failed:', error.message);
  }
}

Step 7: Message Signing​

Sign and verify Bitcoin messages:

function signMessage(message: string, wallet: any) {
  try {
    // Sign with WIF
    const signature = client.getSignatureFromWif(message, wallet.wif);
    console.log('Message signature:', signature);

    // Alternative: Sign with private key
    // const signature2 = client.getSignature(message, wallet.privateKey);

    return signature;
  } catch (error) {
    console.error('Signing failed:', error.message);
  }
}

const wallet = client.generatePrivateKey();
const signature = signMessage('Hello, Bitcoin!', wallet);

Complete Example: Bitcoin Wallet Manager​

Here's a comprehensive Bitcoin wallet manager:

import { btc } from 'vfx-web-sdk';

class BitcoinWalletManager {
  private client: btc.BtcClient;

  constructor(network: 'mainnet' | 'testnet' = 'testnet') {
    this.client = new btc.BtcClient(network);
  }

  // Create new wallet
  createWallet() {
    return this.client.generateMnemonic();
  }

  // Restore wallet from mnemonic
  restoreWallet(mnemonic: string, index: number = 0) {
    return this.client.privateKeyFromMnemonic(mnemonic, index);
  }

  // Import wallet from WIF
  importWallet(wif: string) {
    return this.client.addressFromWif(wif);
  }

  // Get wallet balance and info
  async getWalletInfo(address: string) {
    const [accountInfo, transactions] = await Promise.all([
      this.client.getAddressInfo(address),
      this.client.getTransactions(address)
    ]);

    return {
      balance: accountInfo.balance,
      balanceBTC: accountInfo.balance / 100000000,
      totalReceived: accountInfo.totalRecieved,
      totalSent: accountInfo.totalSent,
      transactionCount: accountInfo.txCount,
      recentTransactions: transactions.slice(0, 5) // Last 5 transactions
    };
  }

  // Send Bitcoin
  async sendBitcoin(fromWif: string, toAddress: string, amountSats: number, feeRate?: number) {
    return await this.client.sendBtc(fromWif, toAddress, amountSats, feeRate);
  }

  // Get current network fees
  async getNetworkFees() {
    return await this.client.getFeeRates();
  }

  // Sign a message
  signMessage(message: string, wif: string) {
    return this.client.getSignatureFromWif(message, wif);
  }
}

// Usage example
async function main() {
  const walletManager = new BitcoinWalletManager('testnet');

  // Create a new wallet
  const wallet = walletManager.createWallet();
  console.log('New Bitcoin wallet created:');
  console.log('Mnemonic:', wallet.mnemonic);
  console.log('Address:', wallet.address);
  console.log('All address types:', wallet.addresses);

  // Get wallet information
  try {
    const walletInfo = await walletManager.getWalletInfo(wallet.address);
    console.log('\nWallet Information:');
    console.log('Balance:', walletInfo.balanceBTC, 'BTC');
    console.log('Transactions:', walletInfo.transactionCount);
  } catch (error) {
    console.log('New wallet - no transactions yet');
  }

  // Check network fees
  const fees = await walletManager.getNetworkFees();
  if (fees) {
    console.log('\nCurrent Network Fees:');
    console.log('Fast:', fees.fastestFee, 'sat/vB');
    console.log('Standard:', fees.hourFee, 'sat/vB');
    console.log('Economy:', fees.economyFee, 'sat/vB');
  }

  // Sign a message
  const message = 'Hello from VerifiedX SDK!';
  const signature = walletManager.signMessage(message, wallet.wif);
  console.log('\nMessage Signature:');
  console.log('Message:', message);
  console.log('Signature:', signature);
}

main().catch(console.error);

Address Types Explained​

The SDK generates multiple address types for maximum compatibility:

Legacy (P2PKH) - addresses start with '1'​

  • Oldest address format
  • Highest fees
  • Maximum compatibility

Nested SegWit (P2SH) - addresses start with '3'​

  • Medium fees
  • Good compatibility
  • Wrapped SegWit transactions

Native SegWit (Bech32) - addresses start with 'bc1' (mainnet) or 'tb1' (testnet)​

  • Lower fees
  • Modern standard
  • Best for most use cases

Taproot (Bech32m) - addresses start with 'bc1p' (mainnet) or 'tb1p' (testnet)​

  • Lowest fees
  • Latest Bitcoin upgrade
  • Advanced privacy features

Best Practices​

Security​

  • Secure WIF storage: WIF keys provide full access to funds
  • Use strong passwords: For email-based wallets
  • Test on testnet first: Always test with testnet Bitcoin

Performance​

  • Cache fee rates: Don't fetch fees for every transaction
  • Batch operations: Group multiple API calls when possible
  • Handle rate limits: Mempool.space has API rate limits

Error Handling​

  • Check balances: Ensure sufficient balance before sending
  • Validate addresses: Verify recipient addresses
  • Monitor confirmations: Track transaction confirmations

What's Next?​

Now that you understand Bitcoin basics:

  1. Learn Cross-Chain: Explore Cross-Chain Integration
  2. Build Applications: Check out Complete Applications
  3. API Reference: Browse the BtcClient API

Common Issues​

Insufficient Balance​

Make sure your wallet has enough Bitcoin. On testnet, use a Bitcoin testnet faucet.

Transaction Fee Too Low​

Increase the fee rate if transactions are stuck in mempool.

Invalid Address Format​

Ensure you're using the correct address format for the recipient's wallet.

Network Connection Issues​

Check internet connection and try again. The SDK automatically retries failed requests.

Getting Help​