followsm-sdk 0.1.0__tar.gz

followsm_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: followsm-sdk
+Version: 0.1.0
+Summary: Official Python SDK for the FollowSM smart-money & orderbook toxicity API
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31
+Requires-Dist: pydantic>=2.0
+Requires-Dist: websockets>=12.0
+Requires-Dist: pytest>=8.0 ; extra == "test"
+Requires-Dist: pytest-mock>=3.12 ; extra == "test"
+Project-URL: Documentation, https://follow-sm.com/docs
+Project-URL: Homepage, https://follow-sm.com
+Provides-Extra: test
+
+# followsm-sdk
+
+Official Python SDK for the [FollowSM](https://follow-sm.com) smart-money & orderbook toxicity API.
+
+## Install
+
+```bash
+pip install followsm-sdk
+```
+
+## Quickstart
+
+```python
+from followsm_sdk import FollowSMClient
+
+client = FollowSMClient(api_key="fsm_live_...")  # or omit to use the free tier
+snapshot = client.get_toxicity_snapshot("BTCUSDT")
+print(snapshot.vpin, snapshot.is_toxic_alert)
+```
+
+## Free vs Developer API
+
+| | Free / Unauthenticated | DEVELOPER_API ($199/mo) |
+|---|---|---|
+| Requests/min | 30 | 300 |
+| WebSocket connections | 1 | Multiple |
+| Binance pairs | Limited | 50+ |
+| Latency | Standard | Sub-10ms in-memory snapshots |
+
+On HTTP 429, the SDK raises `RateLimitExceededException` with an upgrade prompt pointing to https://follow-sm.com/pricing.
+

followsm_sdk-0.1.0/README.md

@@ -0,0 +1,30 @@
+# followsm-sdk
+
+Official Python SDK for the [FollowSM](https://follow-sm.com) smart-money & orderbook toxicity API.
+
+## Install
+
+```bash
+pip install followsm-sdk
+```
+
+## Quickstart
+
+```python
+from followsm_sdk import FollowSMClient
+
+client = FollowSMClient(api_key="fsm_live_...")  # or omit to use the free tier
+snapshot = client.get_toxicity_snapshot("BTCUSDT")
+print(snapshot.vpin, snapshot.is_toxic_alert)
+```
+
+## Free vs Developer API
+
+| | Free / Unauthenticated | DEVELOPER_API ($199/mo) |
+|---|---|---|
+| Requests/min | 30 | 300 |
+| WebSocket connections | 1 | Multiple |
+| Binance pairs | Limited | 50+ |
+| Latency | Standard | Sub-10ms in-memory snapshots |
+
+On HTTP 429, the SDK raises `RateLimitExceededException` with an upgrade prompt pointing to https://follow-sm.com/pricing.

followsm_sdk-0.1.0/followsm_sdk/__init__.py

@@ -0,0 +1,16 @@
+"""followsm-sdk — official Python client for the FollowSM API."""
+
+from .client import FollowSMClient
+from .exceptions import AuthenticationError, FollowSMError, RateLimitExceededException
+from .models import OrderBookDepthBand, SymbolToxicityMetrics
+
+__all__ = [
+    "FollowSMClient",
+    "FollowSMError",
+    "RateLimitExceededException",
+    "AuthenticationError",
+    "SymbolToxicityMetrics",
+    "OrderBookDepthBand",
+]
+
+__version__ = "0.1.0"

followsm_sdk-0.1.0/followsm_sdk/client.py

@@ -0,0 +1,79 @@
+"""Core synchronous + async streaming client for the FollowSM API."""
+
+from __future__ import annotations
+
+import json
+from typing import AsyncIterator, List, Optional
+
+import requests
+import websockets
+
+from .exceptions import AuthenticationError, RateLimitExceededException
+from .models import SymbolToxicityMetrics
+
+DEFAULT_BASE_URL = "https://follow-sm.com/api/v1"
+DEFAULT_WS_URL = "wss://follow-sm.com/api/v1/developer/toxicity/stream"
+FREE_COMMUNITY_KEY = "FREE_COMMUNITY_KEY"
+
+
+class FollowSMClient:
+    """Client for the FollowSM Developer API.
+
+    Falls back to the shared FREE_COMMUNITY_KEY (30 req/min, unauthenticated
+    tier) when no `api_key` is supplied.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        ws_url: str = DEFAULT_WS_URL,
+        timeout: float = 10.0,
+    ):
+        self.api_key = api_key or FREE_COMMUNITY_KEY
+        self.base_url = base_url.rstrip("/")
+        self.ws_url = ws_url
+        self.timeout = timeout
+
+    def _headers(self) -> dict:
+        return {"X-FollowSM-Key": self.api_key}
+
+    def _handle_response(self, response: requests.Response) -> requests.Response:
+        if response.status_code == 429:
+            reset_time = int(response.headers.get("X-RateLimit-Reset", 0))
+            raise RateLimitExceededException(
+                response.json().get("detail", "Rate limit exceeded")
+                if response.content
+                else "Rate limit exceeded",
+                reset_time,
+            )
+        if response.status_code in (401, 403):
+            raise AuthenticationError(response.text)
+        response.raise_for_status()
+        return response
+
+    def get_toxicity_snapshot(self, symbol: str) -> SymbolToxicityMetrics:
+        response = requests.get(
+            f"{self.base_url}/developer/toxicity/snapshot",
+            params={"symbol": symbol},
+            headers=self._headers(),
+            timeout=self.timeout,
+        )
+        self._handle_response(response)
+        return SymbolToxicityMetrics.model_validate(response.json())
+
+    def get_toxic_pairs(self) -> List[SymbolToxicityMetrics]:
+        response = requests.get(
+            f"{self.base_url}/developer/toxicity/toxic-pairs",
+            headers=self._headers(),
+            timeout=self.timeout,
+        )
+        self._handle_response(response)
+        return [SymbolToxicityMetrics.model_validate(item) for item in response.json()]
+
+    async def stream_toxicity(self) -> AsyncIterator[SymbolToxicityMetrics]:
+        """Async-iterate live toxicity snapshots over the WebSocket feed."""
+        uri = f"{self.ws_url}?api_key={self.api_key}"
+        async with websockets.connect(uri) as ws:
+            async for message in ws:
+                yield SymbolToxicityMetrics.model_validate(json.loads(message))

followsm_sdk-0.1.0/followsm_sdk/exceptions.py

@@ -0,0 +1,22 @@
+"""Custom exceptions raised by the FollowSM SDK."""
+
+
+class FollowSMError(Exception):
+    """Base class for all FollowSM SDK errors."""
+
+
+class RateLimitExceededException(FollowSMError):
+    def __init__(self, message: str, reset_time: int):
+        self.reset_time = reset_time
+        upgrade_url = "https://follow-sm.com/pricing"
+        formatted_msg = (
+            f"\n\033[91m[FollowSM RateLimitExceeded]\033[0m {message}\n"
+            f"\033[93m⚡️ Free Tier Limit Reached (30 req/min).\033[0m\n"
+            f"Unlock 300 req/min, 50+ Binance pairs & sub-10ms latency:\n"
+            f"👉 \033[94m{upgrade_url}\033[0m\n"
+        )
+        super().__init__(formatted_msg)
+
+
+class AuthenticationError(FollowSMError):
+    """Raised on HTTP 401/403 responses (invalid key or insufficient plan)."""

followsm_sdk-0.1.0/followsm_sdk/models.py

@@ -0,0 +1,27 @@
+"""Pydantic data models mirroring backend/models/toxicity_models.py."""
+
+from __future__ import annotations
+
+from typing import Dict
+
+from pydantic import BaseModel
+
+
+class OrderBookDepthBand(BaseModel):
+    bid_notional: float
+    ask_notional: float
+    imbalance_ratio: float
+
+
+class SymbolToxicityMetrics(BaseModel):
+    symbol: str
+    timestamp: float
+    price: float
+    vpin: float
+    ob_toxicity_1pct: float
+    ob_imbalance_l1: float
+    depth_bands: Dict[str, OrderBookDepthBand]
+    volume_z_score: float
+    natr_15m: float
+    taker_buy_ratio: float
+    is_toxic_alert: bool

followsm_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["flit_core>=3.9,<4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "followsm-sdk"
+version = "0.1.0"
+description = "Official Python SDK for the FollowSM smart-money & orderbook toxicity API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+dependencies = [
+    "requests>=2.31",
+    "pydantic>=2.0",
+    "websockets>=12.0",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8.0", "pytest-mock>=3.12"]
+
+[project.urls]
+Homepage = "https://follow-sm.com"
+Documentation = "https://follow-sm.com/docs"