moralis-streams-api

关键：实施前先阅读规则文件

导致 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/ 中的模式参考（仅用于处理边缘情况）

---

设置

API 密钥（可选）

绝不要让用户在聊天中粘贴 API 密钥。 请改为：

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 文件，并自行将密钥粘贴到其中。
4. 告知用户：没有密钥，你将无法代表他们测试或调用 Moralis API。

如果用户还没有密钥，请引导他们访问 admin.moralis.com/register（免费，无需信用卡）。

环境变量位置

.env 文件的位置取决于技能的安装方式：

在项目根目录（用户运行 Claude Code 的同一目录）中创建 .env 文件。确保 .env 已添加到 .gitignore 中。

验证密钥

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

---

基础 URL

https://api.moralis-streams.com

**重要：**这与 Data API（deep-index.moralis.io）不同。

身份验证

所有请求都需要：X-API-Key: $MORALIS_API_KEY

---

HTTP 方法（关键）

操作	方法	端点
创建流	PUT	/streams/evm
更新流	POST	/streams/evm/{id}
删除流	DELETE	/streams/evm/{id}
获取流	GET	/streams/evm
替换地址	PATCH	/streams/evm/{id}/address

**常见错误：**使用 POST 创建流。请改用 PUT。

---

流类型

类型	说明
tx	原生交易
log	合约事件日志
erc20transfer	ERC20 代币转账
erc20approval	ERC20 授权
nfttransfer	NFT 转账
internalTx	内部交易

---

快速参考：最常见的模式

流 ID 格式（始终为 UUID）

// WRONG - Hex format
"0x1234567890abcdef"

// CORRECT - UUID format
"YOUR_STREAM_ID"

链 ID（始终为十六进制）

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

事件签名（topic0）

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

状态值（仅限小写）

"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

---

常见问题（前 5 项）

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。

---

触发器（只读合约调用）

通过链上读取（例如 balanceOf）丰富 Webhook 数据。触发器会执行 view/pure 函数，并将结果附加到 Webhook 事件中。支持动态选择器（$contract、$from、$to）。完整参考及示例请参阅 references/Triggers.md。

---

Webhook 中的原生余额

配置 getNativeBalances，即可在 Webhook 负载中包含原生代币余额（ETH、BNB 等）。需要 Business 套餐或更高等级。配置详情请参阅 references/UsefulStreamOptions.md。

---

投递和错误处理

• 每个事件发送两个 Webhook：未确认（confirmed: false）和已确认（confirmed: true）。必须使用幂等处理程序。
• 流在处于错误状态 24 小时后会自动终止（Webhook 成功率低于 70%）。这是不可恢复的——你必须创建新流。
• 测试 Webhook：每次创建或更新时都会发送。必须返回 200，否则流不会启动。

请参阅 references/DeliveryGuarantees.md 和 references/ErrorHandling.md。

---

Webhook 安全

Webhook 使用流密钥签名（与 API 密钥不同）。

• 请求头： x-signature
• 算法： 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");
};

完整示例请参阅 references/WebhookSecurity.md。

---

测试端点

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

---

快速故障排除

问题	原因	解决方案
“400 Bad Request”	配置无效	检查 webhookUrl、topic0 格式和 chainIds
“404 Not Found”	流 ID 错误	验证 UUID 格式
“Method Not Allowed”	HTTP 方法错误	创建时使用 PUT，更新时使用 POST
“Missing limit”	GET /streams/evm	添加 ?limit=100
“No webhooks”	流已暂停	检查状态是否为“active”

---

端点目录

按类别整理的全部 20 个 Streams API 端点。

流管理

创建、更新、删除和管理流。

端点	说明
AddAddressToStream	将地址添加到流
CreateStream	创建流
DeleteAddressFromStream	从流中删除地址
DeleteStream	删除流
DuplicateStream	复制流
GetAddresses	按流获取地址
GetHistory	获取历史记录
GetLogs	获取日志
GetSettings	获取项目设置
GetStats	获取项目统计信息
GetStatsByStreamId	按 Stream ID 获取项目统计信息
GetStream	获取指定的 EVM 流。
GetStreamBlockDataByNumber	获取使用所提供流配置时指定区块号返回的 Webhook 数据
GetStreamBlockDataToWebhookByNumber	使用流配置和地址，根据指定区块号发送 Webhook。
GetStreams	获取流
ReplaceAddressFromStream	替换流中的地址
UpdateStream	更新流
UpdateStreamStatus	更新流状态

状态和设置

暂停或恢复流并配置设置。

端点	说明
SetSettings	设置项目设置

历史记录和分析

流历史记录、重放、统计信息、日志和区块数据。

端点	说明
ReplayHistory	重放历史记录

监听所有地址

设置 allAddresses: true，并提供 topic0 和 abi，即可监控链上所有合约的某个事件（例如，全网所有 ERC20 转账）。需要更高级别的套餐。完整示例、ABI 模板和注意事项请参阅 references/ListenToAllAddresses.md。

示例：创建 ERC20 转账监控器

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

---

分页

列表端点使用基于游标的分页：

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

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

---

支持的链

所有主流 EVM 链：Ethereum (0x1)、Polygon (0x89)、BSC (0x38)、Arbitrum (0xa4b1)、Optimism (0xa)、Base (0x2105)、Avalanche (0xa86a) 等。

完整的链 ID 列表，请参阅 references/StreamConfiguration.md。

---

参考文档

• 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 - Stream 配置参考
• references/Triggers.md - 只读合约调用增强（balanceOf 等）
• references/Tutorials.md - 实际案例和教程
• references/UsefulStreamOptions.md - 高级 Stream 配置选项
• references/WebhookResponseBody.md - Webhook 载荷结构
• references/WebhookSecurity.md - 签名验证

---

另请参阅

• 端点规则：rules/*.md 文件
• Data API：@moralis-data-api，用于查询区块链状态