Electrum Client

0.0.6 · abandoned · verified Tue Apr 21

The package `electrum-client` (npm: `electrum-client`, GitHub: `you21979/node-electrum-client`) provides a Node.js client for interacting with ElectrumX servers using the Electrum protocol. It supports core functionalities like TCP/TLS connections, JSON-RPC method calls for querying blockchain data (e.g., server version), and EventEmitter for handling real-time subscription messages (e.g., blockchain headers). As of its latest version, 0.0.6, the package has not seen updates since its last publish date approximately eight years ago (February 2018), indicating an abandoned state. A key differentiator initially was its explicit lack of external dependencies. However, due to its age, developers should be aware that more actively maintained and feature-rich alternatives exist under similar names, such as `@samouraiwallet/electrum-client`, `@bitcoinerlab/electrum-client`, and `@mempool/electrum-client`, many of which offer ES Module compatibility and TypeScript support. The original `electrum-client` is strictly a CommonJS module.

Common errors

```
TypeError: ElectrumCli is not a constructor
```
cause Attempting to use ES module `import` syntax (`import ElectrumCli from 'electrum-client'`) with this CommonJS-only package.

fix Change the import statement to `const ElectrumCli = require('electrum-client')`.
```
Error: connect ECONNREFUSED <IP_ADDRESS>:<PORT>
```
cause The client could not establish a connection to the specified Electrum server. This can be due to an incorrect IP/hostname, wrong port, server being offline, firewall blocking the connection, or using the wrong protocol (TCP vs TLS).

fix Verify the server's IP address and port, ensure the server is running, check any local or network firewalls, and confirm you are using the correct protocol ('tcp' or 'tls') as specified by the server. Try connecting to a different known good public Electrum server to rule out client-side issues.
```
Error: Protocol Error: Invalid server response (e.g., malformed JSON-RPC, unsupported protocol version)
```
cause The Electrum server responded with data that the client did not understand or was an unexpected format, potentially due to a server-side error, an outdated client/server protocol version mismatch, or an attempt to use a deprecated Electrum method.

fix Ensure the Electrum server you are connecting to supports the protocol version used by this client (likely an older version). Consult the server's documentation or try a different server. Consider updating to a more modern Electrum client library that supports current protocol versions.

Warnings

breaking The `electrum-client` package is effectively abandoned, with its last publish date approximately eight years ago (February 2018). This means no further updates, bug fixes, or security patches will be released. Using unmaintained software, especially for cryptocurrency-related operations, carries significant risk.
Fix: Migrate to a more actively maintained Electrum client library, such as `@samouraiwallet/electrum-client`, `@mempool/electrum-client`, or `@bilthon/electrum-client-ts`, which offer ongoing support and modern features.
breaking Due to its age, this library is likely incompatible with newer Node.js versions (e.g., Node.js 16+ for certain async/await behaviors, or later versions for core module changes) or evolving Electrum protocol specifications. This can lead to unexpected errors, connection failures, or incorrect data parsing.
Fix: Thoroughly test compatibility with your specific Node.js runtime and ElectrumX server version. For production use, migrating to a modern, maintained client is strongly recommended.
breaking The package is written exclusively in CommonJS (`require()`) and does not natively support ES Modules (`import`). Attempting to use `import ElectrumCli from 'electrum-client'` directly in an ESM context will result in a runtime `TypeError`.
Fix: Always use `const ElectrumCli = require('electrum-client')` to import the library. For projects requiring full ESM compatibility, consider alternative modern Electrum client libraries that provide native ES module support.
gotcha This library does not ship with TypeScript declaration files (`.d.ts`). Developers using TypeScript will either need to provide their own type definitions, use `any` types, or rely on `@ts-ignore` directives, reducing type safety and developer experience.
Fix: Consider migrating to a modern Electrum client library that offers first-party TypeScript support for improved type safety and maintainability.
gotcha Connecting to untrusted Electrum servers can expose your application to security risks, including phishing attacks, data privacy leaks, or inaccurate blockchain information. An outdated client may lack modern security features or robust certificate validation.
Fix: Always connect to well-known, trusted ElectrumX servers and verify server hostnames. For sensitive applications, consider running your own ElectrumX server or using a client that offers advanced security features like strong certificate pinning and server authenticity checks. Exercise extreme caution with TLS connections if the certificate chain cannot be fully verified.

Install

npm install electrum-client npm
yarn add electrum-client yarn
pnpm add electrum-client pnpm

Imports

ElectrumCli
wrong:
```
import ElectrumCli from 'electrum-client'
```
correct:
```
const ElectrumCli = require('electrum-client')
```
This package is CommonJS-only. Attempting to use ES module syntax (`import`) will result in runtime errors in modern Node.js environments.
ElectrumCli instance methods
wrong:
```
import { server_version } from 'electrum-client'
```
correct:
```
const ecl = new ElectrumCli(995, 'btc.smsys.me', 'tls'); await ecl.connect(); const ver = await ecl.server_version("2.7.11", "1.0");
```
All core functionality is accessed via methods on an instance of the `ElectrumCli` class after connection. There are no named exports for individual methods.
Subscription events
wrong:
```
import { subscribe } from 'electrum-client'
```
correct:
```
ecl.subscribe.on('blockchain.headers.subscribe', (v) => console.log(v));
```
Subscription events are handled through an EventEmitter accessible via the `ecl.subscribe` property on the client instance, not as direct imports.

Quickstart

This quickstart demonstrates how to connect to an ElectrumX server, subscribe to new block headers, and make a basic JSON-RPC call to fetch the server's version.

const ElectrumCli = require('electrum-client');

const main = async () => {
    // Connect to an Electrum server (e.g., btc.smsys.me on port 995 with TLS)
    // Note: Use a reliable and trusted Electrum server.
    const ecl = new ElectrumCli(995, 'btc.smsys.me', 'tls'); // 'tcp' or 'tls'
    try {
        await ecl.connect(); // Establish connection
        console.log('Connected to Electrum server.');

        // Subscribe to blockchain header updates
        ecl.subscribe.on('blockchain.headers.subscribe', (header) => {
            console.log('New block header received:', header);
        });

        // Make a JSON-RPC call to get the server version
        const ver = await ecl.server_version("2.7.11", "1.0");
        console.log('Server version:', ver);

        // Example: Get balance for a script hash (replace with a real script hash)
        // Note: You would typically derive this from a Bitcoin address.
        // const scriptHash = '716decbe1660861c3d93906cb1d98ee68b154fd4d23aed9783859c1271b52a9c';
        // const balance = await ecl.blockchainScripthash_getBalance(scriptHash);
        // console.log('Script hash balance:', balance);

        // Keep the connection alive for a few seconds to receive subscriptions
        await new Promise(resolve => setTimeout(resolve, 10000));

    } catch (e) {
        console.error('Electrum client error:', e);
    } finally {
        await ecl.close(); // Disconnect
        console.log('Disconnected from Electrum server.');
    }
};

main();

view raw JSON →