{"id":36444275,"url":"https://github.com/wferreirauy/binance-bot","last_synced_at":"2026-05-15T23:19:29.274Z","repository":{"id":263364193,"uuid":"803098723","full_name":"wferreirauy/binance-bot","owner":"wferreirauy","description":"A command-line tool for automated trading on Binance, built in Go. Features technical indicators (Bollinger Bands, DEMA, MACD, RSI, ADX, Volume) for trend analysis, and an AI-powered consensus engine that queries OpenAI, DeepSeek, and Claude in parallel to validate trading signals. Supports bull and bear strategies. TUI interface.","archived":false,"fork":false,"pushed_at":"2026-05-14T22:49:08.000Z","size":6069,"stargazers_count":9,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-15T00:32:03.471Z","etag":null,"topics":["automated","binance","bot","cryptocurrency","go","golang","trading","tranding-bot"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wferreirauy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2024-05-20T04:15:08.000Z","updated_at":"2026-05-14T22:49:12.000Z","dependencies_parsed_at":null,"dependency_job_id":"7cfd4109-5eca-445d-ae08-0967144ea5ef","html_url":"https://github.com/wferreirauy/binance-bot","commit_stats":null,"previous_names":["wferreirauy/binance-bot"],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/wferreirauy/binance-bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wferreirauy%2Fbinance-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wferreirauy%2Fbinance-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wferreirauy%2Fbinance-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wferreirauy%2Fbinance-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wferreirauy","download_url":"https://codeload.github.com/wferreirauy/binance-bot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wferreirauy%2Fbinance-bot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33083150,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-15T20:25:35.270Z","status":"ssl_error","status_checked_at":"2026-05-15T20:25:34.732Z","response_time":103,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automated","binance","bot","cryptocurrency","go","golang","trading","tranding-bot"],"created_at":"2026-01-11T22:02:51.041Z","updated_at":"2026-05-15T23:19:29.268Z","avatar_url":"https://github.com/wferreirauy.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Binance Trade Bot\n\n\u003cimg width=\"1343\" height=\"863\" alt=\"Image\" src=\"https://github.com/user-attachments/assets/10b5cd6f-c80e-4661-b963-9f5b52641330\" /\u003e\n\n\n## Features\n\n- **Auto Trade** — Automatically detects market tendency and switches between bull/bear strategies per operation; supports forced strategy mode to wait for a matching tendency\n- **Bull Trade** — Buy-low-sell-high strategy for uptrending markets\n- **Bear Trade** — Sell-high-buy-low strategy for downtrending markets\n- **Scalp Mode** — High-frequency micro-trading using a scoring-based entry system; no longer requires all signals simultaneously\n- **Top Gainers Monitor** — Real-time TUI dashboard of the top 24h movers on Binance\n- **Rotation Scout Mode** — Scans a configured asset basket and rotates through a bridge asset when relative ratios become fee-adjusted opportunities\n- **Backtesting** — Runs registered strategy simulations over recent Binance candles before live trading\n- **Managed Orders** — Optional buy/sell timeouts with partial-fill handling; unfilled entries return to scanning instead of advancing to exit monitoring\n- **Persistent History API** — Stores trade/scout history in JSONL and serves it through a small local HTTP API\n- **AI Multi-Agent System** — Concurrent analysis from OpenAI, DeepSeek, and Claude with weighted consensus; when enabled, entries require explicit AI approval at the configured confidence threshold\n- **Sentiment Analysis** — Real-time news headlines and Fear \u0026 Greed Index integrated into AI decisions\n- **Trailing Stop-Loss** — Dynamically locks in profits as price moves favorably\n- **Advanced Indicators** — RSI, MACD, DEMA, Bollinger Bands, ADX, ATR, and volume confirmation\n- **Full OHLCV Analysis** — Uses complete candlestick data instead of close-only prices\n- **Auto-Notional Adjustment** — Automatically raises order quantity to meet Binance's minimum notional filter\n- **Config Validation** — Checks the YAML config file before starting a trading session\n- **Detailed Order Reasoning** — Activity Log shows which entry/exit conditions were met (✓/✗) before each trade\n- **File Logging** — All trade events and errors are written to `binance-bot.log` alongside the TUI display\n- **Fee-Aware Targets** — Take-profit thresholds can be adjusted by live Binance taker fees plus a configurable safety buffer\n\n## Download\n\n#### **Download Precompiled Binary**\n\nYou can **download the precompiled binary** from the repository's release artifacts.\n\n1. Visit the [Releases](https://github.com/wferreirauy/binance-bot/releases) page of the repository.\n2. Download the appropriate binary for your operating system (e.g., Linux, macOS, Windows).\n3. Make the binary executable (if required):\n   - On Linux or macOS:\n     ```bash\n     chmod +x binance-bot\n     ```\n4. Move the binary to a directory in your `$PATH` for global access:\n   - On Linux\n   ```bash\n   sudo mv binance-bot /usr/local/bin/\n\n## Usage\n\n\u003e [!WARNING]\n\u003e This bot is provided as-is. Use it at your own risk. Trading involves financial risks, and you may incur significant losses. Always test in a safe environment (e.g., a testnet and/or with small amounts) before deploying in live markets. The author is not responsible for any financial outcomes.\n\n---\n\n### Prerequisites\n\nBefore using the Binance Trade Bot, you need to configure your environment with the Binance API client credentials. These credentials allow the bot to interact securely with your Binance account. Follow these steps to set up:\n\n1. **Obtain your Binance API Key and Secret**\n   - Log in to your [Binance account](https://www.binance.com/).\n   - Navigate to the [API Management section](https://www.binance.com/en/my/settings/api-management).\n   - Create a new API key, choosing HMAC type and providing any label (e.g., `CLI_Bot`).\n   - Save the **API Key** and **Secret Key** securely. You will not be able to view the secret again after closing the page.\n\n2. **Set Environment Variables**\n   Export the API credentials as environment variables in your terminal before executing the binance-bot cli:\n\n   ```bash\n   export BINANCE_API_KEY=\u003cyour-api-key\u003e\n   export BINANCE_SECRET_KEY=\u003cyour-secret-key\u003e\n   ```\n\n3. **Set AI Provider API Keys (optional)**\n   To enable the AI multi-agent system, export one or more of the following API keys. The system works with any combination — you can use 1, 2, or all 3 providers:\n\n   ```bash\n   export OPENAI_API_KEY=\u003cyour-openai-api-key\u003e\n   export DEEPSEEK_API_KEY=\u003cyour-deepseek-api-key\u003e\n   export ANTHROPIC_API_KEY=\u003cyour-anthropic-api-key\u003e\n   ```\n\n   | Variable | Provider | Default Model |\n   |----------|----------|---------------|\n   | `OPENAI_API_KEY` | OpenAI | `gpt-4o-mini` |\n   | `DEEPSEEK_API_KEY` | DeepSeek | `deepseek-chat` |\n   | `ANTHROPIC_API_KEY` | Claude | `claude-3-5-haiku-20241022` |\n\n   \u003e If no AI keys are set, the bot runs entirely on technical indicators — AI is fully optional.\n\n4. **Create a config file**\n   You can specify a custom configuration file to adjust the bot's parameters of trading indicators. \u003cbr /\u003e\n   See the [sample configuration file](/sample-binance-config.yml).\n\n#### Now you're ready to use the Binance Trade Bot! 🎉\n\n### Run the Bot\n\n#### Auto Trade (automatic tendency detection)\n\n```bash\nbinance-bot -f binance-config.yml auto-trade -t \"BTC/USDT\" -a 0.001 -sl 2.0 -tp 2.5 -b 0.9998 -s 1.0003 -rp 2 -ra 5\n```\n\nThis example:\n- Automatically detects whether `BTC/USDT` is trending up or down before each operation.\n- Enters **bull mode** (buy low, sell high) when tendency is \"up\", or **bear mode** (sell high, buy back low) when tendency is \"down\".\n- Re-detects tendency between every operation, adapting to changing market conditions.\n- If tendency flips during entry scanning, the bot dynamically switches mode without waiting.\n- The TUI header shows the currently active mode (BULL/BEAR) updated in real-time.\n\n#### Auto Trade with forced strategy\n\n```bash\nbinance-bot -f binance-config.yml auto-trade -t \"DOGE/USDT\" -a 100 -sl 2.0 -tp 2.5 -b 0.9998 -s 1.0003 -rp 6 -ra 0 --strategy bull\n```\n\nThis example:\n- Forces the bot to only enter **bull** (buy-first) operations — useful when your account only holds USDT.\n- The bot monitors the market and **waits** for an \"up\" tendency before placing any orders.\n- If tendency flips away during scanning, the bot returns to waiting instead of switching to bear.\n- Use `--strategy bear` to force sell-first operations (when you hold the base coin and want to sell first).\n- Use `--strategy auto` (default) for fully automatic tendency detection.\n\n#### Bull Trade (uptrending markets)\n\n```bash\nbinance-bot -f binance-config.yml bull-trade -t \"XRP/USDT\" -a 50 -sl 1.5 -tp 2.0 -b 0.9998 -s 1.0003 -rp 4 -ra 0\n```\n\nThis example:\n- Trades the pair `XRP/USDT` with an amount of `50`.\n- Sets a stop-loss of `1.5%` and a take-profit of `2%`.\n- Adjusts buy and sell factors for the LIMIT order target price.\n- Rounds the price to 4 decimals and the amount to 0 decimals.\n\n#### Bear Trade (downtrending markets)\n\n```bash\nbinance-bot -f binance-config.yml bear-trade -t \"BTC/USDT\" -a 0.001 -sl 2.0 -tp 3.0 -b 0.9998 -s 1.0003 -rp 2 -ra 5\n```\n\nThis example:\n- Sells `0.001 BTC` when bearish signals are detected.\n- Sets a stop-loss of `2%` (price rises above entry) and take-profit of `3%` (price drops below entry).\n- Buys back at a lower price to capture the difference as profit.\n\n#### Scalp Mode (high-frequency micro-trading)\n\n```bash\nbinance-bot -f sample-scalp-config.yml bull-trade -t \"PEPE/USDT\" -a 50 --sl 0.6 --tp 1.0 -b 0.9999 -s 1.0001 -rp 8 -ra 0 -o 500\n```\n\nThis example:\n- Uses 1-minute candles and a scoring-based entry (any 3 of 6 signals bullish).\n- Sets tight stop-loss / take-profit suitable for volatile low-cap tokens.\n- Runs up to 500 operations with only 10s between completed operations.\n- See [sample-scalp-config.yml](/sample-scalp-config.yml) for the full config.\n\n#### Top Gainers Monitor\n\n```bash\nbinance-bot -f binance-config.yml top-gainers\n```\n\nLaunches a real-time TUI listing the top 24h price-change gainers on Binance, filtered by quote asset, minimum volume, and an exclude list. Refreshes on the configured `poll-interval`. Press `q` to quit.\n\n#### Rotation Scout Mode\n\n```bash\nbinance-bot -f binance-config.yml rotate-trade\n```\n\nScans the configured `rotation.supported-assets` basket against `rotation.bridge-asset` and records every scout comparison to `.binance-bot/scouts.jsonl`. When a relative-ratio opportunity beats fee-adjusted thresholds, the bot rotates from the current asset into the selected asset through the bridge. The sample config runs this mode as `dry-run: true`; switch it off only after validating behavior with small balances.\n\n#### Backtest\n\n```bash\nbinance-bot -f binance-config.yml backtest -t \"BTC/USDT\" --strategy classic-bull\n```\n\nRuns a registered strategy over recent Binance candles using the configured indicators, starting balance, and fee assumptions. Available strategies are `classic-bull` and `scalp-bull`.\n\n#### History API\n\n```bash\nbinance-bot -f binance-config.yml serve\n```\n\nStarts a local HTTP server using `api.address`. Endpoints include `/api/health`, `/api/trades`, `/api/scouts`, `/api/values`, and `/api/current-asset`. Use `?limit=100` on history endpoints to read only the most recent records.\n\n#### Validate Configuration\n\n```bash\nbinance-bot -f binance-config.yml validate-config\n```\n\nReads the YAML configuration, validates required ranges and enum-like values, and exits without starting a trading session. Valid configs print `Config OK`; invalid configs print every issue found so you can fix them in one pass.\n\nModify these parameters based on your specific trading requirements.\n\n---\n\n#### Explanation of Command Arguments\n\nThese arguments apply to the `auto-trade`, `bull-trade`, and `bear-trade` commands:\n\n| Option               | Short | Description                                                                                 | Default       |\n|----------------------|-------|---------------------------------------------------------------------------------------------|---------------|\n| `--ticker`           | `-t`  | The trading pair ticker in the format `ABC/USD` (e.g., `BTC/USDT`).                         | **Required**  |\n| `--amount`           | `-a`  | Amount to trade.                                                                            | **Required**  |\n| `--stop-loss`        | `-sl` | Stop-loss percentage (e.g., `1.5` for 1.5%).                                                | `3`           |\n| `--take-profit`      | `-tp` | Take-profit percentage (e.g., `3.0` for 3%).                                                | `2.5`         |\n| `--buy-factor`       | `-b`  | Factor to determine the target price for a LIMIT buy order.                                 | `0.9999`      |\n| `--sell-factor`      | `-s`  | Factor to determine the target price for a LIMIT sell order.                                | `1.0001`      |\n| `--round-price`      | `-rp` | Decimal precision for rounding price values.                                                | **Required**  |\n| `--round-amount`     | `-ra` | Decimal precision for rounding amount values.                                               | **Required**  |\n| `--operations`       | `-o`  | Number of operations to execute during the trading session.                                 | `100`         |\n| `--strategy`         | `-st` | *(auto-trade only)* Force entry strategy: `bull`, `bear`, or `auto`.                       | `auto`        |\n| `--help`             | `-h`  | Show help for the command.                                                                  | -             |\n\n### Help Commands\n\n- For general help on the bot:\n  ```bash\n  binance-bot --help\n  ```\n\n  Output:\n  ```\n  NAME:\n     binance-bot - A program bot to trade in Binance\n\n  USAGE:\n     binance-bot [global options] command \u003ccommand args\u003e\n\n  VERSION:\n     v0.10.1\n\n  AUTHOR:\n     Walter Ferreira \u003cwferreirauy@gmail.com\u003e\n\n  COMMANDS:\n     bull-trade, bt    Start a bull trade run\n     bear-trade, brt   Start a bear trade run (sell high, buy back low)\n     auto-trade, at    Automatically detect market tendency and trade accordingly (bull or bear)\n     top-gainers, tg   Monitor top market gainers in real-time\n     rotate-trade, rt  Scout a basket of assets and rotate through the configured bridge asset\n     backtest, btst    Backtest a registered strategy on recent Binance candles\n     serve, srv        Serve persisted trade, scout, and value history over HTTP\n     validate-config, vc  Validate the configured YAML file without starting a trading session\n     help, h           Shows a list of commands or help for one command\n\n  GLOBAL OPTIONS:\n     --config-file FILE, -f FILE  Load configuration from FILE (default: $HOME/binance-config.yml)\n     --help, -h     show help\n     --version, -v  print the version\n  ```\n\n- For help with the `bull-trade` command:\n  ```bash\n  binance-bot bull-trade --help\n  ```\n\n- For help with the `bear-trade` command:\n  ```bash\n  binance-bot bear-trade --help\n  ```\n\n- For help with the `auto-trade` command:\n  ```bash\n  binance-bot auto-trade --help\n  ```\n\n- For help with the `top-gainers` command:\n  ```bash\n  binance-bot top-gainers --help\n  ```\n\n- For help with the `validate-config` command:\n  ```bash\n  binance-bot validate-config --help\n  ```\n\n### TUI Keyboard Shortcuts\n\nWhile the bot is running, the following keys are available inside the TUI:\n\n| Key | Action |\n|-----|--------|\n| `q` / `Ctrl+C` | Quit the application |\n| `h` | Toggle the help / keyboard shortcuts popup |\n| `c` | Show loaded configuration popup |\n| `Esc` | Close any open popup |\n\n---\n\n## Configuration\n\nThe bot is configured through a YAML file. See [sample-binance-config.yml](/sample-binance-config.yml) for a complete example.\n\n### Base URL Configuration\n\nYou can override the Binance API base URL to use alternative endpoints such as the testnet:\n\n```yaml\nbase-url: \"https://testnet.binance.vision\"\n```\n\nIf omitted or empty, the default `https://api1.binance.com` (production) is used.\n\n| Environment | URL |\n|-------------|-----|\n| Production (default) | `https://api1.binance.com` |\n| Testnet | `https://testnet.binance.vision` |\n\n### Config Validation\n\nRun `validate-config` before trading to catch malformed or risky configuration values:\n\n```bash\nbinance-bot -f binance-config.yml validate-config\n```\n\nThe command checks fields such as Binance candle intervals, RSI limit ordering, MACD length ordering, confidence ranges, positive refresh and polling intervals, and top-gainers settings. It reports all validation failures at once and does not call Binance or any AI provider.\n\n### Persistence, Fees, and Orders\n\n```yaml\ndata-dir: \".binance-bot\"\n\norder-management:\n  buy-timeout-minutes: 20\n  sell-timeout-minutes: 20\n  partial-fill-action: \"keep\"\n  poll-interval-secs: 5\n\nfees:\n  enabled: true\n  default-taker-pct: 0.1\n  buffer-pct: 0.05\n```\n\nThe bot writes trade/scout history to `data-dir`. Managed order timeouts cancel stale limit orders; `partial-fill-action: \"reverse\"` attempts a market order in the opposite direction for partial timeout fills. Fee-aware mode subtracts estimated round-trip taker fees and `buffer-pct` from take-profit decisions.\n\n### Indicators Configuration\n\n```yaml\nhistorical-prices:\n  period: 100           # number of candlesticks to fetch\n  interval: \"1m\"        # candlestick interval (1m, 3m, 5m, 15m, 1h, etc.)\n\ntendency:\n  interval: \"3m\"        # interval for tendency calculation\n  direction: \"up\"       # expected direction for bull-trade\n\nindicators:\n  rsi:\n    interval: \"5m\"\n    length: 14\n    upper-limit: 70     # overbought threshold\n    middle-limit: 50\n    lower-limit: 30     # oversold threshold\n  dema:\n    length: 9\n  macd:\n    fast-length: 12\n    slow-length: 26\n    signal-length: 9\n  bollinger-bands:\n    length: 20\n    multiplier: 2.0\n  atr:\n    period: 14          # Average True Range for volatility\n  adx:\n    period: 14\n    threshold: 25       # minimum ADX value to confirm trend strength\n  volume:\n    ma-period: 20       # volume moving average period\n```\n\n### Trailing Stop Configuration\n\nThe trailing stop-loss dynamically adjusts to lock in profits as the price moves favorably:\n\n```yaml\ntrailing-stop:\n  enabled: true\n  activation-pct: 1.5  # activate after price moves 1.5% in your favor\n  trailing-pct: 1.0    # trail by 1.0% from the peak/trough\n```\n\n- For **bull trades**: once the price rises by `activation-pct` above buy price, the stop tracks from the highest price and triggers if the price drops `trailing-pct` from that peak.\n- For **bear trades**: once the price drops by `activation-pct` below sell price, the stop tracks from the lowest price and triggers if the price rises `trailing-pct` from that trough.\n\n### Scalp Mode Configuration\n\nScalp mode is optimized for **high-frequency micro-trading** on volatile tickers. Instead of requiring all 6 entry signals simultaneously, it scores each signal and enters when `min-score` are bullish.\n\n```yaml\nscalp-mode:\n  enabled: true\n  min-score: 3           # minimum bullish signals out of 6 to trigger entry\n  post-buy-delay: 5      # seconds to wait after fill before exit monitoring\n  inter-op-delay: 10     # seconds to wait between completed operations\n  require-rsi-exit: false # require RSI momentum confirmation before take-profit\n```\n\n**Scoring signals (6 total):**\n\n| # | Signal | Bullish condition |\n|---|--------|-------------------|\n| 1 | RSI | Below upper limit |\n| 2 | MACD | MACD line above signal line |\n| 3 | Tendency | Matches configured direction |\n| 4 | Bollinger | DEMA closer to lower band than upper band |\n| 5 | ADX | Above configured threshold |\n| 6 | Volume | Current volume above its moving average |\n\nWith `min-score: 3` the bot enters if any 3 of 6 signals are bullish. Raise to `4` or `5` for more selective, lower-frequency entries.\n\n\u003e See [sample-scalp-config.yml](/sample-scalp-config.yml) for a complete high-frequency configuration tuned for 1-minute candles.\n\n**Recommended stop-loss / take-profit for scalping (after 0.2% round-trip fees):**\n\n| Scenario | `--sl` | `--tp` | Net gain/loss |\n|----------|--------|--------|---------------|\n| Ultra-tight | `0.4` | `0.7` | +0.5% / -0.4% |\n| Balanced ✓ | `0.6` | `1.0` | +0.8% / -0.6% |\n| Conservative | `1.0` | `1.8` | +1.6% / -1.0% |\n\n### Top Gainers Configuration\n\n```yaml\ntop-gainers:\n  quote-asset: \"USDT\"      # filter pairs ending with this asset\n  limit: 20                # number of top gainers to display\n  poll-interval: 60        # seconds between each refresh\n  min-volume: 1000000      # minimum 24h quote volume to include\n  exclude-symbols:         # symbols to always exclude\n    - \"USDCUSDT\"\n```\n\n### Rotation, Backtest, and API Configuration\n\n```yaml\nrotation:\n  bridge-asset: \"USDT\"\n  current-asset: \"BTC\"\n  supported-assets: [\"BTC\", \"ETH\", \"SOL\", \"XRP\", \"DOGE\"]\n  scout-multiplier: 5\n  scout-margin-pct: 0.8\n  use-margin: false\n  scout-sleep-seconds: 5\n  dry-run: true\n  max-jumps: 0\n  min-notional-buffer: 1.01\n\nbacktest:\n  initial-balance: 1000\n  fee-pct: 0.1\n\napi:\n  address: \"127.0.0.1:8080\"\n```\n\nRotation mode persists its current asset in `data-dir/current_asset.json`. Backtests use recent Binance candles and append simulated trade records. The API server exposes persisted JSONL history from the configured address.\n\n### AI Configuration\n\nThe AI multi-agent system is optional. When enabled, it queries multiple LLM providers concurrently with technical indicators and market sentiment data to produce a consensus trading signal.\n\n```yaml\nai:\n  enabled: true\n  providers:\n    openai:\n      model: \"gpt-4o-mini\"\n    deepseek:\n      model: \"deepseek-chat\"\n    claude:\n      model: \"claude-3-5-haiku-20241022\"\n  min-confidence: 0.5   # minimum consensus confidence to act (0.0 - 1.0)\n```\n\n**How it works:**\n1. Each configured provider receives a structured prompt with all technical indicators plus real-time sentiment data.\n2. Providers are queried **concurrently** for speed.\n3. Each agent returns a signal (`BUY`, `SELL`, or `HOLD`), a confidence score (0.0-1.0), and reasoning.\n4. A **weighted consensus** algorithm aggregates all votes to produce a final decision.\n5. The AI must approve (or at least not contradict) technical signals before trades are executed.\n\n**Sentiment sources (free, no API key required):**\n- **CryptoCompare** — latest news headlines for the traded coin\n- **Alternative.me Fear \u0026 Greed Index** — overall crypto market mood\n\n\u003e Set `ai.enabled: false` or omit all provider API keys to disable AI and run on technical indicators only. This is recommended for low-latency scalp configurations unless you intentionally want slower AI-gated entries.\n\n### File Logging\n\nAll log levels (orders, info, errors) are automatically written to `binance-bot.log` in the working directory, alongside the TUI display. Color tags are stripped before writing. The file is opened in append mode so logs accumulate across sessions.\n\n```\n2026-04-07 12:30:00 [INFO]  Scalp entry: score 5/6 (min 5)\n2026-04-07 12:30:00 [INFO]    ✓ RSI 28.4 \u003c 30 (upper limit)\n2026-04-07 12:30:00 [INFO]    ✓ MACD above signal (0.000012 \u003e 0.000008)\n2026-04-07 12:30:00 [INFO]    ✓ Tendency up = up\n2026-04-07 12:30:00 [INFO]    ✓ Closer to lower BB (lower=0.0023, upper=0.0089)\n2026-04-07 12:30:00 [INFO]    ✓ ADX strong (32.1 \u003e 20)\n2026-04-07 12:30:00 [INFO]    ✗ Volume confirmed (4200 \u003e avg 5100)\n2026-04-07 12:30:01 [ORDER] BUY 50.000000 PEPE @ 0.00001234 USDT = 0.000617 USDT\n2026-04-07 12:30:05 [INFO]  BUY order filled!\n2026-04-07 12:35:10 [INFO]  Take-profit triggered: price 0.00001250 \u003e= TP 0.00001246 (buy 0.00001234, TP 1.00%, P\u0026L +1.30%)\n2026-04-07 12:35:10 [INFO]    ✓ RSI exit ok (RSI declining=true, scalp bypass=false)\n```\n\n### Auto-Notional Adjustment\n\nBinance enforces a minimum notional value (`price × quantity`) per symbol — typically 5 USDT. If the configured `--amount` would produce a notional below this threshold (common with very cheap tokens like PEPE or SHIB), the bot automatically raises the quantity to meet the exchange's `NOTIONAL` and `LOT_SIZE` filters before placing the order. A message is logged when an adjustment occurs:\n\n```\nBUY qty adjusted from 50.00000000 to 405210.00000000 to meet exchange filters (minNotional=5.00)\n```\n\nNo manual intervention is required — the adjustment is transparent and logged.\n\n---\n\n## Trading Strategy Logic\n\n### Bull-Trade\n\nThe `bull-trade` command is designed to operate during **bull market trends**, leveraging upward momentum to execute profitable trades.\n\n#### **Buy Conditions**\n\nIn **classic mode**, the bot places a buy order when **all** of the following conditions are true simultaneously. In **scalp mode**, the conditions are scored and entry triggers when `min-score` out of 6 are bullish (see [Scalp Mode Configuration](#scalp-mode-configuration)).\n\n1. **RSI**: Value is below the configured `upper-limit` (default 70), indicating the market is not overbought.\n2. **MACD Crossover**: The MACD line crosses above the Signal line (classic) or is above the Signal line (scalp), suggesting upward momentum.\n3. **Tendency Confirmation**: The trend direction matches the configured direction (DEMA above EMA = \"up\").\n4. **DEMA Proximity to Bollinger Bands**: The current DEMA is closer to the Lower Band than the Upper Band, suggesting a potential reversal from oversold conditions.\n5. **ADX Trend Strength** *(if configured)*: ADX is above the threshold (default 25), confirming a strong trend.\n6. **Volume Confirmation** *(if configured)*: Current volume exceeds its moving average, avoiding false breakouts.\n7. **AI Consensus** *(if enabled)*: The multi-agent system must explicitly approve the entry at or above `ai.min-confidence`.\n\n#### **Sell Conditions**\nThe bot will exit a position through one of three mechanisms:\n\n1. **Trailing Stop-Loss** *(if enabled)*: After the price rises by `activation-pct` above buy price, the stop trails from the highest price. Triggers when price drops by `trailing-pct` from the peak.\n2. **Fixed Stop-Loss**: The price drops to the stop-loss percentage below buy price. Executes immediately (no AI delay on protective exits).\n3. **Take Profit**: The price reaches the take-profit percentage AND RSI is declining (skipped in scalp mode when `require-rsi-exit: false`) AND the AI supports the exit (if enabled).\n\n---\n\n### Bear-Trade\n\nThe `bear-trade` command is designed to operate during **bear market trends**, profiting from downward price movement by selling high and buying back low.\n\n#### **Sell Entry Conditions**\n\nIn **classic mode**, all conditions must be met simultaneously. In **scalp mode**, `min-score` out of 6 signals must be bearish.\n\nThe bot will open a short position (sell) when:\n\n1. **RSI**: Value is above the configured `lower-limit` (default 30), indicating the market is not oversold.\n2. **MACD Crossover**: The MACD line crosses below the Signal line, suggesting downward momentum.\n3. **Tendency**: The trend direction is \"down\" (DEMA below EMA).\n4. **DEMA Proximity to Bollinger Bands**: The current DEMA is closer to the Upper Band than the Lower Band, suggesting a potential reversal from overbought conditions.\n5. **ADX Trend Strength** *(if configured)*: ADX confirms the trend has strength.\n6. **Volume Confirmation** *(if configured)*: Current volume exceeds its moving average.\n7. **AI Consensus** *(if enabled)*: The multi-agent system must explicitly approve the entry at or above `ai.min-confidence`.\n\n#### **Buy-Back Exit Conditions**\nThe bot will exit the bear position (buy back) through one of three mechanisms:\n\n1. **Trailing Stop** *(if enabled)*: After the price drops by `activation-pct` below sell price, the stop trails from the lowest price. Triggers when price rises by `trailing-pct` from the trough.\n2. **Fixed Stop-Loss**: The price rises to the stop-loss percentage above sell price. Executes immediately.\n3. **Take Profit**: The price drops to the take-profit percentage AND RSI is rising (skipped in scalp mode when `require-rsi-exit: false`) AND the AI supports the exit (if enabled).\n\n---\n\n### Auto-Trade (Dynamic Tendency Detection)\n\nThe `auto-trade` command removes the need to manually choose between bull and bear strategies. Before each operation, the bot evaluates the current market tendency using the same DEMA-vs-EMA analysis used by the individual modes.\n\n#### **How It Works**\n\n1. **Strategy Selection**: The `--strategy` flag determines behavior:\n   - `auto` (default): Detects tendency automatically and trades in whichever direction the market is trending.\n   - `bull`: Forces buy-first operations — the bot waits until tendency is \"up\" before entering. Ideal when you only hold the quote asset (e.g., USDT).\n   - `bear`: Forces sell-first operations — the bot waits until tendency is \"down\" before entering. Ideal when you hold the base asset and want to sell first.\n2. **Tendency Detection**: At the start of each operation, the bot fetches historical prices on the configured `tendency.interval` and compares DEMA to EMA. If DEMA \u003e EMA the tendency is \"up\" (bull); otherwise \"down\" (bear).\n3. **Waiting for Match**: When a strategy is forced (`bull` or `bear`), the bot continuously monitors tendency and only proceeds when it matches the required direction. The TUI shows the mode with \"(waiting)\" until tendency aligns.\n4. **Mode Selection**: Based on the detected/matched tendency, the bot switches to the appropriate strategy — bull (buy low, sell high) or bear (sell high, buy back low).\n5. **Live Re-detection**: During entry scanning in `auto` mode, if the tendency flips, the bot immediately adapts and switches to the opposite mode. In forced strategy mode, a tendency flip causes the bot to return to waiting.\n6. **Entry \u0026 Exit**: Once a mode is selected, the exact same entry conditions (classic or scalp scoring) and exit mechanisms (trailing stop, stop-loss, take-profit, AI confirmation) apply as in the standalone `bull-trade` or `bear-trade` commands.\n7. **Per-Operation Adaptation**: After each completed operation (entry + exit), the bot re-detects tendency before the next one.\n\n#### **TUI Display**\n\nThe TUI header dynamically shows the current mode:\n- `BULL (waiting)` or `BEAR (waiting)` when a forced strategy is waiting for matching tendency\n- `AUTO MODE` in cyan at startup (when strategy is auto)\n- Switches to `BULL MODE` (green) or `BEAR MODE` (red) once tendency is detected/matched\n- Updates in real-time if tendency flips during scanning\n\n\u003e **Tip**: The `auto-trade` command uses the same config file and flags as `bull-trade` / `bear-trade`. The `tendency.direction` config field is ignored — the bot determines direction automatically.\n\n---\n\n### AI Multi-Agent Decision Flow\n\nWhen AI is enabled, the decision flow operates as follows:\n\n```\nTechnical Indicators ──┐\n                       ├──\u003e AI Agents (concurrent) ──\u003e Weighted Consensus ──\u003e Trade Decision\nSentiment Data ────────┘       │         │         │\n                          OpenAI    DeepSeek    Claude\n```\n\n- **Entry signals**: Technical conditions must pass first, then AI must explicitly approve with the matching signal (`BUY` for bull entry, `SELL` for bear entry) at or above `ai.min-confidence`. `HOLD`, low-confidence, malformed, or opposing AI output blocks new exposure.\n- **Stop-loss / trailing-stop exits**: Execute **immediately** without waiting for AI — safety first.\n- **Take-profit exits**: AI is allowed to block the exit only when it gives a confident opposite signal. `HOLD` and low-confidence output do not prevent taking profit once the technical exit checks pass.\n\n\u003e [!NOTE]\n\u003e The AI consensus is considered alongside — not instead of — the technical indicators. Both must agree for a trade to execute. This dual-confirmation approach reduces false signals while preserving protective exits.\n\n---\n\n## Build from Source\n\nTo build the `binance-bot` from the source code, ensure you have the following prerequisites installed:\n\n#### **Prerequisites**\n1. **Go (Golang):**\n   - Install Go from the [official website](https://go.dev/).\n   - Ensure your Go version is at least **1.19** by running:\n     ```bash\n     go version\n     ```\n\n2. **Git:**\n   - Clone the repository using Git. Install Git from [here](https://git-scm.com/) if you don't already have it.\n\n#### **Steps to Build**\n\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/wferreirauy/binance-bot.git\n   cd binance-bot\n   ```\n\n2. Build the project:\n   ```bash\n   go build -o binance-bot\n   ```\n\n3. Verify the executable:\n   ```bash\n   ./binance-bot --help\n   ```\n\nIf the build succeeds, you should see the general help menu displayed, indicating that the bot has been built successfully.\n\n---\n\n\u003e [!WARNING]\n\u003e Always test the bot in a safe environment (e.g., testnet or small amounts) before live trading. Ensure you understand the risks and implications of using automated trading strategies.\n\n## References\n\n### Binance API documentation\n\nhttps://binance-docs.github.io/apidocs/spot/en/#general-info\n\n### Binance GO library\n\nhttps://github.com/binance/binance-connector-go\n\n### AI Provider APIs\n\n- [OpenAI API](https://platform.openai.com/docs)\n- [DeepSeek API](https://platform.deepseek.com/api-docs)\n- [Anthropic Claude API](https://docs.anthropic.com/en/docs)\n\n### Sentiment Data Sources\n\n- [CryptoCompare News API](https://min-api.cryptocompare.com/) — Free, no API key required\n- [Alternative.me Fear \u0026 Greed Index](https://alternative.me/crypto/fear-and-greed-index/) — Free, no API key required\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwferreirauy%2Fbinance-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwferreirauy%2Fbinance-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwferreirauy%2Fbinance-bot/lists"}