> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peaq.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# eth_subscribe
In blockchain systems, pending transactions are those that have been submitted to the network but have **not yet been included** in a block. By subscribing to these events using `eth_subscribe`,
your application can receive **real-time notifications** of transaction hashes as they enter the transaction pool (mempool). This push-based approach helps build responsive decentralized applications,
monitor network activity, and provide transaction tracking or analytics in near real-time.
In this guide, we focus on subscribing to pending transactions using **`eth_subscribe`**. The provided boilerplate uses a WebSocket provider (pointing to `wss://quicknode.peaq.xyz`),
creates a subscription for pending transactions, handles incoming data and errors, and includes a graceful shutdown routine to properly clean up the subscription and disconnect the WebSocket provider.
## Prerequisites
* **Node.js Environment:** You have Node.js installed on your system.
* **Familiarity with JavaScript:** You are comfortable with JavaScript and asynchronous programming (using async/await).
* **WebSocket Connection:** You will connect to a peaq network node via WebSocket (using `wss://quicknode.peaq.xyz`).
* **Dependencies:** The required packages (`web3`, `dotenv`, and `web3-providers-ws`) are installed.
* **Basic Blockchain Knowledge:** You understand the concepts of pending transactions, mempool, and real‑time event subscription.
## Instructions
### 1. Setting Up the Environment
* **Install Dependencies:**
Ensure you install the necessary packages:
```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
npm install web3 dotenv web3-providers-ws
```
* **Set ESM Module:**
Add the following to your `package.json` to alllow for ESM modules.
```javascript theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
"type": "module",
```
* **Configure Environment Variables:**
Create a `.env` file with the following content:
```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
PEAQ_WS_URL=wss://quicknode.peaq.xyz
```
### 2. Understanding `eth_subscribe`
The **`eth_subscribe`** method is a JSON-RPC method available over **WebSocket** connections. It allows you to subscribe to various types of events on the blockchain in real-time. When subscribing to pending transactions,
the node sends updates as soon as new transactions are detected in the **mempool.** Here's how it works:
* **Subscription Request:**
When you call `web3.eth.subscribe('pendingTransactions')`, the node sets up a listener for new pending transactions.
* **Data Event:**
The subscription object returns a push-based stream of events. Each event provides the transaction hash of a pending transaction. The code attaches an event handler on the `"data"` event to process each incoming transaction hash.
* **Error Handling:**
An `"error"` event is also attached to handle any issues (e.g., network errors or connection drops).
### 3. **Implementing the Boilerplate**
The provided boilerplate performs the following steps:
* **Initialize the Provider and Web3 Instance:**
A WebSocket provider is created using `web3-providers-ws`, connecting to the peaq network RPC endpoint.
* **Subscribe to Pending Transactions:**
An asynchronous function is used to call `web3.eth.subscribe('pendingTransactions')`. Once the subscription is created, event handlers for `"data"` and `"error"` are attached.
* **Graceful Shutdown:**
A signal handler for `SIGINT` (e.g., when pressing Ctrl+C) is registered. Upon receiving the shutdown signal, the code unsubscribes from pending transactions and disconnects the WebSocket provider to ensure a clean exit.
```javascript JavaScript theme={"theme":{"light":"github-light-default","dark":"github-dark"}}
// eth_subscribe_pendingTx.js
import dotenv from 'dotenv';
dotenv.config();
import Web3 from 'web3';
import WSProvider from 'web3-providers-ws';
const WS_URL = process.env.PEAQ_WS_URL;
const provider = new WSProvider(WS_URL);
const web3 = new Web3(provider);
let pendingSubscription;
(async () => {
try {
pendingSubscription = await web3.eth.subscribe('pendingTransactions');
pendingSubscription.on("data", (txHash) => {
console.log("Pending Transaction Hash received:");
console.log(txHash);
});
pendingSubscription.on("error", (error) => {
console.error("Error in pendingTransactions subscription:", error);
});
} catch (err) {
console.error("Error subscribing to pendingTransactions:", err);
}
})();
// Graceful shutdown
process.on('SIGINT', async () => {
console.log("\nGracefully shutting down...");
try {
if (pendingSubscription) {
await pendingSubscription.unsubscribe();
console.log("Unsubscribed from pendingTransactions.");
}
} catch (err) {
console.error("Error unsubscribing from pendingTransactions:", err);
}
provider.disconnect();
process.exit();
});
console.log("Listening for pending transactions on the peaq network (eth_subscribe)...");
```
The terminal will output the pending transaction hash as follows:
## Conclusion
This guide demonstrates how to use the `eth_subscribe` JSON-RPC method to listen to pending transactions on peaq network.
Using this approach, your application can efficiently monitor the mempool for new pending transactions, enabling you to build responsive, data-driven decentralized applications on the peaq network.
Feel free to customize and extend the boilerplate code to suit your specific requirements.