Bitcoin Wallets for Agents

A Bitcoin wallet manages keys and tracks UTXOs. For agents, choosing the right wallet architecture balances security, automation capability, and operational requirements.

Wallet Types

1. Full Node Wallet

Runs a complete Bitcoin node with integrated wallet.

Aspect	Details
Examples	Bitcoin Core, btcd
Trust model	Fully trustless
Disk space	500+ GB (pruned: ~10 GB)
Sync time	Hours to days

Agent use case: Maximum verification, long-running infrastructure.

2. SPV Wallet

Simplified Payment Verification—trusts block headers, verifies relevant transactions.

Aspect	Details
Examples	Electrum, BDK
Trust model	Trusts headers from majority hashpower
Disk space	Minimal
Sync time	Minutes

Agent use case: Mobile agents, resource-constrained environments.

3. Watch-Only Wallet

Tracks addresses without holding private keys.

Aspect	Details
Examples	Any wallet with xpub import
Capabilities	View balance, generate addresses, create unsigned tx
Security	Keys stored separately (cold storage, HSM)

Agent use case: Monitoring, payment processing, cold storage management.

4. Custodial API Wallet

Third-party manages keys; agent accesses via API.

Aspect	Details
Examples	Coinbase Commerce, BitPay, OpenNode
Trust model	Trust the custodian
Setup	API key configuration

Agent use case: Quick integration, compliance requirements, fiat conversion.

HD Wallet Architecture

Hierarchical Deterministic wallets derive unlimited addresses from a single seed.

Key Components

Entropy (128-256 bits)
    ↓ (BIP-39)
Mnemonic (12-24 words)
    ↓ (PBKDF2)
Seed (512 bits)
    ↓ (BIP-32)
Master Key (xprv)
    ↓ (derivation)
Account Keys → Address Keys

Derivation Path

m / purpose' / coin_type' / account' / change / address_index

Level	Value	Meaning
purpose’	84’	BIP-84 (SegWit)
coin_type’	0’	Bitcoin mainnet
account’	0’	First account
change	0	Receiving chain
address_index	0..n	Sequential addresses

Extended Keys

Key Type	Prefix	Can Derive
xprv (private)	xprv	Private + public children
xpub (public)	xpub	Public children only
zprv/zpub	SegWit	Native SegWit keys

Security: Never share xprv. Share xpub/zpub for watch-only tracking.

Agent Wallet Patterns

Pattern 1: Hot Wallet (Automated)

Agent has: Master private key (encrypted)
Use for: Automated payments < $1,000
Security: Environment variable encryption, memory isolation

┌─────────────┐
│   Agent     │
│ ┌─────────┐ │
│ │  Keys   │ │ → Automated signing
│ └─────────┘ │
└─────────────┘

Pattern 2: Warm Wallet (Semi-Automated)

Agent has: Watch-only xpub
Signs via: Separate signing service with rate limits

┌─────────────┐     ┌──────────────┐
│   Agent     │────▶│  Signer API  │
│ (xpub only) │     │ (rate limits)│
└─────────────┘     └──────────────┘

Pattern 3: Cold Wallet (Manual)

Agent has: Watch-only xpub
Signs via: Offline device, human approval

┌─────────────┐     ┌──────────────┐     ┌──────────────┐
│   Agent     │────▶│    PSBT      │────▶│   Offline    │
│ (creates tx)│     │ (unsigned)   │     │   Signer     │
└─────────────┘     └──────────────┘     └──────────────┘

Implementation Guide

Step 1: Generate Wallet

const bip39 = require('bip39');
const { BIP32Factory } = require('bip32');
const ecc = require('tiny-secp256k1');

const bip32 = BIP32Factory(ecc);

// Generate mnemonic (do this ONCE, store securely)
const mnemonic = bip39.generateMnemonic(256); // 24 words

// Derive seed
const seed = bip39.mnemonicToSeedSync(mnemonic);

// Create master key
const root = bip32.fromSeed(seed);

// Export xpub for account 0
const account = root.derivePath("m/84'/0'/0'");
const xpub = account.neutered().toBase58();

console.log('xpub:', xpub); // Share this for watch-only

Step 2: Derive Addresses

const bitcoin = require('bitcoinjs-lib');

function deriveAddress(xpub, change, index) {
  const node = bip32.fromBase58(xpub)
    .derive(change)  // 0 = receiving, 1 = change
    .derive(index);

  const { address } = bitcoin.payments.p2wpkh({
    pubkey: node.publicKey,
    network: bitcoin.networks.bitcoin
  });

  return address;
}

// Generate receiving addresses
for (let i = 0; i < 10; i++) {
  console.log(`Address ${i}:`, deriveAddress(xpub, 0, i));
}

Step 3: Track UTXOs

async function getWalletUTXOs(addresses) {
  const utxos = [];

  for (const address of addresses) {
    const response = await fetch(
      `https://mempool.space/api/address/${address}/utxo`
    );
    const addressUtxos = await response.json();

    utxos.push(...addressUtxos.map(u => ({
      ...u,
      address
    })));
  }

  return utxos;
}

Step 4: Create Transactions

const bitcoin = require('bitcoinjs-lib');

function createTransaction(utxos, recipient, amount, feeRate, changeAddress) {
  const psbt = new bitcoin.Psbt({ network: bitcoin.networks.bitcoin });

  // Add inputs
  let totalInput = 0;
  for (const utxo of utxos) {
    psbt.addInput({
      hash: utxo.txid,
      index: utxo.vout,
      witnessUtxo: {
        script: bitcoin.address.toOutputScript(utxo.address),
        value: utxo.value
      }
    });
    totalInput += utxo.value;
  }

  // Add recipient output
  psbt.addOutput({
    address: recipient,
    value: amount
  });

  // Calculate and add change
  const estimatedSize = 110 + (utxos.length * 68) + (2 * 31);
  const fee = Math.ceil(estimatedSize * feeRate);
  const change = totalInput - amount - fee;

  if (change > 294) { // P2WPKH dust threshold
    psbt.addOutput({
      address: changeAddress,
      value: change
    });
  }

  return psbt;
}

Security Checklist

Key Storage

• Mnemonic encrypted at rest (AES-256-GCM)
• Keys never logged or printed
• Memory cleared after use
• Separate backup in secure location

Operational Security

• Transaction limits enforced
• Anomaly detection for unusual patterns
• Multi-signature for high-value operations
• Regular key rotation for hot wallets

Agent-Specific

• Watch-only mode for monitoring
• PSBT workflow for cold signing
• Rate limiting on signing operations
• Audit trail for all transactions

Recommended Libraries

Language	Library	Notes
JavaScript	bitcoinjs-lib, bip32, bip39	Most complete
Python	bdk-python, python-bitcoinlib	BDK for full wallet
Rust	bdk, rust-bitcoin	Production grade
Go	btcsuite	Full node integration

API-Based Wallets

For agents needing quick integration without key management:

LNbits (Lightning + On-chain)

# Check balance
curl -H "X-Api-Key: $LNBITS_API_KEY" \
  https://lnbits.example.com/api/v1/wallet

# Create invoice
curl -X POST \
  -H "X-Api-Key: $LNBITS_API_KEY" \
  -d '{"amount": 1000, "memo": "payment"}' \
  https://lnbits.example.com/api/v1/payments

OpenNode

curl -X POST https://api.opennode.com/v1/charges \
  -H "Authorization: $OPENNODE_API_KEY" \
  -d '{"amount": 100, "currency": "USD"}'

---

Machine-Readable Summary

{
  "topic": "bitcoin-wallets",
  "wallet_types": ["full-node", "spv", "watch-only", "custodial"],
  "hd_standards": ["bip32", "bip39", "bip44", "bip84"],
  "agent_patterns": {
    "hot": "automated-signing",
    "warm": "rate-limited-api",
    "cold": "psbt-offline"
  },
  "libraries": {
    "javascript": ["bitcoinjs-lib", "bip32", "bip39"],
    "python": ["bdk-python", "python-bitcoinlib"],
    "rust": ["bdk", "rust-bitcoin"]
  }
}