From a5dfce54efcbc873a2cbeb41dd316d940c7757aa Mon Sep 17 00:00:00 2001 From: Mart van de Ven Date: Wed, 12 Apr 2023 01:33:20 +0800 Subject: [PATCH 1/4] Correct minor typos --- CHANGELOG.md | 2 +- bot/README.md | 5 ++--- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d4eafb2..62df9a0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p ## 0.8.0.dev (development stage/unreleased/unstable) ### Added -- Additional infos for a better user experience +- Additional info for a better user experience ## 0.8.0 ### Added diff --git a/bot/README.md b/bot/README.md index 1053d68..5a18204 100644 --- a/bot/README.md +++ b/bot/README.md @@ -73,7 +73,7 @@ from GitHub. 8. Read the following [post installation instructions](https://www.lucit.tech/ubtsl-cli.html#installation). ### Mac -Comming soon! Receive a +Coming soon! Receive a [notification](https://www.lucit.tech/unicorn-binance-trailing-stop-loss-bot.html#receive-notifications) on release. ## Update @@ -85,8 +85,7 @@ $ ubtsl --installupdate ``` ### Mac -Comming soon! Receive a -[notification](https://www.lucit.tech/unicorn-binance-trailing-stop-loss-bot.html#receive-notifications) on release. +Coming soon! Receive a [notification](https://www.lucit.tech/unicorn-binance-trailing-stop-loss-bot.html#receive-notifications) on release. ## Change Log [https://unicorn-binance-trailing-stop-loss.docs.lucit.tech/CHANGELOG.html](https://unicorn-binance-trailing-stop-loss.docs.lucit.tech/CHANGELOG.html) From d3a9e81f2a77eab4b91d972d128429bfb4937b25 Mon Sep 17 00:00:00 2001 From: Mart van de Ven Date: Wed, 12 Apr 2023 01:36:49 +0800 Subject: [PATCH 2/4] Add language reference to markdown code blocks Adds syntax highlighting and interactive markdown features where available. --- README.md | 8 ++++---- bot/README.md | 2 +- cli/README.md | 42 +++++++++++++++++++++--------------------- 3 files changed, 26 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 88962f9..1dfea15 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ If you put this engine on a market, you should stop trading manually on this mar Part of ['UNICORN Binance Suite'](https://www.lucit.tech/unicorn-binance-suite.html). ## How to start the trailing stop loss engine: -``` +```python from unicorn_binance_trailing_stop_loss.manager import BinanceTrailingStopLossManager @@ -83,19 +83,19 @@ ubtsl = BinanceTrailingStopLossManager(callback_error=callback_error, ``` ### Stop the engine: -``` +```python ubtsl.stop_manager() ``` ### Get the right [logger](https://github.com/LUCIT-Systems-and-Development/unicorn-binance-trailing-stop-loss/blob/master/example_logging.py): -``` +```python logging.getLogger("unicorn_binance_trailing_stop_loss") ``` [Discover more possibilities](https://unicorn-binance-trailing-stop-loss.docs.lucit.tech/unicorn_binance_trailing_stop_loss.html). ## Start the engine on the command line (Windows, Linux and Mac): -``` +```sh $ ubtsl --profile BTCUSDT_SELL --stoplosslimit 0.5% ``` diff --git a/bot/README.md b/bot/README.md index 5a18204..6e6bb6c 100644 --- a/bot/README.md +++ b/bot/README.md @@ -80,7 +80,7 @@ Coming soon! Receive a ### Windows Just start `ubtsl` with the parameter `--installupdate`. Only available in the bot version! -``` +```sh $ ubtsl --installupdate ``` diff --git a/cli/README.md b/cli/README.md index a6b8803..69e1fa4 100644 --- a/cli/README.md +++ b/cli/README.md @@ -85,61 +85,61 @@ usability immensely. ### Create `ubtsl_config.ini` A fresh `ubtsl_config.ini` file can be created with the following command -``` +```sh $ ubtsl --createconfigini ``` ### Create `ubtsl_profiles.ini` The same command is available for the `ubtsl_profiles.ini` file: -``` +```sh $ ubtsl --createprofilesini ``` ### Open `ubtsl_config.ini` Open the used `ubtsl_config.ini` file in a GUI editor: -``` +```sh $ ubtsl --openconfigini ``` ### Open `ubtsl_profiles.ini` The same command is available for the `ubtsl_profiles.ini` file: -``` +```sh $ ubtsl --openprofilesini ``` ### Test the notification settings If you entered valid email and/or Telegram settings you can test the notification system: -``` +```sh $ ubtsl --test notification ``` ### Test connectivity to Binance API If you entered valid API key and secret you can test the connectivity to the Binance API: -``` +```sh $ ubtsl --test binance-connectivity ``` ### Test data streams Test the data streams, this test needs a defined exchange and market parameter: -``` +```sh $ ubtsl --test streams --exchange binance.com --market BTCUSDT ``` It is possible to use `exchange` and `market` values of a profile. -``` +```sh $ ubtsl --profile "BTCUSDT_SELL" --test streams ``` ## Usage -``` +```sh $ ubtsl --help ``` @@ -147,13 +147,13 @@ Alternatively, it is possible to run `ubtsl` in the Python environment as follow Linux/Mac: -``` +```sh $ python3 -m ubtsl --help ``` Windows: -``` +```sh $ py -m ubtsl --help ``` @@ -161,7 +161,7 @@ $ py -m ubtsl --help If profiles are available, they can be activated with the `--profile` parameter at startup. -``` +```sh $ ubtsl --profile BTCUSDT_SELL ``` @@ -173,7 +173,7 @@ Any CLI parameters will overwrite predefined values from the profile. All parameters that expect numbers can be configured with fixed numerical values as well as with percentage values. -``` +```sh $ ubtsl --help usage: ubtsl [-h] [-ak APIKEY] [-as APISECRET] [-bt BORROWTHRESHOLD] [-coo] [-cci] [-cpi] [-cf CONFIGFILE] [-cu] [-ex EXAMPLE] [-e EXCHANGE] [-n ENGINE] [-k KEEPTHRESHOLD] [-lf LOGFILE] [-ll LOGLEVEL] [-loo] @@ -249,12 +249,12 @@ options: ## Example commands ### Check if a new update is available -``` +```sh $ ubtsl --checkupdate ``` ### Show program version -``` +```sh $ ubtsl --version ``` @@ -263,7 +263,7 @@ Arguments defined in the CLI overrule values from the loaded profile! Start with profile "BTCUSDT_SELL" and overwrite the stoplosslimit: -``` +```sh $ ubtsl --profile BTCUSDT_SELL --stoplosslimit 0.5% ``` @@ -276,32 +276,32 @@ of the [example_ubtsl_profiles.ini](https://github.com/LUCIT-Systems-and-Develop By activating the `jump-in-and-trail` engine, the bot first buys the predefined asset amount and then trails them automatically. -``` +```sh $ ubtsl --profile BTCUSDT_SMART_ENTRY ``` ### List all open orders Get a list of all open orders. -``` +```sh $ ubtsl --exchange "binance.com" --market "BTCUSDT" --listopenorders ``` It is possible to use `exchange` and `market` values of a profile. -``` +```sh $ ubtsl --profile "BTCUSDT_SELL" --listopenorders ``` ### Cancel all open orders -``` +```sh $ ubtsl --exchange "binance.com" --market "BTCUSDT" --cancelopenorders ``` It's possible to use `exchange` and `market` values of a profile. -``` +```sh $ ubtsl --profile "BTCUSDT_SELL" --listopenorders ``` From d379cf983228570fa22903507828c3f2aa64c297 Mon Sep 17 00:00:00 2001 From: Mart van de Ven Date: Tue, 18 Apr 2023 02:26:50 +0800 Subject: [PATCH 3/4] Correct typos in code comments --- unicorn_binance_trailing_stop_loss/cli.py | 2 +- unicorn_binance_trailing_stop_loss/manager.py | 13 +++++++------ 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/unicorn_binance_trailing_stop_loss/cli.py b/unicorn_binance_trailing_stop_loss/cli.py index 1eed373..1bf4119 100755 --- a/unicorn_binance_trailing_stop_loss/cli.py +++ b/unicorn_binance_trailing_stop_loss/cli.py @@ -113,7 +113,7 @@ def main(is_bot=False): parser.add_argument('-ak', '--apikey', type=str, - help="the API key", + help="The API key", required=False) parser.add_argument('-as', '--apisecret', type=str, diff --git a/unicorn_binance_trailing_stop_loss/manager.py b/unicorn_binance_trailing_stop_loss/manager.py index 8b5e11e..21096c4 100644 --- a/unicorn_binance_trailing_stop_loss/manager.py +++ b/unicorn_binance_trailing_stop_loss/manager.py @@ -235,8 +235,9 @@ def __init__(self, exchange=self.exchange, warn_on_update=warn_on_update) if warn_on_update and self.is_update_available(): - update_msg = f"Release {self.name}_" + f"{self.get_latest_version()}" + " is available, " \ - "please consider updating! (Changelog: https://unicorn-binance-trailing-stop-loss.docs.lucit.tech/CHANGELOG.html)" + update_msg = f"Release {self.name}_{self.get_latest_version()} is available," + "please consider updating! (Changelog: " + "https://unicorn-binance-trailing-stop-loss.docs.lucit.tech/CHANGELOG.html)" print(update_msg) self.logger.warning(update_msg) try: @@ -262,7 +263,7 @@ def __init__(self, self.logger.info(msg) if self.print_notifications: print(msg) - notification_text = f"Subject: unicorn-binance-trailing-stop-loss notificaton test\n\nTest notification" + notification_text = f"Subject: unicorn-binance-trailing-stop-loss notification test\n\nTest notification" if self.send_email_notification(notification_text): msg = f"E-Mail sent, please check for incoming messages!" self.logger.info(msg) @@ -541,7 +542,7 @@ def create_stop_loss_order(self, @staticmethod def get_latest_release_info(): """ - Get infos about the latest available release + Get info about the latest available release :return: dict or False """ try: @@ -595,7 +596,7 @@ def get_exchange_info(self) -> Union[dict, bool]: def get_open_orders(self, market: str = None) -> Optional[dict]: """ - Get the owning amount of the stop/loss asset. + Get the open orders on a given market. :return: dict or None """ @@ -829,7 +830,7 @@ def process_userdata_stream(self, self.logger.debug(f"BinanceTrailingStopLossManager.process_userdata_stream() - Received: {stream_data}") else: self.logger.debug(f"BinanceTrailingStopLossManager.process_userdata_stream() - " - f"Received unkown stream_data: {stream_data}") + f"Received unknown stream_data: {stream_data}") if self.print_notifications: print("Unknown, please report:", str(stream_data)) From 22f984af57dc3e9f7b49ea468fd701731d25a54d Mon Sep 17 00:00:00 2001 From: Mart van de Ven Date: Tue, 18 Apr 2023 02:42:11 +0800 Subject: [PATCH 4/4] Edit BinanceTrailingStopLossManager docstring for clarity --- unicorn_binance_trailing_stop_loss/manager.py | 148 +++++++++++------- 1 file changed, 91 insertions(+), 57 deletions(-) diff --git a/unicorn_binance_trailing_stop_loss/manager.py b/unicorn_binance_trailing_stop_loss/manager.py index 21096c4..6b393f6 100644 --- a/unicorn_binance_trailing_stop_loss/manager.py +++ b/unicorn_binance_trailing_stop_loss/manager.py @@ -57,89 +57,123 @@ class BinanceTrailingStopLossManager(threading.Thread): """ - After starting the engine, a stop/loss order is placed and trailed until it is completely fulfilled. If desired, a - notification can be sent via email and Telegram afterwards. Then it calls the function passed with the - `callback_finished` parameter or on error it calls the function passed to `callback_error`. + Manage stop/loss orders on the Binance exchange. - Partially filled orders are currently not handled by the engine. If you want to react individually to this event, - you can use the function provided to `callback_partially_filled`. + Initialising the class spawns a new thread in which a stop/loss order is placed and trailed until it is + completely fulfilled. - In addition, there is a smart entry option called `jump-in-and-trail`. This offers the possibility to buy spot, - future and margin assets with a limit or market order and then to trail a stop/loss order until sold. + Optional support for: + - Telegram and Email notifications - see `send_*` and `telegram_*` parameters. + - Setting "success" and "error" callback functions - see `callback_finished` and `callback_error` parameters. + - Handling of partial fills - see `callback_partially_filled` parameter, note that partial fills are + currently not directly handled by the engine. + - Smart entry - by setting the `engine` param to `jump-in-and-trail`, it offers the possibility to buy + spot, future and margin assets with a limit or market order and then to trail a stop/loss order until sold. Supported exchanges: binance.com, binance.com-testnet, binance.com-futures, binance.com-margin, binance.com-isolated_margin - :param binance_public_key: Provide the public Binance key. + # Authentication parameters + + :param binance_public_key: Provide Binance API public key. :type binance_public_key: str - :param binance_private_key: Provide the private Binance key. + :param binance_private_key: Provide Binance API private key. :type binance_private_key: str - :param borrow_threshold: Provide the private Binance key. + + # Engine Control parameters + + :param engine: Activate standard trailing stop/loss with `trail` (default), or activate the experimental smart + entry method by setting `jump-in-and-trail` + :type engine: str + :param start_engine: Start the trailing stop loss engine. Default is True + :type start_engine: bool + :param test: Specify the subsystem to test. Supported options are : "notification", "binance-connectivity" + and "streams". The streams test needs a valid exchange and market. Note that this value MUST be None + or the engine will NOT start! Only tests will be performed. + :type test: str + + # Stop loss parameters + + :param stop_loss_order_type: Order type. Possible values are `limit` and `market`. If neither is + set, the algorithm will NOT run. + :type stop_loss_order_type: str + + :param stop_loss_price: Price at which the stop/loss order is submitted. Valid until it gets overwritten + by a higher price. + :type stop_loss_price: float + + :param stop_loss_limit: Stop loss limit in percent or as fixed float value + :type stop_loss_limit: str + + :param stop_loss_start_limit: The stop/loss order is trailed with the distance defined in `stop_loss_limit`. For + different initial parameters, you can use `stop_loss_start_limit`. This value will be + used instead of the `stop_loss_limit` value until this value is caught up and then + trailed. + :type stop_loss_start_limit: str + + :param stop_loss_trigger_gap: Gap between stop price and limit order price, use integer or percent + values. + :type stop_loss_trigger_gap: str + + :param reset_stop_loss_price: Reset an existing stop_loss_price and force a new one to be calculated. Only True + evaluates to True, anything else is False! + :type reset_stop_loss_price: bool + + :param keep_threshold: Percentage to keep when selling. Providing % symbol is optional , i.e. "1" is equal to + "1%". If empty, the full balance is sold. + :type keep_threshold: str + + :param borrow_threshold: TODO provide description :type borrow_threshold: str - :param callback_error: Callback function used if an error occurs. + + # Callback parameters + + :param callback_error: Callback to call if error occurs. :type callback_error: function or None - :param callback_finished: Callback function used if stop_loss gets filled. + :param callback_finished: Callback to call if stop_loss gets filled. :type callback_finished: function or None - :param callback_partially_filled: Callback function used if stop_loss gets partially filled filled. + :param callback_partially_filled: Callback to call if stop_loss is only partially filled. :type callback_partially_filled: function or None - :param engine: Option `trail` (default) for standard trailing stop/loss or `jump-in-and-trail` to activate smart - entry function. - :type engine: str - :param exchange: Choose the exchange endpoint: binance.com, binance.com-futures, binance.com-margin, + + # Exchange & Market parameters + + :param exchange: Exchange endpoint to connected to: binance.com, binance.com-futures, binance.com-margin, binance.com-isolated_margin :type exchange: str - :param keep_threshold: If empty we sell the full balance, use integer or percent values. - :type keep_threshold: str - :param market: The market to enforce stop/loss. + :param market: Market to enforce stop/loss on, e.g. "ETHBTC" :type market: str - :param print_notifications: If True the lib is printing user friendly information to terminal. - :type print_notifications: bool - :param reset_stop_loss_price: Reset an existing stop_loss_price and calculate a new one. Only True is True, anything - else is False! - :type reset_stop_loss_price: bool - :param send_to_email_address: Email address of receiver + :param trading_fee_use_bnb: Whether to use BNB for a discount on trading fees. Default is False. See: + https://www.binance.com/en/support/faq/115000583311 for details. + :type trading_fee_use_bnb: bool + + # Logging and Notification parameters + + :param current_price: Current market price. Used for logging purposes only, updated automatically from the stream. + :type current_price: float + :param print_notifications: Print user friendly information to terminal. + :param send_to_email_address: Receiver's email address :type send_to_email_address: str - :param send_from_email_address: Email address of sender + :param send_from_email_address: Sender's email address :type send_from_email_address: str - :param send_from_email_password: Password for SMTP auth + :param send_from_email_password: SMTP auth password :type send_from_email_password: str - :param send_from_email_server: Hostname or IP of SMTP server + :param send_from_email_server: SMTP server hostname or IP :type send_from_email_server: str - :param send_from_email_port: Port of SMTP server + :param send_from_email_port: SMTP server port :type send_from_email_port: int - :param start_engine: Start the trailing stop loss engine. Default is True - :type start_engine: bool - :param stop_loss_limit: The limit is used to calculate the `stop_loss_price` of the highest given price, use integer - or percent values. - :type stop_loss_limit: str - :param stop_loss_order_type: Can be `limit` or `market` - default is None which leads to a stop of the algorithm. - :type stop_loss_order_type: str - :param stop_loss_price: Set a price to use for stop/loss, this is valid till it get overwritten with a higher price. - :type stop_loss_price: float - :param stop_loss_start_limit: The trailing stop/loss order is trailed with the distance defined in - `stop_loss_limit`. If you want to use a different value at the start, you can specify - it with `stop_loss_start_limit`. This value will be used instead of the - `stop_loss_limit` value until this value is caught up and then trailed. - :type stop_loss_start_limit: str - :param stop_loss_trigger_gap: Gap between stopPrice and limit order price, use integer or percent values. - :type stop_loss_trigger_gap: str - :param test: Use this to test specific systems like "notification", "binance-connectivity" and "streams". The - streams test needs a valid exchange and market. If test is not None the engine will NOT start! It - only tests! - :type test: str - :param telegram_bot_token: Token to connect with Telegram API. + :param telegram_bot_token: Telegram API Token :type telegram_bot_token: str - :param telegram_send_to: Receiver of the message sent via Telegram. + :param telegram_send_to: Receiver's UserId (i.e. not username) on Telegram. :type telegram_send_to: str - :param trading_fee_use_bnb: Default is False. Set to True to use BNB for a discount on trading fees: - https://www.binance.com/en/support/faq/115000583311. - :type trading_fee_use_bnb: bool - :param warn_on_update: set to `False` to disable the update warning - :type warn_on_update: bool + + # Unicorn Binance Suite parameters + :param ubra_manager: Provide a shared unicorn_binance_rest_api.manager instance :type ubra_manager: BinanceRestApiManager :param ubwa_manager: Provide a shared unicorn_binance_websocket_api.manager instance. :type ubwa_manager: BinanceWebSocketApiManager + :param warn_on_update: Inform of availability of package updates. Disable with `False`. + :type warn_on_update: bool """ def __init__(self,