🔸 Superalgos 1.2.0

🔸 Table of Contents

Main Topics

• Introduction
• Before You Begin
• Getting Started
• Installation Options
• Installation for Developers and Contributors
  • Pre-Requisites
  • Superalgos Platform Client Installation
• Usage
• Uninstall
• Get In Touch
• Other Resources
• Contributing
• License

Appendix

• Workspace Refactoring for Version 1
• Pre-Requisites Notes
• Troubleshooting Dependencies Installation
• WSL2 VSCode IDE Environment Setup
• Running Superalgos on a Headless Linux Server as a Daemon

🔸 Introduction

Superalgos is not just another open-source project. We are an open and welcoming community nurtured and incentivized with the project's native Superalgos (SA) Token, building an open trading intelligence network. You will notice the difference as soon as you join the Telegram Community Group or the new Discord Server!

Superalgos is a vast project. The focus of this README file is the Superalgos Platform. Please, visit the platform's page on the website for an overview of features and functionality.

🔸 Before You Begin

Worth noting before you start:

• Online Demo | To get a feel of what Superalgos is about without installing anything, take the (limited) online demo for a spin!

• System requirements

• FAQS:

  • Before you begin

  • Trust and safety

  • Trading with Superalgos

  • Open-source strategies

• Documentation | The platform features interactive and searchable documentation counting over 1500 pages. At this point, the Docs are solely available within the app.

🔸 Getting Started

Superalgos is an ever-growing ecosystem of tools and applications. This guide will walk you through the main ways to install the Superalgos Platform — the flagship application of the ecosystem.

Once you install and launch the app, a series of interactive tutorials take you by the hand and walk you all around the system while you learn the basic skills required to use the interface, mine data, backtest strategies, and even run a live trading session. It is highly recommended to do all tutorials, as they are carefully crafted to make your onboarding as easy as possible.

✅ NOTE: Tutorials are the absolute best way to tackle the learning curve. You should do all tutorials before you start exploring other avenues on your own.

The tutorial uses Binance or Binance US as the exchange of choice. If you don't have an account with Binance or Binance US, you will still be able to follow 100% of the tutorial. When you get to the live trading section, keep going even if you don't intend to run the session. You may learn how to work with other exchanges later on. If both Binance and Binance US are blocked in your region, you will need to set up a different exchange from the get-go.

🔸 Installation Options

There are a variety of methods to install the Superalgos Platform ranging from docker installations and packaged application installations to fine-grained technical installations ideal for developers and contributors.

We will briefly describe the options available. Click the link to go to the specific README file with further instructions for the installation method of your choice.

1. Packaged and portable apps | This option is optimized for non-technical users and is by far the easiest way to get started with Superalgos. These are not suitable for development or for contributing.

2. Docker deployments | Docker installations are another avenue that allows for a clean installation. While a little bit more technical than the packaged applications, Docker offers the ability to install the platform in a clean and isolated environment. The standard Docker installation is not optimized for development or contributions, but some workarounds are offered.

3. Developers and Contributors | This is the default installation for developers that wish to dive into the codebase and contribute to making Superalgos better. It is also the recommended installation for non-developers who wish to contribute improvements to the Docs, translations, design work, and so on. Instructions are available further down this same file.

✅ ABOUT REMOTE INSTALLATIONS AND MINIMALIST HARDWARE: Remote installations and minimalist hardware — both virtual and physical — are better suited for production deployments, where the use of the GUI is minimal. We highly recommend learning Superalgos in a local installation, on a full-size PC. Mastering the system takes time, and the use of the GUI to go through in-app tutorials is crucial during the learning process. Your experience will be orders of magnitude better if you follow this advice: leave remote installations and minimalist hardware for when you are ready to start trading live.

✅ EXPERIENCING ISSUES INSTALLING SUPERALGOS? If you're having trouble installing or running the app for the first time, do not open an issue. Instead, join the Support Telegram Group and follow the instructions on the pinned message to ask for help. You may also join the new Discord Server, but bear in mind that the response time tends to be longer. Online support is provided by volunteers — please provide clear information and sufficient context about the issue you are facing, and be mindful of people's time.

If you wish to try the packaged and portable apps or the docker deployments, there is nothing of critical importance left for you on this README file. That said, the Get In Touch, Other Resources, Contributing, and License sections are certainly of interest.

If you opt for the installation for developers and contributors, please keep on reading. Otherwise, click one of the other options above.

🔸 Installation for Developers and Contributors

This is the purest, albeit more technical, way of installing Superalgos. It has no limitations to contributing, which is highly appreciated and rewarded with SA tokens, and gives you the most freedom for custom configurations.

All procedures (other than pre-requisites) are the same for Windows, Linux, or Mac OS. Raspberry Pi terminal commands have been included for ease of use. Some edge cases are covered separately, further down this README.

Pre-Requisites

1️⃣ Install Node.JS, Git, and Chrome

You will need the latest versions of Node JS and Git installed. You will also need a web browser to access the interface. Google Chrome is recommended because it is the most tested browser being used by the development team and power users.

Follow the installation wizards to install the latest NodeJS and Git. Make sure to follow all the default and recommended settings while installing Git. If desired also install Chrome.

• Node.js download page

• Git download page

• Google Chrome download page

✅ NOTE: If you wish to test the (partial and incomplete) TensorFlow integration, you will also need Python 3.

Additional notes about installing pre-requisites on specific environments and edge cases can be found in the Pre-Requisites Notes section in the Appendix.

2️⃣ Get Your Github.com Personal Access Token

You will need to get an access token from Github.com so that you may authenticate with the service from within the app and the terminal/command line.

If you don't have a Github.com account, please open one! Once you are logged in, go to the New Github Personal Access Token Page and create a new token.

Make sure you give it the repo and workflow scopes. Check the clip below for clarity:

Once you get the token, copy it and save it somewhere in your local machine. You will need to retrieve it later on.

Superalgos Platform Client Installation

Now that you have all the pre-requisites and optional environment configurations set up, we can get to the core installation of Superalgos!

There are four steps required to install Superalgos:

1. Fork the Superalgos Repository

2. Clone Your Fork

3. Install Node Dependencies

4. Install Community Plugins

5. Update Forked Repositories from The Superalgos Upstream Repositories

Let's get on with it!

1️⃣ Fork the Superalgos Repository

Scroll the page to the top. Find and click the Fork button to create your fork/copy of this repository.

✅ NOTE: On the page that opens when you click the fork button, Github gives you the option to fork only the master branch by default. You must remove the selection so that you fork all branches instead. Play the following video for clarity.

To fork Superalgos you need a Github account. If you don't have one, go ahead and create it.

✅ NOTE: A Fork is required so that the setup scripts may build the app from multiple repositories, and also for your contributions to the project. The reason why Superalgos is free and open-source is that the project has set up a collective business in which all users may participate. The way to participate is to contribute to make Superalgos better. The project's native SA token is distributed among contributors.

2️⃣ Clone Your Fork

Once the fork is created, you will land on the page of your fork. Copy the complete URL from your browser's address bar.

✅ NOTE: Notice it is your fork you will be cloning, not the upstream repository.

In your computer/laptop/server, open a command prompt or terminal. Make sure you are in a directory where you have write permissions.

✅ NOTE: On most systems, the terminal will open in your user's home directory. It's better to install Superalgos at the root folder of any of your drives, or at least in a path that is not too long. Some systems may experience issues with long paths.

Clone the git repository using the command:

git clone <URL of your Superalgos fork>

For example, if your Github username is John, the command will look like this:

git clone https://github.com/John/Superalgos

This creates the Superalgos folder in the current directory, which contains the whole installation.

3️⃣ Install Node Dependencies

After the Superalgos directory has been installed, you need to set up the necessary node dependencies. In the same command prompt or terminal you just used, type the following:

cd Superalgos

That should take you inside the Superalgos folder created by the git clone command earlier. The node setup command installs the dependencies (notice there are a few options you may use).

node setup

Available Options:

node setup <options>

Option	Description
shortcuts	Use this option to create desktop shortcuts. Otherwise, you will launch the app from the command line/terminal.
tensorflow	Use this option to include the TensorFlow dependencies, only if you intend to test the (partial and incomplete) TensorFlow integration.

If you experience any issues installing dependencies, check the Troubleshooting Dependencies Installation section in the Appendix below.

4️⃣ Install Community Plugins

Before using the software, you will need to install the plugins built by the community. To do so, just run this command from the Superalgos main folder:

node setupPlugins <Your-Github-Username> <Your-Github-Personal-Access-Token>

For example:

node setupPlugins John ghz_2pBD4Sas0iYtwQGPjTq1Xlm3Ot4KpH3RLcr5

✅ NOTE: This is the token you created on earlier steps!`

This script is going to fork all Community Plugins repositories into your own Github account, and then it will clone each of these repositories into your local Superalgos/Plugins folder. The process is designed in a way that if someday a new type of plugin is added, you just need to run this command again and it will fork the new repo and clone it. This script will also find any missing forks needed and clone them too. You are safe running this script whenever you think is good.

✅ NOTE: If you ever have issues with your Plugins repos, you can delete individual folders inside Superalgos/Plugins and run this script to fix the problems for you. Also, if you have any issues with any of your plugin forks at your Github account, you can delete the offending fork and run this script again to fix the problem.

Congratulations! Your setup is complete. Now you may finally run the app for the first time. Please, follow the usage instructions below!

5️⃣ Update Forked Repositories from The Superalgos Upstream Repositories

Prerequisites: "node setup" and "node setupPlugins" commands must be executed beforehand.

node updateGithubRepos

🔸 Usage

Partner Exchanges

The Superalgos Platform is exchange-agnostic, but the project offers partner exchanges custom support and a curated onboarding experience for their customers. In turn, partner exchanges offer preferential trading fees and, in some cases, other benefits to Superalgos users.

Find more information on how to get the benefits, join the corresponding Telegram group.

Partner Exchange	Benefits	Telegram Group
AscendEX	VIP 2 (7.5 bip Maker, 8.5 bip Taker)	https://t.me/superalgosascendex

Partner exchanges have custom workspaces for the onboarding of their users.

Run the Client and GUI

Using the shortcuts

✅ NOTE: This method launches the platform with the fallback workspace only. If you wish to launch with a partner exchange workspace, use the Command Line method instead.

If you ran node setup shortcuts while installing dependencies, then you should have a desktop icon that you can double click to launch the Superalgos application. A terminal window will show the server is running, and a browser window will open with the GUI.

Using the Command Line

To launch the platform with one of the Partner Exchanges custom workspaces, go to the Superalgos directory and run the command as per the following table. You will learn about other options further down this page.

Partner Exchange	Launch Command
AscendEX	node platform Foundations 01-Onboarding-AscendEX

✅ NOTE ABOUT ASCENDEX: An issue with AscendEX API may prevent the Welcome to Superalgos tutorial to run as expected. We suggest you use the fallback/default workspace in the meantime. The issue was reported to the exchange and is currently being investigated.

To run Superalgos with the default/fallback workspace, go to the Superalgos directory/folder and run this command:

node platform

Options usage:

node platform <options> <project> <workspace>

Option	Description
minMemo	Run with minimal memory footprint. This is critical for running on platforms with 8GB of RAM or less, like a Raspberry Pi.
noBrowser	Do not open the GUI in a browser. This is useful on headless servers where a UI is not available.

To load a specific workspace on launch, add any option you may require, then the project, then the workspace. For example, to load the Blank-Template workspace of the Foundations project with no options:

node platform Foundations Blank-Template

The Client will run on your terminal and the GUI will launch on your default browser. If Chrome/Safari is not your default browser, copy the URL, close the browser, open Chrome/Safari, and paste the URL. Be patient... it takes a few seconds to fully load the GUI.

Usage Notes

We are testing the UI on Google Chrome and Safari on macOS only. It may work on other browsers as well — or not. If you are running on a different browser and ever need support, make sure you mention that fact upfront, or even better, try on Chrome/Safari first.

✅ TIP: If your computer has 8 GB of RAM or less, use node platform minMemo to run the system with minimal RAM requirements.

🔸 Uninstall

Superalgos writes nothing outside of the Superalgos folder other than shortcut files. To quickly remove the shortcut files, open a terminal or command prompt, navigate to your main Superalgos directory, and type the following command:

node uninstall

Then simply delete the Superalgos folder to completely remove the application.

🔸 Get In Touch

We just opened a brand new Discord server for Support and the Community.

We also meet on several Telegram groups, where it all started!

⚠️ BEWARE OF IMPERSONATORS — SCAMMERS ARE LURKING! Superalgos Admins, the Founding Team, and Community Mods will never contact you directly unless you contact them first. We will never ask you for API keys, coins, or cash. We will never ask you to trust us in any way. Our Community Safety Policy explains why. In short, we want to make it clear that if someone contacts you directly claiming to work with or for the project, it is a scam. Please report scammers in the Community group so that they may be banned and to increase awareness of the problem, but also block them and report them to Telegram if the option is available.

• Via Telegram: online support through our Superalgos Support Group.

• In-App Integrated Documentation: Superalgos features interactive documentation built into the system.

• Video Tutorials: subscribe to the Superalgos YouTube Channel.

• In-App Tutorials: there are many interactive tutorials you may do and learn from.

🔸 Other Resources

• Web Site

  • For an overview of what Superalgos can do for you, check the Superalgos Website.

  • List of community resources featuring written, audiovisual, and interactive content.

• Telegram

  • For official news, join the Superalgos Announcements Channel.

  • Meet other users in the Superalgos Telegram Community Group.

  • Meet developers in the Superalgos Telegram Developer's Group.

  • Users meet in other topic-specific Telegram Groups. There's a complete list of groups on the website.

• Blog: find official announcements and various articles on the Superalgos Blog.

• Twitter: to stay in the loop, follow Superalgos on Twitter. Help us spread the word!

• Facebook: follow Superalgos on Facebook.

🔸 Contributing

Superalgos is a Community Project built by users for users. Learn how you may contribute.

🔸 License

Superalgos is open-source software released under Apache License 2.0.

---

---

---

---

---

APPENDIX

🔸 Workspace Refactoring for Version 1

Version 1.2.0 carries with it a reorganization of the codebase where several projects were extracted from Foundations: Data-Mining, Algorithmic Trading, Machine Learning, and Community Plugins.

This means that these projects can now have a project leader and a team working on them.

To get your custom workspace upgraded to be compatible with beta 13 you will need to make a few changes:

Project nodes need to be present in the workspace for things to work. The presence of the node of a project, somehow, enables that project features at a workspace. Go to the workspace node and click add missing projects.

At the Plugins hierarchy, new guys appear, each one with their own type of plugin. Meaning that every workspace needs to be manually fixed because, currently, all plugins are loaded from the Foundations node there. The fix is easy though, it takes 2 - 3 min to delete the child nodes from the Foundation node, and add the same plugins from the project they belong to now.

🔸 Pre-Requisites Notes

Windows Pre-Requisites

When following the windows installer for Git, it is very important to make sure that you follow all the recommended and default settings. One of the most important one of these can be found in the screenshot below:

Optional Windows Pre-Requisites

For windows users interested in testing the (partial and incomplete) TensorFlow integration, you need to install Python.

• install Python 3.9.

Github Desktop is a helpful tool to manage Git conflicts and issues. You can install it using the following link.

• GitHub Desktop download page. Click the "Download for Windows" button and follow the wizard to install after the download completes.

Mac OS Pre-Requisites Homebrew Installation

Rather than manually installing NodeJS, Git, and Python, Homebrew can be used to install the pre-requisites with minimal effort on Mac OS. After you clone the repository, change the directory to the Superalgos base and install the requirements using Homebrew.

There are two ways to use Homebrew. The first is to type:

brew install git node npm [email protected]

The second is to use the Brewfile included in the code repository. After downloading, run this command in the same directory where the Brewfile resides:

brew bundle

✅ NOTE: You can use Safari or Google Chrome as your default browser. If you run into a bug in Safari, you will be asked to reproduce it in Chrome as the development team uses Chrome.

Linux (e.g. Ubuntu, or Raspberry Pi running Raspberry Pi OS/Raspbian) Pre-Requisites

Follow the Node.js package manager install instructions for your distribution to ensure you are getting the latest version of Node.js. Many distributions only maintain an older version in their default repositories.

✅ NOTE: Python 3 is only required for testing the (partial and incomplete) TensorFlow integration.

curl -sL https://deb.nodesource.com/setup_17.x | sudo -E bash - && sudo apt-get \
install -y \
nodejs npm git python3

You may verify the installed versions with this command string:

node \
-v && npm \
-v && git --version

If you are running headless (i.e. as a server without a monitor attached) then you do not need to install a web browser and you can follow the tutorial for information on connecting remotely to the server.

Alternatively, you can use https://github.com/nymea/berrylan to set up a tool for using Bluetooth to quickly assign WPA2 access on a WLAN on a Raspbian based Distro. Nymea also has tools for automation of IoT products to allow setting up SuperAlgos as a timed function without needing to learn how to code.

✅ IMPORTANT:

If you are having node version errors there is a chance you may need to read the information in the Debian Pre-Requisites section and use NVM to handle node versions. This is due to some distributions having out-of-date repositories in the package manager lists.

Debian or Debian WSL/WSL2 Pre-Requisites

(NVM & NPM Fix)

Debian distributions have been found to have some additional issues with installing the right version of NodeJS needed to run Superalgos. What follows are the steps to fix this issue.

For this to work you will need to [use NVM to install and control node] (https://github.com/nvm-sh/nvm)

• You will need to remove any versions of Node already installed on Debian due to the repositories currently being out of date.

• This is necessary before proceeding.

sudo apt remove nodejs -y

sudo apt \
update && apt upgrade \
-y sudo apt \
install npm -y

sudo apt \
autoremove -y && \
sudo apt autoclean -y

sudo curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash

Without running the next 3 commands, you will need to logout off your shell/WSL2 user account before you are to use NVM

export NVM_DIR="$HOME/.nvm"

[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

Make sure things are up to date and packages not needed are removed

sudo apt update &&\
sudo apt upgrade && \
apt autoremove -y

cd Superalgos

into the directory of SuperAlgos and run the install commands as follows:

nvm run node <command string/var>

✅ NOTE: This is for node.js/node only, npm should work fine with Debian.

🔸 Troubleshooting Dependencies Installation

Edge Cases

✅ NOTE FOR WINDOWS USERS INSTALLING TENSORFLOW DEPENDENCIES: You may get an error at the end of the setup process. If you do, please follow the instructions following the error message.

✅ NOTE FOR USERS INSTALLING MULTIPLE INSTANCES OF SUPERALGOS ON THE SAME MACHINE: To avoid name conflicts between shortcuts, make sure to rename each Superalgos directory before running node setup shortcuts.

✅ NOTE FOR USERS INSTALLING ON LINUX: If after running node setup you are prompted to address issues by running 'npm audit fix' ignore this step.

✅ NOTE FOR USERS INSTALLING ON COMPUTERS WITH 1GB OF RAM Superalgos has just about outgrown computers with only 1GB of RAM. For Instance a Raspberry Pi 3 does run the Getting Started Tutorials, but over time (Into 2023) this may significantly slow and could even stop. If still wish to use a computer with only 1GB of RAM (you have been warned), you will need to use version 16.x of Node.js as version 18.x needs well over 1 GB of RAM during setup.

General Troubleshooting

If you are having difficulty running the node setup command here are a few common issues that may be getting in the way.

1. Check the version of node and npm you have installed. Make sure that you are running an updated version of node greater than version 16.6 and npm greater than version 5. You can check which version you have by typing node -v and npm -v into a command prompt or terminal. If your version numbers are below these, you can update your installation by following the instructions outlined in the "Node JS Installation" step above.

2. If you are installing Superalgos in an administratively protected directory you will need to do one of the following:

   • For Windows start your command prompt as an administrator.

   • For Linux and Mac Systems make sure to add the sudo command to node setup. This will look like sudo node setup.

3. For Windows it is important that you have C:\Windows\System32 added to your global PATH. For instructions on how to do this google "add to the path on Windows 10."

4. If you are getting a lot of 'unexpected' errors during node setup, try resetting npm using the command npm ci before running node setup again.

Enabling Desktop Shortcut in Ubuntu

The majority of shortcuts that are installed will work out of the box. Desktop shortcuts on Ubuntu, however, require a few additional steps to set up. First, desktop icons need to be enabled within the Tweaks app.

• Check if Tweaks is installed.

• If not go to Ubuntu Software.

• Install Tweaks.

• Open Tweaks.

• Under extensions turn on Desktop Icons

✅ TIP: If you do not see the desktop shortcut appear right away you may need to restart your computer.

Finally, you will need to enable the desktop shortcut. Right-click Superalgos.desktop and select Allow Launching.

Now both launcher and desktop shortcuts will launch Superalgos like any other program on your computer.

🔸 WSL2 VSCode IDE Environment Setup

VSCode is a popular IDE. This short section covers some helpful tips for setting up the IDE's development environment.

There are a few things that need to be configured to obtain full functionality from VSCode. These configurations will make it possible to run notebooks for ML/AI algos and turn VSCode and Windows into a development bench for working with Superalgos.

On windows:

• First, you need to install WSL and WSL2 https://docs.microsoft.com/en-us/windows/wsl/install then reboot if prompted.

  • You may want to review the Docker WSL2 Backend information for VSCode as well before proceeding. https://aka.ms/vscode-remote/containers/docker-wsl2

  • Install Debian or Ubuntu from the Windows Store, Setup the VM as instructed.

On windows and Debian:

To make managing these WSL instances a lot easier, we will now move to installing VSCode + Tools to allow for Dockerizing and rapidly deploying as well as editing and managing test/usage cases of Superalgos edit and forks you create and contribute.

• Install VSCode https://code.visualstudio.com/docs/?dv=win64user

  • Install the remote container and remote docker plugins/extensions for Visual Studio Code https://code.visualstudio.com/docs/remote/containers#_installation

    • You may want to spend time reading the specifics of this documentation on their website.

  • When prompted install shell shortcuts for right-click options, this way you can open Superalgos easy inside of VSCode.

✅ IMPORTANT:

As mentioned above, you need to remove node.js/node from your system and install NVM if you are using Debian. Please refer to the information above for properly setting up node.js and npm on Debian systems with complications regarding versions of node.

Once the install finishes you can now use VSCode as an interactive IDE/Shell to access SuperAlgos, run Dockers for working with Superalgos, and more.

🔸 Running Superalgos on a Headless Linux Server as a Daemon

If you're running Superalgos on a headless Linux server like a Raspberry Pi, you might want to run it as a daemon so it isn't attached to your current login session. The easiest, most standard way to go about this is probably using systemd. Most Linux distributions use it as the default init system/service manager.

Create a superalgos.service file looking like this (change <user> to your user name and /path/to/Superalgos to your Superalgos folder, for instance /home/John/Superalgos):

[Unit]
Description=Superalgos Platform Client

[Service]
Type=simple
User=<user>
WorkingDirectory=/path/to/Superalgos
ExecStart=/usr/bin/node platform minMemo noBrowser

[Install]
WantedBy=multi-user.target

There is no need to run Superalgos as root so we're running it as a user. The minMemo option assumes you're running on a small machine like a Raspberry Pi, while noBrowser makes sense for running daemonized. Now, you'll need to move the file to /etc/systemd/system/ for it to be recognized. You'll need then to enable and start the service.

sudo mv superalgos.service /etc/systemd/system
sudo systemctl daemon-reload
sudo systemctl enable superalgos
sudo systemctl start superalgos

To check the service status

sudo systemctl status superalgos

To stop the service:

sudo systemctl stop superalgos
sudo systemctl disable superalgos

To see the output of Superalgos, use:

journalctl -u superalgos

or to follow the output with -f:

journalctl -u superalgos -f