Arbitrade

Low-latency cryptocurrency arbitrage bot scaffold for Kraken.

Current stack:

• 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

Project plan lives in PLAN.md. Task checklist lives in .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:

git clone https://git.allucanget.biz/allucanget/arbitrade.git
Set-Location arbitrade

If repo already exists locally, confirm remote:

git remote -v

Expected origin:

https://git.allucanget.biz/allucanget/arbitrade.git

Local Development Setup

Create virtualenv with uv:

uv venv

Activate env on Windows:

.\.venv\Scripts\Activate.ps1

Install app + dev dependencies:

uv pip install -e .[dev]

Create local env file:

Copy-Item .env.example .env

Minimum .env values:

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:

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:

./data/arbitrade.duckdb

Schema bootstrap runs automatically on app startup.

Current tables:

• schema_migrations
• opportunities
• trades
• portfolio_snapshots

Quality Checks

Run tests:

pytest -q

Run Ruff:

ruff check .

Run Black check:

black --check .

Run mypy:

mypy src

Install pre-commit hooks:

pre-commit install

Run hooks manually:

pre-commit run --all-files

Docker

Build locally:

docker build -t arbitrade:local .

Run with compose:

docker compose up --build

Compose mounts local data/ folder into container at /app/data.

Important:

• 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

Required Gitea Actions secrets:

• REGISTRY_USERNAME
• REGISTRY_TOKEN
• REGISTRY_NAMESPACE

Expected namespace now likely:

allucanget

Example registry login:

docker login git.allucanget.biz

Example pushed image tag shape:

git.allucanget.biz/allucanget/arbitrade:<tag>

Project Layout

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:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned

Then activate again:

.\.venv\Scripts\Activate.ps1

If app import fails, confirm editable install ran:

uv pip install -e .[dev]

If DuckDB file missing, start app once or create data/ directory manually.