Skip to content

README.md

Latest commit

 

History

History
191 lines (132 loc) · 11.8 KB

README.md

File metadata and controls

191 lines (132 loc) · 11.8 KB
Raw

Flowdepth — crypto order flow, below the surface

Flowdepth is an independent open-source desktop terminal for crypto order flow and options analytics, built natively in Rust.

Develop CI Latest GitHub release Repository License: GPLv3 Rust 1.95 Made with iced Flowsurface Discord

Flowdepth combines crypto order-flow charts with footprint and L2 heatmap views, adaptive volume bubbles, Binance iceberg/replenishment detection, Deribit GEX, and Derive observed maker flow. A persistent market-data cache, automatic reconnect, and historical gap recovery help charts remain useful through longer sessions and network interruptions.

Important

Beta status: Flowdepth is experimental but usable beta software and is evolving quickly. Back up important layouts before updating. Beta releases may contain regressions. Flowdepth is developed and released independently. It originated from Flowsurface and preserves its Git history, license, and contributor attribution.

Flowdepth desktop terminal showing crypto market charts

Why Flowdepth?

Flowdepth is built for traders and market observers who want deeper crypto order-flow tooling in a native desktop application. Its independent roadmap focuses on richer execution and liquidity visualization, resilient market-data ingestion and recovery, and crypto-options analytics.

Detection and analytics such as possible iceberg activity, GEX, and observed maker flow describe market data; they are not certain trading signals.

Download

Automated beta builds are available from the Flowdepth Releases page. They are generated from the develop branch after the full quality gate succeeds.

Beta builds published before Flowdepth became a standalone repository remain available in the read-only legacy release archive.

For a quick start:

  1. Open the Releases page.
  2. Download the package for your platform: Windows x64, Linux x64, or universal macOS.
  3. Extract the archive.
  4. Run flowsurface.exe on Windows or the flowsurface binary on Linux/macOS.

The application binary and Rust package are currently still named flowsurface for compatibility with the original codebase.

Windows and macOS beta binaries are not currently signed. Windows SmartScreen may require More info → Run anyway. On macOS, control-click the binary and choose Open, or allow it under System Settings → Privacy & Security.

Release channels

  • Beta builds: automated builds from develop, published as GitHub prereleases after formatting, check, Clippy, tests, and all platform packages succeed. Tags use develop-<commit>, where <commit> is the seven-character Git commit identifier used for the build.
  • Stable releases: not currently available.

Key features

  • Order-flow charts: footprint views, historical L2 heatmaps, Time & Sales, DOM/ladder, candlesticks, comparisons, volume profiles, and cumulative volume delta.
  • Adaptive volume bubbles: configurable clustering of aggressive executions with adaptive thresholds, side/delta coloring, bounded labels, and stable live updates.
  • Possible Binance iceberg/replenishment detection: optional markers for evidence of passive absorption on Binance USDⓈ-M perpetuals. The detector is probabilistic, disabled by default, and does not prove that an exchange-native iceberg order exists.
  • News Tracker: multi-source crypto headlines, asset/topic filters, source links and explained impact relevance scores, with optional CryptoPanic integration.
  • Crypto options analytics: BTC, ETH, and SOL GEX profiles sourced from Deribit, plus independently displayed Derive observed maker flow matched to Deribit contracts. SOL uses the linear USDC option chain.
  • Persistent market-data cache: local storage for klines, open interest, trades, and derived bubble summaries with gap detection, deduplication, and invalidation.
  • Connection recovery: automatic reconnect, historical gap backfill, bounded retries, stale-request cancellation, and sequence-aware recovery.
  • Technical studies: RSI, ATR, MACD and ADX/DMI evaluated by the upstream indicator engine, plus a candle-based TPO overlay with session coverage labels.
  • Workspace tools: persistent layouts, saved-state recovery, customizable themes, pane linking, loading/coverage feedback, and an in-app debug terminal.
  • Public market data: market data is received directly from exchange REST APIs and WebSockets. Current features do not require exchange trading credentials.

Historical trades on footprint charts

Live trades are captured over WebSocket. Binance charts can optionally backfill the visible range from data.binance.vision daily files, the paginated REST API, or both. Historical trade fetching for Bybit and Hyperliquid is not available; OKX support remains work in progress.

By default, Flowdepth captures and plots live trades in real time via WebSocket.

To backfill the visible time range on footprint charts, enable trade fetching in Settings → Network. Three modes are available:

  • Exchange: Fetches directly from Binance's public REST API and bulk data mirrors (data.binance.vision). Fast for daily archives; paginated and rate-limited for intraday ranges. Binance only for full history (spot, linear, inverse). MEXC perpetuals can seed the chart from the public recent-deals window (the latest 100 trades); use Server mode for older MEXC history.

  • Server: Fetches from any HTTP server that exposes a GET /trades.arrow endpoint returning an Arrow IPC stream with:

    • Response: Content-Type: application/vnd.apache.arrow.stream

    • Schema (columns matched by name, order not significant):

      ts (int64), price (float64), qty (float64), is_sell (bool)

    • Query parameters: venue, market, symbol, from (inclusive), to (inclusive), limit

    • Optional bearer-token auth: (Authorization: Bearer <token>)

    Self-signed TLS certificates are accepted. Works with all exchanges and has no exchange rate limits. Bring your own data source.

    A reference implementation is available at flowsurface-server, a self-contained collector that writes trades to DuckDB and serves them over this protocol.

  • Off: Live trades only; no historical backfill.

Historical klines, open interest, and ticker metadata/stats are always fetched from exchange REST APIs.
Live trades, orderbook and kline updates are streamed from exchange WebSocket feeds.

Installation

Prebuilt beta packages

Follow the quick-start download steps. Packages contain the application binary and the assets needed by that platform.

Build from source

Requirements:

  • Rust; the pinned version and components are defined in rust-toolchain.toml.
  • Git.
  • Platform dependencies:
    • Debian/Ubuntu: sudo apt install build-essential pkg-config libasound2-dev
    • Arch Linux: sudo pacman -S base-devel alsa-lib
    • Fedora: sudo dnf install gcc make alsa-lib-devel
    • macOS: install Xcode Command Line Tools with xcode-select --install.
    • Windows: use a Rust MSVC toolchain; no additional project dependency is required.

Install directly from the develop branch:

cargo install --git https://github.com/Niketion/flowdepth.git --branch develop flowsurface
flowsurface

Or clone, build, and run the repository:

git clone --branch develop https://github.com/Niketion/flowdepth.git
cd flowdepth
cargo build --release --locked
cargo run --release --locked

The application binary and Rust package are currently still named flowsurface for compatibility with the original codebase. The standalone project is named Flowdepth; internal crate and module names intentionally retain their historical names.

Technical documentation

Development model

develop is Flowdepth's default integration branch and the source of automated beta releases. Feature and fix branches are merged into develop after the formatting, build, Clippy, and test gates pass. Stable releases will use main when a stable channel is introduced.

The repository retains Flowsurface as an optional upstream remote for attribution, review, and selective integration. Because Flowdepth is no longer part of GitHub's fork network, compare the codebases locally when needed:

git remote add upstream https://github.com/flowsurface-rs/flowsurface.git
git fetch upstream
git log --oneline upstream/main..develop
git diff upstream/main...develop

Project lineage

Flowdepth is an independent repository originally derived from Flowsurface. The full shared Git history is intentionally preserved, together with the GPL license and attribution of the original contributors. Flowdepth has its own roadmap, development branches, releases, and support lifecycle.

Flowdepth is not part of the Flowsurface GitHub fork network and is not an official Flowsurface release. The Rust package and executable retain the flowsurface name for source and build compatibility while the migration to standalone project naming is evaluated separately.

Credits

  • Flowsurface and its contributors, whose work forms the historical foundation of Flowdepth.
  • Kraken Desktop, formerly Cryptowatch, which inspired the original project.
  • Halloy, an open-source reference for foundational design and architecture.
  • iced, the Rust GUI library used by the application.

Community

Project updates, source code, and release information are published in this repository. The linked Discord server is operated by the Flowsurface community and is not an official Flowdepth support channel.

Please read the contribution guide and Code of Conduct before contributing.

License

Flowdepth is distributed under the GNU General Public License v3.0 or later, consistent with its Flowsurface foundation. Contributions are shared under the same license.