eth_getLogs vs Token Transfers API: histórico de transferências ERC-20

Para histórico de carteiras ou reconciliação de transferências ERC-20, comece pela Token Transfers API. Use eth_getLogs quando precisar de logs de eventos de contratos. Desenvolvedores e agentes de IA podem consultar transferências indexadas de endereços por meio da mesma Data API de blockchain. O guia de ativos de carteiras combina saldos de tokens, histórico de transferências e metadados; a referência da Data API define os parâmetros de requisição e os esquemas de resposta.

Tarefas que este guia ajuda você a realizar

• Consultar logs de eventos de contratos via RPC autenticado em intervalos de blocos delimitados para monitoramento ou recuperação de logs.
• Consultar histórico indexado de transferências ERC-20 por meio da Data API de blockchain por endereço ou contrato de token, com paginação por cursor e verificações de cobertura.

Duas maneiras de ler logs e transferências

eth_getLogs é um método JSON-RPC: ele retorna logs de blocos por meio do endpoint JSON-RPC. A Data API expõe o histórico de transferências de tokens por meio de dois endpoints com escopo de rede:

• GET /{chain}/addresses/{address}/transfers — transferências envolvendo um endereço.
• GET /{chain}/tokens/{token}/transfers — transferências para um único contrato de token.

Ambos usam a mesma API key e são tarifados em CU pelo peso do método (veja os pesos abaixo). A escolha mais adequada depende de quão recentes são os dados, se você precisa de uma janela de blocos e de como realiza a paginação.

Limites aplicáveis ao eth_getLogs

eth_getLogs é delimitado por limites específicos de cada rede que a resposta pública de GET /v1/chains publica:

• Intervalo de blocos: max_logs_block_range é o número máximo de blocos que uma única requisição eth_getLogs pode abranger. Ele varia por rede — leia-o de GET /v1/chains (as redes estão listadas em Redes suportadas) em vez de fixá-lo no código. Um intervalo maior é rejeitado com o erro JSON-RPC -32602 eth_getLogs block range too large (não tarifado).
• Sincronização do nó: enquanto o nó de uma rede não estiver sincronizado, eth_getLogs retorna -32010 (não tarifado).
• Janela de estado: a janela de estado informada por GET /v1/chains como state_window_blocks aplica-se a métodos de leitura de estado como eth_call e eth_getBalance, não a eth_getLogs.
• Poda do nó (pruning): leituras de blocos e logs não são limitadas pela janela de estado, mas são limitadas pelo histórico retido pelo nó. Dados podados retornam 4444 pruned history unavailable (não tarifado).

Quando os campos de filtro fromBlock e toBlock forem omitidos ou forem null, o padrão adotado será latest.

Chamar eth_subscribe via HTTP retorna -32601 method not available. Nas redes em que ws é true em /v1/chains, eth_subscribe está disponível via WebSocket (consulte Redes suportadas); caso contrário, faça polling com eth_getLogs sobre os blocos mais recentes.

O que os endpoints de transferências da Data API oferecem

Os dois endpoints exigem parâmetros diferentes:

Paginação

Ambos os endpoints utilizam paginação baseada em chaves (keyset pagination):

• limit tem valor padrão de 50; valores acima de 500 são limitados a 500, e 0 ou um valor não inteiro retorna 400 bad_request.
• next_cursor aparece apenas quando há outra página. Na última página, a chave fica completamente ausente, nunca sendo null.
• Repasse o valor retornado como cursor, sem alterações, para buscar a próxima página. Um cursor é válido apenas para a rede, o endpoint e os parâmetros de consulta que o geraram.

Cobertura e finalidade

As transferências da Data API indexam transferências históricas de tokens desde o coverage.from_block de cada rede até meta.as_of_block. Consulte Redes suportadas para ver quais redes oferecem esse recurso.

Cada item de transferência contém token, standard, from, to, block_number, block_timestamp, tx_hash, tx_index e log_index. Itens ERC-20 adicionam amount; itens ERC-721 adicionam token_id; itens ERC-1155 adicionam operator, token_id, value e batch_index.

Qual deles usar

Consultar logs com 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"
    }]
  }'

Consultar transferências com a 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"

Para consultar por endereço, from_block e to_block são obrigatórios:

# 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 por chamada

Cada método é tarifado pelo seu peso em CU. Os pesos abaixo são lidos a partir da API de planos da plataforma:

Para ver os preços atuais e opções de recarga, consulte a página de preços.

Próximos passos

• Navegue pelo diretório de conjuntos de dados para ver todos os conjuntos de dados indexados pela BlockVectra.
• Veja o plano gratuito e os preços para verificar o que sua conta inclui.
• Entre no console para criar uma API key.