Bitcoin Streams

​

Overview

​

Key Features

• Real-time delivery: end-to-end latency is typically under 10 seconds after a block is mined
• Mempool notifications: unconfirmed transactions fire a webhook the moment they hit the mempool — react before the next block is mined
• Three-phase notifications: matches can fire up to three times — first when the transaction is broadcast to the mempool (block.hash: "mempool"), again when it lands in a block (confirmed: false, near the chain tip), and finally after the 2-block confirmation depth (confirmed: true, reorg-safe)
• All address formats supported: P2PKH (legacy, 1...), P2SH (SegWit-wrapped, 3...), and Bech32 native SegWit (bc1q...)
• Xpub support: attach an extended public key to a stream and Moralis derives and monitors its addresses automatically — ideal for HD wallets
• Flexible monitoring: watch specific addresses, attach an xpub, or enable firehose mode with allAddresses to receive every Bitcoin transaction
• Automatic retries: Moralis retries webhook delivery until it receives an HTTP 200 response

​

How It Works

1. A transaction is broadcast to the Bitcoin mempool. Moralis evaluates every mempool transaction against your registered addresses and xpubs
2. Matching mempool transactions fire a webhook with confirmed: false and the sentinel values block.height: "0" / block.hash: "mempool" — delivered once per stream
3. A new Bitcoin block is produced and Moralis evaluates every transaction in it against your registered addresses
4. Matching block transactions fire a webhook with confirmed: false and the real block height / hash — the block is close to the chain tip and could still be reorged
5. After 2 additional blocks have been mined on top, Moralis re-fetches the block and delivers a third webhook with confirmed: true — the transaction is now reorg-safe
6. Your service upserts on txid to reconcile the lifecycle, branching on block.hash === "mempool" for the mempool stage

​

Webhook Payload Structure

• Block metadata — hash, height, timestamp, difficulty, merkle root, transaction count
• Transaction details — txid, input/output counts, locktime, version, block reference
• Outputs (vout) — value in BTC (not satoshis), script type, recipient address
• Inputs (vin) — structural fields only; address and value fields remain null
• Confirmation status — confirmed: false for the near-tip delivery, confirmed: true once the block has cleared the 2-block confirmation depth

const satoshis = Math.round(btc * 1e8);

​

Mempool Notifications

​

Example payload

{
  "streamId": "cefa6529-e3ec-4ee8-8cbd-206d2e7ce64e",
  "chainId": "btc-mainnet",
  "confirmed": false,
  "block": {
    "height": "0",
    "hash": "mempool"
  },
  "retries": 0,
  "transactions": [ ]
}

​

Detecting mempool in your handler

const isMempool = payload.block.hash === "mempool";

​

Behavior

• Delivered at most once per stream per matching mempool transaction
• No follow-up webhook on confirmation from the mempool delivery itself — the regular confirmed-block stream handles confirmed: false (in-block) and confirmed: true (reorg-safe) for the same txid
• Mempool transactions are not guaranteed to confirm. They can be evicted, replaced (RBF), or expire on low fee. Treat them as pending, not settled
• Matching covers both sends and receives. In mempool payloads, vin and vout addresses are both populated, so a watched address triggers a match whether it is sending or receiving
• Xpub-derived addresses are fully supported — addresses derived from an attached xpub match against the mempool the same way they do against confirmed blocks

​

Getting started

​

Configuration Parameters

​

API Endpoints

​

Streams

​

Addresses

​

Xpub

​

Limitations

• Input data is not populated. Even with includeInputs: true, input address and value fields return null. You can reliably detect inbound transfers to watched addresses, not outflows.
• isCoinbase is always false. The isCoinbase field does not reliably identify coinbase transactions. Detect coinbase transactions using a heuristic: the transaction contains an OP_RETURN output and has exactly one input.
• Values are BTC decimals. Output values are not denominated in satoshis. Convert with Math.round(btc * 1e8) before feeding integer-based ledger systems.
• Mainnet only. The network parameter must be ["mainnet"].

​

Processing Patterns

​

Branching on mempool vs. confirmed block

if (payload.block.hash === "mempool") {
  // pending: tx broadcast but not yet mined
} else if (payload.confirmed === false) {
  // included in a block near the chain tip — could still reorg
} else {
  // reorg-safe — safe to persist
}

​

Deduplication

​

Coinbase detection

const isCoinbase =
  tx.vin.length === 1 &&
  tx.vout.some((out) => out.scriptPubKey?.type === "nulldata"); // OP_RETURN

​

Value conversion

const btc = vout.value;
const satoshis = Math.round(btc * 1e8);

​

Common Use Cases

• Exchange deposits — surface deposits the moment they hit the mempool (block.hash === "mempool"), mark them pending on block inclusion (confirmed: false), and confirmed on the reorg-safe delivery (confirmed: true)
• Pending balances — show users a pending balance the instant a tx is broadcast, before any block has been mined
• Payment UX — trigger downstream flows on payment broadcast instead of waiting for confirmation
• Mempool analytics — RBF detection, fee analytics, and MEV / arbitrage signals against unconfirmed activity
• Cold wallet surveillance — alert on any inbound transfer to an offline storage address
• Mining pool revenue — watch payout addresses for both standard payments and coinbase block rewards
• Treasury monitoring — real-time accounting for corporate or DAO-held BTC addresses

​

Setup Checklist

1. Generate an API key from admin.moralis.com
2. Deploy a publicly accessible HTTPS webhook endpoint
3. Create the stream via PUT /streams/bitcoin
4. Attach the wallets you want to monitor — either by registering individual addresses (POST /streams/bitcoin/{id}/address) or by adding an xpub (POST /streams/bitcoin/{id}/xpub) to auto-derive and watch its addresses
5. Implement the verification handler — respond to the empty-body test POST with HTTP 200
6. Build upsert logic keyed on txid to handle the confirmed: false → confirmed: true transition
7. Always return HTTP 200 from your handler, even when your own processing errors — Moralis retries on non-200 responses