# TradingBot
A research and development trading bot framework (backtesting + live runners). This repository contains code for strategy development, backtesting, and connecting to exchanges/telegram for notifications. It is provided for educational and research purposes only.
IMPORTANT LEGAL NOTICE — READ CAREFULLY
- This project is NOT financial, investment, tax, or legal advice.
- The author and contributors are NOT responsible for any losses, damages, or legal consequences arising from use of this software.
- Use of this software to trade real funds may be regulated in your jurisdiction. You are solely responsible for ensuring compliance with all local laws, exchange terms of service, and licensing requirements.
- Always consult a qualified legal and financial professional before using this software with real money.
- Test thoroughly in a simulated or paper trading environment before any live deployment.
Quick summary
- Language: Python
- Purpose: Strategy development, backtesting, and optional live trading
- Intended audience: developers and researchers who understand trading risks
- Safety stance: Designed to be used with caution. The user is responsible for all trading decisions.
Repository overview (key files and purpose)
- Dockerfile — container instructions for running the project
- requirements.txt — required Python packages
- backtest.py — top-level backtesting utility (historical simulation)
- src/
- __init__.py
- config.py — configuration and environment variable handling (read this before running)
- dashboard.py — visualization/dashboard utilities
- exchange.py — exchange integration layer (contains exchange API interactions; read and secure!)
- indicators.py — technical indicator implementations
- loggins_utils.py — logging helpers
- risk.py — risk management helpers
- runner.py — core run loop / orchestration logic
- runner_backtest.py — backtesting runner
- runner_live.py — live trading runner (use with extreme caution)
- signals.py — signal generation utilities
- state.py — persistent state handling
- storage.py — data persistence / saving
- telegram_client.py — Telegram notifications client
- strategy/ — strategies (place your strategy implementations here)
Getting started (recommended safe path)
1. Inspect code and configuration
- Read src/config.py and src/exchange.py carefully. Understand how API keys and requests are made.
- Make sure no sensitive credentials are committed to the repo (there are none in version control by design).
2. Install dependencies (use virtualenv)
- python3 -m venv venv
- source venv/bin/activate
- pip install -r requirements.txt
3. Backtest first (paper/simulated)
- Use backtest.py or src/runner_backtest.py to run historical simulations.
- Confirm strategy behavior, risk parameters, and edge cases on historical data.
- Do not assume backtest results will reflect live outcomes.
4. Paper-trade / simulated live
- If you need near-live validation, use a paper trading environment or exchange sandbox.
- Never point a live runner at a production account until you fully understand and accept the risks.
5. Live trading (explicit caution)
- If you decide to run src/runner_live.py, make sure:
- You understand the code paths that execute orders (exchange.py).
- All API keys are stored securely (environment variables, secret manager).
- Safety limits are implemented (max position size, max order per minute, kill-switch, circuit breakers).
- You have monitoring and alerts (telegram_client.py can help).
- Start with minimal capital and small orders if you choose to test live.
Configuration and secrets
- Do NOT commit API keys, secrets, or credentials.
- Use environment variables or an external secrets manager. Check src/config.py to see supported variables.
- Example environment variables (do NOT hardcode):
- EXCHANGE_API_KEY
- EXCHANGE_API_SECRET
- TELEGRAM_BOT_TOKEN
- TELEGRAM_CHAT_ID
Security and best practices
- Perform a security review of all dependencies (requirements.txt).
- Run the bot behind reliable monitoring and logging.
- Rate-limit exchange calls and handle API errors and edge cases.
- Implement strict error handling and fail-safe defaults (do not retry dangerously on uncertain states).
- Maintain a manual kill-switch or emergency stop mechanism.
Compliance and responsible use
- Confirm whether algorithmic trading requires registration, licensing, or reporting where you live.
- Abide by the exchange’s API terms of service and rate limits.
- Ensure customer-protection or compliance measures if this is used for third-party funds.
Testing
- Write unit tests for strategy logic and risk functions.
- Use integration tests for exchange adapters but only against sandbox/paper environments.
- Validate behavior for partial fills, slippage, and connectivity loss.
Contributing
- Contributions are welcome but please:
- Do not add real credentials.
- Keep changes focused and documented.
- Open issues for bugs or feature requests and propose PRs with tests when possible.
Licensing
- There is no license file in this repository by default. Consider adding an explicit license file (for example, MIT, Apache 2.0) and consult legal counsel to choose one appropriate for you.
- A license does not remove the need for the above legal disclaimers or compliance with local laws.
Adding a README checklist (for maintainers)
- Add LICENSE file with chosen license.
- Add a SECURITY.md describing how to report vulnerabilities.
- Add examples for backtest and runner invocations with sample config (without secrets).
- Add CONTRIBUTING.md with guidelines for safe code changes.
Contact and support
- This repository is maintained by the owner. For questions about code, open a GitHub issue or PR.
- For legal or financial advice, consult a licensed professional.
Final note
This README intentionally emphasizes safety, compliance, and the experimental nature of algorithmic trading tools. It is written so the repository can be used for development and learning while making clear that the user assumes all operational, financial, and legal responsibilities.