moralis-streams-api

重要：実装前にルールファイルを読む

バグの最大の原因は、誤った HTTP メソッドやストリーム設定を使用することです。

すべてのエンドポイントについて、次の手順を実施してください。

1. rules/{EndpointName}.md を読む
2. HTTP メソッドを確認する（作成は PUT、更新は POST、削除は DELETE）
3. ストリーム ID の形式を確認する（16 進数ではなく UUID）
4. 名前（eth、polygon）ではなく、16 進数のチェーン ID（0x1、0x89）を使用する

読む順序：

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. 設定されていない場合は、空のプレースホルダー MORALIS_API_KEY= を含む .env ファイルの作成を提案します。
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（必ず 16 進数）

"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 が誤っている - deep-index.moralis.io ではなく、api.moralis-streams.com を使用してください
3. 16 進数のストリーム ID - 16 進数ではなく、UUID 形式である必要があります
4. チェーン名を文字列で指定する - 名前（eth）ではなく、16 進数（0x1）を使用してください
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 を参照してください。

---

配信とエラーハンドリング

• イベントごとに2つのWebhook：未確定（confirmed: false）と確定済み（confirmed: true）が送信されます。冪等性のあるハンドラーが必要です。
• エラー状態（Webhook 成功率が70％未満）が24時間続くと、ストリームは自動的に終了します。これは復旧できません。新しいストリームを作成する必要があります。
• テスト用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" であることを確認する

---

エンドポイント一覧

カテゴリ別に整理した、Streams API の全20エンドポイントの一覧です。

ストリーム管理

ストリームの作成、更新、削除、管理を行います。

エンドポイント	説明
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 - 少なくとも1回の配信、デュアル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ペイロードの構造
• references/WebhookSecurity.md - 署名検証

---

関連項目

• エンドポイントのルール：rules/*.mdファイル
• Data API：ブロックチェーンの状態を照会する@moralis-data-api