Metadata-Version: 2.1
Name: kolaBitMEXBot
Version: 1.1.3
Summary: Trading bot with trail stop and chained orders for pour Bitmex and maybe more...
Home-page: https://github.com/maliky/kolaBitMEXBot
Author: Malik Koné
Author-email: malikykone@gmail.com
License: UNKNOWN
Description: Kola BitMEX Bot
        ===============
        
        Presentation
        ------------
        
        KolaBot is a program to handle concurrently several pairs of orders in
        the BitMEX exchange. A pair is a main order (amoung those allowed by
        BitMEX) and an opposite order (again among allowed) that acts as a stop.
        Each order enter the book based on conditions you set in
        `morders.tsv <https://github.com/maliky/kolaBitMEXBot/blob/master/kolaBitMEXBot/morders.tsv>`__.
        
        Main conditions
        ~~~~~~~~~~~~~~~
        
        -  time condition: an order activate if the time enters the [dateA,
           dateB] range
        -  price condition: an order activate the market enters the [priceA,
           priceB] range
        
        other conditions
        ~~~~~~~~~~~~~~~~
        
        -  a timeout: an order will cancel after timeout minutes. Note this
           enable speed conditions (eg. activate only if price rise by 60ø in 1
           minute, else cancel and restart)
        -  a repeat #: an order will repeat # times if canceled or filled
        -  a waitting time: if canceled or filled the order pair will wait
           before repeating (min wait ~1 minute)
        -  a hook condition: (new not fully stable yet), an order will activate
           if a hooked order reach a specified status (filled, partialy filled,
           canceled)
        
        Units
        ~~~~~
        
        -  time units: they are generaly in minutes and for some command line
           params, in seconds.
        -  price units can be:
        
           -  relative to market price (index, mark or last Price)
        
              -  in %, of the activating price (eg. if price move by 5% from
                 order activation)
              -  in differential of the activating price (eg if price move by
                 -80ø from order activation)
        
           -  absolute, (eg. if price reach 3500ø)
        
        Options specific to the stop order
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        By defaut kolaBitMEXBot runs an opening order (main) and a close order
        (secondary or tail or trail). If your main is a buy, the secondary will
        be a close and vice-versa. It is possible to run only one of the two
        order by setting automatic cancelation condition on the not wanted
        order.
        
        Here's a simple example: A buy at market (main order) with a stop at
        market (secondary order). You just need to set the price differential
        between the main order and the tail order. Like you want a tail at:
        
        -  100ø below the activating price (relative in differential),
        -  or at 2% below of the activating price (relative in %),
        -  or at 2500ø what ever the activating price (absolute)
        
        Example scenarios
        ~~~~~~~~~~~~~~~~~
        
        -  you may want to buy 10% of your available balance if the index price
           goes down by 2% in 2 hours but this should only true for the next 24
           hours.
        
        -  you may want to place a simple buy limit if the price goes up by 100
           USD and then automatically set a (trailing) stop at this higher price
           - 20 USD. This trail stop actually acts both as a stop order and a
           trail stop. If the market moves against you, it stays in place but if
           the market move in your favor it will only move once the price will
           be 20 or higher above the entry price (in this example). Also you can
           set in the code some flexibility to the trail. Meaning that if the
           price rise quickly the trail price will close down on the order up to
           20% of the initial 20 USD delta you set. This is because usualy chart
           increase are followed buy sharp reverse and I think it's wise to go
           out of the market to pick it up automatically later.
        
        -  you may want to use a sell (short) each time the price hits 20000 USD
           with a buy at stop 21000 USD and if the stop trigger wait 20 minutes
           before resetting the condition.
        
        All this and more is feasible with this bot. I do not recommend using it
        to do trading below 1 order per minute unless you have special API
        arrangement with BitMEX and in that case you should have an improved
        bot. :o). The reason is that if you have several orders even If I use
        the websockets, I make REST call that increase with the number of order
        pairs to track.
        
        Hooks: Update <2020-05-05 mar.>
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        You can now use hooks or what was once called chained order in BitMEX. A
        hook condition is a condition that is true if the hooked order reach the
        state defined in the condition. The states can be Filled (F), Triggered
        (T), Canceled (C) or PartiallyFilled (P) Since orders are always passed
        in pairs. The hook condition can apply to the Principal order (the one
        to enter the book) or the Secondary order (the one to exit). The syntax
        to define the hook condition is as follow \`<name>-[P|S]-[F|C|T|P]\`
        
        -  Examples:
        
           -  src1-P-F, will hook when the principal order of the pair named
              src1 will be filled
           -  src1-P-C, will hook when the principal order of the pair named
              src1 will cancel
           -  foo-S-P, will hook when the principal order of the pair named foo
              will partially fill …
        
        #. Why hooks ?
        
           Hooks can be useful especially with trail orders. Hook price and time
           settings are relative to the moment their are started. So you can
           have an order that enter the book when a trailing stop is filled.
           This could be useful to catch reversal in momentum.
        
        Installation
        ------------
        
        Download or clone the repository
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Git Project URL: https://github.com/maliky/kolaBitMEXBot
        
        .. code:: bash
        
           git clone https://github.com/maliky/kolaBitMEXBot.git
           cd kolaBitMexBot
        
        Install dependencies
        ~~~~~~~~~~~~~~~~~~~~
        
        This will create a virtualenv and install packages required by the
        program. You need to \`pip3\` and \`python3.8\` installed on your
        system. *note To install mutliple python on your system, check
        \`pyenv`.*
        
        .. code:: bash
        
           virtualenv --python=</path/to/python3>  .
           source ./bin/activate
           pip install -r requirements.txt
        
           # run main programmes
           python -m  kolaBitMEXBot.run_multi_kola -h
           python -m  kolaBitMEXBot.multi_kola -h
        
        pip install
        ~~~~~~~~~~~
        
        If you just want to use kolaBitMEXBot, you can install the module
        directly with \`pip\`
        
        .. code:: bash
        
           pip install kolaBitMEX
        
        would recommand doing it as a pip editable module with:
        
        .. code:: bash
        
           # build package with the setup.py
           python setup.py sdist bdist_wheel; twine check dist/*
        
           # if you used virtualenv wheel and twine will have been installed
        
           # install the package from local source
           pip install -e . 
        
        Add you API keys in \`kolaBitMEXBot/kola/secret.py\`
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        This file created and it should contain the 4 variable keys:
        
        ::
        
           LIVE_KEY = "zIKTHISISARANDOMKEYNHII3"
           LIVE_SECRET = "HUMOI9OkK89aIoXDAND THIS IS A SECRET0KAthnauwKj0"
           TEST_KEY = "THEn_XATESTgXOcfKEYbuttz"
           TEST_SECRET = "ANDjmJ3tbACz12VERYnzJS7LONGrPKI3r4uSECRETMU2C4HO"
        
        Write your orders in the `morder.tsv <https://github.com/maliky/kolaBitMEXBot/blob/master/kolaBitMEXBot/morders.tsv>`__
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Test your orders on testnet.BitMEX.com
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        .. code:: bash
        
           python -m kolaBitMEXBot.run_multi_kola -l INFO > testlog.org
        
        Check the testlog.org file
        
        Satified? Run it live!
        ~~~~~~~~~~~~~~~~~~~~~~
        
        .. code:: bash
        
           python run_multi_kola.py -l INFO --live
        
        Extension TODO
        --------------
        
        .. _make-chained-or-hooked-orders-2020-05-05-mar.:
        
        DONE make chained (or hooked) orders <2020-05-05 mar.>
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        That is, you can an orders starting based on the state of one or more
        other orders.
        
        Extend dummy bargain to have a personnal test net
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        Write hyptothesis tests
        ~~~~~~~~~~~~~~~~~~~~~~~
        
        FAQ
        ---
        
        Why is it free ?
        ~~~~~~~~~~~~~~~~
        
        #. Because I had fun making it.
        #. Also because the gift you may give me having fun using this code,
           will be infinitely more valuable for me, if its free.:o)
        
        381b5ygUaK3CpHSKH2kKYCYKGMUbH4ruiw (BTC only)
        
        Did I loose money with that bot ?
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        No, but this is a personnal investissement. I spend a gift of 0.5 XBT to
        test it live, and during the development phase which I started in
        September 2017 I used most of it. The reasons are simple: I didn't know
        much about trading and I'm not a professional coder. Also, testnet is
        not as good as real market to make real tests. I'm confident that this
        bot is a great tool to help anyone willing to gain money. 🥂
        
        Warning !
        ~~~~~~~~~
        
        Check the code! I'm not an professional programmer and if I made many
        tests along this 2 years journey on building kola BitMEX bot I did not
        consistently use a test framework yet. THEREFORE there are obviously
        many improvements to be made.
        
        That been published, THIS CODE IS LICENCE FREE. No Gnu, no MIT, no
        GitHub©, no what so ever regulation from my part. Although, I may be
        obliged by some legal contracts I'm not consciously aware off because I
        did reused codes notably `BitMEX's API
        connectors <https://github.com/BitMEX/api-connectors>`__ and an
        uncountable number of functions from python's imported libraries
        (pandas, request, numpy, datetime…). I hope their authors don't really
        care. We are born free, let's stay so. So, your are free to do what you
        want with this code BUT… do check it and understand it.
        
        File Index
        ----------
        
        Core program files
        ~~~~~~~~~~~~~~~~~~
        
        ::
        
           kolaBitMEXBot
           ├── cancel_all.py  ->  cancel and close all order on testnet
           ├── kola
           │   ├── bargain.py  ->  handle connections to markets
           │   ├── chronos.py  ->  handle timeouts and thread of active orders
           │   ├── connexion
           │   │   ├── auth.py  ->  authentification to bitMEX
           │   │   ├── custom_ws_thread.py  ->  websocket API
           │   │   └── __init__.py
           │   ├── custom_bitmex.py
           │   ├── dummy_bitmex.py
           │   ├── __init__.py
           │   ├── orders
           │   │   ├── condition.py  ->  hold condition object to activate orders
           │   │   ├── hookorder.py  ->  orders that can hook to other orders
           │   │   ├── __init__.py
           │   │   ├── ordercond.py  ->  basic order with condition. other orders inherit it
           │   │   ├── orders.py  ->  functions to places limit, stop, limit if touched ...
           │   │   └── trailstop.py  ->  orders that follow price variation and update 
           │   ├── price.py  ->  object to follow the different prices indexes
           │   ├── settings.py  ->  setting files (where your keys may be)
           │   ├── secrets.py  ->  where API keys could be
           │   ├── types.py  ->  (new) types to start typing the programm
           │   └── utils
           │       ├── argfunc.py  ->  handle command line arguments
           │       ├── conditions.py  ->  function to set conditions
           │       ├── constantes.py  ->  constants
           │       ├── datefunc.py  ->  function to handle dates
           │       ├── exceptions.py  ->  customized exceptions
           │       ├── general.py  ->  generic utils
           │       ├── __init__.py
           │       ├── logfunc.py  ->  log function
           │       ├── orderfunc.py  ->  utils to set or check orders
           │       └── pricefunc.py  ->  utils to set or get prices
           ├── morders.tsv  ->  where you set your orders
           ├── multi_kola.py  ->  handle the (multiple runs) of one pair of orders 
           ├── pos_test.py  ->  (depreciated...)
           ├── run_multi_kola.py  ->  handle multiple pairs of orders (parse morders.tsv)
           └── tests
               └── utils.py
        
           5 directories, 33 files
        
        Setup and annexes program files
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        .python-version
           pyenv local python-version, should be >=3.8
        .dir-locals.el
           a versatile IDE config file (emacs :))
        .gitignore
           files that git should ignore
        setup.cfg
           config file for flake, mypy
        LICENSE.txt
           a permissive license
        README.rst
           this README
        requirements.txt
           set of required modules
        setup.py
           package file for python
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
Classifier: Natural Language :: French
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Utilities
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.8
Description-Content-Type: text/x-rst
