QuantDinger

<div align="center">
  <a href="https://github.com/OpenByteInc/QuantDinger">
    <img src="docs/screenshots/logo.png" alt="QuantDinger logo" width="420">
  </a>

  <h1>QuantDinger</h1>
  <p><strong>Open-source AI Trading OS</strong></p>
  <p>Turn trading ideas into Python strategies, backtests, paper trading, live execution, and monitoring — all in one self-hosted stack.</p>
  <p><strong>QuantDinger is a product of Open Byte Inc.</strong></p>
  <p><em>AI research → Strategy code → Backtest → Paper/Live execution → Monitoring</em></p>

  <p>
    <a href="README.md"><strong>English</strong></a>
    ·
    <a href="README_CN.md"><strong>简体中文</strong></a>
    ·
    <a href="docs/api/README.md"><strong>API</strong></a>
    ·
    <a href="docs/agent/README.md"><strong>AI Agents & MCP</strong></a>
  </p>

  <p>
    <a href="https://ai.quantdinger.com"><strong>Live App</strong></a>
    ·
    <a href="https://www.quantdinger.com"><strong>Website</strong></a>
    ·
    <a href="#watch-quantdinger-in-action"><strong>Video Demo</strong></a>
    ·
    <a href="mailto:support@quantdinger.com"><strong>Official Support Email</strong></a>
  </p>

  <p>
    <a href="https://t.me/quantdinger"><img src="https://img.shields.io/badge/Telegram-Join-26A5E4?style=flat-square&logo=telegram&logoColor=white" alt="Telegram"></a>
    <a href="https://discord.com/invite/tyx5B6TChr"><img src="https://img.shields.io/badge/Discord-Server-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Discord"></a>
    <a href="https://youtube.com/@quantdinger"><img src="https://img.shields.io/badge/YouTube-%40quantdinger-FF0000?style=flat-square&logo=youtube&logoColor=white" alt="YouTube"></a>
    <a href="https://x.com/QuantDinger_EN"><img src="docs/badges/x-quantdinger.svg" alt="X @QuantDinger_EN"></a>
  </p>

  <p>
    <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square" alt="Apache 2.0"></a>
    <img src="docs/badges/python-3.12.svg" alt="Python 3.12">
    <img src="https://img.shields.io/badge/PostgreSQL-18-4169E1?style=flat-square&logo=postgresql&logoColor=white" alt="PostgreSQL 18">
    <img src="https://img.shields.io/badge/Redis-8-DC382D?style=flat-square&logo=redis&logoColor=white" alt="Redis 8">
    <a href="#jev-powered-pre-trade-decisions"><img src="https://img.shields.io/badge/JEV-Pre--trade%20Decisions-7C3AED?style=flat-square" alt="JEV pre-trade decisions"></a>
    <img src="docs/badges/docker-compose.svg" alt="Docker Compose">
    <a href="https://github.com/OpenByteInc/QuantDinger/releases/latest"><img src="docs/badges/latest-release.svg" alt="Latest release"></a>
  </p>

  <p>
    <a href="https://github.com/orgs/OpenByteInc/projects/1"><img src="https://img.shields.io/github/issues/OpenByteInc/QuantDinger/roadmap?style=flat-square&label=Roadmap%20items&color=5319E7" alt="Open roadmap items"></a>
    <a href="https://github.com/orgs/OpenByteInc/projects/1/views/4"><img src="https://img.shields.io/github/issues/OpenByteInc/QuantDinger/ready%20for%20contributors?style=flat-square&label=Ready%20tasks&color=0E8A16" alt="Tasks ready for contributors"></a>
  </p>

  <p><sub>SUPPORTED BY</sub></p>
  <p>
    <a href="https://www.atlascloud.ai/?utm_source=github&utm_medium=link&utm_campaign=quantdinger" title="Atlas Cloud — AI inference sponsor">
      <picture>
        <source media="(prefers-color-scheme: dark)" srcset="https://www.atlascloud.ai/logo-white.svg">
        <img src="https://www.atlascloud.ai/logo.svg" alt="Atlas Cloud" width="142">
      </picture>
    </a>
    &nbsp;&nbsp;&nbsp;&nbsp;
    <a href="https://aws.amazon.com/" title="Amazon Web Services — cloud infrastructure sponsor">
      <picture>
        <source media="(prefers-color-scheme: dark)" srcset="https://a0.awsstatic.com/libra-css/images/logos/aws_smile-header-desktop-en-white_59x35.png">
        <img src="https://upload.wikimedia.org/wikipedia/commons/9/93/Amazon_Web_Services_Logo.svg" alt="Amazon Web Services" width="70">
      </picture>
    </a>
  </p>
</div>

> **Want to contribute?** Explore the
> [public roadmap](https://github.com/orgs/OpenByteInc/projects/1) or claim a
> scoped task from [Ready for contributors](https://github.com/orgs/OpenByteInc/projects/1/views/4).

> QuantDinger can submit real orders when live trading is explicitly enabled.
> Start with paper trading, use restricted API keys, and review the risk and
> compliance requirements for your jurisdiction. This project does not provide
> investment advice.

## Watch QuantDinger in action

<p align="center">
  <img src="docs/screenshots/quantdinger-v5-2x.gif" alt="QuantDinger product demo at 2× speed" width="800">
</p>

## What QuantDinger is

QuantDinger is an **open-source AI Trading OS** for independent traders, Python
strategy authors, and small teams. Its local-first, self-hosted design keeps
market data, strategy code, broker credentials, and deployment under the
operator's control.

The project combines:

- multi-provider AI market research and analysis;
- Python indicators and Strategy API V2 development;
- server-side backtesting and experiment workflows;
- paper and live execution across crypto exchanges and traditional brokers;
- web, mobile H5, human API, Agent Gateway, and MCP access;
- PostgreSQL-backed state, durable workers, audit logs, and optional monitoring.

It is not a black-box signal service. Strategy code, risk settings, credentials,
and deployment remain under the operator's control.

### Strategy evolution and signal-only virtual accounts

- **Strategy evolution** searches declared tunable parameters with random,
  grid, or TPE optimization, using bar-count walk-forward validation and a final
  blind holdout. Jobs run asynchronously with per-strategy history, automatic
  pruning, composite scoring, PBO, Deflated Sharpe, block-bootstrap Monte Carlo,
  and transaction-cost stress tests. Results compare parameter robustness; they
  do not forecast future returns.
- **Signal-only virtual accounts** turn notification-mode signals into internal
  virtual orders, fills, positions, trade records, PnL, and an equity curve. They
  never connect to a broker or submit live orders. Each fill uses a fixed 0.05%
  commission on executed notional and 0.05% adverse slippage; leverage is not
  charged a second time in the commission calculation.

## What changed in v5

The v5 backend is organized around explicit runtime and operational boundaries:

- the HTTP API no longer owns long-running trading or scheduler loops;
- trading, scheduling, Celery jobs, and migrations run as separate processes;
- Celery handles finite, retryable work while long-lived strategy runtimes stay
  in the trading worker;
- cache Redis and durable job Redis use separate instances and eviction policies;
- high-risk API contracts are represented in OpenAPI and protected by tests;
- JSON logs, request IDs, Prometheus metrics, dashboards, and alert rules are
  available through an optional observability overlay;
- the production overlay runs backend processes as a non-root user with a
  read-only root filesystem, dropped capabilities, and resource limits;
- CI checks syntax, lint, tests, release gates, Compose files, dependencies,
  source security, secrets, API compatibility, version drift, and text encoding.

The source version is declared in [`VERSION`](VERSION). Git release tags use the
same semantic version with a leading `v`, for example `v5.0.1`.

## Architecture

<p align="center">
  <img src="docs/screenshots/architecture-v5.png" alt="QuantDinger v5 architecture covering clients, Agent Gateway, core platform, distributed runtime workers, Kafka, infrastructure, observability, and the closed-loop trading workflow" width="100%">
</p>

<p align="center"><sub>The editable source is <a href="docs/screenshots/architecture-v5.svg">architecture-v5.svg</a>; the Mermaid topology below is the detailed runtime source of truth.</sub></p>

The static diagram above is the product-level view. The runtime topology below
is the current source of truth for container ownership and event/data flow.

```mermaid
flowchart TB
    C["Web / Mobile / API / MCP clients"]
    FE["Nginx frontend services"]
    API["Flask + Gunicorn API"]
    PG[("PostgreSQL")]
    CACHE[("Redis cache")]
    JOBS[("Redis jobs")]
    KAFKA[("Kafka event backbone")]
    TW["Trading workers\ncontrol, realtime, execution, grid actors"]
    DISPATCH["Strategy dispatcher workers"]
    EVAL["Strategy evaluator workers\nhot bar runtimes"]
    AUDIT["Kafka audit worker"]
    SW["Scheduler worker"]
    CW["Celery worker"]
    BEAT["Celery beat"]
    PROM["Prometheus"]
    GRAF["Grafana"]
    ALERT["Alertmanager"]

    C --> FE --> API
    API --> PG
    API --> CACHE
    API -->|"durable commands"| PG
    TW -->|"leases, order intents, fills, grid actor state"| PG
    TW -->|"closed bars and lifecycle events"| KAFKA
    KAFKA --> DISPATCH --> KAFKA
    KAFKA --> EVAL
    EVAL -->|"inbox, leases, checkpoints, order intents"| PG
    KAFKA --> AUDIT --> PG
    PG -->|"owned pending orders"| TW
    SW -->|"schedules, monitoring, heartbeats"| PG
    API -->|"finite async jobs"| JOBS
    BEAT --> JOBS --> CW
    CW --> PG
    API -. metrics .-> PROM
    PG -. exporter .-> PROM
    CACHE -. exporter .-> PROM
    JOBS -. exporter .-> PROM
    PROM --> GRAF
    PROM --> ALERT
```

One backend image is reused by several containers with different commands:

| Process | Responsibility |
| --- | --- |
| `migration` | Applies the database schema and exits before application services start. |
| `kafka-init` | Creates the versioned runtime topics and exits before event consumers start. |
| `backend` | Handles HTTP, authentication, validation, and durable command submission. |
| `trading-worker` | Owns control/realtime runtimes, exchange sessions, the fenced order gateway, reconciliation, and durable grid actors. |
| `strategy-dispatcher-worker` | Converts closed-bar events into stable strategy-shard evaluation batches. |
|