一把 API key 適用於所有支援的鏈

同一把 key 適用於所有支援的鏈，認證呼叫把 key 放在 x-api-key 請求標頭或路徑，鏈名由 GET /v1/chains 動態傳回，切換網路只需改鏈變數，不要在程式碼裡寫死鏈清單，帶結尾斜線會傳回 404。

1. 一把 key 適用於所有支援的鏈

同一把 API key 適用於所有支援鏈的 JSON-RPC，以及已提供服務的鏈上的 Data API。key 屬於你的帳戶，不綁定特定鏈；不需要為每個網路分別產生 API key。

額度與速率限制在所有網路之間，以及 JSON-RPC API 與 Data API 之間共用，不按網路拆分。詳細計費規則請參閱定價頁面。

餘額共用：付費儲值與免費額度適用於所有鏈。在任何鏈上的呼叫都從同一個帳戶餘額扣款。
速率限制共用：對特定 key 而言，計算單位（CU）的補充速率與突發容量適用於所有鏈。免費方案的每秒呼叫次數上限在所有支援鏈上合併計算，而非按鏈拆分。
升級路徑：儲值後，你不再受免費方案的每秒呼叫次數上限約束；每把 key 仍受 CU 速率與突發限制約束，詳見 JSON-RPC 文件。

2. URL 結構與 `{chain}` 參數

每個以鏈為範圍的請求都會在 URL 路徑中以 {chain} 指定目標網路。{chain} 是鏈的小寫識別代號（例如 robinhood_mainnet）。

服務	認證	URL 範本	說明
JSON-RPC	key 放在 URL 路徑中	`POST /v1/{chain}/{api_key}`	最簡單的形式，適合 curl 與 HTTP 用戶端
JSON-RPC	key 放在請求標頭中	`POST /v1/{chain}`	透過 `x-api-key: {api_key}` 請求標頭傳入 key
Data API	REST 路由	`GET /v1/data/{chain}/…`	透過 `x-api-key: {api_key}` 請求標頭傳入 key
公開鏈清單	免認證	`GET /v1/chains`	公開的鏈清單與靜態參數（不計費）
公開狀態	免認證	`GET /v1/status`	目前服務狀態與各鏈鏈頭（不計費）

GET /v1/chains 會為每條鏈回報 jsonrpc 與 data 旗標。當鏈提供 JSON-RPC 時，請使用其 JSON-RPC URL；當鏈的 data 旗標為 true 時，請使用 GET /v1/data/{chain}/…（Data API 只服務這些鏈）。

提示：透過請求標頭傳入 key 時，URL 結尾請以鏈名作結，且不要加上結尾斜線。JSON-RPC 僅在 /v1/{chain} 與 /v1/{chain}/{api_key} 提供。帶結尾斜線（例如 /v1/{chain}/）或缺少鏈段的請求會回傳 HTTP 404 且回應主體為空。對未知 {chain} 的請求會回傳 HTTP 404 與 error.data.reason: "unknown_chain"（不計費）。

3. 以程式化方式探索鏈與能力

支援的鏈及其能力是動態提供的。請不要在應用程式中硬編碼靜態鏈清單，而應在執行階段探索可用的網路及其能力：

透過 `GET /v1/chains` 探索靜態參數

這個公開端點免認證且不計費，會回傳所有公開的鏈：

GET /v1/chains

回應範例：

{
  "chains": [
    {
      "chain": "robinhood_mainnet", "name": "Robinhood Chain", "chain_id": 4663,
      "jsonrpc": true,
      "data": true,
      "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
    }
  ]
}

欄位說明：

chain：鏈識別代號（用於 URL 中的 {chain}）
name：人類可讀的顯示名稱
chain_id：EIP-155 鏈 ID（十進位整數）
jsonrpc：是否啟用 JSON-RPC
data：是否啟用 Data API
methods：該鏈的 JSON-RPC 方法策略，包含 allow（允許的方法）與 deny（明確拒絕的方法）
max_logs_block_range：單次 eth_getLogs 請求允許的最大區塊範圍
state_window_blocks：歷史狀態視窗大小（以區塊為單位）；無限制時為 null

透過 `GET /v1/status` 檢查運作狀態

這個公開端點免認證且不計費，會回傳服務就緒狀態與各鏈鏈頭資訊：

GET /v1/status

回應範例：

{
  "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
      }
    }
  ]
}

欄位說明：

gateway.status：服務狀態（ok 或 degraded）
chains[].data_features：Data API 為此鏈提供的能力
chains[].status：節點運作狀態（ok 或 unavailable）
chains[].head：最新區塊頭（block、time、lag_seconds）

4. 切換鏈時需要留意的各鏈差異

在鏈之間切換時，請檢視 GET /v1/chains 提供的欄位：

方法允許與策略（methods.allow / methods.deny）：可用的 JSON-RPC 方法會依各網路的方法策略而不同。請求不允許的方法會回傳 HTTP 200 與 JSON-RPC 錯誤碼 -32601（method not available，不計費）。
日誌區塊範圍（max_logs_block_range）：eth_getLogs 查詢的最大區塊跨度因鏈而異。超過該鏈的限制會回傳 HTTP 200 與 JSON-RPC 錯誤碼 -32602（eth_getLogs block range too large，不計費）。
狀態保留視窗（state_window_blocks）：完整歷史的鏈會回傳 null。在具有狀態修剪的鏈上，查詢視窗之外的歷史狀態會回傳 HTTP 200 與 JSON-RPC 錯誤碼 -32011（historical state is not available beyond the most recent <N> blocks，不計費）。
Data API 功能與涵蓋範圍（data / data_features）：提供資料集的鏈列於支援的鏈頁面。查詢鏈不支援的資料集，或早於其已索引涵蓋範圍的區塊，會回傳 HTTP 422（error.code 為 no_coverage，不計費）。當服務暫時無法使用時（例如某條鏈忙碌中），請求會回傳 HTTP 503 並附帶 Retry-After 標頭（不計費）。

5. 程式碼範例

完整入門範本：blockvectra/multichain-viem

只要更新鏈變數（或從 GET /v1/chains 讀取），同一段程式碼就能在不同鏈上執行，透過 JSON-RPC 查詢 eth_blockNumber，並透過 Data API 查詢資料集新鮮度：

export BLOCKVECTRA_API_KEY="rgw_your_api_key"

# 修改鏈變數即可改用「支援的鏈」中的另一條鏈
CHAIN="robinhood_mainnet"

# 1. JSON-RPC：查詢 eth_blockNumber（POST /v1/{chain}，key 放在 x-api-key 標頭）。
RPC_URL="https://api.blockvectra.com/v1/$CHAIN"
curl -s "$RPC_URL" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

# 2. Data API：查詢資料集新鮮度（GET /v1/data/{chain}/status/freshness）
curl -s "https://api.blockvectra.com/v1/data/$CHAIN/status/freshness" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

回應範例

JSON-RPC eth_blockNumber 成功回應（依該方法的 CU 權重計費）：

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

Data API GET /v1/data/{chain}/status/freshness 成功回應（以 CU 計費，僅對 2xx 成功回應計費）：

{
  "data": [
    {
      "dataset": "blocks",
      "category": "raw",
      "max_block_number": 72313256,
      "max_day": null,
      "max_time": "2026-09-28T03:41:07Z",
      "seconds_behind": 0,
      "blocks_behind": null,
      "days_behind": null,
      "checked_at": "2026-09-28T03:41:10Z"
    },
    {
      "dataset": "traces",
      "category": "raw",
      "max_block_number": 72313256,
      "max_day": null,
      "max_time": "2026-09-28T03:41:07Z",
      "seconds_behind": 0,
      "blocks_behind": null,
      "days_behind": null,
      "coverage_from_block": 72050949,
      "coverage_to_block": 72313256,
      "coverage_complete": true,
      "checked_at": "2026-09-28T03:41:10Z"
    },
    {
      "dataset": "dex_prices",
      "category": "derived",
      "max_block_number": null,
      "max_day": "2026-09-27",
      "max_time": "2026-09-27T00:00:00Z",
      "seconds_behind": 99667,
      "blocks_behind": null,
      "days_behind": 1,
      "checked_at": "2026-09-28T03:41:10Z"
    }
  ],
  "meta": {
    "chain": "robinhood_mainnet",
    "chain_slug": "ROBINHOOD_MAINNET",
    "chain_external_id": "eip155:4663",
    "as_of_block": 72313256,
    "safe_block": 72313100,
    "finalized_block": 72313000,
    "coverage": "full",
    "refreshed_at": "2026-09-28T03:41:10Z"
  }
}

下一步

瀏覽資料集目錄，查看 BlockVectra 索引的每個資料集。
查看免費方案與定價，確認你的帳戶包含哪些內容。
登入控制台建立 API key。

一把 key 通用多鏈：將範例切換到另一條鏈