AiTrader

Autonomous paper-trading app for Interactive Brokers Paper Trading architecture. The MVP runs end-to-end with FakeBrokerAdapter and development seed data.

Stack

• Backend: Python 3.12, FastAPI, Pydantic v2, SQLAlchemy 2, Alembic-ready models, pytest
• Package manager: uv, chosen for fast reproducible Python installs and simple Docker usage
• Frontend: Next.js App Router, TypeScript, Tailwind CSS, Recharts, Vitest
• Local infrastructure: Docker Compose with PostgreSQL
• Realtime updates: Server-Sent Events endpoint, plus dashboard polling in the MVP
• Broker integration: ib_async 2.1.0 for Interactive Brokers Paper through TWS or IB Gateway

Start Locally

cp .env.example .env
docker compose up --build

Open:

• Frontend: http://localhost:3000/dashboard
• Backend health: http://localhost:8000/api/health

Run tests locally:

cd backend
uv pip install --system ".[dev]"
alembic upgrade head
python -m app.cli seed
pytest

cd ../frontend
npm install
npm run lint
npm run typecheck
npm test
npm run build

Useful database commands:

cd backend
alembic upgrade head
python -m app.cli seed
alembic downgrade base
alembic upgrade head
psql postgresql://aitrader:aitrader@localhost:5432/aitrader

IBKR read-only smoke:

cd backend
BROKER_PROVIDER=ibkr_paper
IBKR_ACCOUNT_ID=DU...
IBKR_READ_ONLY=true
python -m app.cli ibkr-smoke

Execution smoke remains explicitly gated:

IBKR_READ_ONLY=false
IBKR_ALLOW_PAPER_EXECUTION=true
IBKR_ALLOW_EXECUTION_SMOKE=true
MAX_ORDER_AMOUNT=100
python -m app.cli ibkr-execution-smoke --confirm "PAPER ORDER"

IBKR_ALLOW_PAPER_EXECUTION defaults to false and must stay false for read-only smoke tests. Set it to true only after TWS/Gateway paper-account verification passes and only for deliberate paper execution testing.

Safety

This repository is paper-only. The normal UI has no live trading switch. Orders are never placed directly by AI code; every decision passes schema validation, data freshness checks, risk evaluation, order proposal creation, idempotency and broker adapter execution. Runtime domain state is persisted in PostgreSQL through SQLAlchemy/Alembic; normal startup does not create tables silently.

No secrets are committed. Keep .env local, set OPENAI_API_KEY and broker values through environment variables only, and rotate any key that was ever stored in a local .env before publishing the repository. Production startup refuses the default LOCAL_AUTH_PASSWORD.