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
- Consultar logs de eventos de contratos mediante RPC autenticado en rangos delimitados de bloques para monitoreo o recopilación de logs.
- Consultar el historial indexado de transferencias ERC-20 a través de la API de datos de blockchain por dirección o contrato de token, con paginación por cursor y comprobaciones de cobertura.
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_rangees la cantidad máxima de bloques que puede abarcar una sola solicitudeth_getLogs. Difiere según la cadena — consúltelo enGET /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_getLogsdevuelve-32010(no facturado). - Ventana de estado: la ventana de estado que
GET /v1/chainsreporta comostate_window_blocksse aplica a métodos de lectura de estado comoeth_callyeth_getBalance, no aeth_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:
| Endpoint | standard | Ventana de bloques |
|---|---|---|
GET /{chain}/addresses/{address}/transfers | Obligatorio: erc20 o erc721. erc1155 devuelve 422 no_coverage | from_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}/transfers | Obligatorio: erc20, erc721 o erc1155 | from_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:
limittiene como valor predeterminado 50; los valores superiores a 500 se ajustan a 500, y0o un número no entero devuelve400 bad_request.- Una página con
limitregistros puede incluirnext_cursoraunque no queden más registros. Continúa con cada cursor devuelto hasta que la clave esté ausente; la última página puede contener un arraydatavacío. Si no hay cursor, la clave se omite y nunca esnull. - 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ípica | Mejor opción | Motivo |
|---|---|---|
| Eventos en los últimos cientos de bloques | eth_getLogs | Una 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ón | GET /{chain}/addresses/{address}/transfers | Consulta 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 token | GET /{chain}/tokens/{token}/transfers | Consulta 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 eventos | eth_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étodo | CU por llamada |
|---|---|
eth_getLogs | 30 |
data.address_transfers | 25 |
data.token_transfers | 25 |
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
- Explore el directorio de conjuntos de datos para ver todos los conjuntos de datos indexados por BlockVectra.
- Consulte el plan gratuito y los precios para comprobar lo que incluye su cuenta.
- Inicie sesión en la consola para crear una API key.
Última actualización:
LangChain
Dé a un agente de LangChain datos blockchain en vivo con una sola herramienta sobre el endpoint público de BlockVectra sin clave; después añada el servidor MCP de documentación y una API key para los métodos que la requieren.
Servidor MCP
El servidor MCP de BlockVectra ofrece a desarrolladores y agentes de IA herramientas sin clave de RPC blockchain, estado de cadenas, precios y documentación, con instalación en una línea para Claude Code, Cursor, VS Code, Codex, Gemini CLI y más.