followsm-sdk

Official Python SDK for the FollowSM smart-money & orderbook toxicity API.

Install

pip install followsm-sdk

Quickstart

from followsm_sdk import FollowSMClient

client = FollowSMClient(api_key="fsm_live_...")  # or omit for the free, IP-rate-limited tier
snapshot = client.get_toxicity_snapshot("BTCUSDT")
print(snapshot.vpin, snapshot.is_toxic_alert)

toxic_pairs = client.get_toxic_pairs()  # also works without an api_key

SymbolToxicityMetrics response

get_toxicity_snapshot() and get_toxic_pairs() both return SymbolToxicityMetrics (pydantic models), matching the raw JSON the backend returns:

{
  "symbol": "BTCUSDT",
  "timestamp": 1758412800.0,
  "price": 62150.5,
  "vpin": 0.72,
  "ob_toxicity_1pct": 2.35,
  "ob_imbalance_l1": 0.61,
  "depth_bands": {
    "0.5%": { "bid_notional": 184320.0, "ask_notional": 96410.0, "imbalance_ratio": 0.657 },
    "1.0%": { "bid_notional": 312500.0, "ask_notional": 210800.0, "imbalance_ratio": 0.597 },
    "2.0%": { "bid_notional": 590100.0, "ask_notional": 470200.0, "imbalance_ratio": 0.556 }
  },
  "volume_z_score": 3.1,
  "natr_15m": 0.84,
  "taker_buy_ratio": 0.58,
  "is_toxic_alert": true
}

Free vs Developer API

On HTTP 429, the SDK raises RateLimitExceededException with an upgrade prompt pointing to https://follow-sm.com/pricing.

Live streaming (Enterprise only)

stream_toxicity() connects to /ws/v1/toxicity, which requires an API key on an active Enterprise subscription — Developer API and free/unauthenticated keys are rejected with close code 4003.

import asyncio
from followsm_sdk import FollowSMClient

async def main() -> None:
    client = FollowSMClient(api_key="fsm_live_...")
    async for snapshot in client.stream_toxicity():
        print(snapshot.symbol, snapshot.vpin, snapshot.is_toxic_alert)

asyncio.run(main())