@exodus/bitcoin-api 4.11.1 → 4.13.0

package/CHANGELOG.md

@@ -3,6 +3,26 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [4.13.0](https://github.com/ExodusMovement/assets/compare/@exodus/bitcoin-api@4.12.0...@exodus/bitcoin-api@4.13.0) (2026-03-20)
+
+
+### Features
+
+
+* feat(bitcoin-api): add mempool rest client with insight parity (#7615)
+
+
+
+## [4.12.0](https://github.com/ExodusMovement/assets/compare/@exodus/bitcoin-api@4.11.1...@exodus/bitcoin-api@4.12.0) (2026-03-20)
+
+
+### Features
+
+
+* feat(bitcoin-api): add mempool ws client with insight parity (#7625)
+
+
+
 ## [4.11.1](https://github.com/ExodusMovement/assets/compare/@exodus/bitcoin-api@4.11.0...@exodus/bitcoin-api@4.11.1) (2026-03-19)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/bitcoin-api",
-  "version": "4.11.1",
+  "version": "4.13.0",
   "description": "Bitcoin transaction and fee monitors, RPC with the blockchain node, other networking code.",
   "type": "module",
   "main": "src/index.js",
@@ -32,7 +32,7 @@
     "@exodus/currency": "^6.0.1",
     "@exodus/i18n-dummy": "^1.0.0",
     "@exodus/key-identifier": "^1.3.0",
-    "@exodus/models": "^12.0.1",
+    "@exodus/models": "^13.0.0",
     "@exodus/safe-string": "^1.4.0",
     "@exodus/send-validation-model": "^1.0.0",
     "@exodus/simple-retry": "^0.0.6",
@@ -41,6 +41,7 @@
     "bip32-path": "^0.4.2",
     "bs58check": "^3.0.1",
     "delay": "^4.0.1",
+    "eventemitter3": "^5.0.4",
     "events": "^3.3.0",
     "lodash": "^4.17.21",
     "minimalistic-assert": "^1.0.1",
@@ -62,5 +63,5 @@
     "type": "git",
     "url": "git+https://github.com/ExodusMovement/assets.git"
   },
-  "gitHead": "2933d00c85191b547e822a292f1884b8d6d9e6d7"
+  "gitHead": "49d472ae5c602ba68329227e0e0cd3a9b4568fba"
 }

package/src/index.js

@@ -3,6 +3,8 @@ export * from './balances.js'
 export * from './btc-address.js'
 export * from './btc-like-address.js'
 export * from './btc-like-keys.js'
+export { default as MempoolRestClient } from './insight-api-client/mempool-rest-client.js'
+export { default as MempoolWSClient } from './insight-api-client/mempool-ws-client.js'
 export { default as InsightAPIClient } from './insight-api-client/index.js'
 export { default as InsightWSClient } from './insight-api-client/ws.js'
 export { default as bip44Constants } from './constants/bip44.js'

package/src/insight-api-client/mempool-rest-client.js

@@ -0,0 +1,660 @@
+import { safeString } from '@exodus/safe-string'
+import { retry } from '@exodus/simple-retry'
+import { TraceId } from '@exodus/traceparent'
+import delay from 'delay'
+import urlJoin from 'url-join'
+
+const API_PAGE_SIZE = 25
+const DEFAULT_PAGE_SIZE = 10
+const RETRY_WAIT_TIMES = ['5s', '10s', '20s', '30s']
+
+const MEMPOOL_HTTP_ERROR_MESSAGE = safeString`mempool-api-http-error`
+const MEMPOOL_INSIGHT_JSON_ERROR_MESSAGE = safeString`mempool-insight-api-invalid-json`
+const MEMPOOL_INSIGHT_MISSING_TXID_MESSAGE = safeString`mempool-insight-api-missing-txid`
+const MEMPOOL_INSIGHT_HTTP_ERROR_BROADCAST_MESSAGE = safeString`mempool-insight-api-http-error:broadcast`
+const MEMPOOL_JSON_ERROR_MESSAGE = safeString`mempool-api-invalid-json`
+const MEMPOOL_TEXT_ERROR_MESSAGE = safeString`mempool-api-invalid-text`
+const MEMPOOL_HTTP_ERROR_TX_MESSAGE = safeString`mempool-api-http-error:tx`
+const MEMPOOL_HTTP_ERROR_RAWTX_MESSAGE = safeString`mempool-api-http-error:rawtx`
+const MEMPOOL_HTTP_ERROR_BALANCE_MESSAGE = safeString`mempool-api-http-error:balance`
+const MEMPOOL_HTTP_ERROR_ADDR_TXS_MESSAGE = safeString`mempool-api-http-error:address-txs`
+const MEMPOOL_HTTP_ERROR_UTXO_MESSAGE = safeString`mempool-api-http-error:utxo`
+const MEMPOOL_HTTP_ERROR_PREVOUTS_MESSAGE = safeString`mempool-api-http-error:prevouts`
+const MEMPOOL_HTTP_ERROR_OUTSPENDS_MESSAGE = safeString`mempool-api-http-error:outspends`
+const MEMPOOL_HTTP_ERROR_STATUS_MESSAGE = safeString`mempool-api-http-error:status`
+const MEMPOOL_HTTP_ERROR_FEES_MESSAGE = safeString`mempool-api-http-error:fees`
+const MEMPOOL_HTTP_ERROR_CPFP_MESSAGE = safeString`mempool-api-http-error:cpfp`
+const MEMPOOL_FEES_PAYLOAD_ERROR_MESSAGE = safeString`mempool-api-invalid-fees-payload`
+const MEMPOOL_INVALID_VALUE_ERROR_MESSAGE = safeString`mempool-api-invalid-value`
+
+const parseBroadcastErrorReason = (data) => {
+  if (!data) {
+    return null
+  }
+
+  try {
+    const parsed = JSON.parse(data)
+    return parsed?.error || data
+  } catch {
+    return data
+  }
+}
+
+const isFiniteNumber = (value) => typeof value === 'number' && Number.isFinite(value)
+
+const toBTCStringFromSatsString = (satsString) => {
+  let value = String(satsString)
+  while (value.length <= 8) value = `0${value}`
+  return `${value.slice(0, -8)}.${value.slice(-8)}`
+}
+
+const toBTCString = (sats) => {
+  if (isFiniteNumber(sats)) {
+    return toBTCStringFromSatsString(Math.trunc(sats))
+  }
+
+  if (typeof sats === 'string' || typeof sats === 'bigint') {
+    return toBTCStringFromSatsString(sats)
+  }
+
+  throw new Error(MEMPOOL_INVALID_VALUE_ERROR_MESSAGE)
+}
+
+const toBTC = (sats) => {
+  return Number.parseFloat(toBTCString(sats))
+}
+
+const normalizeTxConfirmations = (status, tipHeight) => {
+  const isConfirmed = !!status?.confirmed
+  const blockHeight = status?.block_height
+  if (!isConfirmed || !Number.isInteger(blockHeight) || !Number.isInteger(tipHeight)) {
+    return 0
+  }
+
+  return Math.max(0, tipHeight - blockHeight + 1)
+}
+
+const getNextBlockMinimumFee = (blocks) => {
+  if (!Array.isArray(blocks) || blocks.length === 0) {
+    throw new Error(MEMPOOL_FEES_PAYLOAD_ERROR_MESSAGE)
+  }
+
+  const firstBlock = blocks[0]
+  const feeRange = firstBlock && Array.isArray(firstBlock.feeRange) ? firstBlock.feeRange : null
+  if (!feeRange || feeRange.length === 0) {
+    throw new Error(MEMPOOL_FEES_PAYLOAD_ERROR_MESSAGE)
+  }
+
+  return Math.ceil(feeRange[0])
+}
+
+const getMinimumFee = ({ minimumFee, hourFee, configMinFeeRate, nextBlockMinimumFee }) => {
+  return Math.min(Math.max(minimumFee, configMinFeeRate), Math.min(hourFee, nextBlockMinimumFee))
+}
+
+const createHttpError = (response, message) => {
+  const error = new Error(message)
+  const traceId = TraceId.fromResponse && TraceId.fromResponse(response)
+  if (traceId) {
+    error.traceId = traceId
+  }
+
+  error.code = `${response.status}`
+  return error
+}
+
+async function withRetry(fn, args = [], { waitTimes = RETRY_WAIT_TIMES } = {}) {
+  const fetchWithRetry = retry(fn, { delayTimesMs: waitTimes })
+  return fetchWithRetry(...args)
+}
+
+async function fetchJson(url, fetchOptions, { nullWhen404 = false, httpErrorMessage } = {}) {
+  const response = await fetch(url, fetchOptions)
+  if (nullWhen404 && response.status === 404) {
+    return null
+  }
+
+  if (!response.ok) {
+    throw createHttpError(response, httpErrorMessage || MEMPOOL_HTTP_ERROR_MESSAGE)
+  }
+
+  try {
+    return await response.json()
+  } catch (err) {
+    const error = new Error(MEMPOOL_JSON_ERROR_MESSAGE, { cause: err })
+    const traceId = TraceId.fromResponse && TraceId.fromResponse(response)
+    if (traceId) {
+      error.traceId = traceId
+    }
+
+    throw error
+  }
+}
+
+async function fetchText(url, fetchOptions, { nullWhen404 = false, httpErrorMessage } = {}) {
+  const response = await fetch(url, fetchOptions)
+  if (nullWhen404 && response.status === 404) {
+    return null
+  }
+
+  if (!response.ok) {
+    throw createHttpError(response, httpErrorMessage || MEMPOOL_HTTP_ERROR_MESSAGE)
+  }
+
+  try {
+    return await response.text()
+  } catch (err) {
+    const error = new Error(MEMPOOL_TEXT_ERROR_MESSAGE, { cause: err })
+    const traceId = TraceId.fromResponse && TraceId.fromResponse(response)
+    if (traceId) {
+      error.traceId = traceId
+    }
+
+    throw error
+  }
+}
+
+const normalizeVin = (vin) => {
+  if (!vin || vin.is_coinbase) return {}
+  return {
+    txid: vin.txid,
+    vout: vin.vout,
+    addr: vin.prevout?.scriptpubkey_address,
+    value: toBTCString(vin.prevout?.value),
+  }
+}
+
+const normalizeVout = (vout, index, outspends) => {
+  const outspend = Array.isArray(outspends) ? outspends[index] : undefined
+  const spentTxId =
+    outspend?.spent && typeof outspend?.txid === 'string' ? outspend.txid : undefined
+  const spentIndex = outspend?.spent && typeof outspend?.vin === 'number' ? outspend.vin : undefined
+  return {
+    n: Number.isInteger(vout?.n) ? vout.n : Number.isInteger(vout?.vout) ? vout.vout : index,
+    value: toBTCString(vout?.value),
+    spentTxId,
+    spentIndex,
+    scriptPubKey: {
+      hex: vout?.scriptpubkey,
+      addresses: vout?.scriptpubkey_address ? [vout.scriptpubkey_address] : [],
+    },
+  }
+}
+
+const normalizeTx = (tx, tipHeight, outspends) => {
+  const normalizedVin = Array.isArray(tx?.vin) ? tx.vin.map((vin) => normalizeVin(vin)) : []
+  const normalizedVout = Array.isArray(tx?.vout)
+    ? tx.vout.map((vout, index) => normalizeVout(vout, index, outspends))
+    : []
+  const vsize = Number.isInteger(tx?.weight) ? Math.ceil(tx.weight / 4) : undefined
+  const rbf =
+    Array.isArray(tx?.vin) &&
+    tx.vin.some((vin) => Number.isInteger(vin?.sequence) && vin.sequence < 0xff_ff_ff_fe)
+
+  return {
+    ...tx,
+    txid: tx?.txid,
+    vin: normalizedVin,
+    vout: normalizedVout,
+    time: tx?.status?.block_time,
+    blockheight: tx?.status?.block_height ?? -1,
+    fees: toBTC(tx?.fee),
+    vsize,
+    rbf,
+    confirmations: normalizeTxConfirmations(tx?.status, tipHeight),
+  }
+}
+
+export default class MempoolRestClient {
+  constructor({
+    baseURL,
+    insightBaseURL,
+    retryWaitTimes = RETRY_WAIT_TIMES,
+    configMinFeeRate = 0,
+  } = {}) {
+    this._baseURL = baseURL
+    this._insightBaseURL = insightBaseURL
+    this._retryWaitTimes = retryWaitTimes
+    this._configMinFeeRate = configMinFeeRate
+  }
+
+  setBaseUrl(baseURL) {
+    this._baseURL = baseURL
+  }
+
+  setInsightBaseUrl(baseURL) {
+    this._insightBaseURL = baseURL
+  }
+
+  _apiUrl(path, { version } = {}) {
+    return urlJoin(this._baseURL, version === 'v1' ? '/api/v1' : '/api', path)
+  }
+
+  async _fetchTipHeight() {
+    const tipText = await fetchText(
+      this._apiUrl('/blocks/tip/height'),
+      { timeout: 10_000 },
+      { httpErrorMessage: MEMPOOL_HTTP_ERROR_STATUS_MESSAGE }
+    )
+    const tipHeight = Number.parseInt(tipText, 10)
+    if (!Number.isInteger(tipHeight) || tipHeight < 0) {
+      throw new Error(MEMPOOL_TEXT_ERROR_MESSAGE)
+    }
+
+    return tipHeight
+  }
+
+  async _fetchTxOutspends(txid) {
+    const encodedTxid = encodeURIComponent(txid)
+    const outspends = await fetchJson(this._apiUrl(`/tx/${encodedTxid}/outspends`), undefined, {
+      nullWhen404: true,
+      httpErrorMessage: MEMPOOL_HTTP_ERROR_OUTSPENDS_MESSAGE,
+    })
+    return Array.isArray(outspends) ? outspends : []
+  }
+
+  async _fetchTxOutspendsBatch(txids) {
+    const query = new URLSearchParams({ txids: txids.join(',') }).toString()
+    const result = await withRetry(
+      fetchJson,
+      [
+        this._apiUrl(`/txs/outspends?${query}`),
+        undefined,
+        { nullWhen404: true, httpErrorMessage: MEMPOOL_HTTP_ERROR_OUTSPENDS_MESSAGE },
+      ],
+      { waitTimes: this._retryWaitTimes }
+    )
+
+    return Array.isArray(result) ? result : []
+  }
+
+  async _fetchOutspendsByTxids(txids) {
+    const txidList = Array.isArray(txids) ? txids : []
+    const outspendsByTxid = new Map()
+    if (txidList.length === 0) return outspendsByTxid
+
+    const BATCH_SIZE = 50
+    for (let i = 0; i < txidList.length; i += BATCH_SIZE) {
+      const batchTxids = txidList.slice(i, i + BATCH_SIZE)
+      const batched = await this._fetchTxOutspendsBatch(batchTxids)
+
+      for (const [j, batchTxid] of batchTxids.entries()) {
+        outspendsByTxid.set(batchTxid, Array.isArray(batched[j]) ? batched[j] : [])
+      }
+    }
+
+    return outspendsByTxid
+  }
+
+  async _fetchPrevouts(outpoints) {
+    return fetchJson(
+      this._apiUrl('/prevouts', { version: 'v1' }),
+      {
+        method: 'post',
+        headers: {
+          Accept: 'application/json',
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(outpoints),
+      },
+      {
+        httpErrorMessage: MEMPOOL_HTTP_ERROR_PREVOUTS_MESSAGE,
+      }
+    )
+  }
+
+  async _fetchMultiAddressTxPage(addresses, { afterTxId, maxTxs }) {
+    const query = new URLSearchParams()
+    if (afterTxId) {
+      query.set('after_txid', afterTxId)
+    }
+
+    if (Number.isInteger(maxTxs) && maxTxs > 0) {
+      query.set('max_txs', `${maxTxs}`)
+    }
+
+    const queryString = query.toString()
+    const path = '/addresses/txs' + (queryString ? `?${queryString}` : '')
+    const page = await withRetry(
+      fetchJson,
+      [
+        this._apiUrl(path),
+        {
+          method: 'post',
+          headers: {
+            Accept: 'application/json',
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify(addresses),
+        },
+        { httpErrorMessage: MEMPOOL_HTTP_ERROR_ADDR_TXS_MESSAGE },
+      ],
+      { waitTimes: this._retryWaitTimes }
+    )
+    const items = Array.isArray(page) ? page : []
+    const nextAfterTxId = items[items.length - 1]?.txid
+    const effectivePageSize = Number.isInteger(maxTxs) && maxTxs > 0 ? maxTxs : API_PAGE_SIZE
+    const hasMore = !!nextAfterTxId && items.length >= effectivePageSize
+
+    return { items, nextAfterTxId, hasMore }
+  }
+
+  async fetchBalance(address) {
+    const encodedAddress = encodeURIComponent(address)
+    const utxos = await fetchJson(this._apiUrl(`/address/${encodedAddress}/utxo`), undefined, {
+      httpErrorMessage: MEMPOOL_HTTP_ERROR_BALANCE_MESSAGE,
+    })
+    const values = Array.isArray(utxos) ? utxos : []
+    const totalSats = values.reduce((sum, utxo) => sum + Number(utxo?.value || 0), 0)
+    return {
+      utxoCount: values.length,
+      balance: toBTC(totalSats),
+    }
+  }
+
+  async fetchBlockHeight() {
+    return this._fetchTipHeight()
+  }
+
+  async fetchTx(txid) {
+    const tipHeightPromise = this._fetchTipHeight()
+    const encodedTxid = encodeURIComponent(txid)
+    const tx = await fetchJson(this._apiUrl(`/tx/${encodedTxid}`), undefined, {
+      nullWhen404: true,
+      httpErrorMessage: MEMPOOL_HTTP_ERROR_TX_MESSAGE,
+    })
+
+    if (!tx) return null
+
+    const outspends =
+      Array.isArray(tx?.vout) && tx.vout.length > 0 ? await this._fetchTxOutspends(txid) : undefined
+    const tipHeight = await tipHeightPromise
+    return normalizeTx(tx, tipHeight, outspends)
+  }
+
+  async fetchTxObject(txid) {
+    return this.fetchTx(txid)
+  }
+
+  async fetchRawTx(txid) {
+    const encodedTxid = encodeURIComponent(txid)
+    const rawTx = await fetchText(this._apiUrl(`/tx/${encodedTxid}/hex`), undefined, {
+      httpErrorMessage: MEMPOOL_HTTP_ERROR_RAWTX_MESSAGE,
+    })
+    return String(rawTx).trim()
+  }
+
+  async fetchTxData(addresses, requestOpts = {}) {
+    if (!Array.isArray(addresses) || addresses.length === 0) {
+      return { items: [] }
+    }
+
+    const from = Number.isInteger(requestOpts.from) ? Math.max(0, requestOpts.from) : 0
+    const to = Number.isInteger(requestOpts.to)
+      ? Math.max(from, requestOpts.to)
+      : Math.max(from + DEFAULT_PAGE_SIZE, DEFAULT_PAGE_SIZE)
+
+    const maxTxs = Math.max(API_PAGE_SIZE, to - from)
+    const shouldIncludeSpent = requestOpts?.noSpent !== 1
+    let afterTxId
+    const dedupedTxs = new Map()
+    const tipHeightPromise = this._fetchTipHeight()
+
+    while (dedupedTxs.size < to) {
+      const previousCursor = afterTxId
+      const page = await this._fetchMultiAddressTxPage(addresses, { afterTxId, maxTxs })
+      afterTxId = page.nextAfterTxId
+      const txsNeedingOutspends = []
+
+      for (const tx of page.items) {
+        txsNeedingOutspends.push(tx)
+      }
+
+      const outspendsByTxid =
+        shouldIncludeSpent && txsNeedingOutspends.length > 0
+          ? await this._fetchOutspendsByTxids(
+              txsNeedingOutspends
+                .filter((tx) => Array.isArray(tx?.vout) && tx.vout.length > 0)
+                .map((tx) => tx.txid)
+            )
+          : new Map()
+
+      for (const tx of txsNeedingOutspends) {
+        const outspends = shouldIncludeSpent ? outspendsByTxid.get(tx.txid) : undefined
+        const tipHeight = await tipHeightPromise
+
+        dedupedTxs.delete(tx.txid)
+        dedupedTxs.set(tx.txid, normalizeTx(tx, tipHeight, outspends))
+      }
+
+      if (afterTxId === previousCursor || !page.hasMore) {
+        break
+      }
+    }
+
+    return {
+      items: [...dedupedTxs.values()].slice(from, to),
+    }
+  }
+
+  async fetchAllTxData(
+    addresses = [],
+    chunk = 25,
+    httpDelay = 2000,
+    shouldStopFetching = () => {}
+  ) {
+    if (!Array.isArray(addresses) || addresses.length === 0) {
+      return []
+    }
+
+    const dedupedTxs = new Map()
+    const tipHeightPromise = this._fetchTipHeight()
+    const maxTxs = Math.max(1, chunk)
+    let afterTxId
+
+    while (true) {
+      const txs = []
+      const previousCursor = afterTxId
+      const page = await this._fetchMultiAddressTxPage(addresses, { afterTxId, maxTxs })
+      afterTxId = page.nextAfterTxId
+      const pageTxs = []
+
+      for (const tx of page.items) {
+        pageTxs.push(tx)
+      }
+
+      const txidsNeedingOutspends = pageTxs
+        .filter((tx) => Array.isArray(tx?.vout) && tx.vout.length > 0)
+        .map((tx) => tx.txid)
+
+      const outspendsByTxid =
+        txidsNeedingOutspends.length > 0
+          ? await this._fetchOutspendsByTxids(txidsNeedingOutspends)
+          : new Map()
+
+      for (const tx of pageTxs) {
+        const outspends =
+          Array.isArray(tx?.vout) && tx.vout.length > 0 ? outspendsByTxid.get(tx.txid) : undefined
+        const tipHeight = await tipHeightPromise
+
+        const normalizedTx = normalizeTx(tx, tipHeight, outspends)
+        txs.push(normalizedTx)
+        dedupedTxs.delete(tx.txid)
+        dedupedTxs.set(tx.txid, normalizedTx)
+      }
+
+      if (afterTxId === previousCursor || !page.hasMore) {
+        break
+      }
+
+      if (txs.length > 0 && shouldStopFetching && (await shouldStopFetching(txs))) break
+
+      await delay(httpDelay)
+    }
+
+    return [...dedupedTxs.values()]
+  }
+
+  async fetchUTXOs(address) {
+    const encodedAddress = encodeURIComponent(address)
+    const utxos = await fetchJson(this._apiUrl(`/address/${encodedAddress}/utxo`), undefined, {
+      httpErrorMessage: MEMPOOL_HTTP_ERROR_UTXO_MESSAGE,
+    })
+
+    if (!Array.isArray(utxos) || utxos.length === 0) return []
+    const tipHeightPromise = this._fetchTipHeight()
+    const outpoints = utxos.map((utxo) => ({ txid: utxo.txid, vout: utxo.vout }))
+
+    const scriptsByOutpoint = new Map()
+    for (let i = 0; i < outpoints.length; i += 100) {
+      const batch = outpoints.slice(i, i + 100)
+      const prevouts = await this._fetchPrevouts(batch)
+      if (!Array.isArray(prevouts)) continue
+
+      for (const [j, outpoint] of batch.entries()) {
+        const script = prevouts[j]?.prevout?.scriptpubkey
+        if (typeof script === 'string') {
+          scriptsByOutpoint.set(`${outpoint.txid}:${outpoint.vout}`, script)
+        }
+      }
+    }
+
+    const tipHeight = await tipHeightPromise
+
+    return utxos.map((utxo) => ({
+      address,
+      txId: utxo.txid,
+      confirmations: normalizeTxConfirmations(utxo.status, tipHeight),
+      value: toBTC(utxo.value),
+      vout: utxo.vout,
+      height: utxo.status?.block_height ?? null,
+      script: scriptsByOutpoint.get(`${utxo.txid}:${utxo.vout}`),
+    }))
+  }
+
+  async fetchFeeRate() {
+    const [mempoolFeeRate, blocks] = await Promise.all([
+      fetchJson(this._apiUrl('/fees/recommended', { version: 'v1' }), undefined, {
+        httpErrorMessage: MEMPOOL_HTTP_ERROR_FEES_MESSAGE,
+      }),
+      fetchJson(this._apiUrl('/fees/mempool-blocks', { version: 'v1' }), undefined, {
+        httpErrorMessage: MEMPOOL_HTTP_ERROR_FEES_MESSAGE,
+      }),
+    ])
+    const fastestFee = mempoolFeeRate?.fastestFee
+    const halfHourFee = mempoolFeeRate?.halfHourFee
+    const hourFee = mempoolFeeRate?.hourFee
+    const economyFee = mempoolFeeRate?.economyFee
+    const baseMinimumFee = mempoolFeeRate?.minimumFee
+    const nextBlockMinimumFee = getNextBlockMinimumFee(blocks)
+
+    const minimumFee = getMinimumFee({
+      minimumFee: baseMinimumFee,
+      hourFee,
+      configMinFeeRate: this._configMinFeeRate,
+      nextBlockMinimumFee,
+    })
+
+    if (
+      !isFiniteNumber(fastestFee) ||
+      !isFiniteNumber(halfHourFee) ||
+      !isFiniteNumber(hourFee) ||
+      !isFiniteNumber(economyFee) ||
+      !isFiniteNumber(baseMinimumFee) ||
+      !isFiniteNumber(nextBlockMinimumFee) ||
+      !isFiniteNumber(minimumFee)
+    ) {
+      throw new Error(MEMPOOL_FEES_PAYLOAD_ERROR_MESSAGE)
+    }
+
+    return {
+      fastestFee,
+      halfHourFee,
+      hourFee,
+      minimumFee,
+      economyFee,
+      nextBlockMinimumFee,
+    }
+  }
+
+  async fetchUnconfirmedAncestorData(txid) {
+    const encodedTxid = encodeURIComponent(txid)
+    const data = await fetchJson(
+      this._apiUrl(`/cpfp/${encodedTxid}`, { version: 'v1' }),
+      undefined,
+      {
+        httpErrorMessage: MEMPOOL_HTTP_ERROR_CPFP_MESSAGE,
+      }
+    )
+    const ancestors = Array.isArray(data?.ancestors) ? data.ancestors : []
+    const ancestorFees = ancestors.reduce((sum, ancestor) => {
+      if (!isFiniteNumber(ancestor?.fee)) return sum
+      return sum + ancestor.fee
+    }, 0)
+    const ancestorSize = ancestors.reduce((sum, ancestor) => {
+      if (!isFiniteNumber(ancestor?.weight)) return sum
+      return sum + Math.ceil(ancestor.weight / 4)
+    }, 0)
+    const selfFees = isFiniteNumber(data?.fee) ? data.fee : 0
+    const tx = await fetchJson(this._apiUrl(`/tx/${encodedTxid}`), undefined, {
+      nullWhen404: true,
+      httpErrorMessage: MEMPOOL_HTTP_ERROR_TX_MESSAGE,
+    })
+    const selfSize = isFiniteNumber(tx?.weight) ? Math.ceil(tx.weight / 4) : 0
+
+    const fees = ancestorFees + selfFees
+    const size = ancestorSize + selfSize
+    if (fees <= 0 || size <= 0) return { size: 0, fees: 0 }
+    return { size, fees: Math.round(fees) }
+  }
+
+  // Keep broadcast behavior aligned with the existing insight client.
+  // Our Insight/Magnifier path fans out to Exodus-managed bitcoin nodes and has the
+  // operational behavior we already depend on when propagation is slow or a rejection
+  // is temporary. The mempool REST API alone is not a drop-in replacement for that.
+  async broadcastTx(rawTx) {
+    const payload = rawTx instanceof Uint8Array ? Buffer.from(rawTx).toString('hex') : rawTx
+    const response = await fetch(urlJoin(this._insightBaseURL, '/tx/send'), {
+      method: 'post',
+      headers: {
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ rawtx: payload }),
+    })
+
+    let data = await response.text()
+
+    if (!response.ok) {
+      console.warn(`Mempool Client's Insight Broadcast HTTP Error:`)
+      console.warn(response.statusText)
+      console.warn(data)
+      const error = createHttpError(response, MEMPOOL_INSIGHT_HTTP_ERROR_BROADCAST_MESSAGE)
+      error.reason = parseBroadcastErrorReason(data)
+      throw error
+    }
+
+    try {
+      data = JSON.parse(data)
+    } catch (err) {
+      console.warn(`Mempool Client's Insight Broadcast JSON Parse Error:`, err.message, data)
+      const error = new Error(MEMPOOL_INSIGHT_JSON_ERROR_MESSAGE, { cause: err })
+      const traceId = TraceId.fromResponse && TraceId.fromResponse(response)
+      if (traceId) {
+        error.traceId = traceId
+      }
+
+      throw error
+    }
+
+    if (!data.txid) {
+      const error = new Error(MEMPOOL_INSIGHT_MISSING_TXID_MESSAGE)
+      const traceId = TraceId.fromResponse && TraceId.fromResponse(response)
+      if (traceId) {
+        error.traceId = traceId
+      }
+
+      throw error
+    }
+  }
+}

package/src/insight-api-client/mempool-ws-client.js

@@ -0,0 +1,239 @@
+import EventEmitter from 'eventemitter3'
+
+const DEFAULT_RECONNECTION_DELAY = 10_000
+const DEFAULT_RECONNECTION_DELAY_MAX = 30_000
+const DEFAULT_PING_INTERVAL = 25_000
+const BLOCK_SUBSCRIBED_ASSETS = new Set(['bitcoin', 'bitcoinregtest', 'bitcointestnet'])
+
+const toMessageString = (data) => {
+  if (typeof data === 'string') return data
+  // Keep tiny compatibility for ws-style Buffer payloads.
+  if (data && typeof data.toString === 'function') return data.toString('utf8')
+
+  return ''
+}
+
+const flattenAddressEntries = (data) => {
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return []
+  return Object.entries(data).filter(([address, payload]) => typeof address === 'string' && payload)
+}
+
+const tryParseJSON = (rawData) => {
+  const message = toMessageString(rawData)
+  if (!message) return null
+
+  try {
+    return JSON.parse(message)
+  } catch (error) {
+    console.warn('mempool-ws-client parse failed', {
+      error: error instanceof Error ? error.message : error,
+      preview: message.slice(0, 200),
+    })
+    return null
+  }
+}
+
+const getReconnectDelay = (attempt, reconnectionDelay, reconnectionDelayMax) => {
+  const baseDelay = reconnectionDelay * 2 ** Math.max(0, attempt)
+  const cappedDelay = Math.min(baseDelay, reconnectionDelayMax)
+  const jitter = 0.8 + Math.random() * 0.4
+  return Math.round(cappedDelay * jitter)
+}
+
+const normalizeOptions = (assetName, opts = {}) => {
+  return {
+    reconnectionDelay: DEFAULT_RECONNECTION_DELAY,
+    reconnectionDelayMax: DEFAULT_RECONNECTION_DELAY_MAX,
+    pingIntervalMs: DEFAULT_PING_INTERVAL,
+    subscribeBlocks: BLOCK_SUBSCRIBED_ASSETS.has(assetName),
+    ...opts,
+  }
+}
+
+export default class MempoolWSClient extends EventEmitter {
+  constructor(url, assetName, { WebSocketClass = globalThis.WebSocket } = {}) {
+    super()
+    this.url = url
+    this.assetName = assetName
+    this.WebSocketClass = WebSocketClass
+    this.socket = null
+    this.addresses = []
+    this.options = null
+    this.reconnectAttempt = 0
+    this.reconnectTimer = null
+    this.pingInterval = null
+    this.closed = false
+    this.socketListeners = null
+    this.connected = false
+  }
+
+  connect(addresses = [], opts = {}) {
+    // Guard against accidental duplicate connect() calls creating parallel sockets.
+    if (this.socket || this.reconnectTimer) {
+      this.close()
+    }
+
+    this.addresses = [...new Set(addresses.filter((address) => typeof address === 'string'))]
+    this.options = normalizeOptions(this.assetName, opts)
+    this.closed = false
+    this.reconnectAttempt = 0
+    this.#clearReconnectTimer()
+    this.#openSocket({ isReconnect: false })
+  }
+
+  #openSocket({ isReconnect }) {
+    if (this.closed) return
+
+    const socket = new this.WebSocketClass(this.url)
+    this.socket = socket
+
+    const onOpen = () => {
+      if (this.socket !== socket || this.closed) return
+
+      this.connected = true
+      this.reconnectAttempt = 0
+      this.emit('connect')
+      if (isReconnect) this.emit('reconnect')
+      this.#subscribe(socket)
+      this.#startPing()
+    }
+
+    const onMessage = (event) => {
+      if (this.socket !== socket || this.closed) return
+      this.#handleMessage(event?.data)
+    }
+
+    const onError = (event) => {
+      // Some runtimes can stall without close; explicitly close to trigger reconnect flow.
+      if (this.socket !== socket || this.closed) return
+      console.warn('mempool-ws-client socket error', event)
+      try {
+        socket.close()
+      } catch {}
+    }
+
+    const onClose = () => {
+      if (this.socket !== socket) return
+      const wasConnected = this.connected
+      this.connected = false
+      this.#clearPing()
+      if (wasConnected) this.emit('disconnect')
+      this.socket = null
+      this.socketListeners = null
+      this.#scheduleReconnect()
+    }
+
+    socket.addEventListener('open', onOpen)
+    socket.addEventListener('message', onMessage)
+    socket.addEventListener('error', onError)
+    socket.addEventListener('close', onClose)
+    this.socketListeners = { onOpen, onMessage, onError, onClose }
+  }
+
+  #scheduleReconnect() {
+    if (this.closed || this.reconnectTimer) return
+
+    const reconnectDelay = getReconnectDelay(
+      this.reconnectAttempt,
+      this.options?.reconnectionDelay ?? DEFAULT_RECONNECTION_DELAY,
+      this.options?.reconnectionDelayMax ?? DEFAULT_RECONNECTION_DELAY_MAX
+    )
+    this.reconnectAttempt += 1
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null
+      this.#openSocket({ isReconnect: true })
+    }, reconnectDelay)
+  }
+
+  #clearReconnectTimer() {
+    if (!this.reconnectTimer) return
+    clearTimeout(this.reconnectTimer)
+    this.reconnectTimer = null
+  }
+
+  #startPing() {
+    this.#clearPing()
+    const intervalMs = this.options?.pingIntervalMs
+    if (!Number.isFinite(intervalMs) || intervalMs <= 0) return
+
+    this.pingInterval = setInterval(() => {
+      if (!this.socket || this.socket.readyState !== (this.WebSocketClass?.OPEN ?? 1)) return
+      this.#send(this.socket, { action: 'ping' })
+    }, intervalMs)
+  }
+
+  #clearPing() {
+    if (!this.pingInterval) return
+    clearInterval(this.pingInterval)
+    this.pingInterval = null
+  }
+
+  #send(socket, payload) {
+    if (!socket || socket.readyState !== (this.WebSocketClass?.OPEN ?? 1)) return
+
+    try {
+      socket.send(JSON.stringify(payload))
+    } catch (error) {
+      console.warn('mempool-ws-client send failed', {
+        payload,
+        error: error instanceof Error ? error.message : error,
+      })
+    }
+  }
+
+  #subscribe(socket) {
+    if (this.addresses.length > 0) {
+      this.#send(socket, { 'track-addresses': this.addresses })
+    }
+
+    if (this.options?.subscribeBlocks) {
+      this.#send(socket, { action: 'want', data: ['blocks'] })
+    }
+  }
+
+  #emitMessage(data, address) {
+    this.emit('message', {
+      address,
+      data,
+    })
+  }
+
+  #handleMessage(rawData) {
+    const payload = tryParseJSON(rawData)
+    if (!payload || typeof payload !== 'object') return
+
+    if (payload.block) {
+      this.emit('block', payload.block)
+    }
+
+    if (payload['multi-address-transactions']) {
+      const entries = flattenAddressEntries(payload['multi-address-transactions'])
+      entries.forEach(([address, addressPayload]) => {
+        this.#emitMessage(addressPayload, address)
+      })
+    }
+  }
+
+  close() {
+    this.closed = true
+    const wasConnected = this.connected
+    this.connected = false
+    this.#clearReconnectTimer()
+    this.#clearPing()
+
+    if (!this.socket) return
+    const socket = this.socket
+    this.socket = null
+    const listeners = this.socketListeners
+    this.socketListeners = null
+    if (listeners) {
+      socket.removeEventListener('open', listeners.onOpen)
+      socket.removeEventListener('message', listeners.onMessage)
+      socket.removeEventListener('close', listeners.onClose)
+      socket.removeEventListener('error', listeners.onError)
+    }
+
+    socket.close()
+    if (wasConnected) this.emit('disconnect')
+  }
+}