Capital runs 24/7 on your own machine, trades on configurable and code-defined strategies, and ships with a dark dashboard for monitoring markets, positions and PnL. It defaults to simulation — no real money moves until you explicitly opt in to Testnet or live trading behind safeguards.
⚠️ Trading involves risk. Capital is provided as-is. Run it in Sim or Testnet mode for a meaningful period before considering any live capital.
- Always-on trading — a background engine ticks every enabled strategy on a schedule, independent of whether the dashboard is open.
- Strategies your way — built-in indicator strategies (MA crossover, RSI, MACD, Bollinger breakout, DCA) plus a plugin loader for custom code strategies.
- Three modes — Simulation (paper trading on live prices) → Binance Testnet → Live, with explicit safeguards before real money is involved.
- Live market data — spot and USDⓈ-M futures prices, candlestick charts, funding rates and order-book depth.
- Honest accounting — every fill records its fee; PnL is always reported
net of fees, and money math uses
Decimalthroughout. - Capital allocation — assign a budget per strategy; the engine enforces it.
- Multi-venue — Binance (crypto), Alpaca (US stocks), Polymarket (prediction markets), behind a common venue interface.
- AI strategies — LLM-driven strategies with per-strategy model selection, daily spend caps, and a per-model performance rollup.
- Roles & audit — JWT login with
admin/userroles; config changes are recorded in an audit log.
Capital is a monorepo of two long-lived services plus a database:
┌────────────┐ REST + WebSocket ┌────────────┐
│ web │ ◀───────────────────────▶ │ engine │
│ React + UI │ │ FastAPI │
└────────────┘ │ + bot │
└─────┬──────┘
│ SQLModel
┌─────▼──────┐
│ PostgreSQL │
└────────────┘
engine/— the bot. Python 3.12 + FastAPI: market-data streams, the strategy tick loop, executors (Sim/Testnet/Live), accounting and the API.web/— the control panel. React 19 + Vite + TypeScript dark dashboard. Closing the browser never stops trading.- PostgreSQL — strategies, trades, positions, candle cache and equity history. Schema managed with Alembic migrations.
See docs/ARCHITECTURE.md for a fuller breakdown.
The fastest path is the single installer — it builds the images, starts PostgreSQL, the engine and the dashboard, and applies database migrations.
Prerequisites: Docker with the Docker Compose v2 plugin.
git clone https://github.com/FurkanEdizkan/Capital.git
cd Capital
scripts/install.shWhen it finishes:
| Service | URL |
|---|---|
| Dashboard | http://localhost:5173 |
| API + docs | http://localhost:8000/docs |
Log in with the admin credentials from .env (CAPITAL_ADMIN_USERNAME /
CAPITAL_ADMIN_PASSWORD). The installer creates .env from
.env.example on first run.
scripts/install.sh # development mode — hot reload
scripts/install.sh prod # production-style mode — built assets
docker compose logs -f # follow logs
docker compose down # stop the stack
docker compose down -v # stop and wipe the databaseAll configuration lives in .env (gitignored). Copy
.env.example and adjust:
| Variable | Purpose |
|---|---|
POSTGRES_USER / _PASSWORD / _DB |
PostgreSQL credentials |
ENGINE_PORT / WEB_PORT |
Host ports for the API and dashboard |
CAPITAL_ENVIRONMENT |
development or production |
CAPITAL_JWT_SECRET |
JWT signing secret — change this |
CAPITAL_ADMIN_USERNAME / _PASSWORD |
Seeded admin operator |
CAPITAL_STRATEGY_PLUGINS_DIR |
Where custom strategy plugins are scanned |
Market data needs no API key — Sim-mode paper trading works out of the box. Placing orders on Testnet or Live needs venue credentials, entered (encrypted) through the Settings page.
- docs/binance-setup.md — Binance (crypto)
- docs/alpaca-setup.md — Alpaca (US stocks)
- docs/polymarket-setup.md — Polymarket (prediction markets)
- docs/venue-api-features.md — what each venue API offers vs. what Capital uses
Run the stack privately over Tailscale, or on a public cloud VM with a real domain and Let's Encrypt TLS — see docs/deployment.md.
For working on a single service directly:
docker compose up -d postgres # database only
cd engine # Python engine — uses `uv`
uv sync
uv run alembic upgrade head
uv run uvicorn main:app --reload # http://localhost:8000
cd web # React dashboard
npm install
npm run dev # http://localhost:5173Drop a Python module into engine/strategies/plugins/ exposing a build()
function that returns strategy instances — the engine auto-discovers it on
startup. See engine/strategies/plugins/README.md
and the _example.py template.
Capital/
├── engine/ Python trading engine + API
│ ├── ai/ LLM provider adapters + AI strategy support
│ ├── api/ REST + WebSocket endpoints
│ ├── auth/ JWT login, roles, API tokens, audit log
│ ├── backtest/ historical backtest runner
│ ├── exchange/ Binance REST/WebSocket client
│ ├── marketdata/ candle cache + streaming
│ ├── notify/ Telegram notifications
│ ├── ops/ boot recovery, watchdog, retention
│ ├── strategies/ strategy framework, built-ins, plugin loader
│ ├── trading/ engine loop, executors, portfolio, risk, accounting
│ ├── mcp_server.py MCP server — the API as agent tools
│ └── tests/ pytest suite
├── web/ React + Vite + TypeScript dashboard
├── scripts/ install.sh, deploy.sh, backup/restore
├── caddy/ reverse-proxy config for production
├── docs/ architecture, branching, PR rules, venue setup
├── docker-compose.yml base service definitions
└── .github/ CI workflows, issue & PR templates
Contributions are welcome! Read CONTRIBUTING.md and the Code of Conduct. In short:
- Branch off
test, open PRs intotest. Never PR intomain—mainis promoted fromtestautomatically once CI is green. See docs/BRANCHING.md. - Commits follow Conventional Commits.
- Run
ruff+pytest(engine) andnpm run lint+build(web) before a PR. - PRs are merged with a merge commit — branches are kept.
Project skills (Conventional Commits, Conventional Branches, modular service design) live in the My-Skills plugin marketplace. Install once per machine:
/plugin marketplace add FurkanEdizkan/My-Skills
/plugin install skills@furkanedizkan-skillsSee AGENTS.md for the full agent guide.
Capital is designed to be navigable and contributable by AI agents:
- API — the engine serves an OpenAPI spec and interactive docs at
/docs; every endpoint is typed and authenticated. - Contribution loop — pick an issue, create a
<type>/<short-slug>branch offtest, implement with tests, open a PR withCloses #<issue>, and let CI gate the merge. This mirrors the human workflow exactly. - Conventions — Conventional Commit messages,
ruff-clean Python, hermetic tests. CI enforces all three, so a green build means the change is contract-compliant. - An MCP server (
mcp_server.py) exposes read / manage / trade tools for external agents, authenticated with role-scoped API tokens.
- Architecture — how Capital is put together
- Branching model — the
test → mainworkflow - Pull request guidelines
- Releases
- Contributing — dev setup and PR rules
- Security policy
- Agent guide
| Phase | Scope | Status |
|---|---|---|
| 0 | Scaffold, CI/CD, auth & roles | Done |
| 1 | Live market data + Markets page | Done |
| 2 | Paper-trading engine + accounting + Dashboard | Done |
| 3 | Strategy system + risk management | Done |
| 4 | Backtesting | Done |
| 5 | Live trading (Testnet → real) | Done |
| 6 | 24/7 hardening, resilience, deployment | Done |
| 7 | AI strategies + agent/MCP integration | Done |
| 8 | Multi-venue expansion (stocks, Polymarket) | Done |
Apache 2.0 © 2026 Furkan Edizkan