Watcher

The Watcher provides real-time mempool intelligence: fee estimates, mempool state snapshots, anomaly detection, and human-readable summaries.

Quick Start


import asyncio
from bitpilot import Watcher

watcher = Watcher.from_default_providers(network="mainnet")

fee = asyncio.run(watcher.estimate_fee(target_blocks=3))
print(fee.human_readable())

state = asyncio.run(watcher.get_mempool_state())
print(state.human_summary())

Factory Methods

Method	Backend
`Watcher.from_default_providers(network)`	mempool.space public API
`Watcher.from_node_rpc(url, network)`	Bitcoin Core JSON-RPC
`Watcher.from_mock(network)`	Offline mock data for testing

Key Methods

estimate_fee(target_blocks) — fee estimate for a confirmation target
get_all_fee_estimates() — fast/medium/slow estimates in one call
get_mempool_state() — snapshot of mempool size, tx count, congestion level
explain_mempool() — human-readable (LLM-friendly) mempool summary
watch_transaction(txid) — track a broadcast transaction's confirmation status

Anomaly Detection

The watcher runs an AnomalyDetector on every mempool refresh, flagging:

Sudden fee spikes (> 2 sigma from 24h mean)
Mempool size jumps
Unusually large UTXOs entering the pool

Providers

Providers implement the MempoolProvider protocol:

MempoolSpaceProvider — REST client for mempool.space
NodeRPCProvider — JSON-RPC client for Bitcoin Core
MockProvider — deterministic offline data

Exceptions

WatcherError — raised when the watcher cannot complete a request (provider timeout, parse failure, etc.)