diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml index c6aa42b..c009ed3 100644 --- a/.gitea/workflows/ci.yml +++ b/.gitea/workflows/ci.yml @@ -41,8 +41,8 @@ jobs: uses: docker/login-action@v3 with: registry: git.allucanget.biz - username: ${{ secrets.GITEA_REGISTRY_USERNAME }} - password: ${{ secrets.GITEA_REGISTRY_TOKEN }} + username: ${{ secrets.REGISTRY_USERNAME }} + password: ${{ secrets.REGISTRY_TOKEN }} - name: Build and push image if: github.event_name != 'pull_request' @@ -50,4 +50,4 @@ jobs: with: context: . push: true - tags: git.allucanget.biz/${{ secrets.GITEA_REGISTRY_NAMESPACE }}/arbitrade:${{ github.sha }} + tags: git.allucanget.biz/${{ secrets.REGISTRY_NAMESPACE }}/arbitrade:${{ github.sha }} diff --git a/README.md b/README.md index 81c2cdd..a7d0fc8 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,284 @@ -# Arbitrage Trading Bot +# Arbitrade -## Objective +Low-latency cryptocurrency arbitrage bot scaffold for Kraken. -- Develop an arbitrage trading bot that can identify and exploit price discrepancies across different currency pairs to generate profits. -- Ensure the bot operates efficiently, securely, and can adapt to changing market conditions. -- Implement risk management strategies to minimize potential losses. -- Continuously monitor and optimize the bot's performance. -- Provide a user-friendly interface for monitoring and controlling the bot's operations. -- Integrate with kraken exchange for executing trades and accessing market data. -- Implement a robust logging and alerting system to track the bot's activities and notify the user of important events or issues. +Current stack: -## Key Features +- Python 3.12+ +- FastAPI + HTMX/Jinja2 +- DuckDB for dev/test/prod +- Native Kraken WebSocket planned for market-data hot path +- Gitea Actions + Gitea container registry -1. **Market Data Collection**: The bot will collect real-time market data, including price, volume, and order book information. -2. **Price Discrepancy Detection**: The bot will analyze the collected data to identify price discrepancies between currency pairs across different cryptocurrencies and fiat currencies. -3. **Trade Execution**: The bot will execute trades automatically when a profitable arbitrage opportunity is detected, ensuring that it can capitalize on the price differences before they disappear. -4. **Risk Management**: The bot will implement risk management strategies, such as setting stop-loss orders and limiting the amount of capital allocated to each trade, to minimize potential losses. -5. **Performance Monitoring**: The bot will continuously monitor its performance, tracking metrics such as profit and loss, win rate, and average trade duration, to identify areas for improvement. -6. **User Interface**: The bot will provide a user-friendly interface that allows users to monitor the bot's activities, view performance metrics, and control its operations. -7. **Integration with Kraken Exchange**: The bot will integrate with the Kraken exchange to access market data and execute trades, ensuring that it can operate effectively in the cryptocurrency market. -8. **Logging and Alerting System**: The bot will implement a robust logging system to track all activities and transactions, and an alerting system to notify the user of important events, such as successful trades, errors, or significant market changes. -9. **Security Measures**: The bot will implement security measures to protect user data and prevent unauthorized access, including encryption of sensitive information and secure authentication methods. +Project plan lives in [PLAN.md](PLAN.md). +Task checklist lives in [.github/instructions/TODO.md](.github/instructions/TODO.md). + +## Current Status + +Bootstrap complete for foundation layer: + +- repo initialized +- typed settings and env loading +- structured logging +- encrypted secret helpers +- DuckDB connection + base schema +- FastAPI app with health endpoint +- Gitea Actions CI scaffold +- Docker / docker-compose scaffold + +Not implemented yet: + +- Kraken REST client +- Kraken native WebSocket client +- arbitrage detection engine +- trade execution +- dashboard beyond health/bootstrap page + +## Prerequisites + +- Python 3.12+ +- `uv` for env/package management +- Git +- Docker Desktop or Docker Engine +- Gitea account on `git.allucanget.biz` for push/CI/registry access + +Optional: + +- PowerShell 7 on Windows + +## Repository Setup + +Clone repo: + +```powershell +git clone https://git.allucanget.biz/allucanget/arbitrade.git +Set-Location arbitrade +``` + +If repo already exists locally, confirm remote: + +```powershell +git remote -v +``` + +Expected origin: + +```text +https://git.allucanget.biz/allucanget/arbitrade.git +``` + +## Local Development Setup + +Create virtualenv with `uv`: + +```powershell +uv venv +``` + +Activate env on Windows: + +```powershell +.\.venv\Scripts\Activate.ps1 +``` + +Install app + dev dependencies: + +```powershell +uv pip install -e .[dev] +``` + +Create local env file: + +```powershell +Copy-Item .env.example .env +``` + +Minimum `.env` values: + +```env +APP_ENV=dev +APP_HOST=0.0.0.0 +APP_PORT=8000 +LOG_LEVEL=INFO +LOG_JSON=true +DUCKDB_PATH=./data/arbitrade.duckdb +FERNET_KEY= +KRAKEN_API_KEY= +KRAKEN_API_SECRET= +``` + +Notes: + +- Leave Kraken creds empty until Kraken integration lands. +- `FERNET_KEY` optional. If empty, keyring-backed key generation used by secret helper. +- On Windows, app falls back to default `asyncio` loop. On non-Windows, `uvloop` installs automatically. + +## Run App + +Start app: + +```powershell +python -m arbitrade.main +``` + +Health endpoints: + +- HTML: `http://localhost:8000/` +- JSON: `http://localhost:8000/health` + +## Database + +DuckDB used everywhere: local dev, tests, production. + +Default database file: + +```text +./data/arbitrade.duckdb +``` + +Schema bootstrap runs automatically on app startup. + +Current tables: + +- `schema_migrations` +- `opportunities` +- `trades` +- `portfolio_snapshots` + +## Quality Checks + +Run tests: + +```powershell +pytest -q +``` + +Run Ruff: + +```powershell +ruff check . +``` + +Run Black check: + +```powershell +black --check . +``` + +Run mypy: + +```powershell +mypy src +``` + +Install pre-commit hooks: + +```powershell +pre-commit install +``` + +Run hooks manually: + +```powershell +pre-commit run --all-files +``` + +## Docker + +Build locally: + +```powershell +docker build -t arbitrade:local . +``` + +Run with compose: + +```powershell +docker compose up --build +``` + +Compose mounts local `data/` folder into container at `/app/data`. + +Important: + +- [docker-compose.yml](docker-compose.yml) still uses registry image placeholder format. +- Replace `git.allucanget.biz/OWNER/arbitrade:latest` with actual namespace image, likely `git.allucanget.biz/allucanget/arbitrade:latest`. + +## Gitea CI / Registry Setup + +CI file: + +- [.gitea/workflows/ci.yml](.gitea/workflows/ci.yml) + +Required Gitea Actions secrets: + +- `REGISTRY_USERNAME` +- `REGISTRY_TOKEN` +- `REGISTRY_NAMESPACE` + +Expected namespace now likely: + +```text +allucanget +``` + +Example registry login: + +```powershell +docker login git.allucanget.biz +``` + +Example pushed image tag shape: + +```text +git.allucanget.biz/allucanget/arbitrade: +``` + +## Project Layout + +```text +arbitrade/ +├── .gitea/workflows/ci.yml +├── .github/instructions/TODO.md +├── PLAN.md +├── pyproject.toml +├── src/arbitrade/ +│ ├── api/ +│ ├── config/ +│ ├── storage/ +│ ├── logging_setup.py +│ └── main.py +├── tests/ +└── web/templates/ +``` + +## Next Work + +Next planned implementation slice: + +- Kraken REST client skeleton +- native Kraken WebSocket client +- in-memory order book cache +- latency instrumentation + +## Troubleshooting + +PowerShell blocks activation script: + +```powershell +Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned +``` + +Then activate again: + +```powershell +.\.venv\Scripts\Activate.ps1 +``` + +If app import fails, confirm editable install ran: + +```powershell +uv pip install -e .[dev] +``` + +If DuckDB file missing, start app once or create `data/` directory manually.