eth_getLogs frente a la API de transferencias de tokens: historial de transferencias ERC-20

Elija eth_getLogs para logs de eventos de contratos o la API de transferencias de tokens para el historial indexado de transferencias ERC-20. Compare rangos de bloques, paginación, cobertura y finalidad.

Para el historial de billeteras o la conciliación de transferencias ERC-20, comience con la API de transferencias de tokens. Utilice eth_getLogs cuando necesite logs de eventos de contratos. Los desarrolladores y agentes de IA pueden consultar transferencias indexadas de direcciones a través de la misma API de datos de blockchain. La guía de activos de billetera combina saldos de tokens, historial de transferencias y metadatos; la referencia de la Data API define los parámetros de solicitud y los esquemas de respuesta.

Tareas que esta guía le ayuda a completar

Dos formas de leer logs y transferencias

eth_getLogs es un método JSON-RPC: devuelve logs de bloques a través del endpoint JSON-RPC. La Data API expone el historial de transferencias de tokens a través de dos endpoints específicos de cada cadena:

  • GET /{chain}/addresses/{address}/transfers — transferencias en las que participa una dirección.
  • GET /{chain}/tokens/{token}/transfers — transferencias para un solo contrato de token.

Ambos utilizan la misma API key y se facturan en CU por peso de método (consulte los pesos a continuación). Cuál utilizar depende de la antigüedad de los datos, de si necesita una ventana de bloques y de cómo pagine.

Límites aplicables a eth_getLogs

eth_getLogs está delimitado por los límites específicos de cada cadena que publica la respuesta pública de GET /v1/chains:

  • Amplitud de bloques: max_logs_block_range es la cantidad máxima de bloques que puede abarcar una sola solicitud eth_getLogs. Difiere según la cadena — consúltelo en GET /v1/chains (las cadenas se enumeran en Cadenas compatibles) en lugar de codificarlo de forma fija. Un rango más amplio se rechaza con el error JSON-RPC -32602 eth_getLogs block range too large (no facturado).
  • Sincronización del nodo: mientras el nodo de una cadena no esté sincronizado, eth_getLogs devuelve -32010 (no facturado).
  • Ventana de estado: la ventana de estado que GET /v1/chains reporta como state_window_blocks se aplica a métodos de lectura de estado como eth_call y eth_getBalance, no a eth_getLogs.
  • Poda del nodo: las lecturas de bloques y logs no están limitadas por la ventana de estado, pero sí por el historial retenido por el nodo. Los datos que han sido podados devuelven 4444 pruned history unavailable (no facturado).

Cuando los campos de filtro fromBlock y toBlock se omiten o son null, su valor predeterminado es latest.

Llamar a eth_subscribe a través de HTTP devuelve -32601 method not available. En las cadenas donde ws es true en /v1/chains, eth_subscribe está disponible mediante WebSocket (consulte Cadenas compatibles); de lo contrario, realice polling con eth_getLogs sobre los bloques más recientes.

Qué ofrecen los endpoints de transferencias de la Data API

Los dos endpoints requieren parámetros diferentes:

EndpointstandardVentana de bloques
GET /{chain}/addresses/{address}/transfersObligatorio: erc20 o erc721. erc1155 devuelve 422 no_coveragefrom_block y to_block son ambos obligatorios. Los resultados se ordenan por (block_number, log_index) descendente. direction (in, out o any; por defecto any) filtra por dirección, y token restringe opcionalmente los resultados a un contrato.
GET /{chain}/tokens/{token}/transfersObligatorio: erc20, erc721 o erc1155from_block y to_block son opcionales. La ausencia de to_block toma por defecto as_of_block; un to_block o from_block explícito por encima de este devuelve un error estricto 409 not_indexed_yet, sin opción de clamp.

Paginación

Ambos endpoints utilizan paginación keyset:

  • limit tiene como valor predeterminado 50; los valores superiores a 500 se ajustan a 500, y 0 o un número no entero devuelve 400 bad_request.
  • Una página con limit registros puede incluir next_cursor aunque no queden más registros. Continúa con cada cursor devuelto hasta que la clave esté ausente; la última página puede contener un array data vacío. Si no hay cursor, la clave se omite y nunca es null.
  • Pase el valor devuelto como cursor, sin cambios, para obtener la siguiente página. Un cursor solo es válido para la cadena, el endpoint y los parámetros de consulta que lo emitieron.

Cobertura y finalidad

Para GET /{chain}/tokens/{token}/transfers, la cobertura se limita al conjunto de datos de transferencias de tokens del standard solicitado. Su límite inferior se calcula a partir de ese conjunto y puede quedar por encima del coverage.from_block de la cadena cuando la cobertura de compilación registrada del conjunto empieza más tarde. Una ventana completamente anterior a ese límite inferior devuelve 422 no_coverage. Una ventana que empieza antes, o que omite from_block, se sirve hasta donde llega el conjunto y notifica meta.coverage = "partial". meta.as_of_block es el bloque más reciente escrito por completo (la marca de agua de escritura), no una prueba de que todos los bloques entre el límite inferior y él estén indexados. El endpoint de direcciones sigue exigiendo tanto from_block como to_block; no aplique esta regla de límite inferior del endpoint de tokens a todas las rutas de transferencias. Consulte Cadenas compatibles para saber qué cadenas exponen el conjunto.

Durante una retrocarga histórica ascendente, no se detecta el hueco entre el final retrocargado y el inicio en vivo: una ventana dentro de ese hueco puede seguir devolviendo 200 con un array data vacío. Ni el éxito HTTP, ni un resultado vacío, ni agotar todos los cursores, ni un solo campo de cobertura demuestran que un rango completo esté completo. Valide la integridad contra los datos que espera o su propia conciliación.

Cada elemento de transferencia contiene token, standard, from, to, block_number, block_timestamp, tx_hash, tx_index y log_index. Los elementos ERC-20 agregan amount; los elementos ERC-721 agregan token_id; los elementos ERC-1155 agregan operator, token_id, value y batch_index.

Cuál utilizar

Tarea típicaMejor opciónMotivo
Eventos en los últimos cientos de bloqueseth_getLogsUna sola solicitud puede cubrir un rango reciente siempre que no supere el max_logs_block_range de esa cadena.
Transferencias históricas de una direcciónGET /{chain}/addresses/{address}/transfersConsulta por dirección con una ventana from_block/to_block, filtros de direction y token, y paginación por cursor; los resultados cubren hasta as_of_block.
Todas las transferencias de un tokenGET /{chain}/tokens/{token}/transfersConsulta por contrato de token que cubre erc20, erc721 y erc1155, con ventana de bloques opcional y paginación por cursor en el rango que sirve el conjunto de datos.
Monitoreo en vivo de nuevos eventoseth_subscribe (cadenas WebSocket) / eth_getLogs (polling)Suscríbase a nuevos bloques (newHeads) o logs a través de WebSocket donde sea compatible, o realice polling en rangos de bloques recientes.

Consultar logs con 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 transferencias con la 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 dirección en su lugar, from_block y to_block son obligatorios:

# 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 llamada

Cada método se factura según su peso en CU. Los pesos siguientes se leen desde la API de planes de la plataforma:

Peso en CU por llamada

MétodoCU por llamada
eth_getLogs30
data.address_transfers25
data.token_transfers25

Para consultar los precios actuales y las opciones de recarga, consulte la página de Precios.

Estimar llamadas y CU para una ventana de bloques

Las ventanas de bloques incluyen ambos extremos: N = to_block - from_block + 1. Si cada solicitud de rango cubre como máximo S bloques, un barrido exitoso requiere al menos ceil(N / S) solicitudes. Por ejemplo, 10.000.000 de bloques con 5 bloques por solicitud son 2.000.000 de solicitudes; con 10.000 bloques por solicitud son 1.000. Estos son solo ejemplos aritméticos, no una promesa sobre el límite de ninguna cadena o proveedor.

Los fallos y reintentos añaden solicitudes, al igual que los límites de tamaño de resultado. Una ventana más pequeña no cuesta automáticamente menos: más llamadas pueden compensar el intervalo más estrecho, y el CU se cobra por peso de llamada. Las transferencias indexadas paginan por resultado, no por número de bloques, así que un barrido puede necesitar páginas adicionales, incluida una posible página vacía final; no derive el número de páginas del número de bloques. Multiplique los pesos por llamada anteriores por el número esperado de llamadas facturables para estimar el CU y consulte la página de Precios para los precios actuales.

Próximos pasos

Última actualización:

En esta página