{"id":15600,"library":"electrum-client","title":"Electrum Client","description":"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.","status":"abandoned","version":"0.0.6","language":"javascript","source_language":"en","source_url":"git://github.com/you21979/node-electrum-client","tags":["javascript","client","electrum","bitcoin"],"install":[{"cmd":"npm install electrum-client","lang":"bash","label":"npm"},{"cmd":"yarn add electrum-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add electrum-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is CommonJS-only. Attempting to use ES module syntax (`import`) will result in runtime errors in modern Node.js environments.","wrong":"import ElectrumCli from 'electrum-client'","symbol":"ElectrumCli","correct":"const ElectrumCli = require('electrum-client')"},{"note":"All core functionality is accessed via methods on an instance of the `ElectrumCli` class after connection. There are no named exports for individual methods.","wrong":"import { server_version } from 'electrum-client'","symbol":"ElectrumCli instance methods","correct":"const ecl = new ElectrumCli(995, 'btc.smsys.me', 'tls'); await ecl.connect(); const ver = await ecl.server_version(\"2.7.11\", \"1.0\");"},{"note":"Subscription events are handled through an EventEmitter accessible via the `ecl.subscribe` property on the client instance, not as direct imports.","wrong":"import { subscribe } from 'electrum-client'","symbol":"Subscription events","correct":"ecl.subscribe.on('blockchain.headers.subscribe', (v) => console.log(v));"}],"quickstart":{"code":"const ElectrumCli = require('electrum-client');\n\nconst main = async () => {\n    // Connect to an Electrum server (e.g., btc.smsys.me on port 995 with TLS)\n    // Note: Use a reliable and trusted Electrum server.\n    const ecl = new ElectrumCli(995, 'btc.smsys.me', 'tls'); // 'tcp' or 'tls'\n    try {\n        await ecl.connect(); // Establish connection\n        console.log('Connected to Electrum server.');\n\n        // Subscribe to blockchain header updates\n        ecl.subscribe.on('blockchain.headers.subscribe', (header) => {\n            console.log('New block header received:', header);\n        });\n\n        // Make a JSON-RPC call to get the server version\n        const ver = await ecl.server_version(\"2.7.11\", \"1.0\");\n        console.log('Server version:', ver);\n\n        // Example: Get balance for a script hash (replace with a real script hash)\n        // Note: You would typically derive this from a Bitcoin address.\n        // const scriptHash = '716decbe1660861c3d93906cb1d98ee68b154fd4d23aed9783859c1271b52a9c';\n        // const balance = await ecl.blockchainScripthash_getBalance(scriptHash);\n        // console.log('Script hash balance:', balance);\n\n        // Keep the connection alive for a few seconds to receive subscriptions\n        await new Promise(resolve => setTimeout(resolve, 10000));\n\n    } catch (e) {\n        console.error('Electrum client error:', e);\n    } finally {\n        await ecl.close(); // Disconnect\n        console.log('Disconnected from Electrum server.');\n    }\n};\n\nmain();","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"0.0.1 - 0.0.6"},{"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.","message":"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.","severity":"breaking","affected_versions":"0.0.1 - 0.0.6"},{"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.","message":"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`.","severity":"breaking","affected_versions":"0.0.1 - 0.0.6"},{"fix":"Consider migrating to a modern Electrum client library that offers first-party TypeScript support for improved type safety and maintainability.","message":"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.","severity":"gotcha","affected_versions":"0.0.1 - 0.0.6"},{"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.","message":"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.","severity":"gotcha","affected_versions":"0.0.1 - 0.0.6"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Change the import statement to `const ElectrumCli = require('electrum-client')`.","cause":"Attempting to use ES module `import` syntax (`import ElectrumCli from 'electrum-client'`) with this CommonJS-only package.","error":"TypeError: ElectrumCli is not a constructor"},{"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.","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).","error":"Error: connect ECONNREFUSED <IP_ADDRESS>:<PORT>"},{"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.","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.","error":"Error: Protocol Error: Invalid server response (e.g., malformed JSON-RPC, unsupported protocol version)"}],"ecosystem":"npm"}