Wickra X-Ray

A free explorer that shows, historically, what only Wickra computes — footprint, order-book heatmap, liquidation map and funding/OI divergence.

▶ 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 and 20 more — see the full list.

Wickra X-Ray is one data-driven core, wickra-xray-core: a serde XraySpec is folded over a recorded dataset — trades, order-book diffs, funding and open interest — into render data-models (XrayFrame), never renderer commands. The frames carry the four microstructure panels; a front-end just draws them. The parallel (rayon) and sequential (the WASM fallback) builds are byte-for-byte identical.

Because the frame is data, not code, the exact same output crosses the C ABI and WASM unchanged. The core is exposed as a JSON-over-C-ABI data API (Xray::command) in Rust, Python, Node.js, WASM, C, C++, C#, Go, Java and R, and a web front-end (Vue + Canvas) renders the frames in the browser.

• Footprint — traded volume per price bin, split by aggressor side.
• Order-book heatmap — resting liquidity over a time × price grid.
• Liquidation map — liquidation events clustered by price bin.
• Funding / OI divergence — funding, open interest and price on one time axis.

use wickra_xray_core::{build_frame, Dataset, Xray, XraySpec};

// The full window: fold the whole dataset and build every panel the spec names.
let spec: XraySpec = XraySpec::from_json(spec_json)?;
let mut dataset = Dataset::from_json(dataset_json)?;
dataset.sort();
let cursor = dataset.bounds().map_or(0, |(_, hi, _)| hi);
let frame = build_frame(&dataset, &spec, cursor)?;

// Scrubbing: the same spec and dataset, folded to any moment. `frame_at(t)`
// returns exactly what the full window would return over a dataset ending at t.
let mut xray = Xray::new(spec_json)?;
xray.command_json(&format!(r#"{{"cmd":"load","dataset":{dataset_json}}}"#))?;
let earlier = xray.command_json(r#"{"cmd":"frame_at","ts":1700000000000}"#)?;

Status

0.1.1 — the current release. The core, the CLI, all ten language bindings, the web renderer, 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). ROADMAP.md has what is done, what is open and what is not planned.

Documentation

• Architecture — the core, the data-driven boundary, the binding surface.
• Panel & spec reference and per-binding quickstarts under docs/; one runnable example per language under examples/.
• ROADMAP.md · BENCHMARKS.md · THREAT_MODEL.md · SECURITY.md.

Quickstart

# Build a frame from a spec + a recorded dataset, raw XrayFrame JSON
# (the same bytes every binding returns):
cargo run -p wickra-xray -- --spec golden/specs/footprint.json --stdin --format json < golden/data.json

# Human-readable summary of the frame:
cargo run -p wickra-xray -- --spec golden/specs/multi_panel.json --stdin < golden/data.json

The --spec file is an XraySpec; the dataset is read from --stdin (a JSON Dataset) or from a --data file.

XraySpec / panels

A spec is a JSON (or TOML) document: a symbol, an optional time window (from_ts / to_ts), and a list of panels. Each panel names a kind and its parameters; the frame returns one PanelData per spec panel, in order.

{
  "dataset_ref": "gold",
  "symbol": "GOLD",
  "panels": [
    { "kind": "footprint", "price_bin": 1.0, "bucket_ms": 60000 },
    { "kind": "book_heatmap", "price_bin": 0.5, "bucket_ms": 2000, "depth_levels": 8 },
    { "kind": "liquidation_map", "price_bin": 1.0 },
    { "kind": "funding_oi_divergence", "bucket_ms": 2000 }
  ]
}

• Panels (kind): footprint, book_heatmap, liquidation_map, funding_oi_divergence.
• Frame — XrayFrame { symbol, cursor_ts, panels }; each PanelData is a render data-model (price bins, intensity matrices, event lists), never a draw command.

Scrubbing through time

The frame is addressable in time. frame builds the full window; frame_at(ts) folds only up to a cursor — the scrubber path a front-end drives as the user drags through history. frame_at(to_ts) reproduces frame byte-for-byte, and every panel's arrays stay length-aligned and monotonic on their axis.

Use in any language

The same Xray handle — construct from a JSON spec, drive with command(json) -> json, read version — is reachable from every binding:

from wickra_xray import Xray
x = Xray('{"dataset_ref":"m","symbol":"AAA","panels":['
         '{"kind":"footprint","price_bin":1.0,"bucket_ms":60000}]}')
x.command('{"cmd":"load","dataset":{"trades":[...]}}')
frame = x.command('{"cmd":"frame"}')  # JSON XrayFrame

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/wickra-xray-core    the data-driven core (XraySpec, Dataset, panels, build_frame, command_json)
crates/xray-cli     the CLI (bin: wickra-xray)
crates/wickra-xray-bench   criterion benchmarks
bindings/{python,node,wasm,c,go,csharp,java,r}   the ten-language surface
web/                the Vue + Canvas browser renderer (over the WASM binding)
golden/             a deterministic dataset, specs, and byte-exact expected frames
fuzz/               cargo-fuzz targets (spec_parse, dataset_parse, build_frame, book_fold)
examples/           one runnable "build a frame" example per language

Building everything from source

The Rust core, the CLI and the WASM package build from the workspace; each binding has its own toolchain and builds on its own.

# Rust core, CLI, C ABI, WASM crate
cargo build --workspace --all-features

# The fuzz crate is a detached workspace (cargo-fuzz builds it with sanitizer
# flags on nightly), so --workspace does not reach it.
cargo check --manifest-path fuzz/Cargo.toml

# Python: an abi3 wheel via maturin
python -m venv .venv && . .venv/bin/activate
pip install maturin pytest
maturin develop --release -m bindings/python/Cargo.toml

# Node.js: a native addon via napi-rs
( cd bindings/node && npm ci && npm run build )

# WASM: a browser/bundler package via wasm-pack
wasm-pack build bindings/wasm --target bundler --out-dir pkg

# C ABI: the cdylib and staticlib every non-native binding links against
cargo build -p wickra-xray-c --release

# C / C++: the example harness, which is also the header smoke test
cmake -S examples/c -B examples/c/build && cmake --build examples/c/build

# C# / Go / Java / R link the C ABI above; each needs it built first
( cd bindings/csharp && dotnet build )
( cd bindings/go && go build ./... )
( cd bindings/java && mvn -q package )
R CMD INSTALL bindings/r

# The web front-end that renders the frames
( cd web && npm ci && npm run build )

The R package resolves the C ABI itself: configure downloads the wickra-xray-c-<triple>.tar.gz asset matching its version and bundles the shared library. Set WKXRAY_INC and WKXRAY_LIB to build against a locally built one instead.

Testing

# The core, in both build paths — they must agree byte for byte
cargo test --workspace --all-features
cargo test --workspace --no-default-features

cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo clippy --workspace --all-targets --no-default-features -- -D warnings
cargo fmt --all --check
cargo deny check

# Per binding
"$(pwd)/.venv/bin/python" -m pytest bindings/python/tests -q
( cd bindings/node && npm test )
( cd bindings/go && go test ./... )
( cd bindings/java && mvn -q test )
( cd bindings/csharp && dotnet test )
Rscript bindings/r/tests/run_tests.R
Rscript bindings/r/tests/golden.R          # golden parity: run from the repo root
ctest --test-dir examples/c/build --output-on-failure

# Fuzzing (nightly)
cargo +nightly fuzz run spec_parse -- -max_total_time=30

Every binding runs the same committed corpus under golden/ and has to reproduce each expected frame byte for byte — that is what makes the cross-language claim checkable rather than asserted. Regenerating those files is the bless loop in golden/README.md, and the diff is meant to be read before it is committed.

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 ≥ 2.10 — see each bindings/<lang>/README.md.

Benchmarks

crates/wickra-xray-bench measures build_frame scaling by event count and panel count, 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 — main library (Rust core + Python / Node.js / WASM bindings + a C ABI for C / C++ / C# / Go / Java / R)
• wickra-playground — a polyglot strategy playground: one StrategySpec live side by side in Python, Rust, JS and Go, entirely in the browser
• 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-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
• wickra-benchmark — reproducible, golden-verified benchmark suite — recompute any (strategy, dataset, report) in ten languages and confirm it byte-for-byte
• wickra-strategy-ci — Jest for trading strategies: golden-pin the report, catch regressions in CI, property-test against fuzzed data
• wickra-verify — confirm or refute a claimed backtest report against its strategy and data, in ten languages
• wickra-proof — Proof-of-Backtest: deterministic (spec, data) → report + blake3 hash, recomputable byte-for-byte in ten languages
• wickra-zk — prove a backtest zero-knowledge — on-chain-verifiable performance without revealing the data or the strategy
• wickra-impact — the backtester that knows you would have moved the market: agent-based fills on the real historical L2 order book
• wickra-darwin — evolutionary strategy search at millions of backtests per second, mutating and crossing JSON specs across the 514-indicator space
• wickra-gym — a Gymnasium-compatible, microstructure-aware backtest environment with O(1) steps for deterministic RL rollouts
• wickra-feature-store — OHLCV and microstructure streams into ML-ready feature matrices over 514 O(1) streaming indicators
• wickra-genome — a vector database of the whole market: every asset a 514-dim live vector, for similarity search, clustering and anomaly detection
• wickra-timemachine — scrub the whole market like a video — every symbol, full order book, rewound to any moment via deterministic re-fold
• wickra-synth — deterministic synthetic market microstructure: OHLCV, order book, trades and funding from a single seed
• wickra-compile — compile a strategy spec into a standalone deployable: a WASM module, a self-contained binary, or a no_std artifact
• wickra-embed — allocation-free, no_std streaming indicators for bare-metal and HFT, byte-for-byte identical to the core
• wickra-pico — the O(1) indicator core running bare-metal on a $5 Raspberry Pi Pico — the LED blinks on the EMA cross

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 X-Ray is analysis software: it computes microstructure views over historical and live market data. It is provided "as is", without warranty of any kind, and is not financial advice — it places no orders. Trading carries risk of loss; review the code and use at your own discretion.