web3-dev

Web3 Dev — Blockscout PRO API

このスキルでは、Blockscout PRO API を通じてブロックチェーンデータを読み取るソフトウェア（アプリ、スクリプト、CLI、ボット、モバイル／デスクトップクライアント）を構築する方法をエージェントに教えます。Blockscout PRO API は、100 以上の EVM チェーン（94 以上の L2 およびスケーリングプロジェクト）を網羅する単一の HTTP API です。1 つの API キーですべての対応チェーンを利用でき、呼び出しの chain_id パスパラメーターを変更するだけでチェーンを切り替えられます。

PRO API は、エクスプローラーによって情報が付加されたデータを返します。データはインデックス化、デコード、構造化されており、トークンのメタデータ、プロキシの実装、内部トランザクション、コントラクトのコンテキストなどが含まれます。dApp やウォレット、AI エージェントやボット、分析プラットフォーム、運用ツールに活用できます。

エクスプローラーが事前にインデックス化していないデータ、特に特定のブロックにおけるコントラクトの現在または過去の状態（例：ブロック N におけるトークンコントラクトへの balanceOf(addr)、過去のブロックにおける totalSupply()、任意のビュー関数呼び出し、コントラクトストレージの読み取り）については、PRO API から JSON-RPC ゲートウェイ経由で eth_call も利用できます。コントラクトの状態を読み取るを参照してください。どちらの API も同じ Bearer トークン認証を使用するため、過去のコントラクトデータを読み取る際に別の RPC エンドポイントは必要ありません。

references/ に含まれるファイルが、存在するエンドポイントとその呼び出し方法に関する唯一の信頼できる情報源です。

ファイル	目的
references/pro-api-index.md	OpenAPI タグごとに分類した、すべてのエンドポイントの 1 行の概要です。必ず最初に確認してください。
references/pro-api.json	OpenAPI v3 の完全な仕様です（約 24,000 行）。全体を読まないでください。oastools を使って検索してください。

エンドポイントを独自の「種類」に分類したり、ユーザーを一部のエンドポイントへ誘導したりしないでください。インデックスに記載されたすべてのエンドポイントを呼び出せます。また、すべてのエンドポイントで以下に説明する同じ認証方式を使用します。

API キー — 必須の事前確認

すべての PRO API 呼び出しに PRO API キーが必要です。セッション中に最初のリクエストを送信する前に、以下の事前確認を実行してください。

事前確認（この順番で）

1. エージェントの環境でキーを探します。優先順位は次のとおりです。

   • エクスポート済みの環境変数。デフォルト名は BLOCKSCOUT_PRO_API_KEY です。
   • 成果物に適したプロジェクトローカルのシークレットファイル。Node／Python アプリでは .env、Next.js では .env.local、Android では local.properties、iOS では *.xcconfig または Keychain、一部の Python フレームワークでは secrets.toml、CI シークレットストアなどです。
   • ユーザーが以前にエージェントの保存メモリまたは永続プロファイルに登録したキー（セッションをまたいでエージェントがアクセスできる、保存済みシークレット／設定ストアなど）。

   キーを会話に貼り付けるようユーザーに求めてはいけません。 貼り付けられた値は LLM のトランスクリプトに記録され、プロバイダーのログ、エクスポートされたチャット、スクリーンショット、またはトレーニングコーパスを通じて漏えいする可能性があります。代わりに export または Git の追跡対象外にした .env を使うよう案内してください（手順 5 を参照）。

2. キーを決して捏造したり、推測したりしてはいけません。 エージェントがキーを把握していない場合、作り出したり、トレーニングデータから取得したりしてはいけません。

3. 保存メモリまたは以前のセッションから取得したキーを再利用する前に、確認を取ってください。ユーザーが意図的に保存したキーは正当な情報源ですが、黙って再利用してはいけません。そのキーを使って最初のリクエストを送る前に、エージェントが使おうとしている保存済みキーをユーザーに示し（例：「エージェントのプロファイルに BLOCKSCOUT_PRO_API_KEY として保存されたキーで、末尾 4 文字は …abcd です」）、確認を求めてください。キーの値全体を絶対に表示してはいけません。現在のセッションの環境またはプロジェクトのシークレットファイルで見つかったキーについては、この追加確認は不要です。これらは現在のタスクに使う意図があるものとみなされます。

4. キーが見つかった場合（必要に応じて手順 3 で確認を取ったうえで）、大まかに検証します。proapi_ で始まっている必要があります。そのうえで処理を続けます。

5. どこにもキーが見つからない場合、直ちに停止し、制御をユーザーに戻してください。 これは軽い警告ではなく、強制的に中断するものです。具体的には、エージェントは次のことをしてはいけません。

   • PRO API を呼び出す（または後で呼び出す）コードを書く、あるいは下書きを作成すること。
   • 「キーが届いたら使うスクリプトを用意する」ことや、事前にエンドポイントを調べたり、パラメーターを検討したりすること。
   • 代替データソースや、一時しのぎの外部 RPC URL を提案すること。
   • キーの問題が解決したかのように、仮定上の次の手順を説明すること。

   これは単なる慎重さの問題ではなく、強制的に中断しなければならない理由があります。エージェント自身が調査やデバッグのリクエストを行うためにキーが必要であり、ユーザーが最終的に使うコードのためだけではないからです。 エンドポイントの実際の応答形式を確認するための呼び出し、パラメーターの組み合わせを試して検証すること、以前の呼び出しで予期しないデータが返った理由をデバッグすることは、いずれも計画や反復の過程でエージェントが行う、実際の PRO API 呼び出しです。キーがなければ、こうした探索作業はできません。そのため、そもそもユーザーのコードを確実に設計できません。「今スクリプトを作り、キーが届いたら後で実行する」方法では、実際の API で一度も検証されていないコードができてしまいます。

   簡潔なメッセージを送り、（a）不足しているキーの名前を示し、（b）**https://dev.blockscout.com**（無料プラン、クレジットカード不要）を案内し、（c）貼り付け不要の方法を 2 つ提示してください。1 つは現在のシェルで export BLOCKSCOUT_PRO_API_KEY=proapi_… を実行する方法、もう 1 つはプロジェクトルートの Git 追跡対象外の .env に追加する方法です。キーを会話に貼り付けるようユーザーに求めてはいけません。 そうすると値が LLM のトランスクリプトに記録されます。その後、待機してください。

   • ❌ 誤り：「環境変数に API キーが見つかりません。エンドポイントのパラメーターを確認してスクリプトを作っておきます。キーを入手したら Blockscout PRO API を使ってトークンの転送を処理します。」
   • ✅ 正しい：「Blockscout PRO API キーが見つかりませんでした。https://dev.blockscout.com でキーを作成してください（無料プラン、クレジットカード不要）。その後、このシェルで export BLOCKSCOUT_PRO_API_KEY=proapi_… を実行するか、プロジェクトルートの Git 追跡対象外の .env に追加してください。どちらの方法でも値が会話に表示されることはありません。完了したらお知らせください。」

キーがない場合のオンボーディング手順

ユーザーがキーを持っていない場合は、次の手順を順番に案内してください。

1. https://dev.blockscout.com の開発者ポータルを開き、アカウントを作成します。無料プランではクレジットカードは不要です。

2. ポータルから API キーを生成します。キーのプレフィックスは proapi_… です。1つのアカウントで最大50個のキーを保持でき、ポータルにはリアルタイムの使用状況ダッシュボードが表示されます。

3. ユーザーの具体的な状況に最も適したキーの保存場所を推奨します。押しつけるのではなく提案してください。構築するものに応じて、最も安全で、かつ最も便利な選択肢を選びます。適切な選択肢はケースごとに異なり、固定リストではありません。考え方の例を以下に示します。

   • ユーザーがローカルで実行する一回限りの対話型スクリプト → 現在のセッションでシェル変数としてエクスポートするか、再利用する場合はシェルの rc ファイルに記述します。
   • Node.js、Python、Go のアプリケーションまたは CLI → 起動時に読み込むプロジェクトローカルの .env ファイルに保存し、.env を .gitignore に追加します。
   • バイナリをエンドユーザーに配布するフロントエンド、モバイル、デスクトップアプリ → クライアントにキーを埋め込まないでください。キーを保持するサーバーサイドプロキシ経由でリクエストを送信するか、各エンドユーザーがアプリの設定 UI で自分のキーを入力する方法（OS のキーチェーン／Android Keystore／同等のセキュアストアに保存）を利用します。
   • CI/CD パイプライン → プラットフォームの暗号化されたシークレットストア（GitHub Actions secrets、GitLab CI variables など）を利用します。
   • コンテナ化されたデプロイ → シークレットマネージャー（AWS Secrets Manager、GCP Secret Manager、Vault など）を使い、実行時に注入します。

   デプロイの形態がはっきりしない場合は、保存場所を推奨する前に確認の質問をしてください。コミット済みコードやクライアントとともに配布するバイナリへのキーの埋め込みをユーザーが求めた場合は、安全でないことを伝え、代替案を提案してください。

4. キーを設定したら、元のリクエストをもう一度実行します。

キーの取り扱いルール

以下のルールは、セッションの残りの間、およびこのスキルが生成するすべてのコードサンプルに適用されます。

• キーをログに記録したり、コミットするコードに含めたり、ユーザーがキーを提供した後にキーをそのまま返したりしないでください。
• キーは実行時に必ず間接的に読み込みます。環境変数、シークレットファイル、またはシークレットマネージャーを使います。スクリプトや例にハードコードせず、変数名のみを参照してください（例：process.env.BLOCKSCOUT_PRO_API_KEY、os.environ["BLOCKSCOUT_PRO_API_KEY"]）。
• .env（または同等のシークレットファイル）を作成または変更する場合は、そのファイルが gitignore されていることを確認し、されていない場合はユーザーに警告してください。
• HTTP 401／403 の応答は、キーが無効、未設定、または取り消されていることを示すものとして扱います。処理を停止してユーザーに失敗を伝え、上記のオンボーディング手順を再度実行してください。
• 注意を促したにもかかわらず、ユーザーがキーを会話に貼り付けた場合は、現在のセッションではそのキーを受け付けます。ただし、その値が会話の記録に残っていることを警告し、セッション終了後にキーをローテーションし、次回から export／.env を使用するよう推奨してください。

ベース URL と URL の構築

ベース URL は https://api.blockscout.com です。API バージョンのプレフィックスや、暗黙的に付加されるパス要素はありません。OpenAPI 仕様に記載された各操作のパスはすべて、このベース URL からの相対パスです。

完全な URL は、ベース URL に references/pro-api-index.md に記載された操作のパス文字列をそのまま連結して構築します（このパス文字列は references/pro-api.json からそのまま取得されています）。連結後、{chain_id}、{transaction_hash_param}、{address_hash_param} などの {templated} セグメントを実際の値に置き換え、操作の parameters スキーマに従ってクエリパラメーターを追加します。

構築例。インデックスには次のように記載されています。

GET /{chain_id}/api/v2/blocks/{block_number_or_hash}

チェーンが 1（Ethereum メインネット）、ブロックが 10000000 の場合、最終的な URL は次のとおりです。

https://api.blockscout.com  +  /1/api/v2/blocks/10000000
=  https://api.blockscout.com/1/api/v2/blocks/10000000

パス構築に関する厳守事項 — よくある統合時のバグを防ぐためのルールです。

• インデックスに記載されたパスをそのまま使用してください。 パスを推測で作成したり、プレフィックスを付けたり、書き換えたり、順序を入れ替えたりしないでください。具体的には、余分な /api/v2 プレフィックスを挿入しないでください。ホストをパスに組み込んだり、{chain_id} を別の位置に移動したりしないでください。
• oastools walk parameters を使ってエンドポイントの parameters 定義を確認し、{templated} セグメントとクエリパラメーターを解決してください。詳しくは、以下のエンドポイントの詳細を確認するを参照してください。どのパラメーターがパスのテンプレートで、どれがクエリで、どれが必須かについては、OpenAPI 仕様が正となります。

認証

PRO API のすべてのエンドポイントで使用する認証方式は 1 つだけです。API キーを Bearer トークンとして Authorization リクエストヘッダーに送信します。

curl --request GET \
  --url 'https://api.blockscout.com/1/api/v2/blocks/10000000' \
  --header "Authorization: Bearer ${BLOCKSCOUT_PRO_API_KEY}"

厳守事項：

• 認証には必ず Authorization: Bearer proapi_… を使用してください。スキルが使用する認証方式はこれだけです。
• キーをログに記録したり、リポジトリにコミットするコードスニペットに埋め込んだり、応答としてそのまま返したりしないでください。実行時に環境変数や同等のシークレットストアから読み込み、変数名で参照してください。

必須リクエストヘッダー（認証以外）

PRO API は CDN の背後で提供されています。すべてのリクエストで User-Agent: <name>/<version>（例：my-wallet-app/1.4.2）と Accept: application/json を設定してください。Python urllib の Python-urllib/3.x、プレーンな Java HttpURLConnection、クライアントを設定していない単純な Go net/http など、HTTP ライブラリのデフォルト設定のままでは CDN のエッジでブロックされることがあります。高水準クライアント（requests、httpx、fetch、undici、OkHttp など）なら通常は通過しますが、両方のヘッダーを明示的に設定しておくと、移植性が高まり CDN によるブロックにも強くなります。

curl では動作するのに、同じ URL へのスクリプトからのリクエストで 403（多くの場合、本文に Cloudflare の 1010 ページが含まれますが、本文が空、または接続がリセットされることもあります）が返る場合、リクエストは API に到達していません。原因は認証情報ではなくヘッダーです。オンボーディングフローをやり直しても解決しません。

エンドポイントの検索 — references/pro-api-index.md

インデックスでは、すべてのエンドポイントが OpenAPI のタグ（addresses、blocks、transactions、tokens、optimism／arbitrum／zkevm などのチェーン固有グループ、legacy など）ごとに分類されています。各項目は次の形式です。

<METHOD> <path>: <short description>

ワークフロー：

1. ユーザーのデータ要件に合うエンドポイント候補を選ぶため、まず必ず references/pro-api-index.md を確認してください。関連するタグをざっと確認してください。1 つのデータ要件に、名前が似ている複数のエンドポイントが対応することがよくありますが、1 行の説明だけで通常は適切なものを選べます。
2. OpenAPI 仕様を参照する際は、インデックスに記載されたパス文字列をそのまま使用してください。これは、以下の oastools の -path フラグに渡す値と同じです。

インデックスに記載されたすべてのエンドポイントは呼び出し可能で、同じ認証方式を使用します。legacy タグのエンドポイントも例外ではありません。タグ名を理由に、特定のエンドポイント群をユーザーに勧めたり、避けるよう案内したりしないでください。データ要件に合った説明のエンドポイントを選んでください。

派生した一連の呼び出しより、直接利用できるエンドポイントを優先する

複数ステップのデータ取得ロジックを書く前に、インデックスを（レガシーの項目も含めて）調べ、質問に直接答える単一の専用エンドポイントがないか確認してください。これは厳守すべきルールです。直接利用できるエンドポイントがあるのに派生した呼び出しを連鎖させると、クレジットを無駄にし、レイテンシーが増え、オフバイワンのバグを招きます。

例：Unix タイムスタンプ T をブロック番号に変換する場合、/api/v2/blocks/{block_hash_or_number_param} に対して二分探索を行ってはいけません。インデックスには、すでに専用エンドポイントがあります。

GET /{chain_id}/api/legacy/block/get-block-number-by-time
# Etherscan-compatible form:
GET /{chain_id}/api?module=block&action=getblocknobytime&timestamp=<T>&closest=before

一般化すると、リクエストが「X を取得し、Y を導出し、Z を集約する」と分解できる場合、呼び出しを連鎖させる前に、Y または Z を直接返すエンドポイントを探してください。

インデックスの制限 — コントラクト状態に関するリクエストを見分ける。 インデックスに掲載されているのは、エクスプローラーがインデックス化したデータを返すエンドポイントです。特定のブロックにおける任意のコントラクト状態（過去の balanceOf、totalSupply、view 関数の呼び出し、コントラクトストレージの読み取り）に対応するエンドポイントは掲載されていません。これらはJSON-RPC ゲートウェイの eth_call を通じて実行します。Bearer 認証とクレジットの計上方法は同じです。「インデックスに該当するものがない」と判断する前、また外部 RPC URL の利用を検討する前に、このケースを見分けてください。外部 RPC URL は必要ありません。

詳細な説明による候補の絞り込み

インデックスの概要だけでは候補を判別できない場合は、諦める前に、該当しそうな候補を絞り込み、各操作の詳細な説明を読んでください。OpenAPI の説明には、インデックスの概要では省略されている、受け付ける入力、レスポンスに含まれるフィールド、対応するチェーンの種類が通常記載されています。エンドポイントの詳細の確認にある oastools walk operations コマンドを使用してください。この手順を尽くした後に限り、ユーザーに該当なしと伝えてください。その場合でも、サードパーティのデータソースに黙って置き換えてはいけません。

エンドポイントの詳細の確認 — oastools を使用して references/pro-api.json を調べる

OpenAPI ドキュメントは大規模です（約 24,000 行）。pro-api.json 全体を読んではいけません。コンテキストを使い果たすうえ、インデックスですでに要約されている以上の情報は得られません。代わりに、jq と組み合わせて oastools で検索してください。

ツール

このスキルは、oastools がローカルにインストールされている場合に最も効果的に機能します。インストール方法（Homebrew、ビルド済みバイナリ、go install など）は https://github.com/erraggy/oastools/blob/main/README.md に記載されています。jq も必要です。

oastools がインストールされていない場合は、エンドポイントの詳細を調べる前にインストールするよう勧めてください。代わりに pro-api.json を grep で検索する方法は不安定で、$ref の間接参照を見落としがちです。

フラグの表記。 フラグにはすべて単一ハイフンを使用してください。-detail、-format、-method、-path、-name、-status です。Go の flag パッケージは -x と --x の両方を受け付けますが、oastools のヘルプでは単一ハイフン表記が使われているため、この標準形を使用してください。

標準コマンド

以下のコマンドは、作業ディレクトリがスキルディレクトリであることを前提としています。それ以外の場合は、pro-api.json への適切な相対パスに置き換えてください。

• エンドポイントの操作の詳細説明：

  oastools walk operations -detail -format json -path '<PATH>' references/pro-api.json \
    | jq '.operation.description'
  

• エンドポイントのパラメーター仕様（不要な path キーを除外）：

  oastools walk parameters -detail -format json -method get -path '<PATH>' references/pro-api.json \
    | jq 'del(.path)'
  

• 成功時（HTTP 200）のレスポンス形式：

  oastools walk responses -status 200 -detail -format json -method get -path '<PATH>' references/pro-api.json \
    | jq 'del(.path)'
  

• 名前でスキーマを検索 — $ref ポインターをたどる際に使用します。スキーマ名は $ref の値の最後の部分です（例：#/components/schemas/Log の場合は Log）：

  oastools walk schemas -detail -format json -name <SCHEMA_NAME> references/pro-api.json \
    | jq 'del(.jsonPath)'
  

<PATH> はインデックスに記載されているパス文字列をそのまま使用し、{templated} の部分も含めてください。シェルが波括弧を解釈しないよう、単一引用符で囲んでください。

コンテキスト効率を高めるトラバーサルのルール

これらのルールが重要な理由：一部のエンドポイントには非常に深いスキーマ依存関係ツリーがあり、すべてを一度に解決すると、数百 KB のデータがエージェントのコンテキストに出力され、実際のタスクに使える余地がなくなることがあります。

1. oastools walk parameters、oastools walk responses、または oastools walk schemas に -resolve-refs を渡さないでください。$ref を先行して解決することは、この API でコンテキストの予算を超過する最も一般的な原因です。
2. エンドポイントを呼び出す前に、必ず parameters を確認してください。これは必須です。どのパラメーターがパステンプレートで指定されているか、どれがクエリーであるか、どれが必須であるか、また受け付ける値は何かを把握する唯一の確実な方法です。
3. レスポンススキーマ全体を必ず確認する必要はありません。レスポンスから必要なフィールドが少数だけの場合は、段階的なトラバーサルを優先してください。まず最上位のレスポンススキーマを読み、次に対象フィールドに必要な $ref だけを、対象ごとに oastools walk schemas -name <SCHEMA_NAME> を呼び出してたどります。これにより、コンテキストの使用量を一定範囲内に抑え、スクリプトやアプリが実際に使用する内容に近づけることができます。
4. スキーマツリー全体の確認は、型付きクライアントモデルの構築、バインディングの生成、包括的なドキュメントの作成など、タスクで本当に必要な場合に限ってください。その場合は、参照されているすべてのスキーマを順にたどっても問題ありません。

API の呼び出し

最小限の curl 呼び出しは次のとおりです。

curl --request GET \
  --url 'https://api.blockscout.com/1/api/v2/transactions/0xabc…/logs' \
  --header "Authorization: Bearer ${BLOCKSCOUT_PRO_API_KEY}"

正確なパス、{chain_id} の位置、パステンプレートで指定されるセグメント、およびクエリー文字列となるパラメーターは、references/pro-api-index.md（パスの確認用）と references/pro-api.json（パラメーターの詳細用）で確認してください。インデックスと仕様に記載されている内容を超えて、パスの形式を一般化しないでください。

chain_id の解決

ほとんどの PRO API エンドポイントでは、数値の chain_id が必要です。対応しているチェーン ID の一覧は、次の場所で公開されています。

GET https://api.blockscout.com/api/json/config        (no API key required)

この同じレスポンスには、呼び出しごとのクレジットコスト表も含まれています。次のような場合に、このエンドポイントを照会してください。

• ユーザーがシンボルまたは名前（例：「Optimism」、「Base」、「Polygon zkEVM」）でチェーンを指定し、その数値のチェーン ID が必要な場合。
• 対象チェーンを指定したコードを書く前に、そのチェーンが PRO API に対応していることを確認する必要がある場合。
• コストを見積もる場合。このエンドポイントの呼び出しごとのコスト表と、予想される呼び出し回数を組み合わせてください。

x-credits-remaining の読み取り

すべての PRO API レスポンスには、請求後のアカウントの残りクレジットを示す x-credits-remaining レスポンスヘッダーが含まれています（呼び出しの請求後）。バッチスクリプト、インデクサー、cron ジョブなど、多数の呼び出しを行うコードでは、次の点に注意してください。

• 各レスポンスから x-credits-remaining を読み取ってください。 残りのクレジットでは予定していたバッチの残りをまかなえなくなった場合や、長時間のジョブの終了後に消費量を確認する場合など、重要な閾値に達したらユーザーに知らせてください。
• バッチスクリプトでは、x-credits-remaining がゼロ、または急速に減少している場合は停止条件として扱ってください。 日次の上限に達して呼び出しが失敗し始めるまで続けるよりも、明確なメッセージを表示して適切に停止するほうが望ましいです。

レスポンスの冗長性の管理

PRO API のレスポンスはエクスプローラーによって情報が拡充されており、数百 KB に達することがあります。1 件のトランザクションのログ、情報が拡充されたアドレスページ、ページ分割されたトークン送金一覧などがその例です。生のレスポンスをそのままエージェントに読み込ませると、コンテキストウィンドウを使い切ってしまいます。そのため、pro-api.json に適用するのと同じ「全体を読み込まず、必要な範囲だけを取り出す」方針を適用してください。次の 2 つの方法があります。

• 必要なデータがわかっている場合 → curl の出力を jq に渡し、タスクを満たす最小限の項目だけを取り出します。例：curl … | jq '{n: .height, t: .timestamp}'。不要な大きなフィールド（デコード済み calldata、NFT メタデータ、生の入力バイト列など）は除外してください。
• なじみのないレスポンスを調査またはデバッグしている場合 → まず oastools walk responses で スキーマ を確認する（クレジット消費なし、取得量に上限あり）か、curl -o /tmp/r.json でレスポンスをディスクに保存し、wc -c r.json、jq 'keys'、jq '.items[0] | keys'、head -c 1000 などで調べます。ファイルに対して cat を実行したり、全体を読み込んだりしないでください。ディスクに保存しておけば、再取得せずに再調査できますが、予算に関するルールは変わりません。会話に渡すのは、範囲を絞ったデータだけにしてください。

コントラクトの状態を読み取る — JSON-RPC ゲートウェイ経由の eth_call

PRO API の OpenAPI 仕様では、エクスプローラーがすでにインデックス化したデータを扱います。コントラクト読み取りメソッドは定義されていません。ライブのコントラクト状態を読み取るには、PRO API が次の JSON-RPC ゲートウェイを提供しています。

POST https://api.blockscout.com/{chain_id}/json-rpc

このゲートウェイでは eth_call を利用でき、他のすべての PRO API 呼び出しと同じ Authorization: Bearer … ヘッダーを使用します。クレジットの計上、レート制限、キーの取り扱いもすべて同じように適用されます。

例：

curl --request POST \
  --url 'https://api.blockscout.com/1/json-rpc' \
  --header "Authorization: Bearer ${BLOCKSCOUT_PRO_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"eth_call",
    "params":[{"to":"0x…","data":"0x…"}, "latest"]
  }'

エクスプローラーがすでにインデックス化しているデータ（残高、トークン保有状況、トランザクション、ログ、デコード済みイベント、コントラクトのメタデータ、NFT の保有一覧、アカウント抽象化オブジェクトなど）には、インデックスの対応する REST エンドポイントを使用してください。同じデータを RPC の基本機能から組み立てるより、インデックス化された REST パスのほうが常に効率的です。

ページネーション

PRO API の多くの一覧エンドポイントはページネーションに対応しています。transactions、logs、token-transfers、holders、NFT の保有一覧、ブロック一覧などのエンドポイントは、一般に一度に 1 ページを返します。各エンドポイントで使用される正確なカーソル方式は OpenAPI 仕様が正式な情報源です。一度の呼び出しですべてのデータが返ると想定しないでください。

一覧を取得するコードを書く前に、oastools walk responses でエンドポイントのレスポンススキーマを確認し、カーソルフィールド（通常は next_page_params）を探してください。そのうえで、次のように処理します。

• 後続の呼び出しでは、カーソルをクエリパラメーターとして渡します。
• カーソルが空になるか、レスポンスが次のページがないことを示すまで、またはユーザーのリクエストに必要なデータが集まるまで、ループします。
• 大規模な履歴をたどるバッチジョブ（ウォレットの全トランザクション履歴、トークンの保有者一覧、日付範囲を指定したコントラクトログなど）では、明示的にページネーションを行ってください。ループ全体を通して x-credits-remaining とプランの RPS 制限が適用されます。

一覧形式のレスポンスにカーソルフィールドがない場合は、単一のレスポンスを完全な一覧として扱ってください。

変更検出のためのポーリング（ボット、監視ツール、インデクサー）

PRO API はリクエスト／レスポンスのみで、Webhook、WebSocket、プッシュチャネルはありません。「新しい X を監視する」ユースケース（アドレスの新しいトランザクション、新しいブロック、新しいコントラクトイベント、残高の変更）では、ポーリングループを構築してください。

• 実行間隔 — プランの RPS 制限を十分に下回る間隔でポーリングしてください。単一の監視ツールであれば、無料プランでは数秒ごとに 1 回のリクエストで通常は問題ありません。同じプロセスで複数の監視ツールを実行する場合は、トークンバケットを共有して、合計 RPS がプランの制限を超えないようにしてください。
• ハイウォーターマーク — 反復処理の間で最後に確認したマーカーを保持してください。マーカーには、最新のブロック番号、最新のトランザクションハッシュ、最新のログインデックスなどがあります。各実行では、マーカーより新しいものだけを取得してください。
• 欠落期間中のカーソル — 監視ツールがオフラインの間に多くの新しい項目が蓄積した場合は、すべてを再取得するのではなく、最後に確認したマーカーから順にページネーションしてください。
• クレジット予算 — ポーリング監視ツールは継続的にクレジットを消費します。/api/json/config を使って、1 日あたりのクレジット使用量（requests_per_day × per-call credits）を事前に見積もり、プランの範囲内に収まるポーリング間隔を選んでください。

プラン、クレジット、コストの見積もり

2 つの認証不要エンドポイントで、最新の課金スキーマを確認できます。料金体系や呼び出しごとのクレジットコストは変更されるため、ハードコードされた数値ではなく、これらのエンドポイントを優先してください。

URL	返される内容	認証
https://api.blockscout.com/api/json/plans	すべてのプランと、1 日あたりのクレジット上限／レート制限	不要
https://api.blockscout.com/api/json/config	エンドポイントごとのクレジットコスト表および対応チェーン ID の一覧	不要

背景情報として、公開ドキュメントでは現在、以下のプランが案内されています。数値はある時点のスナップショットとして扱い、最新の確定値は /api/json/plans を照会して確認してください。

プラン	1 日あたりのクレジット	レート制限	価格
Free	100,000	5 RPS	$0
Standard	100,000,000	15 RPS	$49/mo
Professional	500,000,000	30 RPS	$199/mo
Enterprise	Custom	Custom	Custom

ユーザーから料金、プランの制限、またはスクリプトの実行コストについて質問された場合は、以下の手順に従ってください。

1. /api/json/plans と /api/json/config を呼び出し（API キーは不要）、最新の値を報告します。
2. 対象となる各エンドポイントについて、スクリプトで想定される呼び出し回数に /api/json/config の呼び出しごとのクレジットコストを掛けて、コストを見積もります。該当する場合は、クレジット数と、それに相当するプランの両方を示してください。

レート制限と HTTP エラー

プランごとにRPS 制限があります（/api/json/plans を参照）。スクリプトでは、それに応じてリクエストを調整してください。ステータスごとの標準的な処理は以下のとおりです。

ステータス	意味	処理
200	成功	レスポンスボディと x-credits-remaining ヘッダーを読み取ります。
401 / 403（PRO API の JSON ボディ）	API キーが無効または未指定	停止します。明確に通知してください。再試行しないでください。オンボーディングフローを再実行してください。
403（Cloudflare の HTML ボディ、error code: 1010、または「curl では動作するがスクリプトでは失敗する」場合）	CDN エッジによるブロック — リクエストは API に到達していません	User-Agent と Accept ヘッダーを設定してください。認証の問題ではありません。
402（またはクレジット枯渇を示すボディ）	1 日あたりのクレジット上限を超過	停止して報告します。プランのアップグレード、または日次リセットまで待つことを提案してください。
429	レート制限に到達	指数バックオフで待機時間を延ばしてから再試行します。短い間隔でループ再試行しないでください。
5xx	一時的なサーバーエラー	最大試行回数を設定し、バックオフして再試行します。

まとめ — 推奨ワークフロー

ユーザーが説明したデータニーズごとに、次の手順に従います。

1. このセッションで初めて PRO API を呼び出す場合は、API キーを事前確認します（API キー — 必須の事前確認を参照）。
2. ユーザーがチェーンをシンボル名または名前で指定した場合は、対象のチェーン ID を解決します — /api/json/config をクエリします。
3. リクエストを適切な方法に振り分けます。 データニーズに応える方法を判断します。
   • エクスプローラーにインデックスされたデータ（トランザクション、残高、ブロック、ログ、トークン、NFT、デコード済みイベント、コントラクトのメタデータ、アカウント抽象化オブジェクトなど）→ references/pro-api-index.md の REST エンドポイント。手順 4～6 に進みます。
   • 特定のブロックにおけるコントラクトのライブまたは過去の状態（ブロック N における balanceOf(addr)、過去のブロックにおける totalSupply()、あらゆるビュー関数、コントラクトストレージの読み取り）→ JSON-RPC ゲートウェイ経由の eth_call。手順 7 に進みます。別の RPC エンドポイントを導入しないでください — ゲートウェイは PRO API の一部であり、同じ Bearer 認証を使用します。
4. references/pro-api-index.md で REST エンドポイントを見つけます。パス文字列をそのままコピーします。
5. oastools walk parameters で エンドポイントのパラメーターを確認します。https://api.blockscout.com にパス文字列を連結し、{templated} セグメントを置き換えて URL を組み立てます。レスポンススキーマの確認はタスクに必要な深さにとどめます — トップレベルの構造には oastools walk responses を使い、実際に使用するフィールドについては、特定の $ref をたどって oastools walk schemas -name <SCHEMA_NAME> を使います。
6. Authorization: Bearer ${BLOCKSCOUT_PRO_API_KEY}、意味のある User-Agent、Accept: application/json（必須リクエストヘッダーを参照）、および必要なクエリパラメーターを指定して エンドポイントを呼び出します。レスポンスから x-credits-remaining を読み取り、レスポンス本文は必要な範囲に絞り込みます（レスポンスの冗長性への対処を参照） — 全体をそのまま出力しないでください。
7. eth_call リクエストの場合： 同じ Bearer 認証と JSON-RPC ボディを使って、https://api.blockscout.com/{chain_id}/json-rpc に POST します — コントラクト状態の読み取りを参照してください。
8. 長時間実行またはバッチ処理の場合、 意味のあるチェックポイントで x-credits-remaining をユーザーに提示し、プランの RPS 上限を超えないようにリクエストを調整し、クレジットが少なくなったら適切に停止します。