flowex 0.1.0__tar.gz

flowex-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KhavrTrading
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

flowex-0.1.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: flowex
+Version: 0.1.0
+Summary: Real-time multi-exchange crypto market data in Python — WebSocket streaming, order book metrics, and per-symbol actor workers for Binance, Bybit, and Bitget.
+Author: KhavrTrading
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/KhavrTrading/flowex-py
+Project-URL: Repository, https://github.com/KhavrTrading/flowex-py
+Project-URL: Issues, https://github.com/KhavrTrading/flowex-py/issues
+Keywords: crypto,trading,market-data,websocket,binance,bybit,bitget,order-book,depth,real-time,go,cgo
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# flowex
+
+[![CI](https://github.com/KhavrTrading/flowex-py/actions/workflows/build.yml/badge.svg)](https://github.com/KhavrTrading/flowex-py/actions/workflows/build.yml)
+[![PyPI](https://img.shields.io/pypi/v/flowex)](https://pypi.org/project/flowex/)
+[![Python](https://img.shields.io/pypi/pyversions/flowex)](https://pypi.org/project/flowex/)
+[![License](https://img.shields.io/github/license/KhavrTrading/flowex-py)](LICENSE)
+
+Real-time multi-exchange crypto market data for Python — powered by Go via cgo shared library. WebSocket streaming, order book metrics, and per-symbol actor workers for Binance, Bybit, and Bitget.
+
+No subprocess, no gRPC, no serialization overhead on the hot path. The Go runtime lives inside the Python process. Every symbol gets its own goroutine. `get_snapshot()` hits the atomic store directly.
+
+## Install
+
+```bash
+pip install flowex
+```
+
+## Quick start
+
+```python
+import time
+from flowex import Manager
+
+mgr = Manager("binance")
+mgr.subscribe(["BTCUSDT", "ETHUSDT", "SOLUSDT"])
+time.sleep(2)
+
+snap = mgr.get_snapshot("BTCUSDT")
+print(snap.depth.spread_bps)
+print(snap.depth.mid_price)
+print(snap.candles[-1].close)
+
+mgr.close()
+```
+
+Or use as a context manager:
+
+```python
+with Manager("binance") as mgr:
+    mgr.subscribe(["BTCUSDT"])
+    time.sleep(2)
+    snap = mgr.get_snapshot("BTCUSDT")
+```
+
+## Supported exchanges
+
+- **Binance** — futures WebSocket (candles, depth, aggTrade)
+- **Bybit** — linear futures WebSocket
+- **Bitget** — USDT futures WebSocket
+
+## API
+
+### `Manager(exchange)`
+
+Create a manager for an exchange. Initializes the Go runtime and WebSocket connections.
+
+```python
+mgr = Manager("binance")  # or "bybit", "bitget"
+```
+
+### `mgr.subscribe(symbols)`
+
+Subscribe to one or more symbols. Starts candle, depth, and trade streams for each.
+
+```python
+mgr.subscribe("BTCUSDT")
+mgr.subscribe(["BTCUSDT", "ETHUSDT", "SOLUSDT"])
+```
+
+### `mgr.get_snapshot(symbol) -> Snapshot | None`
+
+Get the latest point-in-time snapshot for a symbol.
+
+```python
+snap = mgr.get_snapshot("BTCUSDT")
+snap.timestamp      # Unix ms
+snap.depth          # DepthMetrics
+snap.candles        # list[CandleHLCV]
+snap.trades         # list[NormalizedTrade]
+```
+
+### `mgr.get_all_snapshots() -> dict[str, Snapshot]`
+
+Get snapshots for all subscribed symbols in one call.
+
+### `mgr.unsubscribe(symbol)`
+
+Remove all streams for a symbol.
+
+### `mgr.close()`
+
+Shutdown all managers and WebSocket connections.
+
+## Data models
+
+### `DepthMetrics`
+
+Order book metrics computed from raw depth data:
+
+| Field | Description |
+|-------|-------------|
+| `mid_price` | (best_bid + best_ask) / 2 |
+| `spread_bps` | Spread in basis points |
+| `bid_liquidity_10` | USD liquidity, top 10 bid levels |
+| `ask_liquidity_10` | USD liquidity, top 10 ask levels |
+| `imbalance_ratio_10` | bid_liq / ask_liq (>1 = bullish) |
+| `slippage_buy_10k` | Estimated slippage % for $10k buy |
+
+Plus 70+ more fields: liquidity at 5/10/20/50 levels, volumes, imbalance deltas, largest walls, slippage at 8 USD sizes, velocity, momentum, z-scores, and depth quality metrics.
+
+### `CandleHLCV`
+
+```python
+candle.ts       # Unix ms
+candle.open
+candle.high
+candle.low
+candle.close
+candle.volume
+```
+
+### `NormalizedTrade`
+
+```python
+trade.timestamp  # Unix ms
+trade.price
+trade.size
+trade.side       # "buy" or "sell"
+trade.symbol
+```
+
+## Architecture
+
+```
+Python process
+|
++-- ctypes loads libflowex.so  <--  Go runtime starts inside Python
+|                                    |
+|                                    +-- Manager (binance)
+|                                    |     +-- Worker: BTCUSDT -> atomic snapshot
+|                                    |     +-- Worker: ETHUSDT -> atomic snapshot
+|                                    |     +-- Worker: SOLUSDT -> atomic snapshot
+|                                    |
+|                                    +-- Manager (bybit)
+|                                          +-- Worker: BTCUSDT -> atomic snapshot
+|
++-- mgr.subscribe(["BTCUSDT"])     ->  FlowexSubscribeBatch()
++-- mgr.get_snapshot("BTCUSDT")    ->  FlowexGetSnapshot() -> atomic.Load -> JSON -> Python
++-- mgr.get_all_snapshots()        ->  FlowexGetSnapshots() -> one call, all symbols
+```
+
+## Build from source
+
+Requires Go 1.22+ and Python 3.10+.
+
+```bash
+# macOS (Apple Silicon)
+make build-mac
+
+# Linux (amd64)
+make build-linux
+
+# All platforms (requires cross-compilers)
+make build-all
+```
+
+## License
+
+MIT

flowex-0.1.0/README.md

@@ -0,0 +1,169 @@
+# flowex
+
+[![CI](https://github.com/KhavrTrading/flowex-py/actions/workflows/build.yml/badge.svg)](https://github.com/KhavrTrading/flowex-py/actions/workflows/build.yml)
+[![PyPI](https://img.shields.io/pypi/v/flowex)](https://pypi.org/project/flowex/)
+[![Python](https://img.shields.io/pypi/pyversions/flowex)](https://pypi.org/project/flowex/)
+[![License](https://img.shields.io/github/license/KhavrTrading/flowex-py)](LICENSE)
+
+Real-time multi-exchange crypto market data for Python — powered by Go via cgo shared library. WebSocket streaming, order book metrics, and per-symbol actor workers for Binance, Bybit, and Bitget.
+
+No subprocess, no gRPC, no serialization overhead on the hot path. The Go runtime lives inside the Python process. Every symbol gets its own goroutine. `get_snapshot()` hits the atomic store directly.
+
+## Install
+
+```bash
+pip install flowex
+```
+
+## Quick start
+
+```python
+import time
+from flowex import Manager
+
+mgr = Manager("binance")
+mgr.subscribe(["BTCUSDT", "ETHUSDT", "SOLUSDT"])
+time.sleep(2)
+
+snap = mgr.get_snapshot("BTCUSDT")
+print(snap.depth.spread_bps)
+print(snap.depth.mid_price)
+print(snap.candles[-1].close)
+
+mgr.close()
+```
+
+Or use as a context manager:
+
+```python
+with Manager("binance") as mgr:
+    mgr.subscribe(["BTCUSDT"])
+    time.sleep(2)
+    snap = mgr.get_snapshot("BTCUSDT")
+```
+
+## Supported exchanges
+
+- **Binance** — futures WebSocket (candles, depth, aggTrade)
+- **Bybit** — linear futures WebSocket
+- **Bitget** — USDT futures WebSocket
+
+## API
+
+### `Manager(exchange)`
+
+Create a manager for an exchange. Initializes the Go runtime and WebSocket connections.
+
+```python
+mgr = Manager("binance")  # or "bybit", "bitget"
+```
+
+### `mgr.subscribe(symbols)`
+
+Subscribe to one or more symbols. Starts candle, depth, and trade streams for each.
+
+```python
+mgr.subscribe("BTCUSDT")
+mgr.subscribe(["BTCUSDT", "ETHUSDT", "SOLUSDT"])
+```
+
+### `mgr.get_snapshot(symbol) -> Snapshot | None`
+
+Get the latest point-in-time snapshot for a symbol.
+
+```python
+snap = mgr.get_snapshot("BTCUSDT")
+snap.timestamp      # Unix ms
+snap.depth          # DepthMetrics
+snap.candles        # list[CandleHLCV]
+snap.trades         # list[NormalizedTrade]
+```
+
+### `mgr.get_all_snapshots() -> dict[str, Snapshot]`
+
+Get snapshots for all subscribed symbols in one call.
+
+### `mgr.unsubscribe(symbol)`
+
+Remove all streams for a symbol.
+
+### `mgr.close()`
+
+Shutdown all managers and WebSocket connections.
+
+## Data models
+
+### `DepthMetrics`
+
+Order book metrics computed from raw depth data:
+
+| Field | Description |
+|-------|-------------|
+| `mid_price` | (best_bid + best_ask) / 2 |
+| `spread_bps` | Spread in basis points |
+| `bid_liquidity_10` | USD liquidity, top 10 bid levels |
+| `ask_liquidity_10` | USD liquidity, top 10 ask levels |
+| `imbalance_ratio_10` | bid_liq / ask_liq (>1 = bullish) |
+| `slippage_buy_10k` | Estimated slippage % for $10k buy |
+
+Plus 70+ more fields: liquidity at 5/10/20/50 levels, volumes, imbalance deltas, largest walls, slippage at 8 USD sizes, velocity, momentum, z-scores, and depth quality metrics.
+
+### `CandleHLCV`
+
+```python
+candle.ts       # Unix ms
+candle.open
+candle.high
+candle.low
+candle.close
+candle.volume
+```
+
+### `NormalizedTrade`
+
+```python
+trade.timestamp  # Unix ms
+trade.price
+trade.size
+trade.side       # "buy" or "sell"
+trade.symbol
+```
+
+## Architecture
+
+```
+Python process
+|
++-- ctypes loads libflowex.so  <--  Go runtime starts inside Python
+|                                    |
+|                                    +-- Manager (binance)
+|                                    |     +-- Worker: BTCUSDT -> atomic snapshot
+|                                    |     +-- Worker: ETHUSDT -> atomic snapshot
+|                                    |     +-- Worker: SOLUSDT -> atomic snapshot
+|                                    |
+|                                    +-- Manager (bybit)
+|                                          +-- Worker: BTCUSDT -> atomic snapshot
+|
++-- mgr.subscribe(["BTCUSDT"])     ->  FlowexSubscribeBatch()
++-- mgr.get_snapshot("BTCUSDT")    ->  FlowexGetSnapshot() -> atomic.Load -> JSON -> Python
++-- mgr.get_all_snapshots()        ->  FlowexGetSnapshots() -> one call, all symbols
+```
+
+## Build from source
+
+Requires Go 1.22+ and Python 3.10+.
+
+```bash
+# macOS (Apple Silicon)
+make build-mac
+
+# Linux (amd64)
+make build-linux
+
+# All platforms (requires cross-compilers)
+make build-all
+```
+
+## License
+
+MIT

flowex-0.1.0/flowex/__init__.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import atexit
+import ctypes
+import json
+
+from flowex._lib import lib as _lib
+from flowex._models import CandleHLCV, DepthMetrics, NormalizedTrade, Snapshot
+
+__all__ = [
+    "Manager",
+    "Snapshot",
+    "CandleHLCV",
+    "DepthMetrics",
+    "NormalizedTrade",
+]
+
+_shutdown_registered = False
+
+
+class Manager:
+    """Wraps a flowex exchange manager loaded via the shared library.
+
+    Usage::
+
+        with Manager("binance") as mgr:
+            mgr.subscribe(["BTCUSDT", "ETHUSDT"])
+            snap = mgr.get_snapshot("BTCUSDT")
+    """
+
+    def __init__(self, exchange: str) -> None:
+        global _shutdown_registered
+        self._exchange = exchange.lower()
+        self._exchange_b = self._exchange.encode("utf-8")
+        rc = _lib.FlowexInit(self._exchange_b)
+        if rc != 0:
+            raise RuntimeError(f"FlowexInit failed for {exchange!r}")
+        if not _shutdown_registered:
+            atexit.register(_lib.FlowexShutdown)
+            _shutdown_registered = True
+
+    def subscribe(self, symbols: list[str] | str) -> None:
+        if isinstance(symbols, str):
+            symbols = [symbols]
+        arr = (ctypes.c_char_p * len(symbols))(
+            *(s.encode("utf-8") for s in symbols)
+        )
+        rc = _lib.FlowexSubscribeBatch(self._exchange_b, arr, len(symbols))
+        if rc != 0:
+            raise RuntimeError("FlowexSubscribeBatch failed")
+
+    def get_snapshot(self, symbol: str) -> Snapshot | None:
+        ptr = _lib.FlowexGetSnapshot(self._exchange_b, symbol.encode("utf-8"))
+        if not ptr:
+            return None
+        try:
+            raw = ctypes.string_at(ptr)
+            data = json.loads(raw)
+        finally:
+            _lib.FlowexFree(ptr)
+        return Snapshot.from_dict(data)
+
+    def get_all_snapshots(self) -> dict[str, Snapshot]:
+        ptr = _lib.FlowexGetSnapshots(self._exchange_b)
+        if not ptr:
+            return {}
+        try:
+            raw = ctypes.string_at(ptr)
+            data = json.loads(raw)
+        finally:
+            _lib.FlowexFree(ptr)
+        return {sym: Snapshot.from_dict(snap) for sym, snap in data.items()}
+
+    def unsubscribe(self, symbol: str) -> None:
+        rc = _lib.FlowexUnsubscribe(self._exchange_b, symbol.encode("utf-8"))
+        if rc != 0:
+            raise RuntimeError(f"FlowexUnsubscribe failed for {symbol!r}")
+
+    def close(self) -> None:
+        _lib.FlowexShutdown()
+
+    def __enter__(self) -> Manager:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()

flowex-0.1.0/flowex/_lib.py

@@ -0,0 +1,67 @@
+import ctypes
+import os
+import platform
+
+
+def _load():
+    system = platform.system()
+    machine = platform.machine()
+
+    pkg_dir = os.path.dirname(os.path.abspath(__file__))
+    lib_dir = os.path.join(pkg_dir, "lib")
+
+    if system == "Linux":
+        if machine in ("aarch64", "arm64"):
+            name = "libflowex-arm64.so"
+        else:
+            name = "libflowex.so"
+    elif system == "Darwin":
+        name = "libflowex.dylib"
+    elif system == "Windows":
+        name = "libflowex.dll"
+    else:
+        raise OSError(f"Unsupported platform: {system}")
+
+    path = os.path.join(lib_dir, name)
+    lib = ctypes.CDLL(path)
+
+    # FlowexInit(exchange *char) -> int
+    lib.FlowexInit.argtypes = [ctypes.c_char_p]
+    lib.FlowexInit.restype = ctypes.c_int
+
+    # FlowexSubscribe(exchange *char, symbol *char) -> int
+    lib.FlowexSubscribe.argtypes = [ctypes.c_char_p, ctypes.c_char_p]
+    lib.FlowexSubscribe.restype = ctypes.c_int
+
+    # FlowexSubscribeBatch(exchange *char, symbols **char, count int) -> int
+    lib.FlowexSubscribeBatch.argtypes = [
+        ctypes.c_char_p,
+        ctypes.POINTER(ctypes.c_char_p),
+        ctypes.c_int,
+    ]
+    lib.FlowexSubscribeBatch.restype = ctypes.c_int
+
+    # FlowexGetSnapshot(exchange *char, symbol *char) -> *char (caller must free)
+    lib.FlowexGetSnapshot.argtypes = [ctypes.c_char_p, ctypes.c_char_p]
+    lib.FlowexGetSnapshot.restype = ctypes.c_void_p
+
+    # FlowexGetSnapshots(exchange *char) -> *char (caller must free)
+    lib.FlowexGetSnapshots.argtypes = [ctypes.c_char_p]
+    lib.FlowexGetSnapshots.restype = ctypes.c_void_p
+
+    # FlowexUnsubscribe(exchange *char, symbol *char) -> int
+    lib.FlowexUnsubscribe.argtypes = [ctypes.c_char_p, ctypes.c_char_p]
+    lib.FlowexUnsubscribe.restype = ctypes.c_int
+
+    # FlowexShutdown() -> void
+    lib.FlowexShutdown.argtypes = []
+    lib.FlowexShutdown.restype = None
+
+    # FlowexFree(ptr *char) -> void
+    lib.FlowexFree.argtypes = [ctypes.c_void_p]
+    lib.FlowexFree.restype = None
+
+    return lib
+
+
+lib = _load()

flowex-0.1.0/flowex/_models.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import dataclasses
+from dataclasses import dataclass, field
+
+
+@dataclass
+class CandleHLCV:
+    ts: int = 0
+    open: float = 0.0
+    high: float = 0.0
+    low: float = 0.0
+    close: float = 0.0
+    volume: float = 0.0
+
+
+@dataclass
+class NormalizedTrade:
+    timestamp: int = 0
+    price: float = 0.0
+    size: float = 0.0
+    size_usd: float = 0.0
+    side: str = ""
+    trade_id: str = ""
+    symbol: str = ""
+    exchange: str = ""
+
+
+@dataclass
+class DepthMetrics:
+    # Basic
+    timestamp: int = 0
+    symbol: str = ""
+    best_bid: float = 0.0
+    best_ask: float = 0.0
+    spread: float = 0.0
+    spread_bps: float = 0.0
+    mid_price: float = 0.0
+
+    # Liquidity (USD) at different depths
+    bid_liquidity_5: float = 0.0
+    ask_liquidity_5: float = 0.0
+    bid_liquidity_10: float = 0.0
+    ask_liquidity_10: float = 0.0
+    bid_liquidity_20: float = 0.0
+    ask_liquidity_20: float = 0.0
+    bid_liquidity_50: float = 0.0
+    ask_liquidity_50: float = 0.0
+
+    # Volumes (coin size) at different depths
+    bid_volume_5: float = 0.0
+    ask_volume_5: float = 0.0
+    bid_volume_10: float = 0.0
+    ask_volume_10: float = 0.0
+    bid_volume_20: float = 0.0
+    ask_volume_20: float = 0.0
+    bid_volume_50: float = 0.0
+    ask_volume_50: float = 0.0
+
+    # Imbalance ratios
+    imbalance_ratio_5: float = 0.0
+    imbalance_ratio_10: float = 0.0
+    imbalance_ratio_20: float = 0.0
+    imbalance_ratio_50: float = 0.0
+
+    # Imbalance deltas
+    imbalance_delta_10: float = 0.0
+    imbalance_delta_20: float = 0.0
+
+    # Largest single orders (walls)
+    largest_bid_size: float = 0.0
+    largest_bid_price: float = 0.0
+    largest_bid_value: float = 0.0
+    largest_ask_size: float = 0.0
+    largest_ask_price: float = 0.0
+    largest_ask_value: float = 0.0
+
+    # Slippage estimation (%)
+    slippage_buy_100: float = 0.0
+    slippage_sell_100: float = 0.0
+    slippage_buy_1k: float = 0.0
+    slippage_sell_1k: float = 0.0
+    slippage_buy_5k: float = 0.0
+    slippage_sell_5k: float = 0.0
+    slippage_buy_10k: float = 0.0
+    slippage_sell_10k: float = 0.0
+    slippage_buy_50k: float = 0.0
+    slippage_sell_50k: float = 0.0
+    slippage_buy_100k: float = 0.0
+    slippage_sell_100k: float = 0.0
+    slippage_buy_500k: float = 0.0
+    slippage_sell_500k: float = 0.0
+    slippage_buy_1m: float = 0.0
+    slippage_sell_1m: float = 0.0
+
+    # Velocity metrics
+    liquidity_velocity_10: float = 0.0
+    liquidity_velocity_50: float = 0.0
+    imbalance_velocity: float = 0.0
+    spread_velocity: float = 0.0
+    wall_velocity: float = 0.0
+
+    # Momentum
+    buy_pressure_momentum: float = 0.0
+    sell_pressure_momentum: float = 0.0
+    wall_building_bid: bool = False
+    wall_building_ask: bool = False
+
+    # Z-scores
+    liquidity_zscore_10: float = 0.0
+    imbalance_zscore: float = 0.0
+    spread_zscore: float = 0.0
+
+    # Depth quality
+    bid_levels_count: int = 0
+    ask_levels_count: int = 0
+    avg_bid_size_10: float = 0.0
+    avg_ask_size_10: float = 0.0
+    top_bid_concentration_5: float = 0.0
+    top_ask_concentration_5: float = 0.0
+    spread_norm_imbalance_delta_10: float = 0.0
+    spread_norm_imbalance_delta_20: float = 0.0
+    slippage_gradient_buy: float = 0.0
+    slippage_gradient_sell: float = 0.0
+    slippage_skew_1k: float = 0.0
+    slippage_skew_10k: float = 0.0
+
+    @classmethod
+    def from_dict(cls, d: dict) -> DepthMetrics:
+        known = {f.name for f in dataclasses.fields(cls)}
+        return cls(**{k: v for k, v in d.items() if k in known})
+
+
+@dataclass
+class Snapshot:
+    timestamp: int = 0
+    candles: list[CandleHLCV] = field(default_factory=list)
+    depth: DepthMetrics | None = None
+    trades: list[NormalizedTrade] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> Snapshot:
+        return cls(
+            timestamp=d.get("timestamp", 0),
+            candles=[CandleHLCV(**c) for c in d.get("candles") or []],
+            depth=DepthMetrics.from_dict(d["depth"]) if d.get("depth") else None,
+            trades=[NormalizedTrade(**t) for t in d.get("trades") or []],
+        )

flowex-0.1.0/flowex.egg-info/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: flowex
+Version: 0.1.0
+Summary: Real-time multi-exchange crypto market data in Python — WebSocket streaming, order book metrics, and per-symbol actor workers for Binance, Bybit, and Bitget.
+Author: KhavrTrading
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/KhavrTrading/flowex-py
+Project-URL: Repository, https://github.com/KhavrTrading/flowex-py
+Project-URL: Issues, https://github.com/KhavrTrading/flowex-py/issues
+Keywords: crypto,trading,market-data,websocket,binance,bybit,bitget,order-book,depth,real-time,go,cgo
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# flowex
+
+[![CI](https://github.com/KhavrTrading/flowex-py/actions/workflows/build.yml/badge.svg)](https://github.com/KhavrTrading/flowex-py/actions/workflows/build.yml)
+[![PyPI](https://img.shields.io/pypi/v/flowex)](https://pypi.org/project/flowex/)
+[![Python](https://img.shields.io/pypi/pyversions/flowex)](https://pypi.org/project/flowex/)
+[![License](https://img.shields.io/github/license/KhavrTrading/flowex-py)](LICENSE)
+
+Real-time multi-exchange crypto market data for Python — powered by Go via cgo shared library. WebSocket streaming, order book metrics, and per-symbol actor workers for Binance, Bybit, and Bitget.
+
+No subprocess, no gRPC, no serialization overhead on the hot path. The Go runtime lives inside the Python process. Every symbol gets its own goroutine. `get_snapshot()` hits the atomic store directly.
+
+## Install
+
+```bash
+pip install flowex
+```
+
+## Quick start
+
+```python
+import time
+from flowex import Manager
+
+mgr = Manager("binance")
+mgr.subscribe(["BTCUSDT", "ETHUSDT", "SOLUSDT"])
+time.sleep(2)
+
+snap = mgr.get_snapshot("BTCUSDT")
+print(snap.depth.spread_bps)
+print(snap.depth.mid_price)
+print(snap.candles[-1].close)
+
+mgr.close()
+```
+
+Or use as a context manager:
+
+```python
+with Manager("binance") as mgr:
+    mgr.subscribe(["BTCUSDT"])
+    time.sleep(2)
+    snap = mgr.get_snapshot("BTCUSDT")
+```
+
+## Supported exchanges
+
+- **Binance** — futures WebSocket (candles, depth, aggTrade)
+- **Bybit** — linear futures WebSocket
+- **Bitget** — USDT futures WebSocket
+
+## API
+
+### `Manager(exchange)`
+
+Create a manager for an exchange. Initializes the Go runtime and WebSocket connections.
+
+```python
+mgr = Manager("binance")  # or "bybit", "bitget"
+```
+
+### `mgr.subscribe(symbols)`
+
+Subscribe to one or more symbols. Starts candle, depth, and trade streams for each.
+
+```python
+mgr.subscribe("BTCUSDT")
+mgr.subscribe(["BTCUSDT", "ETHUSDT", "SOLUSDT"])
+```
+
+### `mgr.get_snapshot(symbol) -> Snapshot | None`
+
+Get the latest point-in-time snapshot for a symbol.
+
+```python
+snap = mgr.get_snapshot("BTCUSDT")
+snap.timestamp      # Unix ms
+snap.depth          # DepthMetrics
+snap.candles        # list[CandleHLCV]
+snap.trades         # list[NormalizedTrade]
+```
+
+### `mgr.get_all_snapshots() -> dict[str, Snapshot]`
+
+Get snapshots for all subscribed symbols in one call.
+
+### `mgr.unsubscribe(symbol)`
+
+Remove all streams for a symbol.
+
+### `mgr.close()`
+
+Shutdown all managers and WebSocket connections.
+
+## Data models
+
+### `DepthMetrics`
+
+Order book metrics computed from raw depth data:
+
+| Field | Description |
+|-------|-------------|
+| `mid_price` | (best_bid + best_ask) / 2 |
+| `spread_bps` | Spread in basis points |
+| `bid_liquidity_10` | USD liquidity, top 10 bid levels |
+| `ask_liquidity_10` | USD liquidity, top 10 ask levels |
+| `imbalance_ratio_10` | bid_liq / ask_liq (>1 = bullish) |
+| `slippage_buy_10k` | Estimated slippage % for $10k buy |
+
+Plus 70+ more fields: liquidity at 5/10/20/50 levels, volumes, imbalance deltas, largest walls, slippage at 8 USD sizes, velocity, momentum, z-scores, and depth quality metrics.
+
+### `CandleHLCV`
+
+```python
+candle.ts       # Unix ms
+candle.open
+candle.high
+candle.low
+candle.close
+candle.volume
+```
+
+### `NormalizedTrade`
+
+```python
+trade.timestamp  # Unix ms
+trade.price
+trade.size
+trade.side       # "buy" or "sell"
+trade.symbol
+```
+
+## Architecture
+
+```
+Python process
+|
++-- ctypes loads libflowex.so  <--  Go runtime starts inside Python
+|                                    |
+|                                    +-- Manager (binance)
+|                                    |     +-- Worker: BTCUSDT -> atomic snapshot
+|                                    |     +-- Worker: ETHUSDT -> atomic snapshot
+|                                    |     +-- Worker: SOLUSDT -> atomic snapshot
+|                                    |
+|                                    +-- Manager (bybit)
+|                                          +-- Worker: BTCUSDT -> atomic snapshot
+|
++-- mgr.subscribe(["BTCUSDT"])     ->  FlowexSubscribeBatch()
++-- mgr.get_snapshot("BTCUSDT")    ->  FlowexGetSnapshot() -> atomic.Load -> JSON -> Python
++-- mgr.get_all_snapshots()        ->  FlowexGetSnapshots() -> one call, all symbols
+```
+
+## Build from source
+
+Requires Go 1.22+ and Python 3.10+.
+
+```bash
+# macOS (Apple Silicon)
+make build-mac
+
+# Linux (amd64)
+make build-linux
+
+# All platforms (requires cross-compilers)
+make build-all
+```
+
+## License
+
+MIT

flowex-0.1.0/flowex.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+flowex/__init__.py
+flowex/_lib.py
+flowex/_models.py
+flowex.egg-info/PKG-INFO
+flowex.egg-info/SOURCES.txt
+flowex.egg-info/dependency_links.txt
+flowex.egg-info/top_level.txt
+flowex/lib/libflowex-arm64.so
+flowex/lib/libflowex.dll
+flowex/lib/libflowex.dylib
+flowex/lib/libflowex.so

flowex-0.1.0/flowex.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

flowex-0.1.0/flowex.egg-info/top_level.txt

@@ -0,0 +1 @@
+flowex

flowex-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "flowex"
+version = "0.1.0"
+description = "Real-time multi-exchange crypto market data in Python — WebSocket streaming, order book metrics, and per-symbol actor workers for Binance, Bybit, and Bitget."
+requires-python = ">=3.10"
+license = "MIT"
+readme = "README.md"
+authors = [
+    { name = "KhavrTrading" },
+]
+keywords = [
+    "crypto",
+    "trading",
+    "market-data",
+    "websocket",
+    "binance",
+    "bybit",
+    "bitget",
+    "order-book",
+    "depth",
+    "real-time",
+    "go",
+    "cgo",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/KhavrTrading/flowex-py"
+Repository = "https://github.com/KhavrTrading/flowex-py"
+Issues = "https://github.com/KhavrTrading/flowex-py/issues"
+
+[tool.setuptools.packages.find]
+include = ["flowex*"]
+
+[tool.setuptools.package-data]
+flowex = ["lib/*"]

flowex-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+