From 3319c273e283c536903c6aab17d217d5c709c3b8 Mon Sep 17 00:00:00 2001 From: tennisleng Date: Sat, 11 Apr 2026 00:34:52 -0400 Subject: [PATCH 1/3] Rewrite README to be more human and descriptive --- README.md | 106 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 92 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 749259b..f441826 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,100 @@ # Triangular Arbitrage Bot -A multi-threaded triangular arbitrage trading bot for cryptocurrency markets using the Binance API. +This is a crypto arbitrage bot I built that scans Binance for triangular arbitrage opportunities across ETH/BTC/ALT pairs and executes trades automatically when it finds an edge. -## My Contributions +The basic idea: if you can go ETH → ALT → BTC → ETH (or the reverse) and end up with more ETH than you started with after fees, that's free money. The catch is these windows are tiny and close fast, so the bot has to be quick about it. -- **CI Workflow**: Added GitHub Actions for testing and linting -- **Arbitrage Algorithms**: Implemented advanced arbitrage detection -- **Monetization**: Added profit tracking and optimization features +## How it works -## Features +The bot continuously scans all available ALT pairs on Binance, checking both forward (ETH → ALT → BTC → ETH) and backward (ETH → BTC → ALT → ETH) paths. It uses multi-threading to scan batches of tokens in parallel — the market moves fast and sequential scanning would miss most opportunities. -- Real-time triangular arbitrage detection -- Multi-threaded execution for speed -- Configurable trading parameters -- Profit tracking and analytics +For each path, it looks at the actual order book (not just ticker prices) to get realistic execution prices. Once it finds a spread that exceeds the minimum profit threshold after accounting for fees and estimated slippage, it fires off limit orders and walks the book at the best available prices. -## Tech Stack +### Key design choices -- **Python** - Core implementation -- **ccxt** - Exchange API library -- **Binance API** - Trading platform integration +- **Maker fees over taker fees** — Limit orders cost 0.05% vs 0.1% for market orders. That difference matters a lot when you're chasing sub-1% spreads. +- **BNB fee discount** — If you hold BNB in your account, Binance gives a 25% fee reduction. The bot checks for this automatically and adjusts its math. +- **Dynamic position sizing** — Bigger opportunities get more capital allocated (up to 80% of balance), smaller ones get more conservative sizing. No point risking a lot on a 0.3% edge. +- **Slippage estimation** — Before committing to a trade, the bot scans the top 10 order book levels to estimate how much slippage you'd actually take at a given size. This prevents the classic "looked profitable on paper, lost money in execution" problem. + +## Project structure + +``` +ini.py — Entry point. Spawns checker threads, runs the main loop. +src/model.py — Core trading logic: order execution, price fetching, arbitrage estimation. +src/strategies.py — Alternative strategy implementations (grid trading, funding rate, etc.) +src/arbitrage_algorithms.py — Advanced detection algorithms +src/dashboard.py — Flask-based real-time dashboard with WebSocket updates +src/order_executor.py — Order management and execution engine +src/ml_predictor.py — ML-based opportunity prediction (XGBoost, LightGBM, PyTorch) +src/exchange_manager.py — Exchange connection management +src/telegram_notifier.py — Trade alerts via Telegram +data/settings.py — All configurable parameters in one place +data/secrets.py — API keys (not committed, obviously) +data/tokens.py — List of ALT tokens to scan +``` + +## Getting started + +```bash +pip install -r requirements.txt +``` + +Add your Binance API keys to `data/secrets.py`: +```python +BINANCE_KEY = "your-api-key" +BINANCE_SECRET = "your-api-secret" +``` + +Then run: +```bash +python ini.py +``` + +The bot will start scanning immediately and log everything to `logs.txt`. You can monitor profit in a separate terminal: +```bash +python check_profit.py +``` + +## Configuration + +Everything lives in `data/settings.py`. The important ones: + +| Setting | Default | What it does | +|---|---|---| +| `MIN_PROFIT_USD` | $1.00 | Won't execute a trade unless expected profit exceeds this | +| `AGGRESSIVE_MODE` | True | Lowers detection threshold by 20%, uses 8 threads instead of 5 | +| `ENABLE_DYNAMIC_POSITION_SIZING` | True | Scales position size based on opportunity quality | +| `ENABLE_SLIPPAGE_OPTIMIZATION` | True | Uses order book depth to estimate real execution costs | +| `MAX_POSITION_SIZE` | 0.5 | Max fraction of ETH balance to use per trade | + +## Dashboard + +There's a real-time web dashboard built with Flask + Socket.IO + Plotly that shows live opportunity scanning, profit over time, and trade history. It starts automatically on port 5001 when enabled, or you can access the REST API on port 5000 if you have a premium subscription. + +## Backtesting + +I ran a 10-year backtest across six strategies. All came back positive EV: + +- **Funding Rate Arbitrage**: $17,269 total PnL (Sharpe: 58.07) +- **Grid Trading**: $6,485 across 34k trades +- **Futures Basis**: $4,903 (Sharpe: 6.30) +- **Market Making**: $581 across 8.5k trades +- **Cross-Exchange**: $3.91 across 42 trades +- **Triangular Arbitrage**: $2.09 across 53 trades + +Full results in `backtest_results.json`. Run your own with `python run_backtest.py`. + +## Telegram notifications + +Optional but useful — set up a bot through [@BotFather](https://t.me/BotFather), drop the token and chat ID into `data/secrets.py`, and you'll get push notifications for every opportunity detected, trade executed, and daily summaries. + +## What I learned building this + +Triangular arbitrage on a single exchange is much harder than it sounds. The spreads are razor-thin — we're talking fractions of a percent — and by the time you detect an opportunity and get your orders filled, it's often gone. The math is straightforward; the execution is the hard part. + +The biggest improvements came from switching to maker fees (cut costs in half), adding proper slippage estimation (stopped the bot from taking bad trades), and dynamic position sizing (stopped it from over-committing on marginal opportunities). + +## License + +GPL-3.0 — see [LICENSE](LICENSE) for details. From b70192310b45152ed575569b08da37ed8aec85e7 Mon Sep 17 00:00:00 2001 From: tennisleng Date: Sat, 11 Apr 2026 00:39:59 -0400 Subject: [PATCH 2/3] Remove ASCII art, keep it clean text + tables --- README.md | 128 +++++++++++++++++++++++++++--------------------------- 1 file changed, 64 insertions(+), 64 deletions(-) diff --git a/README.md b/README.md index f441826..0618a45 100644 --- a/README.md +++ b/README.md @@ -1,100 +1,100 @@ # Triangular Arbitrage Bot -This is a crypto arbitrage bot I built that scans Binance for triangular arbitrage opportunities across ETH/BTC/ALT pairs and executes trades automatically when it finds an edge. +A multi-threaded trading bot that exploits price inefficiencies across ETH/BTC/ALT pairs on Binance. -The basic idea: if you can go ETH → ALT → BTC → ETH (or the reverse) and end up with more ETH than you started with after fees, that's free money. The catch is these windows are tiny and close fast, so the bot has to be quick about it. +--- -## How it works +### The concept -The bot continuously scans all available ALT pairs on Binance, checking both forward (ETH → ALT → BTC → ETH) and backward (ETH → BTC → ALT → ETH) paths. It uses multi-threading to scan batches of tokens in parallel — the market moves fast and sequential scanning would miss most opportunities. +When the price of a token is slightly different depending on which pair you trade through, there's a small window to profit. This bot catches those windows. -For each path, it looks at the actual order book (not just ticker prices) to get realistic execution prices. Once it finds a spread that exceeds the minimum profit threshold after accounting for fees and estimated slippage, it fires off limit orders and walks the book at the best available prices. +The bot checks both directions — forward (ETH → ALT → BTC → ETH) and backward (ETH → BTC → ALT → ETH) — in parallel across every available ALT pair, checks the actual order book depth (not just ticker price), and only executes when the math works out after fees and slippage. -### Key design choices +--- -- **Maker fees over taker fees** — Limit orders cost 0.05% vs 0.1% for market orders. That difference matters a lot when you're chasing sub-1% spreads. -- **BNB fee discount** — If you hold BNB in your account, Binance gives a 25% fee reduction. The bot checks for this automatically and adjusts its math. -- **Dynamic position sizing** — Bigger opportunities get more capital allocated (up to 80% of balance), smaller ones get more conservative sizing. No point risking a lot on a 0.3% edge. -- **Slippage estimation** — Before committing to a trade, the bot scans the top 10 order book levels to estimate how much slippage you'd actually take at a given size. This prevents the classic "looked profitable on paper, lost money in execution" problem. +### What makes this different -## Project structure +**It's not a toy.** Most open-source arb bots use ticker prices and ignore execution costs — they look profitable on paper but lose money in practice. This one: -``` -ini.py — Entry point. Spawns checker threads, runs the main loop. -src/model.py — Core trading logic: order execution, price fetching, arbitrage estimation. -src/strategies.py — Alternative strategy implementations (grid trading, funding rate, etc.) -src/arbitrage_algorithms.py — Advanced detection algorithms -src/dashboard.py — Flask-based real-time dashboard with WebSocket updates -src/order_executor.py — Order management and execution engine -src/ml_predictor.py — ML-based opportunity prediction (XGBoost, LightGBM, PyTorch) -src/exchange_manager.py — Exchange connection management -src/telegram_notifier.py — Trade alerts via Telegram -data/settings.py — All configurable parameters in one place -data/secrets.py — API keys (not committed, obviously) -data/tokens.py — List of ALT tokens to scan -``` +- Reads order book depth before every trade to estimate real slippage +- Uses limit orders (0.05% maker fee) instead of market orders (0.1% taker fee) +- Auto-detects BNB balance for an additional 25% fee discount +- Scales position size dynamically — bigger edge = more capital, small edge = conservative +- Runs 8 parallel threads in aggressive mode for faster scanning + +--- -## Getting started +### Quickstart ```bash pip install -r requirements.txt ``` -Add your Binance API keys to `data/secrets.py`: -```python -BINANCE_KEY = "your-api-key" -BINANCE_SECRET = "your-api-secret" -``` +Add your keys to `data/secrets.py`, then: -Then run: ```bash -python ini.py +python ini.py # start the bot +python check_profit.py # monitor profit (separate terminal) ``` -The bot will start scanning immediately and log everything to `logs.txt`. You can monitor profit in a separate terminal: -```bash -python check_profit.py -``` +--- -## Configuration +### Config -Everything lives in `data/settings.py`. The important ones: +All in `data/settings.py`: -| Setting | Default | What it does | +| | Default | | |---|---|---| -| `MIN_PROFIT_USD` | $1.00 | Won't execute a trade unless expected profit exceeds this | -| `AGGRESSIVE_MODE` | True | Lowers detection threshold by 20%, uses 8 threads instead of 5 | -| `ENABLE_DYNAMIC_POSITION_SIZING` | True | Scales position size based on opportunity quality | -| `ENABLE_SLIPPAGE_OPTIMIZATION` | True | Uses order book depth to estimate real execution costs | -| `MAX_POSITION_SIZE` | 0.5 | Max fraction of ETH balance to use per trade | - -## Dashboard +| **Min profit threshold** | `$1.00` | Won't trade below this | +| **Aggressive mode** | `On` | 20% lower threshold, 8 threads | +| **Dynamic sizing** | `On` | 35-80% of balance per trade | +| **Slippage optimization** | `On` | Order book depth analysis | +| **Max position** | `50%` | Safety cap per trade | -There's a real-time web dashboard built with Flask + Socket.IO + Plotly that shows live opportunity scanning, profit over time, and trade history. It starts automatically on port 5001 when enabled, or you can access the REST API on port 5000 if you have a premium subscription. +--- -## Backtesting +### Project layout -I ran a 10-year backtest across six strategies. All came back positive EV: +``` +ini.py entry point — spawns threads, runs the loop +src/ + model.py core logic — pricing, execution, arbitrage math + strategies.py alternative strategies (grid, funding rate, etc) + arbitrage_algorithms.py detection algorithms + dashboard.py live web dashboard (Flask + WebSocket) + ml_predictor.py ML-based prediction (XGBoost / LightGBM / PyTorch) + order_executor.py order management + exchange_manager.py exchange connections + telegram_notifier.py trade alerts via Telegram +data/ + settings.py all tunable parameters + secrets.py API keys (not committed) + tokens.py token list to scan +``` -- **Funding Rate Arbitrage**: $17,269 total PnL (Sharpe: 58.07) -- **Grid Trading**: $6,485 across 34k trades -- **Futures Basis**: $4,903 (Sharpe: 6.30) -- **Market Making**: $581 across 8.5k trades -- **Cross-Exchange**: $3.91 across 42 trades -- **Triangular Arbitrage**: $2.09 across 53 trades +--- -Full results in `backtest_results.json`. Run your own with `python run_backtest.py`. +### Backtest results (10yr simulated) -## Telegram notifications +| Strategy | PnL | Trades | +|---|---|---| +| Funding Rate Arb | **$17,269** | 5,419 collections | +| Grid Trading | **$6,485** | 34,141 | +| Futures Basis | **$4,903** | 120 | +| Market Making | **$581** | 8,571 | +| Cross-Exchange | **$3.91** | 42 | +| Triangular Arb | **$2.09** | 53 | -Optional but useful — set up a bot through [@BotFather](https://t.me/BotFather), drop the token and chat ID into `data/secrets.py`, and you'll get push notifications for every opportunity detected, trade executed, and daily summaries. +All strategies positive EV. Full data in `backtest_results.json`, run your own with `python run_backtest.py`. -## What I learned building this +--- -Triangular arbitrage on a single exchange is much harder than it sounds. The spreads are razor-thin — we're talking fractions of a percent — and by the time you detect an opportunity and get your orders filled, it's often gone. The math is straightforward; the execution is the hard part. +### Extras -The biggest improvements came from switching to maker fees (cut costs in half), adding proper slippage estimation (stopped the bot from taking bad trades), and dynamic position sizing (stopped it from over-committing on marginal opportunities). +- **Dashboard** — real-time web UI on port 5001 showing opportunities, profit charts, trade history +- **Telegram alerts** — set up via [@BotFather](https://t.me/BotFather), drop creds in `data/secrets.py` +- **REST API** — stats, trade history, subscription management on port 5000 -## License +--- -GPL-3.0 — see [LICENSE](LICENSE) for details. +*Built with Python, ccxt, and a lot of staring at order books.* From 81c682e1dff48010479ef036a70c458228ebe056 Mon Sep 17 00:00:00 2001 From: tennisleng Date: Sat, 11 Apr 2026 00:41:19 -0400 Subject: [PATCH 3/3] =?UTF-8?q?Full=20revamp=20=E2=80=94=20bullets=20and?= =?UTF-8?q?=20tables=20only,=20no=20visuals?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 133 +++++++++++++++++++++--------------------------------- 1 file changed, 52 insertions(+), 81 deletions(-) diff --git a/README.md b/README.md index 0618a45..67f5d42 100644 --- a/README.md +++ b/README.md @@ -1,100 +1,71 @@ # Triangular Arbitrage Bot -A multi-threaded trading bot that exploits price inefficiencies across ETH/BTC/ALT pairs on Binance. +Automated crypto trading bot that finds and exploits price gaps across ETH/BTC/ALT pairs on Binance. ---- +## What it does -### The concept +- Scans every ALT token on Binance for triangular arbitrage opportunities in real time +- Checks both forward (ETH → ALT → BTC → ETH) and backward (ETH → BTC → ALT → ETH) paths simultaneously +- Uses actual order book depth, not ticker prices, to calculate real execution cost +- Executes trades automatically when expected profit exceeds the threshold +- Runs 8 parallel threads for maximum scanning speed -When the price of a token is slightly different depending on which pair you trade through, there's a small window to profit. This bot catches those windows. +## Why it works -The bot checks both directions — forward (ETH → ALT → BTC → ETH) and backward (ETH → BTC → ALT → ETH) — in parallel across every available ALT pair, checks the actual order book depth (not just ticker price), and only executes when the math works out after fees and slippage. +- Limit orders at 0.05% maker fee instead of 0.1% taker — cuts trading cost in half +- Detects BNB balance and applies the 25% Binance fee discount automatically +- Estimates slippage from order book depth before committing to any trade +- Scales position size based on opportunity quality — bigger edge gets more capital +- Filters out opportunities that look good on paper but would lose money in execution ---- +## Backtest Performance (10yr simulated) -### What makes this different +| Strategy | Total PnL | Trades | Profitable | +|---|---|---|---| +| Funding Rate Arb | $17,269 | 5,419 | ✅ | +| Grid Trading | $6,485 | 34,141 | ✅ | +| Futures Basis | $4,903 | 120 | ✅ | +| Market Making | $581 | 8,571 | ✅ | +| Cross-Exchange | $3.91 | 42 | ✅ | +| Triangular Arb | $2.09 | 53 | ✅ | -**It's not a toy.** Most open-source arb bots use ticker prices and ignore execution costs — they look profitable on paper but lose money in practice. This one: +**Combined PnL: $29,244 — all strategies positive EV.** -- Reads order book depth before every trade to estimate real slippage -- Uses limit orders (0.05% maker fee) instead of market orders (0.1% taker fee) -- Auto-detects BNB balance for an additional 25% fee discount -- Scales position size dynamically — bigger edge = more capital, small edge = conservative -- Runs 8 parallel threads in aggressive mode for faster scanning +## Configuration ---- - -### Quickstart - -```bash -pip install -r requirements.txt -``` - -Add your keys to `data/secrets.py`, then: - -```bash -python ini.py # start the bot -python check_profit.py # monitor profit (separate terminal) -``` - ---- - -### Config +| Setting | Default | Description | +|---|---|---| +| Min profit threshold | $1.00 | Minimum expected profit to execute a trade | +| Aggressive mode | On | Lowers detection threshold by 20%, uses 8 threads | +| Dynamic position sizing | On | Allocates 35-80% of balance based on opportunity quality | +| Slippage optimization | On | Analyzes order book depth before every trade | +| Max position size | 50% | Hard cap on balance used per trade | -All in `data/settings.py`: +## Setup -| | Default | | -|---|---|---| -| **Min profit threshold** | `$1.00` | Won't trade below this | -| **Aggressive mode** | `On` | 20% lower threshold, 8 threads | -| **Dynamic sizing** | `On` | 35-80% of balance per trade | -| **Slippage optimization** | `On` | Order book depth analysis | -| **Max position** | `50%` | Safety cap per trade | - ---- - -### Project layout - -``` -ini.py entry point — spawns threads, runs the loop -src/ - model.py core logic — pricing, execution, arbitrage math - strategies.py alternative strategies (grid, funding rate, etc) - arbitrage_algorithms.py detection algorithms - dashboard.py live web dashboard (Flask + WebSocket) - ml_predictor.py ML-based prediction (XGBoost / LightGBM / PyTorch) - order_executor.py order management - exchange_manager.py exchange connections - telegram_notifier.py trade alerts via Telegram -data/ - settings.py all tunable parameters - secrets.py API keys (not committed) - tokens.py token list to scan -``` - ---- - -### Backtest results (10yr simulated) - -| Strategy | PnL | Trades | -|---|---|---| -| Funding Rate Arb | **$17,269** | 5,419 collections | -| Grid Trading | **$6,485** | 34,141 | -| Futures Basis | **$4,903** | 120 | -| Market Making | **$581** | 8,571 | -| Cross-Exchange | **$3.91** | 42 | -| Triangular Arb | **$2.09** | 53 | +- Install dependencies with `pip install -r requirements.txt` +- Add Binance API keys to `data/secrets.py` +- Run `python ini.py` to start the bot +- Run `python check_profit.py` in a separate terminal to monitor profit +- Optional: add Telegram bot token and chat ID to `data/secrets.py` for push notifications -All strategies positive EV. Full data in `backtest_results.json`, run your own with `python run_backtest.py`. +## Features ---- +- **Live dashboard** — Flask + WebSocket UI on port 5001 with profit charts and trade history +- **Telegram alerts** — real-time notifications for every opportunity and trade +- **REST API** — stats, trade history, and subscription management on port 5000 +- **ML prediction** — opportunity scoring with XGBoost, LightGBM, and PyTorch models +- **Profit tracking** — persistent tracking across restarts, saved to `profit_tracking.json` -### Extras +## Tech -- **Dashboard** — real-time web UI on port 5001 showing opportunities, profit charts, trade history -- **Telegram alerts** — set up via [@BotFather](https://t.me/BotFather), drop creds in `data/secrets.py` -- **REST API** — stats, trade history, subscription management on port 5000 +- Python +- ccxt (exchange API) +- Flask + Socket.IO (dashboard) +- Plotly (charting) +- scikit-learn, XGBoost, LightGBM, PyTorch (ML) +- Binance API ---- +## License -*Built with Python, ccxt, and a lot of staring at order books.* +GPL-3.0