Skip to content

  Nodesmith users! Bloq delivers connectivity for The OAN. Learn More

The Sync Blog

Updates and insights from the Bloq team

« Blog Home

How to: Create Your Own “Whale Alert”

Build Your Own Whale Alert

A while back, a Twitter account with the handle @whale_alert posted that 50 bitcoin, mined in 2009, moved for the very first time and resulted in a 7% selloff. That this caused plenty of speculation underscored that bots designed to auto-magically deliver interesting information has some utility.

In our previous installments, we worked through step-by-step instructions to parse blockchains for various information — blocks, balances, transactions, and so on.

Putting elements of this together, we’ll outline the steps required to create a “Whale Alerts” program to track large Bitcoin transactions, filtered by transaction size and/or addresses.

If this is your first time using Bloq, follow the Getting Started guide to create your Bloq account before continuing.

Websocket for Transaction Streams

With the Bloq Connect Websocket API, users can set up a room that listens for and reports Bitcoin or Bitcoin Cash transactions as they broadcast to the network, in real-time. (You might remember our Websocket lesson from earlier.) 

Websocket rooms can be specified to listen for some combination of transactions, blocks, and addresses. For the purpose of a “Whale Alerts” bot, we’ll set the room to listen in for transactions:

When executed, the above code will listen and report all incoming Bitcoin transactions as they are broadcast. It also includes messaging to highlight any error or disconnection that may occur.

Save this code as a Javascript file (.js extension). You’ll need to replace the ‘token’ field with your own access token. A Client Access Token can be created at the Connect tab of the Bloq Console website. You can additionally create your Client Access Token directly in the command line by following these steps.

Navigate to the location of your file in your terminal and run it with node filename.js.

Each broadcast transaction will be displayed by its transaction id (txid), output value in BTC (valueOut), recipient addresses and amount received in satoshi (vout), and whether or not it was a replace-by-fee transaction (isRBF).

Filtering Transactions

While the above code is interesting to see, it’s not yet intuitive for proper “Whale Alerts” signaling.

Filter by Size

First and foremost, transactions must be filtered based on their size. For this example, let’s ignore every transaction smaller than 5 BTC. In order to do this, an ‘if‘ statement can be used to assert only to print the transaction when the ‘valueOut‘ variable of the transaction is greater than 5 (BTC). We’ll create a constant to determine the size we want to filter by. Here’s how function(tx) looks with these changes:

Now, the room will only log transactions of more than 5 BTC. But the output is still somewhat clunky, as the entire contents of the transaction are displayed. Let’s tweak the console.log() to just report the components of the transaction that are needed:

When the room is set up with the following code, printed transactions will read as follows:

Large Transaction!
Size: 5.12345678 BTC
To: [ { 'outputaddress1': 500000000 },
{ 'outputaddress2':  12345678 } ]
Transaction Id: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

To take things a step further, the function can be filtered further by recipient address. This is useful to track deposits to exchanges. The ‘vout‘ variable can be parsed for strings corresponding to the desired deposit address. 

The ‘vout‘ variable is a JSON array, where each recipient address corresponds to its own entry. A for loop can be used to analyze each address. The .stringify() method is used to convert the line to a String, then the outputs can be scanned for a certain address or tag with .includes().

For example, every Bitmex deposit address begins with “3BMEX”. Just like before, a constant set to “3BMEX” allows us to filter by the tag.

We’ll also have to adjust the code to filter for the size of the transaction to the specified address. The parseInt() method allows us to grab the transaction size to only the Bitmex deposit address. This value will have to be converted from satoshis to BTC by dividing it by 100,000,000.

For purposes of the demonstration, we’ll lower the filter threshold to 0.1 BTC, too. Here’s what the updated code looks like:

For one final improvement, the Date() method can be logged to give us a timestamp of when the large Bitmex deposit was broadcast:

Next Steps

With your room situated to filter the transactions as you desire, the next steps involve packaging the code into whichever solution you’re looking to build out. This could look like a bot for the likes of Twitter, Telegram, or Discord, or perhaps as a website feed.

To display the “Whale Alerts” as a web page, you will need to convert the file to HTML. Here’s how what the above code looks like as an HTML file:

Save this file as HTML (.html extension) and open it through your web browser. Because the outputs are still displayed via console.log(), they’ll be displayed through the browser console instead of the page itself.

To display the transactions as they are received, console.log() instances must be replaced with document.write(). HTML doesn’t recognize objects, so you’ll have to display the “stringified” variable for ‘vout‘ instead of the object itself. With some adjustments for formatting, the website-ready code is as follows:

Because this is Javascript within a larger html file, “<br>” tags are also required to add line breaks between statements. The Javascript “\n” character will not work as intended. Input this code into a section on an existing html webpage to enable your own “Bitmex Whale Alerts” feed!