eth_getLogs 與代幣轉帳 API：ERC-20 轉帳歷史查詢

對於錢包歷史記錄或 ERC-20 轉帳對帳，請從代幣轉帳 API 開始。當你需要合約事件日誌時，請使用 eth_getLogs。開發者與 AI Agent 可透過相同的區塊鏈資料 API 查詢已索引的地址轉帳記錄。錢包資產指南結合了代幣餘額、轉帳歷史記錄與中繼資料；Data API 參考定義了請求參數與回應結構定義。

這篇指南協助你完成的任務

• 查詢合約事件日誌：在有界區塊範圍內透過帶驗證的 RPC 進行監控或日誌回填。
• 查詢已索引的 ERC-20 轉帳歷史記錄：透過區塊鏈資料 API 按地址或代幣合約查詢，支援游標分頁與覆蓋範圍檢查。

讀取日誌與轉帳的兩種方式

eth_getLogs 是一個 JSON-RPC 方法：它透過 JSON-RPC 端點回傳區塊日誌。Data API 則透過兩個以鏈為範圍的端點公開代幣轉帳歷史記錄：

• GET /{chain}/addresses/{address}/transfers — 涉及某地址的轉帳。
• GET /{chain}/tokens/{token}/transfers — 單一代幣合約的轉帳。

兩者使用相同的 API key，並按方法權重以 CU 計量（見下方的權重表）。選擇哪一個取決於資料的新舊程度、是否需要區塊範圍，以及如何進行分頁。

適用於 eth_getLogs 的限制

eth_getLogs 受公開的 GET /v1/chains 回應發布的逐鏈限制約束：

• 區塊跨度：max_logs_block_range 是單次 eth_getLogs 請求可跨越的最大區塊數。該限制因鏈而異 — 請從 GET /v1/chains 讀取（鏈清單見支援的鏈），切勿寫死在程式碼中。超過該範圍將被拒絕並回傳 JSON-RPC 錯誤 -32602 eth_getLogs block range too large（不計費）。
• 節點同步：當鏈的節點未同步時，eth_getLogs 回傳 -32010（不計費）。
• 狀態保留範圍：GET /v1/chains 報告為 state_window_blocks 的狀態保留範圍適用於狀態讀取方法（例如 eth_call 與 eth_getBalance），不適用於 eth_getLogs。
• 節點修剪：區塊與日誌讀取不受狀態保留範圍限制，但受節點保留歷史記錄的限制。已被修剪的資料回傳 4444 pruned history unavailable（不計費）。

當過濾欄位 fromBlock 與 toBlock 省略或為 null 時，預設為 latest。

透過 HTTP 呼叫 eth_subscribe 會回傳 -32601 method not available。在 /v1/chains 中 ws 為 true 的鏈上，可透過 WebSocket 使用 eth_subscribe（參見支援的鏈）；否則，請在最新區塊上輪詢 eth_getLogs。

Data API 轉帳端點提供的內容

這兩個端點需要不同的參數：

分頁

兩個端點均採用鍵集分頁（keyset-paginated）：

• limit 預設為 50；高於 500 的值被限制為 500，且 0 或非整數回傳 400 bad_request。
• 僅在存在另一頁時才出現 next_cursor。在最後一頁上，該鍵完全不存在，絕非 null。
• 將回傳的值原樣傳回為 cursor 以取得下一頁。游標僅對簽發它的鏈、端點與查詢參數有效。

覆蓋範圍與最終性

Data API 轉帳從每條鏈的 coverage.from_block 到 meta.as_of_block 索引歷史代幣轉帳。有關提供該功能的鏈，請參閱支援的鏈。

每個轉帳項目包含 token、standard、from、to、block_number、block_timestamp、tx_hash、tx_index 與 log_index。ERC-20 項目增加 amount；ERC-721 項目增加 token_id；ERC-1155 項目增加 operator、token_id、value 與 batch_index。

該選用哪一個

使用 eth_getLogs 查詢日誌

export BLOCKVECTRA_API_KEY=rgw_your_api_key

# fromBlock / toBlock 預設為 latest。設定明確的近期範圍以跟隨
# 新事件，並將其跨度保持在鏈的 max_logs_block_range 之內。
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_getLogs",
    "params": [{
      "address": "0x1111111111111111111111111111111111111111",
      "fromBlock": "latest",
      "toBlock": "latest"
    }]
  }'

使用 Data API 查詢轉帳

export BLOCKVECTRA_API_KEY=rgw_your_api_key

# 這裡 from_block / to_block 為選填；省略 to_block 時預設為 as_of_block。
curl -s "https://api.blockvectra.com/v1/data/robinhood_mainnet/tokens/0x1111111111111111111111111111111111111111/transfers?standard=erc20" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

若改為按地址查詢，則 from_block 與 to_block 均為必填：

# clamp=true 會截斷過寬的區間或高於 as_of_block 的 to_block，
# 而不是回傳 409。
curl -s "https://api.blockvectra.com/v1/data/robinhood_mainnet/addresses/0x1111111111111111111111111111111111111111/transfers?standard=erc20&from_block=0&to_block=73000000&direction=any&clamp=true" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

單次呼叫的 CU

每個方法都依其 CU 權重計費。下方權重讀取自平台方案 API：

有關目前的價格與儲值選項，請參閱定價頁面。

下一步

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