web3-dev

Web3 开发 — Blockscout PRO API

本技能教会 Agent 如何构建通过 Blockscout PRO API 读取区块链数据的软件（应用、脚本、CLI、机器人、移动端／桌面端客户端）。这是一个 HTTP API，覆盖 100 多条 EVM 链（94 条以上的 L2 和扩容项目）。一个 API 密钥即可用于所有受支持的链；只需更改调用中的 chain_id 路径参数即可切换链。

PRO API 返回经区块浏览器丰富的数据：经过索引、解码和结构化的数据，包括代币元数据、代理合约实现、内部交易、合约上下文等。可用于 dApp 和钱包、AI Agent 和机器人、分析平台以及运维工具。

对于区块浏览器尚未预先索引的数据，尤其是特定区块的实时或历史合约状态（例如，在区块 N 读取代币合约上的 balanceOf(addr)、读取过去区块的 totalSupply()、调用任意视图函数、读取合约存储），PRO API 还可通过 JSON-RPC 网关提供 eth_call。请参阅读取合约状态。同一 Bearer 令牌身份验证适用于这两种接口；读取历史合约数据无需单独的 RPC 端点。

references/ 中的文件是唯一可信来源，用于了解有哪些端点以及如何调用：

文件	用途
references/pro-api-index.md	按 OpenAPI 标签分组的每个端点的一行摘要。始终从这里开始。
references/pro-api.json	完整的 OpenAPI v3 规范（约 24,000 行）。不要完整读取——请使用 oastools 查询。

不要将端点归类到自定义的“类别”中，也不要引导用户只使用其中一部分。索引中列出的每个端点都可以调用，并且都使用下文所述的同一种身份验证方案。

API 密钥 — 必须先完成的准备工作

每次调用 PRO API 都必须使用 PRO API 密钥。在会话中发出第一个请求前，请执行以下准备工作。

预检（按此顺序）

1. 按以下优先顺序，在 Agent 的环境中查找密钥：

   • 已导出的环境变量，默认名称为 BLOCKSCOUT_PRO_API_KEY。
   • 适用于该项目的本地机密文件：Node/Python 应用使用 .env，Next.js 使用 .env.local，Android 使用 local.properties，iOS 使用 *.xcconfig 或 Keychain，某些 Python 框架使用 secrets.toml，以及 CI 机密存储等。
   • 用户先前放入 Agent 已存储记忆或持久配置文件中的密钥（例如，Agent 可跨会话访问的已保存机密/偏好设置存储）。

   不要要求用户将密钥粘贴到对话中。 粘贴的值会进入大模型的对话记录，并可能通过服务提供商日志、导出的聊天记录、屏幕截图或训练语料泄露。引导用户改用 export 或被 git 忽略的 .env（见第 5 步）。

2. 绝不要编造或猜测密钥。 如果 Agent 没有密钥记录，就不要伪造密钥或从训练数据中提取密钥。

3. 重复使用存储记忆或之前会话中的密钥前，必须先确认。 用户有意保存的密钥是合法来源，但不能在未告知的情况下重复使用。首次使用此类密钥发送请求前，向用户说明 Agent 打算使用的是哪一个已存储密钥（例如：“Agent 配置文件中保存为 BLOCKSCOUT_PRO_API_KEY 的密钥，末尾 4 个字符为 …abcd”），并征求确认。绝不要回显完整密钥。当前会话的环境变量或项目机密文件中找到的密钥不需要额外确认，因为它们本就代表用户有意为当前任务提供。

4. 如果找到密钥（且在第 3 步要求时已获得确认），进行宽松校验——密钥应以 proapi_ 开头——然后继续。

5. 如果任何地方都找不到密钥，立即停止并将控制权交还给用户。 这是强制中断，不是一般警告。具体来说，Agent 不得：

   • 编写或构思会调用（或最终会调用）PRO API 的代码；
   • “先准备好脚本，等密钥到位后再运行”，也不得预先检查端点或遍历参数；
   • 提议使用其他数据源或外部 RPC URL 权宜替代；
   • 像密钥问题已解决一样叙述假设性的后续步骤。

   之所以必须强制中断，而不只是出于规范要求，是因为Agent 需要密钥来进行自己的研究和调试调用，而不仅仅是为了用户最终编写的代码。在规划和迭代过程中，探测端点以确认实际响应结构、尝试验证一组参数组合，以及调试先前调用为何返回意外数据，都属于 Agent 发起的实时 PRO API 调用。没有密钥，Agent 就无法进行这些探索工作，因此也无法可靠地设计用户的代码。“先编写脚本，等密钥到位后再运行”会导致代码从未经过真实 API 验证。

   发送一条简短消息，其中：(a) 指明缺少的密钥；(b) 引导用户访问 **https://dev.blockscout.com**（免费层级，无需信用卡）；(c) 提供两种无需粘贴密钥的方式：在当前 Shell 中运行 export BLOCKSCOUT_PRO_API_KEY=proapi_…，或将密钥添加到项目根目录中被 git 忽略的 .env 文件。不要要求用户将密钥粘贴到对话中——那会使密钥进入大模型的对话记录。然后等待。

   • ❌ 错误：“在环境中没有找到 API 密钥。我来检查端点参数并编写脚本——密钥可用后，它就会使用 Blockscout PRO API 获取代币转账数据。”
   • ✅ 正确：“我没有找到 Blockscout PRO API 密钥。请在 https://dev.blockscout.com 生成一个（免费层级，无需信用卡），然后在此 Shell 中运行 export BLOCKSCOUT_PRO_API_KEY=proapi_…，或将密钥添加到项目根目录中被 git 忽略的 .env 文件。无论采用哪种方式，密钥都不会出现在我们的对话中。完成后告诉我。”

缺少密钥时的入门说明

当用户没有密钥时，按顺序提供以下步骤：

1. 打开开发者门户 https://dev.blockscout.com 并创建账户。免费套餐无需提供信用卡。

2. 在门户中生成 API 密钥。密钥以 proapi_… 为前缀。一个账户最多可持有 50 个密钥，门户还会显示实时用量仪表板。

3. 根据用户的具体情况，推荐最合适的密钥存储位置。提出建议，而非强制要求——根据用户正在构建的内容，选择最安全且最方便的选项。正确选择因情况而异，并非固定清单。思考时可参考以下示例：

   • 用户在本地运行的一次性交互式脚本 → 在当前会话中导出 shell 变量，或者如果之后会重复使用，则将其添加到 shell 配置文件中。
   • Node.js、Python 或 Go 应用或 CLI → 在应用启动时加载项目本地的 .env 文件，并将 .env 添加到 .gitignore。
   • 可将二进制文件分发给最终用户的前端、移动端或桌面应用 → 绝不要将密钥嵌入客户端。可以通过持有密钥的服务端代理转发请求，也可以让每位最终用户通过应用的设置界面提供自己的密钥（并将其存储在 OS Keychain / 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（或同等密钥文件），请确保该文件已被 git 忽略；如果没有，请提醒用户。
• 将 HTTP 401/403 响应视为密钥无效、缺失或已撤销的信号——停止操作，向用户说明失败情况，并重新执行上述入门流程。
• 如果用户不听建议，仍在对话中粘贴密钥，请在本次会话中接受该密钥，但要提醒用户该值现已出现在对话记录中，并建议他们在会话结束后轮换密钥，下次改用 export/.env。

基础 URL 和 URL 构造

基础 URL 为 https://api.blockscout.com。没有 API 版本前缀或其他隐式路径组件——OpenAPI 规范中的每个操作路径都相对于此基础 URL。

将基础 URL 与从 references/pro-api-index.md 中逐字获取的操作路径字符串拼接，即可构造完整 URL（该文件中的路径又是从 references/pro-api.json 中逐字获取的）。拼接后，将任何 {templated} 片段（例如 {chain_id}、{transaction_hash_param}、{address_hash_param}）替换为实际值，然后追加操作 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 的所有端点都使用同一种身份验证方案：API 密钥作为 Bearer token 发送到 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。直接使用 HTTP 库的默认设置——例如 Python urllib 的 Python-urllib/3.x、原生 Java HttpURLConnection、未配置客户端的临时 Go net/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，根据用户的数据需求选择候选端点。浏览相关标签；单一数据需求通常对应多个名称相似的端点，而一行描述通常足以选出合适的端点。
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、视图函数调用、合约存储读取。这些请求应通过 JSON-RPC 网关上的 eth_call 执行——使用相同的 Bearer 身份验证，并按相同规则计费。应在宣称“索引中没有匹配项”以及考虑使用外部 RPC URL 之前识别这种情况：无需使用外部 RPC URL。

使用完整描述区分候选项

当索引中的单行摘要存在歧义时，不要轻易放弃；应先筛选出可能的候选项，并查看其完整操作描述。OpenAPI 描述通常会明确说明索引摘要中未提及的可接受输入、已填充的响应字段以及适用的链类型。使用端点详细信息查询中的 oastools walk operations 命令。只有完成这一步后，才能告知用户没有匹配项；即便如此，也不要悄悄改用第三方数据源。

端点详细信息查询——通过 oastools 查询 references/pro-api.json

OpenAPI 文档很大（约 24,000 行）。切勿完整读取 pro-api.json——这会耗尽上下文，而且不会提供索引摘要中没有的信息。应改用 oastools，并通过 jq 处理结果。

工具

本技能在本地安装了 oastools 时效果最佳。安装选项（Homebrew、预编译二进制文件、go install 等）见 https://github.com/erraggy/oastools/blob/main/README.md。还需要 jq。

如果尚未安装 oastools，建议在查询端点详细信息前安装；改用 grep 搜索 pro-api.json 的方式并不可靠，而且容易漏掉 $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} 片段。请用单引号将其括起来，避免 shell 解释其中的大括号。

高效利用上下文的遍历规则

这些规则很重要：某些端点的架构依赖树非常深，一次性解析所有内容可能会向 Agent 的上下文中倾倒数百 KB 的内容，让实际任务无处容身。

1. 调用 oastools walk parameters、oastools walk responses 或 oastools walk schemas 时，不要传入 -resolve-refs。 急切地解析 $ref 是导致此 API 的上下文预算超限最常见的原因。
2. 调用端点前，务必先检查 parameters。 这条不可妥协——这是了解哪些参数采用路径模板、哪些是查询参数、哪些为必填项，以及它们接受哪些值的唯一可靠方式。
3. 不要总是检查完整的响应架构。 如果任务只需要响应中的少数字段，优先采用增量遍历：先读取顶层响应架构，然后针对目标字段，仅通过为每个架构调用 oastools walk schemas -name <SCHEMA_NAME> 来跟进所需的 $ref。这样能控制上下文用量，并紧密贴合脚本或应用实际使用的内容。
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——例如单笔交易的日志、经过增强的地址页面，或分页的代币转账列表。将原始响应直接输出供 Agent 阅读会耗尽上下文窗口，因此请像处理 pro-api.json 一样，遵循“不要通读全文，只提取所需内容”的原则。两种做法：

• 明确需要什么 → 使用 jq 将 curl 输出管道传入，并采用满足任务所需的最小投影：curl … | jq '{n: .height, t: .timestamp}'。去掉不需要的繁重字段（已解码的 calldata、NFT 元数据、原始输入字节）。
• 正在探索或调试不熟悉的响应 → 先用 oastools walk responses 检查 schema（不消耗额度，且有界），或者用 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 库存、区块列表以及类似端点通常一次只返回一页。每个端点具体使用的游标机制以 OpenAPI 规范为准；不要假设一次调用就能返回所有内容。

编写获取列表的代码前，请使用 oastools walk responses 检查端点的响应 schema，并查找游标字段（通常为 next_page_params）。然后：

• 在后续调用中将游标作为查询参数传回。
• 循环请求，直到游标为空／响应表明没有更多页面，或者已收集到满足用户请求所需的数据。
• 对于需要遍历大量历史数据的批处理任务（例如某个钱包的完整交易历史、某种代币的持有者集合，或某个日期范围内的合约日志），请明确处理分页——整个循环仍受 x-credits-remaining 和套餐 RPS 限制约束。

如果列表形式的响应完全没有游标字段，则将单次响应视为完整结果集。

轮询以检测变更（机器人、监控器、索引器）

PRO API 仅支持请求/响应，不提供 webhook、websocket 或推送通道。对于“监视新的 X”这类用例（某个地址上的新交易、新区块、新合约事件、余额变更），请构建轮询循环：

• 轮询间隔 — 轮询间隔应明显短于套餐的 RPS 限制。对于单个监视器，免费套餐每隔几秒发送 1 个请求通常没问题；同一进程中的多个监视器应共用一个令牌桶，确保总 RPS 不超过套餐限制。
• 高水位标记 — 在每次迭代之间持久化上次看到的标记：最新区块编号、最新交易哈希、最新日志索引等。每轮只获取比该标记更新的内容。
• 跨越间隙的游标 — 如果监视器离线期间积累了许多新条目，请从上次看到的标记开始向前分页，而不是重新获取所有内容。
• 额度预算 — 轮询监视器会持续消耗额度；请根据 /api/json/config 预先估算每日额度用量（每日请求数 × 每次调用的额度），并选择符合套餐额度的轮询间隔。

套餐、额度与成本估算

有两个无需身份验证的端点可提供实时计费规则。请优先使用它们，而不是硬编码数值——定价等级和每次调用的额度成本会发生变化。

URL	返回内容	身份验证
https://api.blockscout.com/api/json/plans	所有套餐等级及其每日额度上限 / 速率限制	无
https://api.blockscout.com/api/json/config	各端点的额度成本表以及支持的链 ID 列表	无

作为背景信息，公开文档当前列出了以下套餐——请将这些数字视为快照；如需权威的当前值，请查询 /api/json/plans：

等级	每日额度	速率限制	价格
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（或正文表示额度耗尽）	已超出每日额度上限	停止并报告。建议升级套餐或等待每日额度重置。
429	受到速率限制	采用指数延迟退避后重试——不要在循环中紧密重试。
5xx	临时服务器错误	采用退避策略重试，并限制尝试次数。

整合起来——推荐工作流

对于用户描述的每个新数据需求：

1. 预先检查 API 密钥，如果这是本次会话中首次调用 PRO API（请参阅 API 密钥——必须进行的预先检查）。
2. 确定目标链 ID，如果用户按符号或名称指定了链——查询 /api/json/config。
3. 路由请求。 判断由哪个接口满足数据需求：
   • 浏览器索引的数据（交易、余额、区块、日志、代币、NFT、解码后的事件、合约元数据、账户抽象对象等）→ 使用 references/pro-api-index.md 中的 REST 端点。继续执行步骤 4–6。
   • 特定区块的实时或历史合约状态（区块 N 上的 balanceOf(addr)、过去区块上的 totalSupply()、任何 view 函数、合约存储读取）→ 通过 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 查看顶层结构，然后使用 oastools walk schemas -name <SCHEMA_NAME> 跟进实际要用字段对应的特定 $ref。
6. 调用端点时，使用 Authorization: Bearer ${BLOCKSCOUT_PRO_API_KEY}、有意义的 User-Agent、Accept: application/json（请参阅必需请求标头）以及任何必需的查询参数。从响应中读取 x-credits-remaining，并仅提取所需的响应正文内容（请参阅处理响应内容）——不要完整输出整个响应正文。
7. **对于 eth_call 请求：**向 https://api.blockscout.com/{chain_id}/json-rpc 发送 POST 请求，使用相同的 Bearer 身份验证和 JSON-RPC 正文——请参阅读取合约状态。
8. **对于长时间运行或批量任务，**在有意义的检查点向用户展示 x-credits-remaining，限制请求速率以不超过计划的 RPS 上限，并在额度不足时妥善停止。