search

timelyart / Kairos

Kairos aims to help you save time by automating repetitive tasks on TradingView such as scanning markets for setups, and refreshing alerts as well as creating new ones.
GNU General Public License v3.0
70 stars 31 forks source link

readme

GitHub Release Date

Updates Python 3

Kairos

Web automation tool using Python, Selenium and Chrome's Web Driver. Kairos aims to help you save time by automating repetitive tasks on TradingView such as refreshing alerts and creating new ones.

Besides this document you can also find instructional videos here.

Table of contents

Features

Prerequisites

Note: when you install Python on Windows make sure that it's part of your PATH.

Installing

If you run Ubuntu there is a list of commands here: Ubuntu - command line installation.

From archive (Linux, OS X and Windows)

If you are running Linux / OS X then run listed commands with sudo

From source

Ubuntu - command line installation

cd ~/
wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
echo 'deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main' | sudo tee /etc/apt/sources.list.d/google-chrome.list
sudo apt-get update
sudo apt-get install google-chrome-stable
sudo apt-get install unzip
sudo apt-get install python3.11
pip install setuptools
pip install --upgrade setuptools
sudo apt-get install xvfb xserver-xephyr tigervnc-standalone-server x11-utils gnumeric
python3 -m pip install pyvirtualdisplay pillow EasyProcess
wget https://chromedriver.storage.googleapis.com/2.43/chromedriver_linux64.zip
unzip chromedriver_linux64.zip
sudo mv chromedriver /usr/bin/chromedriver
sudo chown root:root /usr/bin/chromedriver
sudo chmod +x /usr/bin/chromedriver
mkdir -p Git/repositories
cd Git/repositories/
git clone https://github.com/timelyart/Kairos.git
cd Kairos/
sudo python3 setup.py install

Configuring Kairos

Editing YAML files

When it comes to configuring Kairos, there are two type of files:

You may find that both file types have the same setting, i.e. run-in-background. In these cases the YAML file will take precedence over kairos.cfg.

This may sound a little abstract and where to begin? Luckily, Kairos comes with a number of templates/example files.

Generally speaking, you want to remove the _ (underscore) from the file name prior to editing it. This ensures your file doesn't get overwritten with a future update of Kairos. Please read the inline comments of the templates carefully. They are there to give context and necessary information.

YAML within YAML

As of version 1.3.0 you can load YAML files from any other YAML file by including the following in your YAML file:

file: path_to/my_other_yaml_file.yaml

Consider root.yaml:

root:
  - branch:
      - branch: ["leaf", "leaf", "leaf"]
      - file: "branch_in_branch.yaml"
  - branch: ["leaf", "leaf", "leaf"]
  - file: "branch_in_branch.yaml"

By using other YAML files you can re-use parts of your YAML and share them with other YAML definitions you may have.

If you find yourself copying and pasting a lot, you might want to consider to put some or all of that code into a separate YAML file.

The files needed to run root.yaml can be found in the folder yaml and I highly encourage to look into them to figure out how they work.

When creating/editing YAML files you have to be careful with indentation, and you might want to use a website like https://yamlchecker.com to check your YAML before running it with Kairos. Also, note that values are case-sensitive.

Troubleshooting YAML

When Kairos runs, it will create a temporary copy of your YAML file called my_file.yaml.tmp. This temporary file includes your YAML file (obviously) but also any YAML file that gets referenced from your YAML files.
In case of an error, a my_file.yaml.err will be created. Kairos error messages will reference the line and column number of the .err file.

Examples

The rest of this chapter will elaborate on setting up various use cases with YAML files.
Signals are the core of Kairos and strategies are really useful for automatic backtesting. Although Alerts have largely become obsolete with Signals, they are still expanded upon here. They were the core of version 1 after all, and may still prove to be useful to some.

Alerts

Please read Editing YAML files if you haven't done so already.

Steps:

You can define in one file multiple charts with each chart having multiple alerts, like this:

charts:
- url:
  timeframes: []
  watchlists: []
  alerts:
  - name:
    conditions: []
    trigger: "Once Per Bar Close"
    expiration: 86400
    show_popup: no
    sound:
      play: no
      ringtone: Hand Bell
      duration: 10 seconds
    send:
      email: yes
      email-to-sms: no
      sms: no
      notify-on-app: no
    message:
      prepend: no
      text:
  - name:
    conditions: []
    trigger: "Only Once"
    expiration: 2
    show_popup: no
    sound:
      play: no
      ringtone: Hand Bell
      duration: 10 seconds
    send:
      email: yes
      email-to-sms: no
      sms: no
      notify-on-app: no
    message:
      prepend: no
      text:
- url:
  timeframes: []
  watchlists: []
  alerts:
  - name:
    conditions: []
    trigger: "Once Per Bar Close"
    expiration: 86400
    show_popup: no
    sound:
      play: no
      ringtone: Hand Bell
      duration: 10 seconds
    send:
      email: yes
      email-to-sms: no
      sms: no
      notify-on-app: no
    message:
      prepend: no
      text:

Signals

Please read Editing YAML files if you haven't done so already.

As of version 2, you can screen markets based upon indicator values. Kairos can read indicator values and then use these values to determine if a particular setup has fired or not. For example, when the 50 SMA has crossed the 200 SMA (Golden Cross). Kairos can read the values of multiple indicators and has a simple equation language to determine if indicator values meet the requirements of setups. The equation language is built up in the following format: 

<left-hand-side> <type> <right-hand-side>

Where <left-hand-side> and <right-hand-side> is either a fixed value, or an indicator value at a specific index; and where type is one of the following: =, <=, >=, <, >, !=. A YAML definition might be:

    trigger:
      # The left and right hand side can have one (or both)of the following values:
      # - index: indicator provided value found at the defined index
      # - value: a literal value which can be anything
      # If both index and value are set, then index will take precedence
      left-hand-side:
        index: 6
        value:
        # list of values to ignore, e.g. you can use this to ignore "n/a" values
        ignore: [n/a, 0.00000000]
      right-hand-side:
        index: 7
        value:
        ignore: [n/a, 0.00000000]
      # Define how the equation should be processed. Possible values are: =, <=, >=, <, >, != (use quotation marks)
      type: ">"

Meaning that in order for Kairos to signal the value found at index 6 of the indicator must be greater than the value at index 7.
You can define multiple indicators each with their own trigger. Only when each trigger for every indicator returns 'true', will Kairos notify the user that the setup has triggered.

Generic Template

Use the _signal.yaml as a base for your own yaml file.
_Note: _signal_golden_cross.yaml has more settings filled in for you and may be easier to start with (see Golden Cross Template)._

Steps:

Golden Cross Template

Use the _signal_golden_cross.yaml as a base for your own yaml file.

Steps:

Strategies

You can use strategies to backtest TradingView strategies, much in the same way as signals or alerts. Kairos will run your TradingView strategy for each symbol on your watchlist(s) and save the results for you in a JSON file. You can open the JSON with your favorite web browser or text editor. The results that are saved are per timeframe, symbol and per different input/property setting (see below). Kairos will also aggregate results to help with analyzing the data.

Much like you can set alerts, you can set the inputs/properties of a strategy as well. This can be any number of combinations of inputs and properties, but try to keep the number down as Kairos will run a strategy for each combination of inputs and properties.
A word of caution, running large watchlists with a lot of different combinations of inputs/properties will be notoriously slow and can take up hours, or even days. Since TradingView has a limit on how long you can keep a session with them open, Kairos might fail before it has finished. The best way to work around this, is to first identify optimal inputs/properties for a strategy by limiting your watchlist. After you have found good candidates of input/property combinations, you can then use them in a separate run on a bigger watchlist.

The yaml to define strategies is something like below. 

strategies:    
  - name: "my_strategy"
    pane_index: 0
    inputs: {my_first_input: 6, my_second_input: [60, 240, 1D, 1W], my_third_input: yes}
    properties: {initial_capital: 1000, base_currency: EUR, order_size: {0: 1 - 5&1, 1: '% of equity'}, commission: {0: [0.25], 1: '%'}, verify_price_for_limit_orders: 10, slippage: 10, recalculate: {after_order_filled: yes, on_every_tick: no}}

Note, that the example yaml files contain a lot of inline comments to help you with filling them out.

Generic Template

Use the _strategies.yaml as a base for your own yaml file.

Steps:

These issues are all related and amount to Kairos unable to either find an element or to interact with an element. You will get errors (see debug.log) like:

Solutions

Run multiple times

If you are running Kairos for the first time, then Chrome hasn't cached anything yet. Try to run it a couple of times and ignore any errors. Of course, clearing the cache will, in all likelihood, spawn the same issues again.

Run on a different time of day

At certain times during the day TradingView can become less responsive. Try to run Kairos on a different time. If the issue persists, try to Increase delays

Increase delays

If you have run Kairos five times or so, and still encounter issues try to increase the _breakmini, break and / or _submitalert in the kairos.cfg.

Check existing issues

If, after increasing wait times, you still get errors then the markup of the web page may have changed. Check if it is an existing issue, and if it is not: open one.

Feedback

Feedback is invaluable. Please, take the time to give constructive feedback by opening an issue so that this project may be improved on code and documentation.

Acknowledgements

DorukKorkmaz, for providing a starting point with his TradingView scraper.

PaulMcG, for his timing module

Author

timelyart

Donate

If you find value in this project, and you would like to donate, please do so here

License

This project is licensed under the GNU GPLv3 License - see the LICENSE.md file for details.