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

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_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:

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.
• next_cursor aparece solo cuando existe otra página. En la última página, la clave no existe en absoluto, 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

Las transferencias de la Data API indexan transferencias históricas de tokens desde el coverage.from_block de cada cadena hasta meta.as_of_block. Consulte Cadenas compatibles para saber qué cadenas lo proporcionan.

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

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:

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

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.