docker-wickworks

# wickworks

[![Docker Pulls](https://img.shields.io/docker/pulls/psyb0t/wickworks)](https://hub.docker.com/r/psyb0t/wickworks)
[![License: WTFPL](https://img.shields.io/badge/License-WTFPL-brightgreen.svg)](LICENSE)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.136-009688.svg)](https://fastapi.tiangolo.com/)

The dumb-as-rocks OHLC analyzer. You throw bars at it over HTTP, it throws indicators and SMC objects back. That's the whole product. No database, no queue, no state, no opinions, no "AI-powered signals," no upsell to a $97/mo Discord. Just primitives.

Every snake-oil-flavored TA SaaS out there wants to tell you when to buy. Wickworks tells you the order block is at 1.0832 and the RSI is 71.4. The "what does that mean?" part is where your strategy lives — and it should live in your code, not behind someone else's paywall.

Built on `pandas_ta` and `smartmoneyconcepts`, wrapped in a FastAPI server, locked behind 280+ tests that diff our output against closed-form references on real EURUSD ticks. If a math bug slips in, the test suite screams before the container builds.

## Table of Contents

- [What's Inside](#whats-inside)
- [Quick Start](#quick-start)
- [API](#api)
  - [`GET /health`](#get-health)
  - [`POST /` — compute](#post---compute)
  - [The `indicators` object](#the-indicators-object--the-whole-point)
  - [Concepts](#concepts)
  - [Available indicators](#available-indicators)
  - [Request fields](#request-fields)
  - [Response](#response)
  - [Errors](#errors)
- [MCP](#mcp)
- [Configuration](#configuration)
- [Architecture](#architecture)
- [Development](#development)
- [Testing philosophy](#testing-philosophy)
- [License](#license)

## What's Inside

| Category        | Primitives                                                                                                                    |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Trend**       | SMA/EMA + 15 other moving averages, slope, Donchian channels, Ichimoku                                                        |
| **Momentum**    | RSI, MACD, Stochastic, StochRSI, ADX, MFI, CCI, Williams %R, ROC, MOM, TSI, TRIX, UO, Fisher                                  |
| **Volatility**  | ATR, NATR, Bollinger Bands, Keltner Channels, Squeeze                                                                         |
| **Volume**      | VWAP (anchored), VWMA, OBV, AD, ADOSC, CMF, KVO                                                                               |
| **SMC**         | Order Blocks, Fair Value Gaps, BOS/CHoCH, swing structure, S/R levels, liquidity, retracements, sessions, previous-period H/L |
| **Summaries**   | Position, slope, momentum, volume regime, recent range — pre-baked projections over the raw series                            |

All JSON field names are camelCase. Output is NaN-safe — `NaN` becomes `null`, never a literal `NaN` token that blows up downstream parsers. NumPy/Pandas scalars and arrays are serialized cleanly (no `numpy.float64(...)` leaks). Bars in UTC, math in UTC, container runs `TZ=UTC` — timezone bullshit is your problem, not ours.

## Quick Start

```bash
docker run --rm -p 8000:8000 psyb0t/wickworks:latest
```

That's it. The service listens on `:8000`.

### docker compose

```yaml
services:
  wickworks:
    image: psyb0t/wickworks:latest
    ports: ["8000:8000"]
    environment:
      LOG_LEVEL: INFO
      MAX_BARS: "5000"
      MIN_BARS: "50"
```

### Local (uv-based)

```bash
make install     # uv sync from lockfile (supply-chain-pinned, see below)
make run         # uvicorn on :8000
```

## API

Two endpoints. That's the whole surface.

### `GET /health`

```bash
curl -s http://localhost:8000/health
```

```json
{ "ok": true, "version": "0.3.2" }
```

### `POST /` — compute

Send OHLC(V) bars + the indicators you want. Get back **only what you asked for** — response keys mirror the keys you sent. No "let me also throw in 40 indicators you didn't ask for" energy.

```bash
curl -s -X POST http://localhost:8000/ \
  -H 'Content-Type: application/json' \
  -d '{
    "symbol": "EURUSD",
    "timeframe": "H1",
    "bars": [
      { "time": 1700000000, "open": 1.0832, "high": 1.0851, "low": 1.0828, "close": 1.0844, "tickVolume": 1247 },
      ...
    ],
    "indicators": {
      "rsi":         true,
      "rsi21":       { "type": "rsi",   "length": 21 },
      "stochFast":   { "type": "stoch", "k": 5,  "d": 3, "smoothK": 3 },
      "stochSlow":   { "type": "stoch", "k": 21, "d": 7, "smoothK": 5 },
      "macd":        true,
      "orderBlocks": true,
      "fvg":         true
    }
  }'
```

### The `indicators` object — the whole point

Each entry maps an **output name** (the key) to a **spec**:

- `true` — run the indicator with default params; key doubles as the type.
- `{ ...params }` — params object; missing `type` falls back to the key.
- `{ "type": "<name>", ...params }` — run a known indicator under a custom output name. This is how you stack multiple instances of the same indicator (e.g. four stochs with different params, three EMAs at different lengths).

```json
"indicators": {
  "rsi":    true,
  "rsi21":  { "type": "rsi",   "length": 21 },
  "stochA": { "type": "stoch", "k": 5,  "d": 3 },
  "stochB": { "type": "stoch", "k": 21, "d": 7 }
}
```

The response contains `rsi`, `rsi21`, `stochA`, `stochB`. Nothing else. Duplicate output names are physically impossible by JSON-object construction — you can't shoot yourself in the foot with this API even if you try.

### Concepts

The outputs below map to a handful of recurring trading ideas. If you've used any TradingView-style charting tool most of these will be familiar; if not, the short framing here is enough to pick the right output for the job.

**Series vs events.** A _Series_ output is one value per input bar (warmup positions are `null`) — these are continuous quantities you can chart. An _event_ output is a sparse array of objects pinpointing things that just happened (a swing, a block, a structure break). Series tell you _state_; events tell you _occurrences_.

**Primitives only — no signals.** Wickworks does not emit interpretive signals (no divergence detection, no MA-cross events, no "buy/sell" tags). Everything returned is either a raw indicator series, a structural fact (an order block was formed at this bar, price closed past this swing), or a pre-baked summary over those — never a judgment about what to do. If you want divergences, MACD-cross events, golden/death crosses, or any other derived signal, build that layer in your own consumer.

**The four questions every indicator answers part of:**

1. **What's the trend?** → Moving averages, ADX, supertrend, ichimoku.
2. **Is momentum behind it?** → RSI, MACD, stochastic, MFI.
3. **How much room is there?** → ATR, Bollinger Bands, Donchian, Keltner.
4. **Is volume backing it up?** → OBV, CMF, A/D, KVO, VWAP.

**In-house event constructs you won't find on TradingView:**

- **`srLevels`** — support / resistance construction: take pivot levels from a 7-bar swing detector (`sw7`), keep only those that price has tested at least **twice** (within ½·ATR of the level), enforce **≥3·ATR spacing** between kept levels so you don't get three nearly-identical levels stacked together, return up to 3 nearest above current price (resistance) and 3 nearest below (support).
- **Order block / FVG `mitigated` filter** — a zone is _unmitigated_ when price has not yet traded back into it since formation. We return **only unmitigated zones** — the live, untested ones. A mitigated zone is consumed history; it's filtered out of the response.
- **BOS vs CHoCH** — both come from Smart-Money-Concepts structural analysis. **BOS** (Break of Structure) = trend continuation: the most recent swing in the trend's direction is taken out (uptrend breaks the prior higher-high; downtrend breaks the prior lower-low). **CHoCH** (Change of Character) = trend reversal: price breaks _against_ the prior trend's structure for the first time (uptrend breaks a swing low; downtrend breaks a swing high). BOS = "trend is still alive"; CHoCH = "trend just died." These are structural facts (a level was crossed) — interpreting "alive" vs "died" is the consumer's job.

### Available indicators

> Want the formal contract for tooling / validators? See [`schema.json`](schema.json) — full JSON Schema Draft 2020-12. The reference below is the human version: categories + per-indicator blurbs + params tables + return shapes + examples.

**Three series shapes are shared across most outputs:**

- **Series** — one value per bar (`number | null`), aligned 1:1 with input `bars`. Warmup positions are `null`.
- **FlagSeries** — one `0/1` integer per bar.
- **DirectionSeries** — one `-1/+1` integer per bar (`1` = bullish/long, `-1` = bearish/short).

Indicators below are grouped by what they tell a trader, not by parameter shape. Each subsection starts with a one-paragraph framing of the category, then lists every indicator in it with a short "what it is / when to use it" blurb.

---

#### Moving averages — trend bias and dynamic levels

Smoothed price lines. Each flavor trades **responsiveness against lag** differently — pick by how fast you want the curve to react to new bars. Trader use: define the dominant direction (price above/below the MA = bull/bear bias), identify dynamic support/resistance the market keeps touching, fire crossover signals (fast MA crossing slow MA = trend shift).

All take a single `length` parameter and return a Series.

| `type`   | default | inputs      | what it is                                                                                                              |
| -------- | ------: | ----------- | --------------------------------------------------------------------------------------------