A custodial Bitcoin product has the same data problem every other UTXO custodian has. The product needs to detect inbound deposits and outbound withdrawals against thousands of customer addresses, attribute every event to the right customer account, and stay in sync with the chain without operating bitcoind and an indexer fleet.

This article walks through the deposit reconciliation architecture used by production Bitcoin custodians on Bitquery. It covers the Bitcoin inputs and outputs query shape, the tip of chain heartbeat that drives the walker, the address-corpus batching pattern, the script-type filter for P2PKH versus SegWit versus P2SH wallets, the address book reconciliation step, the Coinpath screening pass for source-of-funds compliance, the finality buffer for safe deposit confirmation, and the portability of the same skeleton to Litecoin and Dogecoin.

It is the Bitcoin companion to the Cardano deposits guide. Same three-component architecture, different chain, different UTXO model details.

The Three Component Architecture

Every production Bitcoin deposit detector reduces to three components. The first component is a tip of chain heartbeat. It fires on a fixed schedule and returns the current Bitcoin block height. This tells the rest of the pipeline how far the chain has advanced since the last sweep.

The second component is an address-corpus walker. It calls the Bitcoin inputs and outputs queries with height filters and a batch of customer addresses, then pages through the results. Each iteration extends the walked range by a fixed chunk size until the cursor catches up to tip.

The third component is a reconciler. It joins the walker’s output against the custodian’s internal address book, attributes each transaction to a customer account, applies the confirmation buffer, and writes a deposit or withdrawal event to the ledger. The three components run independently. The heartbeat decides when there is new work, the walker does the work, and the reconciler turns the work into business state. Failures in one do not cascade into the others.

Tip of Chain Heartbeat

The heartbeat is one query that returns the current block height. This is the cheapest query in the pipeline. Cache the response per second on your own side if the heartbeat fires more often than that. Bitcoin produces a block roughly every ten minutes, so a higher cadence buys nothing for freshness.

The heartbeat does two jobs. It tells the walker the upper bound of the next chunk to fetch. It also signals chain liveness, so a heartbeat that fails repeatedly is the earliest indicator that something upstream is wrong.

Address Corpus Walker

The walker is the workhorse query. It fetches every input and every output touching a batch of customer addresses inside a bounded block range. The inputAddress and outputAddress filters take a batch of customer addresses, so one call covers many users. Smaller batches mean more requests, while larger batches risk hitting timeouts on busy block ranges or on wallets with high activity.

The height filter bounds the work to a specific block range, which makes the call deterministic and idempotent. Re-running the same address and height range returns the same result every time. The reconciler can safely retry a chunk. The block height ordering guarantees the walker sees events in chain order. Deposits and the spends that consume them arrive in the same order they appear on chain, which simplifies the reconciler’s deduplication logic.

Script Type Filtering for P2PKH, SegWit, and P2SH

Bitcoin addresses come in three common formats, each tied to a different output script type. A custodian’s address book often holds all three because legacy addresses are still in circulation, some inbound flows originate from older exchanges, and modern wallets default to SegWit.

The outputScriptType filter restricts the walker to P2PKH outputs. For SegWit native addresses, use witness_v0_keyhash for P2WPKH or witness_v1_taproot for Taproot. Dropping the filter altogether returns matching outputs regardless of script type, which works when the address corpus is a strict whitelist. For mixed corpora, run separate walker queries per script type and merge the results in the reconciler.

For P2SH wallets, use scripthash. A custodian managing all three script types runs three walker queries per chunk, one per type, and writes the union to the reconciler. The total work is similar to running one unfiltered query, with the bonus that each script-type stream can be monitored separately.

Chunk Size, Steady State, and Catch Up

The block range chunk size is the main lever for throughput. Bitcoin’s block interval averages ten minutes, so a 100-block chunk covers roughly 17 hours of chain history and a 1,000-block chunk covers about a week. The right number depends on how active the address corpus is and how aggressive the timeout limits are.

Steady state runs at tip. The walker watches the heartbeat, and when a new block lands it fetches the chunk from the last walked height to tip. Most of the time this chunk is small and resolves in well under a second. Catch up mode runs when the walker is more than one chunk behind tip. This happens after deployment, after a service restart that lost the cursor, or after extended downtime.

Address Book Reconciliation

The walker returns chain level data. Each output carries the recipient address, the transaction hash, the output index, and the value. The chain has no concept of which customer owns that address. That mapping lives inside the custodian’s own systems. The reconciler is the component that joins the two: it takes each output the walker found and looks the recipient address up against the custodian’s internal address book to attribute the deposit to a customer.

The reconciler holds two tables. The first is the address book, mapping every customer to the deposit addresses generated for them. The second is the ledger, the custodian’s source of truth for deposits and withdrawals. For every output returned by the walker, the reconciler looks up the recipient address in the address book, attributes the value to a customer, and writes a deposit event to the ledger keyed on the transaction hash and output index pair. The address book lookup is the hot path; keep it in memory or in a low-latency key-value store.

Source of Funds Screening with Coinpath

A regulated custodian usually has a second job after attribution. Before the deposit clears to the customer’s available balance, the back office wants to know where the funds came from. Did the sender’s address belong to a sanctioned entity? Did the funds pass through a known mixer in the last few hops?

The Bitcoin Coinpath API answers where funds came from. The simplest screening query is an inbound trace at depth one. Pipe the sender address through the in-house sanctions list and known-mixer registry. A hit pauses the deposit credit and routes the case to the compliance queue. A miss lets the reconciler proceed to the confirmation buffer. For deeper provenance, add depth to trace the funds N hops back.

The Six Confirmation Buffer

Bitcoin transactions are not final the moment they appear in a block. A reorg can invalidate a recently mined block and roll back any deposit credited inside it. The standard mitigation is to delay deposit confirmation by a fixed number of blocks, conventionally six on Bitcoin. The walker can still fetch every block at tip and feed the reconciler. The reconciler holds events in a pending state until they clear the buffer, then promotes them to confirmed.

Bitquery vs Self Hosted bitcoind plus Indexer

The natural alternative is running bitcoind against an indexer such as Electrs, BTC RPC Explorer, or Esplora, then querying that indexer over RPC or HTTP. This is a legitimate choice for some teams, but it is the wrong choice for most custodians. Bitquery offers faster time to first deposit, no disk requirements, and built-in address batch filtering and script type decoding.

Multi UTXO Portability: The Same Loop on Litecoin and Dogecoin

The whole reconciliation pattern above ports to other UTXO chains without architectural changes. Swap the network argument for Litecoin or Dogecoin, swap the address format in the corpus, and the same heartbeat plus walker plus reconciler runs against the new chain. A custodian supporting BTC, LTC, DOGE, and BCH runs four instances of the loop, one per chain, against the same underlying Bitquery API.

Putting it Together

The full deposit detector loop is short. The custodian’s deposit and withdrawal feeds are now driven by Bitcoin chain state with no node fleet to operate. This is the same architecture used by production Bitcoin custodians on Bitquery. It pairs with the Cardano deposits guide and the Avalanche balance polling guide to give a complete custodial data layer across UTXO and EVM chains.

Summary

A custodial Bitcoin product detecting deposits and withdrawals at scale has three real choices. Build and operate a Bitcoin node fleet and a custom indexer. Stream from a managed RPC provider and reconstruct UTXO movements per call. Or run a tip heartbeat plus an address-corpus walker against Bitquery and let the reconciler handle attribution.

[Bitquery]