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.
ECPairFactory
✓ import { ECPairFactory } from 'ecpair';
✗ const { ECPairFactory } = require('ecpair');
ecpair v3 is an ESM-first package. This is the primary export for initializing the ECPair API.
ECPairAPI
✓ import { ECPairAPI } from 'ecpair';
✗ import ECPair from 'ecpair'; // ECPairAPI is a type, not a runtime value
This is a TypeScript type definition. The runtime instance is created via `ECPairFactory`.
TinySecp256k1Interface
✓ import { TinySecp256k1Interface } from 'ecpair';
This is a TypeScript interface defining the required methods for the external ECC library (e.g., `tiny-secp256k1`).
This quickstart demonstrates how to initialize `ecpair` with an ECC library, generate random keypairs, and import keys from WIF, private keys, and public keys, including custom network and RNG function usage.
import { ECPairFactory, TinySecp256k1Interface, ECPairInterface } from 'ecpair';
import * as crypto from 'crypto';
// You need to provide an ECC library that implements TinySecp256k1Interface
// This is typically 'tiny-secp256k1'
const tinysecp: TinySecp256k1Interface = require('tiny-secp256k1');
const ECPair = ECPairFactory(tinysecp);
// Generate a random key pair
const keyPair1: ECPairInterface = ECPair.makeRandom();
console.log('Random Private Key (HEX):', keyPair1.privateKey?.toString('hex'));
console.log('Random Public Key (HEX):', keyPair1.publicKey.toString('hex'));
// Import from WIF
const wifKey = 'L45P2H58kPq611cRjP5H3rXfRjP5H3rXfRjP5H3rXfRjP5H3rXfRjP5H3rXfRjP5H3rXfRjP5H3rXf'; // Example WIF (DO NOT USE FOR REAL ASSETS)
const keyPair2: ECPairInterface = ECPair.fromWIF(wifKey);
console.log('WIF Public Key (HEX):', keyPair2.publicKey.toString('hex'));
// Import from a private key buffer
const privateKeyBuffer = crypto.randomBytes(32);
const keyPair3: ECPairInterface = ECPair.fromPrivateKey(privateKeyBuffer);
console.log('Imported Private Key (HEX):', keyPair3.privateKey?.toString('hex'));
// Import from a public key buffer
const keyPair4: ECPairInterface = ECPair.fromPublicKey(keyPair1.publicKey);
console.log('Imported Public Key (HEX):', keyPair4.publicKey.toString('hex'));
// Demonstrate custom network and RNG
const customNetwork = { messagePrefix: '\x18Bitcoin Signed Message:\n', bip32: { public: 0x0488b21e, private: 0x0488ade4 }, pubKeyHash: 0x00, scriptHash: 0x05, wif: 0x80 };
const customRng = (size: number): Buffer => crypto.randomBytes(size);
const keyPair5 = ECPair.makeRandom({ network: customNetwork, rng: customRng });
console.log('Custom Network Public Key (HEX):', keyPair5.publicKey.toString('hex'));
Debug
Known issues
gotchaThe `ECPair.makeRandom()` method, when no custom `rng` function is provided, internally uses `crypto.getRandomValues`. This API was experimental in Node.js 18.19.0 and earlier. Running on older Node versions without the `--experimental-global-webcrypto` flag or a polyfill can lead to issues.fixFor Node.js < 20, either provide a custom `rng` function (e.g., using `randombytes` package) or run Node.js with `--experimental-global-webcrypto` flag. Ensure your Node.js environment is v20.0.0 or higher.
affects: <3.0.0 || <=18.19.0 (Node.js)
breakingVersion 3.x of `ecpair` has moved to an ESM-first (ECMAScript Module) architecture and mandates Node.js >= 20.0.0. Direct `require()` statements for `ecpair` will generally not work in new projects or if your environment is configured for ESM. Similarly, the internal usage of `crypto.getRandomValues` instead of `randombytes` is a significant change.fixUpdate your project to use ES Modules (`import`/`export`) for `ecpair`. Ensure your Node.js version is 20.0.0 or higher. If you need CommonJS, consider using a bundler (like Webpack or Rollup) or stick to `ecpair` v2.x if compatible with your other dependencies.
affects: >=3.0.0
gotchaPassing a custom Random Number Generator (RNG) function to `ECPair.makeRandom({ rng: customRng })` requires extreme caution. A poorly implemented or compromised RNG can lead to predictable private keys, resulting in significant security vulnerabilities and loss of funds.fixOnly provide a custom `rng` function if you fully understand cryptographic random number generation and have a strong justification for it. In most cases, rely on the default, cryptographically secure RNG provided by the library (which uses `crypto.getRandomValues`).
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: ECPair.makeRandom is not a function
The `ECPair` object itself is not directly imported but is the result of calling `ECPairFactory` with an ECC library.
fixEnsure you initialize `ECPair` by calling `const ECPair = ECPairFactory(tinysecp);` after importing `ECPairFactory` and `tiny-secp256k1`.
Error: Missing TinySecp256k1Interface implementation. Please provide an ECC library (e.g., tiny-secp256k1).
`ECPairFactory` was called without a valid implementation of `TinySecp256k1Interface` (most commonly `tiny-secp256k1`).
fixInstall `tiny-secp256k1` (`npm install tiny-secp256k1`) and pass it to the factory: `const tinysecp = require('tiny-secp256k1'); const ECPair = ECPairFactory(tinysecp);` ReferenceError: require is not defined in ES module scope
Attempting to use `require()` to import `ecpair` in an ES Module context.
fixUse ES Module `import` syntax: `import { ECPairFactory } from 'ecpair';`. Audit
Dependencies
tiny-secp256k1requiredRequired as the external ECC library for all cryptographic operations (e.g., key generation, signing, validation).