maxbot/README.md

# TSLA Grid Trading Bot — Capital.com

A grid/mean-reversion trading bot for Tesla (TSLA) CFDs on Capital.com.
Runs on Ubuntu server. Written in Python 3.

---

## How the strategy works

The bot places limit buy orders at regular intervals **below the current price**.
When TSLA dips, orders fill automatically. Each position has a take profit set
to return a fixed GBP amount. Positions close automatically at take profit.

- Many small £1.00 profits compound over time
- Deeper dips = more positions open = more profit potential on recovery
- Grid self-adjusts as equity grows (tighter spacing = more frequent fills)
- Designed to survive a 60% drop from highest open position (builds toward this)

---

## Project structure

```
maxbot/
  bot.py         Main entry point — run this
  config.py      ALL settings — edit this for day-to-day changes
  client.py      Capital.com API calls
  state.py       Account state snapshot + field access helpers
  calculator.py  Grid maths, survival check, gap detection
  grid.py        Order management (gap-filling, TP rules)
  actions.py     dry/confirm/live action handler
  bot.log        Activity log (auto-created on first run)
  README.md      This file
```

**When making changes:** each file has one job. Bug in order placement → `grid.py`.
Change a setting → `config.py`. API field name changed → `client.py` and `state.py`.

---

## Setup

### 1. Requirements

Python 3.8+ and requests:
```bash
pip install requests --break-system-packages
```

### 2. Capital.com API key

1. Log into Capital.com
2. Go to **Settings → API integrations**
3. Enable 2FA if not already done (required for API key)
4. Generate API key

### 3. Set credentials as environment variables

```bash
# Add to ~/.bashrc so they persist across reboots
echo 'export CAPITAL_API_KEY="your_key_here"' >> ~/.bashrc
echo 'export CAPITAL_IDENTIFIER="your@email.com"' >> ~/.bashrc
echo 'export CAPITAL_PASSWORD="your_password_here"' >> ~/.bashrc
source ~/.bashrc
```

### 4. Verify credentials work

```bash
cd ~/maxbot
python3 bot.py --mode dryrun
```

Should connect, read your positions and orders, print the audit. No actions taken.

---

## Running the bot

### Step 1 — Dry run (safe, always start here)
```bash
python3 bot.py --mode dryrun
```
Reads everything, prints what it would do. Zero actions. Run this first.

### Step 2 — Confirm mode (approve each action)
```bash
python3 bot.py --mode confirm
```
Asks `y/n` before every order placement, cancellation, or TP change.
Run this for several days until you trust the behaviour completely.

### Step 3 — Live mode (autonomous)
```bash
python3 bot.py --mode live
```
Fully autonomous. Only switch here after thorough testing.

---

## Running as a system service (auto-start on boot)

### Create the service file

```bash
sudo nano /etc/systemd/system/maxbot.service
```

Paste this (adjust paths/credentials):

```ini
[Unit]
Description=TSLA Grid Trading Bot
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
User=george
WorkingDirectory=/home/george/maxbot
Environment=CAPITAL_API_KEY=your_key_here
Environment=CAPITAL_IDENTIFIER=your@email.com
Environment=CAPITAL_PASSWORD=your_password_here
ExecStart=/usr/bin/python3 /home/george/maxbot/bot.py --mode live
Restart=always
RestartSec=30

[Install]
WantedBy=multi-user.target
```

### Enable and start

```bash
sudo systemctl daemon-reload
sudo systemctl enable maxbot
sudo systemctl start maxbot
```

### Check status and logs

```bash
sudo systemctl status maxbot          # current status
sudo journalctl -u maxbot -f          # live systemd logs
tail -f ~/maxbot/bot.log              # bot's own log file
```

### Stop / restart

```bash
sudo systemctl stop maxbot
sudo systemctl restart maxbot
```

---

## Day-to-day configuration

**All settings are in `config.py`.** Common changes:

### Increase survival threshold as equity grows

```python
# In config.py — increase this as equity grows:
SURVIVAL_DROP_PCT = 30.0   # current (£640 equity)
# → 35.0  at £900
# → 40.0  at £1200
# → 50.0  at £1500
# → 60.0  at £1800 (target)
```

### Adjust queue depth

```python
QUEUE_DEPTH = 10  # default
```

### Toggle demo mode for testing

```python
USE_DEMO = True   # points to demo.capital.com
```

---

## Margin call stages (Capital.com UK retail)

| Margin level | What happens |
|---|---|
| > 100% | Normal — bot operates |
| ≤ 100% | Warning 1 — bot stops placing new orders |
| ≤ 75%  | Warning 2 — urgent alert in logs |
| ≤ 50%  | Auto closeout — Capital.com closes positions |

---

## Planned future enhancements

- [ ] Telegram alerts — ping on fills, closures, margin warnings
- [ ] Profit tracker — log every closed position, running total
- [ ] Automatic survival threshold stepping (reads equity, updates config)
- [ ] Claude AI integration — consult Claude on edge cases
- [ ] Web dashboard — view positions and grid on homelab browser