psyb0t/wickworks repository overview

Source⁠ | Project page⁠

⁠wickworks

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 370 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⁠
• Quick Start⁠
• API⁠
  • GET /health⁠
  • GET /metadata⁠
  • POST / — compute⁠
  • The indicators object⁠
  • Concepts⁠
  • Available indicators⁠
  • Request fields⁠
  • Response⁠
  • Errors⁠
• MCP⁠
• Agent integrations⁠
• Configuration⁠
• Architecture⁠
• Development⁠
• Testing philosophy⁠
• License⁠

⁠What's Inside

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

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

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

⁠docker compose

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

⁠Local development container

make run         # build the dev image and run uvicorn on :8000

⁠API

Three endpoints. That's the whole surface.

⁠GET /health

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

{ "ok": true, "version": "0.7.0" }

⁠GET /metadata

Returns the versioned catalog of labels, descriptions, units, categories, and interpretation notes for every output path. Consumers can cache it for the reported Wickworks version.

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

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, "volume": 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).

"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 uses at most the latest 500 bars, a fixed five-bar separation between distinct touches, and at least two tests within half an ATR. It returns up to three nearest levels on each side of price.
• Order blocks and FVGs expose different state. Order blocks include mitigation state and times so consumers can choose their own freshness rule. FVG output contains only gaps that remain unmitigated.
• BOS vs CHoCH are classifications produced by the configured Smart Money Concepts swing algorithm. A BOS marks a same-direction structural break. A CHoCH marks an opposite-direction break. Neither label proves continuation or reversal.

⁠Available indicators

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.

"ema":   true,
"ema50": { "type": "ema", "length": 50 }

⁠vwap — session-anchored VWAP

Volume-weighted average price, reset at the configured daily, weekly, or monthly anchor. Unlike a rolling average, VWAP accumulates from that fixed boundary. The sessionOffset shifts the UTC anchor by a fixed duration. It does not apply exchange calendars or daylight-saving changes.

Returns: Series.

⁠Momentum oscillators — speed and exhaustion

Measure the rate of price change, not the level itself. Most are bounded (0–100 or centered around zero), so readings are directly comparable across instruments and timeframes. Trader use: spot overbought/oversold extremes (mean-reversion edges), watch for divergence vs price (momentum fading while price extends = reversal hint), trade zero-line / midline crosses as momentum-shift triggers.

⁠Length-based single-line oscillators

Same spec: one length parameter, returns one Series.

cci accepts an extra c parameter (number > 0, default 0.015) — the constant scaling factor in the classic Lambert formula.

⁠uo — Ultimate Oscillator

Williams' combo of three timeframes (short/medium/long) blended into one 0–100 line. Designed specifically to reduce the false signals single-period oscillators give in ranging markets. Watch for divergences and 30/70 extremes — same as RSI but with built-in multi-period confirmation.

Returns: Series (0–100).

⁠stoch — Stochastic oscillator

"Where is the close within the recent high-to-low range?" Returns %K (raw position) and %D (smoothed %K). Classic signals: %K crossing %D is the trigger; both lines above 80 = overbought zone, below 20 = oversold zone. Like RSI but more reactive — fires more often, false-positives more often too.

Returns: { k, d } — each a Series (0–100).

⁠stochrsi — Stochastic of RSI

Stochastic formula applied to RSI values instead of price. Doubly sensitive — fires far more frequently than vanilla stoch and is especially good at picking turning points inside a ranging move. Pair with a trend filter; on its own it overtrades.

Returns: { k, d } — each a Series (0–1, not 0–100).

⁠macd — Moving Average Convergence Divergence

Difference between a fast and slow EMA, plus a signal-line smoothing of that difference. Three lenses: the macd line (raw momentum), the signal line (smoothed), the hist (macd − signal — what most traders actually watch). Hist crossing zero = momentum direction change; hist diverging from price = momentum exhaustion.

Returns: { macd, signal, hist } — each a Series. hist = macd - signal.

⁠tsi / trix / fisher — momentum with signal line

All return the same shape: { <name>: Series, signal: Series }. Watch zero-line crosses and value-vs-signal crosses, same as MACD.

tsi — True Strength Index. Double-smoothed price momentum (close-based). Smoother than MACD, slower to flip — fewer false signals, more lag.

trix — Triple-smoothed exponential ROC. By design it filters out cycles shorter than its length, so it's a longer-term momentum read — useful for higher-timeframe trend confirmation, not scalping.

fisher — Ehlers Fisher Transform. Reshapes price into a Gaussian-like distribution so extremes are sharper and turning points are easier to spot than in RSI.

⁠Trend strength & cross-direction

These don't tell you the price level — they tell you how trendy the market is right now, or which side is in control. Pair them with a price-based indicator: trend-strength tells you whether to trust trend signals at all.

⁠adx — ADX + DMI

Average Directional Index measures trend strength only, not direction. adx rises when one side is winning decisively (regardless of which side). The +DI and -DI lines are the directional pressure components — +DI > -DI = bulls in control, and vice versa. Rule of thumb: adx > 25 = market is trendable, follow signals; adx < 20 = chop, avoid trend strategies and prefer mean-reversion.

Returns: { adx, diPlus, diMinus } — each a Series.

⁠aroon

Race between "how many bars since the highest high?" and "how many bars since the lowest low?", normalized 0–100. up near 100 = recent action keeps making new highs (strong uptrend); down near 100 = recent lows (strong downtrend). oscillator = up - down is the net directional read on the same -100..+100 scale.

Returns: { up, down, oscillator } — up/down are 0–100; oscillator ranges -100..+100.

⁠vortex

Two lines measuring positive (plus) vs negative (minus) true-range movement. Pure trend-flip detector: plus crossing above minus = bullish shift; the inverse = bearish shift. No overbought/oversold concept here.

Returns: { plus, minus } — each a Series.

⁠Volatility

Measure the spread of price action, not its direction. These don't generate buy/sell signals on their own — they're inputs to stop placement (don't set a stop tighter than 1–2 ATR), position sizing (size inversely to volatility so each trade risks the same dollar amount), and regime detection (rising volatility = breakout regime; collapsing volatility = consolidation, watch for squeeze).

⁠Volume / money flow

Volume-derived lines compare price movement with the caller-selected activity series. They can show whether activity expanded or contracted with a move, but they do not identify participants or prove that a breakout is real.

⁠obv and ad — parameterless cumulative lines

No params. Returns: Series.

• obv — On-Balance Volume. Adds volume on up bars, subtracts on down bars. Cumulative running total. When OBV diverges from price (price up, OBV flat or down) = warning sign that the move lacks volume backing.
• ad — Accumulation/Distribution. Weighted by where close lands within the bar's range (close near high = mostly buying; close near low = mostly selling). Cumulative. More precise than OBV when bars have long ranges.

⁠cmf — Chaikin Money Flow

The A/D formula normalized to a rolling window instead of accumulating forever. Returns -1..+1: positive = net accumulation pressure over the window, negative = distribution. Use the zero line as a regime filter — only take longs when CMF is positive.