eth_getLogs | Immutable RPC Docs

Query event logs on Immutable. Essential for indexing Web3 gaming (Gods Unchained, RavenQuest), gaming NFTs with enforced royalties, and cross-chain game assets on the gaming-optimized zkEVM with 660+ games, 5.5M+ Passport signups, and $40M TVL.

Returns an array of all logs matching a given filter object on Immutable.

Why Immutable? Build on the gaming-optimized zkEVM with 660+ games, 5.5M+ Passport signups, and $40M TVL with first EVM chain with enforceable royalties, Polygon zkEVM technology, $2B+ ecosystem funding, and Agglayer cross-chain liquidity.

When to Use This Method

The eth_getLogs method serves these key scenarios for AAA game studios, indie game developers, and NFT gaming teams seeking enforceable royalties:

Index smart contract events - Track transfers, swaps, and approvals emitted by any contract on Immutable for use in indexed databases
Monitor DeFi protocol activity - Watch for liquidity changes, price updates, and position events in real time across Web3 gaming (Gods Unchained, RavenQuest), gaming NFTs with enforced royalties, and cross-chain game assets
Build analytics pipelines - Extract on-chain event data for dashboards, reporting, and trend analysis on Immutable
Track token holder activity - Monitor whale movements and large transfers to detect significant market activity

Common Use Cases

1. Monitor ERC20 Transfer Events

Track all transfer events for a specific token contract within a defined block range. The Transfer event signature hash filters for exactly this event type, and you can optionally filter by sender or recipient address using indexed topics.

JavaScript

import { JsonRpcProvider } from 'ethers';

const provider = new JsonRpcProvider('https://api-immutable-zkevm-mainnet.n.dwellir.com/YOUR_API_KEY');
const tokenAddress = '0x3A0C2Ba54D6CBd3121f01b96DFd20e99D1696c9D';
const transferTopic = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef';

async function getRecentTransfers(fromBlock, toBlock) {
  const logs = await provider.getLogs({
    address: tokenAddress,
    fromBlock: fromBlock,
    toBlock: toBlock,
    topics: [transferTopic]
  });

  const transfers = logs.map(log => ({
    from: '0x' + log.topics[1].slice(26),
    to: '0x' + log.topics[2].slice(26),
    amount: BigInt(log.data).toString(),
    txHash: log.transactionHash
  }));

  console.log(`Found ${transfers.length} transfers`);
  return transfers;
}

const recentTransfers = await getRecentTransfers('latest', 'latest');

2. Track DEX Swap Events

Capture swap events from a DEX to analyze trading volume, price impact, and liquidity flow. Each swap emits event parameters that include the amounts and addresses involved - ideal for building price feeds and volume aggregators.

JavaScript

const provider = new JsonRpcProvider('https://api-immutable-zkevm-mainnet.n.dwellir.com/YOUR_API_KEY');

const SWAP_TOPIC = '0xd78ad95fa46c994b6551d0da85fc275fe613ce37657fb8d5e3d130840159d822';
const pairAddress = '0x3A0C2Ba54D6CBd3121f01b96DFd20e99D1696c9D';

async function getRecentSwaps(fromBlock, toBlock) {
  const logs = await provider.getLogs({
    address: pairAddress,
    fromBlock: fromBlock,
    toBlock: toBlock,
    topics: [SWAP_TOPIC]
  });

  return logs.map(log => ({
    sender: '0x' + log.topics[1].slice(26),
    to: '0x' + log.topics[2].slice(26),
    amount0In: BigInt('0x' + log.data.slice(2, 66)).toString(),
    amount1In: BigInt('0x' + log.data.slice(66, 130)).toString(),
    amount0Out: BigInt('0x' + log.data.slice(130, 194)).toString(),
    amount1Out: BigInt('0x' + log.data.slice(194, 258)).toString(),
    txHash: log.transactionHash
  }));
}

const swaps = await getRecentSwaps('latest', 'latest');
console.log(`Found ${swaps.length} swaps`);

3. Multi-Contract Event Aggregation

Query events from multiple contracts simultaneously by passing an array of addresses. This is useful for cross-protocol analytics - aggregating lending, borrowing, and liquidation events from multiple DeFi protocols in a single query on Immutable.

JavaScript

const provider = new JsonRpcProvider('https://api-immutable-zkevm-mainnet.n.dwellir.com/YOUR_API_KEY');

const contracts = [
  '0xContractA...',
  '0xContractB...',
  '0xContractC...'
];

const EVENT_TOPIC = '0x...';

async function aggregateEvents(fromBlock, toBlock) {
  const logs = await provider.getLogs({
    address: contracts,
    fromBlock: fromBlock,
    toBlock: toBlock,
    topics: [EVENT_TOPIC]
  });

  const grouped = {};
  for (const log of logs) {
    const contract = log.address;
    if (!grouped[contract]) grouped[contract] = [];
    grouped[contract].push(log);
  }

  for (const [contract, events] of Object.entries(grouped)) {
    console.log(`${contract}: ${events.length} events`);
  }

  return grouped;
}

aggregateEvents('0x100000', '0x100500');

Best Practices

Limit block range to 1,000-5,000 blocks per query to avoid timeouts and rate limits on Immutable
Use topic filters for efficient log filtering: the node filters at the storage level before returning results
For high-volume monitoring, use eth_newFilter with polling instead of repeatedly calling eth_getLogs
Store the last processed block number for incremental indexing rather than re-scanning the full chain
Be aware that eth_getLogs often has stricter rate limits than other RPC methods on Immutable

Code Examples

Error Handling

Error Code	Message	Description
-32005	Query returned more than 10000 results	Reduce block range
-32602	Invalid params	Invalid filter parameters

eth_newFilter - Create a filter for logs
eth_getFilterChanges - Poll filter for new logs

eth_getLogs - Immutable RPC Method

When to Use This Method

Common Use Cases

1. Monitor ERC20 Transfer Events

2. Track DEX Swap Events

3. Multi-Contract Event Aggregation

Best Practices

Code Examples

Error Handling

On this page