> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstack.com/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.chainstack.com/feedback

```json
{
  "path": "/reference/avalanche-subscribelogs",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# subscribe ("logs") | Avalanche

web3.js subscription equivalent to [eth\_newFilter](/reference/avalanche-newfilter). `subscribe("logs")` allows developers to subscribe to real-time updates about new event logs on the Avalanche blockchain; the application will receive notifications whenever new logs matching the filter are emitted.

<Check>
  ### Get your own node endpoint today

  [Start for free](https://console.chainstack.com/) and get your app to production levels immediately. No credit card required.

  You can sign up with your GitHub, X, Google, or Microsoft account.
</Check>

## Parameters

* `string` — a keyword identifying the type of event to subscribe to, `logs` in this case.

* `object` — (optional) The subscription options:

  * `fromBlock` — an integer that specifies the starting block number from which the logs should be fetched. `null` by default.
  * `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

<Info>
  Note that web3.js subscriptions require a WebSocket connection.
</Info>

Use the [event emitter instances](https://web3js.readthedocs.io/en/v1.2.11/web3-eth-subscribe.html#eth-subscription-return) to attach event listeners to the subscription object:

* `data` — activates for each new syncing event.
* `error` — activates if an error is detected during the subscription.
* `connected` — activates after the subscription is successfully connected and returns the subscription ID.
* `unsubscribe` — unsubscribes the subscription and returns `true` if successful.

<CodeGroup>
  ```javascript index.js theme={"system"}
  const Web3 = require("web3");
  const NODE_URL = "CHAINSTACK_WSS_URL";
  const web3 = new Web3(NODE_URL);

  // Only log transfer events from the WETH smart contract.
  const logsFilter = {
      address: '0x82aF49447D8a07e3bd95BD0d56f35241523fBab1',
      topics: ['0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef']
  }

  async function subscribeToLogs() {
      try {
          // Create a new subscription to the 'pendingTransactions' event
          const subscription = await web3.eth.subscribe('logs', logsFilter);

          // Attach event listeners to the subscription object
          subscription.on('connected', handleConnected);
          subscription.on('data', handleLogs);
          subscription.on('error', handleError);
      } catch (error) {
          console.error(`Error subscribing to new logs: ${error}`);
      }
  }

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

  // Event listener that logs a message when the subscription is connected
  function handleConnected(subscriptionId) {
      console.log(`New subscription: ${subscriptionId}`);
  }

  // Event listener that logs the filtered events
  async function handleLogs(logs) {
      console.log(logs)
  }

  // Event listener that logs any errors that occur
  function handleError(error) {
      console.error(`Error receiving new blocks: ${error}`);
  }

  subscribeToLogs();
  ```
</CodeGroup>

## 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 web3.js subscriptions; this program will only track the `Transfer` event from the [FunnelHeads collection](https://snowtrace.io/token/0x5378d068001d7e53d6c0a7ef539fbe213b5eb075#code) smart contract.

The `Tranfer` event looks like this in the smart contract:

<CodeGroup>
  ```sol IERC721.sol theme={"system"}
      event Transfer(address indexed from, address indexed to, uint256 indexed tokenId);
  ```
</CodeGroup>

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.

<CodeGroup>
  ```javascript index.js theme={"system"}
  const Web3 = require("web3");
  const NODE_URL = "CHAINSTACK_WSS_URL";
  const web3 = new Web3(NODE_URL);

  // Only log Tranfer events from the Avalanche FunnelHeads smart contract.
  const logsFilter = {
      address: '0x5378d068001D7E53D6c0a7ef539fbE213B5eB075',
      topics: ['0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef']
  }

  async function subscribeToLogs() {
      try {
          // Create a new subscription to the 'pendingTransactions' event
          const subscription = await web3.eth.subscribe('logs', logsFilter);

          // Attach event listeners to the subscription object
          subscription.on('connected', handleConnected);
          subscription.on('data', handleLogs);
          subscription.on('error', handleError);
      } catch (error) {
          console.error(`Error subscribing to new blocks: ${error}`);
      }
  }

  // Use this function to unsuscribe and exit the program
  function unsubscribe() {
      subscription.unsubscribe(function(error, success) {
          if (success) console.log("Successfully unsubscribed!");
          return process.exit(1)
      });
  }

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

  // Event listener that logs a message when the subscription is connected
  function handleConnected(subscriptionId) {
      console.log(`New subscription: ${subscriptionId}`);
  }

  // Event listener that logs the filtered events
  async function handleLogs(logs) {
      const block = logs.blockNumber
      console.log(`A FunnelHead was transferred in this block: ${block}`)
  }

  // Event listener that logs any errors that occur
  function handleError(error) {
      console.error(`Error receiving new blocks: ${error}`);
  }

  subscribeToLogs();
  ```
</CodeGroup>

This code creates a new subscription to the `logs` event using the `web3.eth.subscribe` method. This method returns a subscription object that can be used to attach event listeners to the subscription.

The code defines three event listener functions that are attached to the subscription object: `handleConnected`, `handleLogs`, and `handleError`. The `handleConnected` function is called when the subscription is connected, and it logs a message with the subscription ID. 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.

The `handleError` function is called when an error occurs, and it logs an error message.

The code includes the `unsubscribe` function that can be implemented in the logic to unsubscribe and exit the program when a condition is met.

Finally, the code calls the `subscribeToLogs` function, which creates the subscription and attaches the event listeners. When a new event log is received, the `handleLogs` function is called to extract the data and log it to the console.