API
🛠️ Start for free

subscribe("pendingTransactions") | Ethereum

web3.js subscription equivalent to eth_newPendingTransactionFilter. subscribe("pendingTransactions") allows developers to subscribe to real-time updates about pending transactions on the Ethereum blockchain; the application will receive notifications whenever a pending transaction appears on the blockchain.

👍

Get you 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, pendingTransactions in this case.
  • 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

  • string — the hash identifying the pending transaction.

subscribe("pendingTransactions") code example

📘

Note that web3.js subscriptions require a WebSocket connection.

Use the event emitter instances 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.
const { Web3 } = require("web3");

const NODE_URL = "CHAINSTACK_WSS_URL"; // Ensure this is your WebSocket endpoint
const web3 = new Web3(NODE_URL);

async function subscribeToPendingTransactions() {
  try {
    // Subscribe to 'pendingTransactions' event
    const subscription = await web3.eth.subscribe('pendingTransactions');

    console.log(`Subscription successful, Subscription ID: ${subscription.id}`);

    // Event listener for new pending transactions
    subscription.on('data', (transaction) => {
      console.log('New pending transaction:', transaction);
    });

    // Event listener for any errors during the subscription
    subscription.on('error', (error) => {
      console.error('Subscription error:', error);
    });
  } catch (error) {
    console.error(`Error subscribing to pending transactions: ${error}`);
  }
}

subscribeToPendingTransactions();

Use case

A practical use case for subscribe("pendingTransactions") is a DApp that continuously listens for new pending transactions, then isolates the from, to, and value fields for analytics purposes. This is useful, for example, to only track transactions that move at least a certain amount of ETH.

The following is an implementation of this concept using web3.js subscriptions:

const {Web3} = require("web3");
const NODE_URL = "CHAINSTACK_WSS_URL";
const web3 = new Web3(NODE_URL);

async function subscribeToPendingTransactions() {
  try {
      subscription = await web3.eth.subscribe('pendingTransactions');

      console.log("Subscription successful");

      // Event listener for new pending transactions
      subscription.on('data', handleNewPending)
      
      // Event listener for any errors during the subscription
    subscription.on('error', (error) => {
      console.error('Subscription error:', error);
    });
  } catch (error) {
      console.error(`Error subscribing to pending transactions: ${error}`);
  }
}

// Adapted to be able to call unsubscribe correctly
async function unsubscribe() {
  if (!subscription) {
      console.error("No subscription to unsubscribe from.");
      return;
  }

  try {
      await subscription.unsubscribe();
      console.log("Successfully unsubscribed!");
      process.exit(0); // Exiting normally
  } catch (error) {
      console.error(`Error unsubscribing: ${error}`);
      process.exit(1); // Exiting with an error
  }
}

// Event listener that logs the received pendingTransactions and extracts from, to, and value fields
async function handleNewPending(transactionHash) {
  try {
      const transaction = await web3.eth.getTransaction(transactionHash);
      const from = transaction.from;
      const to = transaction.to;
      const value = transaction.value;
      if (value >= BigInt(1000000000000000000)) { // 1 ETH in Wei
          console.log(`----- New pending transaction ------`);
          console.log(`From: ${from}`)
          console.log(`To: ${to}`)
          console.log(`Value: ${Number(web3.utils.fromWei(value, 'ether')).toFixed(2)} ETH \n`)

      }
      
  } catch (error) {
      console.error(`Error getting transaction: ${error}`);
  }
}

subscribeToPendingTransactions();

This code creates a new subscription to the pendingTransactions 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 two event listener functions that are attached to the subscription object: handleNewPending and handleError. The handleNewPending function is called when a new pending transaction is received; it runs the eth_getTransactionByHash method and extracts the from, to, and value fields. If the value transferred is above 1 ETH, the data is logged.

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 subscribeTopendingTransactions function, which creates the subscription and attaches the event listeners. When a new pending transaction is received, the handleNewPending function is called to extract the data and log it to the console.