pie/trading-bot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update documentation to reflect Inverse ETP strategy and virtual balance logic

Browse Source
This commit is contained in:
pie
2026-05-07 11:59:50 +01:00
parent deba044a7b
commit 1cfca22ddd
3 changed files with 90 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files
GEMINI.md
+31 -24
View File
@@ -1,11 +1,11 @@
# Trading212 Python Scalping Bot - "Touch & Turn" (Opening Range Reversal) # Trading212 Python Scalping Bot - "Touch & Turn" (Opening Range Reversal)
This project implements the "Touch & Turn" scalping strategy, originally designed for ProRealTime, translated into Python for the Trading212 API. This project implements the "Touch & Turn" scalping strategy, originally designed for ProRealTime, translated into Python for the Trading212 API. It is optimized for the UK ISA environment using Inverse ETPs for shorting.
## Project Overview ## Project Overview
* **Strategy:** Opening Range Liquidity Reversal (Touch & Turn). * **Strategy:** Opening Range Liquidity Reversal (Touch & Turn).
* **Asset Class:** US Stocks (e.g., Netflix, Apple, Tesla). * **Asset Class:** US Stocks (e.g., NVDA, ARM, TSLA).
* **Timeframe:** 15-minute chart. * **Timeframe:** 15-minute chart.
* **Operating Window:** 09:30 - 11:00 EST (Opening of the US Regular Trading Session). * **Operating Window:** 09:30 - 11:00 EST (Opening of the US Regular Trading Session).
@@ -13,26 +13,28 @@ This project implements the "Touch & Turn" scalping strategy, originally designe
1. **Identify the Opening Candle:** Capture the `High`, `Low`, `Open`, and `Close` of the first 15-minute candle of the session (09:30 to 09:45 EST). 1. **Identify the Opening Candle:** Capture the `High`, `Low`, `Open`, and `Close` of the first 15-minute candle of the session (09:30 to 09:45 EST).
2. **Filter for Liquidity:** 2. **Filter for Liquidity:**
- Calculate the 14-day ATR (Average True Range). - The opening range (`High - Low`) must be at least **25% of the 14-day ATR**. If smaller, the bot stays flat.
- The opening range (`High - Low`) must be at least **25% of the ATR**. If smaller, the bot stays flat for the day.
3. **Determine Direction:** 3. **Determine Direction:**
- If the candle is **Bearish** (Close < Open): Prepare for a **LONG** entry at the `Low`. - If the candle is **Bearish** (Close < Open): Prepare for a **LONG** entry.
- If the candle is **Bullish** (Close > Open): Prepare for a **SHORT** entry at the `High`. - If the candle is **Bullish** (Close > Open): Prepare for a **SHORT** entry.
4. **Calculate Targets (Fibonacci):** 4. **ISA-Compliant Shorting:**
- The target price is the **38.2% Fibonacci level** of the opening candle's range. - Since standard shorting is forbidden in a UK ISA, the bot automatically substitutes SHORT signals with **BUY orders for 3x Inverse ETPs** (e.g., 3SLA for TSLA).
5. **Risk Management:** 5. **Execution:**
- **Take Profit (TP):** The distance from the entry to the 38.2% Fib level. - Uses **Market Orders** at 09:45 EST for immediate entry.
- **Stop Loss (SL):** Half the TP distance (Risk:Reward ratio of 1:2). - Recalculates SL/TP brackets based on the **Actual Fill Price** fetched from the portfolio.
6. **Automatic Exit:** Force close any open positions at 11:00 EST. 6. **Risk Management:**
- **Position Sizing:** Risks **1% of account balance** per trade.
- **Virtual Balance:** In demo mode, subtracts £4,750 from total value to simulate a realistic £250 starting point.
- **Targets:** 38.2% Fibonacci retracement level. Risk:Reward ratio of 1:2.
7. **Automatic Exit:** Force close any open positions at 11:00 EST via Market Order.
## Technical Architecture ## Technical Architecture
* **API Client (`src/api/client.py`):** Handles REST calls to Trading212. * **API Client (`src/api/client.py`):** Handles REST Basic Auth calls to Trading212.
* **Strategy Engine (`src/strategy/touch_turn.py`):** * **Strategy Engine (`src/strategy/touch_turn.py`):** Calculates setup, Fibonacci levels, and percentage-based targets.
- Monitors the clock for the 09:45 EST trigger. * **Execution Manager (`src/execution/manager.py`):** Handles ticker swapping for ISA mode, market order placement, protection bracketing, and status monitoring.
- Fetches 14-day ATR and the 09:30-09:45 15m candle. * **Orchestrator (`main.py`):** Automates the morning routine: scanning, backtesting, and spawning parallel execution threads.
- Calculates entry/TP/SL levels. * **Data resilient:** Implements retry loops and random jitter to handle API delays and rate limits (429/403/404 errors).
* **Execution Engine (`src/execution/manager.py`):** Places the limit orders and manages the position lifetime.
## Getting Started ## Getting Started
@@ -41,13 +43,18 @@ This project implements the "Touch & Turn" scalping strategy, originally designe
pip install -r requirements.txt pip install -r requirements.txt
``` ```
2. **Configuration:** 2. **Configuration:**
- Set `TRADING212_API_KEY` and `TRADING212_BASE_URL` in your `.env` file. - Set credentials in your `.env` file.
- Ensure your system clock is accurate or handle timezone conversions to EST. - `ISA_MODE=True` enables Inverse ETP substitution.
3. **Operation:**
- Best deployed via a systemd timer at 09:30 America/New_York time.
## TODOs ## TODOs
- [x] Document the strategy logic. - [x] Document the strategy logic.
- [x] Implement ATR calculation in the strategy engine. - [x] Implement ATR calculation and Fibonacci targets.
- [x] Implement the 15m candle capture logic. - [x] Implement 15m candle capture with timezone resilience.
- [x] Implement the entry/exit order placement logic in the execution manager. - [x] Implement ISA-compliant shorting via Inverse ETP mapping.
- [x] Create a backtesting script (optional but recommended). - [x] Implement Risk-based position sizing (Virtual Balance logic).
- [x] Create a leaderboard-based backtesting engine.
- [x] Implement resilient execution (Retry loops, Jitter, Portfolio-checks).
- [x] Add daily logging and P&L tracking (CSV).
README.md
+30 -74
View File
@@ -12,14 +12,15 @@ This project implements the "Touch & Turn" scalping strategy (Opening Range Liqu
The strategy capitalizes on the initial liquidity and volatility of the US market open. The strategy capitalizes on the initial liquidity and volatility of the US market open.
1. **The Setup:** Captures the high and low of the first 15-minute candle (09:30 - 09:45 EST). 1. **The Setup:** Captures the high and low of the first 15-minute candle (09:30 - 09:45 EST).
2. **The Filter:** The range of this opening candle must be at least **25%** of the stock's 14-day Average True Range (ATR). If the market is too quiet, no trade is taken. 2. **The Filter:** The range of this opening candle must be at least **25%** of the stock's 14-day Average True Range (ATR).
3. **The Trigger:** 3. **The Trigger (ISA Optimized):**
- If the opening candle closes **Bearish** (Close < Open), the bot prepares a **LONG** entry at the candle's Low. - **LONG (Bearish candle):** Bot places an immediate **Market BUY** order for the stock.
- If the opening candle closes **Bullish** (Close > Open), the bot prepares a **SHORT** entry at the candle's High. - **SHORT (Bullish candle):** Since standard shorting is restricted in UK ISAs, the bot automatically substitutes this with a **Market BUY** order for a **3x Inverse ETP** (e.g., buying `3SLA` if `TSLA` gives a short signal).
4. **The Targets:** 4. **The Targets:**
- **Take Profit (TP):** The 38.2% Fibonacci retracement level of the opening candle's range. - Brackets are placed **immediately** after the market order is filled, using the **Actual Fill Price** from your portfolio.
- **Stop Loss (SL):** Placed to ensure a Risk:Reward ratio of 1:2 (Risking 1 unit to make 2). - **Take Profit (TP):** The 38.2% Fibonacci retracement level.
5. **Time Exit:** All open positions are forcefully closed at 11:00 EST to avoid mid-day chop. - **Stop Loss (SL):** Placed to ensure a Risk:Reward ratio of 1:2.
5. **Time Exit:** All open positions are forcefully closed via Market Order at **11:00 EST**.
--- ---
@@ -29,96 +30,51 @@ The strategy capitalizes on the initial liquidity and volatility of the US marke
```bash ```bash
python3 -m venv venv python3 -m venv venv
source venv/bin/activate source venv/bin/activate
```
2. **Install dependencies:**
```bash
pip install -r requirements.txt pip install -r requirements.txt
``` ```
*(Note: The `prettytable` library was recently added for backtesting outputs. Run `pip install prettytable` if it's missing from your requirements file).*
3. **Configure Environment Variables:** 2. **Configure Environment Variables:**
Create a `.env` file in the root directory based on `.env.example`: Create a `.env` file in the root directory:
```ini ```ini
TRADING212_API_KEY_ID=your_key_id_here TRADING212_API_KEY_ID=your_key_id_here
TRADING212_API_KEY=your_api_key_here TRADING212_API_KEY=your_api_key_here
TRADING212_BASE_URL=https://demo.trading212.com/api/v0/ TRADING212_BASE_URL=https://demo.trading212.com/api/v0/
ISA_MODE=True
``` ```
*You can generate your API Key and ID inside the Trading212 app under Settings -> API.*
4. **Verify Connection:**
Run the test script to ensure your credentials are correct and you can read your account balance:
```bash
python3 test_api_connection.py
```
---
## The Workflow & Scripts
This repository is split into the live execution bot and several helper scripts to find the best assets to trade.
### 1. Finding ISA-Eligible Tickers
If you are trading from a UK Trading212 Stocks ISA, you are restricted from trading US-domiciled ETFs and certain other assets.
Run the ISA candidate script to fetch all available instruments, filter for ISA-compliant US Stocks, and rank a basket of popular tech stocks by their current volatility (ATR %):
```bash
PYTHONPATH=. python3 scripts/find_isa_candidates.py
```
*This script outputs a leaderboard to the console and saves `isa_watchlist.csv`.*
### 2. Backtesting the Watchlist
High volatility doesn't always guarantee a strategy works on a specific stock. You must backtest.
Run the backtesting engine. It will automatically read the `isa_watchlist.csv` generated in the previous step and simulate the strategy over the last ~60 trading days (using 15m data from Yahoo Finance).
```bash
PYTHONPATH=. python3 scripts/backtest.py
```
*This will output a leaderboard ranked by **Net PnL (in Risk Multiples/R)**. Identify the top 2-3 performing tickers (e.g., `NFLX`, `UBER`, `MSFT`) to configure the live bot.*
### 3. Running the Live Bot
Once you have identified the best tickers for the day, the orchestrator will automatically spin up threads to monitor and trade them.
Start the bot before the US market opens (09:30 EST):
```bash
python3 main.py
```
The bot will:
1. Initialize and run the ISA scanner.
2. Backtest the top candidates and pick the **Top 3** with the highest historical R-multiple profit.
3. Spawn isolated background threads for each ticker to wait for exactly 09:45 EST.
4. Evaluate the opening candle, calculate risk-adjusted position sizes, and place the necessary Entry, Take Profit, and Stop Loss orders.
5. Poll for order fills and gracefully flatten all open positions at exactly 11:00 EST.
--- ---
## Risk Management & Position Sizing ## Risk Management & Position Sizing
The bot uses dynamic **Risk-Based Position Sizing**. It does not buy a fixed number of shares. Instead, it calculates the distance between the Entry price and the Stop Loss price to determine the "Risk per Share". The bot uses dynamic **Risk-Based Position Sizing** to ensure consistent exposure.
By default, the bot risks **1% of your account balance** per trade. - **1% Risk Rule:** By default, the bot risks **1% of your account balance** per trade.
- **Virtual Balance simulation:** If you are testing on a demo account with a large balance (e.g., £5,000) but plan to trade live with £250, the bot can maintain perspective. It automatically calculates a "Virtual Balance" by subtracting £4,750 from your actual total, ensuring your risk amount is exactly what it will be in the real world.
**Virtual Balances:** - **Leverage Adjusted:** For Inverse ETPs (3x leverage), the bot adjusts the quantity and bracket percentages to ensure the monetary risk remains identical to a standard 1x stock trade.
If you are testing on a demo account with a massive starting balance (e.g., £5,000) but plan to trade live with a much smaller amount, you can override the risk calculation to maintain psychological perspective. Set `VIRTUAL_STARTING_BALANCE=250` in your `.env` file. The bot will pretend your account only has £250 and will size its fraction share purchases to risk exactly £2.50 per trade.
--- ---
## Logging & PnL Tracking ## Automation Workflow
The bot provides comprehensive monitoring out of the box: The bot is designed to be triggered once per day (e.g., via a **systemd timer** or cron) at exactly **09:30 EST**.
- **Console & File Logging:** All activity (entries, fills, errors) is logged to the console and simultaneously appended to a daily file in the `logs/` directory (e.g., `logs/bot_2026-04-14.log`). 1. **Scan:** Runs the ISA candidate filter to find the most volatile US stocks.
- **PnL Tracking:** A running ledger of all closed trades is kept in `pnl_tracking.csv`. This file records the Ticker, Direction, Entry/Exit prices, the reason for the exit (e.g., "TP Hit" or "11:00 Time Exit"), and the Profit/Loss measured in Risk Multiples (R). You can import this CSV into Excel or Python to chart your strategy's performance over time. 2. **Backtest:** Runs a 60-day historical backtest on the top 10 candidates.
3. **Select:** Picks the **Top 3** tickers that showed a positive historical return (Net PnL > 0 R).
4. **Execute:** Spawns parallel threads to monitor and trade the selected assets.
5. **Clean:** Shuts down automatically after the 11:00 EST exit and cleanup.
--- ---
## Utility Scripts ## Monitoring
- `scripts/get_available_tickers.py`: Fetches the raw metadata for all 16,000+ instruments available on Trading212 and saves them to `available_instruments.json` and `available_tickers.csv`. Useful if you want to manually search for new tickers outside the default tech/growth basket. - **Logs:** All activity is recorded in `logs/bot_YYYY-MM-DD.log`.
- **PnL Tracking:** A permanent ledger of every trade (including ETP substitutions) is kept in `pnl_tracking.csv` for graphing and analysis.
## Architecture ## Architecture
* **`src/api/client.py`:** Handles REST HTTP basic authentication and request formatting for the Trading212 API. * **`src/api/client.py`:** REST API wrapper with Basic Auth.
* **`src/strategy/touch_turn.py`:** The core logic engine. Fetches market data via Yahoo Finance, calculates ATR and Fibonacci levels, and returns the trade parameters. * **`src/strategy/touch_turn.py`:** Logic engine and Fibonacci calculator.
* **`src/strategy/scanner.py`:** The ranking engine used to sort tickers by ATR volatility. * **`src/strategy/inverse_mapping.py`:** Map of US stocks to 3x Short Inverse ETPs.
* **`src/execution/manager.py`:** Consumes the trade parameters and places the orders via the API client. * **`src/execution/manager.py`:** Handles market entries, actual fill-based bracketing, and ISA substitutions.
* **`main.py`:** The morning orchestrator.
src/strategy/inverse_mapping.py
+29
View File
@@ -0,0 +1,29 @@
# Mapping of standard US Stock tickers to their 3x Short Inverse ETP counterparts on Trading212 (USD versions)
INVERSE_TICKER_MAP = {
"TSLA": "3STSl_EQ", # GraniteShares 3x Short Tesla
"NVDA": "3SNVl_EQ", # GraniteShares 3x Short NVIDIA
"AAPL": "3SAPl_EQ", # GraniteShares 3x Short Apple
"AMZN": "3SAMl_EQ", # GraniteShares 3x Short Amazon
"NFLX": "3SNFl_EQ", # GraniteShares 3x Short Netflix
"MSFT": "3SMSl_EQ", # Leverage Shares -3x Short Microsoft
"GOOGL": "3SGOl_EQ", # Leverage Shares -3x Short Alphabet
"META": "3SMEl_EQ", # Leverage Shares -3x Short Facebook META
"MSTR": "3SMIl_EQ", # GraniteShares 3x Short MicroStrategy
"PLTR": "3SPAl_EQ", # GraniteShares 3x Short Palantir
"AMD": "SAMDl_EQ", # Leverage Shares -1x AMD (Note: 3x not available in USD for AMD, using -1x)
}
# Leverage factors for the mapped tickers
LEVERAGE_MAP = {
"3STSl_EQ": 3.0,
"3SNVl_EQ": 3.0,
"3SAPl_EQ": 3.0,
"3SAMl_EQ": 3.0,
"3SNFl_EQ": 3.0,
"3SMSl_EQ": 3.0,
"3SGOl_EQ": 3.0,
"3SMEl_EQ": 3.0,
"3SMIl_EQ": 3.0,
"3SPAl_EQ": 3.0,
"SAMDl_EQ": 1.0,
}