Skip to main content
Subscription equivalent to eth_newFilter. subscribe("logs") allows developers to subscribe to real-time updates about new event logs on the Ethereum blockchain; the application will receive notifications whenever new logs matching the filter are emitted.

​
Get your own node endpoint today

Start for free and get your app to production levels immediately. No credit card required.You can sign up with your GitHub, X, Google, or Microsoft account.

​
Parameters

  • string — a keyword identifying the type of event to subscribe to, logs in this case.
  • object — (optional) The subscription options:
    • address — the contract address from which the logs should be fetched. It can be a single address or an array of addresses.
    • topics — an array of DATA topics. The event topics for which the logs should be fetched. It can be a single topic or an array of topics.
  • function — (optional) a callback function that will be called every time a new event of the specified type is received. This function takes two parameters: error and result. The error parameter contains any error that occurred while subscribing to the event, and the result parameter contains the data for the event that was received.

​
Response

  • array — an array of log objects that match the specified filter:
    • address — the contract address from which the event originated.
    • topics — an array of 32-byte data fields containing indexed event parameters.
    • data — the non-indexed data that was emitted along with the event.
    • blocknumber — the block number in which the event was included. null if it is pending.
    • transactionhash — the hash of the transaction that triggered the event. null if pending.
    • transactionindex — the integer index of the transaction within the block’s list of transactions. null if it is pending.
    • blockhash — the hash of the block in which the event was included. null if it is pending.
    • logindex — the integer identifying the index of the event within the block’s list of events. null if pending.
    • removed — the boolean value indicating if the event was removed from the blockchain due to a chain reorganization. True if the log was removed. False if it is a valid log.

​
subscribe("logs") code example

Note that log subscriptions require a WebSocket connection.
Use the provider’s event listeners to react to subscription events:
  • provider.on(filter, listener) — registers a listener that fires for each new log matching the filter.
  • the listener receives the log object emitted by the contract.
  • provider.off(filter) — removes the listeners and stops the subscription.
const ethers = require("ethers");

const NODE_URL = "CHAINSTACK_WSS_ENDPOINT";
const provider = new ethers.WebSocketProvider(NODE_URL);

// Filter for WETH transfer events
const logsFilter = {
    address: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH contract address
    topics: ['0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'] // Transfer event signature
};

async function subscribeToLogs() {
  try {
    // Create a new subscription to logs with the specified filter
    provider.on(logsFilter, handleLogs);

    console.log("Subscription created for the specified logs filter");
  } catch (error) {
    console.error(`Error subscribing to new logs: ${error}`);
  }
}

// Listener that logs the received log data
function handleLogs(log) {
  console.log("New log received:", log);
}

// Surface any provider-level errors
provider.on("error", (error) => {
  console.error("Error when subscribing to new logs:", error);
});

subscribeToLogs();

​
Use case

A practical use case for subscribe("logs") is a DApp that continuously listens for new specific event logs and isolates certain fields for analytics purposes. This is useful, for example, to only track events about a specific ERC-721 token. The following is an implementation of this concept using ethers.js subscriptions, this program will only track the Transfer event from the MutantApeYachtClub collection smart contract. The Transfer event looks like this in the smart contract: 
event Transfer(address indexed from, address indexed to, uint256 indexed tokenId);
Read Tracking some Bored Apes: The Ethereum event logs tutorial to learn more about event logs.
The following code will log all of the new Transfer events, and extract the block number. This can be useful to analyze when tokens are moved. 
const ethers = require("ethers");
const NODE_URL = "CHAINSTACK_WSS_ENDPOINT";
const provider = new ethers.WebSocketProvider(NODE_URL);

// Filter for Transfer events from the MAYC smart contract
const logsFilter = {
    address: '0x60E4d786628Fea6478F785A6d7e704777c86a7c6', // MAYC contract address
    topics: ['0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'] // Transfer event signature
};

async function subscribeToLogs() {
    try {
        // Create a new subscription to logs with the specified filter
        provider.on(logsFilter, handleLogs);

        console.log("Subscription created for the specified logs filter");
    } catch (error) {
        console.error(`Error subscribing to logs: ${error}`);
    }
}

/* Fallback functions to react to the different events */

// Listener that logs the filtered events
function handleLogs(log) {
    const block = log.blockNumber;
    console.log(`A Mutant Ape was transferred in this block: ${block}`);
}

// Surface any provider-level errors
provider.on("error", (error) => {
    console.error(`Error receiving logs: ${error}`);
});

subscribeToLogs();
This code creates a new subscription to the logs event by passing the filter to the provider.on method. This method registers a listener that fires every time a new log matching the filter is emitted. The code defines a listener function that is attached to the provider: handleLogs. The handleLogs function is called when a new log matching the filter is emitted, then extracts the block number field and logs it to the console. A separate error listener is attached to the provider, and it logs an error message when an error occurs. Finally, the code calls the subscribeToLogs function, which creates the subscription and attaches the listener. When a new event log is received, the handleLogs function is called to extract and log the data to the console.
Last modified on June 25, 2026