Documentation Index
Fetch the complete documentation index at: https://docs.moralis.com/llms.txt
Use this file to discover all available pages before exploring further.
Overview
Bitcoin Streams extends Moralis Streams to the Bitcoin network, delivering real-time transaction data via webhooks. Moralis indexes Bitcoin automatically and pushes structured payloads to your endpoint whenever transactions match your criteria.
Webhooks typically arrive within seconds of a block being mined — no node, no polling, no missed blocks.
Key Features
- Real-time delivery: end-to-end latency is typically under 10 seconds after a block is mined
- Dual-phase notifications: every match fires twice — first when the transaction is included in a block (
confirmed: false, the block is near the chain tip and could still be reorged), then again 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
- A new Bitcoin block is produced
- Moralis evaluates every transaction in the block against your registered addresses
- Matching transactions fire a webhook with
confirmed: false — the block is close to the chain tip and could still be reorged
- After 2 additional blocks have been mined on top, Moralis re-fetches the block and delivers a second webhook with
confirmed: true — the transaction is now reorg-safe
- Your service upserts on
txid to reconcile the two-phase lifecycle
Webhook Payload Structure
Each Bitcoin webhook payload contains:
- 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
Output values are represented as BTC decimals (e.g. 3.13258866). To convert to satoshis, multiply by 1e8:const satoshis = Math.round(btc * 1e8);
Configuration Parameters
When creating a Bitcoin stream you specify:
| Parameter | Description |
|---|
webhookUrl | Public HTTPS endpoint that will receive payloads (required) |
network | Must be ["mainnet"] as an array |
includeInputs | Include input structure in the payload |
includeOutputs | Include output structure in the payload |
allAddresses | Firehose mode — deliver every Bitcoin transaction |
description | Human-readable stream description |
tag | Identifier for routing / filtering on your side |
API Endpoints
All Bitcoin Streams endpoints require the x-api-key header.
Streams
| Method | Endpoint | Purpose |
|---|
PUT | /streams/bitcoin | Create a stream with a webhook URL and configuration |
POST | /streams/bitcoin/{id} | Update a stream’s configuration |
POST | /streams/bitcoin/{id}/status | Pause or resume a stream |
GET | /streams/bitcoin | List existing Bitcoin streams |
GET | /streams/bitcoin/{id} | Get a stream by ID |
DELETE | /streams/bitcoin/{id} | Remove a stream |
POST | /streams/bitcoin/{chainId}/block/{blockNumber} | Get webhook data for a historical block |
POST | /streams/bitcoin/{chainId}/block-to-webhook/{blockNumber}/{streamId} | Replay a historical block for backfilling |
Addresses
| Method | Endpoint | Purpose |
|---|
GET | /streams/bitcoin/{id}/address | List addresses attached to a stream |
POST | /streams/bitcoin/{id}/address | Add an address to monitor (one per request) |
DELETE | /streams/bitcoin/{id}/address | Remove an address from a stream |
Xpub
| Method | Endpoint | Purpose |
|---|
GET | /streams/bitcoin/{id}/xpub | List xpubs attached to a stream |
POST | /streams/bitcoin/{id}/xpub | Add an xpub to derive and monitor addresses from |
DELETE | /streams/bitcoin/{id}/xpub/{xpubId} | Remove an xpub from a stream |
Limitations
Bitcoin Streams has a few behaviors that differ from EVM Streams — plan your consumer around them.
- 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
Deduplication
Each matched transaction is delivered twice — first at block inclusion (confirmed: false, near-tip), then again after the 2-block confirmation depth (confirmed: true, reorg-safe). Use the transaction id (txid) as your natural deduplication key and upsert on the second delivery to flip the confirmation flag.
Coinbase detection
Since isCoinbase is unreliable, detect coinbase transactions like this:
const isCoinbase =
tx.vin.length === 1 &&
tx.vout.some((out) => out.scriptPubKey?.type === "nulldata"); // OP_RETURN
Value conversion
Store both BTC and satoshi values so downstream services can pick whichever representation fits:
const btc = vout.value;
const satoshis = Math.round(btc * 1e8);
Common Use Cases
- Exchange deposits — monitor hot wallet addresses, mark deposits as
pending on the first delivery (confirmed: false) and confirmed on the reorg-safe delivery (confirmed: true)
- 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
- Generate an API key from admin.moralis.com
- Deploy a publicly accessible HTTPS webhook endpoint
- Create the stream via
PUT /streams/bitcoin
- 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
- Implement the verification handler — respond to the empty-body test
POST with HTTP 200
- Build upsert logic keyed on
txid to handle the confirmed: false → confirmed: true transition
- Always return HTTP
200 from your handler, even when your own processing errors — Moralis retries on non-200 responses
