{"id":25287746,"url":"https://github.com/nimiq/electrum-client","last_synced_at":"2025-10-27T22:30:26.580Z","repository":{"id":39585663,"uuid":"282903998","full_name":"nimiq/electrum-client","owner":"nimiq","description":"API to interact with ElectrumX servers from browsers","archived":false,"fork":false,"pushed_at":"2023-08-03T07:37:15.000Z","size":461,"stargazers_count":13,"open_issues_count":5,"forks_count":11,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-04-14T23:53:40.073Z","etag":null,"topics":["bitcoin","electrum","electrumx","websocket"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nimiq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-07-27T13:19:19.000Z","updated_at":"2024-03-18T16:14:24.000Z","dependencies_parsed_at":"2023-01-16T16:01:04.032Z","dependency_job_id":null,"html_url":"https://github.com/nimiq/electrum-client","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nimiq%2Felectrum-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nimiq%2Felectrum-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nimiq%2Felectrum-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nimiq%2Felectrum-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nimiq","download_url":"https://codeload.github.com/nimiq/electrum-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238563740,"owners_count":19492976,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bitcoin","electrum","electrumx","websocket"],"created_at":"2025-02-12T22:51:39.245Z","updated_at":"2025-10-27T22:30:26.065Z","avatar_url":"https://github.com/nimiq.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Electrum API for Browsers\n\nAccess Bitcoin ElectrumX servers from browsers via a WebSocket-to-TCP proxy.\n\n## Installation\n\nThere is no NPM package yet, so you need to set the `#build` branch of this repo\nas the package source:\n\n```bash\nnpm install @nimiq/electrum-client@https://github.com/nimiq/electrum-client#build\n# or\nyarn add @nimiq/electrum-client@https://github.com/nimiq/electrum-client#build\n```\n\n### BitcoinJS Library\n\n`ElectrumApi` depends on [bitcoinjs-lib](https://github.com/bitcoinjs/bitcoinjs-lib),\nwhich is only natively available for NodeJS. To use it in browsers, you need to\ncreate a build with Browserify and include it as a `\u003cscript\u003e` in your app HTML:\n\n```bash\nbrowserify -r bitcoinjs-lib -s BitcoinJS | terser --compress --mangle \u003e public/bitcoinjs.min.js\n```\n\nYou also need to mark the `bitcoinjs-lib` package as _external_ in your bundler to prevent\nit from blowing up your app:\n\n- [Rollup](https://rollupjs.org/guide/en/#warning-treating-module-as-external-dependency)\n  ([example config](example/rollup.config.js#L37-L43))\n- [Webpack](https://webpack.js.org/configuration/externals/#externals)\n\n## Quick Start\n\n```javascript\nimport { ElectrumApi } from '@nimiq/electrum-client'\n\n// Connect to Blockstream Bitcoin Mainnet server via NIMIQ.WATCH proxy\nconst electrum = new ElectrumApi();\n\n// Get an object with confirmed and unconfirmed balances in sats\nconst balance = await electrum.getBalance('3G4RSoDDF2HRJujqdqHcL6oW3toETE38CH');\n\n// Get a plain object describing a transaction\nconst tx = await electrum.getTransaction('18aa...b03f');\n```\n\n## Usage\n\n### Initialization\n\n```javascript\nimport { ElectrumApi } from '@nimiq/electrum-client'\n\nconst electrum = new ElectrumApi({\n    /**\n     * The URL and port of the Websocket-to-TCP proxy or ElectrumX server\n     * with Websockets enabled.\n     *\n     * [optional]\n     * Default: 'wss://api.nimiq.watch:50002'\n     */\n    endpoint: 'wss://api.nimiq.watch:50002',\n\n    /**\n     * Specify if you are using a Websocket-to-TCP proxy (set to true)\n     * or a native ElectrumX websocket connection (set to false).\n     *\n     * [optional]\n     * Default: true\n     */\n    proxy: true,\n\n    /**\n     * Connection token for Websockify proxies, to specify which server\n     * to proxy to. Find tokens for available servers at\n     * https://api.nimiqwatch.com:50002/tokens.txt.\n     *\n     * [optional]\n     * Default: 'mainnet:electrum.blockstream.info'\n     */\n    token: 'mainnet:electrum.blockstream.info',\n\n    /**\n     * Which Bitcoin network to use to encode and decode addresses.\n     * Can be either a BitcoinJS.Network object or either of\n     * 'bitcoin' | 'testnet'.\n     *\n     * [optional]\n     * Default: BitcoinJS.network.bitcoin\n     */\n    network: 'bitcoin',\n});\n```\n\n### Methods\n\nGet the balance for an address:\n\n```javascript\nconst balance = await electrum.getBalance('3G4RSoDDF2HRJujqdqHcL6oW3toETE38CH');\n\n// Returns an object:\n// {\n//   confirmed: number,\n//   unconfirmed: number,\n// }\n```\n\nGet transaction receipts for an address:\n\n```javascript\nconst receipts = await electrum.getReceipts('3G4RSoDDF2HRJujqdqHcL6oW3toETE38CH');\n\n// Returns an array of objects:\n// Array\u003c{\n//   blockHeight: number,\n//   transactionHash: string,\n//   fee?: number, // When the transaction is unconfirmed\n// }\u003e\n```\n\nGet transaction history for an address:\n\n```javascript\nconst txs = await electrum.getHistory('3G4RSoDDF2HRJujqdqHcL6oW3toETE38CH');\n\n// Returns an array of plain objects describing the address's transactions,\n// including block height, block hash and timestamp.\n```\n\nGet a specific transaction:\n\n```javascript\nconst tx = await electrum.getTransaction('18aa...b03f', 641085);\n// The second argument (the transaction's block height) is optional.\n\n// Returns a plain object describing the transaction. Includes the block header's\n// block height, block hash and timestamp when the block height is given.\n```\n\nGet a block header for a block height:\n\n```javascript\nconst header = await electrum.getBlockHeader(641085);\n\n// Returns a plain object describing the block header.\n// {\n//   blockHash: string,\n//   blockHeight: number,\n//   timestamp: number,\n//   bits: number,\n//   nonce: number,\n//   version: number,\n//   weight: number,\n//   prevHash: string | null,\n//   merkleRoot: string | null,\n// }\n```\n\nBroadcast a raw transaction to the network:\n\n```javascript\nconst tx = await electrum.broadcastTransaction('0012...13d9');\n\n// Returns a plain object describing the broadcast transaction.\n// Throws an error on failure.\n```\n\nSubscribe for changing receipts for an address:\n\n```javascript\nawait electrum.subscribeReceipts('3G4RSoDDF2HRJujqdqHcL6oW3toETE38CH', (receipts) =\u003e {\n    // See the `getReceipts` function for the format of `receipts`.\n});\n// Calls the callback with the current receipts and whenever the receipts change\n```\n\nSubscribe to blockchain head changes:\n\n```javascript\nawait electrum.subscribeHeaders((blockHeader) =\u003e {\n    // See the `getBlockHeader` method for the format of `blockHeader`\n});\n// Calls the callback with the current header and whenever the header changes\n```\n\n## Websockify\n\nThis library uses [Websockify](https://github.com/novnc/websockify) as a WebSocket-to-TCP\nproxy server for communicating with ElectrumX servers. Most ElectrumX server implementations\nsupport native websocket connections by now, but no publicly listed server has them\nenabled.\n\nIf you want to use your own ElectrumX server and have native websockets enabled,\nyou must set the `proxy` setting to `false` (Websockify requires appending a line-break\n(`\\n`) character at the end of messages, but native ElectrumX websockets do not).\n\nA public Websockify instance is running at https://api.nimiqwatch.com:50002. You\ncan see the Electrum servers that it can proxy to [here](https://api.nimiqwatch.com:50002/tokens.txt).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnimiq%2Felectrum-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnimiq%2Felectrum-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnimiq%2Felectrum-client/lists"}