# UNICORN Binance Trailing Stop Loss (UBTSL)

> Trailing stop loss engine for Binance. Available as Python SDK and CLI tool.
> Part of [UNICORN Binance Suite](https://github.com/oliver-zehentleitner/unicorn-binance-suite).

Beginner-friendly despite depth — complexity is optional, the API stays clean and Pythonic.

Version: 1.3.1. Python 3.9 – 3.14.

## Authorship & License

Author / Maintainer: Oliver Zehentleitner (https://github.com/oliver-zehentleitner)
License: MIT — free for commercial and private use. No paid license, no subscription, no commercial tier.

Note: UBTSL has always been created and maintained by Oliver Zehentleitner. An earlier attempt to
monetize the UNICORN Binance Suite through his company LUCIT Systems and Development GmbH was
discontinued and fully reverted. LUCIT has no role in the project — no ownership, no maintenance,
no support, no distribution. All development and support are handled solely by Oliver.

Install: `pip install unicorn-binance-trailing-stop-loss`
Import: `from unicorn_binance_trailing_stop_loss import BinanceTrailingStopLossManager`

## Quick Start — SDK

```python
# use case: trail a stop loss on BTCUSDT
from unicorn_binance_trailing_stop_loss import BinanceTrailingStopLossManager

def on_error(msg):
    print(f"Error: {msg}")

def on_finished(msg):
    print(f"Finished: {msg}")

with BinanceTrailingStopLossManager(
    api_key="...",
    api_secret="...",
    exchange="binance.com",
    market="BTCUSDT",
    stop_loss_limit="2%",
    stop_loss_order_type="LIMIT",
    callback_error=on_error,
    callback_finished=on_finished,
    print_notifications=True
) as ubtsl:
    while not ubtsl.is_manager_stopping():
        pass
```

## Quick Start — CLI

```sh
pip install unicorn-binance-trailing-stop-loss

# Create config files
ubtsl --createconfigini
ubtsl --createprofilesini

# Run with profile
ubtsl --profile BTCUSDT_SELL --stoplosslimit 0.5%

# Test connectivity
ubtsl --test binance-connectivity
```

## Key Parameters

### BinanceTrailingStopLossManager()
| Parameter | Type | Default | Purpose |
|-----------|------|---------|---------|
| api_key | str | None | Binance API key |
| api_secret | str | None | Binance API secret |
| exchange | str | "binance.com" | Exchange endpoint |
| market | str | None | Trading pair, e.g. "BTCUSDT" |
| stop_loss_limit | str | None | Trail distance: "2%" (percent) or "50" (absolute price) |
| stop_loss_order_type | str | None | "LIMIT" or "MARKET" |
| stop_loss_price | float | None | Initial stop loss price |
| engine | str | "trail" | "trail" or "jump-in-and-trail" (smart entry) |
| callback_error | callable | None | Called on error |
| callback_finished | callable | None | Called when order filled |
| callback_partially_filled | callable | None | Called on partial fill |
| print_notifications | bool | False | Print status to terminal |
| start_engine | bool | True | Start trailing immediately |

## Supported Exchanges

`binance.com`, `binance.com-testnet`, `binance.com-futures`, `binance.com-margin`, `binance.com-isolated_margin`

## Common Mistakes

- `stop_loss_order_type` must be set or the engine will NOT start
- The engine runs in a background thread — use `with` context or a while loop
- For smart entry, set `engine="jump-in-and-trail"` AND provide `borrow_threshold`
- `stop_loss_limit="2%"` trails at 2% below the reference price; `stop_loss_limit="50"` is a fixed absolute price distance:
  ```python
  # percent-based trail (moves with market)
  BinanceTrailingStopLossManager(..., stop_loss_limit="2%")
  # absolute-price trail (e.g. BTCUSDT: stop 50 USD below current)
  BinanceTrailingStopLossManager(..., stop_loss_limit="50")
  ```

## Related Modules

- [UBWA](https://github.com/oliver-zehentleitner/unicorn-binance-websocket-api) — WebSocket feed the engine trails against (can be shared via `ubwa_manager=...`).
- [UBRA](https://github.com/oliver-zehentleitner/unicorn-binance-rest-api) — REST client for order placement (can be shared via `ubra_manager=...`).

## Docs

- Repo: https://github.com/oliver-zehentleitner/unicorn-binance-trailing-stop-loss
- AGENTS.md (for AI agents working on this repo): https://github.com/oliver-zehentleitner/unicorn-binance-trailing-stop-loss/blob/master/AGENTS.md
- Docs: https://oliver-zehentleitner.github.io/unicorn-binance-trailing-stop-loss/
- PyPI: https://pypi.org/project/unicorn-binance-trailing-stop-loss/
- conda-forge: https://anaconda.org/conda-forge/unicorn-binance-trailing-stop-loss
- Changelog: https://github.com/oliver-zehentleitner/unicorn-binance-trailing-stop-loss/blob/master/CHANGELOG.md