CRITICAL: Read Rule Files Before Implementing

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

For EVERY endpoint:

• Read rules/{EndpointName}.md

• Check HTTP method (PUT for create, POST for update, DELETE for delete)

• Verify stream ID format (UUID, not hex)

• Use hex chain IDs (0x1, 0x89), not names (eth, polygon)

Reading Order:

• This SKILL.md (core patterns)

• Endpoint rule file in rules/

• 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:

• Check if MORALIS_API_KEY is already set in the environment (try running echo $MORALIS_API_KEY ).

• If not set, offer to create the .env file with an empty placeholder: MORALIS_API_KEY=

• Tell the user to open the .env file and paste their key there themselves.

• 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)

• Using POST to create streams - Use PUT instead

• Wrong base URL - Use api.moralis-streams.com , NOT deep-index.moralis.io

• Hex stream ID - Must be UUID format, not hex

• String chain names - Use hex (0x1), not names (eth)

• 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