jerick/crypto-trader
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
jerick
2026-05-03 23:37:55 -04:00
commit 8b96dd1465
18 changed files with 1048 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

140
README.md Normal file
View File

@@ -0,0 +1,140 @@
# crypto-trader
A Python trading bot for [Kraken](https://www.kraken.com) that identifies momentum opportunities and manages positions with automated risk controls.
## Strategy
Each run the bot:
1. **Checks open positions** — evaluates every held asset against the exit rules below and sells if triggered.
2. **Scans the market** — fetches all USD-quoted pairs on Kraken and filters to assets with:
- 24h traded volume ≥ $1,000,000 (confirms the asset is liquid and active)
- 24h price change between **+5% and +10%** (momentum window — enough movement, not yet overextended)
3. **Buys qualifying assets** — splits available USD balance equally across the top results (sorted by volume), up to `max_positions` concurrent holdings.
4. **Re-scans if a position closed** — freed capital is immediately put to work in the same run.
## Risk management
Exit rules are checked in priority order on every run:
| Rule | Default | Behaviour |
|------|---------|-----------|
| Hard stop-loss | −12% from entry | Absolute floor. Protects against a gap-down before the trailing stop can react. |
| Trailing stop | −8% from peak | Follows the price upward. If an asset goes $100 → $130, the stop sits at $119.60. A reversal to $119.60 triggers a sell. |
| Take profit | +25% from entry | Locks in gains when the target is reached. |
| Time limit | 72 hours | Exits stagnant positions so capital isn't tied up indefinitely. |
All thresholds are in [`config.py`](config.py) and can be tuned without touching any other file.
## Requirements
- Python 3.8 or newer
- A Kraken account with an API key that has **Query Funds**, **Query Open Orders & Trades**, and **Create & Modify Orders** permissions
## Setup
### Local / manual use
```bash
# Clone and enter the directory
git clone <your-repo-url> crypto-trader
cd crypto-trader
# Create virtual environment and install dependencies
bash setup.sh
# Add your Kraken API keys
nano .env
```
### Ubuntu server (systemd — runs automatically on schedule)
```bash
sudo bash install.sh
sudo nano /opt/crypto-trader/.env # add API keys
```
The installer copies the project to `/opt/crypto-trader`, creates a dedicated `crypto-trader` system user, and registers a systemd timer that runs at **09:00, 13:00, and 17:00 UTC** daily.
## Running
```bash
# Paper trading (no real orders — safe to run any time)
./venv/bin/python bot.py
# Live trading (real orders placed on Kraken)
./venv/bin/python bot.py --live
```
Always verify paper trading behaviour for at least one full cycle before switching to live mode.
## Configuration
All settings live in [`config.py`](config.py). The most commonly tuned values:
| Setting | Default | Description |
|---------|---------|-------------|
| `min_volume_usd` | 1,000,000 | Minimum 24h USD volume to consider an asset |
| `min_price_change_pct` | 5.0 | Lower bound of the momentum window (%) |
| `max_price_change_pct` | 10.0 | Upper bound of the momentum window (%) |
| `max_positions` | 5 | Maximum concurrent holdings |
| `trailing_stop_pct` | 8.0 | Sell if price drops this % below its peak |
| `hard_stop_pct` | 12.0 | Sell if price drops this % below entry |
| `take_profit_pct` | 25.0 | Sell when this % profit is reached |
| `max_hold_hours` | 72 | Exit after this many hours regardless |
| `paper_trading` | True | Set to False for live orders |
## Scheduling
**Systemd (Ubuntu server):**
```bash
sudo systemctl start crypto-trader.timer # enable schedule
systemctl list-timers crypto-trader.timer # show next run time
journalctl -u crypto-trader.service -f # stream logs
sudo systemctl start crypto-trader.service # trigger a manual run
```
To change the schedule, edit [`systemd/crypto-trader.timer`](systemd/crypto-trader.timer) then:
```bash
sudo systemctl daemon-reload
sudo systemctl restart crypto-trader.timer
```
**Cron (alternative):**
```bash
crontab -e
# Add one or more lines, e.g. run at 09:00, 13:00, 17:00 UTC:
0 9,13,17 * * * /opt/crypto-trader/venv/bin/python /opt/crypto-trader/bot.py >> /opt/crypto-trader/bot.log 2>&1
```
## Project structure
```
crypto-trader/
├── bot.py # Entry point — orchestrates each trading cycle
├── config.py # All tunable parameters
├── kraken_client.py # Kraken REST API client (auth, tickers, orders)
├── scanner.py # Scans market, filters by volume and price change
├── portfolio.py # Tracks open positions, persists to positions.json
├── risk_manager.py # Trailing stop, hard stop, take profit, time limit
├── setup.sh # One-time local setup (venv + deps)
├── install.sh # Full Ubuntu server install with systemd
├── systemd/
│ ├── crypto-trader.service # Systemd service unit
│ └── crypto-trader.timer # Systemd timer unit
├── requirements.txt
└── .env.example
```
## State and logs
- **`positions.json`** — open positions, updated after every buy or sell. Safe to inspect at any time.
- **`bot.log`** — full run history including every scan result, order placed, and exit reason.
- On Ubuntu with systemd: `journalctl -u crypto-trader.service` also captures all output.
## Disclaimer
This software is provided for educational purposes. Cryptocurrency trading carries significant financial risk. Always test thoroughly in paper trading mode before risking real funds. You are solely responsible for any trading decisions made by this bot.