Agent66

Agent66 is a paper-first trading monorepo with a React workstation, a compatibility Express API, a hardened FastAPI control plane, a protected historical data service, and realistic execution and backtesting engines. Use this README as the top-level map for local development and safe operations.

flowchart LR
  UI["React UI<br/>smc_trading_agent/src<br/>port 5173"] --> EXPRESS["Express compatibility API<br/>smc_trading_agent/server<br/>port 3002"]
  UI --> V1["FastAPI v1 control plane<br/>smc_trading_agent/v1<br/>port 9000"]
  V1 --> DB["SQLite in development<br/>durable database for live"]
  V1 --> LEGACY["Legacy market-data adapter<br/>/api/trading read surface"]
  HIST["Historical data API<br/>historical_data/api.py<br/>port 8000"] --> STORE["OHLCV storage, validation,<br/>export, and coverage status"]
  BACK["Execution and backtesting<br/>execution/ + backtesting/"] --> V1

Loading

What stays canonical

• Trading write traffic goes to /api/v1/*.
• The legacy Express layer keeps compatibility and read-oriented routes.
• Live trading stays gated behind v1 policy, approvals, idempotency, and freshness checks.
• Historical data is a separate FastAPI service with its own auth and rate limit guardrails.

Quick start

Run these commands from the repository root unless a step says otherwise.

1. Install Python and web dependencies.

   pip install -r requirements.txt
   pip install -r smc_trading_agent/requirements.txt
   npm install --prefix smc_trading_agent

2. Start the React frontend.

   cd smc_trading_agent
   npm run client:dev

3. Start the compatibility Express server.

   cd smc_trading_agent
   npm run server:dev

4. Start the FastAPI v1 control plane.

   AGENT66_V1_PORT=9000 PYTHONPATH=. python -m smc_trading_agent.v1.run

5. Start the historical data API when you need query, export, or backfill flows.

   uvicorn historical_data.api:app --reload --port 8000

6. Verify the core runtime surfaces.

   curl http://localhost:3002/api/health
   curl http://localhost:9000/api/v1/health
   curl http://localhost:8000/health

Runtime map

Surface	Start command	Default port	Purpose
React UI	cd smc_trading_agent && npm run client:dev	5173	Operator UI and routing
Express compatibility API	cd smc_trading_agent && npm run server:dev	3002	Read-heavy routes, market data bridge, degraded fallback
FastAPI v1	AGENT66_V1_PORT=9000 PYTHONPATH=. python -m smc_trading_agent.v1.run	9000	Canonical trading control plane
Historical data API	uvicorn historical_data.api:app --reload --port 8000	8000	OHLCV query, fetch, validation, export

Repository map

Path	Role
smc_trading_agent/	Main application package
smc_trading_agent/v1/	Canonical FastAPI control plane
historical_data/	Historical OHLCV API and worker integration
execution/	Order orchestration, risk, and simulated execution
backtesting/	Realistic backtesting and validation
docs/	Repo-level runbooks, deployment notes, and archive index
tests/	Root integration and regression suites

Documentation paths

Start with these pages:

• smc_trading_agent/docs/DOCUMENTATION_INDEX.md
• docs/README.md
• ARCHITECTURE.md
• CONTRIBUTING.md
• docs/runbooks/README.md

Safety and operations

• Trade writes require Authorization, Idempotency-Key, and X-Market-Data-Age-Seconds.
• Live-gated operations also require X-Live-Approval-Token.
• FastAPI v1 runs reconciliation and invariant checks on startup and can keep the API in degraded mode if initialization fails.
• The Express layer can still start when PostgreSQL is unavailable, but it reports a degraded database state.

Verification slice

Use these checks before you trust a local environment:

pytest -q smc_trading_agent/v1/tests historical_data/tests
pytest -q execution/tests
pytest -q backtesting/tests