📘

API Endpoint

This tutorial uses the alchemy_minedTransactions subscription endpoint.

Alchemy provides the most effective method to subscribe to mined transactions, log events, and new blocks using WebSockets on Ethereum, Polygon, Arbitrum, and Optimism. By leveraging the Alchemy SDK, you're able to access direct subscription types by simply connecting to each endpoint.
[mined

In this tutorial, we will test and create a sample project using the alchemy_minedTransactions method offered by the Alchemy SDK.

What relevance does the alchemy_minedTransactions provide to users?

• Tracking transactions being mined and notify users via SMS - Alchemy Notify API
• Display all transactions within the Ethereum network on a rolling basis

How does alchemy_minedTransactions compare to [alchemy_pendingTransactions](ref:alchemy-pendingTransactions)?
Although both these Subscription API endpoints emit full transaction objects or hashes and filter based on specified parameters, they serve two different objectives. The alchemy_minedTransactions returns entire transactions that are mined on the network whereas alchemy_pendingTransactions returns transactions that are sent to the network and marked as pending.

Developers can enhance the requests with specific parameters including:

• addresses(optional): Singular address or array of addresses to receive pending transactions sent from this address.
• includeRemoved(optional): Singular address or array of addresses from receive pending transactions sent from this address.
• hashesOnly(optional - default set to false): The response matches the payload of eth_getTransactionByHash. This is information about a transaction by the transaction hash including blockHash, blockNumber and transactionIndex. If set to true, the payload will return only the hashes of the mined transactions.

Step 0: Configure your developer environment

Before you begin, complete the following steps to set up your web3 developer environment.

1. Install Node.js (> 14) on your local machine

2. Install npm on your local machine

3. Install wscat on your local machine

To check your Node version, run the following command in your terminal:

node -v

4. Create a free Alchemy account

Step 1: Open your Alchemy App

Once your Alchemy account is created, there will also be a default app that is also created.

To create another Alchemy app, check out this video.

Step 2: Get WebSocket URL from Alchemy App

Once you have created your app, get your WebSocket URL that we will use later in this tutorial.

1. Click on your app's View Key button in the dashboard
2. Copy and save the WebSocket URL

Step 3: Output Mined Transactions Using wscat

Wscat is a terminal or shell tool used to connect to the WebSockets server. Each Alchemy application will provide a WebSocket URL that can be used directly with the wscat command.

1. Initiate the WebSocket stream
2. Enter the specific call command

The following example will use the demo key, but should be replaced with your key from Step 2.

From your terminal, run the following commands:

// initiate websocket stream first and replace demo with your key
wscat -c wss://eth-mainnet.alchemyapi.io/v2/demo 

// no param specification - return all mined txs  
{"jsonrpc":"2.0","id": 2, "method": "eth_subscribe", "params": ["alchemy_minedTransactions"]}

// to and from filters, hashesOnly = true
{"jsonrpc": "2.0", "method": "eth_subscribe","params": ["alchemy_minedTransactions", {"addresses": [{"to": "0x9f3ce0ad29b767d809642a53c2bccc9a130659d7", "from": "0x228f108fd09450d083bb33fe0cc50ae449bc7e11"}, {"to": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"}],"includeRemoved": false,  "hashesOnly": true}],"id": 1}

If successful, you should see output that looks something like this:

{"id":1,"result":"0xf13f7073ddef66a8c1b0c9c9f0e543c3","jsonrpc":"2.0"}

// hashesOnly = true
{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": {
    "result": {
            "removed": false
            "transaction": {
                "hash":"0xa8f2cf69e302da6c8100b80298ed77c37b6e75eed1177ca22acd5772c9fb9876",
            }
    },
    "subscription": "0xf13f7073ddef66a8c1b0c9c9f0e543c3"
  }
}


// hashesOnly = false
{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": {
    "result": {
            "removed": false
            "transaction": {
          "blockHash":"0xbe847be2bceb74e660daf96b3f0669d58f59dc9101715689a00ef864a5408f43",
                "blockNumber":"0x5b8d80",
                "hash":"0xa8f2cf69e302da6c8100b80298ed77c37b6e75eed1177ca22acd5772c9fb9876",
                "from":"0x2a9847093ad514639e8cdec960b5e51686960291",
                "gas":"0x4f588",
                "gasPrice":"0xc22a75840",
                "input":"0x000101d521928b4146",
                "nonce":"0x9a2",
                "r":"0xb5889c55a0ebbf86627524affc9c4fdedc4608bee7a0f9880b5ec965d58e4264",
                "s":"0x2da32e817e2483ec2199ec0121b93384ac820049a75e11b40d152fc7558a5d72",
                "to":"0xc7ed8919c70dd8ccf1a57c0ed75b25ceb2dd22d1",
                "transactionIndex":"0x14",
                "type":"0x0",
                "v":"0x1c",
                "value":"0x0"
            }
    },
    "subscription": "0xf13f7073ddef66a8c1b0c9c9f0e543c3"
  }
}

By using wscat, you are able to verify the transaction immediately via the computer's terminal or shell.

Step 4: Create a Node project

To build out a kick starter that leverages the alchemy-sdk, let's create an empty repository and install all node dependencies.

To make requests to the SDK WebSockets Endpoints, we recommend using the Alchemy SDK Quickstart.

From your terminal, run the following commands:

mkdir mined-transactions && cd mined-transactions
npm init -y
npm install --save alchemy-sdk
touch main.js

This will create a repository named mined-transactions that holds all the files and dependencies we need.

Open this repo in your preferred code editor, where we'll write our code in the main.js file.

Step 5: Output Pending Transactions using alchemy-sdk

Next, we’ll demonstrate how to use the Alchemy SDK to create an alchemy_minedTransactions subscription.

To make requests using Alchemy's minedTransactions API, we recommend reviewing the alchemy_minedTransactions docs.

Next, add the following code to the main.js file, using your Alchemy API key:

// Installation: npm install alchemy-sdk
import { Alchemy, Network, AlchemySubscription } from "alchemy-sdk";

const settings = {
  apiKey: "demo", // Replace with your Alchemy API Key
  network: Network.ETH_MAINNET, // Replace with your network
};

const alchemy = new Alchemy(settings);

// Subscription for Alchemy's minedTransactions API
alchemy.ws.on(
  {
    method: AlchemySubscription.MINED_TRANSACTIONS,
  },
  (tx) => console.log(tx)
);

Run this script by running the following command in your terminal:

node main.js

It should look something like this:

🚧

Notice stream of results

If successful, you should see a stream of transactions as the result. This stream of output indicates the all transactions that are mined on the Ethereum Mainnet.

{
  removed: false,
  transaction: {
    blockHash: '0x1a6adfef39de127f52cd451af2352a97c06cccdd6afe3a30bfa26c45165de74d',
    blockNumber: '0xf25e13',
    from: '0x30d762b88f9e4cd6aca5ee47da31538d3d02ebae',
    gas: '0x5208',
    gasPrice: '0x4486199b4',
    hash: '0x2a35069462e8ff5ae44579cce690116b0520e2c190fa75a452b50190bfec862c',
    input: '0x',
    nonce: '0x4',
    to: '0x974caa59e49682cda0ad2bbe82983419a2ecc400',
    transactionIndex: '0xae',
    value: '0x32e997e5e977820',
    type: '0x0',
    chainId: '0x1',
    v: '0x25',
    r: '0x89b952803c6e94e4caaaaa3c82d426d40fdc5471019a9ff550fc006a546a8537',
    s: '0x1d5180386250c53f7073a06d2dd02790a410e03cf1d8184cc861456bdefb2325'
  }
}
{
  removed: false,
  transaction: {
    blockHash: '0x1a6adfef39de127f52cd451af2352a97c06cccdd6afe3a30bfa26c45165de74d',
    blockNumber: '0xf25e13',
    from: '0xaccbbf7a2189a56c0dfd10bb37d8316d300dbcd4',
    gas: '0x15f90',
    gasPrice: '0x4486199b4',
    maxFeePerGas: '0x4486199b4',
    maxPriorityFeePerGas: '0x4486199b4',
    hash: '0x1c22aee60a6121ce29073a1771155216ccee54962cb235c0ec8d71b6449dd708',
    input: '0x2d2da806000000000000000000000000accbbf7a2189a56c0dfd10bb37d8316d300dbcd4',
    nonce: '0x4',
    to: '0xabea9132b05a70803a4e85094fd0e1800777fbef',
    transactionIndex: '0xaf',
    value: '0x38866cac3c00',
    type: '0x2',
    accessList: [],
    chainId: '0x1',
    v: '0x1',
    r: '0x7a7a294c5844a2b16f8b2cd5ddc3b748e3ab89215f6974f82910d95d5707b47a',
    s: '0x79f17cec79d3a66b89780345831408288c9a2c535548c5df35fd9df0692ab5a3'
  }
}

Step 6: Filter Pending Transactions

Next, we’ll demonstrate how to filter pending transactions using the alchemy_minedTransactions subscription. The filters will input an address or an array of addresses that will output mined transactions based on the parameters. These filters are (fromAddress) indicating the address that will send the transaction and (toAddress) indicating the address that will receive the transaction.

Add the following code to the main.js file, using your Alchemy API key:

🚧

Notice new filters

Within the Subscription API method, we've added three filters: addresses, includeRemoved and hashesOnly. This will enable our request to the Alchemy minedTransactions API to be filtered based on the parameters that we've assigned.

Here is what each filter is doing:

• addresses is an array with two objects that specify the mined transactions based on the address from and to.
• includeRemoved set to true includes transactions that have been removed from the chain.
• hashesOnly set to false returns a full transaction object.

// Installation: npm install alchemy-sdk
import { Alchemy, Network, AlchemySubscription } from "alchemy-sdk";

const settings = {
  apiKey: "<-- ALCHEMY APP API KEY -->", // Replace with your Alchemy API Key
  network: Network.ETH_MAINNET, // Replace with your network
};

const alchemy = new Alchemy(settings);

// Subscription for Alchemy's minedTransactions API
alchemy.ws.on(
  {
    method: AlchemySubscription.MINED_TRANSACTIONS,
    addresses: [
      {
        from: "0x473780deaf4a2ac070bbba936b0cdefe7f267dfc",
      },
      {
        to: "0x473780deaf4a2ac070bbba936b0cdefe7f267dfc",
      },
    ],
    includeRemoved: true,
    hashesOnly: false,
  },
  (tx) => console.log(tx)
);

Conclusion

You now know how to use the Alchemy SDK to check for mined transactions and filter using various parameters.

If you enjoyed this tutorial, tweet us at @AlchemyPlatform.

Don't forget to join our Discord server to meet other blockchain devs, builders, and entrepreneurs!