AI Agent 接入区块链 RPC 与文档 MCP

为AI Agent接入区块链RPC与文档MCP：先用免key的MCP端点与llms.txt发现可用链与方法，读取文档与定价了解计费规则，再通过开户流程创建key，并用它调用需要鉴权的RPC方法与数据集。

先连接免 key 的文档 MCP 端点，发现区块链 RPC 方法、Data API 数据集、价格与文档。AI Agent 是第一等用户：开发者与 AI Agent 使用同一套 API、规则、限额和价格。

在各客户端中接入

以 Claude Code 为例，添加文档 MCP 服务：

claude mcp add --transport http blockvectra-docs https://docs.blockvectra.com/mcp

在客户端中请求依次执行以下两次免 key 工具调用：先发现链，再读取快速上手文档。这两步都不需要账户、钱包或 API key。

调用 list_chains，参数 chain=robinhood_mainnet。
然后调用 read_doc，参数 path=quickstart、lang=zh。

成功是指 list_chains 返回 robinhood_mainnet，且 read_doc 返回快速上手文档正文；仅注册工具或看到工具列表不代表调用成功。

安装或连接失败时，见在各客户端中接入中的配置、请求头与排错说明。已知目标链时，把精确链名作为 chain 传给 list_chains；未知链仍可用 list_chains 发现。其他任务先用 search_docs 搜索，再把匹配页面的 path 传给 read_doc。

仅当 RPC、Data API 或账户任务需要鉴权时，才继续下面的开户流程。

发现能力：用文档 MCP、llms.txt、OpenAPI 与公开 JSON 选择链和方法。免 key RPC 调用限于该链的 public.methods。
通过 HTTP 开户：按程序化开户指南用钱包签名登录并创建 API key。MCP 的 how_to_get_api_key 返回这套独立 HTTP 流程的操作说明。
调用数据接口：把 key 放入 BLOCKVECTRA_API_KEY，用于需鉴权的 RPC 或 Data API 请求。使用带 key 的 MCP 工具时配置客户端 x-api-key 请求头；各工具支持的操作见下文。

1. 机器可读的上下文与规格文件

BlockVectra 面向 LLM agent 与开发者工具提供以下文件：

llms.txt 索引

遵循 llmstxt.org 规范，用于向 LLM 提供站点结构与端点概览：

官网索引：官网 llms.txt —— 汇总官网主页、公开链列表、计费与公开接口概览。
文档索引：文档 llms.txt —— 罗列文档站每个页面的标题与说明。

完整文档单文件（`llms-full.txt`）

文档全文：llms-full.txt —— 聚合英文文档站每个页面的纯文本 Markdown 内容，可直接注入 Agent 系统提示词（System Prompt）或用于检索增强生成（RAG）流程。

可下载的 OpenAPI 3.1 规范

文档站提供 OpenAPI 3.1 格式的 YAML 文件，可直接导入 agent 框架、代码生成工具或 API 客户端：

JSON-RPC 接口规范：/openapi/json-rpc.yaml —— 包含支持的方法、各链方法策略、错误响应与计算单元计量。
Data API 接口规范：/openapi/data.yaml —— 包含已索引区块、交易、转账、余额、持有人及相关数据集的 REST 端点定义。
Push API 接口规范：/openapi/push.yaml —— 包含 HTTP 订阅管理、钱包地址关注、Webhook 事件、签名与重放。

钱包地址活动接入见区块链 Webhook API 指南，ERC-20 USDT / USDC 到账通知见收款接收示例。开发者与 AI Agent 通过携带 x-api-key 的 HTTP Push API 创建与管理订阅；文档 MCP 用于发现和读取这些指南。

关于路径版本、向后兼容规则以及面向 Agent 与 SDK 作者的对接建议，请参阅 API 版本与兼容性。如需主流框架（ElizaOS、viem、wagmi、Coinbase AgentKit）的即用型配置配方，请参阅 Agent 框架接入配方。

Model Context Protocol（MCP）服务

BlockVectra 提供基于 Streamable HTTP 的无状态 MCP 服务，端点见 MCP 端点，连接无需 key。共 15 个工具：文档、链、状态与价格类工具免 key 可用，带 key 工具从客户端请求头读取 x-api-key；key 不会经过工具参数传递。

工具清单、key 要求、常见问题与各客户端（Claude Code、Cursor、VS Code、Codex、Gemini CLI、OpenAI Responses API、Windsurf）的接入步骤见 BlockVectra MCP 服务页。

如果你的 Agent 已经通过 One 工作，可以在它的公开 API 目录里选用 BlockVectra 的动作，例如 DEX 代币日价。如需直接连接文档 MCP，请使用上面的客户端配置。认证使用你自己的 BlockVectra key，以 x-api-key 请求头发送，获取方式见程序化开户指南。key 只放在 One 的私密连接配置里，不要写进 Agent 提示或动作参数。调用价格类动作时，需要明确给出链、代币、计价币和 UTC 日期。链数据以响应中的 freshness 与 coverage 为准：日价缺失或数据为空，不代表价格为零。请求参数见 Data API 参考。

2. 免 Key 的公开 JSON 接口

Agent 可以先查看可用链、实时状态与套餐参数，再发起任何计费调用。以下接口都无需 API key：

GET /v1/status 与 GET /v1/chains 免鉴权、不计费。
GET /v1/plans 公开且免鉴权。

三者都返回 Access-Control-Allow-Origin: *。

服务状态（`GET /v1/status`）

返回服务就绪状态及各公开链的同步状态：

curl -s "https://api.blockvectra.com/v1/status"

返回字段：

checked_at：状态快照生成时间（RFC 3339 / ISO 8601 UTC）。
gateway.status：服务运行状态。ok 表示服务就绪；degraded 表示在恢复前付费请求会被拒绝。该状态与任何一条链的节点状态无关。
chains[]：对外服务的链列表：
- chain：链标识符（slug，如 robinhood_mainnet）。
- name：人类可读的显示名。
- chain_id：EIP-155 链 ID（十进制整数）。
- jsonrpc：是否提供 JSON-RPC 服务。
- data：是否提供 Data API 服务。
- data_features：Data API 为该链提供的能力（data 为 false 时为空数组）。
- data_status：Data API 运行状态（ok、syncing 或 unavailable，仅在 data 为 true 时出现）。
- status：链节点状态（ok 或 unavailable）。
- head：最新区块信息，包含 block（最新区块高度）、time（区块时间戳）与 lag_seconds（区块时间落后当前时间的秒数）；未知时为 null。

示例返回：

{
  "checked_at": "2026-09-28T12:00:00Z",
  "gateway": {
    "status": "ok"
  },
  "chains": [
    {
      "chain": "robinhood_mainnet", "name": "Robinhood Chain", "chain_id": 4663,
      "jsonrpc": true,
      "data": true,
      "data_features": [
        "blocks",
        "transactions",
        "address_transactions",
        "transfers",
        "token_metadata",
        "freshness"
      ],
      "status": "ok",
      "head": {
        "block": 73017329,
        "time": "2026-09-28T11:59:58Z",
        "lag_seconds": 2
      }
    }
  ]
}

链列表与参数（`GET /v1/chains`）

返回各公开链的静态参数与方法策略：

curl -s "https://api.blockvectra.com/v1/chains"

返回字段：

chains[]：公开链及其静态参数：
- chain：链标识符。
- name：人类可读的显示名。
- chain_id：EIP-155 链 ID。
- jsonrpc：是否提供 JSON-RPC 服务。
- data：是否提供 Data API 服务。
- ws：是否支持 WebSocket 连接。
- subscriptions：支持的 WebSocket 订阅类型（如 newHeads、logs）。
- methods：方法策略：
  - allow：允许调用的方法全名列表（如 eth_call、debug_traceTransaction）。
  - deny：拒绝的方法或前缀通配符列表（如 eth_newFilter）。被拒绝的方法优先于允许的方法。
- max_logs_block_range：单次 eth_getLogs 请求允许的最大区块跨度。
- state_window_blocks：历史状态窗口大小（区块数）；可查全历史时为 null。
- info：链的公网扩展信息（预留字段，当前为空对象 {}）。
- public：免鉴权公开端点配置。仅提供公开 JSON-RPC 的链包含此对象，其他链省略该字段：
  - url：公开端点 Base URL。
  - methods：公开端点开放的方法列表。
  - rate_limit：公开端点请求速率限制（per_ip_rps、burst、batch_max）。
  - history_blocks：公开端点可查询的历史区块数。
  - send_raw_rate_limit：eth_sendRawTransaction 独立速率限制。

示例返回：

{
  "chains": [
    {
      "chain": "robinhood_mainnet", "name": "Robinhood Chain", "chain_id": 4663,
      "jsonrpc": true,
      "data": true,
      "ws": true,
      "subscriptions": [
        "newHeads",
        "logs"
      ],
      "methods": {
        "allow": [
          "eth_blockNumber",
          "eth_call",
          "eth_chainId",
          "debug_traceTransaction"
        ],
        "deny": [
          "eth_newFilter",
          "eth_newBlockFilter",
          "eth_newPendingTransactionFilter",
          "eth_getFilterLogs",
          "eth_getFilterChanges",
          "eth_uninstallFilter",
          "eth_subscribe",
          "eth_unsubscribe"
        ]
      },
      "max_logs_block_range": 1000,
      "state_window_blocks": 900,
      "info": {},
      "public": {
        "url": "https://api.blockvectra.com/v1/robinhood_mainnet/public",
        "methods": [
          "eth_chainId",
          "net_version",
          "eth_blockNumber",
          "eth_call"
        ],
        "rate_limit": {
          "per_ip_rps": 3,
          "burst": 20,
          "batch_max": 10
        },
        "history_blocks": 128,
        "send_raw_rate_limit": {
          "per_ip_rps": 1,
          "burst": 3
        }
      }
    }
  ]
}

计费计划与权重（`GET /v1/plans`）

计费计划接口地址为：GET https://console-api.blockvectra.com/v1/plans。Agent 可在运行时查询当前生效的免费套餐限制与各方法的计算单元（CU）权重：

free：免费套餐参数 —— signup_units（注册赠送额度，单位为 unit）、monthly_units（周期补足水位，单位为 unit）、window_days（用量周期天数）与 max_calls_per_sec（免费套餐每秒调用次数上限）。
pricing：付费方案参数 —— units_per_usd（每 1 USD 兑换的计费单位数）、cu_per_unit（每个计费单位对应的 CU 数）与 min_topup_usd（最低充值金额，USD）。
method_weights：每次调用的 CU 权重数组，每项为 { "method": string, "cu_weight": number }。method 对应 JSON-RPC 方法名、未列出方法的默认规则或 Data API 操作（如 data.<op>）。权重按方法计，不按链拆分。

3. Agent 鉴权与密钥安全

Agent 发起 RPC 调用时需遵循以下规则：

鉴权方式：API key 有三种传法。路径传法：POST /v1/{chain}/{api_key}——只使用路径中的 key，忽略两个请求头。x-api-key 请求头传法：POST /v1/{chain} 加 x-api-key: $BLOCKVECTRA_API_KEY。Authorization 请求头传法：POST /v1/{chain} 加 Authorization: Bearer $BLOCKVECTRA_API_KEY。同时带两个请求头时，非空的 x-api-key 优先；只有 x-api-key 缺失或为空时才使用 Bearer。同一个 key 可用于所有已支持的链，也可用于相应链已提供的 Data API（Data API 只接受 x-api-key 请求头）。
保护密钥：API key 只放在服务端环境变量（如 BLOCKVECTRA_API_KEY）或密钥管理服务中，切勿写入浏览器代码或任何客户端产物。接口虽然返回 Access-Control-Allow-Origin: *，但设计为由后端服务调用，而不是在浏览器中直接调用。
计量与付费：按计算单元（CU）计量：每个方法按其权重消耗 CU；余额、CU 令牌桶与免费套餐限流在所有链上合并计算。付费充值后，免费套餐的每秒调用次数上限不再适用；每个 key 仍有 CU 速率上限与突发上限。尚未用完的免费额度保留在服务额度中，可以继续使用。详见定价页。

还没有 API key？

如果有以太坊钱包：可参考程序化开户指南通过以太坊钱包签名自主开户建 key，无需浏览器。Agent 的身份即是开户所用的钱包，若会话或 key 丢失，凭同一个钱包重新签名登录即可找回。如果没有钱包：请用户登录 console.blockvectra.com 建一个 key，并设置为环境变量 BLOCKVECTRA_API_KEY。不要让用户把 key 贴进对话。

查询余额（`GET /v1/account`）

Agent 可以直接查询当前 key 对应的余额与限额信息，无需消耗计算单元（CU）。完整请求格式、独立限流与字段说明请参阅查询余额：GET /v1/account。

4. Agent 动态选链流程

发起调用前，Agent 可以按以下步骤决策：

查验链与方法策略：调用 GET /v1/chains，确认目标链存在且 jsonrpc 为 true，计划调用的方法在 methods.allow 中且未被 methods.deny 拒绝（拒绝优先）。
查验实时状态：调用 GET /v1/status，确认 gateway.status 为 ok、目标链的 status 为 ok；用 head.lag_seconds 判断链上数据是否足够新。某条链的节点未同步时，除 eth_chainId 外的所有方法都返回 JSON-RPC 错误 -32010（HTTP 200，不计费），Agent 可以等待后重试，或改选其他链。
发起请求：POST /v1/{chain}，带上 x-api-key 请求头，发送标准 JSON-RPC 请求体。

5. 最小实现示例

以下示例先读取 /v1/chains 选出一条允许 eth_blockNumber 的链，再确认 /v1/status，最后调用一次 eth_blockNumber。

示例遇到 HTTP 非 2xx、无效 JSON 或 JSON-RPC 错误时会失败退出。仅在响应版本为 2.0、整数 id 为 1、无 error 键且 result 为规范十六进制数量（含 0x0）时打印成功结果。cURL 示例需要 python3。

set -eu
export BLOCKVECTRA_API_KEY="rgw_your_api_key"

# Reject every non-2xx status, including redirects.
request() {
  response=$(curl -fsS -w '\n%{http_code}' "$@") || return "$?"
  case "${response##*$'\n'}" in
    2[0-9][0-9]) printf '%s' "${response%$'\n'*}" ;;
    *) return 1 ;;
  esac
}

chains=$(request "https://api.blockvectra.com/v1/chains")
status=$(request "https://api.blockvectra.com/v1/status")

# Select an allowed chain and check readiness before the RPC call.
chain=$(CHAINS="$chains" STATUS="$status" python3 - <<'PYTHON'
import json
import os


def matches(pattern, method):
    return pattern == method or (pattern.endswith("*") and method.startswith(pattern[:-1]))


selected = next((
    c for c in json.loads(os.environ["CHAINS"])["chains"]
    if c["jsonrpc"]
    and not any(matches(p, "eth_blockNumber") for p in c["methods"]["deny"])
    and any(matches(p, "eth_blockNumber") for p in c["methods"]["allow"])
), None)
if selected is None:
    raise RuntimeError("No chain found that allows eth_blockNumber")

status = json.loads(os.environ["STATUS"])
chain_status = next((c for c in status["chains"] if c["chain"] == selected["chain"]), None)
if status["gateway"]["status"] != "ok" or chain_status is None or chain_status["status"] != "ok":
    raise RuntimeError("Selected chain is currently unavailable")
print(selected["chain"])
PYTHON
)

default_endpoint="https://api.blockvectra.com/v1/robinhood_mainnet"
rpc_response=$(request "${default_endpoint%/*}/$chain" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -H "x-bv-meter: 1" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}')

RPC_RESPONSE="$rpc_response" python3 - <<'PYTHON'
import json
import os
import re

rpc_response = json.loads(os.environ["RPC_RESPONSE"])
if (
    not isinstance(rpc_response, dict)
    or rpc_response.get("jsonrpc") != "2.0"
    or type(rpc_response.get("id")) is not int
    or rpc_response["id"] != 1
    or "error" in rpc_response
    or "result" not in rpc_response
    or not isinstance(rpc_response["result"], str)
    or re.fullmatch(r"0x(?:0|[1-9a-fA-F][0-9a-fA-F]*)", rpc_response["result"]) is None
):
    raise RuntimeError("Invalid eth_blockNumber response")

print("Response:", rpc_response)
PYTHON

调用成功返回标准 JSON-RPC 响应对象：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x45a27f1"
}

若需在响应头中查看单次请求消耗的 CU 及剩余余额单位，可在请求中携带 x-bv-meter: 1。响应头判定规则与返回说明请参阅扣费与余额响应头。

下一步

浏览数据集目录，查看 BlockVectra 索引的全部数据集。
查看免费额度与定价，确认账户可用的方案。
参考程序化开户指南通过钱包签名自主开户建 key，或登录控制台创建 key。