moralis-streams-api

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

导致 Streams 错误的首要原因，是混淆了不同流系列或请求结构。

对于每个端点：

1. 阅读 rules/{EndpointName}.md
2. 先确认所属系列：
   • EVM：/streams/evm
   • Solana：/streams/solana
   • Bitcoin：/streams/bitcoin
   • 实用工具：/history、/historical-jobs、/settings、/stats
3. 仔细检查 HTTP 方法（PUT 创建、POST 更新／状态／重放、DELETE 删除）
4. 确认流 ID 是 UUID，而不是哈希或地址
5. 使用对应系列的正确配置结构：
   • EVM：chainIds、topic0、abi、advancedOptions
   • Solana：network、programIds、mintAddresses、allAddresses
   • Bitcoin：network、includeInputs、includeOutputs、allAddresses、xpub

阅读顺序：

1. 本文件 SKILL.md
2. rules/ 中的端点规则
3. references/StreamConfiguration.md
4. 针对特殊情况的系列专属参考资料

---

设置

API 密钥

**切勿要求用户在聊天中粘贴 API 密钥。**请改为：

1. 检查是否已设置 MORALIS_API_KEY：

   [ -n "$MORALIS_API_KEY" ] && echo "API key is set" || echo "API key is NOT set"
   

2. 如果未设置，提出在本地创建一个包含 MORALIS_API_KEY= 的 .env 文件
3. 告知用户打开 .env 并自行添加密钥
4. 说明没有密钥就无法调用或测试 Moralis Streams

如果用户需要密钥，请引导他们访问 admin.moralis.com/register。Free 套餐已于 2026 年 9 月 1 日取消；现在需要付费套餐。Starter、Pro 和 Business 的月费价格请参阅套餐定价，并核对实时定价页面。未确认的免费 Webhook 不代表存在 Free 订阅套餐。

验证密钥

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

---

基础 URL

https://api.moralis-streams.com

所有请求都必须包含 X-API-Key: $MORALIS_API_KEY。

---

流系列

系列	核心筛选条件	其他功能	说明
EVM	chainIds、topic0、abi、流地址	advancedOptions、includeContractLogs、includeNativeTxs、includeInternalTxs、triggers、getNativeBalances	使用十六进制链 ID，例如 0x1、0x89
Solana	network、programIds、mintAddresses、流地址	allAddresses、区块重放辅助功能	不使用 chainIds、topic0，也不进行 EVM ABI 解码
Bitcoin	network、流地址、allAddresses	includeInputs、includeOutputs、xpub 端点、区块重放辅助功能	通过地址和 xpub 监控，而不是通过合约主题监控
实用工具	历史记录、重放、历史任务、设置、统计数据	账户级操作	必须确认历史任务的时间戳单位和系列范围

EVM

在受支持的 EVM 主网链上，用户需要监控合约事件、ERC20 / ERC721 / ERC1155 转账、授权、原生交易和内部交易时，请使用 EVM 流。

流类型：

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

Solana

用户需要监控 mainnet 上的程序、铸币或地址活动时，请使用 Solana 流。

• 主要筛选条件为 programIds 和 mintAddresses
• network 必须为 ["mainnet"]
• 没有 EVM 风格的 topic0、abi 或 chainIds
• Solana 地址使用 base58 编码且区分大小写；切勿将其转换为小写
• Solana 负载使用 transactions[].signature、accountKeys、instructions、innerInstructions 和代币前后余额，而不是 EVM 事件数组

请参阅 references/SolanaStreams.md。

Bitcoin

使用 Bitcoin 流进行基于地址或 xpub 的监控。

• 主要筛选条件是监控的地址或 xpub
• network 是一个数组
• includeInputs 和 includeOutputs 控制载荷详情
• network 必须为 ["mainnet"]

使用 ["mainnet"]。

参见 references/BitcoinStreams.md。

---

快速参考

流 ID 格式

// WRONG
"0x1234567890abcdef"

// CORRECT
"YOUR_STREAM_ID"

EVM 链 ID

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

Solana 网络

["mainnet"]

Bitcoin 网络

["mainnet"]

Bitcoin 流仅支持 mainnet。

状态值

"active"
"paused"
"error"
"terminated"

更新请求中只能发送 active 或 paused。

---

交付模型

• Moralis 会在创建和更新时发送必需的测试 Webhook。你的端点必须返回 2xx。
• 流采用至少一次交付。请构建幂等消费者。
• EVM 和 Solana Webhook 流程会先使用 confirmed: false，然后使用 confirmed: true。
• 对于一个 txid，Bitcoin 最多会发送三次生命周期通知：内存池（block.hash: "mempool"、block.height: "0"）、已纳入区块但尚未确认（confirmed: false），然后在达到 2 个区块的确认深度后可防止重组（confirmed: true）。
• 如果 Webhook 持续交付失败，流可能进入 error 状态，然后进入 terminated 状态。

参见 references/DeliveryGuarantees.md、references/ErrorHandling.md 和 references/WebhookSecurity.md。

---

仅限 EVM 的功能

以下功能仅适用于 EVM 流：

• triggers
• advancedOptions
• includeContractLogs
• includeNativeTxs
• includeInternalTxs（仅支持 EVM 主网链；不支持测试网）
• includeAllTxLogs（Pro 及更高套餐可用）
• getNativeBalances
• filterPossibleSpamAddresses
• topic0 / 基于 ABI 的筛选

参见 references/UsefulStreamOptions.md、references/Triggers.md 和 references/ListenToAllAddresses.md。

---

快速故障排查

问题	可能原因	解决方法
400 Bad Request	请求结构混用	重新检查端点规则中的特定系列字段
404 Not Found	流 ID 错误	使用 UUID 流 ID
Method Not Allowed	请求方法错误	使用 PUT 创建，使用 POST 更新状态或重放
Missing limit	列表端点	添加 ?limit=100
流始终无法激活	测试 Webhook 失败	让 Webhook 端点返回 2xx

---

端点目录

包含 EVM、Solana、Bitcoin 和共享实用功能的全部 47 个 Streams API 端点。

EVM 流

创建、更新、删除和模拟 EVM 流，包括区块重放辅助功能。

端点	描述
CreateStream	创建流
DeleteStream	删除流
DuplicateStream	复制流
GetStream	获取指定的 EVM 流。
GetStreamBlockDataByNumber	使用提供的流配置，获取区块编号对应的 Webhook 数据
GetStreamBlockDataToWebhookByNumber	使用流配置和地址，根据指定区块编号发送 Webhook。
GetStreams	获取流
UpdateStream	更新流
UpdateStreamStatus	更新流状态

EVM 地址

管理 EVM 流的地址列表。

端点	描述
AddAddressToStream	向流添加地址
DeleteAddressFromStream	从流中删除地址
GetAddresses	按流获取地址
ReplaceAddressFromStream	替换流中的地址

Solana 流

创建、更新、删除和模拟 Solana 流，包括区块重放辅助功能。

Endpoint	描述
solanaBlockToWebhook	按区块编号发送 Solana Webhook 数据
solanaGetBlockByNumber	按区块编号获取 Solana Webhook 数据
solanaStreamsCreate	创建 Solana 流
solanaStreamsDelete	删除 Solana 流
solanaStreamsGet	按 ID 获取 Solana 流
solanaStreamsGetAll	获取 Solana 流
solanaStreamsUpdate	更新 Solana 流
solanaStreamsUpdateStatus	更新 Solana 流状态

Solana 地址

管理 Solana 流的地址列表。

Endpoint	描述
solanaStreamsAddAddresses	向 Solana 流添加地址
solanaStreamsDeleteAddresses	从 Solana 流删除地址
solanaStreamsGetAddresses	获取 Solana 流的地址

Bitcoin 流

创建、更新、删除和模拟 Bitcoin 流，包括区块重放辅助功能。

Endpoint	描述
bitcoinBlockToWebhook	按区块编号发送 Bitcoin Webhook 数据
bitcoinGetBlockByNumber	按区块编号获取 Bitcoin Webhook 数据
bitcoinStreamsCreate	创建 Bitcoin 流
bitcoinStreamsDelete	删除 Bitcoin 流
bitcoinStreamsGet	按 ID 获取 Bitcoin 流
bitcoinStreamsGetAll	获取 Bitcoin 流
bitcoinStreamsUpdate	更新 Bitcoin 流
bitcoinStreamsUpdateStatus	更新 Bitcoin 流状态

Bitcoin 地址

管理 Bitcoin 流的地址列表。

Endpoint	描述
bitcoinStreamsAddAddresses	向 Bitcoin 流添加地址
bitcoinStreamsDeleteAddresses	从 Bitcoin 流删除地址
bitcoinStreamsGetAddresses	获取 Bitcoin 流的地址

Bitcoin Xpub

管理关联到流的 Bitcoin xpub。

Endpoint	描述
bitcoinStreamsAddXpub	向 Bitcoin 流添加 xpub
bitcoinStreamsDeleteXpub	从 Bitcoin 流删除 xpub
bitcoinStreamsGetXpubs	获取 Bitcoin 流的 xpub

项目设置

读取和更新项目级别的流设置。

Endpoint	描述
GetSettings	获取项目设置
SetSettings	设置项目设置

统计信息

查看全局和各流的统计信息。

Endpoint	描述
GetStats	获取项目统计信息
GetStatsByStreamId	按 Stream ID 获取项目统计信息

历史记录

查看投递历史记录和日志，并重放失败的 Webhook 投递。

Endpoint	描述
GetHistory	获取历史记录
GetLogs	获取日志
ReplayHistory	重放历史记录

历史任务

创建并检查历史流任务。在生产环境使用前，请确认时间戳单位和支持的流系列。

Endpoint	描述
CreateJob	创建历史流任务
GetJobs	获取历史流任务

示例：创建 EVM 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)",
        "includeNativeTxs": true
      }
    ]
  }'

示例：创建 Solana 程序流

curl -X PUT "https://api.moralis-streams.com/streams/solana" \
  -H "X-API-Key: $MORALIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-server.com/webhook",
    "description": "Monitor Solana program activity",
    "tag": "solana-monitor",
    "network": ["mainnet"],
    "programIds": ["YOUR_SOLANA_PROGRAM_ID"],
    "mintAddresses": ["YOUR_SOLANA_MINT"],
    "allAddresses": false
  }'

示例：创建 Bitcoin 地址流

curl -X PUT "https://api.moralis-streams.com/streams/bitcoin" \
  -H "X-API-Key: $MORALIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-server.com/webhook",
    "description": "Monitor Bitcoin transactions",
    "tag": "bitcoin-monitor",
    "network": ["mainnet"],
    "includeInputs": true,
    "includeOutputs": true,
    "allAddresses": false
  }'

示例：添加 Bitcoin Xpub

curl -X POST "https://api.moralis-streams.com/streams/bitcoin/YOUR_STREAM_ID/xpub" \
  -H "X-API-Key: $MORALIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "xpub": "YOUR_XPUB"
  }'

分页

列表端点使用游标分页：

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

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

---

支持的链

• EVM Streams：请使用当前支持链文档和十六进制 ID。Moonbeam、Moonriver 和 Lisk 计划于 2026 年 9 月 25 日移除。
• Solana Streams：仅支持 mainnet
• Bitcoin Streams：仅支持 mainnet

Moralis 的在线文档还为 EVM Streams 发布了专门的支持链页面。

---

参考文档

• references/BitcoinStreams.md - Bitcoin 流配置、xpub 和负载注意事项
• references/SolanaStreams.md - Solana 网络、程序、mint 和地址流指南
• references/StreamConfiguration.md - 跨系列请求格式参考
• references/CommonPitfalls.md - 常见错误和调试清单
• references/DeliveryGuarantees.md - 交付、确认和重试
• references/ErrorHandling.md - 错误状态、恢复和重放工作流
• references/FAQ.md - Streams 常见问题
• references/HistoricalJobs.md - 历史任务请求格式和范围注意事项
• references/FilterStreams.md - EVM 过滤表达式
• references/ListenToAllAddresses.md - EVM 全地址监控
• references/MonitorMultipleAddresses.md - 地址列表模式
• references/ReplayFailedWebhooks.md - 重放失败的 webhook 交付
• references/ReliabilityAndLifecycle.md - 确认、幂等性、生命周期、速率限制和重组处理
• references/Triggers.md - EVM 只读合约调用增强
• references/Tutorials.md - 实际示例
• references/UsefulStreamOptions.md - 仅适用于 EVM 的高级选项
• references/WebhookResponseBody.md - Webhook 负载结构
• references/WebhookSecurity.md - 签名验证

---

另请参阅

• 端点规则：rules/*.md
• Data API：用于查询历史或当前区块链状态的 @moralis-data-api