DOCSEARCHbyAlgolia
Submit Docs

QuantDinger Documentation

repository·main·Indexed 27 days ago

https://github.com/brokermr810/quantdinger

An open-source AI Trading OS for independent traders and small teams. QuantDinger provides a self-hosted stack for the entire trading lifecycle, including AI research, Python strategy development, backtesting, and live execution. It features integration modules for Alpaca and Interactive Brokers (IBKR), a Model Context Protocol (MCP) server (quantdinger-mcp v0.4.0) for AI agents, and a Flask-based backend API with support for Docker Compose deployment and Prometheus monitoring.

Tokens
60.1K
Snippets
128
Records
317
Agent score
95%

What's inside QuantDinger

  1. Overview of Agent-facing documentation

    main
    The docs/agent/ directory contains documentation specifically designed for coding assistants (e.g., Cursor, Claude Code, Codex) and autonomous AI agents. It provides instructions for connecting agents to the QuantDinger backend, architectural designs for agent environments, and machine-readable API contracts.

  2. Identify QuantDinger Runtime Surfaces

    main

    QuantDinger's backend is divided into several runtime surfaces depending on the interaction type. Use these paths to locate specific logic:

    • Human Web API: Web and mobile UI endpoints under /api/.... Located in backend_api_python/app/routes and app/openapi.
    • Agent Gateway: Scoped agent/MCP API under /api/agent/v1/.... Located in backend_api_python/app/routes/agent_v1.
    • Strategy Runtime: Strategy loops, signal handling, and pending order generation. Located in backend_api_python/app/services/trading_executor.py and related services.
    • Market Data: K-line, quote, symbol, fundamentals, macro, and news data. Located in backend_api_python/app/data_sources and app/data_providers.
    • Live Trading: Exchange and broker REST adapters. Located in backend_api_python/app/services/live_trading.
    • Background Workers: Pending orders, portfolio monitor, grid fill poller, and USDT watchers. Located in backend_api_python/app/startup.py and worker services.

  3. Understand the QuantDinger Multi-Agent Runtime Architecture

    main

    QuantDinger uses a three-layered architecture to ensure stability and predictability for coding agents (like Cursor, Claude Code, or Codex) working in the repository. This layered approach separates intent, local execution, and machine-driven capabilities.

    • Layer 1: Documentation contract (Intent) - Provides the repository map, 'red lines' (security boundaries), recommended workflows, and pointers to specific guides. This is the starting point for any agent to understand the repo without network calls.
    • Layer 2: Command contract (Execution) - A set of stable, documented commands (via Make, npm, or scripts) for environment setup, running the stack, quality checks (lint/test), and testing. Agents should use these instead of ad-hoc shell commands.
    • Layer 3: Machine interfaces (Capabilities) - Optional layer providing machine-consumable contracts like OpenAPI for REST APIs or MCP (Model Context Protocol) for narrow, auditable tool operations.

  4. Understand QuantDinger AI/Agent Integration Design

    main
    QuantDinger provides a stable, documented capability surface for external AI agents (P4/P5 personas) to perform research, backtesting, and supervised execution. This is achieved through a dedicated Agent Gateway (/api/agent/v1/...) that is separate from the standard Browser UI API. The design focuses on treating AI agents as first-class API consumers with strict security, least privilege, and auditability.

  5. Explore QuantDinger Architecture and Contracts

    main

    To understand the system design, dependency directions, and concurrency rules, refer to the following architectural documents:

    • Architecture: Backend ownership map and contributor design rules.
    • Module boundaries: Dependency direction and package responsibilities.
    • Concurrency model: Database, worker, and thread ownership rules.
    • Process roles: Boundaries for API, trading, scheduler, Celery, and migration.
    • API conventions: Human API envelopes, authentication, and stability classes.
    • Extension guide: Instructions for safely adding routes, services, adapters, and tasks.

  6. Identify the correct QuantDinger API surface

    main

    QuantDinger provides two distinct API surfaces depending on your integration type:

    1. Human Web API (/api/...): Designed for frontend applications (web/mobile UI) and third-party integrators. It uses user JWTs for authentication.
    2. Agent Gateway (/api/agent/v1/...): Designed for AI agents, MCP (Model Context Protocol), and automation. It uses scoped agent tokens and has a different response envelope structure.

  8. Configure network transport for QuantDinger MCP

    main

    When using network transports (sse or streamable-http) bound to a non-loopback host, you must configure a separate inbound bearer token (QUANTDINGER_MCP_AUTH_TOKEN). This token is used by clients to authenticate against the /mcp or /sse endpoints and must be different from the Agent Gateway token.

    Security Note: If you are using a private ingress that already handles authentication, you can set QUANTDINGER_MCP_ALLOW_INSECURE_HTTP=true, but never use this on a publicly reachable listener.

    export QUANTDINGER_MCP_TRANSPORT=streamable-http
export QUANTDINGER_MCP_HOST=0.0.0.0
export QUANTDINGER_MCP_PORT=7800
export QUANTDINGER_MCP_PUBLIC_URL=https://mcp.example.com
export QUANTDINGER_MCP_AUTH_TOKEN=replace-with-a-random-32-plus-character-secret
quantdinger-mcp

  9. Migrate Data from SQLite to PostgreSQL

    main

    If you are moving from a legacy SQLite-based installation to the multi-user PostgreSQL setup, use the provided migration script. You must set the DATABASE_URL environment variable pointing to your new PostgreSQL instance before running the script.

    # Set environment variables
export DATABASE_URL=postgresql://quantdinger:your_password@localhost:5432/quantdinger

# Run migration script
python scripts/migrate_sqlite_to_postgres.py

  10. Manage Strategy Source Lifecycle via Strategy API V2

    main

    Executable strategies follow the Strategy API V2 contract. You define an initialize(context) function, declare universes/subscriptions, and provide logic via handle_data, on_rebalance, or scheduled callbacks. The Agent Gateway manages the source lifecycle through the following endpoints:

    1. GET /strategy-sources/templates: List starter code.
    2. POST /strategy-sources/compile: Compile code.
    3. POST /strategy-sources: Save a private source.
    4. /strategy-sources/{source_id}: Inspect or update a source.
    5. /strategy-sources/{source_id}/versions: Review immutable snapshots.
    6. Create deployments from saved source IDs.

    To create a stopped deployment from a saved source, use POST /api/agent/v1/strategies. To update canonical fields of an existing deployment, use PATCH /api/agent/v1/strategies/{id}. Stopping a running deployment requires a T scope token via /strategies/{id}/stop.

    curl -X POST http://localhost:8888/api/agent/v1/strategies \
  -H "Authorization: Bearer $QUANTDINGER_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "spy-trend", "sourceId": 12, "initialCapital": 10000, "executionMode": "signal", "leverageEnabled": false, "params": {"lookback": 50} }'

  11. Set up a local Python development environment

    main

    To run the backend locally without Docker, ensure you have Python 3.12, PostgreSQL 18, and Redis 8 installed.

    1. Create and activate a virtual environment.
    2. Install development dependencies.
    3. Apply database migrations.
    4. Start the API.
    # Create environment and install dependencies
python -m venv .venv
python -m pip install --upgrade pip
python -m pip install -r requirements-dev.txt

# Apply migrations (Linux/macOS)
QD_PROCESS_ROLE=migration python -m app.commands.migrate

# Start the API
python run.py

  12. Authenticate with the Agent Gateway

    main

    QuantDinger provides a tenant-scoped Agent Gateway at /api/agent/v1. To authenticate, create an Agent Token via the human admin UI. Store the full token immediately as it is only shown once. Use this token as a Bearer token in your HTTP headers.

    Token Scopes:

    • R: Read access.
    • W: Write access for saved artifacts and deployment configuration.
    • B: Backtest execution.
    • T: Runtime or order mutations.

    Note: Token permissions do not bypass server-side live-trading controls.

    curl -H "Authorization: Bearer $QUANTDINGER_AGENT_TOKEN" \
  http://localhost:8888/api/agent/v1/whoami