eth_getLogs vs Token Transfers API : historique des transferts ERC-20

Pour l'historique d'un portefeuille ou la réconciliation des transferts ERC-20, commencez par la Token Transfers API. Utilisez eth_getLogs lorsque vous avez besoin des logs d'événements de contrat. Les développeurs et les agents IA peuvent interroger les transferts d'adresses indexés via la même API de données blockchain. Le guide des actifs de portefeuille combine les soldes de jetons, l'historique des transferts et les métadonnées ; la référence de la Data API définit les paramètres de requête et les schémas de réponse.

Tâches que ce guide vous aide à accomplir

• Interroger les logs d'événements de contrat via le RPC authentifié dans des plages de blocs bornées pour la surveillance ou le rétro-remplissage de logs.
• Interroger l'historique indexé des transferts ERC-20 via l'API de données blockchain par adresse ou par contrat de jeton, avec pagination par curseur et vérifications de couverture.

Deux façons de lire les logs et les transferts

eth_getLogs est une méthode JSON-RPC : elle renvoie les logs de blocs via l'endpoint JSON-RPC. La Data API expose l'historique des transferts de jetons via deux endpoints délimités par chaîne :

• GET /{chain}/addresses/{address}/transfers — transferts impliquant une adresse.
• GET /{chain}/tokens/{token}/transfers — transferts pour un contrat de jeton unique.

Les deux utilisent la même API key et sont mesurés en CU selon le poids de la méthode (voir les poids ci-dessous). Le choix de l'une ou l'autre dépend de l'ancienneté des données, du besoin d'une fenêtre de blocs et du mode de pagination.

Limites qui s'appliquent à eth_getLogs

eth_getLogs est encadré par des limites par chaîne publiées par la réponse publique de GET /v1/chains :

• Étendue de blocs : max_logs_block_range est le nombre maximal de blocs qu'une seule requête eth_getLogs peut couvrir. Il varie selon la chaîne — lisez-le depuis GET /v1/chains (les chaînes sont répertoriées sur la page Chaînes prises en charge) plutôt que de le coder en dur. Une plage plus large est rejetée avec l'erreur JSON-RPC -32602 eth_getLogs block range too large (non facturé).
• Synchronisation du nœud : tant que le nœud d'une chaîne n'est pas synchronisé, eth_getLogs renvoie -32010 (non facturé).
• Fenêtre d'état : la fenêtre d'état que GET /v1/chains indique sous le nom state_window_blocks s'applique aux méthodes de lecture d'état telles que eth_call et eth_getBalance, et non à eth_getLogs.
• Élagage du nœud : les lectures de blocs et de logs ne sont pas limitées par la fenêtre d'état, mais elles sont limitées par l'historique conservé par le nœud. Les données élaguées renvoient 4444 pruned history unavailable (non facturé).

Lorsque les champs de filtre fromBlock et toBlock sont omis ou définis sur null, ils prennent la valeur par défaut latest.

Appeler eth_subscribe sur HTTP renvoie -32601 method not available. Sur les chaînes où ws vaut true dans /v1/chains, eth_subscribe est disponible via WebSocket (voir Chaînes prises en charge) ; sinon, scrutez eth_getLogs sur les blocs les plus récents.

Ce que fournissent les endpoints de transferts de la Data API

Les deux endpoints nécessitent des paramètres différents :

Pagination

Les deux endpoints utilisent une pagination par jeu de clés (keyset) :

• limit a pour valeur par défaut 50 ; les valeurs supérieures à 500 sont ramenées à 500, et 0 ou une valeur non entière renvoie 400 bad_request.
• next_cursor n'apparaît que lorsqu'il existe une page suivante. Sur la dernière page, la clé est totalement absente, jamais null.
• Transmettez la valeur renvoyée dans le paramètre cursor, sans modification, pour récupérer la page suivante. Un curseur n'est valide que pour la chaîne, l'endpoint et les paramètres de requête qui l'ont émis.

Couverture et finalité

Les transferts de la Data API indexent l'historique des transferts de jetons depuis le coverage.from_block de chaque chaîne jusqu'à meta.as_of_block. Consultez la page Chaînes prises en charge pour savoir quelles chaînes le proposent.

Chaque élément de transfert contient token, standard, from, to, block_number, block_timestamp, tx_hash, tx_index et log_index. Les éléments ERC-20 ajoutent amount ; les éléments ERC-721 ajoutent token_id ; les éléments ERC-1155 ajoutent operator, token_id, value et batch_index.

Lequel utiliser

Interroger les logs avec 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"
    }]
  }'

Interroger les transferts avec 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"

Pour interroger par adresse à la place, from_block et to_block sont requis :

# 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 par appel

Chaque méthode est facturée selon son poids en CU. Les poids ci-dessous sont lus depuis l'API des forfaits de la plateforme :

Pour les prix actuels et les options de recharge, consultez la page Tarifs.

Prochaines étapes

• Parcourir le catalogue des jeux de données pour découvrir chaque jeu de données indexé par BlockVectra.
• Consulter le forfait gratuit et les tarifs pour vérifier ce que comprend votre compte.
• Se connecter à la console pour créer une API key.