
![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

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 (orders, fills)
-   Portfolio events (position updates)
-   Recording events (trade lifecycle)

As a user, you primarily:

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


## 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_update`
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:

-   CSV or historical provider feeds market data
-   Backtest runner drives event loop
-   Strategy executes normally
-   Portfolio and recording operate identically to live mode

See `docs/backtesting_guide.md` for detailed usage.


## 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.


## Portfolio & Risk

The portfolio subsystem:

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

Risk controls can reject or modify orders before execution.


## Recording & Reporting

The recording subsystem:

-   Tracks trades and equity curves
-   Computes excursions and performance metrics
-   Generates structured reports

Users can subscribe to recording events for custom reporting pipelines.


## Typical Project Structure


    my_strategy/
        strategy.py
        run_backtest.py
        config.py


## Installation

Install using your preferred environment manager. Ensure Python 3.11+.


## Documentation

See the `docs/` directory for:

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


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

## 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)

