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

查詢合約事件日誌用 eth_getLogs,已索引的 ERC-20 與 ERC-721 轉帳歷史用代幣轉帳 API,支援按地址或按代幣合約讀取,使用游標分頁,超出涵蓋範圍時傳回 422,已被修剪的歷史傳回 4444。

對於錢包歷史記錄或 ERC-20 轉帳對帳,請從代幣轉帳 API 開始。當你需要合約事件日誌時,請使用 eth_getLogs。開發者與 AI Agent 可透過相同的區塊鏈資料 API 查詢已索引的地址轉帳記錄。錢包資產指南結合了代幣餘額、轉帳歷史記錄與中繼資料;Data 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 轉帳端點提供的內容

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

端點standard區塊範圍
GET /{chain}/addresses/{address}/transfers必填:erc20 或 erc721。erc1155 回傳 422 no_coveragefrom_block 與 to_block 均為必填。結果按 (block_number, log_index) 降序排列。direction(in、out 或 any;預設 any)按方向過濾,token 可選填以將結果限制為單一合約。
GET /{chain}/tokens/{token}/transfers必填:erc20、erc721 或 erc1155from_block 與 to_block 為選填。省略 to_block 時預設為 as_of_block;顯式傳入高於它的 to_block 或 from_block 會直接回傳硬錯誤 409 not_indexed_yet,沒有 clamp 規避機制。

分頁

兩個端點均採用鍵集分頁(keyset-paginated):

  • limit 預設為 50;高於 500 的值被限制為 500,且 0 或非整數回傳 400 bad_request。
  • 傳回 limit 筆記錄的頁面可能包含 next_cursor,即使已經沒有更多記錄。繼續使用傳回的游標,直到該欄位缺失;最後一次讀取可能傳回空的 data 陣列。沒有游標時,該欄位會整個省略,不會傳回 null。
  • 將回傳的值原樣傳回為 cursor 以取得下一頁。游標僅對簽發它的鏈、端點與查詢參數有效。

覆蓋範圍與最終性

對 GET /{chain}/tokens/{token}/transfers,覆蓋範圍以所請求 standard 的代幣轉帳資料集為準,而非只看鏈的起點。當該資料集有記錄的建置覆蓋起點較晚時,其下界可能高於鏈的 coverage.from_block。完全早於該下界的區間會回傳 422 no_coverage;起點早於該下界、或未提供 from_block 的區間,會依資料集實際提供的範圍傳回,並標記 meta.coverage = "partial"。meta.as_of_block 是已完整寫入的最新區塊(寫入水位),並不證明從下界到它之間的每個區塊都已建立索引。地址端點仍然要求同時提供 from_block 與 to_block;不要把這條代幣端點的下界規則套用到所有轉帳路由。哪些鏈提供該資料集,請參閱支援的鏈。

在由舊到新的歷史回填中,已回填尾端與即時起點之間的缺口不會被偵測到:完全落在這個缺口裡的區間仍可能回傳 200 和空 data 陣列。HTTP 成功、空結果、遍歷完所有游標,或單單一個覆蓋欄位,都不能證明整段範圍完整。請對照預期資料或自己的核對結果驗證完整性。

每個轉帳項目包含 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只要不超過該鏈的 max_logs_block_range,一次請求即可涵蓋近期的範圍。
某個地址的歷史轉帳GET /{chain}/addresses/{address}/transfers具備 from_block/to_block 範圍、direction 與 token 過濾器以及游標分頁的地址範圍查詢;結果提供至 as_of_block。
某個代幣的全部轉帳GET /{chain}/tokens/{token}/transfers涵蓋 erc20、erc721 與 erc1155 的代幣合約範圍查詢,具備選填區塊範圍與游標分頁,遍歷資料集實際提供的範圍。
即時監聽新事件eth_subscribe(WebSocket 鏈)/ eth_getLogs(輪詢)在支援的鏈上透過 WebSocket 訂閱新區塊頭或日誌,或輪詢近期區塊範圍。

使用 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:

單次呼叫的 CU 權重

方法單次呼叫 CU
eth_getLogs30
data.address_transfers25
data.token_transfers25

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

估算區塊區間的呼叫次數與 CU

區塊區間包含兩端:N = to_block - from_block + 1。如果每次範圍請求最多涵蓋 S 個區塊,一次成功遍歷至少需要 ceil(N / S) 次請求。例如 10,000,000 個區塊、每次 5 個區塊是 2,000,000 次請求;每次 10,000 個區塊是 1,000 次。這些只是算術範例,不代表對任意鏈或 provider 上限的承諾。

失敗與重試會增加請求,結果大小限制也一樣。縮小區間不自動等於更省:呼叫次數變多可能抵消區間變窄,而 CU 按每次呼叫的權重計費。已建立索引的轉帳按結果分頁,不按區塊數分頁,因此一次遍歷可能需要更多頁,包括最後可能出現的空頁;不要用區塊數直接推算頁數。把上方每次呼叫的權重乘以預期計費呼叫次數來估算 CU,目前價格請參閱定價頁面。

下一步

最後更新:

本頁目錄