Metadata-Version: 2.4
Name: dtrader-v3-adapter
Version: 0.1.0
Summary: Adapters that connect DTrader V3 to strategy frameworks such as RQAlpha.
Requires-Python: <3.13,>=3.10
Requires-Dist: backtrader>=1.9.78.123
Requires-Dist: dtrader-v3-sdk>=0.1.0
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.0
Requires-Dist: rqalpha>=6.1.4
Provides-Extra: backtesting
Requires-Dist: backtesting>=0.6; extra == 'backtesting'
Provides-Extra: lean
Requires-Dist: lean>=1.0; extra == 'lean'
Provides-Extra: nautilus
Requires-Dist: nautilus-trader>=1.200; extra == 'nautilus'
Provides-Extra: vectorbt
Requires-Dist: vectorbt>=0.26; extra == 'vectorbt'
Provides-Extra: zipline
Requires-Dist: zipline-reloaded>=3.0; extra == 'zipline'
Description-Content-Type: text/markdown

# DTrader V3 Adapter

`v3-adapter` is the integration layer between DTrader V3 and popular strategy
frameworks. It packages framework-specific adapters so strategy projects can use
DTrader historical market data, real-time quotes, and trading APIs through the framework API they already know.

## Current adapter status

| Framework | Package / module | Status | What works now | Known gaps |
| --- | --- | --- | --- | --- |
| RQAlpha | `rqalpha_mod_dtrader` | Usable prototype | Daily A-share bars, quote snapshots, RQAlpha mod loading, simulated backtests, guarded paper/live broker bridge | Trading calendar is weekday-only, no futures/options, no tick history, no real exchange holidays, limited live event source |
| Backtrader | `backtrader_dtrader` | Prototype | DTrader daily K-lines as Backtrader `PandasData`, Cerebro smoke tests, guarded broker bridge | No dedicated live event loop, no full Store notification lifecycle, simulated accounting remains Backtrader-side |
| vn.py / VeighNa | `vnpy_dtrader` | Prototype | DTrader K-lines as vn.py `BarData`, quote snapshots as `TickData`, guarded Gateway buy/sell/cancel bridge | No streaming loop, no full order reconciliation, no CTA engine integration test yet |
| JoinQuant-style | `joinquant_dtrader` | Prototype | Local `initialize`/`handle_data` runtime, history/get_price/current_data APIs, simulated portfolio, guarded order bridge | Not a full JoinQuant clone; no factor/finance/query APIs, simple instant-fill backtest model |
| Zipline Reloaded | `zipline_dtrader` | Prototype | DTrader daily K-lines as Zipline bundle frames, asset metadata, ingest function, csvdir export, fake-writer tests | No minute writer/live broker bridge yet; full exchange calendar/corporate actions need production validation |
| backtesting.py | `backtesting_dtrader` | Prototype | DTrader daily K-lines as backtesting.py OHLCV DataFrame, fake Backtest smoke, guarded signal bridge | Single-asset history-first adapter; no full live broker/order reconciliation |
| vectorbt | `vectorbt_dtrader` | Prototype | DTrader OHLCV DataFrame/panel loaders, vectorbt `Portfolio.from_signals` helper, guarded signal bridge | Research/data-first adapter; no full live trading engine/order reconciliation |
| NautilusTrader | `nautilus_dtrader` | Prototype | Nautilus-style instrument IDs, DTrader K-lines as staged bar records/catalog CSV, quote snapshot client, guarded execution bridge | Not yet native Nautilus DataClient/ExecutionClient or ParquetDataCatalog writer |
| QuantConnect LEAN | `lean_dtrader` | Prototype | LEAN-style symbols, DTrader K-lines as TradeBar/custom-data CSV rows, quote snapshot provider, guarded Brokerage-shaped bridge | Not yet native LEAN IDataProvider/IBrokerage plugin or live deployment package |
| Other frameworks | TBD | Planned | Article directories and adapter taxonomy exist | Adapter shape not implemented yet |

## Layout

```text
src/rqalpha_mod_dtrader/      # RQAlpha mod: data source, broker, event source, price board
src/backtrader_dtrader/       # Backtrader data feed, store, guarded broker bridge
src/vnpy_dtrader/             # vn.py Datafeed and guarded Gateway bridge
src/joinquant_dtrader/        # JoinQuant-style local runtime and guarded order bridge
src/zipline_dtrader/          # Zipline Reloaded bundle/csvdir data adapter
src/backtesting_dtrader/      # backtesting.py OHLCV loader and signal bridge
src/vectorbt_dtrader/         # vectorbt OHLCV/panel loaders and signal bridge
src/nautilus_dtrader/         # Nautilus-style data catalog staging and guarded execution bridge
src/lean_dtrader/             # LEAN custom data staging and guarded brokerage bridge
configs/                      # Runnable RQAlpha configs per example
examples/rqalpha/             # RQAlpha strategy examples
examples/backtrader/          # Backtrader strategy examples
examples/vnpy/                # vn.py datafeed/gateway examples
examples/joinquant/           # JoinQuant-style local strategy examples
examples/zipline/             # Zipline csvdir, bundle registration, and strategy examples
examples/backtesting/         # backtesting.py strategy and signal bridge examples
examples/vectorbt/            # vectorbt research and signal bridge examples
examples/nautilus/            # Nautilus catalog/quote/execution boundary examples
examples/lean/                # LEAN custom-data/quote/brokerage boundary examples
docs/rqalpha/                 # Detailed RQAlpha adapter docs
docs/backtrader/              # Backtrader adapter docs
docs/vnpy/                    # vn.py adapter docs
docs/joinquant/               # JoinQuant-style adapter docs
docs/zipline/                 # Zipline adapter docs
docs/backtesting/             # backtesting.py adapter docs
docs/vectorbt/                # vectorbt adapter docs
docs/nautilus/                # NautilusTrader adapter docs
docs/lean/                    # QuantConnect LEAN adapter docs
docs/adapter-quality-gate.md  # Required tests before raising adapter maturity
scripts/mock_dtrader_server.py # Local fake DTrader endpoint for smoke tests
tests/                        # Unit/regression tests for adapter behavior
```

## Install as a library

Install the adapter library:

```sh
pip install dtrader-v3-adapter
```

After installation, strategy projects can import the framework module they need, for example `rqalpha_mod_dtrader`, `backtrader_dtrader`, `zipline_dtrader`, `backtesting_dtrader`, `vectorbt_dtrader`, `nautilus_dtrader`, or `lean_dtrader`.

Optional framework extras:

```sh
pip install "dtrader-v3-adapter[backtesting]"
pip install "dtrader-v3-adapter[vectorbt]"
pip install "dtrader-v3-adapter[nautilus]"
pip install "dtrader-v3-adapter[lean]"
pip install "dtrader-v3-adapter[zipline]"
```

## Source setup

Use Python 3.10-3.12. RQAlpha currently runs here with Python 3.11.

```sh
uv sync
```

If you want to run without `uv run`, activate the venv first:

```sh
source .venv/bin/activate
```

## Run against a real DTrader service

Installed package usage:

```sh
export DTRADER_BASE_URL="https://your-dtrader-endpoint"
export DTRADER_AUTH="your-auth-token"
rqalpha run --config backtest.yml
```

Source checkout usage:

```sh
PYTHONPATH=src uv run rqalpha run --config configs/backtest.yml
```

## Run without a real DTrader service

Start the mock endpoint in one terminal:

```sh
PYTHONPATH=src uv run python scripts/mock_dtrader_server.py
```

Run an example in another terminal:

```sh
DTRADER_BASE_URL=http://127.0.0.1:18080 \
DTRADER_AUTH=dev \
PYTHONPATH=src \
uv run rqalpha run --config configs/backtest_buy_and_hold.yml
```

## Available JoinQuant-style examples

| Example | Purpose |
| --- | --- |
| [`examples/joinquant/run_backtest.py`](https://github.com/DTrader-store/v3-adapter/blob/main/examples/joinquant/run_backtest.py) | Run a local JoinQuant-style moving-average backtest with DTrader historical K-lines |
| [`examples/joinquant/order_guard.py`](https://github.com/DTrader-store/v3-adapter/blob/main/examples/joinquant/order_guard.py) | Guarded order path; real trading off unless both switches are enabled |

## Available Zipline Reloaded examples

| Example | Purpose |
| --- | --- |
| [`examples/zipline/write_csvdir.py`](https://github.com/DTrader-store/v3-adapter/blob/main/examples/zipline/write_csvdir.py) | Export DTrader historical K-lines into Zipline `csvdir`-style daily CSV files |
| [`examples/zipline/register_bundle.py`](https://github.com/DTrader-store/v3-adapter/blob/main/examples/zipline/register_bundle.py) | Register a custom `dtrader-a-share` bundle for `zipline ingest` |
| [`examples/zipline/ma_strategy.py`](https://github.com/DTrader-store/v3-adapter/blob/main/examples/zipline/ma_strategy.py) | Zipline moving-average strategy using `data.history` and simulated orders |

## Available backtesting.py examples

| Example | Purpose |
| --- | --- |
| [`examples/backtesting/backtest_ma.py`](https://github.com/DTrader-store/v3-adapter/blob/main/examples/backtesting/backtest_ma.py) | Moving-average backtesting.py run using DTrader historical K-lines |
| [`examples/backtesting/signal_bridge.py`](https://github.com/DTrader-store/v3-adapter/blob/main/examples/backtesting/signal_bridge.py) | Guarded signal handoff example; real trading off unless both switches are enabled |

## Available vectorbt examples

| Example | Purpose |
| --- | --- |
| [`examples/vectorbt/ma_parameter_scan.py`](https://github.com/DTrader-store/v3-adapter/blob/main/examples/vectorbt/ma_parameter_scan.py) | Vectorized moving-average signal backtest using DTrader historical K-lines |
| [`examples/vectorbt/multi_symbol_close.py`](https://github.com/DTrader-store/v3-adapter/blob/main/examples/vectorbt/multi_symbol_close.py) | Load multiple DTrader symbols into a close-price matrix |
| [`examples/vectorbt/signal_bridge.py`](https://github.com/DTrader-store/v3-adapter/blob/main/examples/vectorbt/signal_bridge.py) | Guarded vectorbt signal handoff; real trading off unless both switches are enabled |

## Available NautilusTrader examples

| Example | Purpose |
| --- | --- |
| [`examples/nautilus/write_catalog_csv.py`](https://github.com/DTrader-store/v3-adapter/blob/main/examples/nautilus/write_catalog_csv.py) | Write DTrader historical K-lines into Nautilus-style staged catalog CSV files |
| [`examples/nautilus/quote_snapshot.py`](https://github.com/DTrader-store/v3-adapter/blob/main/examples/nautilus/quote_snapshot.py) | Map one DTrader quote snapshot into a Nautilus-style quote tick |
| [`examples/nautilus/execution_guard.py`](https://github.com/DTrader-store/v3-adapter/blob/main/examples/nautilus/execution_guard.py) | Guarded execution-client-shaped order handoff; real trading off unless both switches are enabled |

## Available QuantConnect LEAN examples

| Example | Purpose |
| --- | --- |
| [`examples/lean/write_custom_data_csv.py`](https://github.com/DTrader-store/v3-adapter/blob/main/examples/lean/write_custom_data_csv.py) | Write DTrader historical K-lines into LEAN Custom Data CSV files |
| [`examples/lean/quote_snapshot.py`](https://github.com/DTrader-store/v3-adapter/blob/main/examples/lean/quote_snapshot.py) | Map one DTrader quote snapshot into a LEAN QuoteBar-shaped record |
| [`examples/lean/brokerage_guard.py`](https://github.com/DTrader-store/v3-adapter/blob/main/examples/lean/brokerage_guard.py) | Guarded Brokerage-shaped order handoff; real trading off unless both switches are enabled |
| [`examples/lean/custom_data_algorithm.py`](https://github.com/DTrader-store/v3-adapter/blob/main/examples/lean/custom_data_algorithm.py) | Shape reference for a LEAN Custom Data strategy project |

## Available vn.py examples

| Example | Purpose |
| --- | --- |
| [`examples/vnpy/query_history.py`](https://github.com/DTrader-store/v3-adapter/blob/main/examples/vnpy/query_history.py) | Query DTrader historical K-lines as vn.py-style `BarData` |
| [`examples/vnpy/gateway_order_guard.py`](https://github.com/DTrader-store/v3-adapter/blob/main/examples/vnpy/gateway_order_guard.py) | Guarded Gateway quote/order path; real trading off unless both switches are enabled |

## Available Backtrader examples

| Example | Purpose |
| --- | --- |
| [`examples/backtrader/backtest_ma.py`](https://github.com/DTrader-store/v3-adapter/blob/main/examples/backtrader/backtest_ma.py) | Moving-average Cerebro backtest using DTrader historical K-lines |
| [`examples/backtrader/paper_order_guard.py`](https://github.com/DTrader-store/v3-adapter/blob/main/examples/backtrader/paper_order_guard.py) | Guarded paper/live order path; real trading off unless both switches are enabled |

## Available RQAlpha examples

| Config | Strategy | Purpose |
| --- | --- | --- |
| [`configs/backtest.yml`](https://github.com/DTrader-store/v3-adapter/blob/main/configs/backtest.yml) | [`examples/rqalpha/backtest_ma.py`](https://github.com/DTrader-store/v3-adapter/blob/main/examples/rqalpha/backtest_ma.py) | Moving-average crossover using DTrader historical K-lines |
| [`configs/backtest_buy_and_hold.yml`](https://github.com/DTrader-store/v3-adapter/blob/main/configs/backtest_buy_and_hold.yml) | [`examples/rqalpha/backtest_buy_and_hold.py`](https://github.com/DTrader-store/v3-adapter/blob/main/examples/rqalpha/backtest_buy_and_hold.py) | Minimal one-shot target position example |
| [`configs/backtest_multi_asset_rotation.yml`](https://github.com/DTrader-store/v3-adapter/blob/main/configs/backtest_multi_asset_rotation.yml) | [`examples/rqalpha/backtest_multi_asset_rotation.py`](https://github.com/DTrader-store/v3-adapter/blob/main/examples/rqalpha/backtest_multi_asset_rotation.py) | Multi-symbol momentum rotation with `history_bars` |
| [`configs/backtest_stop_loss_take_profit.yml`](https://github.com/DTrader-store/v3-adapter/blob/main/configs/backtest_stop_loss_take_profit.yml) | [`examples/rqalpha/backtest_stop_loss_take_profit.py`](https://github.com/DTrader-store/v3-adapter/blob/main/examples/rqalpha/backtest_stop_loss_take_profit.py) | Position entry plus stop-loss/take-profit exit |
| [`configs/paper.yml`](https://github.com/DTrader-store/v3-adapter/blob/main/configs/paper.yml) | [`examples/rqalpha/paper_quote_threshold.py`](https://github.com/DTrader-store/v3-adapter/blob/main/examples/rqalpha/paper_quote_threshold.py) | Paper/live quote threshold order example; real trading off by default |
| [`configs/paper_order_guard.yml`](https://github.com/DTrader-store/v3-adapter/blob/main/configs/paper_order_guard.yml) | [`examples/rqalpha/paper_order_guard.py`](https://github.com/DTrader-store/v3-adapter/blob/main/examples/rqalpha/paper_order_guard.py) | Paper/live guarded one-order example; real trading off by default |

## Read-only real endpoint validation

Use this before enabling any paper/live order path:

```sh
export DTRADER_BASE_URL="https://your-dtrader-endpoint"
export DTRADER_AUTH="your-osk-or-auth-token"
export DTRADER_VALIDATE_SYMBOLS="600519,000001"
PYTHONPATH=src .venv/bin/python scripts/validate_dtrader_readonly.py \
  --output .cache/dtrader-readonly-validation/report.json
```

This checks quote, kline, account, positions, and orders query APIs. It does not call buy, sell, or cancel endpoints.

## Real trading safety

Paper/live configs default to:

```yaml
enable_trading: false
paper_fill: true
```

Real DTrader `buy` / `sell` calls require **both**:

```yaml
mod:
  dtrader:
    enable_trading: true
```

and:

```sh
export DTRADER_ENABLE_TRADING=1
```

Keep this two-switch guard. Do not enable real trading while validating examples.

## Verification

```sh
PYTHONPATH=src uv run python -m unittest discover -s tests
PYTHONPATH=src uv run python -m unittest tests/test_backtrader_adapter.py -v
PYTHONPATH=src uv run python -m unittest tests/test_vnpy_adapter.py -v
PYTHONPATH=src uv run python -m unittest tests/test_joinquant_adapter.py -v
PYTHONPATH=src uv run python -m unittest tests/test_zipline_adapter.py -v
PYTHONPATH=src uv run python -m unittest tests/test_backtesting_adapter.py -v
PYTHONPATH=src uv run python -m unittest tests/test_vectorbt_adapter.py -v
PYTHONPATH=src uv run python -m unittest tests/test_nautilus_adapter.py -v
PYTHONPATH=src uv run python -m unittest tests/test_lean_adapter.py -v
PYTHONPATH=src uv run python -m unittest tests/test_readonly_validation.py -v
PYTHONPATH=src uv run python -m compileall src examples tests scripts
uv build
```

For a smoke run with the local mock server:

```sh
PYTHONPATH=src uv run python scripts/mock_dtrader_server.py
# second terminal
DTRADER_BASE_URL=http://127.0.0.1:18080 DTRADER_AUTH=dev PYTHONPATH=src uv run rqalpha run --config configs/backtest.yml
# Backtrader smoke example
DTRADER_BASE_URL=http://127.0.0.1:18080 DTRADER_AUTH=dev PYTHONPATH=src uv run python examples/backtrader/backtest_ma.py
# vn.py datafeed smoke example
DTRADER_BASE_URL=http://127.0.0.1:18080 DTRADER_AUTH=dev PYTHONPATH=src uv run python examples/vnpy/query_history.py
# JoinQuant-style smoke example
DTRADER_BASE_URL=http://127.0.0.1:18080 DTRADER_AUTH=dev PYTHONPATH=src uv run python examples/joinquant/run_backtest.py
# Zipline csvdir export smoke example
DTRADER_BASE_URL=http://127.0.0.1:18080 DTRADER_AUTH=dev PYTHONPATH=src uv run python examples/zipline/write_csvdir.py
# backtesting.py smoke example
DTRADER_BASE_URL=http://127.0.0.1:18080 DTRADER_AUTH=dev PYTHONPATH=src uv run python examples/backtesting/backtest_ma.py
# vectorbt multi-symbol data smoke example
DTRADER_BASE_URL=http://127.0.0.1:18080 DTRADER_AUTH=dev PYTHONPATH=src uv run python examples/vectorbt/multi_symbol_close.py
# Nautilus staged catalog smoke example
DTRADER_BASE_URL=http://127.0.0.1:18080 DTRADER_AUTH=dev PYTHONPATH=src uv run python examples/nautilus/write_catalog_csv.py
# LEAN custom-data CSV smoke example
DTRADER_BASE_URL=http://127.0.0.1:18080 DTRADER_AUTH=dev PYTHONPATH=src uv run python examples/lean/write_custom_data_csv.py
```

## Promotional article library

Framework integration and promotion articles live in the article repository:

https://github.com/DTrader-store/v3-articles

The adapter repository keeps runnable integration code; `v3-articles` keeps publishable narratives, tutorials, and series outlines.

## More docs

- [`docs/adapter-quality-gate.md`](https://github.com/DTrader-store/v3-adapter/blob/main/docs/adapter-quality-gate.md) — testing and maturity gate for every framework adapter
- [`docs/backtrader/adapter-status.md`](https://github.com/DTrader-store/v3-adapter/blob/main/docs/backtrader/adapter-status.md) — Backtrader adapter status and limitations
- [`docs/vnpy/adapter-status.md`](https://github.com/DTrader-store/v3-adapter/blob/main/docs/vnpy/adapter-status.md) — vn.py adapter status and limitations
- [`docs/joinquant/adapter-status.md`](https://github.com/DTrader-store/v3-adapter/blob/main/docs/joinquant/adapter-status.md) — JoinQuant-style adapter status and limitations
- [`docs/zipline/adapter-status.md`](https://github.com/DTrader-store/v3-adapter/blob/main/docs/zipline/adapter-status.md) — Zipline Reloaded adapter status and limitations
- [`docs/backtesting/adapter-status.md`](https://github.com/DTrader-store/v3-adapter/blob/main/docs/backtesting/adapter-status.md) — backtesting.py adapter status and limitations
- [`docs/vectorbt/adapter-status.md`](https://github.com/DTrader-store/v3-adapter/blob/main/docs/vectorbt/adapter-status.md) — vectorbt adapter status and limitations
- [`docs/nautilus/adapter-status.md`](https://github.com/DTrader-store/v3-adapter/blob/main/docs/nautilus/adapter-status.md) — NautilusTrader adapter status and limitations
- [`docs/lean/adapter-status.md`](https://github.com/DTrader-store/v3-adapter/blob/main/docs/lean/adapter-status.md) — QuantConnect LEAN adapter status and limitations
- [`docs/rqalpha/getting-started.md`](https://github.com/DTrader-store/v3-adapter/blob/main/docs/rqalpha/getting-started.md) — setup and first run
- [`docs/rqalpha/adapter-status.md`](https://github.com/DTrader-store/v3-adapter/blob/main/docs/rqalpha/adapter-status.md) — what is actually integrated and what is not
- [`docs/rqalpha/examples.md`](https://github.com/DTrader-store/v3-adapter/blob/main/docs/rqalpha/examples.md) — example-by-example walkthrough
- [`docs/rqalpha/readonly-validation.md`](https://github.com/DTrader-store/v3-adapter/blob/main/docs/rqalpha/readonly-validation.md) — safe real-endpoint validation without trading
- [`docs/adapter-roadmap.md`](https://github.com/DTrader-store/v3-adapter/blob/main/docs/adapter-roadmap.md) — how future framework adapters should be added

## License note

RQAlpha source and docs contain commercial-use restrictions. Check licensing
before using this adapter in a commercial hosted product.
