eth_getLogs vs Token Transfers API: ERC-20 전송 내역 조회

지갑 내역 조회나 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 전송 엔드포인트가 제공하는 기능

두 엔드포인트는 요구하는 파라미터가 다릅니다:

페이지네이션

두 엔드포인트 모두 키셋 페이지네이션(keyset pagination)을 사용합니다:

• limit 기본값은 50입니다. 500을 초과하는 값은 500으로 제한되며, 0이나 정수가 아닌 값은 400 bad_request를 반환합니다.
• next_cursor는 다음 페이지가 존재할 때만 표시됩니다. 마지막 페이지에서는 키가 null이 아니라 완전히 생략됩니다.
• 다음 페이지를 가져오려면 반환된 값을 변경 없이 cursor로 다시 전달하세요. 커서는 이를 발급한 체인, 엔드포인트 및 쿼리 파라미터 조합에 대해서만 유효합니다.

커버리지 및 완결성

Data API transfers는 각 체인의 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 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에서 읽어옵니다:

현재 요금 및 충전 옵션은 요금 페이지를 참조하세요.

다음 단계

• 데이터셋 디렉터리 둘러보기: BlockVectra가 인덱싱하는 모든 데이터셋 확인.
• 무료 플랜 및 요금 확인: 계정에 포함된 혜택 확인.
• 콘솔 로그인: API key 생성.