eth_getLogs vs Token Transfers API: ERC-20 전송 내역 조회
컨트랙트 이벤트 로그는 eth_getLogs, 인덱싱된 ERC-20 전송 내역은 Token Transfers API를 선택하세요. 블록 범위, 페이지네이션, 커버리지 및 완결성을 비교합니다.
지갑 내역 조회나 ERC-20 전송 대사 작업에는 Token Transfers API로 시작하는 것이 좋습니다. 컨트랙트 이벤트 로그가 필요한 경우에는 eth_getLogs를 사용하세요. 개발자와 AI 에이전트는 동일한 블록체인 Data API를 통해 인덱싱된 주소 전송 내역을 조회할 수 있습니다. 지갑 자산 가이드는 토큰 잔액, 전송 내역 및 메타데이터를 결합하며, Data API 레퍼런스에서 요청 파라미터와 응답 스키마를 정의합니다.
이 가이드에서 다루는 작업
- 모니터링 또는 로그 백필을 위해 제한된 블록 범위에서 인증된 RPC로 컨트랙트 이벤트 로그 조회.
- 커서 페이지네이션 및 커버리지 확인을 거쳐 블록체인 Data API를 통해 주소 또는 토큰 컨트랙트별로 인덱싱된 ERC-20 전송 내역 조회.
로그 및 전송을 읽는 두 가지 방식
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에는 적용되지 않습니다. - 노드 프루닝(Pruning): 블록 및 로그 조회는 상태 윈도우의 제한을 받지 않지만, 노드에 보관된 기록에 의해 제한됩니다. 프루닝되어 보관되지 않은 데이터는
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_coverage 반환 | from_block 및 to_block 모두 필수. 결과는 (block_number, log_index) 내림차순으로 정렬됩니다. direction(in, out, any; 기본값 any)은 방향별로 필터링하며, token을 사용하여 특정 컨트랙트로 결과를 제한할 수 있습니다. |
GET /{chain}/tokens/{token}/transfers | 필수: erc20, erc721, 또는 erc1155 | from_block 및 to_block은 선택 사항입니다. to_block을 생략하면 as_of_block이 기본값으로 사용됩니다. 이보다 큰 to_block 또는 from_block을 명시하면 clamp 대체 없이 409 not_indexed_yet 오류가 반환됩니다. |
페이지네이션
두 엔드포인트 모두 키셋 페이지네이션(keyset pagination)을 사용합니다:
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을 모두 요구합니다. 이 토큰 엔드포인트의 하한 규칙을 모든 전송 라우트에 적용하지 마세요. 어떤 체인이 데이터셋을 제공하는지는 지원 체인에서 확인하세요.
오름차순 과거 백필 중에는 백필된 끝과 라이브 시작 사이의 빈틈이 감지되지 않습니다. 그 빈틈 안의 윈도우는 여전히 빈 data 배열과 함께 200을 반환할 수 있습니다. 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을 통해 newHeads 또는 logs를 구독하거나, 최근 블록 범위를 폴링합니다. |
eth_getLogs로 로그 조회하기
export BLOCKVECTRA_API_KEY=rgw_your_api_key
# fromBlock / toBlock default to latest. Set an explicit recent range to follow
# new events, and keep its span within the chain's 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 are optional here; omitting to_block defaults to 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 truncates a too-wide window, or a to_block above as_of_block,
# instead of returning 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_getLogs | 30 |
data.address_transfers | 25 |
data.token_transfers | 25 |
현재 요금 및 충전 옵션은 요금 페이지를 참조하세요.
블록 윈도우의 호출 수와 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를 추정한 뒤, 현재 가격은 요금 페이지에서 확인하세요.
다음 단계
- 데이터셋 디렉터리 둘러보기: BlockVectra가 인덱싱하는 모든 데이터셋 확인.
- 무료 플랜 및 요금 확인: 계정에 포함된 혜택 확인.
- 콘솔 로그인: API key 생성.
최종 수정일: