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

> Source: https://docs.blockvectra.com/zh-hant/guides/ai-agents/

從免 key 的[文件 MCP 端點](https://docs.blockvectra.com/mcp)開始，探索區塊鏈 RPC 方法、Data API 資料集、價格與文件。AI Agent 是第一等使用者：開發者與 AI Agent 使用相同的 API、規則、限制與價格。

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

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

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

### llms.txt 索引

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

* **主站索引**：[主站 llms.txt](https://blockvectra.com/llms.txt)——主站、支援鏈、定價與公開 API 的概觀。
* **文件索引**：[文件 llms.txt](https://docs.blockvectra.com/llms.txt)——每一頁文件及其標題與說明的目錄。

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

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

### 可下載的 OpenAPI 3.1 規格

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

* **JSON-RPC API 規格**：[/openapi/json-rpc.yaml](https://docs.blockvectra.com/openapi/json-rpc.yaml)——支援的方法、各鏈方法策略、錯誤回應與計算單位計量。
* **Data API 規格**：[/openapi/data.yaml](https://docs.blockvectra.com/openapi/data.yaml)——已索引區塊、交易、轉帳、餘額、持有者及相關資料集的 REST 端點定義。
* **Push API 規格**：[/openapi/push.yaml](https://docs.blockvectra.com/openapi/push.yaml)——HTTP 訂閱管理、關注的錢包地址、webhook 事件、簽章與重放。

關於錢包地址活動，請依照[區塊鏈 Webhook API 指南](https://docs.blockvectra.com/zh-hant/guides/webhook-push/)。關於 ERC-20 USDT / USDC 收款通知，請使用[收款接收端範例](https://docs.blockvectra.com/zh-hant/guides/stablecoin-payments/#receive-payments-with-webhooks)。開發者與 AI agent 透過 HTTP Push API 與 `x-api-key` 建立及管理訂閱；文件 MCP 提供這些指南的探索與閱讀。

關於路徑版本控制、回溯相容性規則，以及給 agent 與 SDK 作者的建議，請參閱 [API 版本控制與相容性](https://docs.blockvectra.com/en/api/versioning/)。關於熱門框架（ElizaOS、viem、wagmi、Coinbase AgentKit）的立即可用配方，請參閱 [Agent 框架配方](https://docs.blockvectra.com/en/guides/agent-frameworks/)。

### Model Context Protocol（MCP）伺服器

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

* **端點**：[MCP 端點](https://docs.blockvectra.com/mcp)（HTTP POST 接收 JSON-RPC 2.0；GET 回傳 405）
* **傳輸**：MCP Streamable HTTP（無狀態，無需 API key）

#### 可用工具

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

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

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

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

官方文件：[Claude Code MCP 文件](https://code.claude.com/docs/en/mcp)。

#### Cursor

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

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

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

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

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

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

官方文件：[Cursor MCP 文件](https://cursor.com/docs/context/mcp) 與 [Cursor 安裝連結](https://cursor.com/docs/context/mcp/install-links)。

#### VS Code

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

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

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

```json
{
  "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 伺服器文件](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) 與 [VS Code MCP 設定參考](https://code.visualstudio.com/docs/agents/reference/mcp-configuration)。

#### Codex

使用 OpenAI Codex CLI 新增伺服器：

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

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

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

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

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

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

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

官方文件：[OpenAI Codex CLI MCP 文件](https://learn.chatgpt.com/docs/extend/mcp?surface=cli)。

#### Gemini CLI

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

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

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

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

官方文件：[Gemini CLI MCP 伺服器文件](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md)。

#### OpenAI Responses API

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

```bash
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` 欄位：

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

官方文件：[OpenAI MCP 工具指南](https://developers.openai.com/api/docs/guides/tools-connectors-mcp) 與 [OpenAI Responses API 參考](https://developers.openai.com/api/reference/resources/responses/methods/create)。

#### Windsurf

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

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

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

```json
{
  "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 文件](https://docs.devin.ai/desktop/cascade/mcp)。

#### Claude Desktop 與 claude.ai

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

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

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

官方文件：[Claude 自訂連接器指南](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp)。

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

agent 可以在送出任何計量請求之前，先檢視可用的鏈、即時狀態與方案參數。這些端點都不需要 API key：

* `GET /v1/status` 與 `GET /v1/chains` 未認證且不計費。
* `GET /v1/plans` 為公開且未認證。

三者都會送出 `Access-Control-Allow-Origin: *`。

### 服務狀態（`GET /v1/status`）

回傳服務的就緒狀態與每條公開鏈的同步狀態：

```bash
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`。

回應範例：

```json
{
  "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`）

回傳每條公開鏈的靜態參數與方法策略：

```bash
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` 廣播交易的速率限制。

回應範例：

```json
{
  "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 速率限制與突發容量。未使用的免費額度會留在你的額度中，仍可使用。詳情請參閱[定價頁面](https://blockvectra.com/zh-hant/pricing/)。

> **還沒有 API key？**
>
> 如果你有以太坊錢包：依照[程式化建立帳戶指南](https://docs.blockvectra.com/en/guides/programmatic-signup/)在無瀏覽器的情況下，使用以太坊錢包簽章建立帳戶並建立 API key。agent 的身分就是它的錢包：如果 session 權杖或 key 遺失，[以同一個錢包重新認證即可復原](https://docs.blockvectra.com/en/guides/programmatic-signup/#lost-your-session-or-api-key)。如果你沒有錢包：請使用者登入 [console.blockvectra.com](https://console.blockvectra.com/login/?next=%2Fkeys%2F) 建立 key，並設為環境變數 `BLOCKVECTRA_API_KEY`。不要要求使用者將 key 貼進對話。


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

agent 可以直接檢查其 key 的目前餘額、CU 限制與 key 參數，而不消耗計算單位（CU）。請求格式、速率限制與完整回應欄位定義，請參閱[查詢餘額：GET /v1/account](https://docs.blockvectra.com/en/guides/billing-rules/#query-balance-get-v1account)。

## 4. 給 agent 的鏈選擇工作流

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

1. **檢查鏈及其方法策略**：呼叫 `GET /v1/chains`，確認目標鏈存在且 `jsonrpc: true`，而且你打算呼叫的方法被 `methods.allow` 允許、未被 `methods.deny` 拒絕（deny 優先）。
2. **檢查即時狀態**：呼叫 `GET /v1/status`，確認 `gateway.status` 為 `ok`，且目標鏈的 `status` 為 `ok`；使用 `head.lag_seconds` 判斷該鏈的資料對你的使用情境是否足夠新鮮。當某條鏈的節點尚未同步時，除了 `eth_chainId` 以外的每個方法都會回傳 JSON-RPC 錯誤 `-32010`（HTTP 200，不計費），因此 agent 可以等待並重試，或改選另一條鏈。
3. **送出請求**：`POST /v1/{chain}`，附上 `x-api-key` 標頭與標準 JSON-RPC 主體。

## 5. 最小可行範例

以下範例讀取 `/v1/chains` 以選出允許 `eth_blockNumber` 的鏈、檢查 `/v1/status`，然後呼叫一次 `eth_blockNumber`。

**cURL**

```bash
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":[]}'
```


  **TypeScript**

```typescript
const apiKey = process.env.BLOCKVECTRA_API_KEY;

if (!apiKey) {
  throw new Error("Missing BLOCKVECTRA_API_KEY");
}

type ChainFacts = {
  chain: string;
  jsonrpc: boolean;
  methods: { allow: string[]; deny: string[] };
};

function matches(pattern: string, method: string): boolean {
  if (pattern === "*") return true;
  if (pattern.endsWith("*")) return method.startsWith(pattern.slice(0, -1));
  return pattern === method;
}

// 1. Fetch the public chain directory
const chainsRes = await fetch("https://api.blockvectra.com/v1/chains");
const { chains } = (await chainsRes.json()) as { chains: ChainFacts[] };

// 2. Select a chain that serves JSON-RPC and allows eth_blockNumber
const selected = chains.find(
  (chain) =>
    chain.jsonrpc &&
    !chain.methods.deny.some((pattern) => matches(pattern, "eth_blockNumber")) &&
    chain.methods.allow.some((pattern) => matches(pattern, "eth_blockNumber")),
);

if (!selected) {
  throw new Error("No chain found that allows eth_blockNumber");
}

// 3. Confirm the service and the selected chain are ready
const statusRes = await fetch("https://api.blockvectra.com/v1/status");
const status = await statusRes.json();
const chainStatus = status.chains?.find(
  (chain: { chain: string }) => chain.chain === selected.chain,
);

if (status.gateway?.status !== "ok" || chainStatus?.status !== "ok") {
  throw new Error(`Chain ${selected.chain} is currently unavailable`);
}

// 4. Call eth_blockNumber on the selected chain
const defaultEndpoint = "https://api.blockvectra.com/v1/robinhood_mainnet";
const rpcUrl = `${defaultEndpoint.slice(0, defaultEndpoint.lastIndexOf("/"))}/${selected.chain}`;
const rpcRes = await fetch(rpcUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": apiKey,
    "x-bv-meter": "1",
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "eth_blockNumber",
    params: [],
  }),
});

console.log("Response:", await rpcRes.json());
```


  **Python**

```python
import os
import requests

api_key = os.environ["BLOCKVECTRA_API_KEY"]


def matches(pattern: str, method: str) -> bool:
    if pattern == "*":
        return True
    if pattern.endswith("*"):
        return method.startswith(pattern[:-1])
    return pattern == method


# 1. Fetch the public chain directory
chains = requests.get("https://api.blockvectra.com/v1/chains").json()["chains"]

# 2. Select a chain that serves JSON-RPC and allows eth_blockNumber
selected = next(
    (
        chain
        for chain in chains
        if chain["jsonrpc"]
        and not any(matches(p, "eth_blockNumber") for p in chain["methods"]["deny"])
        and any(matches(p, "eth_blockNumber") for p in chain["methods"]["allow"])
    ),
    None,
)

if selected is None:
    raise RuntimeError("No chain found that allows eth_blockNumber")

# 3. Confirm the service and the selected chain are ready
status = requests.get("https://api.blockvectra.com/v1/status").json()
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(f"Chain {selected['chain']} is currently unavailable")

# 4. Call eth_blockNumber on the selected chain
default_endpoint = "https://api.blockvectra.com/v1/robinhood_mainnet"
rpc_url = f"{default_endpoint.rsplit('/', 1)[0]}/{selected['chain']}"
rpc_response = requests.post(
    rpc_url,
    headers={
        "Content-Type": "application/json",
        "x-api-key": api_key,
        "x-bv-meter": "1",
    },
    json={"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber", "params": []},
).json()

print("Response:", rpc_response)
```


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

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

若要檢查每個請求的 CU 費用與回應標頭中的剩餘餘額 units，請加入 `x-bv-meter: 1`。標頭行為與錯誤情況，請參閱[費用與餘額回應標頭](https://docs.blockvectra.com/en/guides/billing-rules/#http-status-codes-and-billing-rules)。

## 下一步

* [瀏覽資料集目錄](https://blockvectra.com/zh-hant/data/)，查看 BlockVectra 索引的全部資料集。
* [查看免費方案與定價](https://blockvectra.com/zh-hant/pricing/#free)，確認你的帳戶包含哪些內容。
* 參考[程式化建立帳戶指南](https://docs.blockvectra.com/en/guides/programmatic-signup/)使用錢包簽章建立帳戶並建立 API key，或[登入控制台](https://console.blockvectra.com/login/?next=%2Fkeys%2F)建立 key。