wickd 0.2.0

WickdAlgo

WickdAlgo is a C#/.NET 10 trading research platform for deterministic backtest plumbing and Smart Money Concepts structure journaling. Its technical codebase uses the Wickd.* project, package, and namespace family.

Canonical repository: https://github.com/WickdAlgo/wickd-dotnet.

The current implementation supports historical candle fetching/caching and backtest replay through the A1 -> B path:

A1 HistoricalDataSource -> B StructureEngine -> structures.jsonl

It does not yet perform setup selection, trade creation, settlement, live execution, dashboard rendering, or AI analyst reasoning.

Current Status

Implemented:

• fetch: fetches and caches completed historical OHLCV candles for one market and one timeframe.
• Dataset aliases: fetch --alias saves a reusable range in data/datasets.json; backtest --dataset replays it.
• backtest: replays cached candles, runs the structure engine, and writes runs/{runId}/structures.jsonl.
• manage: lists and deletes saved dataset aliases, optional cached candle files, and local backtest run output folders.
• Structure journaling: emits deterministic events for swings, equal highs/lows, liquidity breaches, sweeps, order blocks, expansion/FVG events, and lifecycle updates.

Placeholder:

• analyze: parses --run-id, then returns a not-implemented message.

Not implemented yet:

• Setup engine.
• Trade engine.
• Backtest settlement outcomes.
• Live execution.
• AI analyst agent.
• Web or TradingView dashboard.

Requirements

• .NET 10 SDK. The repository pins SDK 10.0.301 through global.json.
• Network access for first-time NuGet restore.
• Network access when fetching public historical candles.

The current production market data path supports Binance USD-M futures through CCXT. Markets configured for unsupported exchange IDs are present for future work but will fail historical fetch until a matching data client exists.

Quick Start

Run commands from the repository root:

dotnet restore Wickd.slnx
dotnet build Wickd.slnx
dotnet test Wickd.slnx
dotnet run --project src/Wickd.Cli -- --help

Package and install the CLI as a local NuGet tool for a smoke test:

dotnet pack src/Wickd.Cli/Wickd.Cli.csproj -c Release
dotnet tool install wickd --source src/Wickd.Cli/bin/Release --tool-path artifacts/wickd-tool --version 0.1.0-preview.1
artifacts/wickd-tool/wickd --help

After publishing to NuGet, users install and run the WickdAlgo CLI as a .NET tool:

dotnet tool install --global wickd --version 0.1.0-preview.1
wickd config init
wickd config path
wickd --help

Developers building on the engine can install the SDK packages separately:

dotnet add package Wickd.Core --version 0.1.0-preview.1
dotnet add package Wickd.Adapters.Ccxt --version 0.1.0-preview.1

CLI users do not need to install the SDK packages separately.

Fetch and name a reusable historical candle range:

dotnet run --project src/Wickd.Cli -- fetch --market BTC_USDT_PERP --timeframe 5m --from 2026-05-06T00:00:00Z --to 2026-05-07T07:00:00Z --alias may6-session --force

Replay that dataset through the current structure engine:

dotnet run --project src/Wickd.Cli -- backtest --dataset may6-session --run-id phase-3-smoke

List or clean generated local artifacts:

dotnet run --project src/Wickd.Cli -- manage datasets list
dotnet run --project src/Wickd.Cli -- manage datasets delete --alias may6-session --delete-cache
dotnet run --project src/Wickd.Cli -- manage runs list
dotnet run --project src/Wickd.Cli -- manage runs delete --run-id phase-3-smoke --force

Analyze cached candles with the session VWAP indicator without refetching:

dotnet run --project src/Wickd.Cli -- analyze vwap --dataset may6-session --periods daily,weekly --level-periods none

The backtest command currently stops after writing structure events. It does not create setups.jsonl, trades.jsonl, outcomes.jsonl, or analysis.json.

See docs/cli.md for every command, option, and exit code.

Generated Outputs

The WickdAlgo CLI writes generated runtime data under ignored local folders:

data/cache/.../candles.jsonl
data/datasets.json
runs/{runId}/structures.jsonl

• candles.jsonl contains normalized historical candle input.
• data/datasets.json maps friendly aliases to fetched ranges.
• structures.jsonl contains deterministic structure events for one backtest run.

Project Structure

Wickd/
  README.md
  PRODUCT.md
  CHANGELOG.md
  AGENTS.md
  src/
    Wickd.Core/
      Backtesting/
      Data/
      Engines/
      Infrastructure/
      Models/
    Wickd.Adapters.Ccxt/
      CcxtBinanceMarketDataClient.cs
    Wickd.Cli/
      Program.cs
      appsettings.defaults.json
      markets.defaults.json
  tests/
    Wickd.Core.Tests/
    Wickd.Adapters.Ccxt.Tests/
    Wickd.Cli.Tests/
    Wickd.TestSupport/
  docs/
    sprints/
    releases/
    archive/

• src/Wickd.Core/ contains reusable engine, data, model, backtesting, and infrastructure contracts.
• src/Wickd.Adapters.Ccxt/ contains the CCXT-backed Binance market data adapter.
• src/Wickd.Cli/ contains the .NET 10 CLI/global tool entry point and packaged configuration defaults.
• tests/ contains split xUnit coverage for Core, adapter, CLI, and shared test support.
• docs/sprints/ and docs/releases/ hold execution and release scope.
• docs/archive/ preserves superseded historical records.

Configuration

Packaged defaults live beside the CLI project:

src/Wickd.Cli/appsettings.defaults.json
src/Wickd.Cli/markets.defaults.json

• appsettings.defaults.json contains public reference defaults for storage, backtest, setup, trade, settlement, and structure settings.
• markets.defaults.json maps Wickd market IDs, such as BTC_USDT_PERP, to exchange IDs and exchange symbols.
• appsettings.Local.json remains ignored by Git for private repository-local tuning during development, but it is not packaged.

Installed users should edit user-owned copies, not package files. Configuration is never created implicitly, so initialize it before running configuration-dependent commands:

wickd config init
wickd config path

Default user config locations:

Windows: %APPDATA%\Wickd\
macOS: ~/Library/Application Support/Wickd/
Linux: $XDG_CONFIG_HOME/wickd/ or ~/.config/wickd/

Configuration path precedence:

--config <path>
WICKD_CONFIG
user-profile appsettings.json

Each backtest run is for exactly one market and one timeframe.

Documentation

Use source code as the API reference. The maintained documentation set is:

• PRODUCT.md — durable product vision, principles, identity, and governance.
• docs/cli.md — complete CLI command, option, and exit-code reference.
• docs/sprints/ — backlog, current commitments, reviews, and retrospectives.
• docs/releases/ — version scope contracts and package release process.
• CHANGELOG.md — shipped release history.
• AGENTS.md — repository and agent guidance.
• docs/archive/ — superseded historical records.