Wickra Shazam

July 4, 2026 · View on GitHub

Wickra Shazam — match an asset's current microstructure fingerprint against its entire history

Built on Wickra Status CI CodeQL codecov License: MIT OR Apache-2.0 OpenSSF Scorecard OpenSSF Best Practices Build provenance Docs Live demo

Wickra Shazam

Point at live data → "that's the May-2021 crash setup". Match the current microstructure fingerprint of an asset against its entire history.

▶ Live demo: all 514 indicators over real Binance market data, computed live in your browser — live.wickra.org · zero backend, powered by wickra-wasm.

Part of the Wickra ecosystem: the same data-driven core and ten-language binding surface also power wickra-exchange, wickra-backtest, wickra-terminal, wickra-screener, wickra-xray, wickra-radar, wickra-copilot and wickra-shazam.

Wickra Shazam turns an asset's whole history into a rolling index of fixed-dimension microstructure fingerprints — a vector built from the full Wickra feature space (indicators, price, and microstructure: order-book imbalance, funding, open interest, liquidations, footprint) — and matches the current fingerprint against that entire index to name the regime. It is pattern/regime recognition over the full feature space, not price alone.

  • The fingerprint is data — a serde FingerprintSpec (an ordered feature list + window + normalize + metric), not Rust closures, so it crosses the C ABI and WASM unchanged. A fixed dimension N is what makes it deterministic.
  • Deterministic core — indexing and matching are byte-identical across all ten languages and between the parallel (rayon) and sequential (WASM) builds.
  • Three operations, one core — index(history, spec) builds the rolling index, match_current(index, current, k) finds the k most similar historical fingerprints, and a label attaches a human name ("may_2021_crash") to a match.

The core is one library (shazam-core), usable from Rust, Python, Node.js, WASM, C, C++, C#, Go, Java and R over a JSON-over-C-ABI boundary, plus a reference CLI.

Status

Pre-release — functionally complete, CI-verified, not yet published. The core, the CLI, all ten language bindings, the byte-exact golden corpus, property + fuzz tests, benchmarks and one runnable example per language are in place and green across the full CI matrix (10 languages × 3 OS). Not yet released to any registry — track progress in ROADMAP.md.

Documentation

Quickstart

# Index a history and match the current state, human-readable table:
cargo run -p wickra-shazam -- --spec golden/specs/crash_setup.json \
  --history golden/data/history/sym-01.csv --current golden/data/current/sym-01.csv

# Raw MatchReport JSON (the same bytes every binding returns), top 5 matches:
cargo run -p wickra-shazam -- --spec golden/specs/price_euclid.json \
  --history golden/data/history/sym-01.csv --k 5 --format json

--current defaults to the last window bars of --history. Attach a label to a historical bar with --label <ts>=<name> (repeatable) and it comes back on any match at that timestamp.

FingerprintSpec / features

A spec is a JSON (or TOML) document: an ordered features list, a window, a normalize mode and a metric. The feature order is the vector's axis order and never changes within an index, so the dimension N = features.len() * window is fixed and the fingerprint is fully deterministic.

{
  "features": [
    { "kind": "indicator", "name": "Rsi", "params": [14] },
    { "kind": "indicator", "name": "Sma", "params": [20] },
    { "kind": "indicator", "name": "Atr", "params": [14] },
    { "kind": "price", "field": "close" },
    { "kind": "price", "field": "volume" }
  ],
  "window": 1,
  "normalize": "z_score",
  "metric": "cosine"
}
  • indicator — any PascalCase Wickra indicator resolved from the registry by name + params (Rsi, Sma, Atr, Macd, …), with an optional field to pick a sub-output of a multi-output indicator.
  • price — a raw OHLCV field (open/high/low/close/volume).
  • microstructure — an order-book / flow feature (imbalance, funding, open interest, liquidations, footprint), resolved from the same registry.
  • window — how many consecutive bars are stacked into one fingerprint (1 = the current bar only; > 1 = a short shape).

Similarity & metrics

The metric decides how two fingerprints are compared. Similarity is always mapped to [0, 1] (1 = identical) and rounded deterministically:

  • cosine — cosine of the angle between the flat vectors, mapped from [-1, 1] to [0, 1] via (cos + 1) / 2. Scale-insensitive; good with z_score normalization.
  • euclid — 1 / (1 + d) where d is the L2 distance. Scale-sensitive; pair with min_max or z_score to weight features evenly.
  • dtw — dynamic time warping over the per-bar feature vectors of a window > 1 spec, tolerant of small time shifts between two shapes. With window == 1 it is identical to euclid.

normalize (none · z_score · min_max) is fitted once over the whole index and reused for the current fingerprint, so history and query live on the same axes.

Labels

A label attaches a human-readable name to a historical timestamp; when a match lands on that bar the name rides along in the report:

{ "cmd": "label", "ts": 1700216000, "label": "may_2021_crash" }
// → a later match at ts 1700216000 comes back as
//   { "ts": 1700216000, "similarity": 0.98, "label": "may_2021_crash" }

Use in any language

The same Shazam handle — construct from a JSON spec, drive with command(json) -> json, read version — is reachable from every binding. The commands are set_spec, index, match, label, reset and version; index returns {"indexed":N} and match returns a MatchReport that is byte-identical to the CLI's --format json.

from wickra_shazam import Shazam
s = Shazam('{"features":[{"kind":"price","field":"close"}],'
           '"window":1,"metric":"euclid"}')
s.command('{"cmd":"index","history":[/* candles */]}')
report = s.command('{"cmd":"match","current":[/* candles */],"k":5}')  # JSON MatchReport

The C ABI hub (bindings/c) backs C, C++, C#, Go, Java and R; Rust, Python, Node.js and WASM are native. See each bindings/<lang>/README.md and the runnable examples/.

Project layout

crates/shazam-core     the deterministic core (FingerprintSpec, index, match_current, labels)
crates/shazam-cli      the CLI (bin: wickra-shazam)
crates/shazam-bench    criterion benchmarks
bindings/{python,node,wasm,c,go,csharp,java,r}   the ten-language surface
golden/                CSV histories, current windows, specs, and byte-exact expected reports
fuzz/                  cargo-fuzz targets (spec_parse, build_index, match_index, normalize_metric)
examples/              one runnable "index a history and match the current state" example per language

Building from source

cargo build --workspace
cargo test  --workspace --all-features
cargo test  --workspace --no-default-features   # sequential (WASM) index/match path
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo run -p wickra-shazam -- --spec golden/specs/crash_setup.json \
  --history golden/data/history/sym-01.csv

Requirements

  • Rust ≥ 1.86 (workspace MSRV; the Node binding needs ≥ 1.88).
  • Binding toolchains as needed: Node ≥ 22, Python ≥ 3.9, a C toolchain, .NET 8, JDK 22+, Go 1.23, R — see each bindings/<lang>/README.md.

Benchmarks

crates/shazam-bench measures build_index scaling by history length and feature count, and match_index by index size and metric (cosine / euclid / dtw), parallel vs sequential. See BENCHMARKS.md.

Ecosystem

Part of the Wickra family — each one a data-driven core with a CLI and the same ten-language binding surface:

  • wickra — the core library: 514 O(1) streaming indicators across ten languages
  • wickra-exchange — unified market-data + execution across ten crypto exchanges
  • wickra-backtest — event-driven backtester over the Wickra core
  • wickra-terminal — the trading terminal: a TUI and a browser renderer over the stack
  • wickra-screener — parallel multi-symbol screening over 514 streaming indicators
  • wickra-xray — market-microstructure explorer: footprint, order-book heatmap, liquidation map, funding/OI divergence
  • wickra-radar — perp-universe alert radar: OI delta, funding flip, book imbalance, liquidation clusters, OI/price divergence
  • wickra-copilot — local market copilot grounded in real order-book, liquidation and funding microstructure
  • wickra-shazam — match an asset's current microstructure fingerprint against its entire history

Docs at docs.wickra.org; the marketing site and in-browser demo at wickra.org.

Contributing

See CONTRIBUTING.md and CODE_OF_CONDUCT.md. Commits are signed and in English; open a PR against main.

Security

See SECURITY.md and THREAT_MODEL.md. Report vulnerabilities privately — never in a public issue.

License

Dual-licensed under either MIT or Apache-2.0, at your option.

Disclaimer

Wickra Shazam is analysis software: it computes similarity between market states. A historical match is a statistical resemblance, not a prediction and not financial advice — the past setup did not have to repeat, and neither does this one. It places no orders. Trading carries risk of loss; review the code and use at your own discretion.