Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
bitcoin
✓ import * as bitcoin from 'bitcoinjs-lib';
✗ const bitcoin = require('bitcoinjs-lib');
While CommonJS `require` is supported for Node.js, ESM `import * as bitcoin` is the recommended pattern for modern applications. This provides access to all exported modules under the `bitcoin` namespace.
Transaction, networks, Psbt
✓ import { Transaction, networks, Psbt } from 'bitcoinjs-lib';
✗ import bitcoinjsLib from 'bitcoinjs-lib';
Use named imports for specific functionalities like `Transaction` or `Psbt` to leverage tree-shaking, particularly for browser builds. The library does not provide a default export.
ECPair, BIP32
✓ import * as ecc from '@noble/secp256k1';
import * as ECPairFactory from 'ecpair';
const ECPair = ECPairFactory.ECPairFactory(ecc);
// Similarly for bip32: import * as bip32Factory from 'bip32'; const bip32 = bip32Factory.BIP32Factory(ecc);
✗ import { ECPair } from 'bitcoinjs-lib';
Since `bitcoinjs-lib` v6, `ECPair` and `bip32` functionalities have been extracted into separate packages (`ecpair` and `bip32` respectively) to reduce the core library's bundle size. They must be imported from their own packages and initialized with an ECC curve library (e.g., `tiny-secp256k1` or `@noble/secp256k1`). Attempting to import them directly from `bitcoinjs-lib` will result in an `undefined` or similar error.
This quickstart demonstrates how to generate a P2WPKH (SegWit) address and construct/sign a basic Partially Signed Bitcoin Transaction (PSBT) using `bitcoinjs-lib` along with the external `ecpair` and an ECC curve library.
import * as ecc from '@noble/secp256k1'; // Or 'tiny-secp256k1'
import * as ECPairFactory from 'ecpair';
import { Psbt, payments, networks } from 'bitcoinjs-lib';
// 1. Initialize ECPair with an ECC library (required since v6)
const ECPair = ECPairFactory.ECPairFactory(ecc);
// 2. Generate a key pair for a new P2WPKH (SegWit) address
const keyPair = ECPair.makeRandom({ network: networks.testnet });
const { address } = payments.p2wpkh({ pubkey: keyPair.publicKey, network: networks.testnet });
console.log('New SegWit Testnet Address:', address);
console.log('WIF (WARNING: DO NOT SHARE OR USE IN PRODUCTION):', keyPair.toWIF());
// 3. Create a Partially Signed Bitcoin Transaction (PSBT)
// This is a simplified example; real PSBTs require fetching actual UTXO details.
const psbt = new Psbt({ network: networks.testnet })
.addInput({
hash: '8f72289c02d75a8a113333333333333333333333333333333333333333333333', // Dummy TX ID
index: 0,
// For P2WPKH, witnessUtxo is required
witnessUtxo: { script: payments.p2wpkh({ pubkey: keyPair.publicKey }).output!, value: 20000 },
})
.addOutput({
address: 'tb1qgs400u6kqvq977gskv0d5x0r0sfgz7454w077e', // Another dummy testnet address
value: 10000,
});
// 4. Sign the input
psbt.signInput(0, keyPair);
// 5. Finalize the input (adds witness data)
psbt.finalizeAllInputs();
// 6. Extract the signed transaction (hex format) and log it
const transaction = psbt.extractTransaction().toHex();
console.log('Signed Transaction (Hex):', transaction);
Errors
Common errors & fixes
Cannot read properties of undefined (reading 'ECPairFactory')
Attempting to use `ECPairFactory` (or `BIP32Factory`) without correct import and initialization, typically because the `ecpair` or `bip32` packages are not installed or an ECC library is not provided.
fixEnsure `ecpair` (and/or `bip32`) is installed. Import `ECPairFactory` from `ecpair` (e.g., `import * as ECPairFactory from 'ecpair';`) and initialize it with an ECC library (e.g., `const ECPair = ECPairFactory.ECPairFactory(ecc);`).
TypeError: Psbt.data.globalMap.unsignedTx.getHash is not a function
Accessing methods of the `Transaction` object directly from `Psbt.data.globalMap.unsignedTx` in `bitcoinjs-lib` v7. The type has changed to `TransactionFromBuffer` for performance.
fixUse the methods provided by `TransactionFromBuffer` (e.g., `getId()` or `getHash()`) directly on `psbt.data.globalMap.unsignedTx`.
Error: No inputs to sign.
The PSBT was created without proper input information, specifically `witnessUtxo` or `nonWitnessUtxo` being missing for the respective script type (e.g., P2WPKH needs `witnessUtxo`, P2PKH needs `nonWitnessUtxo`).
fixEnsure that each input added to the PSBT has the necessary UTXO information (`witnessUtxo` or `nonWitnessUtxo`) corresponding to the script type you are attempting to sign.
Error: Key pair for input #X not provided.
The `keyPair` provided to `psbt.signInput(X, keyPair)` does not match the public key associated with the UTXO in input X, or the input data is insufficient for signing.
fixVerify that the `keyPair` used for signing corresponds to the private key of the address funding the specific input (index X) you are trying to sign. Also ensure the input details in the PSBT are accurate and complete.
Audit
Dependencies
ecpairoptionalRequired for ECPair functionality (e.g., generating key pairs, signing) as key management was externalized.
bip32optionalRequired for BIP32 HD key derivation functionalities as key management was externalized.
@noble/secp256k1optionalAn Elliptic Curve Cryptography (ECC) library is required to initialize `ecpair` and `bip32`.