Access Bitcoin ElectrumX servers from browsers via a WebSocket-to-TCP proxy.
There is no NPM package yet, so you need to set the #build branch of this repo
as the package source:
npm install @nimiq/electrum-client@https://github.com/nimiq/electrum-client#build
# or
yarn add @nimiq/electrum-client@https://github.com/nimiq/electrum-client#buildElectrumApi depends on bitcoinjs-lib,
which is only natively available for NodeJS. To use it in browsers, you need to
create a build with Browserify and include it as a <script> in your app HTML:
browserify -r bitcoinjs-lib -s BitcoinJS | terser --compress --mangle > public/bitcoinjs.min.jsYou also need to mark the bitcoinjs-lib package as external in your bundler to prevent
it from blowing up your app:
import { ElectrumApi } from '@nimiq/electrum-client'
// Connect to Blockstream Bitcoin Mainnet server via NIMIQ.WATCH proxy
const electrum = new ElectrumApi();
// Get an object with confirmed and unconfirmed balances in sats
const balance = await electrum.getBalance('3G4RSoDDF2HRJujqdqHcL6oW3toETE38CH');
// Get a plain object describing a transaction
const tx = await electrum.getTransaction('18aa...b03f');import { ElectrumApi } from '@nimiq/electrum-client'
const electrum = new ElectrumApi({
/**
* The URL and port of the Websocket-to-TCP proxy or ElectrumX server
* with Websockets enabled.
*
* [optional]
* Default: 'wss://api.nimiq.watch:50002'
*/
endpoint: 'wss://api.nimiq.watch:50002',
/**
* Specify if you are using a Websocket-to-TCP proxy (set to true)
* or a native ElectrumX websocket connection (set to false).
*
* [optional]
* Default: true
*/
proxy: true,
/**
* Connection token for Websockify proxies, to specify which server
* to proxy to. Find tokens for available servers at
* https://api.nimiqwatch.com:50002/tokens.txt.
*
* [optional]
* Default: 'mainnet:electrum.blockstream.info'
*/
token: 'mainnet:electrum.blockstream.info',
/**
* Which Bitcoin network to use to encode and decode addresses.
* Can be either a BitcoinJS.Network object or either of
* 'bitcoin' | 'testnet'.
*
* [optional]
* Default: BitcoinJS.network.bitcoin
*/
network: 'bitcoin',
});Get the balance for an address:
const balance = await electrum.getBalance('3G4RSoDDF2HRJujqdqHcL6oW3toETE38CH');
// Returns an object:
// {
// confirmed: number,
// unconfirmed: number,
// }Get transaction receipts for an address:
const receipts = await electrum.getReceipts('3G4RSoDDF2HRJujqdqHcL6oW3toETE38CH');
// Returns an array of objects:
// Array<{
// blockHeight: number,
// transactionHash: string,
// fee?: number, // When the transaction is unconfirmed
// }>Get transaction history for an address:
const txs = await electrum.getHistory('3G4RSoDDF2HRJujqdqHcL6oW3toETE38CH');
// Returns an array of plain objects describing the address's transactions,
// including block height, block hash and timestamp.Get a specific transaction:
const tx = await electrum.getTransaction('18aa...b03f', 641085);
// The second argument (the transaction's block height) is optional.
// Returns a plain object describing the transaction. Includes the block header's
// block height, block hash and timestamp when the block height is given.Get a block header for a block height:
const header = await electrum.getBlockHeader(641085);
// Returns a plain object describing the block header.
// {
// blockHash: string,
// blockHeight: number,
// timestamp: number,
// bits: number,
// nonce: number,
// version: number,
// weight: number,
// prevHash: string | null,
// merkleRoot: string | null,
// }Broadcast a raw transaction to the network:
const tx = await electrum.broadcastTransaction('0012...13d9');
// Returns a plain object describing the broadcast transaction.
// Throws an error on failure.Subscribe for changing receipts for an address:
await electrum.subscribeReceipts('3G4RSoDDF2HRJujqdqHcL6oW3toETE38CH', (receipts) => {
// See the `getReceipts` function for the format of `receipts`.
});
// Calls the callback with the current receipts and whenever the receipts changeSubscribe to blockchain head changes:
await electrum.subscribeHeaders((blockHeader) => {
// See the `getBlockHeader` method for the format of `blockHeader`
});
// Calls the callback with the current header and whenever the header changesThis library uses Websockify as a WebSocket-to-TCP proxy server for communicating with ElectrumX servers. Most ElectrumX server implementations support native websocket connections by now, but no publicly listed server has them enabled.
If you want to use your own ElectrumX server and have native websockets enabled,
you must set the proxy setting to false (Websockify requires appending a line-break
(\n) character at the end of messages, but native ElectrumX websockets do not).
A public Websockify instance is running at https://api.nimiqwatch.com:50002. You can see the Electrum servers that it can proxy to here.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent