Back to Details

moralis-streams-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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)
出现bug的首要原因是使用了错误的HTTP方法或流配置。
对于每个接口：
  1. 阅读 
    rules/{EndpointName}.md
    文件
  2. 确认HTTP方法（创建用PUT，更新用POST，删除用DELETE）
  3. 验证流ID格式（必须是UUID，不能是十六进制格式）
  4. 使用十六进制链ID（如0x1、0x89），而非链名称（如eth、polygon）
阅读顺序：
  1. 本SKILL.md文件（核心模式）
  2. rules/
    目录下的接口规则文件
  3. references/
    目录下的模式参考（仅用于处理边缘情况）

Setup

配置步骤

API Key (optional)

API Key（可选）

Never ask the user to paste their API key into the chat. Instead:
  1. Check if 
    MORALIS_API_KEY
    is set in the environment (try running 
    [ -n "$MORALIS_API_KEY" ] && echo "API key is set" || echo "API key is NOT set"
    ).
  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).
切勿要求用户在聊天框中粘贴其API Key。 应按以下方式操作：
  1. 检查环境变量中是否已设置
    MORALIS_API_KEY
    （可执行命令：
    [ -n "$MORALIS_API_KEY" ] && echo "API key is set" || echo "API key is NOT set"
    ）。
  2. 若未设置，提议创建包含空占位符的
    .env
    文件：
    MORALIS_API_KEY=
  3. 告知用户自行打开
    .env
    文件并粘贴其API Key。
  4. 说明：若无API Key，将无法代表用户测试或调用Moralis API。
若用户尚未拥有API Key，可引导其前往admin.moralis.com/register注册（免费，无需信用卡）。

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
.
.env
文件的位置取决于Skill的安装方式：
请在项目根目录（即用户运行Claude Code的目录）创建
.env
文件，并确保
.env
已添加到
.gitignore
中。

Verify Your Key

验证API Key

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

Base URL

基础URL

https://api.moralis-streams.com
Important: Different from Data API (
deep-index.moralis.io
).
https://api.moralis-streams.com
注意： 此URL与Data API的URL（
deep-index.moralis.io
）不同。

Authentication

身份验证

All requests require: 
X-API-Key: $MORALIS_API_KEY
所有请求均需携带：
X-API-Key: $MORALIS_API_KEY

HTTP Methods (CRITICAL)

HTTP方法（重点注意）

ActionMethodEndpoint
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.
操作方法接口
创建流
PUT
/streams/evm
更新流
POST
/streams/evm/{id}
删除流
DELETE
/streams/evm/{id}
获取流列表
GET
/streams/evm
替换流中地址
PATCH
/streams/evm/{id}/address
常见错误： 使用POST方法创建流。请改用PUT。

Stream Types

流类型

TypeDescription
tx
Native transactions
log
Contract event logs
erc20transfer
ERC20 token transfers
erc20approval
ERC20 approvals
nfttransfer
NFT transfers
internalTx
Internal transactions
类型描述
tx
原生交易
log
合约事件日志
erc20transfer
ERC20代币转账
erc20approval
ERC20授权
nfttransfer
NFT转账
internalTx
内部交易

Quick Reference: Most Common Patterns

快速参考：最常用模式

Stream ID Format (ALWAYS UUID)

流ID格式（必须为UUID）

typescript
// WRONG - Hex format
"0x1234567890abcdef"

// CORRECT - UUID format
"YOUR_STREAM_ID"
typescript
// 错误示例 - 十六进制格式
"0x1234567890abcdef"

// 正确示例 - UUID格式
"YOUR_STREAM_ID"

Chain IDs (ALWAYS hex)

链ID（必须为十六进制）

typescript
"0x1"     // Ethereum
"0x89"    // Polygon
"0x38"    // BSC
"0xa4b1"  // Arbitrum
"0xa"     // Optimism
"0x2105"  // Base
typescript
"0x1"     // Ethereum（以太坊）
"0x89"    // Polygon（Polygon链）
"0x38"    // BSC（币安智能链）
"0xa4b1"  // Arbitrum（Arbitrum链）
"0xa"     // Optimism（Optimism链）
"0x2105"  // Base（Base链）

Event Signatures (topic0)

事件签名（topic0）

typescript
"Transfer(address,address,uint256)"   // ERC20/NFT Transfer
"Approval(address,address,uint256)"   // ERC20 Approval
typescript
"Transfer(address,address,uint256)"   // ERC20/NFT转账事件
"Approval(address,address,uint256)"   // ERC20授权事件

Status Values (lowercase only)

状态值（仅支持小写）

typescript
"active"      // CORRECT - normal operating state
"paused"      // CORRECT - manually paused
"error"       // CORRECT - auto-set when webhook success rate <70%
"terminated"  // CORRECT - unrecoverable, after 24h in error
"ACTIVE"      // WRONG
typescript
"active"      // 正确 - 正常运行状态
"paused"      // 正确 - 手动暂停
"error"       // 正确 - 当Webhook成功率<70%时自动设置
"terminated"  // 正确 - 错误状态持续24小时后进入，不可恢复
"ACTIVE"      // 错误示例

Common Pitfalls (Top 5)

常见陷阱（前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")
  6. Not returning 200 on test webhook - Stream won't start unless your endpoint returns 2xx on the test webhook sent during create/update
See references/CommonPitfalls.md for complete reference.
  1. 使用POST创建流 - 请改用
    PUT
    方法
  2. 使用错误的基础URL - 请使用
    api.moralis-streams.com
    ，而非
    deep-index.moralis.io
  3. 使用十六进制格式的流ID - 必须为UUID格式，不能是十六进制
  4. 使用字符串格式的链名称 - 请使用十六进制格式（如0x1），而非链名称（如eth）
  5. 使用大写状态值 - 请使用小写格式（如"active"、"paused"）
  6. 测试Webhook未返回200状态码 - 创建/更新流时会发送测试Webhook，若未返回2xx状态码，流将无法启动
完整参考请见references/CommonPitfalls.md。

Triggers (Read-Only Contract Calls)

触发器（只读合约调用）

Enrich webhook data with on-chain reads (e.g., 
balanceOf
). Triggers execute 
view
/
pure
functions and attach results to webhook events. Supports dynamic selectors (
$contract
, 
$from
, 
$to
). See references/Triggers.md for complete reference with examples.
通过链上只读调用（如
balanceOf
）丰富Webhook数据。触发器可执行
view
/
pure
函数，并将结果附加到Webhook事件中。支持动态选择器（如
$contract
、
$from
、
$to
）。完整示例请见references/Triggers.md。

Native Balances in Webhooks

Webhook中的原生代币余额

Configure 
getNativeBalances
to include native token balances (ETH, BNB, etc.) in webhook payloads. Requires Business plan+. See references/UsefulStreamOptions.md for configuration details.
配置
getNativeBalances
可在Webhook payload中包含原生代币余额（如ETH、BNB等）。此功能需Business及以上套餐。配置详情请见references/UsefulStreamOptions.md。

Delivery and Error Handling

投递与错误处理

  • Two webhooks per event: Unconfirmed (
    confirmed: false
    ) + Confirmed (
    confirmed: true
    ). Idempotent handlers required.
  • Streams auto-terminate after 24 hours in error state (webhook success rate <70%). This is unrecoverable — you must create a new stream.
  • Test webhook: Sent on every create/update. Must return 200 or stream won't start.
See references/DeliveryGuarantees.md and references/ErrorHandling.md.
  • 每个事件触发两次Webhook：未确认状态（
    confirmed: false
    ）+ 已确认状态（
    confirmed: true
    ）。需实现幂等处理逻辑。
  • 流在错误状态持续24小时后将自动终止（Webhook成功率<70%）。此状态不可恢复——必须创建新流。
  • 测试Webhook：每次创建/更新流时都会发送。必须返回200状态码，否则流无法启动。
完整参考请见references/DeliveryGuarantees.md和references/ErrorHandling.md。

Webhook Security

Webhook安全

Webhooks are signed with your streams secret (different from API key).
  • Header: 
    x-signature
  • Algorithm: 
    sha3(JSON.stringify(body) + secret)
javascript
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.
Webhook会使用你的流密钥（与API Key不同）进行签名。
  • 请求头： 
    x-signature
  • 算法： 
    sha3(JSON.stringify(body) + secret)
javascript
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");
};
完整示例请见references/WebhookSecurity.md。

Testing Endpoints

测试接口

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

List streams (requires limit)

获取流列表（必须指定limit参数）

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

Create stream (PUT, not POST)

创建流（使用PUT，而非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"] }'
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)

暂停流（通过POST修改状态）

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"}'

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

快速故障排查

IssueCauseSolution
"400 Bad Request"Invalid configCheck webhookUrl, topic0 format, chainIds
"404 Not Found"Wrong stream IDVerify UUID format
"Method Not Allowed"Wrong HTTP methodPUT for create, POST for update
"Missing limit"GET /streams/evmAdd 
?limit=100
"No webhooks"Stream pausedCheck status is "active"
问题原因解决方案
"400 Bad Request"配置无效检查webhookUrl、topic0格式、chainIds是否正确
"404 Not Found"流ID错误验证流ID是否为UUID格式
"Method Not Allowed"HTTP方法错误创建用PUT，更新用POST
"Missing limit"调用GET /streams/evm时未传参数添加
?limit=100
参数
"No webhooks"流已暂停检查流状态是否为"active"

Endpoint Catalog

接口目录

Complete list of all 20 Streams API endpoints organized by category.
按类别整理的全部20个Streams API接口。

Stream Management

流管理

Create, update, delete, and manage streams.
EndpointDescription
AddAddressToStreamAdd address to stream
CreateStreamCreate stream
DeleteAddressFromStreamDelete address from stream
DeleteStreamDelete stream
DuplicateStreamDuplicate stream
GetAddressesGet addresses by stream
GetHistoryGet history
GetLogsGet logs
GetSettingsGet project settings
GetStatsGet project stats
GetStatsByStreamIdGet project stats by Stream ID
GetStreamGet a specific evm stream.
GetStreamBlockDataByNumberGet webhook data returned on the block number with provided stream config
GetStreamBlockDataToWebhookByNumberSend webhook based on a specific block number using stream config and addresses.
GetStreamsGet streams
ReplaceAddressFromStreamReplaces address from stream
UpdateStreamUpdate stream
UpdateStreamStatusUpdate stream status
创建、更新、删除及管理流。
接口描述
AddAddressToStream向流中添加地址
CreateStream创建流
DeleteAddressFromStream从流中移除地址
DeleteStream删除流
DuplicateStream复制流
GetAddresses获取流关联的地址列表
GetHistory获取历史记录
GetLogs获取日志
GetSettings获取项目设置
GetStats获取项目统计数据
GetStatsByStreamId按流ID获取项目统计数据
GetStream获取指定EVM流的详情
GetStreamBlockDataByNumber根据区块号获取流配置对应的Webhook数据
GetStreamBlockDataToWebhookByNumber根据指定区块号、流配置和地址发送Webhook
GetStreams获取流列表
ReplaceAddressFromStream替换流中的地址
UpdateStream更新流
UpdateStreamStatus更新流状态

Status & Settings

状态与设置

Pause/resume streams and configure settings.
EndpointDescription
SetSettingsSet project settings
暂停/恢复流及配置项目设置。
接口描述
SetSettings设置项目配置

History & Analytics

历史与分析

Stream history, replay, statistics, logs, and block data.
EndpointDescription
ReplayHistoryReplay history
流历史、重放、统计、日志及区块数据。
接口描述
ReplayHistory重放历史事件

Listen to All Addresses

监听链上所有地址

Set 
allAddresses: true
with a 
topic0
and 
abi
to monitor an event across every contract on a chain (e.g., all ERC20 transfers network-wide). Requires higher-tier plans. See references/ListenToAllAddresses.md for complete examples, ABI templates, and gotchas.
设置
allAddresses: true
并指定
topic0
和
abi
，即可监控链上所有合约的指定事件（如全网所有ERC20转账）。此功能需高级套餐支持。完整示例、ABI模板及注意事项请见references/ListenToAllAddresses.md。

Example: Create ERC20 Transfer Monitor

示例：创建ERC20转账监控流

bash
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
    }]
  }'
bash
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:
bash
undefined
列表类接口使用基于游标（cursor）的分页：
bash
undefined

First page

第一页

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

Next page

下一页

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

---
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.
所有主流EVM兼容链：Ethereum（0x1）、Polygon（0x89）、BSC（0x38）、Arbitrum（0xa4b1）、Optimism（0xa）、Base（0x2105）、Avalanche（0xa86a）等。
完整链ID列表请见references/StreamConfiguration.md。

Reference Documentation

参考文档

  • references/CommonPitfalls.md - Complete pitfalls reference
  • references/DeliveryGuarantees.md - At-least-once delivery, dual webhooks, confirmation blocks, test webhooks
  • references/ErrorHandling.md - Retry schedule, error/terminated states, rate limits, re-org handling
  • references/FAQ.md - Streams API frequently asked questions
  • references/FilterStreams.md - Webhook data filtering to reduce noise
  • references/ListenToAllAddresses.md - Monitor events across all contracts on a chain
  • references/MonitorMultipleAddresses.md - Multi-address monitoring patterns
  • references/ReplayFailedWebhooks.md - Replay failed webhook guide
  • references/StreamConfiguration.md - Stream config reference
  • references/Triggers.md - Read-only contract call enrichment (balanceOf, etc.)
  • references/Tutorials.md - Real-world examples and tutorials
  • references/UsefulStreamOptions.md - Advanced stream configuration options
  • references/WebhookResponseBody.md - Webhook payload structure
  • references/WebhookSecurity.md - Signature verification
  • references/CommonPitfalls.md - 常见陷阱完整参考
  • references/DeliveryGuarantees.md - 至少一次投递、双重Webhook、确认区块、测试Webhook
  • references/ErrorHandling.md - 重试机制、错误/终止状态、速率限制、链重组处理
  • references/FAQ.md - Streams API常见问题
  • references/FilterStreams.md - Webhook数据过滤以减少冗余
  • references/ListenToAllAddresses.md - 监控链上所有合约的事件
  • references/MonitorMultipleAddresses.md - 多地址监控模式
  • references/ReplayFailedWebhooks.md - 重放失败Webhook指南
  • references/StreamConfiguration.md - 流配置参考
  • references/Triggers.md - 只读合约调用数据增强（如balanceOf等）
  • references/Tutorials.md - 实战示例与教程
  • references/UsefulStreamOptions.md - 高级流配置选项
  • references/WebhookResponseBody.md - Webhook payload结构
  • references/WebhookSecurity.md - 签名验证

See Also

另请参阅

  • Endpoint rules: 
    rules/*.md
    files
  • Data API: @moralis-data-api for querying blockchain state
  • 接口规则：
    rules/*.md
    文件
  • Data API：@moralis-data-api（用于查询区块链状态）