eth_getLogs: Query Event Logs by Address and Topic

What eth_getLogs does

Events are not state. When a contract emits, the EVM writes a log entry into the transaction's receipt: up to four 32-byte topics plus an arbitrary data blob. eth_getLogs searches those receipts. Nothing about a log can be read from a contract afterwards, which is why event history is the only cheap way to reconstruct what happened on chain.

Topics are positional and mostly hashed. For a normal (non-anonymous) event, topic 0 is the keccak256 of the canonical signature, so Transfer(address,address,uint256) is always 0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef. Indexed value-type arguments fill topics 1 through 3 left-padded to 32 bytes; indexed dynamic types (string, bytes, arrays, structs) are stored as the keccak of their contents, so you can filter on them but never recover the original value. Everything not marked indexed is ABI-encoded into data.

Serving the query is the expensive part. Every block header carries a 2048-bit logsBloom; the client walks the headers in your range, tests the bloom for your address and topics, then opens the receipts of the candidate blocks for exact matching. Blooms produce false positives but never false negatives, so a rare topic over a wide range still costs a full header walk plus receipt reads on the false hits. That work, not the size of the answer, is why hosted endpoints put a ceiling on the range.

Parameters

Topic matching is positional: [A] matches any log whose first topic is A regardless of the rest; [A, null, B] pins topics 0 and 2 and leaves topic 1 free; [[A, B]] matches either A or B in position 0. blockHash cannot be combined with fromBlock or toBlock, and it is the reorg-safe way to ask for a single block, because a block number can point at different blocks before and after a reorg.

What it returns

An array of log objects, ordered by block and then by position within the block. Each carries address, topics, data, blockNumber, blockHash, transactionHash, transactionIndex, logIndex and removed. logIndex counts across the whole block rather than per transaction, so the pair (blockHash, logIndex) is the stable primary key for an indexer. Recent Geth also stamps each log with blockTimestamp, which saves a block lookup per log.

No match returns an empty array rather than an error, and that is a trap: a mistyped topic hash, the wrong contract address and a genuinely quiet range all look identical. When a query unexpectedly returns nothing, verify the topic hash and re-run with the address filter removed before assuming the range is empty.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "topics": [
        "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
        "0x00000000000000000000000098a7f18d4e56cfe84e3d081b40001b3d5bd3eb8b",
        "0x00000000000000000000000045312ea0eff7e09c83cbe249fa1d7598c4c8cd4e"
      ],
      "data": "0x0000000000000000000000000000000000000000000000000000000006aff77f",
      "blockNumber": "0x18789ac",
      "blockHash": "0x7e9ea4877f25847c29ea338043948a8ea43383da1620ace955a20baf667c5ff5",
      "transactionHash": "0x2efde06bb1dcf26741f3a7c1385d5a62ad2554523322e9dd53f1635ba6add6d1",
      "transactionIndex": "0x1",
      "logIndex": "0x5",
      "removed": false
    }
  ]
}

One USDC Transfer, trimmed to a single entry. Topic 1 is the sender and topic 2 the recipient, both left-padded addresses; the non-indexed amount sits in data (0x6aff77f is 112,195,455 raw units, 112.19 USDC at 6 decimals). Running the example against the head block returns however many transfers that block happened to contain.

import { JsonRpcProvider, Interface, id } from "ethers";

const provider = new JsonRpcProvider("https://ethereum-rpc.publicnode.com");
const iface = new Interface([
  "event Transfer(address indexed from, address indexed to, uint256 value)",
]);

const head = await provider.getBlockNumber();
const logs = await provider.getLogs({
  address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  topics: [id("Transfer(address,address,uint256)")],
  fromBlock: head - 9, // keep windows small and walk them
  toBlock: head,
});

for (const log of logs) {
  const parsed = iface.parseLog(log);
  if (parsed) console.log(parsed.args.from, "->", parsed.args.to, parsed.args.value);
}

Gotchas and common errors

What eth_getLogs costs on BLAZED.sh

eth_getLogs costs 1 credit per request on BLAZED.sh, the standard rate. The number that matters for indexers is the second one: responses over 100KB add 50 credits per MB, and a wide range over an active contract is exactly the response shape that gets there. Chunking keeps each response small and therefore usually under the surcharge, at the cost of more requests. A single request currently covers up to 1,000 blocks, and because your code runs on the node host, every chunk is a sub-10ms local round-trip rather than a queued call into a shared gateway.

eth_getLogs: frequently asked questions