# 快速入門

> Source: https://docs.blockvectra.com/zh-hant/quickstart/

開發者與 AI Agent 都可以先呼叫免 key 公開 RPC，再建立 key 繼續使用。

## 1. 免 key 讀取區塊高度

無需註冊帳號或建立 API key，直接呼叫範例鏈 `robinhood_mainnet` 的公開 JSON-RPC 端點：

```bash
curl -s "https://api.blockvectra.com/v1/robinhood_mainnet/public" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
```

回應中的 `id: 1` 對應本次請求；`result` 是十六進位區塊高度，每次呼叫可能不同。若傳回 `error`，查看錯誤碼與原因。公開方法、歷史範圍與按 IP 限額見[免費公開 RPC 節點](https://blockvectra.com/en/free/#public-rpc)。

## 2. 建立 API key

前往[控制台](https://console.blockvectra.com/login/?next=%2Fkeys%2F)，用 GitHub、Google 或以太坊錢包登入（首次登入自動開戶），然後建立 API key。建立時 secret 只顯示一次，請立即妥善儲存，並設定為環境變量 `BLOCKVECTRA_API_KEY`。不要把 key 放進瀏覽器前端程式碼。新帳戶註冊即得 30,000,000 CU，無需信用卡。

> **還沒有 API key？**
>
> 如果有以太坊錢包：可參考[程式化開戶指南](https://docs.blockvectra.com/en/guides/programmatic-signup/)透過以太坊錢包簽名自主開戶建 key，無需瀏覽器。如果沒有錢包：請用戶登入 [console.blockvectra.com](https://console.blockvectra.com/login/?next=%2Fkeys%2F) 建一個 key，並設定為環境變量 `BLOCKVECTRA_API_KEY`。不要讓用戶把 key 貼進對話。


## 3. 發出首個通過驗證的呼叫

使用 `x-api-key` 請求標頭讀取同一條鏈的區塊高度。URL 以鏈名結尾，不帶結尾斜槓：

```bash
: "${BLOCKVECTRA_API_KEY:?Set BLOCKVECTRA_API_KEY first}"

curl -s "https://api.blockvectra.com/v1/robinhood_mainnet" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
```

`result` 仍是十六進位區塊高度。此請求按 CU 計費；方法權重與錯誤碼見 [JSON-RPC 參考](https://docs.blockvectra.com/en/api/json-rpc/)，目前價格見[定價](https://blockvectra.com/en/pricing/)。新建 key 約 5 秒後生效；若收到 `invalid_api_key`，稍等重試。其他失敗見下方[常見錯誤](#common-errors)。

## 4. 繼續完成業務任務

* [查詢 Robinhood Chain 上的代幣化股票活動](https://docs.blockvectra.com/en/guides/stocks/)
* [分段回填 HyperEVM 日誌](https://docs.blockvectra.com/en/guides/hyperevm-backfill/)
* [透過 Webhook 接收錢包活動與代幣轉帳](https://docs.blockvectra.com/en/guides/webhook-push/)

## 參考

### API key 與餘額

完整模板倉庫：[blockvectra/agent-quickstart](https://github.com/blockvectra/agent-quickstart)

key 的樣子是 `rgw_` 加 64 位十六進位字元，例如 `rgw_1f2e...`（已截斷）。請保管好，
拿到 key 的任何人都能消耗你的餘額。

> 餘額不足時伺服器端傳回 HTTP 402（JSON-RPC 錯誤碼為 `-32020`；Data API 為 `error.code` `insufficient_balance`），去控制台[帳單頁](https://console.blockvectra.com/billing/)查看餘額與儲值方式。


### 免註冊先試

無需註冊帳號或建立 API key，即可直接呼叫公開 JSON-RPC 端點先試用。下面範例中的端點按 IP 限制呼叫速率（每 IP 3 req/s，突發上限 20，單批最大 10 次呼叫）。超出呼叫頻率限制時回傳 HTTP 429 及 reason `public_rate_limit` 或 `public_pool_busy`（並附帶 `Retry-After` 回應頭）；呼叫未公開方法回傳 JSON-RPC 錯誤碼 `-32601` (`method_not_public`)。

```bash
# 直接呼叫公開端點：
curl -s "https://api.blockvectra.com/v1/robinhood_mainnet/public" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

# 或使用環境變數回退寫法（未設定 BLOCKVECTRA_API_KEY 時自動回退至 public）：
curl -s "https://api.blockvectra.com/v1/robinhood_mainnet/${BLOCKVECTRA_API_KEY:-public}" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
```

#### 各鏈公開端點

- Arbitrum One: https://api.blockvectra.com/v1/arb_mainnet/public — 可查詢、可廣播已簽名交易（eth_sendRawTransaction）
- Base: https://api.blockvectra.com/v1/base_mainnet/public — 可查詢、可廣播已簽名交易（eth_sendRawTransaction）
- BNB Smart Chain: https://api.blockvectra.com/v1/bsc_mainnet/public — 可查詢、可廣播已簽名交易（eth_sendRawTransaction）
- Ethereum: https://api.blockvectra.com/v1/eth_mainnet/public — 可查詢、可廣播已簽名交易（eth_sendRawTransaction）
- Ethereum Sepolia: https://api.blockvectra.com/v1/eth_sepolia/public — 可查詢、可廣播已簽名交易（eth_sendRawTransaction）
- HyperEVM: https://api.blockvectra.com/v1/hyperevm_mainnet/public — 唯讀
- Polygon: https://api.blockvectra.com/v1/polygon_mainnet/public — 可查詢、可廣播已簽名交易（eth_sendRawTransaction）
- Robinhood Chain: https://api.blockvectra.com/v1/robinhood_mainnet/public — 可查詢、可廣播已簽名交易（eth_sendRawTransaction）
- Robinhood Chain Testnet: https://api.blockvectra.com/v1/robinhood_testnet/public — 可查詢、可廣播已簽名交易（eth_sendRawTransaction）

下面兩個公開元資料端點可查看服務狀態與各鏈設定，免鑑權、不計費。

### 檢查服務與各鏈健康狀態

```bash
curl https://api.blockvectra.com/v1/status
```

傳回包含檢查時間戳記 `checked_at`、服務運行狀態 `gateway.status`，以及各支援鏈的節點同步進度 `sync`、鏈頭高度與延遲 `head`：

```json
{
  "checked_at": "2026-10-03T13:30:47Z",
  "gateway": {
    "status": "ok"
  },
  "chains": [
    {
      "chain": "bsc_mainnet",
      "name": "BNB Smart Chain",
      "chain_id": 56,
      "jsonrpc": true,
      "data": true,
      "data_features": [
        "blocks",
        "transactions",
        "address_transactions",
        "transfers",
        "token_metadata",
        "freshness"
      ],
      "data_status": "ok",
      "data_head_block": 125492675,
      "data_head_age_seconds": 3,
      "status": "ok",
      "sync": {
        "stage": "synced",
        "node_block": 125492676,
        "target_block": null
      },
      "head": {
        "block": 125492676,
        "time": "2026-10-03T13:30:45Z",
        "lag_seconds": 2
      }
    }
  ]
}
```

### 查詢支援的鏈與方法策略

```bash
curl https://api.blockvectra.com/v1/chains
```

傳回所有支援鏈的 Chain ID、JSON-RPC / Data API / WebSocket 能力識別碼、方法開放與禁用策略（`methods.allow` 與 `methods.deny`）、日誌單次查詢區間上限 `max_logs_block_range`，以及歷史狀態視窗 `state_window_blocks`：

```json
{
  "chains": [
    {
      "chain": "bsc_mainnet",
      "name": "BNB Smart Chain",
      "chain_id": 56,
      "jsonrpc": true,
      "data": true,
      "ws": false,
      "subscriptions": [],
      "methods": {
        "allow": [
          "eth_blockNumber",
          "eth_call",
          "eth_chainId",
          "eth_getLogs"
        ],
        "deny": [
          "eth_newFilter",
          "eth_subscribe",
          "eth_unsubscribe"
        ]
      },
      "max_logs_block_range": 1000,
      "state_window_blocks": 990000,
      "info": {}
    }
  ]
}
```

### 選擇鏈

BlockVectra 的每個端點都按鏈區分：JSON-RPC 請求在 URL 路徑中帶上鏈名 `{chain}`，Data API 請求則在路由前加上鏈名。目前已開放的鏈及對應鏈名見[支援的鏈](https://docs.blockvectra.com/en/chains/)。

| 鏈 | {chain} | Chain ID | Tracing | 公開端點 | WebSocket | Data API | 帶 key 方法數 | Webhook 推送 | 傳送交易 | 傳送交易（免 key 公開端點） | 歷史狀態保留範圍 | eth_getLogs 單次最大區塊跨度 | Data API 資料集 | 相關測試網 | 相關教學 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| [arb_mainnet RPC 與 Data API](https://blockvectra.com/zh-hant/chains/arb_mainnet/) | arb_mainnet | 42161 | ✓ | `https://api.blockvectra.com/v1/arb_mainnet/public` | 不支援 | 已開放 | 43 | [支援 · 確認數 1–1（預設 1）](https://blockvectra.com/zh-hant/webhooks/), [Webhook 推送指南](https://docs.blockvectra.com/zh/guides/webhook-push/) | 支援 | 支援 | 最近 6,000 個區塊的歷史狀態 | 1,000 個區塊 | 區塊、交易、地址交易、轉帳、代幣中繼資料、資料新鮮度 | 未知 | 未知 |
| [base_mainnet RPC 與 Data API](https://blockvectra.com/zh-hant/chains/base_mainnet/) | base_mainnet | 8453 | — | `https://api.blockvectra.com/v1/base_mainnet/public` | 不支援 | 已開放 | 39 | [支援 · 確認數 1–1（預設 1）](https://blockvectra.com/zh-hant/webhooks/), [Webhook 推送指南](https://docs.blockvectra.com/zh/guides/webhook-push/) | 支援 | 支援 | 最近 10,000 個區塊的歷史狀態 | 1,000 個區塊 | 區塊、交易、地址交易、轉帳、代幣中繼資料、資料新鮮度 | 未知 | [Base](https://docs.blockvectra.com/zh/guides/base/) |
| [bsc_mainnet RPC 與 Data API](https://blockvectra.com/zh-hant/chains/bsc_mainnet/) | bsc_mainnet | 56 | — | `https://api.blockvectra.com/v1/bsc_mainnet/public` | 不支援 | 已開放 | 25 | [支援 · 確認數 1–1（預設 1）](https://blockvectra.com/zh-hant/webhooks/), [Webhook 推送指南](https://docs.blockvectra.com/zh/guides/webhook-push/) | 支援 | 支援 | 最近 100 個區塊的歷史狀態 | 1,000 個區塊 | 區塊、交易、地址交易、轉帳、代幣中繼資料、資料新鮮度 | 未知 | 未知 |
| [以太坊 RPC 與 Data API](https://blockvectra.com/zh-hant/chains/eth_mainnet/) | eth_mainnet | 1 | ✓ | `https://api.blockvectra.com/v1/eth_mainnet/public` | 不支援 | 已開放 | 38 | [支援 · 確認數 1–1（預設 1）](https://blockvectra.com/zh-hant/webhooks/), [Webhook 推送指南](https://docs.blockvectra.com/zh/guides/webhook-push/) | 支援 | 支援 | 最近 250,000 個區塊的歷史狀態 | 1,000 個區塊 | 區塊、交易、地址交易、轉帳、代幣中繼資料、資料新鮮度 | 未知 | 未知 |
| [eth_sepolia RPC 與 Data API](https://blockvectra.com/zh-hant/chains/eth_sepolia/) | eth_sepolia | 11155111 | — | `https://api.blockvectra.com/v1/eth_sepolia/public` | 不支援 | 已開放 | 29 | [支援 · 確認數 1–1（預設 1）](https://blockvectra.com/zh-hant/webhooks/), [Webhook 推送指南](https://docs.blockvectra.com/zh/guides/webhook-push/) | 支援 | 支援 | 未知 | 1,000 個區塊 | 區塊、交易、地址交易、轉帳、代幣中繼資料、資料新鮮度 | 未知 | 未知 |
| [HyperEVM RPC 與 Data API](https://blockvectra.com/zh-hant/chains/hyperevm_mainnet/) | hyperevm_mainnet | 999 | — | `https://api.blockvectra.com/v1/hyperevm_mainnet/public` | 不支援 | 已開放 | 24 | [支援 · 確認數 1–1（預設 1）](https://blockvectra.com/zh-hant/webhooks/), [Webhook 推送指南](https://docs.blockvectra.com/zh/guides/webhook-push/) | 不支援 | 不支援 | 未知 | 1,000 個區塊 | 區塊、交易、地址交易、轉帳、代幣中繼資料、餘額、持有者、NFT、資料新鮮度 | 未知 | [HyperEVM 回填与轮询](https://docs.blockvectra.com/zh/guides/hyperevm-backfill/) |
| [polygon_mainnet RPC 與 Data API](https://blockvectra.com/zh-hant/chains/polygon_mainnet/) | polygon_mainnet | 137 | ✓ | `https://api.blockvectra.com/v1/polygon_mainnet/public` | 不支援 | 已開放 | 43 | [支援 · 確認數 1–1（預設 1）](https://blockvectra.com/zh-hant/webhooks/), [Webhook 推送指南](https://docs.blockvectra.com/zh/guides/webhook-push/) | 支援 | 支援 | 最近 126 個區塊的歷史狀態 | 1,000 個區塊 | 區塊、交易、地址交易、轉帳、代幣中繼資料、資料新鮮度 | 未知 | 未知 |
| [Robinhood Chain RPC 與 Data API](https://blockvectra.com/zh-hant/chains/robinhood_mainnet/) | robinhood_mainnet | 4663 | ✓ | `https://api.blockvectra.com/v1/robinhood_mainnet/public` | 支援 (newHeads, logs) | 已開放 | 43 | [支援 · 確認數 1–1（預設 1）](https://blockvectra.com/zh-hant/webhooks/), [Webhook 推送指南](https://docs.blockvectra.com/zh/guides/webhook-push/) | 支援 | 支援 | 最近 900 個區塊的歷史狀態 | 1,000 個區塊 | 區塊、交易、地址交易、轉帳、代幣中繼資料、餘額、持有者、NFT、DEX 成交、DEX 價格、代幣化股票、Trace、資料新鮮度 | 未知 | [Robinhood Chain](https://docs.blockvectra.com/zh/guides/robinhood-chain/), [股票代币乘数与指标](https://docs.blockvectra.com/zh/guides/stock-token-multiplier/), [代币化股票指标](https://docs.blockvectra.com/zh/guides/stocks/) |
| [robinhood_testnet RPC](https://blockvectra.com/zh-hant/chains/robinhood_testnet/) | robinhood_testnet | 46630 | ✓ | `https://api.blockvectra.com/v1/robinhood_testnet/public` | 支援 (newHeads, logs) | 暫未開放 | 43 | [支援 · 確認數 1–1（預設 1）](https://blockvectra.com/zh-hant/webhooks/), [Webhook 推送指南](https://docs.blockvectra.com/zh/guides/webhook-push/) | 支援 | 支援 | 最近 1,023 個區塊的歷史狀態 | 1,000 個區塊 | 不支援 | 未知 | [测试网水龙头](https://docs.blockvectra.com/zh/guides/robinhood-testnet-faucet/), [Robinhood Chain 测试网入门](https://docs.blockvectra.com/zh/guides/robinhood-testnet-starter/) |

## 拿到 key 之後

### arb_mainnet

#### eth_getLogs

```bash
set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/arb_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/arb_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"
```

[eth_getLogs](https://docs.blockvectra.com/zh/guides/getlogs-block-range/)

#### Data API

```bash
curl -fsS 'https://api.blockvectra.com/v1/data/arb_mainnet/status/freshness' -H "x-api-key: $BLOCKVECTRA_API_KEY"
```

[Data API](https://docs.blockvectra.com/zh/api/data/)

[建立 Webhook 訂閱](https://blockvectra.com/zh-hant/webhooks/) · [建立 Webhook 訂閱](https://docs.blockvectra.com/zh/guides/webhook-push/) · [用量與 CU](https://console.blockvectra.com/usage/) · [儲值](https://console.blockvectra.com/billing/)

### base_mainnet

#### eth_getLogs

```bash
set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/base_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/base_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"
```

[eth_getLogs](https://docs.blockvectra.com/zh/guides/getlogs-block-range/)

#### Data API

```bash
curl -fsS 'https://api.blockvectra.com/v1/data/base_mainnet/status/freshness' -H "x-api-key: $BLOCKVECTRA_API_KEY"
```

[Data API](https://docs.blockvectra.com/zh/api/data/)

[建立 Webhook 訂閱](https://blockvectra.com/zh-hant/webhooks/) · [建立 Webhook 訂閱](https://docs.blockvectra.com/zh/guides/webhook-push/) · [用量與 CU](https://console.blockvectra.com/usage/) · [儲值](https://console.blockvectra.com/billing/)

### bsc_mainnet

#### eth_getLogs

```bash
set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/bsc_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/bsc_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"
```

[eth_getLogs](https://docs.blockvectra.com/zh/guides/getlogs-block-range/)

#### Data API

```bash
curl -fsS 'https://api.blockvectra.com/v1/data/bsc_mainnet/status/freshness' -H "x-api-key: $BLOCKVECTRA_API_KEY"
```

[Data API](https://docs.blockvectra.com/zh/api/data/)

[建立 Webhook 訂閱](https://blockvectra.com/zh-hant/webhooks/) · [建立 Webhook 訂閱](https://docs.blockvectra.com/zh/guides/webhook-push/) · [用量與 CU](https://console.blockvectra.com/usage/) · [儲值](https://console.blockvectra.com/billing/)

### 以太坊

#### eth_getLogs

```bash
set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/eth_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/eth_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"
```

[eth_getLogs](https://docs.blockvectra.com/zh/guides/getlogs-block-range/)

#### Data API

```bash
curl -fsS 'https://api.blockvectra.com/v1/data/eth_mainnet/status/freshness' -H "x-api-key: $BLOCKVECTRA_API_KEY"
```

[Data API](https://docs.blockvectra.com/zh/api/data/)

[建立 Webhook 訂閱](https://blockvectra.com/zh-hant/webhooks/) · [建立 Webhook 訂閱](https://docs.blockvectra.com/zh/guides/webhook-push/) · [用量與 CU](https://console.blockvectra.com/usage/) · [儲值](https://console.blockvectra.com/billing/)

### eth_sepolia

#### eth_getLogs

```bash
set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/eth_sepolia' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/eth_sepolia' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"
```

[eth_getLogs](https://docs.blockvectra.com/zh/guides/getlogs-block-range/)

#### Data API

```bash
curl -fsS 'https://api.blockvectra.com/v1/data/eth_sepolia/status/freshness' -H "x-api-key: $BLOCKVECTRA_API_KEY"
```

[Data API](https://docs.blockvectra.com/zh/api/data/)

[建立 Webhook 訂閱](https://blockvectra.com/zh-hant/webhooks/) · [建立 Webhook 訂閱](https://docs.blockvectra.com/zh/guides/webhook-push/) · [用量與 CU](https://console.blockvectra.com/usage/) · [儲值](https://console.blockvectra.com/billing/)

### HyperEVM

#### eth_getLogs

```bash
set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/hyperevm_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/hyperevm_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"
```

[eth_getLogs](https://docs.blockvectra.com/zh/guides/getlogs-block-range/)

#### Data API

```bash
curl -fsS 'https://api.blockvectra.com/v1/data/hyperevm_mainnet/status/freshness' -H "x-api-key: $BLOCKVECTRA_API_KEY"
```

[Data API](https://docs.blockvectra.com/zh/api/data/)

[建立 Webhook 訂閱](https://blockvectra.com/zh-hant/webhooks/) · [建立 Webhook 訂閱](https://docs.blockvectra.com/zh/guides/webhook-push/) · [用量與 CU](https://console.blockvectra.com/usage/) · [儲值](https://console.blockvectra.com/billing/)

### polygon_mainnet

#### eth_getLogs

```bash
set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/polygon_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/polygon_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"
```

[eth_getLogs](https://docs.blockvectra.com/zh/guides/getlogs-block-range/)

#### Data API

```bash
curl -fsS 'https://api.blockvectra.com/v1/data/polygon_mainnet/status/freshness' -H "x-api-key: $BLOCKVECTRA_API_KEY"
```

[Data API](https://docs.blockvectra.com/zh/api/data/)

[建立 Webhook 訂閱](https://blockvectra.com/zh-hant/webhooks/) · [建立 Webhook 訂閱](https://docs.blockvectra.com/zh/guides/webhook-push/) · [用量與 CU](https://console.blockvectra.com/usage/) · [儲值](https://console.blockvectra.com/billing/)

### Robinhood Chain

#### eth_getLogs

```bash
set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/robinhood_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/robinhood_mainnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"
```

[eth_getLogs](https://docs.blockvectra.com/zh/guides/getlogs-block-range/)

#### Data API

```bash
curl -fsS 'https://api.blockvectra.com/v1/data/robinhood_mainnet/status/freshness' -H "x-api-key: $BLOCKVECTRA_API_KEY"
```

[Data API](https://docs.blockvectra.com/zh/api/data/)

#### WebSocket

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]}' | websocat --no-close -H="x-api-key: $BLOCKVECTRA_API_KEY" 'wss://api.blockvectra.com/v1/robinhood_mainnet'
```

[WebSocket](https://docs.blockvectra.com/zh/guides/websocket-subscriptions/)

[建立 Webhook 訂閱](https://blockvectra.com/zh-hant/webhooks/) · [建立 Webhook 訂閱](https://docs.blockvectra.com/zh/guides/webhook-push/) · [用量與 CU](https://console.blockvectra.com/usage/) · [儲值](https://console.blockvectra.com/billing/)

### robinhood_testnet

#### eth_getLogs

```bash
set -eu
MAX_LOGS_BLOCK_RANGE=1000
head=$(curl -fsS 'https://api.blockvectra.com/v1/robinhood_testnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}' | python3 -c 'import json,sys; print(int(json.load(sys.stdin)["result"],16))')
from=$((head >= MAX_LOGS_BLOCK_RANGE ? head - MAX_LOGS_BLOCK_RANGE + 1 : 0))
from_hex=$(printf '0x%x' "$from")
to_hex=$(printf '0x%x' "$head")
curl -fsS 'https://api.blockvectra.com/v1/robinhood_testnet' -H "x-api-key: $BLOCKVECTRA_API_KEY" -H 'Content-Type: application/json' \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"eth_getLogs\",\"params\":[{\"fromBlock\":\"$from_hex\",\"toBlock\":\"$to_hex\"}]}"
```

[eth_getLogs](https://docs.blockvectra.com/zh/guides/getlogs-block-range/)

#### WebSocket

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]}' | websocat --no-close -H="x-api-key: $BLOCKVECTRA_API_KEY" 'wss://api.blockvectra.com/v1/robinhood_testnet'
```

[WebSocket](https://docs.blockvectra.com/zh/guides/websocket-subscriptions/)

[建立 Webhook 訂閱](https://blockvectra.com/zh-hant/webhooks/) · [建立 Webhook 訂閱](https://docs.blockvectra.com/zh/guides/webhook-push/) · [用量與 CU](https://console.blockvectra.com/usage/) · [儲值](https://console.blockvectra.com/billing/)

**HyperEVM**
HyperEVM 的區塊包含 HyperCore 系統交易（傳送方地址為 0x2222…2222 或 0x20…，gasPrice 為 0）。
該鏈暫不支援傳送交易（`eth_sendRawTransaction` 傳回 `-32601` `method_not_allowed`），讀取方法正常。

[檢視即時狀態 →](https://blockvectra.com/zh-hant/status/)

本頁所有範例均使用 `robinhood_mainnet`。

> **提示**：先在上表中選擇支援範例所需服務、方法與歷史視窗的鏈，再把範例 URL 中的 `robinhood_mainnet` 換成它的 `{chain}`。同一個 API key 適用於所有支援的鏈。

### 其他認證方式與語言範例

JSON-RPC 端點按鏈區分：`POST /v1/{chain}/{api_key}`（key 放在路徑中），或 `POST /v1/{chain}`（key 放在 `x-api-key` 請求標頭中）。`{chain}` 是鏈名，與 Data API 使用的鏈名相同；Robinhood Chain 的鏈名是 `robinhood_mainnet`，所以本頁範例使用的端點是 `https://api.blockvectra.com/v1/robinhood_mainnet`。透過 HTTP 呼叫 `eth_subscribe` 傳回 `-32601`；各鏈的 WebSocket 訂閱支援情況見[支援的鏈](https://docs.blockvectra.com/en/chains/)。雖然 API 傳回了 `Access-Control-Allow-Origin: *`，但請妥善保管 API key，端點設計為由後端服務呼叫，而非在瀏覽器前端程式碼中直接暴露 key。

key 有三種傳法：放在 URL 路徑中（`POST /v1/{chain}/{api_key}`，只使用路徑中的 key，忽略兩個請求標頭）、放在 `x-api-key` 請求標頭中，或放在 `Authorization: Bearer <api_key>` 請求標頭中。

#### key 放在 URL 路徑中

**cURL**

```bash
: "${BLOCKVECTRA_API_KEY:?先設定 BLOCKVECTRA_API_KEY}"

curl -s "https://api.blockvectra.com/v1/robinhood_mainnet/$BLOCKVECTRA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
```


  **TypeScript**

```ts
import { createPublicClient, http } from "viem";

const key = process.env.BLOCKVECTRA_API_KEY!;
const client = createPublicClient({
  transport: http(`https://api.blockvectra.com/v1/robinhood_mainnet/${key}`),
});

console.log(await client.getBlockNumber());

// 運行方式：npx tsx example.mts
```

完整模板倉庫：[blockvectra/multichain-viem](https://github.com/blockvectra/multichain-viem)


  **Python**

```python
import os

from web3 import Web3

w3 = Web3(Web3.HTTPProvider("https://api.blockvectra.com/v1/robinhood_mainnet/" + os.environ["BLOCKVECTRA_API_KEY"]))
print(w3.eth.block_number)
```


  **Go**

```go
// 運行方式：go mod init example && go get github.com/ethereum/go-ethereum && go mod tidy && go run .
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/ethereum/go-ethereum/ethclient"
)

func main() {
	client, err := ethclient.Dial("https://api.blockvectra.com/v1/robinhood_mainnet/" + os.Getenv("BLOCKVECTRA_API_KEY"))
	if err != nil {
		log.Fatal(err)
	}
	number, err := client.BlockNumber(context.Background())
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(number)
}
```


  **Rust**

```toml
[dependencies]
alloy = { version = "1", features = ["provider-http", "rpc-types"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
```

```rust
use alloy::providers::{Provider, ProviderBuilder};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let key = std::env::var("BLOCKVECTRA_API_KEY")?;
    let url = format!("https://api.blockvectra.com/v1/robinhood_mainnet/{key}");
    let provider = ProviderBuilder::new().connect_http(url.parse()?);
    println!("{}", provider.get_block_number().await?);
    Ok(())
}
```


#### key 放在請求標頭中

**cURL**

```bash
: "${BLOCKVECTRA_API_KEY:?Set BLOCKVECTRA_API_KEY first}"

curl -s "https://api.blockvectra.com/v1/robinhood_mainnet" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
```


  **TypeScript**

```ts
import { createPublicClient, http } from "viem";

const key = process.env.BLOCKVECTRA_API_KEY!;
const client = createPublicClient({
  transport: http("https://api.blockvectra.com/v1/robinhood_mainnet", {
    fetchOptions: { headers: { "x-api-key": key } },
  }),
});

console.log(await client.getBlockNumber());

// 運行方式：npx tsx example.mts
```


  **Python**

```python
import os

from web3 import Web3

key = os.environ["BLOCKVECTRA_API_KEY"]
# request_kwargs 會整體替換掉 provider 的預設請求標頭，所以這裡必須重新帶上
# Content-Type，否則伺服器端無法解析請求體。
headers = {"Content-Type": "application/json", "x-api-key": key}
w3 = Web3(Web3.HTTPProvider("https://api.blockvectra.com/v1/robinhood_mainnet", request_kwargs={"headers": headers}))
print(w3.eth.block_number)
```


  **Go**

```go
// 運行方式：go mod init example && go get github.com/ethereum/go-ethereum && go mod tidy && go run .
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/ethereum/go-ethereum/ethclient"
	"github.com/ethereum/go-ethereum/rpc"
)

func main() {
	ctx := context.Background()
	c, err := rpc.DialOptions(ctx, "https://api.blockvectra.com/v1/robinhood_mainnet", rpc.WithHeader("x-api-key", os.Getenv("BLOCKVECTRA_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	number, err := ethclient.NewClient(c).BlockNumber(ctx)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(number)
}
```


  **Rust**

```toml
[dependencies]
alloy = { version = "1", features = ["provider-http", "rpc-types"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
reqwest = "0.13"
```

```rust
use alloy::providers::{Provider, ProviderBuilder};
use alloy::rpc::client::RpcClient;
use reqwest::header::{HeaderMap, HeaderValue};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let key = std::env::var("BLOCKVECTRA_API_KEY")?;

    let mut headers = HeaderMap::new();
    headers.insert("x-api-key", HeaderValue::from_str(&key)?);
    let http_client = reqwest::Client::builder().default_headers(headers).build()?;

    let rpc_client = RpcClient::new_http_with_client(http_client, "https://api.blockvectra.com/v1/robinhood_mainnet".parse()?);
    let provider = ProviderBuilder::new().connect_client(rpc_client);

    println!("{}", provider.get_block_number().await?);
    Ok(())
}
```


> **不要加結尾斜槓**
>
> 用請求標頭傳 key 時，請按上面的寫法原樣呼叫 `https://api.blockvectra.com/v1/robinhood_mainnet`：URL 以鏈名結尾，**不帶**結尾斜槓。
>   JSON-RPC 只在 `/v1/{chain}` 和 `/v1/{chain}/{api_key}` 兩種路徑上提供，帶結尾斜槓（如 `/v1/{chain}/`）或不帶鏈段的請求（如 `/v1` 或 `/v1/`）傳回 404 且回應體為空。


`Authorization: Bearer <api_key>` 請求標頭同樣有效。在 `POST /v1/{chain}` 上，非空的
`x-api-key` 優先於 Bearer；只有 `x-api-key` 缺失或為空時才使用 Bearer。路徑傳法忽略兩個請求標頭。

### 批次呼叫

傳一個陣列即可在一次請求裡發起多個呼叫（單批最多 100 個）。注意每個 API key 都有一個 CU 權杖桶（`cu_per_sec` 補充速率、`burst_cu` 突發容量——預設 400 CU/s、突發 1,600 CU；在控制台 Keys 表按 key 顯示）；單個請求（包括整批 JSON-RPC 批次呼叫）若總 CU 超過該 key 的突發容量，即使未達到 100 個呼叫的上限也會被拒絕並傳回 `-32022 request_exceeds_burst`；需拆分為較小的批次。下面這個範例在一次往返裡
同時讀取鏈 ID 和某個地址的餘額：

**cURL**

```bash
curl -s "https://api.blockvectra.com/v1/robinhood_mainnet" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -d '[
    {"jsonrpc":"2.0","id":1,"method":"eth_chainId"},
    {"jsonrpc":"2.0","id":2,"method":"eth_getBalance","params":["0x1111111111111111111111111111111111111111","latest"]}
  ]'
```


  **TypeScript**

```ts
import { createPublicClient, http } from "viem";

const key = process.env.BLOCKVECTRA_API_KEY!;
const client = createPublicClient({
  transport: http("https://api.blockvectra.com/v1/robinhood_mainnet", {
    batch: true,
    fetchOptions: { headers: { "x-api-key": key } },
  }),
});

// viem 會把同時發出的請求自動合併成一次 JSON-RPC 批次呼叫。
const [chainId, balance] = await Promise.all([
  client.getChainId(),
  client.getBalance({ address: "0x1111111111111111111111111111111111111111" }),
]);
console.log(chainId, balance);

// 運行方式：npx tsx example.mts
```


  **Python**

```python
import os

from web3 import Web3

key = os.environ["BLOCKVECTRA_API_KEY"]
headers = {"Content-Type": "application/json", "x-api-key": key}
w3 = Web3(Web3.HTTPProvider("https://api.blockvectra.com/v1/robinhood_mainnet", request_kwargs={"headers": headers}))

with w3.batch_requests() as batch:
    batch.add(w3.eth.chain_id)
    batch.add(w3.eth.get_balance("0x1111111111111111111111111111111111111111"))
    chain_id, balance = batch.execute()

print(chain_id, balance)
```


  **Go**

```go
// 運行方式：go mod init example && go get github.com/ethereum/go-ethereum && go mod tidy && go run .
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/ethereum/go-ethereum/rpc"
)

func main() {
	ctx := context.Background()
	c, err := rpc.DialOptions(ctx, "https://api.blockvectra.com/v1/robinhood_mainnet", rpc.WithHeader("x-api-key", os.Getenv("BLOCKVECTRA_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}

	var chainID, balance string
	calls := []rpc.BatchElem{
		{Method: "eth_chainId", Result: &chainID},
		{Method: "eth_getBalance", Args: []any{"0x1111111111111111111111111111111111111111", "latest"}, Result: &balance},
	}
	if err := c.BatchCallContext(ctx, calls); err != nil {
		log.Fatal(err)
	}
	for _, call := range calls {
		if call.Error != nil {
			log.Fatal(call.Error)
		}
	}
	fmt.Println(chainID, balance)
}
```


  **Rust**

```toml
[dependencies]
alloy = { version = "1", features = ["provider-http", "rpc-types"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
reqwest = "0.13"
```

```rust
use alloy::primitives::{Address, U256};
use alloy::rpc::client::RpcClient;
use reqwest::header::{HeaderMap, HeaderValue};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let key = std::env::var("BLOCKVECTRA_API_KEY")?;

    let mut headers = HeaderMap::new();
    headers.insert("x-api-key", HeaderValue::from_str(&key)?);
    let http_client = reqwest::Client::builder().default_headers(headers).build()?;
    let rpc_client = RpcClient::new_http_with_client(http_client, "https://api.blockvectra.com/v1/robinhood_mainnet".parse()?);

    let address: Address = "0x1111111111111111111111111111111111111111".parse()?;
    let mut batch = rpc_client.new_batch();
    let chain_id = batch.add_call::<_, U256>("eth_chainId", &())?;
    let balance = batch.add_call::<_, U256>("eth_getBalance", &(address, "latest"))?;
    batch.send().await?;

    println!("{} {}", chain_id.await?, balance.await?);
    Ok(())
}
```


回應是一個陣列，順序與請求一致，按 `id` 對應。

如果伺服器端直接拒絕整個批次請求——餘額不足、限流、突發容量超限，或批次過大（見下方[常見錯誤](#common-errors)）——它會傳回一個單獨的 JSON-RPC 錯誤物件而不是陣列；此時 viem 的 `batch: true` 模式只會報出一個不透明的 `UnknownRpcError`，請改為單獨重試一次呼叫以查看真實錯誤。

### 了解 CU 計量

每個被計費的呼叫都會消耗一定的 **CU（Compute Unit）**：便宜的呼叫比如 `eth_blockNumber`、
`eth_chainId` 最便宜；常見讀取比如 `eth_getBlockByNumber` 稍貴；較重的呼叫比如
`eth_call`、`eth_getLogs` 更貴；執行跟蹤方法（如 `debug_traceTransaction`）最貴。
結算按帳戶、按小時週期彙總扣費，無條件捨去為整數計費單位（1 計費單位 = 1,000 CU），未滿 1 單位的餘數結轉到下一期（跨期合計扣費為 `floor(累計 CU / 1,000)`）；結算在結算時段結束約 15 分鐘後執行。例如：上期結轉 508 CU，本期消耗 2557 CU，合計 3065 CU，本期扣除 3 個計費單位，餘數 65 CU 繼續結轉至下一期。目前價格見[定價](https://blockvectra.com/en/pricing/)。

完整的方法權重表與錯誤碼見 [API 參考 → JSON-RPC](https://docs.blockvectra.com/en/api/json-rpc/)；
本頁只演示請求的基本形態。

#### 常見錯誤

| 你做了什麼                                                                                                                               | 會收到什麼                                                                   | 建議操作                                                                                                                           |
| ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| 未知或暫未開放的鏈名                                                                                                                          | HTTP `404`，JSON 回應體包含 `error.data.reason: "unknown_chain"`              | 檢查 URL 中的鏈名                                                                                                                    |
| 不帶鏈段的請求（如 `/v1` 或 `/v1/`）                                                                                                           | HTTP `404`，空 body                                                       | 在 URL 中補全鏈名（`/v1/{chain}`）                                                                                                     |
| API key 缺失、未知或被禁用                                                                                                                   | HTTP `401`，JSON-RPC 錯誤碼 `-32024`（`missing_api_key` 或 `invalid_api_key`） | 使用有效且處於生效中的 API key（剛新建或輪換的 key 約 5 秒內在所有實例生效；這期間可能傳回 401 `invalid_api_key`，或計費狀態暫未確認時傳回 503 `-32021`（帶 `Retry-After`），稍等重試即可） |
| 餘額為零或為負                                                                                                                             | HTTP `402`，JSON-RPC 錯誤碼 `-32020`                                        | 儲值或等待免費額度週期補足                                                                                                                  |
| 請求過於頻繁（超出限流或伺服器端臨時過載）                                                                                                               | HTTP `429`（或 `200`），JSON-RPC 錯誤碼 `-32005`                               | 稍後重試（若回應標頭帶 `Retry-After` 請按其等待）                                                                                               |
| 單個請求或整批呼叫的 CU 超過 key 突發容量（`burst_cu`，預設 1,600 CU；預設速率 400 CU/s），或免費方案單批呼叫數超過每秒上限（25 次/秒）                                                             | HTTP `429`，JSON-RPC 錯誤碼 `-32022`（`request_exceeds_burst`）               | 拆分請求或減小批次（按原樣傳送永遠不會成功）                                                                                                         |
| 上游節點暫時不可用                                                                                                                           | HTTP `200`，JSON-RPC 錯誤碼 `-32603`（`upstream unavailable`），不計費            | 重試請求                                                                                                                           |
| 歷史狀態查詢超出該鏈的狀態視窗（見 `GET /v1/chains` 的 `state_window_blocks`）                                                                         | HTTP `200`，JSON-RPC 錯誤碼 `-32011`，不計費                                    | 改查較新的區塊                                                                                                                        |
| 交易或區塊未找到，或回應過大；以太坊上超出近期視窗的區塊 / 收據 / 日誌查詢亦傳回 -32000 "old data not available due to pruning"（不計費，見[支援的鏈 → 以太坊](https://docs.blockvectra.com/en/chains/#ethereum)） | HTTP `200`，JSON-RPC 錯誤碼 `-32000`                                        | 修改請求（核對交易哈希或區塊號；格式不合法的 trace 哈希同樣傳回交易未找到）                                                                                      |
| 使用了不支援的 tracer 或超時參數（`debug_trace` 系列呼叫）                                                                                            | HTTP `200`，JSON-RPC 錯誤碼 `-32602`，不計費                                    | 改用內建原生 tracer（`callTracer`、`flatCallTracer`、`prestateTracer`、`4byteTracer`、`noopTracer`，或預設）且超時時間 ≤ 30s                        |
| 呼叫了該鏈方法表不允許的方法（見[支援的鏈](https://docs.blockvectra.com/en/chains/)）                                                                                                | HTTP `200`，JSON-RPC 錯誤碼 `-32601`，不計費                                    | 僅呼叫該鏈允許的方法                                                                                                                     |
| 請求主體不是合法 JSON                                                                                                                       | HTTP `200`，JSON-RPC 錯誤碼 `-32700`，不計費                                    | 修正 JSON 請求主體語法                                                                                                                 |
| 單批呼叫數超過 100                                                                                                                         | HTTP `200`，JSON-RPC 錯誤碼 `-32600`（`batch too large`），不計費                 | 拆分為不超過 100 個呼叫的批次                                                                                                              |

以上這些拒絕一律不計費；每個被受理並得到應答的呼叫按公布的 CU 權重計費，不計費的情況見[錯誤碼錶](https://docs.blockvectra.com/en/api/json-rpc/#error-codes)的「是否計費」列。

### 呼叫 Data API

Data API 把只讀鏈資料（區塊、交易、餘額、持有者、DEX 活動等）封裝成 REST/JSON 端點。除 `GET https://api.blockvectra.com/v1/data/chains` 外，所有路由都帶鏈識別碼前綴：下面路徑中的 `robinhood_mainnet` 就是鏈識別碼（即 `/chains` 和 `meta` 中的 `chain` 欄位）。`GET https://api.blockvectra.com/v1/data/chains` 僅列出已公開的鏈，只傳回 `{"data": [...]}`（沒有 `meta`，也沒有 `next_cursor`）。請求按 CU 計費（僅對 2xx 成功回應計費）。

每次請求需要帶與 JSON-RPC 相同的 API key——透過 `x-api-key` 請求標頭傳遞。每個鏈相關路由的成功回應都使用同一套信封：`data`（資料本體）、`next_cursor`（不透明字串，只在有下一頁時才出現，否則這個欄位整個不存在，不是 `null`）、以及 `meta`（`chain`、`chain_slug`（`chain` 的大寫形式）、`chain_external_id`、`as_of_block`、`safe_block`、`finalized_block`、`coverage`、`refreshed_at`；`refreshed_at` 可能為 `null`，表示這份資料的更新時間未知，應按過期處理，區塊類端點始終有值）。每個錯誤回應一般是 `{"error":{"code","message"}}` 兩個欄位，僅 `409 not_indexed_yet` 額外帶 `indexed_through`（已索引到的最高區塊）；鏈未知或暫未公開時傳回 HTTP `404`，`error.code` 為 `not_found`（不計費；鏈名必須為全小寫 slug）；API key 缺失、未知或被禁用時傳回 HTTP `401`，`error.code` 為 `missing_api_key` 或 `invalid_api_key`。超出限流時傳回 HTTP `429`（`error.code` 為 `rate_limited`，`data.reason` 為 `key_rate_limit`），餘額耗盡時傳回 HTTP `402`（`error.code` 為 `insufficient_balance`），兩者均不計費。超過 2^53 的數值（餘額、代幣數量）一律是十進位字串，不是 JSON 數字。

**按區塊號查區塊：**

**cURL**

```bash
curl -s "https://api.blockvectra.com/v1/data/robinhood_mainnet/blocks/72838701" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"
```


  **TypeScript**

```ts
const res = await fetch("https://api.blockvectra.com/v1/data/robinhood_mainnet/blocks/72838701", {
  headers: { "x-api-key": process.env.BLOCKVECTRA_API_KEY! },
});
const body = await res.json();
console.log(body);

// 運行方式：npx tsx example.mts
```


  **Python**

```python
import os, requests

res = requests.get(
    "https://api.blockvectra.com/v1/data/robinhood_mainnet/blocks/72838701",
    headers={"x-api-key": os.environ["BLOCKVECTRA_API_KEY"]},
)
print(res.json())
```


```json
{
  "data": {
    "number": 72838701,
    "hash": "0x9f2c1e7a4b6d3f805e1c9a72b4d6f1e0a3c8b5d7e2f4a1c6b9d3e7f0a2c4b6d8",
    "parent_hash": "0x1a3c5e7f9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f1a3c5e7b9d1f3a",
    "timestamp": "2026-09-26T05:41:07Z",
    "miner": "0x00000000000000000000000000000000000a4b05",
    "gas_limit": 32000000,
    "gas_used": 4821932,
    "base_fee_per_gas": "100000000",
    "state_root": "0x2b4d6f8a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d",
    "transactions_root": "0x3c5e7b9d1f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f1a3c5e",
    "receipts_root": "0x4d6f8a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f",
    "tx_count": 239,
    "size": 48213,
    "l1_block_number": null,
    "extra": {}
  },
  "meta": {
    "chain": "robinhood_mainnet",
    "chain_slug": "ROBINHOOD_MAINNET",
    "chain_external_id": "eip155:4663",
    "as_of_block": 72838957,
    "safe_block": 72838800,
    "finalized_block": 72838701,
    "coverage": "full",
    "refreshed_at": "2026-09-27T02:15:03Z"
  }
}
```

高於已索引鏈頭（`as_of_block`）的區塊號傳回 `409`（`error.code: "not_indexed_yet"`），`indexed_through` 會告訴你已索引到的最高區塊——資料還沒到，稍後重試即可。完全早於該鏈覆蓋起點（`coverage.from_block`）的區塊號傳回 `422`（`error.code: "no_coverage"`）。在覆蓋範圍內，不高於 `as_of_block` 但沒有對應行的區塊號（從未索引過，或被 reorg 回滾）傳回 `404`（`error.code: "not_found"`）。

**查看資料新鮮度**（每個被跟蹤的資料集落後鏈頭多少，適合做狀態頁或呼叫前的自檢）：

**cURL**

```bash
curl -s "https://api.blockvectra.com/v1/data/robinhood_mainnet/status/freshness" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"
```


  **TypeScript**

```ts
const res = await fetch("https://api.blockvectra.com/v1/data/robinhood_mainnet/status/freshness", {
  headers: { "x-api-key": process.env.BLOCKVECTRA_API_KEY! },
});
const body = await res.json();
console.log(body);

// 運行方式：npx tsx example.mts
```


  **Python**

```python
import os, requests

res = requests.get(
    "https://api.blockvectra.com/v1/data/robinhood_mainnet/status/freshness",
    headers={"x-api-key": os.environ["BLOCKVECTRA_API_KEY"]},
)
print(res.json())
```


```json
{
  "data": [
    {
      "dataset": "blocks",
      "category": "raw",
      "max_block_number": 72838957,
      "max_day": null,
      "max_time": "2026-09-27T02:15:01Z",
      "seconds_behind": 0,
      "blocks_behind": null,
      "days_behind": null,
      "checked_at": "2026-09-27T02:15:07Z"
    }
  ],
  "meta": {
    "chain": "robinhood_mainnet",
    "chain_slug": "ROBINHOOD_MAINNET",
    "chain_external_id": "eip155:4663",
    "as_of_block": 72838957,
    "safe_block": 72838800,
    "finalized_block": 72838701,
    "coverage": "full",
    "refreshed_at": "2026-09-27T02:15:07Z"
  }
}
```

*（範例已精簡：實際回應每個資料集一行，這裡只列出 `blocks` 這一行；`traces` 行還會額外帶 `coverage_from_block`、`coverage_to_block`、`coverage_complete`。）*

如果該鏈的新鮮度資料暫時不可用，會傳回 `503`（`error.code: "unavailable"`），而不是傳回不完整的結果；回應標頭帶 `Retry-After`（秒）——請至少等待該時長後重試。

**查詢某地址的 ERC-20 餘額**（快照，只保留非零餘額，按 token 排序）：

**cURL**

```bash
curl -s "https://api.blockvectra.com/v1/data/robinhood_mainnet/addresses/0x1111111111111111111111111111111111111111/balances" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"
```


  **TypeScript**

```ts
const res = await fetch(
  "https://api.blockvectra.com/v1/data/robinhood_mainnet/addresses/0x1111111111111111111111111111111111111111/balances",
  { headers: { "x-api-key": process.env.BLOCKVECTRA_API_KEY! } },
);
const body = await res.json();
console.log(body);

// 運行方式：npx tsx example.mts
```


  **Python**

```python
import os, requests

res = requests.get(
    "https://api.blockvectra.com/v1/data/robinhood_mainnet/addresses/0x1111111111111111111111111111111111111111/balances",
    headers={"x-api-key": os.environ["BLOCKVECTRA_API_KEY"]},
)
print(res.json())
```


```json
{
  "data": [
    { "token": "0x0bd7d308f8e1639fab988df18a8011f41eacad73", "balance": "185371464119396", "symbol": "WETH", "decimals": 18 },
    { "token": "0x2295f15bd4914ae9b4685f01d52f4e6f89bf8b03", "balance": "10000000000000000", "symbol": "WNVDA", "decimals": 18 }
  ],
  "meta": {
    "chain": "robinhood_mainnet",
    "chain_slug": "ROBINHOOD_MAINNET",
    "chain_external_id": "eip155:4663",
    "as_of_block": 72838957,
    "safe_block": 72838800,
    "finalized_block": 72838701,
    "coverage": "full",
    "refreshed_at": "2026-09-27T02:10:00Z"
  }
}
```

沒有任何非零餘額的地址仍會傳回 `200` + `data: []`——不會是 `404`。可以傳 `?limit=`（預設 50，最大 500），並用傳回的 `next_cursor` 翻頁。

完整的端點覆蓋——區塊、交易、地址、代幣、NFT、DEX、代幣化股票——參見 [API 參考 → Data API](https://docs.blockvectra.com/en/api/data/)。

### 更多參考

* [API 參考 → JSON-RPC](https://docs.blockvectra.com/en/api/json-rpc/) —— 方法、CU 權重、錯誤碼
* [完整 JSON-RPC 參考](https://docs.blockvectra.com/zh/api/json-rpc/reference/) —— 全部支援方法的完整規範、請求參數與傳回格式
* [API 參考 → Data API](https://docs.blockvectra.com/en/api/data/) —— 鏈資料的 REST 端點
* [資料集](https://docs.blockvectra.com/zh/datasets/) —— 各支援鏈上可用的派生資料集
* [指南](https://docs.blockvectra.com/zh/guides/) —— API 集成、CU 用量管理與多鏈工作流實戰指南
* [支援的鏈](https://docs.blockvectra.com/en/chains/) —— 網路識別碼與端點 URL

## 常見問題

### 支援哪些鏈？

目前支援 9 條鏈：Arbitrum One、Base、BNB Smart Chain、以太坊、Ethereum Sepolia、HyperEVM、Polygon、Robinhood Chain、Robinhood Chain Testnet。以 GET /v1/chains 為準，新鏈上線後自動出現。各鏈即時狀態見[狀態頁](https://blockvectra.com/zh-hant/status/)。 [檢視支援的鏈](https://blockvectra.com/zh-hant/chains/)

### 支援 WebSocket 嗎？

透過 HTTP 呼叫 eth_subscribe 回傳 -32601；在 /v1/chains 中 ws 為 true 的鏈上，可以透過 WebSocket 使用 eth_subscribe；其他情況請輪詢 eth_getLogs。 [檢視支援的鏈列表](https://blockvectra.com/zh-hant/chains/)

### 能查歷史狀態和 trace 嗎？

可以，但因鏈而異。歷史狀態保留範圍以 /v1/chains 的 state_window_blocks 欄位為準（null 表示全歷史）；trace 是否開放看該鏈 methods.allow 是否包含 debug_trace 系列方法（如 debug_traceTransaction）；單次 eth_getLogs 的區塊跨度上限是 max_logs_block_range。 [檢視鏈目錄與逐鏈參數](https://blockvectra.com/zh-hant/chains/)

### 一個 key 能用於所有鏈嗎？

可以。同一個 API key 適用於所有支援鏈的 JSON-RPC，並在已開放的鏈上呼叫 Data API；key 屬於帳戶，不綁定特定鏈。 [檢視「一個 key 切鏈」指南](https://docs.blockvectra.com/zh/guides/one-key-many-chains/)