botf

Crypto trading bot — algorithmic OHLCV signals + LLM news sentiment, strict risk controls.

---

How it works

news feed ──► LLM sentiment ──► ┐
                                 ├──► signal bus ──► risk manager ──► order manager ──► Binance
  OHLCV feed ──► algorithm ──► ─┘

Two layers, two strict rules:

• LLM (Claude Sonnet) — reads only raw news text. Never sees prices.
• Algorithm — reads only candlestick (OHLCV) data. Never reads news text.

Both produce independent signals that are merged by the signal bus before any order decision.

---

Stack

Concern	Technology
Language	Python 3.11+, asyncio
Package manager	uv
Exchange	ccxt / Binance
LLM	Anthropic Claude Sonnet
Time-series DB	PostgreSQL 16 + TimescaleDB
Cache / pub-sub	Redis 7
Config	Pydantic Settings
Logging	structlog (JSON in prod, pretty in TTY)
Linting	Ruff
Scripts	pnpm

---

Quick start

Prerequisites

• Python 3.11+
• uv — curl -LsSf https://astral.sh/uv/install.sh | sh
• pnpm — npm i -g pnpm
• Docker + Docker Compose

1. Clone and configure

git clone https://github.com/karadyaur/botf.git
cd botf
pnpm setup          # copies .env.example → .env and runs uv sync

Edit .env and fill in your keys:

ANTHROPIC_API_KEY=sk-ant-...
BINANCE_API_KEY=...
BINANCE_SECRET_KEY=...

2. Start infrastructure

pnpm docker:up      # PostgreSQL 16 + TimescaleDB + Redis 7

3. Run the bot

pnpm dev            # debug logging
pnpm start          # info logging

---

Configuration

All config lives in .env. Key variables:

Variable	Default	Description
ANTHROPIC_API_KEY	—	Claude API key
BINANCE_API_KEY	—	Binance API key
BINANCE_SECRET_KEY	—	Binance secret
BINANCE_ENV	testnet	testnet or mainnet
SYMBOLS	BTC/USDT,ETH/USDT	Comma-separated pairs
RISK_PER_TRADE	0.01	Max risk per trade (1% = 0.01)
TRADING_MODE	dry_run	dry_run or live
LOG_LEVEL	INFO	DEBUG / INFO / WARNING / ERROR

Note: TRADING_MODE=live + BINANCE_ENV=mainnet places real orders. Double-check before flipping.

---

Scripts

pnpm setup          # first-time: copy .env + install deps
pnpm start          # run bot (INFO logging)
pnpm dev            # run bot (DEBUG logging)

pnpm docker:up      # start containers
pnpm docker:down    # stop containers
pnpm docker:reset   # wipe volumes + restart
pnpm docker:logs    # stream container logs

pnpm up             # docker:up + start
pnpm reset          # docker:reset + start

pnpm lint           # ruff check
pnpm format         # ruff format
pnpm check          # lint + format check (CI)
pnpm test           # pytest

---

Risk rules

• Position size is derived from distance to stop, not a fixed lot.
• Risk per trade is capped at 1–2% of capital (RISK_PER_TRADE).
• Stop-loss is placed at entry and never moved into the loss zone.
• Every decision (signal, risk check, order) is written to structured logs with a reason field.

---

Project structure

botf/
├── .env.example          # all required env vars
├── config.py             # Pydantic Settings, DSN helpers
├── main.py               # asyncio entry point + graceful shutdown
├── docker-compose.yml    # PostgreSQL + TimescaleDB + Redis
├── pyproject.toml        # dependencies (uv)
├── package.json          # convenience scripts (pnpm)
└── CLAUDE.md             # architecture guide for AI assistants

---

Status

Early skeleton — infrastructure and config only. No trading logic yet.

Component	Status
Config + env	✅
Docker infra	✅
Asyncio loop + shutdown	✅
OHLCV feed	🔜
LLM sentiment	🔜
Signal bus	🔜
Risk manager	🔜
Order manager	🔜
Backtesting	🔜

---

License

MIT