Class ElectrumXProvider

ElectrumX provider for interacting with Bitcoin network via ElectrumX servers

Remarks

ElectrumXProvider implements a robust connection to ElectrumX servers with:

Automatic server failover and retry logic
WebSocket connection management
Full ElectrumX protocol support
Built-in caching for performance
Address validation and script hash conversion

Features:

Multiple server endpoints with automatic failover
Configurable retry attempts and timeouts
UTXO fetching with mempool awareness
Transaction broadcasting and monitoring
Balance queries with confirmed/unconfirmed breakdown
Fee estimation support

Example

const provider = new ElectrumXProvider({
  endpoints: [
    { host: 'electrum.blockstream.info', port: 50002, ssl: true }
  ],
  network: networks.bitcoin,
  maxRetries: 3
});

const utxos = await provider.getUTXOs('bc1q...');
const balance = await provider.getBalance('bc1q...');

Hierarchy (View Summary)

BaseProvider
- ElectrumXProvider

Constructors

constructor

new ElectrumXProvider(options?: ElectrumXOptions): ElectrumXProvider
Parameters
- Optionaloptions: ElectrumXOptions
Returns ElectrumXProvider
Overrides BaseProvider.constructor
- Defined in providers/electrumx-provider.ts:145

Properties

`Protected`maxRetryDelay

maxRetryDelay: number

`Protected`network

network: Network

`Protected`retries

retries: number

`Protected`retryDelay

retryDelay: number

`Protected`timeout

timeout: number

Methods

broadcastTransaction

broadcastTransaction(hexTx: string): Promise<string>
Broadcast a signed transaction
Parameters
- hexTx: string
Returns Promise<string>
Overrides BaseProvider.broadcastTransaction
- Defined in providers/electrumx-provider.ts:296

`Protected`btcToSatoshis

btcToSatoshis(btc: number): number
Convert BTC to satoshis
Parameters
- btc: number
Returns number
Inherited from BaseProvider.btcToSatoshis
- Defined in providers/base-provider.ts:136

disconnect

disconnect(): Promise<void>
Disconnect from ElectrumX server

Returns Promise<void>
- Defined in providers/electrumx-provider.ts:848

`Protected`executeWithRetry

executeWithRetry<T>(fn: () => Promise<T>, retries?: number): Promise<T>
Execute request with retry logic
Type Parameters
- T
Parameters
- fn: () => Promise<T>
- retries: number = ...
Returns Promise<T>
Inherited from BaseProvider.executeWithRetry
- Defined in providers/base-provider.ts:61

`Protected`executeWithTimeout

executeWithTimeout<T>(fn: () => Promise<T>, timeout?: number): Promise<T>
Execute request with timeout
Type Parameters
- T
Parameters
- fn: () => Promise<T>
- timeout: number = ...
Returns Promise<T>
Inherited from BaseProvider.executeWithTimeout
- Defined in providers/base-provider.ts:87

getAddressHistory

getAddressHistory(
address: string,
options?: AddressHistoryOptions,
): Promise<AddressHistory[]>
Get address transaction history
Parameters
- address: string
- Optionaloptions: AddressHistoryOptions
Returns Promise<AddressHistory[]>
Overrides BaseProvider.getAddressHistory
- Defined in providers/electrumx-provider.ts:365

getBalance

getBalance(address: string): Promise<Balance>
Get balance for a given address
Parameters
- address: string
Returns Promise<Balance>
Overrides BaseProvider.getBalance
- Defined in providers/electrumx-provider.ts:237

getBlockHeight

getBlockHeight(): Promise<number>
Get current block height

Returns Promise<number>
Overrides BaseProvider.getBlockHeight
- Defined in providers/electrumx-provider.ts:352

getConfig

getConfig(): ElectrumXConfig
Get current configuration

Returns ElectrumXConfig
- Defined in providers/electrumx-provider.ts:865

getCurrentEndpoint

getCurrentEndpoint(): null | ElectrumXEndpoint
Get current active endpoint

Returns null | ElectrumXEndpoint
- Defined in providers/electrumx-provider.ts:872

getFailedEndpoints

getFailedEndpoints(): string[]
Get failed endpoints (for debugging)

Returns string[]
- Defined in providers/electrumx-provider.ts:879

getFeeEstimates

getFeeEstimates(): Promise<ElectrumXFeeEstimate>
Get comprehensive fee estimates for multiple confirmation targets

Returns Promise<ElectrumXFeeEstimate>
- Defined in providers/electrumx-provider.ts:312

getFeeRate

getFeeRate(priority?: "low" | "medium" | "high"): Promise<number>
Get current fee rate (sat/vB) for specific priority
Parameters
- priority: "low" | "medium" | "high" = 'medium'
Returns Promise<number>
Overrides BaseProvider.getFeeRate
- Defined in providers/electrumx-provider.ts:336

getNetwork

getNetwork(): Network
Get network this provider is connected to

Returns Network
Inherited from BaseProvider.getNetwork
- Defined in providers/base-provider.ts:54

`Protected`getNormalizedFeeRate

getNormalizedFeeRate(
priority?: "low" | "medium" | "high",
): Promise<NormalizedFeeRate>
Get normalized fee rate ensuring it's within acceptable bounds
Parameters
- priority: "low" | "medium" | "high" = 'medium'
Returns Promise<NormalizedFeeRate>
Inherited from BaseProvider.getNormalizedFeeRate
- Defined in providers/base-provider.ts:153

getNormalizedFeeRates

getNormalizedFeeRates(): Promise<
    {
        high: NormalizedFeeRate;
        low: NormalizedFeeRate;
        medium: NormalizedFeeRate;
        urgent?: NormalizedFeeRate;
    },
>
Get all priority levels with normalized rates

Returns Promise<
    {
        high: NormalizedFeeRate;
        low: NormalizedFeeRate;
        medium: NormalizedFeeRate;
        urgent?: NormalizedFeeRate;
    },
>
Inherited from BaseProvider.getNormalizedFeeRates
- Defined in providers/base-provider.ts:225

`Protected`getProviderSource

getProviderSource(): FeeSource
Get the fee source identifier for this provider Override in child classes to specify the correct source

Returns FeeSource
Inherited from BaseProvider.getProviderSource
- Defined in providers/base-provider.ts:211

getServerInfo

getServerInfo(): null | ElectrumXServerInfo
Get server information

Returns null | ElectrumXServerInfo
- Defined in providers/electrumx-provider.ts:858

getTransaction

getTransaction(txid: string): Promise<Transaction>
Get transaction by ID
Parameters
- txid: string
Returns Promise<Transaction>
Overrides BaseProvider.getTransaction
- Defined in providers/electrumx-provider.ts:258

getUTXOs

getUTXOs(address: string): Promise<UTXO[]>
Get UTXOs for a given address
Parameters
- address: string
Returns Promise<UTXO[]>
Overrides BaseProvider.getUTXOs
- Defined in providers/electrumx-provider.ts:205

isConnected

isConnected(): Promise<boolean>
Check if provider is connected

Returns Promise<boolean>
Overrides BaseProvider.isConnected
- Defined in providers/electrumx-provider.ts:435

`Protected`isValidAddress

isValidAddress(address: string): boolean
Validate Bitcoin address format
Parameters
- address: string
Returns boolean
Inherited from BaseProvider.isValidAddress
- Defined in providers/base-provider.ts:109

`Protected`isValidTxid

isValidTxid(txid: string): boolean
Validate transaction ID format
Parameters
- txid: string
Returns boolean
Inherited from BaseProvider.isValidTxid
- Defined in providers/base-provider.ts:122

`Protected`normalizeFeeRate

normalizeFeeRate(rate: any, source: FeeSource): null | NormalizedFeeRate
Normalize fee rate from provider response to consistent satsPerVB
Parameters
- rate: any
- source: FeeSource
Returns null | NormalizedFeeRate
Inherited from BaseProvider.normalizeFeeRate
- Defined in providers/base-provider.ts:143

`Protected`normalizeLegacyFeeResponse

normalizeLegacyFeeResponse(
feeResponse: any,
source: FeeSource,
): null | NormalizedFeeRate
Convert legacy fee rate response to normalized format
Parameters
- feeResponse: any
- source: FeeSource
Returns null | NormalizedFeeRate
Inherited from BaseProvider.normalizeLegacyFeeResponse
- Defined in providers/base-provider.ts:177

resetFailedEndpoints

resetFailedEndpoints(): void
Reset failed endpoints (to allow retry)

Returns void
- Defined in providers/electrumx-provider.ts:886

`Protected`satoshisToBTC

satoshisToBTC(satoshis: number): number
Convert satoshis to BTC
Parameters
- satoshis: number
Returns number
Inherited from BaseProvider.satoshisToBTC
- Defined in providers/base-provider.ts:129

`Protected`sleep

sleep(ms: number): Promise<void>
Sleep for specified milliseconds
Parameters
- ms: number
Returns Promise<void>
Inherited from BaseProvider.sleep
- Defined in providers/base-provider.ts:102

testEndpoints

testEndpoints(): Promise<
{ endpoint: ElectrumXEndpoint; error?: string; success: boolean }[],
>
Test connection to all configured endpoints

Returns Promise<{ endpoint: ElectrumXEndpoint; error?: string; success: boolean }[]>
- Defined in providers/electrumx-provider.ts:893

`Protected`validateFeeRate

validateFeeRate(satsPerVB: number): boolean
Validate that fee rate is reasonable for the current network conditions
Parameters
- satsPerVB: number
Returns boolean
Inherited from BaseProvider.validateFeeRate
- Defined in providers/base-provider.ts:218

Class ElectrumXProvider

Remarks

Example

Hierarchy (View Summary)

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns ElectrumXProvider

Properties

ProtectedmaxRetryDelay

Protectednetwork

Protectedretries

ProtectedretryDelay

Protectedtimeout

Methods

broadcastTransaction

Parameters

Returns Promise<string>

ProtectedbtcToSatoshis

Parameters

Returns number

disconnect

Returns Promise<void>

ProtectedexecuteWithRetry

Type Parameters

Parameters

Returns Promise<T>

ProtectedexecuteWithTimeout

Type Parameters

Parameters

Returns Promise<T>

getAddressHistory

Parameters

Returns Promise<AddressHistory[]>

getBalance

Parameters

Returns Promise<Balance>

getBlockHeight

Returns Promise<number>

getConfig

Returns ElectrumXConfig

getCurrentEndpoint

Returns null | ElectrumXEndpoint

getFailedEndpoints

Returns string[]

getFeeEstimates

Returns Promise<ElectrumXFeeEstimate>

getFeeRate

Parameters

Returns Promise<number>

getNetwork

Returns Network

ProtectedgetNormalizedFeeRate

Parameters

Returns Promise<NormalizedFeeRate>

getNormalizedFeeRates

Returns Promise< { high: NormalizedFeeRate; low: NormalizedFeeRate; medium: NormalizedFeeRate; urgent?: NormalizedFeeRate; },>

ProtectedgetProviderSource

Returns FeeSource

getServerInfo

Returns null | ElectrumXServerInfo

getTransaction

Parameters

Returns Promise<Transaction>

getUTXOs

Parameters

Returns Promise<UTXO[]>

isConnected

Returns Promise<boolean>

ProtectedisValidAddress

Parameters

Returns boolean

ProtectedisValidTxid

Parameters

Returns boolean

ProtectednormalizeFeeRate

`Protected`maxRetryDelay

`Protected`network

`Protected`retries

`Protected`retryDelay

`Protected`timeout

`Protected`btcToSatoshis

`Protected`executeWithRetry

`Protected`executeWithTimeout

`Protected`getNormalizedFeeRate

Returns Promise<
{
high: NormalizedFeeRate;
low: NormalizedFeeRate;
medium: NormalizedFeeRate;
urgent?: NormalizedFeeRate;
},
>

`Protected`getProviderSource

`Protected`isValidAddress

`Protected`isValidTxid

`Protected`normalizeFeeRate

`Protected`normalizeLegacyFeeResponse

`Protected`satoshisToBTC

`Protected`sleep

`Protected`validateFeeRate