Recent node data vs indexed history: when to use eth_getLogs and when to use the transfers API

Two ways to read logs and transfersCopy Anchor Link

eth_getLogs is a JSON-RPC method: it returns block logs through the JSON-RPC endpoint. The Data API exposes token transfer history through two chain-scoped endpoints:

• GET /{chain}/addresses/{address}/transfers — transfers involving an address.
• GET /{chain}/tokens/{token}/transfers — transfers for a single token contract.

Both use the same API key and are metered in CU by method weight (see the weights below). Which one fits depends on how recent the data is, whether you need a block window, and how you paginate.

Limits that apply to eth_getLogsCopy Anchor Link

eth_getLogs is bounded by per-chain limits that the public GET /v1/chains response publishes:

• Block span: max_logs_block_range is the maximum number of blocks a single eth_getLogs request may span. It differs by chain — read it from GET /v1/chains (chains are listed on Supported Chains) instead of hardcoding it. A wider range is rejected with JSON-RPC error -32602 eth_getLogs block range too large (not billed).
• Node sync: while a chain's node is not synced, eth_getLogs — like every method except eth_chainId — returns -32010; the call is not forwarded and not billed.
• State window: the state window that GET /v1/chains reports as state_window_blocks applies to state-reading methods such as eth_call and eth_getBalance, not to eth_getLogs.
• Node pruning: block and log reads are not limited by the state window, but they are limited by the node's retained history. Data that has been pruned returns 4444 pruned history unavailable (not billed).

When the fromBlock and toBlock filter fields are omitted or null, they default to latest.

WebSocket subscriptions are not supported: eth_subscribe returns -32601 method not available. To follow new events, poll eth_getLogs over the newest blocks.

What the Data API transfers endpoints provideCopy Anchor Link

The two endpoints require different parameters:

PaginationCopy Anchor Link

Both endpoints are keyset-paginated:

• limit defaults to 50; values above 500 are clamped to 500, and 0 or a non-integer returns 400 bad_request.
• next_cursor appears only when there is another page. On the last page the key is absent entirely, never null.
• Pass the returned value back as cursor, unchanged, to fetch the next page. A cursor is valid only for the chain, endpoint, and query parameters that issued it.

Coverage and finalityCopy Anchor Link

• Both endpoints belong to the transfers capability. A chain that does not provide it returns 422 no_coverage. Chains that provide this dataset are subject to the Supported Chains page.
• GET /v1/data/chains reports each chain's coverage (history_mode, from_block, and retention_days on window chains). A block window entirely before the chain's first indexed block is 422 no_coverage; one that starts before it is served as far as it goes, with meta.coverage = "partial". On window chains coverage.from_block moves forward — read it at runtime.
• Block-scoped responses only serve data at or below meta.finalized_block, the reorg-safety watermark (not a consensus finality signal), which trails as_of_block by a per-chain margin.
• For address transfers, a to_block above finalized_block is 409 finality_exceeded unless clamp=true truncates it down to finalized_block; a window that is too wide is 409 window_too_large unless clamp=true. Token transfers have no clamp escape.

Each transfer item contains token, standard, from, to, block_number, block_timestamp, tx_hash, tx_index, and log_index. ERC-20 items add amount; ERC-721 items add token_id; ERC-1155 items add operator, token_id, value, and batch_index.

Which one to useCopy Anchor Link

Querying logs with eth_getLogsCopy Anchor Link

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://dev-api.blockvectra.network/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"
    }]
  }'

Querying transfers with the Data APICopy Anchor Link

export BLOCKVECTRA_API_KEY=rgw_your_api_key

# from_block / to_block are optional here; omitting to_block defaults to finalized_block.
curl -s "https://dev-api.blockvectra.network/v1/data/robinhood_mainnet/tokens/0x1111111111111111111111111111111111111111/transfers?standard=erc20" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

To query by address instead, from_block and to_block are required:

# clamp=true truncates a too-wide window, or a to_block above finalized_block,
# instead of returning 409.
curl -s "https://dev-api.blockvectra.network/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 per callCopy Anchor Link

Every method is billed by its CU weight. The weights below are read from the platform plans API at build time:

For current prices and top-up options, see the Pricing page.

Next stepsCopy Anchor Link

• Browse the datasets directory to see every dataset BlockVectra indexes.
• See the free plan and pricing to check what your account includes.
• Log in to the console to create an API key.