給 AI Agent 的區塊鏈 RPC 與文件 MCP

將 AI Agent 連接到區塊鏈 RPC 與文件 MCP：免 key 探索能力、透過 HTTP 建立帳戶，然後以 API key 呼叫 RPC 與 Data API。

從免 key 的文件 MCP 端點開始，探索區塊鏈 RPC 方法、Data API 資料集、價格與文件。AI Agent 是第一等使用者：開發者與 AI Agent 使用相同的 API、規則、限制與價格。

探索：使用文件 MCP、llms.txt、OpenAPI 與公開 JSON 來選擇鏈與方法。免 key RPC 呼叫僅限於該鏈的 public.methods。
透過 HTTP 建立帳戶：依照程式化建立帳戶以錢包簽章登入並建立 API key。MCP 的 how_to_get_api_key 會回傳這個獨立 HTTP 流程的指示。
呼叫資料 API：將 key 保存在 BLOCKVECTRA_API_KEY，並用於認證 RPC 或 Data API 請求。對於需要 key 的 MCP 工具，請設定用戶端的 x-api-key 標頭；每個工具允許的操作列於下方。

1. 機器可讀的脈絡與規格

BlockVectra 發布了以 LLM agent 與開發者工具為目標的檔案：

llms.txt 索引

依照 llmstxt.org 慣例，這些檔案為 agent 提供網站及其端點的結構化摘要：

主站索引：主站 llms.txt——主站、支援鏈、定價與公開 API 的概觀。
文件索引：文件 llms.txt——每一頁文件及其標題與說明的目錄。

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

完整文件：llms-full.txt——每一頁英文文件的全文，集結為單一純文字 Markdown 檔，適合載入 agent 的系統提示，或匯入檢索增強生成（RAG）管線。

可下載的 OpenAPI 3.1 規格

文件站提供 OpenAPI 3.1 YAML 檔，可直接匯入 agent 框架、工具產生器或 API 用戶端：

JSON-RPC API 規格：/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 透過 HTTP Push API 與 x-api-key 建立及管理訂閱；文件 MCP 提供這些指南的探索與閱讀。

關於路徑版本控制、回溯相容性規則，以及給 agent 與 SDK 作者的建議，請參閱 API 版本控制與相容性。關於熱門框架（ElizaOS、viem、wagmi、Coinbase AgentKit）的立即可用配方，請參閱 Agent 框架配方。

Model Context Protocol（MCP）伺服器

BlockVectra 透過 Streamable HTTP 提供無狀態、免 key 的 MCP 伺服器：

端點：MCP 端點（HTTP POST 接收 JSON-RPC 2.0；GET 回傳 405）
傳輸：MCP Streamable HTTP（無狀態，無需 API key）

可用工具

read_doc(path, lang?)：從 /md/{lang}/{path}.md 回傳任一文件頁面的原始 Markdown 內容。接受內部相對路徑（例如 quickstart、guides/ai-agents、api/json-rpc、chains）。
search_docs(query, lang?, limit?)：跨標題、路徑與摘要搜尋文件頁面。
list_chains()：從 GET /v1/chains 讀取支援的區塊鏈網路、靜態參數與方法策略。
get_status()：從 GET /v1/status 讀取即時服務就緒狀態、網路狀態、最新區塊高度與同步延遲。
get_pricing()：從 GET /v1/plans 讀取計算單位（CU）權重、免費方案參數與預設 key 限制。
estimate_usage(lines?, method?, calls_per_day?)：估算一種或多種方法的計算單位（CU）、標價總成本，以及扣除週期免費額度後的淨成本（支援多列 lines: [{method, calls_per_day}]，或單一 method 與 calls_per_day）。也會回報來自 key_defaults 的每把 key 速率限制，並在流量超過單一 key 限制時建議所需的 API key 數量。
how_to_get_api_key(lang?)：回傳 API key 交付步驟，以及 JSON-RPC 與 Data API 的請求認證形式。
get_method_info(method, chain?)：回傳某方法的鏈可用性、計算單位（CU）權重、每百萬次呼叫價格與文件連結。JSON-RPC 可用性依 GET /v1/chains 中的 methods.allow 與 deny；Data API 資料集涵蓋範圍依 GET /v1/status 中的 data_features，並以鏈目錄中的 data: true 為準。
explain_error(reason?, code?, http_status?)：從錯誤目錄查詢錯誤說明、計費影響、可重試性與復原動作。
list_docs(lang?)：從文件索引列出所有文件頁面的相對路徑與標題。
rpc_call(chain, method, params?)：使用你的 API key 在支援的鏈上執行唯讀 JSON-RPC 2.0 呼叫（readOnlyHint: true）。寫入方法（例如 eth_sendRawTransaction）會被拒絕；請改用 send_raw_transaction。完整存取需要在 MCP 用戶端設定中提供 x-api-key 標頭，或在可用時使用免 key 公共端點。
data_api_get(chain, path, query?)：使用你的 API key，對支援的鏈與路徑向 Data API 發出 GET 請求（readOnlyHint: true）。需要在 MCP 用戶端設定中提供 x-api-key 標頭。
get_account()：使用你的 API key，從 GET /v1/account 查詢帳戶餘額、計算單位（CU）、速率限制與 key 參數（readOnlyHint: true）。需要在 MCP 用戶端設定中提供 x-api-key 標頭。
get_deposit_address()：使用你的 API key，從 GET /v1/topup/deposit-address 查詢專屬鏈上儲值地址、已開放網路與代幣（readOnlyHint: true）。請只轉帳到列出的網路與代幣。需要在 MCP 用戶端設定中提供 x-api-key 標頭。
send_raw_transaction(chain, raw_tx)：透過 eth_sendRawTransaction 將已簽章的原始交易廣播到支援的鏈（destructiveHint: true）。完整存取需要在 MCP 用戶端設定中提供 x-api-key 標頭，或在該鏈允許時使用免 key 公共端點。

需要 key 的工具

需要 key 的工具需要 API key，才能執行鏈上查詢、交易、Data API 請求或帳戶操作。

API key 安全性：

僅從標頭讀取：API key 只從 MCP 用戶端 HTTP 請求標頭讀取（x-api-key: rgw_... 或 Authorization: Bearer rgw_...）。
絕不要把 key 放進對話：絕不要在工具引數中傳遞 API key 或私鑰，也不要將它們貼進對話。工具引數與對話歷史會進入對話記錄與脈絡；在引數中傳遞 key 會被拒絕。

若在沒有 API key 標頭的情況下呼叫，這些工具會回傳 isError: true，並引導 agent 前往 how_to_get_api_key 與程式化建立帳戶指南。

從 MCP 用戶端連線

你可以在常見的開發環境與框架中，連線到 https://docs.blockvectra.com/mcp 的 BlockVectra 文件 MCP 伺服器。

先從沒有 API key 開始。連線到 MCP 端點、呼叫 list_chains，然後用 read_doc 閱讀 quickstart。當你需要 Data API 或帳戶工具時，在用戶端的 HTTP 標頭中加入 API key。免 key RPC 存取依每條鏈的公開方法策略。

x-api-key 標頭為選填。沒有 API key 時，用戶端可以使用所有唯讀文件工具（read_doc、search_docs、list_docs）、鏈探索（list_chains）、即時狀態（get_status）、定價估算（get_pricing、estimate_usage）、錯誤說明（explain_error），以及公開端點允許的方法。使用需要 key 的工具（受限方法上的 rpc_call、send_raw_transaction、data_api_get、get_account 與 get_deposit_address）時，請以你的 API key 設定 x-api-key 標頭。

Claude Code

使用 CLI 連線到 MCP 伺服器：

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

若要為認證工具加入選填的 API key，請傳入 --header（或 -H）選項：

claude mcp add --transport http blockvectra-docs https://docs.blockvectra.com/mcp \
  --header "x-api-key: YOUR_API_KEY"

官方文件：Claude Code MCP 文件。

Cursor

將伺服器加入 Cursor 的 MCP 設定：

{
  "mcpServers": {
    "blockvectra": {
      "url": "https://docs.blockvectra.com/mcp"
    }
  }
}

Cursor 也支援透過 deep link 一鍵安裝，使用 base64 編碼的設定 eyJ1cmwiOiJodHRwczovL2RvY3MuYmxvY2t2ZWN0cmEuY29tL21jcCJ9（代表 {"url":"https://docs.blockvectra.com/mcp"}）：

cursor://anysphere.cursor-deeplink/mcp/install?name=blockvectra&config=eyJ1cmwiOiJodHRwczovL2RvY3MuYmxvY2t2ZWN0cmEuY29tL21jcCJ9

當你需要認證工具（Data API 或帳戶管理）時，加入含有 API key 的 headers 物件：

{
  "mcpServers": {
    "blockvectra": {
      "url": "https://docs.blockvectra.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

官方文件：Cursor MCP 文件與 Cursor 安裝連結。

VS Code

在 VS Code 中，於 .vscode/mcp.json 的頂層 servers 鍵底下，以 type: "http" 設定伺服器：

{
  "servers": {
    "blockvectra": {
      "type": "http",
      "url": "https://docs.blockvectra.com/mcp"
    }
  }
}

當你需要認證工具時，加入 headers 物件：

{
  "servers": {
    "blockvectra": {
      "type": "http",
      "url": "https://docs.blockvectra.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

儲存敏感憑證時，VS Code 支援參照輸入變數或環境檔案，而不是將 key 寫死。你也可以使用命令面板動作 MCP: Add Server 來新增伺服器。

官方文件：VS Code MCP 伺服器文件與 VS Code MCP 設定參考。

Codex

使用 OpenAI Codex CLI 新增伺服器：

codex mcp add blockvectra --url https://docs.blockvectra.com/mcp

在 config.toml 中設定伺服器 URL：

[mcp_servers.blockvectra]
url = "https://docs.blockvectra.com/mcp"

當你需要認證工具時，在 config.toml 中設定請求標頭：

[mcp_servers.blockvectra]
url = "https://docs.blockvectra.com/mcp"
http_headers = { "x-api-key" = "YOUR_API_KEY" }

或者，從環境變數對應標頭：

[mcp_servers.blockvectra]
url = "https://docs.blockvectra.com/mcp"
env_http_headers = { "x-api-key" = "BLOCKVECTRA_API_KEY" }

官方文件：OpenAI Codex CLI MCP 文件。

Gemini CLI

在 Gemini CLI 設定中，於 mcpServers 底下使用 httpUrl 新增伺服器，以支援 Streamable HTTP：

{
  "mcpServers": {
    "blockvectra": {
      "httpUrl": "https://docs.blockvectra.com/mcp"
    }
  }
}

當你需要認證工具時，加入含有 API key 的 headers 物件：

{
  "mcpServers": {
    "blockvectra": {
      "httpUrl": "https://docs.blockvectra.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

官方文件：Gemini CLI MCP 伺服器文件。

OpenAI Responses API

呼叫 OpenAI Responses API 時，在 tools 陣列中傳入 MCP 伺服器，並設定 type: "mcp"：

OPENAI_API_BASE="https://api.openai.com/v1"
curl "$OPENAI_API_BASE/responses" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "tools": [{
      "type": "mcp",
      "server_label": "blockvectra",
      "server_url": "https://docs.blockvectra.com/mcp",
      "require_approval": "never"
    }],
    "input": "..."
  }'

當你需要認證工具時，在工具定義中包含 headers 欄位：

{
  "type": "mcp",
  "server_label": "blockvectra",
  "server_url": "https://docs.blockvectra.com/mcp",
  "headers": { "x-api-key": "YOUR_API_KEY" },
  "require_approval": "never"
}

官方文件：OpenAI MCP 工具指南與 OpenAI Responses API 參考。

Windsurf

在 Windsurf 中，於 mcpServers 底下使用 serverUrl 欄位設定伺服器：

{
  "mcpServers": {
    "blockvectra": {
      "serverUrl": "https://docs.blockvectra.com/mcp"
    }
  }
}

當你需要認證工具時，加入含有 API key 的 headers 物件：

{
  "mcpServers": {
    "blockvectra": {
      "serverUrl": "https://docs.blockvectra.com/mcp",
      "headers": {
        "x-api-key": "YOUR_API_KEY"
      }
    }
  }
}

Windsurf 也支援參照環境變數，例如 "x-api-key": "${env:BLOCKVECTRA_API_KEY}"。

官方文件：Windsurf MCP 文件。

Claude Desktop 與 claude.ai

自訂連接器透過使用者介面設定：

claude.ai：前往 Customize > Connectors，點選 + Add，選擇 Add custom connector，然後輸入 URL：
```
https://docs.blockvectra.com/mcp
```
Claude Desktop：開啟帳戶設定選單，並透過連接器介面設定自訂連接器。

連線到該 URL 可讓 Claude 在無憑證的情況下搜尋指南、閱讀 Markdown 文件、檢視支援的鏈、檢查網路狀態並計算定價估算。

官方文件：Claude 自訂連接器指南。

2. 公開 JSON 端點（無需 key）

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：鏈代稱（例如 robinhood_mainnet）。
- name：人類可讀的顯示名稱。
- chain_id：EIP-155 chain 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 chain 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：未認證的公開端點設定（或 null）：
  - url：公開請求的基底 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（註冊贈額，單位為 units）、monthly_units（週期補充水位，單位為 units）、window_days（用量週期長度，以天為單位）與 max_calls_per_sec（免費方案每秒呼叫上限）。
pricing：付費方案參數——units_per_usd（每 1 美元的 units）、cu_per_unit（每 unit 的 CU）與 min_topup_usd（最低儲值金額，以美元為單位）。
method_weights：每次呼叫的 CU 權重，每一項為 { "method": string, "cu_weight": number }。method 指定 JSON-RPC 方法名稱或模式、未列出方法的預設權重，或 Data API 操作（例如 data.<op>）。權重以方法為單位，不依鏈拆分。

3. 認證與 key 安全性

發出 RPC 呼叫的 agent 必須遵守以下規則：

認證：以下列三種方式之一傳入 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 標頭中的 key）。
Key 安全性：將 API key 保存在伺服器端環境變數（例如 BLOCKVECTRA_API_KEY）或機密管理員中。絕不要將 key 嵌入瀏覽器程式碼或任何用戶端 bundle。端點確實會回傳 Access-Control-Allow-Origin: *，但它們是要由後端服務呼叫，而非從瀏覽器呼叫。
計量與升級：用量以計算單位（CU）計量：每個方法依其權重消耗 CU，而餘額、CU 桶與免費方案速率限制在所有鏈之間共享。付費儲值後，免費方案的每秒呼叫上限不再適用；每把 key 仍有 CU 速率限制與突發容量。未使用的免費額度會留在你的額度中，仍可使用。詳情請參閱定價頁面。

還沒有 API key？

如果你有以太坊錢包：依照程式化建立帳戶指南在無瀏覽器的情況下，使用以太坊錢包簽章建立帳戶並建立 API key。agent 的身分就是它的錢包：如果 session 權杖或 key 遺失，以同一個錢包重新認證即可復原。如果你沒有錢包：請使用者登入 console.blockvectra.com 建立 key，並設為環境變數 BLOCKVECTRA_API_KEY。不要要求使用者將 key 貼進對話。

查詢餘額（`GET /v1/account`）

agent 可以直接檢查其 key 的目前餘額、CU 限制與 key 參數，而不消耗計算單位（CU）。請求格式、速率限制與完整回應欄位定義，請參閱查詢餘額：GET /v1/account。

4. 給 agent 的鏈選擇工作流

在派送呼叫之前，agent 可以依循以下步驟：

檢查鏈及其方法策略：呼叫 GET /v1/chains，確認目標鏈存在且 jsonrpc: true，而且你打算呼叫的方法被 methods.allow 允許、未被 methods.deny 拒絕（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。

export BLOCKVECTRA_API_KEY="rgw_your_api_key"

# 1. List public chains and their method policy
curl -s "https://api.blockvectra.com/v1/chains"

# 2. Check the service and per-chain status
curl -s "https://api.blockvectra.com/v1/status"

# 3. Call eth_blockNumber on the chain you selected (e.g. robinhood_mainnet)
curl -s "https://api.blockvectra.com/v1/robinhood_mainnet" \
  -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":[]}'

成功的呼叫會回傳標準 JSON-RPC 回應物件：

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

若要檢查每個請求的 CU 費用與回應標頭中的剩餘餘額 units，請加入 x-bv-meter: 1。標頭行為與錯誤情況，請參閱費用與餘額回應標頭。

下一步

瀏覽資料集目錄，查看 BlockVectra 索引的全部資料集。
查看免費方案與定價，確認你的帳戶包含哪些內容。
參考程式化建立帳戶指南使用錢包簽章建立帳戶並建立 API key，或登入控制台建立 key。

給 AI Agent 的區塊鏈 RPC 與文件 MCP

本頁目錄