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:

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)

导致bug的头号原因是使用错误的HTTP方法或流配置。

对于每个端点：

阅读
```
rules/{EndpointName}.md
```
检查HTTP方法（创建用PUT，更新用POST，删除用DELETE）
验证流ID格式（必须是UUID，不能是十六进制格式）
使用十六进制链ID（如0x1、0x89），而非链名称（如eth、polygon）

阅读顺序：

本SKILL.md（核心模式）
```
rules/
```
目录下的端点规则文件
```
references/
```
中的模式参考（仅用于处理边缘情况）

Setup

配置步骤

API Key (optional)

API密钥（可选）

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

绝对不要让用户在聊天框中粘贴他们的API密钥。 正确做法：

检查环境变量中是否已设置
```
MORALIS_API_KEY
```
（可尝试运行
```
echo $MORALIS_API_KEY
```
）。
如果未设置，可协助创建
```
.env
```
文件并添加空占位符：
```
MORALIS_API_KEY=
```
告知用户自行打开
```
.env
```
文件并粘贴密钥。
提醒用户：如果没有密钥，将无法代表他们测试或调用Moralis API。

如果用户还没有密钥，可引导他们访问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的安装方式：

在项目根目录创建

.env

文件（即用户运行Claude Code的目录）。确保

.env

已添加到

.gitignore

中。

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

注意： 与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方法（重点注意）

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.

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

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

Stream Types

流类型

Type	Description
`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
"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

typescript

// 错误格式 - 十六进制
"0x1234567890abcdef"

// 正确格式 - UUID
"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Chain IDs (ALWAYS hex)

链ID（必须是十六进制）

typescript

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

typescript

"0x1"     // Ethereum
"0x89"    // Polygon
"0x38"    // BSC
"0xa4b1"  // Arbitrum
"0xa"     // Optimism
"0x2105"  // 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
"paused"   // CORRECT
"ACTIVE"   // WRONG

typescript

"active"   // 正确
"paused"   // 正确
"ACTIVE"   // 错误

Common Pitfalls (Top 5)

常见陷阱（前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.

使用POST创建流 - 请改用
```
PUT
```

使用错误的基础URL - 请使用

api.moralis-streams.com

，而非

deep-index.moralis.io

使用十六进制流ID - 必须是UUID格式，不能是十六进制
使用字符串格式的链名称 - 请使用十六进制格式（如0x1），而非链名称（如eth）
状态值使用大写 - 请使用小写（"active"、"paused"）

完整参考请查看references/CommonPitfalls.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密钥不同）。

请求头：
```
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"

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

Pause stream (POST to status)

暂停流（向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

快速故障排查

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"

问题	原因	解决方案
"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"

Endpoint Catalog

端点目录

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

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

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

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

端点	描述
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.

Endpoint	Description
SetSettings	Set project settings

暂停/恢复流及配置设置。

端点	描述
SetSettings	设置项目配置

History & Analytics

历史记录与分析

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

Endpoint	Description
ReplayHistory	Replay history

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

端点	描述
ReplayHistory	重放历史记录

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

references/CommonPitfalls.md - 完整陷阱参考
references/StreamConfiguration.md - 流配置参考
references/WebhookSecurity.md - 签名验证
references/WebhookResponseBody.md - Webhook负载结构
references/MonitorMultipleAddresses.md - 多地址监控模式
references/ReplayFailedWebhooks.md - 失败Webhook重放指南

另请参阅

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

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

moralis-streams-api

Original

Translation

CRITICAL: Read Rule Files Before Implementing

重要提示：实施前请阅读规则文件

Setup

配置步骤

API Key (optional)

API密钥（可选）

Environment Variable Discovery

环境变量位置说明

Verify Your Key

验证密钥有效性

Base URL

基础URL

Authentication

身份验证

HTTP Methods (CRITICAL)

HTTP方法（重点注意）

Stream Types

流类型

Quick Reference: Most Common Patterns

快速参考：最常用模式

Stream ID Format (ALWAYS UUID)

流ID格式（必须是UUID）

Chain IDs (ALWAYS hex)

链ID（必须是十六进制）

Event Signatures (topic0)

事件签名（topic0）

Status Values (lowercase only)

状态值（仅支持小写）

Common Pitfalls (Top 5)

常见陷阱（前5名）

Webhook Security

Webhook安全性

Testing Endpoints

测试端点

List streams (requires limit)

列出流（必须携带limit参数）

Create stream (PUT, not POST)

创建流（用PUT，不要用POST）

Pause stream (POST to status)

暂停流（向status端点发送POST请求）

Quick Troubleshooting

快速故障排查

Endpoint Catalog

端点目录

Stream Management

流管理

Status & Settings

状态与设置

History & Analytics

历史记录与分析

Example: Create ERC20 Transfer Monitor

示例：创建ERC20转账监控流

Pagination

分页

First page

第一页

Next page

下一页

Supported Chains

支持的链

Reference Documentation

参考文档

See Also

另请参阅