Skip to content

Getting Started

This guide gets the QGTMAI paper-first precious-metals stack running locally.

Prerequisites

Tool Version Install
Python 3.12+ python.org or brew install python@3.12
uv latest curl -LsSf https://astral.sh/uv/install.sh \| sh
Docker 24+ docker.com
Git 2.40+ brew install git
Node.js 20+ brew install node

1. Clone and Install

git clone https://github.com/QGTMAI/trading.git
cd trading
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

2. Configure Environment

cp .env.example .env

Fill in the minimum required values:

  • ALPACA_API_KEY
  • ALPACA_SECRET_KEY
  • REDIS_URL for local Redis or your chosen runtime
  • any optional data-provider keys you want to exercise in development

For local work, keep the stack paper-first.

3. Start Local Infrastructure

docker compose -f infra/compose/docker-compose.yml up -d

This boots the local support services used by the repo, including Redis and the default local data services defined in compose.

4. Run the Test Suite

pytest

The repo has a large automated suite. If tests fail immediately, check Docker, environment variables, and any required external API credentials.

5. Start the API

uvicorn qgtm_api.main:app --reload --port 8000

Interactive docs:

6. Verify the Runtime

curl http://localhost:8000/health | python -m json.tool
curl http://localhost:8000/api/v1/universe | python -m json.tool

Expected behavior:

  • /health returns status: ok
  • /api/v1/universe returns the PM-focused default universe (20 instruments)
  • pass focus=broad if you want the broader legacy commodity universe (44 instruments)

7. Optional Frontend Work

The repo also contains the QGTMAI terminal frontend in qgtm_web/. Start it with the package-manager flow used by that app when you want to iterate on the web terminal alongside the API.

Next Steps