Mempool

Skill is based on mempool (mempool.space) backend and frontend API surface, generated at 2026-02-24.

Mempool is the open-source mempool visualizer, block explorer, and API service behind mempool.space. It provides REST and WebSocket APIs for fees, blocks, transactions, addresses (with Electrum/Esplora), mining pools and hashrate, optional Lightning explorer, and Liquid assets. Use this skill when building agents or tools that query or stream Bitcoin/Liquid chain and mempool data.

Core References

Features

Fees and Mempool

Blocks and Transactions

Addresses

Liquid and Lightning

Services

Best Practices

Generation Info

• Source: sources/mempool
• Git SHA: 7d1ca3660cac08aab62e76f3aa4daec0d7403ecc
• Generated: 2026-02-24

Mempool Backend Configuration

The backend reads mempool-config.json (or path from MEMPOOL_CONFIG_FILE). For Docker, all keys can be overridden via environment variables in docker-compose.yml (see docker/README.md).

Key sections (agent-relevant)

• MEMPOOL — NETWORK (mainnet, testnet, signet, testnet4, regtest), BACKEND (electrum, esplora, none), API_URL_PREFIX (default /api/v1/), HTTP_PORT, POLL_RATE_MS, INDEXING_BLOCKS_AMOUNT, BLOCKS_SUMMARIES_INDEXING, CPFP_INDEXING, AUTOMATIC_POOLS_UPDATE, MAX_TRACKED_ADDRESSES, UNIX_SOCKET_PATH.
• CORE_RPC — Bitcoin Core RPC (HOST, PORT, USERNAME, PASSWORD, TIMEOUT). Required for block/mempool data; with BACKEND: "none" address lookups are disabled.
• ELECTRUM / ESPLORA — Electrum or Esplora backend for address/script hash lookups. Electrum: HOST, PORT, TLS_ENABLED. Esplora: REST_API_URL or UNIX_SOCKET_PATH.
• DATABASE — MariaDB/MySQL for indexing (ENABLED, HOST, PORT, DATABASE, USERNAME, PASSWORD). Required for mining dashboard, statistics, Lightning explorer.
• STATISTICS — ENABLED, TX_PER_SECOND_SAMPLE_PERIOD. Requires DATABASE.
• LIGHTNING — ENABLED, BACKEND (lnd, clightning). LND: TLS_CERT_PATH, MACAROON_PATH, REST_API_URL. CLIGHTNING: SOCKET.
• MEMPOOL_SERVICES.ACCELERATIONS — When true, acceleration routes are registered.

Environment overrides (Docker)

Map config keys to env vars: section key in UPPER_SNAKE_CASE, e.g. MEMPOOL_NETWORK, MEMPOOL_BACKEND, CORE_RPC_HOST, CORE_RPC_PORT, ELECTRUM_HOST, ELECTRUM_PORT, DATABASE_ENABLED, LIGHTNING_ENABLED, etc. See docker/README.md for the full list.

Backend behavior

• With BACKEND: "none": no address/scripthash APIs; blocks and mempool from Bitcoin Core only.
• With BACKEND: "electrum" or "esplora": address and scripthash endpoints are available (delegated to Electrum or Esplora).
• Reindex: npm run start -- --reindex=blocks,hashrates truncates specified tables at startup (with delay). Used for mining/Lightning re-indexing.
• Pools update: npm run start -- --update-pools updates mining pool definitions at startup.

<!-- Source references:

• sources/mempool/backend/mempool-config.sample.json
• sources/mempool/docker/README.md
• sources/mempool/backend/README.md

-->

Mempool REST API Overview

Mempool exposes a REST API used by mempool.space and self-hosted instances. All endpoints use the prefix `/api/v1/`. Base URL is the instance root (e.g. https://mempool.space or http://localhost:8999).

Base URL and prefix

• Prefix: API_URL_PREFIX from config, default /api/v1/
• Example: GET https://mempool.space/api/v1/fees/recommended

When building requests, agents should use the instance base URL + /api/v1/ + path. For public mempool.space, use https://mempool.space; for testnet/signet/liquid use the same host with the appropriate subdomain or path (e.g. testnet.mempool.space, liquid.network).

Main endpoint groups

Backend routes are registered in backend/src/index.ts via setUpHttpApiRoutes(); Bitcoin core routes live in backend/src/api/bitcoin/bitcoin.routes.ts. Some routes (e.g. mempool, tx/:txId, address/:address) are only available when MEMPOOL.BACKEND !== 'esplora' (Electrum or none); with Esplora backend, those are served by the Esplora REST API.

Practical usage

# Recommended fees (sat/vB)
curl -s "https://mempool.space/api/v1/fees/recommended"

# Block tip height
curl -s "https://mempool.space/api/v1/blocks/tip/height"

# Init data (same as WebSocket initial payload)
curl -s "https://mempool.space/api/v1/init-data"

Use init-data when you need a one-off snapshot of mempool blocks, fees, difficulty adjustment, and backend info without opening a WebSocket.

<!-- Source references:

• sources/mempool/backend/src/index.ts (setUpHttpApiRoutes)
• sources/mempool/backend/src/api/bitcoin/bitcoin.routes.ts
• sources/mempool/frontend/src/app/docs/api-docs/api-docs-data.ts

-->

Mempool WebSocket API

Clients connect to the same host/port as the HTTP API (e.g. wss://mempool.space/ws or ws://localhost:8999). After connection, send a want message to subscribe to live data.

Valid subscriptions (want)

From websocket-handler.ts, the valid want values are:

• `blocks` — new blocks
• `mempool-blocks` — projected mempool blocks (fee tiers)
• `live-2h-chart` — 2h fee/size chart data
• `stats` — tx/sec and similar statistics
• `tomahawk` — Tomahawk-specific data

Subscription format

Send a JSON message:

{ "action": "want", "data": ["blocks", "mempool-blocks", "stats"] }

You can also track addresses, transactions, or mempool txids by sending:

• Track address: { "action": "track-address", "data": "<address>" }
• Track tx: { "action": "track-tx", "data": "<txid>" }
• Track mempool: { "action": "track-mempool", "data": true } (or track specific txids)

Server pushes updates as JSON; initial state for blocks, mempool-blocks, fees, and difficulty can also be obtained via GET /api/v1/init-data without opening a WebSocket.

Initial data

On connect, the server does not send a full init blob over the wire by default; the client can request the same payload via REST:

curl -s "https://mempool.space/api/v1/init-data"

That response includes mempool-blocks, fees, da (difficulty adjustment), backend, mempoolInfo, vBytesPerSecond, blocks, conversions, etc., which matches what the WebSocket layer uses for its internal serializedInitData.

When to use WebSocket vs REST

• REST: One-off queries (fees, block by hash, tx, address), scripting, init-data snapshot.
• WebSocket: Live blocks, live mempool blocks, live stats, or tracking specific addresses/txs for real-time updates.

<!-- Source references:

• sources/mempool/backend/src/api/websocket-handler.ts (wantable, connection handling)
• sources/mempool/frontend/src/app/docs/api-docs/api-docs-data.ts (wsApiDocsData)

-->

Acceleration (MEMPOOL_SERVICES.ACCELERATIONS)

When the backend is configured with MEMPOOL_SERVICES.ACCELERATIONS (and optional MEMPOOL_SERVICES.API for proxy), acceleration routes are registered:

• GET /api/v1/services/accelerator/accelerations — List active accelerations (from local mempool state).
• GET /api/v1/services/accelerator/accelerations/:txid — Acceleration info for a txid (from DB/repository).
• GET /api/v1/services/accelerator/accelerations/history — History (optional blockHeight query).
• GET /api/v1/services/accelerator/accelerations/history/aggregated — Proxied to MEMPOOL_SERVICES.API.
• GET /api/v1/services/accelerator/accelerations/stats — Proxied to MEMPOOL_SERVICES.API.
• POST /api/v1/services/accelerator/estimate — Get acceleration cost estimate (body as per service).

Use these to query or request transaction acceleration (e.g. paid boost into the next block).

Mining routes acceleration endpoints

The mining module also exposes acceleration endpoints under /api/v1/ when indexing is on:

• GET /api/v1/accelerations/pool/:slug, /accelerations/block/:height, /accelerations/recent/:interval, /accelerations/total, /accelerations
• POST /api/v1/acceleration/request/:txid

These are in mining-routes.ts and may overlap or complement the services/accelerator routes depending on deployment.

Wallet and Stratum (optional)

• WALLETS.ENABLED — Registers services routes, e.g. GET /api/v1/wallet/:walletId for wallet info. Used for supported wallet integrations.
• STRATUM.ENABLED — Backend connects to stratum WebSocket and can expose stratum-related state; no separate REST route list was required for basic agent usage.

<!-- Source references:

• sources/mempool/backend/src/api/acceleration/acceleration.routes.ts
• sources/mempool/backend/src/api/services/services-routes.ts
• sources/mempool/backend/src/api/mining/mining-routes.ts (acceleration endpoints)
• sources/mempool/backend/src/index.ts

-->

Addresses and Scripthash

Address and scripthash endpoints require an Electrum or Esplora backend (MEMPOOL.BACKEND not "none"). With BACKEND: "none", these are unavailable.

Address

• GET /api/v1/address/:address

Address summary: chain_stats and mempool_stats (tx_count, funded_txo_count/sum, spent_txo_count/sum).

• GET /api/v1/address/:address/txs

Transaction list (newest first). Returns up to 50 mempool + first 25 confirmed; use after_txid query to paginate confirmed.

• GET /api/v1/address/:address/txs/summary

Transaction list in summary form (e.g. txid, status, fee).

• GET /api/v1/address/:address/utxo

Unspent outputs (UTXOs) for the address.

• GET /api/v1/validate-address/:address

Address validation (format/checksum).

• GET /api/v1/address-prefix/:prefix

Lookup by address prefix (if supported by backend).

Scripthash

• GET /api/v1/scripthash/:scripthash

Same shape as address: chain_stats, mempool_stats.

• GET /api/v1/scripthash/:scripthash/txs

Transaction list for scripthash.

• GET /api/v1/scripthash/:scripthash/txs/summary

Summary list.

• GET /api/v1/scripthash/:scripthash/utxo

UTXOs for the scripthash.

Scripthash is the hex-encoded script hash (as used in Electrum protocol).

Pagination and limits

• Address txs: default 25 confirmed + 50 mempool; use after_txid=<txid> for next page of confirmed.
• Server may enforce MAX_TRACKED_ADDRESSES for WebSocket tracking; REST has no per-address limit documented beyond normal rate limits.

Example

# Address stats
curl -s "https://mempool.space/api/v1/address/1wiz18xYmhRX6xStj2b9t1rwWX4GKUgpv"

# Address txs (paginate with after_txid)
curl -s "https://mempool.space/api/v1/address/1wiz18xYmhRX6xStj2b9t1rwWX4GKUgpv/txs?after_txid=<txid>"

# UTXOs
curl -s "https://mempool.space/api/v1/address/1wiz18xYmhRX6xStj2b9t1rwWX4GKUgpv/utxo"

<!-- Source references:

• sources/mempool/backend/src/api/bitcoin/bitcoin.routes.ts (getAddress, getAddressTransactions, getAddressUtxo, getScriptHash, etc.)
• sources/mempool/frontend/src/app/docs/api-docs/api-docs-data.ts (get-address, get-address-transactions, get-address-utxo)

-->

Blocks and Transactions

Blocks

• GET /api/v1/blocks — List of recent blocks (optional ?height= N for single height).
• GET /api/v1/blocks/:height — Blocks at given height (can return multiple for reorgs).
• GET /api/v1/block/:hash — Block by hash (full block object).
• GET /api/v1/block/:hash/summary — Block with stripped/summary tx list.
• GET /api/v1/block/:hash/txids — Transaction IDs in block.
• GET /api/v1/block/:hash/txs — Full transactions in block (optional /:index for single tx).
• GET /api/v1/block/:hash/header — Raw block header (hex).
• GET /api/v1/block/:hash/raw — Raw block (hex).
• GET /api/v1/block-height/:height — Block hash for height.
• GET /api/v1/blocks/tip/height — Current tip height.
• GET /api/v1/blocks/tip/hash — Current tip hash.
• GET /api/v1/blocks-bulk/:from and /api/v1/blocks-bulk/:from/:to — Bulk block hashes.
• GET /api/v1/block/:hash/audit-summary — Block audit summary (when audit enabled).
• GET /api/v1/chain-tips, /api/v1/stale-tips — Chain tips and stale tips.

All hashes and heights are as in the backend; use the appropriate network base URL (mainnet/testnet/signet/liquid).

Transactions (non-Esplora backend)

When MEMPOOL.BACKEND !== 'esplora':

• GET /api/v1/tx/:txId — Transaction by txid.
• GET /api/v1/tx/:txId/hex — Raw tx hex.
• GET /api/v1/tx/:txId/status — Confirmation status (confirmed height, block hash, etc.).
• GET /api/v1/tx/:txId/outspends — Outspend status for each output.
• GET /api/v1/tx/:txId/merkle-proof — Merkle proof (for SPV).
• GET /api/v1/tx/:txId/rbf — RBF history for this tx.
• GET /api/v1/tx/:txId/cached — Cached version if available.
• POST /api/v1/tx — Broadcast raw tx (body: raw hex).
• POST /api/v1/tx/push — Broadcast (form or body); backend accepts hex.
• POST /api/v1/txs/package — Submit package (multiple txs).
• POST /api/v1/psbt/addparents — Add parent tx to PSBT for RBF/CPFP.
• POST /api/v1/prevouts — Get prevout info for a set of outpoints (body as per backend).
• GET /api/v1/txs/outspends — Batched outspends (POST body with txids).
• GET /api/v1/replacements, /api/v1/fullrbf/replacements — RBF replacement sets.

With Esplora backend, use the Esplora REST API for these; the Mempool backend proxies or delegates.

Practical examples

# Tip height
curl -s "https://mempool.space/api/v1/blocks/tip/height"

# Block by hash
curl -s "https://mempool.space/api/v1/block/0000000000000000000123456789abcdef.../txids"

# Transaction status
curl -s "https://mempool.space/api/v1/tx/<txid>/status"

# Broadcast (POST body = raw hex)
curl -s -X POST "https://mempool.space/api/v1/tx" -H "Content-Type: text/plain" -d "<hex>"

<!-- Source references:

• sources/mempool/backend/src/api/bitcoin/bitcoin.routes.ts
• sources/mempool/frontend/src/app/docs/api-docs/api-docs-data.ts (restApiDocsData)

-->

Fees and Mempool State

Recommended fees

• GET /api/v1/fees/recommended

Returns estimated fee tiers (e.g. fastestFee, halfHourFee, hourFee, economyFee, minimumFee) in sat/vB. Returns 503 when backend is not in sync.

• GET /api/v1/fees/precise

Same idea with more precise values (floats). Use when building transactions that need exact fee estimates.

curl -s "https://mempool.space/api/v1/fees/recommended"
# {"fastestFee":12,"halfHourFee":10,"hourFee":8,"economyFee":6,"minimumFee":2}

Mempool blocks (projected)

• GET /api/v1/fees/mempool-blocks

Returns the current set of projected mempool blocks (next blocks by fee rate). Each block has blockSize, blockVSize, nTx, totalFees, medianFee, feeRange. Used to show “next block” vs “in 3 blocks” fee estimates.

Transaction times (batch)

• GET /api/v1/transaction-times?txId=txid1&txId=txid2

Query parameter txId can be repeated. Returns estimated confirmation times for given txids (based on fee rate and mempool). Useful for “when will my tx confirm?” without polling tx status.

Mempool contents (Electrum/non-Esplora only)

When MEMPOOL.BACKEND !== 'esplora':

• GET /api/v1/mempool — Mempool summary (e.g. tx count, size, min fee).
• GET /api/v1/mempool/txids — List of txids in mempool.
• GET /api/v1/mempool/recent — Recent mempool transactions.

With Esplora backend, mempool data is served by the Esplora API; use the same paths against the Esplora base URL if needed.

CPFP

• GET /api/v1/cpfp/:txId — CPFP (child-pays-for-parent) info for a given txid.
• POST /api/v1/cpfp — Get CPFP info for a set of transactions (body: array of txids or similar as per backend).

Use these when building or analyzing replacement or CPFP strategies.

<!-- Source references:

• sources/mempool/backend/src/api/bitcoin/bitcoin.routes.ts (getRecommendedFees, getMempoolBlocks, getTransactionTimes, getMempool, getCpfp)
• sources/mempool/backend/src/api/fee-api.ts
• sources/mempool/backend/src/api/mempool-blocks.ts

-->

Lightning Explorer (optional)

When LIGHTNING.ENABLED is true, Lightning routes are registered under /api/v1/:

• GET /api/v1/lightning/search — Search nodes and channels (query params as per backend).
• GET /api/v1/lightning/nodes/world — Nodes with geo (if MaxMind enabled).
• GET /api/v1/lightning/channels/txids — Channels by funding txids (POST body or query).

Backend can be lnd or clightning; config under LND.* or CLIGHTNING.*. Lightning data is synced into the database and served from there.

Mining and hashrate (indexing + DB)

When DATABASE.ENABLED and indexing (e.g. INDEXING_BLOCKS_AMOUNT) and MEMPOOL.ENABLED are on, mining routes are available:

• GET /api/v1/mining/pools — List of known mining pools.
• GET /api/v1/mining/pools/:interval — Pools with hashrate/share over interval.
• GET /api/v1/mining/pool/:slug — Pool details.
• GET /api/v1/mining/pool/:slug/hashrate — Pool hashrate over time.
• GET /api/v1/mining/pool/:slug/blocks — Blocks mined by pool (optional /:height).
• GET /api/v1/mining/hashrate/pools/:interval — Pools hashrate time series.
• GET /api/v1/mining/hashrate/:interval — Network hashrate over interval.
• GET /api/v1/mining/difficulty-adjustments and /mining/difficulty-adjustments/:interval — Difficulty adjustments.
• GET /api/v1/mining/reward-stats/:blockCount — Reward stats.
• GET /api/v1/mining/blocks/fees, /mining/blocks/fees/:interval — Block fees.
• GET /api/v1/mining/blocks/rewards/:interval, /mining/blocks/fee-rates/:interval, /mining/blocks/sizes-weights/:interval — Block rewards, fee rates, sizes.
• GET /api/v1/mining/blocks/predictions/:interval — Block health predictions.
• GET /api/v1/mining/blocks/audit/scores, /audit/scores/:height, /audit/score/:hash, /audit/:hash — Audit scores and block audit.
• GET /api/v1/mining/blocks/timestamp/:timestamp — Block height from timestamp.
• GET /api/v1/accelerations/pool/:slug, /accelerations/block/:height, /accelerations/recent/:interval, /accelerations/total, /accelerations — Acceleration by pool/block/recent/total/active.
• POST /api/v1/acceleration/request/:txid — Request acceleration for a tx.

Intervals are typically like 24h, 3d, 1w, 1m, 3m, 6m, 1y, 2y, 3y (see frontend api-docs-data).

Statistics (DB)

When STATISTICS.ENABLED and DATABASE.ENABLED and MEMPOOL.ENABLED:

• GET /api/v1/statistics/2h (and other time ranges) — Tx/sec and other stats over the period.

<!-- Source references:

• sources/mempool/backend/src/api/explorer/general.routes.ts, nodes.routes.ts, channels.routes.ts
• sources/mempool/backend/src/api/mining/mining-routes.ts
• sources/mempool/backend/src/api/statistics/statistics.routes.ts
• sources/mempool/backend/src/index.ts (setUpHttpApiRoutes)

-->

Liquid (Elements) Support

When the backend runs in Liquid mode (Common.isLiquid() i.e. network is liquid or liquidtestnet), Liquid-specific routes are registered. The same API prefix /api/v1/ is used; base URL is typically a Liquid instance (e.g. liquid.network).

Assets

• GET /api/v1/assets/icons — All asset icons (list or map).
• GET /api/v1/asset/:assetId — Asset metadata (id, name, ticker, etc.).
• GET /api/v1/asset/:assetId/transactions — Transactions involving the asset.
• GET /api/v1/asset/:assetId/supply — Supply info.
• GET /api/v1/asset/:assetId/icon — Single asset icon.

Asset IDs are Liquid asset identifiers (hex or registered id). Address format and UTXO semantics are Liquid-specific (confidential outputs, etc.); address and scripthash endpoints follow the same path pattern as Bitcoin but return Liquid-shaped data.

Backend behavior

• Icons are loaded from config (e.g. EXTERNAL_ASSETS) and refreshed periodically; see api/liquid/icons.ts.
• Elements/Liquid block and tx parsing is handled by elementsParser; new blocks trigger federation UTXO updates when DATABASE is enabled.
• Use the same REST and WebSocket patterns as Bitcoin; only the network and response shapes (e.g. asset fields, confidential amounts) differ.

Example

# Asset list/icons (Liquid instance)
curl -s "https://liquid.network/api/v1/assets/icons"

# Single asset
curl -s "https://liquid.network/api/v1/asset/<asset_id>"

<!-- Source references:

• sources/mempool/backend/src/api/liquid/liquid.routes.ts
• sources/mempool/backend/src/index.ts (isLiquid, liquid routes, icons)
• sources/mempool/backend/src/api/liquid/icons.ts

-->