moralis-streams-api

CRITICAL: Read Rule Files Before Implementing

The #1 cause of Streams bugs is mixing up stream families or request shapes.

For EVERY endpoint:

Read rules/{EndpointName}.md
Confirm the family first:
- EVM: /streams/evm
- Solana: /streams/solana
- Bitcoin: /streams/bitcoin
- Utilities: /history, /historical-jobs, /settings, /stats
Check the HTTP method carefully (PUT create, POST update/status/replay, DELETE delete)
Verify stream IDs are UUIDs, not hashes or addresses
Use the correct config shape for that family:
- EVM: chainIds, topic0, abi, advancedOptions
- Solana: network, programIds, mintAddresses, allAddresses
- Bitcoin: network, includeInputs, includeOutputs, allAddresses, xpub

Reading order:

This SKILL.md
The endpoint rule in rules/
references/StreamConfiguration.md
Family-specific references for edge cases

Setup

API Key

Never ask the user to paste their API key into the chat. Instead:

Check whether MORALIS_API_KEY is set:

[ -n "$MORALIS_API_KEY" ] && echo "API key is set" || echo "API key is NOT set"

If missing, offer to create a local .env with MORALIS_API_KEY=
Tell the user to open .env and add the key themselves
Explain that without the key, you cannot call or test Moralis Streams

If they need a key, point them to admin.moralis.com/register. The Free plan was removed on September 1, 2026; a paid plan is required. For Starter, Pro, and Business monthly prices, see plan pricing and verify the live pricing page. Free unconfirmed webhooks do not imply a Free subscription plan.

Verify Your Key

curl "https://api.moralis-streams.com/streams/evm?limit=10" \
  -H "X-API-Key: $MORALIS_API_KEY"

Base URL

https://api.moralis-streams.com

All requests require X-API-Key: $MORALIS_API_KEY.

Stream Families

Family	Core filters	Extras	Notes
EVM	`chainIds`, `topic0`, `abi`, stream addresses	`advancedOptions`, `includeContractLogs`, `includeNativeTxs`, `includeInternalTxs`, `triggers`, `getNativeBalances`	Use hex chain IDs like `0x1`, `0x89`
Solana	`network`, `programIds`, `mintAddresses`, stream addresses	`allAddresses`, block replay helpers	No `chainIds`, no `topic0`, no EVM ABI decoding
Bitcoin	`network`, stream addresses, `allAddresses`	`includeInputs`, `includeOutputs`, xpub endpoints, block replay helpers	Address and xpub monitoring instead of contract topics
Utilities	history, replay, historical jobs, settings, stats	account-level operations	Historical-job timestamp units and family scope require confirmation

EVM

Use EVM streams for contract events, ERC20 / ERC721 / ERC1155 transfers, approvals, native transactions, and internal transactions on supported EVM mainnet chains.

Stream types:

Type	Description
`tx`	Native transactions
`log`	Contract event logs
`erc20transfer`	ERC20 token transfers
`erc20approval`	ERC20 approvals
`nfttransfer`	NFT transfers
`internalTx`	Internal transactions

Solana

Use Solana streams when the user wants program, mint, or address activity on mainnet.

Primary filters are programIds and mintAddresses
network must be ["mainnet"]
There is no EVM-style topic0, abi, or chainIds
Solana addresses are base58 and case-sensitive; never lowercase them
Solana payloads use transactions[].signature, accountKeys, instructions, innerInstructions, and pre/post token balances instead of EVM event arrays

See references/SolanaStreams.md.

Bitcoin

Use Bitcoin streams for address-based or xpub-based monitoring.

Primary filters are watched addresses or xpubs
network is an array
includeInputs and includeOutputs control payload detail
network must be ["mainnet"]

Use ["mainnet"].

See references/BitcoinStreams.md.

Quick Reference

Stream ID Format

// WRONG
"0x1234567890abcdef"

// CORRECT
"YOUR_STREAM_ID"

EVM Chain IDs

"0x1"     // Ethereum
"0x89"    // Polygon
"0x38"    // BSC
"0xa4b1"  // Arbitrum
"0xa"     // Optimism
"0x2105"  // Base

Solana Networks

["mainnet"]

Bitcoin Networks

["mainnet"]

Bitcoin Streams supports mainnet only.

Status Values

"active"
"paused"
"error"
"terminated"

Only send active or paused in update requests.

Delivery Model

Moralis sends a mandatory test webhook on create and update. Your endpoint must return 2xx.
Streams are at-least-once delivered. Build idempotent consumers.
EVM and Solana webhook flows use confirmed: false then confirmed: true.
Bitcoin can deliver up to three lifecycle notifications for one txid: mempool (block.hash: "mempool", block.height: "0"), in-block but unconfirmed (confirmed: false), then reorg-safe (confirmed: true) after the 2-block confirmation depth.
Streams can enter error and then terminated if webhook delivery keeps failing.

See references/DeliveryGuarantees.md, references/ErrorHandling.md, and references/WebhookSecurity.md.

EVM-Only Features

These are for EVM streams only:

triggers
advancedOptions
includeContractLogs
includeNativeTxs
includeInternalTxs (supported EVM mainnet chains only; not testnets)
includeAllTxLogs (available on Pro plans and higher)
getNativeBalances
filterPossibleSpamAddresses
topic0 / ABI-based filtering

See references/UsefulStreamOptions.md, references/Triggers.md, and references/ListenToAllAddresses.md.

Quick Troubleshooting

Issue	Likely cause	Fix
`400 Bad Request`	Mixed request shape	Re-check the family-specific fields in the endpoint rule
`404 Not Found`	Wrong stream ID	Use a UUID stream ID
`Method Not Allowed`	Wrong method	Create with `PUT`, update/status/replay with `POST`
`Missing limit`	List endpoint	Add `?limit=100`
Stream never activates	Test webhook failed	Return `2xx` from the webhook endpoint

Endpoint Catalog

Complete list of all 47 Streams API endpoints across EVM, Solana, Bitcoin, and shared utilities.

EVM Streams

Create, update, delete, and simulate EVM streams, including block replay helpers.

Endpoint	Description
CreateStream	Create stream
DeleteStream	Delete stream
DuplicateStream	Duplicate stream
GetStream	Get a specific evm stream.
GetStreamBlockDataByNumber	Get webhook data returned on the block number with provided stream config
GetStreamBlockDataToWebhookByNumber	Send webhook based on a specific block number using stream config and addresses.
GetStreams	Get streams
UpdateStream	Update stream
UpdateStreamStatus	Update stream status

EVM Addresses

Manage address lists for EVM streams.

Endpoint	Description
AddAddressToStream	Add address to stream
DeleteAddressFromStream	Delete address from stream
GetAddresses	Get addresses by stream
ReplaceAddressFromStream	Replaces address from stream

Solana Streams

Create, update, delete, and simulate Solana streams, including block replay helpers.

Endpoint	Description
solanaBlockToWebhook	Send Solana webhook data by block number
solanaGetBlockByNumber	Get Solana webhook data by block number
solanaStreamsCreate	Create Solana stream
solanaStreamsDelete	Delete Solana stream
solanaStreamsGet	Get Solana stream by ID
solanaStreamsGetAll	Get Solana streams
solanaStreamsUpdate	Update Solana stream
solanaStreamsUpdateStatus	Update Solana stream status

Solana Addresses

Manage address lists for Solana streams.

Endpoint	Description
solanaStreamsAddAddresses	Add address to Solana stream
solanaStreamsDeleteAddresses	Delete address from Solana stream
solanaStreamsGetAddresses	Get addresses by Solana stream

Bitcoin Streams

Create, update, delete, and simulate Bitcoin streams, including block replay helpers.

Endpoint	Description
bitcoinBlockToWebhook	Send Bitcoin webhook data by block number
bitcoinGetBlockByNumber	Get Bitcoin webhook data by block number
bitcoinStreamsCreate	Create Bitcoin stream
bitcoinStreamsDelete	Delete Bitcoin stream
bitcoinStreamsGet	Get Bitcoin stream by ID
bitcoinStreamsGetAll	Get Bitcoin streams
bitcoinStreamsUpdate	Update Bitcoin stream
bitcoinStreamsUpdateStatus	Update Bitcoin stream status

Bitcoin Addresses

Manage address lists for Bitcoin streams.

Endpoint	Description
bitcoinStreamsAddAddresses	Add address to Bitcoin stream
bitcoinStreamsDeleteAddresses	Delete address from Bitcoin stream
bitcoinStreamsGetAddresses	Get addresses by Bitcoin stream

Bitcoin Xpub

Manage Bitcoin xpubs attached to a stream.

Endpoint	Description
bitcoinStreamsAddXpub	Add xpub to Bitcoin stream
bitcoinStreamsDeleteXpub	Delete xpub from Bitcoin stream
bitcoinStreamsGetXpubs	Get xpubs by Bitcoin stream

Project Settings

Read and update project-level stream settings.

Endpoint	Description
GetSettings	Get project settings
SetSettings	Set project settings

Stats

Inspect global and per-stream statistics.

Endpoint	Description
GetStats	Get project stats
GetStatsByStreamId	Get project stats by Stream ID

History

List delivery history, logs, and replay failed webhook deliveries.

Endpoint	Description
GetHistory	Get history
GetLogs	Get logs
ReplayHistory	Replay history

Historical Jobs

Create and inspect historical stream jobs. Confirm timestamp units and supported stream families before production use.

Endpoint	Description
CreateJob	Create historical stream job
GetJobs	Get historical stream jobs

Example: Create EVM ERC20 Transfer Monitor

curl -X PUT "https://api.moralis-streams.com/streams/evm" \
  -H "X-API-Key: $MORALIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-server.com/webhook",
    "description": "Monitor ERC20 transfers",
    "tag": "erc20-monitor",
    "topic0": ["Transfer(address,address,uint256)"],
    "allAddresses": true,
    "chainIds": ["0x1", "0x89"],
    "advancedOptions": [
      {
        "topic0": "Transfer(address,address,uint256)",
        "includeNativeTxs": true
      }
    ]
  }'

Example: Create Solana Program Stream

curl -X PUT "https://api.moralis-streams.com/streams/solana" \
  -H "X-API-Key: $MORALIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-server.com/webhook",
    "description": "Monitor Solana program activity",
    "tag": "solana-monitor",
    "network": ["mainnet"],
    "programIds": ["YOUR_SOLANA_PROGRAM_ID"],
    "mintAddresses": ["YOUR_SOLANA_MINT"],
    "allAddresses": false
  }'

Example: Create Bitcoin Address Stream

curl -X PUT "https://api.moralis-streams.com/streams/bitcoin" \
  -H "X-API-Key: $MORALIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-server.com/webhook",
    "description": "Monitor Bitcoin transactions",
    "tag": "bitcoin-monitor",
    "network": ["mainnet"],
    "includeInputs": true,
    "includeOutputs": true,
    "allAddresses": false
  }'

Example: Add Bitcoin Xpub

curl -X POST "https://api.moralis-streams.com/streams/bitcoin/YOUR_STREAM_ID/xpub" \
  -H "X-API-Key: $MORALIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "xpub": "YOUR_XPUB"
  }'

Pagination

List endpoints use cursor pagination:

# First page
curl "...?limit=100" -H "X-API-Key: $MORALIS_API_KEY"

# Next page
curl "...?limit=100&cursor=<cursor>" -H "X-API-Key: $MORALIS_API_KEY"

Supported Chains

EVM Streams: use the current supported-chain docs and hex IDs. Moonbeam, Moonriver, and Lisk are scheduled for removal on September 25, 2026.
Solana Streams: mainnet only
Bitcoin Streams: mainnet only

The live Moralis docs also publish a dedicated supported-chains page for EVM Streams.

Reference Documentation

references/BitcoinStreams.md - Bitcoin stream config, xpubs, payload caveats
references/SolanaStreams.md - Solana network, program, mint, and address stream guidance
references/StreamConfiguration.md - Cross-family request-shape reference
references/CommonPitfalls.md - Common mistakes and debugging checklist
references/DeliveryGuarantees.md - Delivery, confirmation, retries
references/ErrorHandling.md - Error states, recovery, replay workflows
references/FAQ.md - Streams FAQ
references/HistoricalJobs.md - Historical job request shape and scope caveats
references/FilterStreams.md - EVM filter expressions
references/ListenToAllAddresses.md - EVM all-address monitoring
references/MonitorMultipleAddresses.md - Address-list patterns
references/ReplayFailedWebhooks.md - Replay failed webhook deliveries
references/ReliabilityAndLifecycle.md - Confirmation, idempotency, lifecycle, rate limits, and re-org handling
references/Triggers.md - EVM read-only contract call enrichment
references/Tutorials.md - Real-world examples
references/UsefulStreamOptions.md - EVM-only advanced options
references/WebhookResponseBody.md - Webhook payload structure
references/WebhookSecurity.md - Signature verification

About this skill