moralis-streams-api

CRITICAL: Read Rule Files Before Implementing

The #1 cause of bugs is using wrong HTTP methods or stream configurations.

For EVERY endpoint:

1. Read rules/{EndpointName}.md
2. Check HTTP method (PUT for create, POST for update, DELETE for delete)
3. Verify stream ID format (UUID, not hex)
4. Use hex chain IDs (0x1, 0x89), not names (eth, polygon)

Reading Order:

1. This SKILL.md (core patterns)
2. Endpoint rule file in rules/
3. Pattern references in references/ (for edge cases only)

---

Setup

API Key (optional)

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

1. Check if MORALIS_API_KEY is already set in the environment (try running echo $MORALIS_API_KEY).
2. If not set, offer to create the .env file with an empty placeholder: MORALIS_API_KEY=
3. Tell the user to open the .env file and paste their key there themselves.
4. Let them know: without the key, you won't be able to test or call the Moralis API on their behalf.

If they don't have a key yet, point them to admin.moralis.com/register (free, no credit card).

Environment Variable Discovery

The .env file location depends on how skills are installed:

Create the .env file in the project root (same directory the user runs Claude Code from). Make sure .env is in .gitignore.

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

Important: Different from Data API (deep-index.moralis.io).

Authentication

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

---

HTTP Methods (CRITICAL)

Action	Method	Endpoint
Create stream	PUT	/streams/evm
Update stream	POST	/streams/evm/{id}
Delete stream	DELETE	/streams/evm/{id}
Get streams	GET	/streams/evm
Replace addresses	PATCH	/streams/evm/{id}/address

Common mistake: Using POST to create streams. Use PUT instead.

---

Stream Types

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

---

Quick Reference: Most Common Patterns

Stream ID Format (ALWAYS UUID)

// WRONG - Hex format
"0x1234567890abcdef"

// CORRECT - UUID format
"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Chain IDs (ALWAYS hex)

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

Event Signatures (topic0)

"Transfer(address,address,uint256)"   // ERC20/NFT Transfer
"Approval(address,address,uint256)"   // ERC20 Approval

Status Values (lowercase only)

"active"   // CORRECT
"paused"   // CORRECT
"ACTIVE"   // WRONG

---

Common Pitfalls (Top 5)

1. Using POST to create streams - Use PUT instead
2. Wrong base URL - Use api.moralis-streams.com, NOT deep-index.moralis.io
3. Hex stream ID - Must be UUID format, not hex
4. String chain names - Use hex (0x1), not names (eth)
5. Uppercase status - Use lowercase ("active", "paused")

See references/CommonPitfalls.md for complete reference.

---

Webhook Security

Webhooks are signed with your streams secret (different from API key).

• Header: x-signature
• Algorithm: sha3(JSON.stringify(body) + secret)

const verifySignature = (req, secret) => {
  const provided = req.headers["x-signature"];
  const generated = web3.utils.sha3(JSON.stringify(req.body) + secret);
  if (generated !== provided) throw new Error("Invalid Signature");
};

See references/WebhookSecurity.md for complete examples.

---

Testing Endpoints

WEBHOOK_URL="https://your-server.com/webhook"

# List streams (requires limit)
curl "https://api.moralis-streams.com/streams/evm?limit=100" \
  -H "X-API-Key: $MORALIS_API_KEY"

# Create stream (PUT, not POST)
curl -X PUT "https://api.moralis-streams.com/streams/evm" \
  -H "X-API-Key: $MORALIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "'${WEBHOOK_URL}'",
    "description": "Test stream",
    "tag": "test",
    "topic0": ["Transfer(address,address,uint256)"],
    "allAddresses": false,
    "chainIds": ["0x1"]
  }'

# Pause stream (POST to status)
curl -X POST "https://api.moralis-streams.com/streams/evm/<stream_id>/status" \
  -H "X-API-Key: $MORALIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "paused"}'

---

Quick Troubleshooting

Issue	Cause	Solution
"400 Bad Request"	Invalid config	Check webhookUrl, topic0 format, chainIds
"404 Not Found"	Wrong stream ID	Verify UUID format
"Method Not Allowed"	Wrong HTTP method	PUT for create, POST for update
"Missing limit"	GET /streams/evm	Add ?limit=100
"No webhooks"	Stream paused	Check status is "active"

---

Endpoint Catalog

Complete list of all 20 Streams API endpoints organized by category.

Stream Management

Create, update, delete, and manage streams.

Endpoint	Description
AddAddressToStream	Add address to stream
CreateStream	Create stream
DeleteAddressFromStream	Delete address from stream
DeleteStream	Delete stream
DuplicateStream	Duplicate stream
GetAddresses	Get addresses by stream
GetHistory	Get history
GetLogs	Get logs
GetSettings	Get project settings
GetStats	Get project stats
GetStatsByStreamId	Get project stats by Stream ID
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
ReplaceAddressFromStream	Replaces address from stream
UpdateStream	Update stream
UpdateStreamStatus	Update stream status

Status & Settings

Pause/resume streams and configure settings.

Endpoint	Description
SetSettings	Set project settings

History & Analytics

Stream history, replay, statistics, logs, and block data.

Endpoint	Description
ReplayHistory	Replay history

Example: Create 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)",
      "includeNativeHash": true
    }]
  }'

---

Pagination

List endpoints use cursor-based pagination:

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

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

---

Supported Chains

All major EVM chains: Ethereum (0x1), Polygon (0x89), BSC (0x38), Arbitrum (0xa4b1), Optimism (0xa), Base (0x2105), Avalanche (0xa86a), and more.

See references/StreamConfiguration.md for complete chain ID list.

---

Reference Documentation

• references/CommonPitfalls.md - Complete pitfalls reference
• references/StreamConfiguration.md - Stream config reference
• references/WebhookSecurity.md - Signature verification
• references/WebhookResponseBody.md - Webhook payload structure
• references/MonitorMultipleAddresses.md - Multi-address monitoring patterns
• references/ReplayFailedWebhooks.md - Replay failed webhook guide

---

See Also

• Endpoint rules: rules/*.md files
• Data API: @moralis-data-api for querying blockchain state