Metadata-Version: 2.4
Name: tradedesk
Version: 0.12.0
Summary: Trading infrastructure library with backtesting
Project-URL: Homepage, https://github.com/radiusred
Project-URL: Repository, https://github.com/radiusred/tradedesk
Project-URL: Issues, https://github.com/radiusred/tradedesk/issues
Author-email: "Radius Red Ltd." <opensource@radiusred.uk>
Maintainer-email: "Radius Red Ltd." <opensource@radiusred.uk>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: lightstreamer-client-lib>=2.0
Requires-Dist: matplotlib>=3.10.8
Requires-Dist: numpy>=2.4.0
Requires-Dist: pandas-stubs[dev]>=3.0.0.260204
Requires-Dist: pandas>=3.0.1
Requires-Dist: python-dotenv>=1.0
Requires-Dist: requests>=2.31
Requires-Dist: seaborn>=0.13.2
Requires-Dist: types-seaborn[dev]>=0.13.2.20251221
Requires-Dist: zstandard>=0.25
Provides-Extra: dev
Requires-Dist: llm-tldr[dev]>=1.5.2; extra == 'dev'
Requires-Dist: mypy>=1.19; extra == 'dev'
Requires-Dist: pre-commit>=4.5; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=7.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: responses>=0.25; extra == 'dev'
Requires-Dist: ruff>=0.15; extra == 'dev'
Description-Content-Type: text/markdown


![CI Build](https://github.com/radiusred/tradedesk/actions/workflows/ci.yml/badge.svg)
[![PyPI Version](https://img.shields.io/pypi/v/tradedesk?label=PyPI)](https://pypi.python.org/pypi/tradedesk)

# tradedesk

Contributing: [CONTRIBUTING.md](./CONTRIBUTING.md)

tradedesk is an event-driven trading framework for building, running,
and evaluating systematic trading strategies across both backtesting and live
broker environments.

It provides:

-   Event-based strategy execution
-   Unified backtest and live broker runtime model
-   Market data aggregation and indicator framework
-   Portfolio orchestration and risk management
-   Trade recording, metrics, and reporting

The framework is designed so that strategies react to events --- not
broker implementations --- enabling the same strategy code to run
unchanged in both backtest and live environments.


## Core Concepts

### Event-Driven Architecture

All major subsystems communicate via events:

-   Market data events (ticks, candles)
-   Strategy events (signals)
-   Execution events (order completions and broker fills)
-   Portfolio events (position updates and lifecycle transitions)
-   Recording events (trade lifecycle, equity, and reporting)

As a user, you primarily:

-   Implement a strategy that reacts to candle updates
-   Optionally subscribe to events for custom analytics or logging


## Architecture Overview

For a concise public map of the system, see ARCHITECTURE.md. tradedesk is built around an event-driven core that wires together market data, strategy logic, portfolio management, execution adapters (IG for live trading, Dukascopy-backed backtests), and a recording layer for metrics and reports. The public interfaces expose reusable building blocks (marketdata, strategy, portfolio, recording) with clear data-flow guarantees across backtest and live paths.

## Basic Strategy Structure

A strategy derives from the base strategy class and implements candle
handling logic.

Typical flow:

1.  Market data arrives (tick or candle)
2.  Aggregation produces candles
3.  Strategy receives `on_candle_close`
4.  Strategy emits order requests
5.  Execution layer processes orders
6.  Portfolio updates positions
7.  Recording captures trade lifecycle


## Running a Backtest

Backtesting uses the same event model as live trading.

High-level flow:

-   Dukascopy cache data is loaded via `BacktestClient.from_dukascopy_cache(...)`
-   `run_backtest(...)` drives the event loop and recording pipeline
-   Strategy code executes unchanged
-   Portfolio and recording operate identically to live mode

See `docs/backtesting_guide.md` for the current cache-backed workflow.


## Live Trading (IG)

The IG execution module provides:

-   REST client for order management
-   Streaming price integration
-   Position synchronization
-   Retry and resilience handling

Your strategy remains unchanged --- only the execution configuration
differs.

Orders placed through `request_order(...)` continue to flow through
`OrderExecutionHandler` in both backtest and live sessions. For clients such as
IG that do not publish their own position-open callbacks, tradedesk emits a
`PositionOpenedEvent` immediately after a confirmed opening fill. That keeps
recording subscribers and custom event consumers aligned across backtest,
DEMO, and LIVE runs without double-publishing for clients that already emit
their own lifecycle events.

### IG Credentials

Live IG runs read credentials from environment variables:

-   `IG_API_KEY` (required)
-   `IG_USERNAME` (required)
-   `IG_PASSWORD` (required)
-   `IG_ENVIRONMENT` (optional, defaults to `DEMO`, valid values are `DEMO` and `LIVE`)

Example:

```bash
IG_API_KEY=... \
IG_USERNAME=... \
IG_PASSWORD=... \
IG_ENVIRONMENT=DEMO \
python your_live_runner.py
```

`tradedesk` authenticates with IG and captures the short-lived session headers
(`CST` and `X-SECURITY-TOKEN`) from the login response automatically. You do not
configure those session tokens yourself.


## Portfolio & Risk

The portfolio subsystem:

-   Tracks positions
-   Applies risk policies
-   Reconciles fills
-   Emits portfolio events

Risk controls such as spread limits and portfolio-level order gates can reject
orders before broker submission.


## Recording & Reporting

The recording subsystem:

-   Tracks trades and equity curves
-   Computes excursions and performance metrics
-   Generates structured reports from position lifecycle events and fills

Users can subscribe to recording events for custom reporting pipelines.


## Typical Project Structure


    my_strategy/
        strategy.py
        run_backtest.py
        config.py


## Installation

Python 3.11+ is required.

Install the published package:

```bash
pip install tradedesk
```

For local development:

```bash
pip install -e '.[dev]'
```


## Documentation

See the `docs/` directory for:

-   Backtesting guide
-   Strategy guide
-   Portfolio guide
-   Indicator guide
-   Aggregation guide
-   Risk management guide
-   Metrics guide

Public package entry points are grouped under:

-   `tradedesk.marketdata`
-   `tradedesk.execution`
-   `tradedesk.execution.backtest`
-   `tradedesk.portfolio`
-   `tradedesk.recording`
-   `tradedesk.strategy`


tradedesk is designed for clarity, determinism, and event-level
transparency.

## See Also
- docs/backtesting_guide.md
- docs/strategy_guide.md
- docs/indicator_guide.md
- docs/crash-recovery.md

## Contributing

See CONTRIBUTING.md for guidelines on contributing to tradedesk.

## License

Licensed under the Apache License, Version 2.0.
See: [https://www.apache.org/licenses/LICENSE-2.0](https://www.apache.org/licenses/LICENSE-2.0)

Copyright 2026 [Radius Red Ltd.](https://github.com/radiusred) | [Contact](mailto:opensource@radiusred.uk)
