Awesome Open Source
Awesome Open Source

Crypto Whale Watcher

Build Status

Constantly looking at the order book and depth charts of different crypto-currencies on different exchanges can be painstakingly tedious. I decided to create this app to simultaneously monitor different exchanges and currencies without being bothered by insignificant trades and orders. With this app, a person can get real time trade and volume alerts from GDAX, Binance, and Bitfinex. These alerts currently occur on Telegram, but are easily switchable with other services.

Note : This README mostly deals with the setup and execution of the app. If you want to understand the working of the project and code, please refer to the wiki section.

A Note About Exchange APIs

You might notice I haven't used any of the exchanges' respective node modules in this project, and have instead gone with the raw REST APIs. This is because I did not realize these modules existed until much later into the development process. Therefore, I understand that my API calls might come with manual need for stream management. But I feel going through the documentations of these modules, then rewriting the code would cause a significant waste of time and resources until I am made to realize otherwise.

Table of Contents

Basic Setup

  1. Fork and Clone the repository

  2. Create a Telegram Bot using BotFather, note down the authorization-token.

  3. Create a group or channel, and add the bot to it. Then get the group/channel's chat_id.

  4. Create a PostgreSQL database.
    Creating Database

  5. Create a file with name ".env" in the parent directory.

  6. Add the auth-token, respective chat_id(s), and database url to the ".env" file as key-value pairs in the form shown below. These key-value pairs will be exported to the environment variables.

    • On a *nix OS, steps 5 and 6 can be combined by typing the following lines in sequence in the terminal:
      touch .env
      echo "BOT_TOKEN=<your-bot-token>" >> .env
      echo "CHAT_ID=<main-chat-id>" >> .env
      echo "TEST_CHAT_ID=<test-chat-id>" >> .env
      echo "DATABASE_URL=$USER@localhost:5432/<db-name>" >> .env
    • There is another optional environment variable for directing alerts to a test chat for development and testing purposes. If you want to do so, add the following on a new line to the ".env" file: TESTING=true
  7. Run npm install, and run the app via npm run start.


  • If you get Database errors, try running npm run db:migrate. IMPORTANT: This command deletes and recreates all tables. You will need to run this every time you make a change in the list of currencies in the config file.
  • A lot of the major hosting services come preinstalled with PostgreSQL or provide some plugin. Therefore the steps for creating and setting up the database may differ. For example, Heroku has an excellend PostgreSQL plugin which upon installation automatically adds the environment variable for the database URL.
  • On your local machine, the app will be served on port 3000 of localhost.


The app is made to use certain limits and services that may or may not be suitable for others. Therefore it is possible to make changes and customize the app to better suit the developers requirements. Please do not send pull requests to the main repository with these changes.

Currency Pairs

Currency pairs are defined in the config.js file, and can easily be added and removed as needed. One needs to be mindful to try and add pairs that are supported by both Binance and Bitfinex. Not doing so can cause unexpected behavior.


The alerts are triggered by checking the various limits for the crypto-currency. You can learn about each limit in the wiki section of this project.

Limit changes are persistent and are saved to the PostgreSQL databse on the running machine. Limits can easily be changed without affecting the repository through the browser by going to the endpoint of the running app. If you are running the app on your local machine, it'll be served on localhost:3000.

Limits can also be changed by editing the migration file, and running npm run db:migrate, in which case changes will be saved on the repository level. This method is not recommended if you plan to contribute to the main repository.


The app currently uses Telegram as the medium for alerts. However, if one requires they can choose to add and/or replace it with other services like Discord. It is recommended you keep the structure of the functions the same.

The alerts are managed in message.js.


Telegram :


Webpage :



If you are a developer trying to contribute to this project, please follow these steps:

  1. Fork and Clone the repository.
  2. Run npm install.
  3. Export the DATABASE_URL to the environment using export or adding it to a ".env" file.
  4. Run npm start or npm run start:dev to see if it runs without errors.
  5. Tests can be performed by running npm test

Please refer Contribution Guidelines for more information.


Telegram : @uzair_inamdar



Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
javascript (70,403
ethereum (747
bitcoin (574
cryptocurrency (508
binance (79
cryptocurrencies (73
cryptocurrency-exchanges (32
bitfinex (23
gdax (20
binance-api (18