metascalp 1.1.0__py3-none-any.whl

metascalp/__init__.py

@@ -0,0 +1,4 @@
+from .client import MetaScalpClient
+from .socket import MetaScalpSocket
+
+__all__ = ['MetaScalpClient', 'MetaScalpSocket']

metascalp/client.py

@@ -0,0 +1,317 @@
+"""MetaScalp REST API client."""
+
+from __future__ import annotations
+
+import aiohttp
+from typing import Any, Optional
+
+HTTP_PORT_START = 17845
+HTTP_PORT_END = 17855
+
+
+class MetaScalpApiError(Exception):
+    """Raised when the MetaScalp API returns an error response."""
+
+    def __init__(self, status: int, error: str, path: str):
+        self.status = status
+        self.error = error
+        self.path = path
+        super().__init__(f"MetaScalp API error {status} on {path}: {error}")
+
+
+class MetaScalpClient:
+    """HTTP REST client for MetaScalp API.
+
+    Usage:
+        client = await MetaScalpClient.discover()
+        connections = await client.get_connections()
+    """
+
+    def __init__(self, port: int):
+        self.port = port
+        self.base_url = f"http://127.0.0.1:{port}"
+        self._session: Optional[aiohttp.ClientSession] = None
+
+    @classmethod
+    async def discover(cls, timeout: float = 1.0) -> MetaScalpClient:
+        """Scan ports 17845-17855 to find a running MetaScalp instance."""
+        timeout_obj = aiohttp.ClientTimeout(total=timeout)
+        async with aiohttp.ClientSession(timeout=timeout_obj) as session:
+            for port in range(HTTP_PORT_START, HTTP_PORT_END + 1):
+                try:
+                    async with session.get(f"http://127.0.0.1:{port}/ping") as resp:
+                        if resp.status == 200:
+                            data = await resp.json()
+                            if data.get("app") == "MetaScalp":
+                                return cls(port)
+                except (aiohttp.ClientError, OSError):
+                    continue
+        raise ConnectionError(
+            f"MetaScalp not found on ports {HTTP_PORT_START}-{HTTP_PORT_END}"
+        )
+
+    async def _ensure_session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession()
+        return self._session
+
+    async def close(self) -> None:
+        """Close the underlying HTTP session."""
+        if self._session and not self._session.closed:
+            await self._session.close()
+
+    async def _get(self, path: str) -> Any:
+        session = await self._ensure_session()
+        async with session.get(f"{self.base_url}{path}") as resp:
+            data = await resp.json()
+            if resp.status >= 400:
+                raise MetaScalpApiError(resp.status, data.get("error", ""), path)
+            return data
+
+    async def _post(self, path: str, body: Any) -> Any:
+        session = await self._ensure_session()
+        async with session.post(
+            f"{self.base_url}{path}", json=body
+        ) as resp:
+            data = await resp.json()
+            if resp.status >= 400:
+                raise MetaScalpApiError(resp.status, data.get("error", ""), path)
+            return data
+
+    async def _put(self, path: str, body: dict) -> Any:
+        session = await self._ensure_session()
+        async with session.put(f"{self.base_url}{path}", json=body) as resp:
+            data = await resp.json()
+            if resp.status >= 400:
+                raise MetaScalpApiError(resp.status, data.get("error", ""), path)
+            return data
+
+    async def _delete(self, path: str) -> Any:
+        session = await self._ensure_session()
+        async with session.delete(f"{self.base_url}{path}") as resp:
+            data = await resp.json()
+            if resp.status >= 400:
+                raise MetaScalpApiError(resp.status, data.get("error", ""), path)
+            return data
+
+    # ---- Discovery ----
+
+    async def ping(self) -> dict:
+        """Check MetaScalp instance and get version."""
+        return await self._get("/ping")
+
+    # ---- Connections ----
+
+    async def get_connections(self) -> dict:
+        """List all active exchange connections."""
+        return await self._get("/api/connections")
+
+    async def get_connection(self, connection_id: int) -> dict:
+        """Get a single connection by ID."""
+        return await self._get(f"/api/connections/{connection_id}")
+
+    # ---- Market Data Queries ----
+
+    async def get_tickers(self, connection_id: int, refresh: bool = False) -> dict:
+        """List available tickers on a connection. Set refresh=True to fetch fresh data from exchange."""
+        qs = "?Refresh=true" if refresh else ""
+        return await self._get(f"/api/connections/{connection_id}/tickers{qs}")
+
+    # ---- Trading Data ----
+
+    async def get_orders(self, connection_id: int, ticker: str) -> dict:
+        """Get open orders for a ticker."""
+        return await self._get(
+            f"/api/connections/{connection_id}/orders?Ticker={ticker}"
+        )
+
+    async def get_positions(self, connection_id: int) -> dict:
+        """Get open positions on a connection."""
+        return await self._get(f"/api/connections/{connection_id}/positions")
+
+    async def get_balance(self, connection_id: int) -> dict:
+        """Get account balances on a connection."""
+        return await self._get(f"/api/connections/{connection_id}/balance")
+
+    # ---- Order Execution ----
+
+    async def place_order(
+        self,
+        connection_id: int,
+        *,
+        ticker: str,
+        side: int,
+        price: float,
+        size: float,
+        type: int = 0,
+        reduce_only: bool = False,
+    ) -> dict:
+        """Place an order on the exchange."""
+        return await self._post(
+            f"/api/connections/{connection_id}/orders",
+            {
+                "ticker": ticker,
+                "side": side,
+                "price": price,
+                "size": size,
+                "type": type,
+                "reduceOnly": reduce_only,
+            },
+        )
+
+    async def cancel_order(
+        self,
+        connection_id: int,
+        *,
+        ticker: str,
+        order_id: int,
+        type: int = 0,
+    ) -> dict:
+        """Cancel an existing order."""
+        return await self._post(
+            f"/api/connections/{connection_id}/orders/cancel",
+            {"ticker": ticker, "orderId": order_id, "type": type},
+        )
+
+    # ---- UI Control ----
+
+    async def change_ticker(
+        self,
+        *,
+        ticker_pattern: Optional[str] = None,
+        exchange: Optional[int] = None,
+        market: Optional[int] = None,
+        ticker: Optional[str] = None,
+        binding: Optional[str] = None,
+    ) -> dict:
+        """Switch the active ticker in MetaScalp UI."""
+        body: dict[str, Any] = {}
+        if ticker_pattern is not None:
+            body["tickerPattern"] = ticker_pattern
+        if exchange is not None:
+            body["exchange"] = exchange
+        if market is not None:
+            body["market"] = market
+        if ticker is not None:
+            body["ticker"] = ticker
+        if binding is not None:
+            body["binding"] = binding
+        return await self._post("/api/change-ticker", body)
+
+    async def open_combo(self, ticker: str) -> dict:
+        """Open a combo layout for a ticker."""
+        return await self._post("/api/combo", {"ticker": ticker})
+
+    # ---- Signal Levels ----
+
+    async def get_signal_levels(self, connection_id: int, ticker: str) -> dict:
+        """Get signal levels for a ticker on a connection."""
+        return await self._get(
+            f"/api/connections/{connection_id}/signal-levels?Ticker={ticker}"
+        )
+
+    async def place_signal_level(self, connection_id: int, *, ticker: str, price: float) -> dict:
+        """Place a signal level on a connection."""
+        return await self._post(
+            f"/api/connections/{connection_id}/signal-levels",
+            {"Ticker": ticker, "Price": price},
+        )
+
+    async def remove_signal_level(self, connection_id: int, signal_level_id: int) -> dict:
+        """Remove a signal level by ID."""
+        return await self._delete(
+            f"/api/connections/{connection_id}/signal-levels/{signal_level_id}"
+        )
+
+    async def remove_all_signal_levels(self, connection_id: int, ticker: str) -> dict:
+        """Remove all signal levels for a ticker on a connection."""
+        return await self._delete(
+            f"/api/connections/{connection_id}/signal-levels?Ticker={ticker}"
+        )
+
+    async def remove_triggered_signal_levels(self) -> dict:
+        """Remove all triggered signal levels."""
+        return await self._delete("/api/signal-levels/triggered")
+
+    # ---- Order Book Settings ----
+
+    async def get_orderbook_settings(self, connection_id: int, ticker: str) -> dict:
+        """Get order book settings for a ticker on a connection."""
+        return await self._get(
+            f"/api/connections/{connection_id}/orderbook-settings?Ticker={ticker}"
+        )
+
+    async def update_orderbook_settings(self, connection_id: int, ticker: str, **settings) -> dict:
+        """Update order book settings (partial update). Only provided fields are changed."""
+        return await self._put(
+            f"/api/connections/{connection_id}/orderbook-settings?Ticker={ticker}",
+            settings,
+        )
+
+    # ---- Order Book Snapshot (one-shot fresh REST fetch) ----
+
+    async def get_order_book_snapshot(
+        self,
+        connection_id: int,
+        ticker: str,
+        zoom_index: int = 0,
+        depth_levels: int | None = None,
+        depth_percent: float | None = None,
+    ) -> dict:
+        """Fetch a fresh order book snapshot directly from the exchange REST endpoint.
+
+        Each call performs one exchange REST request — no cache, no subscription side
+        effects. Intended as a one-shot complement to subscribe_order_book(..., fetch_snapshot=False):
+        subscribe to deltas cheaply, then call this once per ticker when you need to seed
+        state.
+
+        Raises MetaScalpApiError with status 501 for exchanges that don't expose a REST
+        snapshot endpoint (e.g. Bybit USDT Perpetual, which only delivers snapshots over WS).
+
+        The caller is responsible for not exceeding the exchange's rate limit when invoking
+        this for many tickers in quick succession.
+
+        Returns a dict with keys: connectionId, ticker, updateId, asks, bids, bestAsk, bestBid.
+        """
+        qs = [f"Ticker={ticker}"]
+        if zoom_index > 0:
+            qs.append(f"ZoomIndex={zoom_index}")
+        if depth_levels is not None:
+            qs.append(f"DepthLevels={depth_levels}")
+        if depth_percent is not None:
+            qs.append(f"DepthPercent={depth_percent}")
+        return await self._get(
+            f"/api/connections/{connection_id}/orderbook-snapshot?{'&'.join(qs)}"
+        )
+
+    # ---- Clusters ----
+
+    async def get_cluster_snapshot(
+        self,
+        connection_id: int,
+        ticker: str,
+        time_frame: str,
+        zoom_index: int = 1,
+        columns: int | None = None,
+    ) -> dict:
+        """Fetch the cluster (volume profile / footprint) snapshot for a ticker at a timeframe.
+
+        time_frame is one of S30, M1, M5, M10, M15, M30, H1, H4, D1.
+        zoom_index > 1 groups price levels into buckets of zoom_index * PriceIncrement.
+
+        The response always holds 100 time columns, oldest first. By default only the newest
+        10 carry data (the cluster backend's default page); pass columns (up to 100) to fill
+        more history. Each extra 5 columns is one more backend request, so deep fills take
+        longer.
+
+        Returns a dict with keys: Ticker, TimeFrame, ZoomIndex, PriceIncrement, Columns
+        (each column: StartTime, AsksSum, BidsSum, Items[Price, AskSize, BidSize]).
+        """
+        qs = [f"Ticker={ticker}", f"TimeFrame={time_frame}"]
+        if zoom_index > 1:
+            qs.append(f"ZoomIndex={zoom_index}")
+        if columns is not None and columns > 0:
+            qs.append(f"Columns={columns}")
+        return await self._get(
+            f"/api/connections/{connection_id}/cluster-snapshot?{'&'.join(qs)}"
+        )

metascalp/socket.py

@@ -0,0 +1,457 @@
+"""MetaScalp WebSocket client for real-time updates."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any, Callable, Optional
+
+import websockets
+from websockets.client import WebSocketClientProtocol
+
+WS_PORT_START = 17845
+WS_PORT_END = 17855
+
+
+def _normalize(obj: Any) -> Any:
+    """Normalize PascalCase keys from server to camelCase."""
+    if obj is None:
+        return obj
+    if isinstance(obj, list):
+        return [_normalize(item) for item in obj]
+    if isinstance(obj, dict):
+        return {k[0].lower() + k[1:]: _normalize(v) for k, v in obj.items()}
+    return obj
+
+
+class MetaScalpSocket:
+    """WebSocket client for MetaScalp real-time updates.
+
+    Supports connection-level subscriptions (orders, positions, balances)
+    and market data subscriptions (trades, order book) scoped by connectionId + ticker.
+
+    Usage:
+        socket = await MetaScalpSocket.discover()
+
+        @socket.on('trade_update')
+        def on_trade(data):
+            print(data)
+
+        socket.subscribe(connection_id)
+        socket.subscribe_trades(connection_id, 'BTCUSDT')
+        await socket.listen_forever()
+    """
+
+    def __init__(self, port: int):
+        self.port = port
+        self._ws: Optional[WebSocketClientProtocol] = None
+        self._listeners: dict[str, list[Callable]] = {}
+        self._connected = False
+
+    @classmethod
+    async def discover(cls, timeout: float = 1.0) -> MetaScalpSocket:
+        """Scan ports 17845-17855 to find the MetaScalp WebSocket server."""
+        for port in range(WS_PORT_START, WS_PORT_END + 1):
+            try:
+                ws = await asyncio.wait_for(
+                    websockets.connect(f"ws://127.0.0.1:{port}/"),
+                    timeout=timeout,
+                )
+                socket = cls(port)
+                socket._ws = ws
+                socket._connected = True
+                return socket
+            except (ConnectionRefusedError, OSError, asyncio.TimeoutError):
+                continue
+        raise ConnectionError(
+            f"MetaScalp WebSocket not found on ports {WS_PORT_START}-{WS_PORT_END}"
+        )
+
+    @property
+    def connected(self) -> bool:
+        return self._connected
+
+    async def connect(self, timeout: float = 5.0) -> None:
+        """Connect to the WebSocket server."""
+        self._ws = await asyncio.wait_for(
+            websockets.connect(f"ws://127.0.0.1:{self.port}/"),
+            timeout=timeout,
+        )
+        self._connected = True
+
+    async def disconnect(self) -> None:
+        """Disconnect from the WebSocket server."""
+        if self._ws:
+            await self._ws.close()
+        self._ws = None
+        self._connected = False
+
+    # ---- Connection-level subscriptions ----
+    # Use these to receive order, position, balance, and finres updates
+    # for ALL tickers on a connection.
+    # Events: 'order_update', 'position_update', 'balance_update', 'finres_update'
+
+    def subscribe(self, connection_id: int) -> None:
+        """Subscribe to order, position, balance, and finres updates for a connection.
+
+        This covers ALL tickers on the connection.
+
+        Events you'll receive:
+        - 'order_update' — order created/modified/filled/cancelled
+        - 'position_update' — position opened/changed/closed
+        - 'balance_update' — account balances changed
+        - 'finres_update' — financial results recalculated
+        """
+        self._send("subscribe", {"connectionId": connection_id})
+
+    def unsubscribe(self, connection_id: int) -> None:
+        """Unsubscribe from connection-level updates."""
+        self._send("unsubscribe", {"connectionId": connection_id})
+
+    # ---- Market data subscriptions ----
+    # Use these to receive real-time market data for a SPECIFIC ticker on a connection.
+    # These are independent from subscribe() — you can use one without the other.
+    # Events: 'trade_update', 'orderbook_snapshot', 'orderbook_update'
+
+    def subscribe_trades(self, connection_id: int, ticker: str) -> None:
+        """Subscribe to real-time trade updates for a specific ticker.
+
+        Independent from subscribe() — only sends trade data for this exact ticker.
+
+        Event: 'trade_update'
+
+        Trades are aggregated server-side using the order book's `AddingTicksForAPeriod`
+        setting (per-(connection, ticker), default 200 ms). Consecutive same-side trades
+        inside the window are merged into one entry — `size` is summed, `price` and `time`
+        track the latest merged trade. Set `AddingTicksForAPeriod = 0` in the order book
+        settings to receive the raw exchange stream.
+        """
+        self._send("trade_subscribe", {"connectionId": connection_id, "ticker": ticker})
+
+    def unsubscribe_trades(self, connection_id: int, ticker: str) -> None:
+        """Unsubscribe from trade updates for a specific ticker."""
+        self._send("trade_unsubscribe", {"connectionId": connection_id, "ticker": ticker})
+
+    def subscribe_order_book(
+        self,
+        connection_id: int,
+        ticker: str,
+        zoom_index: int = 0,
+        depth_levels: int | None = None,
+        depth_percent: float | None = None,
+        fetch_snapshot: bool = True,
+    ) -> None:
+        """Subscribe to order book updates for a specific ticker.
+
+        When zoom_index is 0 (default), receives full order book + incremental updates.
+        When zoom_index > 1, price levels are aggregated into zoomed buckets.
+
+        Optional filters:
+        - depth_levels (must be >= 1): trims the snapshot to the top N price levels per side
+          (asks ascending, bids descending), applied AFTER zoom and depth_percent. Filters the
+          snapshot ONLY — incremental updates are unaffected.
+        - depth_percent (must be > 0): per-side band as a percentage, anchored on best ask /
+          best bid (NOT mid). Asks kept where price <= bestAsk * (1 + depth_percent / 100);
+          bids where price >= bestBid * (1 - depth_percent / 100). Applies to both the
+          snapshot and subsequent updates; the band refreshes from the latest known best ask /
+          best bid on each event. If a side's anchor is unknown, that side is not filtered
+          (degrades open).
+        - fetch_snapshot (default True): when False AND this subscriber is the first to ask for
+          the ticker, the exchange REST snapshot fetch is skipped — only the WS delta feed is
+          subscribed. Useful for mass-subscribing 100+ tickers without hitting exchange REST
+          rate limits. Seed state separately via MetaScalpClient.get_order_book_snapshot()
+          when needed. If a later subscriber requests a snapshot, it is fetched lazily and
+          delivered to all subscribers.
+        bestAsk / bestBid payload fields are never filtered.
+
+        Events: 'orderbook_snapshot' (once, unless fetch_snapshot=False), then 'orderbook_update'
+        """
+        data: dict = {"connectionId": connection_id, "ticker": ticker, "zoomIndex": zoom_index}
+        if depth_levels is not None:
+            data["depthLevels"] = depth_levels
+        if depth_percent is not None:
+            data["depthPercent"] = depth_percent
+        # Only emit fetchSnapshot when non-default, for compatibility with older servers
+        if not fetch_snapshot:
+            data["fetchSnapshot"] = False
+        self._send("orderbook_subscribe", data)
+
+    def unsubscribe_order_book(self, connection_id: int, ticker: str) -> None:
+        """Unsubscribe from order book updates for a specific ticker."""
+        self._send("orderbook_unsubscribe", {"connectionId": connection_id, "ticker": ticker})
+
+    def subscribe_mark_price(self, connection_id: int, ticker: str) -> None:
+        """Subscribe to mark price updates for a specific ticker (futures only).
+
+        No initial snapshot — only live updates as the exchange publishes them.
+        Spot connections will not emit any updates even after a successful subscribe.
+
+        Event: 'mark_price_update'
+        """
+        self._send("mark_price_subscribe", {"connectionId": connection_id, "ticker": ticker})
+
+    def unsubscribe_mark_price(self, connection_id: int, ticker: str) -> None:
+        """Unsubscribe from mark price updates for a specific ticker."""
+        self._send("mark_price_unsubscribe", {"connectionId": connection_id, "ticker": ticker})
+
+    def subscribe_funding(self, connection_id: int, ticker: str) -> None:
+        """Subscribe to funding rate updates for a specific ticker (perpetual futures only).
+
+        No initial snapshot — only live updates as the exchange publishes them.
+        Spot and dated-futures connections will not emit any updates even after a successful subscribe.
+
+        Event: 'funding_update'
+        """
+        self._send("funding_subscribe", {"connectionId": connection_id, "ticker": ticker})
+
+    def unsubscribe_funding(self, connection_id: int, ticker: str) -> None:
+        """Unsubscribe from funding rate updates for a specific ticker."""
+        self._send("funding_unsubscribe", {"connectionId": connection_id, "ticker": ticker})
+
+    # ---- Notification subscriptions ----
+    # App-wide notifications (trades, signal levels, large amounts, screener).
+    # Independent from subscribe() — no connectionId required.
+    # Events: 'notification_snapshot', 'notification_update'
+
+    def subscribe_notifications(self) -> None:
+        """Subscribe to app-wide notifications.
+
+        Receives a snapshot of recent notifications, then live updates.
+        Independent from subscribe() — no connectionId required.
+
+        Events: 'notification_snapshot' (once), then 'notification_update' (continuous)
+        """
+        self._send("notification_subscribe", {})
+
+    def unsubscribe_notifications(self) -> None:
+        """Unsubscribe from notification updates."""
+        self._send("notification_unsubscribe", {})
+
+    # ---- Signal level subscriptions ----
+
+    def subscribe_signal_levels(self) -> None:
+        """Subscribe to signal level events."""
+        self._send("signal_level_subscribe", {})
+
+    def unsubscribe_signal_levels(self) -> None:
+        """Unsubscribe from signal level events."""
+        self._send("signal_level_unsubscribe", {})
+
+    # ---- MetaBroker analytics streams ----
+    # Density map / large trades / liquidations — app-wide feeds relayed from the MetaBroker
+    # backend (the same data the terminal's analytics windows show). No connection_id required.
+    # One subscription per feed per socket: re-subscribing REPLACES the config.
+
+    def subscribe_density_map(
+        self,
+        exchange_markets: list[dict],
+        large_coefficient: float | None = None,
+        medium_coefficient: float | None = None,
+        small_coefficient: float | None = None,
+        large_lifetime_minutes: int | None = None,
+        medium_lifetime_minutes: int | None = None,
+        small_lifetime_minutes: int | None = None,
+        included_quote_assets: list[str] | None = None,
+    ) -> None:
+        """Subscribe to the MetaBroker density map notifications stream.
+
+        Order book walls, each reported exactly once on first sight of its id.
+
+        exchange_markets is required and must be non-empty; each entry is a dict like
+        {"exchange": "binance", "market": "futures", "bdsMode": "auto", "bdsValue": 1000000}
+        (bdsMode/bdsValue optional — default manual / 1 000 000 USD). All other arguments
+        default to the terminal's Density Map window defaults (coefficients 3/2/1,
+        lifetimes 5 min, quote assets ["USDT"]; valid assets: USDT, USDC, OTHER).
+        Re-subscribing replaces the config without replaying already-notified walls.
+
+        Events: 'density_map_snapshot' (after the ack; may be empty — it resolves the
+        loading state), then 'density_map_update' (continuous).
+        """
+        data: dict = {"exchangeMarkets": exchange_markets}
+        if large_coefficient is not None:
+            data["largeCoefficient"] = large_coefficient
+        if medium_coefficient is not None:
+            data["mediumCoefficient"] = medium_coefficient
+        if small_coefficient is not None:
+            data["smallCoefficient"] = small_coefficient
+        if large_lifetime_minutes is not None:
+            data["largeLifetimeMinutes"] = large_lifetime_minutes
+        if medium_lifetime_minutes is not None:
+            data["mediumLifetimeMinutes"] = medium_lifetime_minutes
+        if small_lifetime_minutes is not None:
+            data["smallLifetimeMinutes"] = small_lifetime_minutes
+        if included_quote_assets is not None:
+            data["includedQuoteAssets"] = included_quote_assets
+        self._send("density_map_subscribe", data)
+
+    def unsubscribe_density_map(self) -> None:
+        """Stop the density map stream (tears down the upstream feed)."""
+        self._send("density_map_unsubscribe", {})
+
+    def subscribe_large_trades(
+        self,
+        exchange_markets: list[dict],
+        aggregation_ms: int | None = None,
+        min_amount_usd: float | None = None,
+        large_coefficient: float | None = None,
+        medium_coefficient: float | None = None,
+        small_coefficient: float | None = None,
+        included_quote_assets: list[str] | None = None,
+    ) -> None:
+        """Subscribe to the MetaBroker large trades stream.
+
+        Aggregated trade prints, final and append-only — no snapshot; history starts at
+        subscribe time. exchange_markets uses the same shape and defaults as
+        subscribe_density_map(). aggregation_ms is 0-60000 (default 500; 0 = every raw
+        print individually); quote assets default to ["USDT", "USDC", "OTHER"].
+        Re-subscribing replaces the config.
+
+        Event: 'large_trades_update'
+        """
+        data: dict = {"exchangeMarkets": exchange_markets}
+        if aggregation_ms is not None:
+            data["aggregationMs"] = aggregation_ms
+        if min_amount_usd is not None:
+            data["minAmountUsd"] = min_amount_usd
+        if large_coefficient is not None:
+            data["largeCoefficient"] = large_coefficient
+        if medium_coefficient is not None:
+            data["mediumCoefficient"] = medium_coefficient
+        if small_coefficient is not None:
+            data["smallCoefficient"] = small_coefficient
+        if included_quote_assets is not None:
+            data["includedQuoteAssets"] = included_quote_assets
+        self._send("large_trades_subscribe", data)
+
+    def unsubscribe_large_trades(self) -> None:
+        """Stop the large trades stream."""
+        self._send("large_trades_unsubscribe", {})
+
+    def subscribe_liquidations(
+        self,
+        exchanges: list[str],
+        min_notional_usd: float | None = None,
+        min_impact_bps: float | None = None,
+        asset_class: str | None = None,
+        side: str | None = None,
+        coin: str | None = None,
+        window: str | None = None,
+        backfill: int | None = None,
+    ) -> None:
+        """Subscribe to the MetaBroker cross-exchange liquidations stream (futures only).
+
+        No MetaBroker login is needed: the upstream is the screener-v2 hub signed with
+        the shared service key.
+
+        exchanges is required and must be non-empty; valid names: binance, bybit, okx,
+        bitget, gate, htx, aster, lighter. asset_class: 'all' | 'crypto' | 'tradfi'
+        (default all). side filters by the side of the LIQUIDATED position: 'all' |
+        'long' | 'short' (default all). coin is a case-insensitive prefix on the
+        resolved coin ('BTC', not 'BTCUSDT'). window ('m5'|'m15'|'h1'|'h4'|'h24',
+        default h1) affects totals / top tokens only, never the rows. backfill is the
+        snapshot row count, 0-500 (default 200). Re-subscribing replaces the filters
+        and the server re-sends a snapshot.
+
+        Events: 'liquidations_snapshot' (after every subscribe/replace),
+        'liquidations_update' (live rows, newest first), 'liquidations_metadata'
+        (totals + top tokens, sub-second cadence).
+        """
+        data: dict = {"exchanges": exchanges}
+        if min_notional_usd is not None:
+            data["minNotionalUsd"] = min_notional_usd
+        if min_impact_bps is not None:
+            data["minImpactBps"] = min_impact_bps
+        if asset_class is not None:
+            data["assetClass"] = asset_class
+        if side is not None:
+            data["side"] = side
+        if coin is not None:
+            data["coin"] = coin
+        if window is not None:
+            data["window"] = window
+        if backfill is not None:
+            data["backfill"] = backfill
+        self._send("liquidations_subscribe", data)
+
+    def unsubscribe_liquidations(self) -> None:
+        """Stop the liquidations stream."""
+        self._send("liquidations_unsubscribe", {})
+
+    # ---- Event handling ----
+
+    def on(self, event: str) -> Callable:
+        """Decorator to register an event listener.
+
+        Usage:
+            @socket.on('trade_update')
+            def on_trade(data):
+                print(data)
+        """
+        def decorator(fn: Callable) -> Callable:
+            if event not in self._listeners:
+                self._listeners[event] = []
+            self._listeners[event].append(fn)
+            return fn
+        return decorator
+
+    def add_listener(self, event: str, fn: Callable) -> None:
+        """Register an event listener."""
+        if event not in self._listeners:
+            self._listeners[event] = []
+        self._listeners[event].append(fn)
+
+    def remove_listener(self, event: str, fn: Callable) -> None:
+        """Remove an event listener."""
+        if event in self._listeners:
+            self._listeners[event] = [f for f in self._listeners[event] if f is not fn]
+
+    # ---- Message loop ----
+
+    async def listen_forever(self) -> None:
+        """Listen for messages and dispatch to registered listeners.
+
+        Blocks until the connection is closed. Call this after subscribing.
+        """
+        if not self._ws:
+            raise RuntimeError("Not connected")
+
+        try:
+            async for raw in self._ws:
+                try:
+                    data = _normalize(json.loads(raw))
+                    msg_type = data.get("type", "")
+                    msg_data = data.get("data")
+                    self._emit(msg_type, msg_data)
+                except json.JSONDecodeError:
+                    continue
+        except websockets.ConnectionClosed:
+            pass
+        finally:
+            self._connected = False
+
+    async def listen_once(self, timeout: float = 30.0) -> tuple[str, Any]:
+        """Wait for and return a single message as (type, data)."""
+        if not self._ws:
+            raise RuntimeError("Not connected")
+        raw = await asyncio.wait_for(self._ws.recv(), timeout=timeout)
+        data = _normalize(json.loads(raw))
+        msg_type = data.get("type", "")
+        msg_data = data.get("data")
+        self._emit(msg_type, msg_data)
+        return msg_type, msg_data
+
+    # ---- Internals ----
+
+    def _send(self, msg_type: str, data: dict) -> None:
+        if not self._ws or not self._connected:
+            raise RuntimeError("Not connected")
+        asyncio.get_event_loop().create_task(
+            self._ws.send(json.dumps({"type": msg_type, "data": data}))
+        )
+
+    def _emit(self, event: str, data: Any) -> None:
+        for fn in self._listeners.get(event, []):
+            try:
+                fn(data)
+            except Exception:
+                pass

metascalp-1.1.0.dist-info/METADATA

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: metascalp
+Version: 1.1.0
+Summary: Official SDK for MetaScalp API — trade, stream order book and trades via REST and WebSocket
+Author: MetaScalp
+License: MIT
+Project-URL: Homepage, https://metascalp.io
+Project-URL: Repository, https://github.com/MetaScalp/metascalp-sdk
+Keywords: metascalp,trading,api,websocket,orderbook,crypto,market-data
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: aiohttp>=3.8
+Requires-Dist: websockets>=11.0
+
+# MetaScalp SDK
+
+Official SDK for [MetaScalp](https://metascalp.io) API — connect your trading bots and scripts to the MetaScalp terminal via REST and WebSocket.
+
+MetaScalp exposes a local API that lets you query exchange data, execute trades, and stream real-time market data (trades, order book, mark/index price, funding) and account updates (orders, positions, balances) — plus manage signal levels, plain levels, chart annotations, the notification feed and the terminal UI itself, and stream the MetaBroker analytics feeds (density map, large trades, liquidations).
+
+## Available SDKs
+
+| Language | Directory | Install |
+|----------|-----------|---------|
+| **JavaScript / TypeScript** | [`js/`](./js) | `npm install metascalp` |
+| **Python** | [`python/`](./python) | `pip install metascalp` |
+| **C# / .NET** | [`dotnet/`](./dotnet) | `dotnet add package MetaScalp.Sdk` |
+
+## Quick Start
+
+### JavaScript / TypeScript
+
+```typescript
+import { MetaScalpClient, MetaScalpSocket } from 'metascalp';
+
+// REST — discover MetaScalp and query data
+const client = await MetaScalpClient.discover();
+const { connections } = await client.getConnections();
+const conn = connections[0];
+
+// Place a limit buy order
+await client.placeOrder(conn.id, {
+  ticker: 'BTCUSDT',
+  side: 1,
+  price: 65000,
+  size: 0.01,
+  type: 0
+});
+
+// WebSocket — stream real-time updates
+const socket = await MetaScalpSocket.discover();
+
+// Connection-level: orders, positions, balances for ALL tickers on this connection
+socket.subscribe(conn.id);
+socket.on('order_update', (data) => console.log('Order:', data));
+socket.on('position_update', (data) => console.log('Position:', data));
+socket.on('balance_update', (data) => console.log('Balance:', data));
+
+// Market data: trades and order book for a SPECIFIC ticker (independent from subscribe)
+socket.subscribeTrades(conn.id, 'BTCUSDT');
+socket.on('trade_update', (data) => console.log('Trade:', data));
+
+socket.subscribeOrderBook(conn.id, 'BTCUSDT');
+socket.on('orderbook_snapshot', (data) => console.log('OB Snapshot:', data));
+socket.on('orderbook_update', (data) => console.log('OB Update:', data));
+```
+
+### Python
+
+```python
+import asyncio
+from metascalp import MetaScalpClient, MetaScalpSocket
+
+async def main():
+    # REST
+    client = await MetaScalpClient.discover()
+    connections = await client.get_connections()
+    conn = connections['connections'][0]
+
+    # Place order
+    await client.place_order(conn['id'], ticker='BTCUSDT', side=1, price=65000, size=0.01)
+
+    # WebSocket
+    socket = await MetaScalpSocket.discover()
+
+    # Connection-level events (from subscribe) — all tickers
+    @socket.on('order_update')
+    def on_order(data):
+        print(f"Order: {data['ticker']} {data['side']} {data['status']}")
+
+    @socket.on('balance_update')
+    def on_balance(data):
+        print(f"Balance: {data}")
+
+    # Market data events (from subscribe_trades / subscribe_order_book) — specific ticker
+    @socket.on('trade_update')
+    def on_trade(data):
+        print(f"Trade: {data}")
+
+    @socket.on('orderbook_snapshot')
+    def on_snapshot(data):
+        print(f"Snapshot: {len(data['asks'])} asks, {len(data['bids'])} bids")
+
+    # Connection-level: orders, positions, balances for ALL tickers
+    socket.subscribe(conn['id'])
+
+    # Market data: trades and order book for a SPECIFIC ticker (independent from subscribe)
+    socket.subscribe_trades(conn['id'], 'BTCUSDT')
+    socket.subscribe_order_book(conn['id'], 'BTCUSDT')
+
+    await socket.listen_forever()
+
+asyncio.run(main())
+```
+
+### C# / .NET
+
+```csharp
+using MetaScalp.Sdk;
+
+// REST
+var client = await MetaScalpClient.DiscoverAsync();
+var connections = await client.GetConnectionsAsync();
+var conn = connections.First();
+
+await client.PlaceOrderAsync(conn.Id, new PlaceOrderRequest
+{
+    Ticker = "BTCUSDT",
+    Side = 1,
+    Price = 65000m,
+    Size = 0.01m,
+    Type = 0
+});
+
+// WebSocket
+var socket = await MetaScalpSocket.DiscoverAsync();
+
+// Connection-level events (from Subscribe) — all tickers
+socket.OnOrderUpdate += (data) => Console.WriteLine($"Order: {data.Ticker} {data.Side} {data.Status}");
+socket.OnBalanceUpdate += (data) => Console.WriteLine($"Balance updated");
+
+// Market data events (from SubscribeTrades / SubscribeOrderBook) — specific ticker
+socket.OnTradeUpdate += (data) => Console.WriteLine($"Trade: {data.Ticker} {data.Trades.Count} trades");
+socket.OnOrderBookSnapshot += (data) => Console.WriteLine($"OB: {data.Asks.Count} asks, {data.Bids.Count} bids");
+
+// Connection-level: orders, positions, balances for ALL tickers
+socket.Subscribe(conn.Id);
+
+// Market data: trades and order book for a SPECIFIC ticker (independent from Subscribe)
+socket.SubscribeTrades(conn.Id, "BTCUSDT");
+socket.SubscribeOrderBook(conn.Id, "BTCUSDT");
+```
+
+## API Overview
+
+Full reference with request/response shapes: [MetaScalp API docs](https://metascalp.github.io/metascalp-sdk/) ([markdown](./docs/MetaScalp-Api.md)).
+
+### REST Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/ping` | Discover running MetaScalp instance |
+| `GET` | `/api/connections` | List active exchange connections |
+| `GET` | `/api/connections/{id}` | Get single connection details |
+| `GET` | `/api/connections/{id}/tickers` | List available tickers (`?Refresh=true` re-fetches from the exchange) |
+| `GET` | `/api/connections/{id}/orders?Ticker=X` | Get open orders |
+| `GET` | `/api/connections/{id}/positions` | Get open positions |
+| `GET` | `/api/connections/{id}/balance` | Get account balances |
+| `GET` | `/api/connections/{id}/orderbook-snapshot?Ticker=X` | One-shot fresh order book snapshot from the exchange REST endpoint |
+| `GET` | `/api/connections/{id}/cluster-snapshot?Ticker=X&TimeFrame=M5` | Cluster (volume profile) snapshot; `Columns=1..100` fills more history than the default 10 columns |
+| `POST` | `/api/connections/{id}/orders` | Place an order |
+| `POST` | `/api/connections/{id}/orders/cancel` | Cancel an order |
+| `POST` | `/api/connections/{id}/orders/cancel-all` | Cancel all orders for a ticker |
+| `GET/POST/PUT/DELETE` | `/api/connections/{id}/signal-levels[/{slId}]` | Full signal-level CRUD (+ `DELETE /api/signal-levels/triggered`) |
+| `GET/POST/PUT/DELETE` | `/api/connections/{id}/user-levels[/{ulId}]` | Full user (plain) level CRUD |
+| `GET/PUT/POST/DELETE` | `/api/connections/{id}/annotations[/{type}[/{index}]]` | Chart annotations: read all three lists, replace a list, append one, delete by index, clear all |
+| `GET/PUT` | `/api/connections/{id}/orderbook-settings?Ticker=X` | Read / partially update order book settings |
+| `POST` | `/api/notifications` | Inject a custom row into the notification feed |
+| `GET` | `/api/ui/state`, `/api/ui/windows/{windowId}` | Read-only inventory of the open UI (windows, tabs, documents) |
+| `PUT` | `/api/ui/documents/{externalId}/link-number`, `.../ticker` | Set a panel's link group / re-point a panel to another market |
+| `POST` | `/api/change-ticker` | Switch ticker in MetaScalp UI |
+| `POST` | `/api/combo` | Open combo layout |
+
+### WebSocket Messages
+
+**Connection-level** — subscribe by `connectionId`:
+
+| Subscribe | Updates received |
+|-----------|-----------------|
+| `subscribe` | `order_update`, `position_update`, `balance_update`, `finres_update` |
+
+**Market data** — subscribe by `connectionId` + `ticker`:
+
+| Subscribe | Updates received |
+|-----------|-----------------|
+| `trade_subscribe` | `trade_update` (aggregated ticks carry `highPrice`/`lowPrice`) |
+| `orderbook_subscribe` | `orderbook_snapshot`, `orderbook_update` |
+| `mark_price_subscribe` | `mark_price_update` (futures only) |
+| `index_price_subscribe` | `index_price_update` (futures only) |
+| `funding_subscribe` | `funding_update` (perpetual futures only) |
+| `annotation_subscribe` | one-shot `annotations_snapshot` of the current chart annotations |
+
+**App-wide** — no `connectionId` required:
+
+| Subscribe | Updates received |
+|-----------|-----------------|
+| `notification_subscribe` | `notification_update` (including custom rows injected via `POST /api/notifications`) |
+| `signal_level_subscribe` | `signal_level_placed/updated/triggered/removed/...` |
+| `user_level_subscribe` | `user_level_placed/updated/removed/...` |
+| `ui_subscribe` | `ui_snapshot`, then `ui_update` on UI changes |
+| `density_map_subscribe` | `density_map_snapshot`, then `density_map_update` — MetaBroker order-book walls, one notification per wall |
+| `large_trades_subscribe` | `large_trades_update` — MetaBroker aggregated large trade prints (append-only, no snapshot) |
+| `liquidations_subscribe` | `liquidations_snapshot`, `liquidations_update`, `liquidations_metadata` — MetaBroker cross-exchange liquidations (no MetaBroker login needed) |
+
+> **SDK coverage note.** The js / python / dotnet convenience wrappers currently cover the core surface (connections, orders, positions, balances, market data) plus the MetaBroker analytics streams (density map, large trades, liquidations). The newer families (levels, annotations, notifications, UI) are available through the same clients as plain REST calls / raw WS messages until dedicated wrappers ship.
+
+> **Mass-subscribe optimization.** `orderbook_subscribe` accepts an optional `fetchSnapshot` field (default `true`). Pass `false` to skip the exchange REST snapshot fetch when subscribing — useful when subscribing to 100+ tickers at once without hitting exchange REST rate limits. Seed state separately via `GET /api/connections/{id}/orderbook-snapshot` when you need it. A later subscriber that wants a snapshot triggers a lazy fetch that fans out to all listeners.
+
+## Connection Details
+
+- **Host:** `127.0.0.1` (localhost only)
+- **Port range:** `17845`–`17855` (first available, shared by HTTP and WebSocket)
+- Both REST and WebSocket run on the same port — no separate socket port
+- All SDKs include auto-discovery that scans the port range
+
+## License
+
+MIT

metascalp-1.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+metascalp/__init__.py,sha256=PWdfEtoNN4Fveo39MGy3oLdqdffdXkuAGrj7JR2c8CE,122
+metascalp/client.py,sha256=M1i5-7x0U1ZYVm12BXlSVN_ZYW8A73ee1aUFof81Ffc,11879
+metascalp/socket.py,sha256=sOM6rKKDE9cbpefY1wu11z2Kiel-SihpZHq080-muqc,19483
+metascalp-1.1.0.dist-info/METADATA,sha256=dV0j2De6mpP56-OGW1h0HUdUbDaeqCceZBK7IrFaDK4,10695
+metascalp-1.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+metascalp-1.1.0.dist-info/top_level.txt,sha256=pArHJVJ5B00E-WpcoBIHuxmTCr4CLpReZP_74Sv3qj8,10
+metascalp-1.1.0.dist-info/RECORD,,

metascalp-1.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

metascalp-1.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+metascalp