Boutquin.Trading.Data.TwelveData 1.0.1

Boutquin.Trading

A multi-asset, multi-strategy, event-driven quantitative trading framework for backtesting strategies with portfolio-based risk management and dynamic capital allocation. Built with clean architecture, .NET 10, and strict code quality standards.

Solution Structure

Features

Event-Driven Backtesting Engine

• Event pipeline — MarketEvent → SignalEvent → OrderEvent → FillEvent with pluggable handlers
• Portfolio — Multi-currency cash management, position tracking, equity curve computation (14 interface methods)
• SimulatedBrokerage — Market, limit, stop, and stop-limit order execution with slippage, commission models, and optional buffered market data path
• Strategies — BuyAndHoldStrategy, RebalancingBuyAndHoldStrategy, ConstructionModelStrategy

Portfolio Construction (8 Models)

• Equal Weight — Uniform allocation across all assets
• Inverse Volatility — Weight inversely proportional to realized volatility
• Minimum Variance — Minimize portfolio variance via projected gradient descent
• Mean-Variance — Maximize Sharpe ratio via mean-variance optimization
• Risk Parity — Equalize risk contribution across assets
• Black-Litterman — Bayesian framework combining equilibrium returns with investor views
• Tactical Overlay — Regime-specific tilts plus optional momentum scoring
• Volatility Targeting — Scale weights to hit a target portfolio volatility

Financial Metrics

• Sharpe Ratio, Sortino Ratio, Annualized Return, Standard Deviation, Downside Deviation
• Maximum Drawdown, Beta, Information Ratio, Tracking Error
• All calculations use sample divisor (N-1) for financial time series

Analytics & Attribution

• Brinson-Fachler Attribution — Allocation, selection, and interaction effects
• Factor Regression — Multi-factor OLS via normal equations (Fama-French compatible)
• Correlation Analysis — Full N×N correlation matrix, diversification ratio, rolling pairwise correlation
• Drawdown Analysis — Discrete drawdown period identification (peak → trough → recovery)
• Walk-Forward Optimization — Rolling in-sample/out-of-sample validation (no look-ahead bias)
• Monte Carlo Simulation — Bootstrap resampling with Sharpe ratio distribution

Tactical & Regime Detection

• Indicators — SMA, EMA, Realized Volatility, Momentum Score, Spread, Rate of Change
• Regime Classifier — Growth/inflation quadrant detection with configurable deadband hysteresis
• Universe Filtering — AUM, inception age, and liquidity filters with composite AND logic

Risk Management

• Composite risk manager — Evaluates all rules; first rejection short-circuits
• MaxDrawdownRule — Rejects orders when equity curve drawdown exceeds limit
• MaxPositionSizeRule — Rejects when single position exceeds % of portfolio
• MaxSectorExposureRule — Rejects when asset class exposure exceeds threshold

Reporting

• HTML Tearsheet — Self-contained HTML with embedded SVG equity curve, drawdown area chart, metrics table, and monthly returns heatmap
• Benchmark Comparison — Side-by-side portfolio vs benchmark with dual equity curve and tracking error

Caching

• L1 memory cache — ConcurrentDictionary + Lazy<Task> decorators for thread-safe exactly-once materialization of market data, economic data, and factor data fetches
• L2 CSV write-through — Transparent disk cache with atomic writes (tmp + rename), per-symbol existence checks, and partial cache support
• Backtest prefetch — Materializes market data into a buffer dictionary; SimulatedBrokerage uses O(1) dictionary lookups instead of re-streaming IAsyncEnumerable
• DI wiring — AddBoutquinTradingCaching() auto-decorates pre-registered fetchers based on CacheOptions (L1/L2 independently toggleable)

Data Providers

• Tiingo — Historical equity/ETF price data
• Twelve Data — Equity market data combining time series, dividends, and splits
• Frankfurter — ECB-sourced FX rates with date range filtering
• FRED — Federal Reserve Economic Data (treasury yields, inflation, GDP, macro indicators)
• Fama-French — Academic factor return series (3-factor, 5-factor, momentum) from the Ken French Data Library
• CSV — Market data, economic data, factor data, and symbol list storage/ingestion
• Composite fetcher — Routes equity vs FX requests to the appropriate provider

Quick Start

Installation

dotnet add package Boutquin.Trading.Domain
dotnet add package Boutquin.Trading.Application

Dependency Injection Setup

using Boutquin.Trading.Application.Configuration;

services.AddBoutquinTrading(configuration);

Configuration via appsettings.json:

{
  "Backtest": {
    "StartDate": "2020-01-01",
    "EndDate": "2023-12-31",
    "BaseCurrency": "USD",
    "RebalancingFrequency": "Monthly",
    "ConstructionModel": "RiskParity"
  },
  "CostModel": {
    "CommissionRate": 0.001,
    "SlippageType": "PercentageSlippage",
    "SlippageAmount": 0.0005
  },
  "RiskManagement": {
    "MaxDrawdownPercent": 0.20,
    "MaxPositionSizePercent": 0.10,
    "MaxSectorExposurePercent": 0.40
  },
  "Cache": {
    "DataDirectory": "./data/cache",
    "EnableMemoryCache": true
  }
}

Architecture

┌───────────────────────────────────────────────────────────────────────┐
│                           Domain Layer                                │
│  Interfaces: IPortfolio, IBrokerage, IStrategy, IPositionSizer,       │
│    ICovarianceEstimator, IPortfolioConstructionModel, IRiskManager,   │
│    IIndicator, IMacroIndicator, IRegimeClassifier, IUniverseSelector  │
│  Events: MarketEvent, SignalEvent, OrderEvent, FillEvent              │
│  Enums: AssetClassCode, CurrencyCode, OrderType, TradeAction (14)     │
│  Extensions: DecimalArrayExtensions, EquityCurveExtensions            │
│  Analytics: BrinsonFachlerResult, DrawdownPeriod, MonteCarloResult    │
│  Value Objects: RiskEvaluation                                        │
└───────────────────────────┬───────────────────────────────────────────┘
                            │ depends on
┌───────────────────────────▼───────────────────────────────────────────┐
│                        Application Layer                              │
│  Engine: Portfolio, BackTest, SimulatedBrokerage                      │
│  Strategies: BuyAndHold, RebalancingBuyAndHold, ConstructionModel     │
│  Construction: EqualWeight, InverseVol, MinVar, MeanVar, RiskParity,  │
│    BlackLitterman, TacticalOverlay, VolatilityTargeting               │
│  Analytics: BrinsonFachler, FactorRegressor, CorrelationAnalyzer,     │
│    DrawdownAnalyzer, WalkForwardOptimizer, MonteCarloSimulator        │
│  Caching: L1 Memory (CachingXxxFetcher), L2 CSV (WriteThroughXxx)     │
│  Risk: RiskManager, MaxDrawdown, MaxPositionSize, MaxSectorExposure   │
│  Indicators: SMA, EMA, RealizedVol, Momentum, Spread, RateOfChange    │
│  Reporting: HtmlReportGenerator, BenchmarkComparisonReport            │
│  DI: ServiceCollectionExtensions, BacktestOptions, CacheOptions       │
└───────────────────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────────────┐
│                          Data Layer                                   │
│  Tiingo, TwelveData (equities), Frankfurter (FX), FRED, FF (factors)  │
│  CompositeMarketDataFetcher, DataAccess (EF Core SecurityMaster)      │
└───────────────────────────────────────────────────────────────────────┘

The architecture follows the dependency inversion principle — the Domain layer defines contracts, and Application/Data layers provide implementations that can be swapped independently.

For detailed architecture including component navigation and data flow, see ARCHITECTURE.md.

Directory Structure

Boutquin.Trading/
├── src/                    # Source projects
│   ├── Domain/             # Core domain: interfaces, events, enums, extensions
│   ├── Application/        # Backtest engine, strategies, analytics, DI
│   ├── DataAccess/         # EF Core data access
│   ├── Data.Tiingo/        # Tiingo equity data fetcher
│   ├── Data.TwelveData/    # Twelve Data equity data fetcher
│   ├── Data.Frankfurter/   # Frankfurter FX rate fetcher
│   ├── Data.Fred/          # FRED economic data fetcher
│   ├── Data.FamaFrench/    # Fama-French factor data fetcher
│   ├── Data.CSV/           # CSV data reader
│   ├── Data.Processor/     # Data processing pipeline
│   ├── BackTest/           # Backtest runner entry point
│   └── Sample/             # Usage examples
├── tests/                  # Test projects
│   ├── UnitTests/          # xUnit + FluentAssertions + Moq
│   └── ArchitectureTests/  # NetArchTest fitness functions
├── benchmarks/             # Performance benchmarks
│   └── BenchMark/          # BenchmarkDotNet suite
├── docs/                   # Documentation
├── specs/                  # Specifications
├── hooks/                  # Git hooks (pre-commit)
└── Resources/              # Shared assets (icon)

Contributing

Contributions are welcome! Please read the contributing guidelines and code of conduct first.

Reporting Bugs

If you find a bug, please report it by opening an issue on the Issues page with:

• A clear and descriptive title
• Steps to reproduce the issue
• Expected and actual behavior
• Screenshots or code snippets, if applicable

Contributing Code

1. Fork the repository and clone locally
2. Create a feature branch: git checkout -b feature-name
3. Install git hooks: ./hooks/install.sh
4. Make your changes following the style guides
5. Commit with clear messages: git commit -m "Add feature X"
6. Push and open a pull request

License

This project is licensed under the Apache 2.0 License — see the LICENSE file for details.

Contact

For inquiries, please open an issue or reach out via GitHub Discussions.