From 1cfca22dddb23c9e0b582dd0ddcd04df1dc551f0 Mon Sep 17 00:00:00 2001 From: pie Date: Thu, 7 May 2026 11:59:50 +0100 Subject: [PATCH] docs: update documentation to reflect Inverse ETP strategy and virtual balance logic --- GEMINI.md | 55 +++++++++-------- README.md | 104 +++++++++----------------------- src/strategy/inverse_mapping.py | 29 +++++++++ 3 files changed, 90 insertions(+), 98 deletions(-) create mode 100644 src/strategy/inverse_mapping.py diff --git a/GEMINI.md b/GEMINI.md index 01259fc..0632829 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -1,11 +1,11 @@ # 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 * **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. * **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). 2. **Filter for Liquidity:** - - Calculate the 14-day ATR (Average True Range). - - The opening range (`High - Low`) must be at least **25% of the ATR**. If smaller, the bot stays flat for the day. + - The opening range (`High - Low`) must be at least **25% of the 14-day ATR**. If smaller, the bot stays flat. 3. **Determine Direction:** - - If the candle is **Bearish** (Close < Open): Prepare for a **LONG** entry at the `Low`. - - If the candle is **Bullish** (Close > Open): Prepare for a **SHORT** entry at the `High`. -4. **Calculate Targets (Fibonacci):** - - The target price is the **38.2% Fibonacci level** of the opening candle's range. -5. **Risk Management:** - - **Take Profit (TP):** The distance from the entry to the 38.2% Fib level. - - **Stop Loss (SL):** Half the TP distance (Risk:Reward ratio of 1:2). -6. **Automatic Exit:** Force close any open positions at 11:00 EST. + - If the candle is **Bearish** (Close < Open): Prepare for a **LONG** entry. + - If the candle is **Bullish** (Close > Open): Prepare for a **SHORT** entry. +4. **ISA-Compliant Shorting:** + - 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. **Execution:** + - Uses **Market Orders** at 09:45 EST for immediate entry. + - Recalculates SL/TP brackets based on the **Actual Fill Price** fetched from the portfolio. +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 -* **API Client (`src/api/client.py`):** Handles REST calls to Trading212. -* **Strategy Engine (`src/strategy/touch_turn.py`):** - - Monitors the clock for the 09:45 EST trigger. - - Fetches 14-day ATR and the 09:30-09:45 15m candle. - - Calculates entry/TP/SL levels. -* **Execution Engine (`src/execution/manager.py`):** Places the limit orders and manages the position lifetime. +* **API Client (`src/api/client.py`):** Handles REST Basic Auth calls to Trading212. +* **Strategy Engine (`src/strategy/touch_turn.py`):** Calculates setup, Fibonacci levels, and percentage-based targets. +* **Execution Manager (`src/execution/manager.py`):** Handles ticker swapping for ISA mode, market order placement, protection bracketing, and status monitoring. +* **Orchestrator (`main.py`):** Automates the morning routine: scanning, backtesting, and spawning parallel execution threads. +* **Data resilient:** Implements retry loops and random jitter to handle API delays and rate limits (429/403/404 errors). ## Getting Started @@ -41,13 +43,18 @@ This project implements the "Touch & Turn" scalping strategy, originally designe pip install -r requirements.txt ``` 2. **Configuration:** - - Set `TRADING212_API_KEY` and `TRADING212_BASE_URL` in your `.env` file. - - Ensure your system clock is accurate or handle timezone conversions to EST. + - Set credentials in your `.env` file. + - `ISA_MODE=True` enables Inverse ETP substitution. +3. **Operation:** + - Best deployed via a systemd timer at 09:30 America/New_York time. ## TODOs - [x] Document the strategy logic. -- [x] Implement ATR calculation in the strategy engine. -- [x] Implement the 15m candle capture logic. -- [x] Implement the entry/exit order placement logic in the execution manager. -- [x] Create a backtesting script (optional but recommended). +- [x] Implement ATR calculation and Fibonacci targets. +- [x] Implement 15m candle capture with timezone resilience. +- [x] Implement ISA-compliant shorting via Inverse ETP mapping. +- [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). diff --git a/README.md b/README.md index 24bcd0f..8a86eeb 100644 --- a/README.md +++ b/README.md @@ -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. 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. -3. **The Trigger:** - - If the opening candle closes **Bearish** (Close < Open), the bot prepares a **LONG** entry at the candle's Low. - - If the opening candle closes **Bullish** (Close > Open), the bot prepares a **SHORT** entry at the candle's High. +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 (ISA Optimized):** + - **LONG (Bearish candle):** Bot places an immediate **Market BUY** order for the stock. + - **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:** - - **Take Profit (TP):** The 38.2% Fibonacci retracement level of the opening candle's range. - - **Stop Loss (SL):** Placed to ensure a Risk:Reward ratio of 1:2 (Risking 1 unit to make 2). -5. **Time Exit:** All open positions are forcefully closed at 11:00 EST to avoid mid-day chop. + - Brackets are placed **immediately** after the market order is filled, using the **Actual Fill Price** from your portfolio. + - **Take Profit (TP):** The 38.2% Fibonacci retracement level. + - **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 python3 -m venv venv source venv/bin/activate - ``` - -2. **Install dependencies:** - ```bash 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:** - Create a `.env` file in the root directory based on `.env.example`: +2. **Configure Environment Variables:** + Create a `.env` file in the root directory: ```ini TRADING212_API_KEY_ID=your_key_id_here TRADING212_API_KEY=your_api_key_here 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 -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. - -**Virtual Balances:** -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. +- **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. +- **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. --- -## 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`). -- **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. +1. **Scan:** Runs the ISA candidate filter to find the most volatile US stocks. +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 -* **`src/api/client.py`:** Handles REST HTTP basic authentication and request formatting for the Trading212 API. -* **`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/scanner.py`:** The ranking engine used to sort tickers by ATR volatility. -* **`src/execution/manager.py`:** Consumes the trade parameters and places the orders via the API client. +* **`src/api/client.py`:** REST API wrapper with Basic Auth. +* **`src/strategy/touch_turn.py`:** Logic engine and Fibonacci calculator. +* **`src/strategy/inverse_mapping.py`:** Map of US stocks to 3x Short Inverse ETPs. +* **`src/execution/manager.py`:** Handles market entries, actual fill-based bracketing, and ISA substitutions. +* **`main.py`:** The morning orchestrator. diff --git a/src/strategy/inverse_mapping.py b/src/strategy/inverse_mapping.py new file mode 100644 index 0000000..74998fa --- /dev/null +++ b/src/strategy/inverse_mapping.py @@ -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, +}