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:

1. Read rules/{EndpointName}.md
2. Confirm the family first:
   • EVM: /streams/evm
   • Solana: /streams/solana
   • Bitcoin: /streams/bitcoin
   • Utilities: /history, /historical-jobs, /settings, /stats
3. Check the HTTP method carefully (PUT create, POST update/status/replay, DELETE delete)
4. Verify stream IDs are UUIDs, not hashes or addresses
5. 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:

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

Setup

API Key

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

1. Check whether MORALIS_API_KEY is set:

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

2. If missing, offer to create a local .env with MORALIS_API_KEY=
3. Tell the user to open .env and add the key themselves
4. 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

EVM

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

Stream types:

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

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.

EVM Addresses

Manage address lists for EVM streams.

Solana Streams

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

Solana Addresses

Manage address lists for Solana streams.

Bitcoin Streams

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

Bitcoin Addresses

Manage address lists for Bitcoin streams.

Bitcoin Xpub

Manage Bitcoin xpubs attached to a stream.

Project Settings

Read and update project-level stream settings.

Stats

Inspect global and per-stream statistics.

History

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

Historical Jobs

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

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

See Also

• Endpoint rules: rules/*.md
• Data API: @moralis-data-api for historical or current blockchain state