# @electrum-cash/protocol

> Library that provides fully typed functions and events for all electrum cash methods.

Latest version **2.6.0** (published 2026-10-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install @electrum-cash/protocol
pnpm add @electrum-cash/protocol
yarn add @electrum-cash/protocol
bun add @electrum-cash/protocol
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.6.0 |
| Published | 2026-10-03 |
| First published | 2024-02-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Dependencies | 3 |
| Unpacked size | 215.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Jonathan Silverblood |
| Maintainers | monsterbitar |
| Keywords | electrum, bitcoin, bitcoin cash |

## Links

- npm: https://www.npmjs.com/package/@electrum-cash/protocol
- Repository: https://gitlab.com/electrum-cash/protocol
- Homepage: https://gitlab.com/electrum-cash/protocol#readme
- Issues: https://gitlab.com/electrum-cash/protocol/issues
- npm.io page: https://npm.io/package/@electrum-cash/protocol

## Dependencies (3)

- [@bitauth/libauth](https://npm.io/package/@bitauth/libauth.md) ^3.0.0
- [@electrum-cash/socket](https://npm.io/package/@electrum-cash/socket.md) ^4.0.1
- [@electrum-cash/network](https://npm.io/package/@electrum-cash/network.md) ^4.4.8

## Recent versions

- 2.6.0 (latest) — 2026-10-03
- 2.6.0-development.16913617998 (development) — 2026-10-03
- 2.5.0-development.16912046273 — 2026-10-03
- 2.5.0-development.16911643886 — 2026-10-03
- 2.5.0 — 2026-10-03
- 2.5.0-development.16910443690 — 2026-10-03
- 2.5.0-development.16910460653 — 2026-10-03
- 2.5.0-development.16910443756 — 2026-10-03
- 2.5.0-development.16910447269 — 2026-10-03
- 2.5.0-development.16906508742 — 2026-10-02
- 2.5.0-development.16906467361 — 2026-10-02
- 2.5.0-development.16905768256 — 2026-10-02
- 2.5.0-development.16905368334 — 2026-10-02
- 2.5.0-development.16904547931 — 2026-10-02
- 2.4.2 — 2026-09-30
- … 55 more at https://npm.io/package/@electrum-cash/protocol/versions

## README

# Introduction

The Electrum Cash Protocol ([`@electrum-cash/protocol`](https://www.npmjs.com/package/@electrum-cash/protocol)) provides fully typed functions and events for all [Electrum Cash](https://electrum-cash-protocol.readthedocs.io/en/latest/index.html) [methods](https://electrum-cash-protocol.readthedocs.io/en/latest/protocol-methods.html).

For complete information on all typings, arguments and options available, read to the [documentation](https://electrum-cash.gitlab.io/protocol/) generated from the source code.

## Usage

### Installation

Installation is easy, just get the library from NPM:

```sh
npm install @electrum-cash/protocol
```

### Setup

Before you can make requests you first need to set up and connect to a server.

```ts
// Import the electrum protocol library.
import { initializeElectrumClient } from '@electrum-cash/protocol';

// Initialize an electrum client with following the electrum protocol.
const electrumClient = await initializeElectrumClient('Electrum Protocol Test', 'bch.imaginary.cash');
```

### Event handling

After you have initialized an electrum client and subscribe to new information, it will emit fully typed subscription events.

```ts
// Set up handler functions for electrum events.
electrumClient.on('blockchain.headers.subscribe', handleNewBlockchainHeaders);
electrumClient.on('blockchain.address.subscribe', handleAddressStatusUpdates);
electrumClient.on('blockchain.transaction.subscribe', handleTransactionStatusUpdates);
electrumClient.on('blockchain.transaction.dsproof.subscribe', handleTransactionDoublespendEvents);

// Subscribe to block headers.
await subscribeToBlockheaderUpdates(electrumClient);

// Subscribe to address status updates for a given address.
await subscribeToAddressUpdates(electrumClient, someAddress);

// Subscribe to transaction block inclusion updates for a given transaction.
await subscribeToTransactionUpdates(electrumClient, someTransactionHash);

// Subscribe to transaction doublespend updates for a given transaction.
await subscribeToDoublespendUpdates(electrumClient, someTransactionHash);
```

### Requesting data

After you have initialized an electrum client you can request data with the following functions.

#### Address

```ts
// Import address related requests.
import { fetchHistory, fetchPendingTransactions, fetchBalance, fetchUnspentTransactionOutputs } from '@electrum-cash/protocol';

// Fetch transaction history for an address.
const currentAddressHistory = await fetchHistory(electrumClient, someAddress);
console.log('history', currentAddressHistory);

// Fetch pending transactions relating to an address.
const pendingTransactions = await fetchPendingTransactions(electrumClient, someAddress);
console.log('pending transactions', pendingTransactions);

// Fetch the current spendable balance of an address.
const currentTrustedBalance = await fetchBalance(electrumClient, someAddress);
console.log('trusted balance', currentTrustedBalance);

// Fetch a list of unspent transaction outputs for an address.
const currentUnspentOutputs = await fetchUnspentTransactionOutputs(electrumClient, someAddress);
console.log('unspent outputs', currentUnspentOutputs);
```


#### Blockchain

```ts
// Import chain related requests.
import { fetchBlockHeaderFromBlockHeight, fetchBlockHeaders, fetchBlockHeaderWithProofFromBlockHeight, fetchCurrentChainTip } from '@electrum-cash/protocol';

// Fetch the block header of a given block height.
const checkpointBlockHeader = await fetchBlockHeaderFromBlockHeight(electrumClient, someBlockHeight);
console.log('header from height', checkpointBlockHeader);

// Fetch three block headers start at a specified height.
const blockHeaders = await fetchBlockHeaders(electrumClient, electrumCheckpoint.height, 3);
console.log('list of headers', blockHeaders);

// Fetch the block header and inclusion proof the server reports.
const checkpointBlockHeaderWithProof = await fetchBlockHeaderWithProofFromBlockHeight(electrumClient, electrumCheckpoint.height, someBlockHeight);
console.log('header with proof', checkpointBlockHeaderWithProof);

// Fetch the current block height, also called the chain tip.
const currentChainTip = await fetchCurrentChainTip(electrumClient);
console.log('current chaintip', currentChainTip);
```


#### Transaction

```ts
// Import transaction related requests.
import { broadcastTransaction, fetchDoublespendProof, fetchTransaction, fetchTransactionBlockHeight, fetchTransactionProof } from '@electrum-cash/protocol';

// Ask the server to broadcast a transaction. The returned hash is checked against the transaction that was sent.
const transactionHash = await broadcastTransaction(electrumClient, someTransactionHex);
console.log('txhash', transactionHash);

// Fetch double spend proofs related to a transaction, if they exist.
const doublespendProof = await fetchDoublespendProof(electrumClient, someTransactionHash);
console.log('dsproof', doublespendProof);

// Fetch a raw transaction. Its hash is checked against the hash that was requested.
const transactionHex = await fetchTransaction(electrumClient, someTransactionHash);
console.log('fetch transaction', transactionHex);

// Fetch the block height a given transaction was included in, if possible.
const transactionBlockHeight= await fetchTransactionBlockHeight(electrumClient, someTransactionHash);
console.log('fetch transaction height', transactionBlockHeight);

// Fetch the merkle proof the server reports.
const transactionProof = await fetchTransactionProof(electrumClient, someTransactionHash, 800649);
console.log('fetch transaction proof', transactionProof);
```


#### UTXO

```ts
// Import UTXO related requests.
import { fetchUnspentTransactionOutputInfo } from '@electrum-cash/protocol';

// Fetch information about an unspent transaction output, or null if it does not exist or is spent.
const unspentOutput = await fetchUnspentTransactionOutputInfo(electrumClient, someTransactionHash, someOutputIndex);
console.log('unspent output', unspentOutput);
```


#### Mempool

```ts
// Import mempool related requests.
import { fetchMempoolFeeHistogram, fetchMempoolInfo } from '@electrum-cash/protocol';

// Fetch a histogram of the fee rates paid by transactions in the mempool.
const feeHistogram = await fetchMempoolFeeHistogram(electrumClient);
console.log('fee histogram', feeHistogram);

// Fetch mempool statistics, such as the current minimum fee rates.
const mempoolInfo = await fetchMempoolInfo(electrumClient);
console.log('mempool info', mempoolInfo);
```


#### Server

```ts
// Import server related requests.
import { fetchServerBanner, fetchServerDonationAddress, fetchServerFeatures, fetchServerPeers, pingServer } from '@electrum-cash/protocol';

// Fetch the banner of the server.
const banner = await fetchServerBanner(electrumClient);
console.log('banner', banner);

// Fetch the donation address of the server.
const donationAddress = await fetchServerDonationAddress(electrumClient);
console.log('donation address', donationAddress);

// Fetch the features and services supported by the server.
const features = await fetchServerFeatures(electrumClient);
console.log('features', features);

// Fetch a list of peer servers known to the server.
const peers = await fetchServerPeers(electrumClient);
console.log('peers', peers);

// Ping the server to ensure it is responding, and to keep the session alive.
await pingServer(electrumClient);
```

## Support

If you find bugs or have problems using this library, you can file issues on the [Gitlab](https://gitlab.com/electrum-cash/protocol/issues).

---
_Source: https://npm.io/package/@electrum-cash/protocol · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
