Registry / http-networking / electrum-client

electrum-client

JSON →
library0.0.6jsnpmunverified

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.

npm install electrum-client
INSTALL
IMPORT
SIG · ELECTRUM-CLIENT
E
electrum-client
http-networkingjavascriptv0.0.6
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ElectrumCli
const ElectrumCli = require('electrum-client')
import ElectrumCli from '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
const ecl = new ElectrumCli(995, 'btc.smsys.me', 'tls'); await ecl.connect(); const ver = await ecl.server_version("2.7.11", "1.0");
import { server_version } from 'electrum-client'
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
ecl.subscribe.on('blockchain.headers.subscribe', (v) => console.log(v));
import { subscribe } from 'electrum-client'
Subscription events are handled through an EventEmitter accessible via the `ecl.subscribe` property on the client instance, not as direct imports.

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();
Debug
Known issues
breakingThe `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.
affects: 0.0.1 - 0.0.6
breakingDue 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.
affects: 0.0.1 - 0.0.6
breakingThe 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.
affects: 0.0.1 - 0.0.6
gotchaThis 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.
affects: 0.0.1 - 0.0.6
gotchaConnecting 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.
affects: 0.0.1 - 0.0.6
Errors
Common errors & fixes
TypeError: ElectrumCli is not a constructor
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>
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)
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.
Upgrade
Version history
0.0.6latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
14 hits · last 30 days
node
12
Amazon
1
OpenAI (training)
1
Resources
electrum-client — npm install electrum-client · libregistry