lpsignal 0.1.0__py3-none-any.whl

lpsignal/__init__.py

@@ -0,0 +1,12 @@
+"""Official LPSignal SDK: net-of-IL APR signals for concentrated-liquidity pools."""
+
+from .client import DEFAULT_BASE_URL, AsyncLPSignal, LPSignal, LPSignalError
+from .stream import FileLastIdStore, LastIdStore, MemoryLastIdStore, SignalStream
+from .webhook import WebhookVerificationError, verify_webhook
+
+__all__ = [
+    "DEFAULT_BASE_URL", "AsyncLPSignal", "LPSignal", "LPSignalError",
+    "FileLastIdStore", "LastIdStore", "MemoryLastIdStore", "SignalStream",
+    "WebhookVerificationError", "verify_webhook",
+]
+__version__ = "0.1.0"

lpsignal/client.py

@@ -0,0 +1,375 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from typing import Any, AsyncIterator, Iterator, Literal, Optional
+from urllib.parse import quote
+
+import httpx
+
+from .types import (
+    Backtest, BillingStatus, ChainStatus, Follow, Leaderboard, Me, PoolDetail, PoolHour, PoolsPage, Signal,
+    SignalsPage, TelegramLink, WalletPositions, WebhookRegistration,
+)
+
+DEFAULT_BASE_URL = "https://api.lpsignal.app"
+_IDEMPOTENT = {"GET", "PUT", "DELETE"}
+_MAX_RETRY_WAIT = 60.0
+
+
+class LPSignalError(Exception):
+    """A non-2xx answer from the API. `code` is the API's stable `error` field (e.g. `rate_limited`)."""
+
+    def __init__(self, status: int, body: Any, request_id: Optional[str] = None):
+        self.status = status
+        self.body = body
+        self.request_id = request_id
+        self.code: Optional[str] = body.get("error") if isinstance(body, dict) and isinstance(body.get("error"), str) else None
+        detail = body if isinstance(body, str) else json.dumps(body)
+        super().__init__(f"LPSignal API {status}{' ' + self.code if self.code else ''}"
+                         f"{f' (request {request_id})' if request_id else ''}: {detail}")
+
+
+def _q(v: str) -> str:
+    return quote(str(v), safe="")
+
+
+class _Base:
+    def __init__(self, api_key: Optional[str], base_url: str, timeout: float, max_retries: int):
+        if api_key is not None and not api_key.startswith("lps_"):
+            raise ValueError('api_key must start with "lps_"')
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+    @property
+    def stream_url(self) -> str:
+        """The stream URL derived from the base URL (https → wss)."""
+        return ("ws" + self.base_url[4:] if self.base_url.startswith("http") else self.base_url) + "/v1/stream"
+
+    @property
+    def _headers(self) -> dict[str, str]:
+        h = {"accept": "application/json"}
+        if self.api_key:
+            h["authorization"] = f"Bearer {self.api_key}"
+        return h
+
+    @staticmethod
+    def _params(query: Optional[dict[str, Any]]) -> dict[str, Any]:
+        return {k: v for k, v in (query or {}).items() if v is not None}
+
+    @staticmethod
+    def _body(res: httpx.Response) -> Any:
+        text = res.text
+        if not text:
+            return None
+        try:
+            return json.loads(text)
+        except ValueError:
+            return text
+
+    def _retry_wait(self, method: str, res: httpx.Response, body: Any, attempt: int) -> Optional[float]:
+        """Seconds to wait before retrying, or None to raise."""
+        if res.status_code != 429 or method not in _IDEMPOTENT or attempt >= self.max_retries:
+            return None
+        raw = res.headers.get("retry-after") or (body.get("retryAfterSec") if isinstance(body, dict) else None)
+        try:
+            after = float(raw) if raw is not None else 1.0
+        except (TypeError, ValueError):
+            after = 1.0
+        return min(_MAX_RETRY_WAIT, after if after > 0 else 1.0)
+
+    @staticmethod
+    def _pools_query(chain, pair_class, window, min_tvl_usd, limit, offset) -> dict[str, Any]:
+        return {"chain": chain, "class": pair_class, "window": window, "minTvlUsd": min_tvl_usd, "limit": limit, "offset": offset}
+
+
+class LPSignal(_Base):
+    """Synchronous client for the LPSignal API. `api_key` is optional: public endpoints work without one
+    (opportunity signals then arrive 24h late)."""
+
+    def __init__(self, api_key: Optional[str] = None, base_url: str = DEFAULT_BASE_URL, timeout: float = 15.0,
+                 max_retries: int = 2, http: Optional[httpx.Client] = None):
+        super().__init__(api_key, base_url, timeout, max_retries)
+        self._http = http or httpx.Client(timeout=timeout)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "LPSignal":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def request(self, method: str, path: str, query: Optional[dict[str, Any]] = None, body: Any = None) -> Any:
+        attempt = 0
+        while True:
+            res = self._http.request(method, self.base_url + path, params=self._params(query), headers=self._headers,
+                                     json=body)
+            parsed = self._body(res)
+            if res.is_success:
+                return parsed
+            wait = self._retry_wait(method, res, parsed, attempt)
+            if wait is None:
+                raise LPSignalError(res.status_code, parsed, res.headers.get("x-request-id"))
+            time.sleep(wait)
+            attempt += 1
+
+    # ── status
+    def health(self) -> dict[str, Any]:
+        return self.request("GET", "/v1/health")
+
+    def chains(self) -> list[ChainStatus]:
+        """Scan progress per chain."""
+        return self.request("GET", "/v1/chains")["chains"]
+
+    # ── pools
+    def pools(self, chain: Optional[str] = None, pair_class: Optional[str] = None, window: Optional[int] = None,
+              min_tvl_usd: Optional[float] = None, limit: Optional[int] = None, offset: Optional[int] = None) -> PoolsPage:
+        """Active pools ranked by their best range's net APR over `window` hours (24, 168 or 720)."""
+        return self.request("GET", "/v1/pools", self._pools_query(chain, pair_class, window, min_tvl_usd, limit, offset))
+
+    def pool(self, chain: str, address: str) -> PoolDetail:
+        """One pool with every (window, range) metric. `address` is the pool id for Uniswap v4."""
+        return self.request("GET", f"/v1/pools/{_q(chain)}/{_q(address)}")
+
+    def pool_hours(self, chain: str, address: str, hours: Optional[int] = None) -> list[PoolHour]:
+        """Hourly aggregates, oldest first (at most 720 hours)."""
+        return self.request("GET", f"/v1/pools/{_q(chain)}/{_q(address)}/hours", {"hours": hours})["hours"]
+
+    def backtest(self, chain: str, address: str, range_pct: float, days: Optional[int] = None) -> Backtest:
+        """Backtest a symmetric ±`range_pct`% range (0 = full range) over the last `days` (1..30, default 7)."""
+        return self.request("GET", f"/v1/pools/{_q(chain)}/{_q(address)}/backtest", {"rangePct": range_pct, "days": days})
+
+    # ── signals
+    def signals(self, kind: Optional[str] = None, limit: Optional[int] = None, before: Optional[str] = None) -> SignalsPage:
+        """One page of signals, newest first."""
+        return self.request("GET", "/v1/signals", {"kind": kind, "limit": limit, "before": before})
+
+    def signal_stats(self, days: Optional[int] = None) -> dict[str, Any]:
+        """The public track record over the last `days` (7..365, default 30)."""
+        return self.request("GET", "/v1/signals/stats", {"days": days})
+
+    def signal(self, signal_id: str) -> Signal:
+        return self.request("GET", f"/v1/signals/{_q(signal_id)}")
+
+    def iter_signals(self, kind: Optional[str] = None, limit: int = 100) -> Iterator[Signal]:
+        """Every signal matching `kind`, newest first, following the `next` cursor page by page."""
+        before: Optional[str] = None
+        while True:
+            page = self.signals(kind=kind, limit=limit, before=before)
+            yield from page["signals"]
+            if not page["next"]:
+                return
+            before = page["next"]
+
+    def signals_after(self, after_id: str) -> list[Signal]:
+        """Every signal visible to this key with an id greater than `after_id`, oldest first."""
+        newer: list[Signal] = []
+        for s in self.iter_signals():
+            if int(s["id"]) <= int(after_id):
+                break
+            newer.append(s)
+        newer.reverse()
+        return newer
+
+    # ── smart LPs
+    def smart_lps(self, window_days: Optional[int] = None, chain: Optional[str] = None, limit: Optional[int] = None) -> Leaderboard:
+        """Wallets ranked by LP pnl versus holding. Without Pro: the top 10 with masked addresses."""
+        return self.request("GET", "/v1/smart-lps", {"windowDays": window_days, "chain": chain, "limit": limit})
+
+    def wallet_positions(self, owner: str, limit: Optional[int] = None) -> WalletPositions:
+        """A wallet's open and closed positions (Pro)."""
+        return self.request("GET", f"/v1/smart-lps/{_q(owner)}/positions", {"limit": limit})
+
+    def follows(self) -> list[Follow]:
+        """Wallets you follow (Pro)."""
+        return self.request("GET", "/v1/me/follows")["follows"]
+
+    def follow(self, owner: str) -> dict[str, Any]:
+        """Follow a wallet: its new positions of $10k+ become smart_lp signals for you (Pro, up to 50)."""
+        return self.request("PUT", f"/v1/me/follows/{_q(owner)}")
+
+    def unfollow(self, owner: str) -> None:
+        self.request("DELETE", f"/v1/me/follows/{_q(owner)}")
+
+    # ── account
+    def me(self) -> Me:
+        return self.request("GET", "/v1/me")
+
+    def set_webhook(self, url: str) -> WebhookRegistration:
+        """Set or replace the webhook. The signing secret is returned only here."""
+        return self.request("PUT", "/v1/me/webhook", body={"url": url})
+
+    def delete_webhook(self) -> None:
+        self.request("DELETE", "/v1/me/webhook")
+
+    def create_api_key(self, replace: Optional[bool] = None) -> dict[str, str]:
+        """Create a new API key and return it (shown only here). By default it replaces the current key, which stops
+        working at once; `replace=False` only creates one when the account has none (else 409 `api_key_exists`)."""
+        return self.request("POST", "/v1/me/api-key", body=None if replace is None else {"replace": replace})
+
+    def telegram_link(self) -> TelegramLink:
+        """A one-time code: send `/start <code>` to the LPSignal Telegram bot."""
+        return self.request("POST", "/v1/me/telegram-link")
+
+    # ── billing
+    def billing(self, refresh: bool = False) -> BillingStatus:
+        """Current plan. `refresh=True` re-reads Stripe first (use it right after a checkout)."""
+        return self.request("GET", "/v1/billing", {"refresh": 1 if refresh else None})
+
+    def checkout(self, tier: Literal["basic", "pro"]) -> dict[str, str]:
+        """A Stripe Checkout URL for a monthly plan."""
+        return self.request("POST", "/v1/billing/checkout", body={"tier": tier})
+
+    def billing_portal(self) -> dict[str, str]:
+        """A Stripe Customer Portal URL (change plan, cancel, invoices)."""
+        return self.request("POST", "/v1/billing/portal")
+
+    def crypto_billing(self) -> dict[str, Any]:
+        """Prepaid USDT/USDC plans: prices for this account (upgrade credit applied), networks, the open order."""
+        return self.request("GET", "/v1/billing/crypto")
+
+    def create_crypto_order(self, tier: Literal["basic", "pro"], months: Literal[1, 3, 12]) -> dict[str, Any]:
+        """Start (or get back the open) crypto order; send exactly `amount` before `expiresAt`."""
+        return self.request("POST", "/v1/billing/crypto/orders", body={"tier": tier, "months": months})
+
+    def crypto_order(self, order_id: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/billing/crypto/orders/{_q(order_id)}")
+
+    def cancel_crypto_order(self, order_id: str) -> dict[str, Any]:
+        """Withdraw an open order (a payment already sent before its deadline still pays it)."""
+        return self.request("POST", f"/v1/billing/crypto/orders/{_q(order_id)}/cancel")
+
+
+class AsyncLPSignal(_Base):
+    """Asynchronous client; same methods as `LPSignal`, awaitable. Needed by `SignalStream`."""
+
+    def __init__(self, api_key: Optional[str] = None, base_url: str = DEFAULT_BASE_URL, timeout: float = 15.0,
+                 max_retries: int = 2, http: Optional[httpx.AsyncClient] = None):
+        super().__init__(api_key, base_url, timeout, max_retries)
+        self._http = http or httpx.AsyncClient(timeout=timeout)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncLPSignal":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+    async def request(self, method: str, path: str, query: Optional[dict[str, Any]] = None, body: Any = None) -> Any:
+        attempt = 0
+        while True:
+            res = await self._http.request(method, self.base_url + path, params=self._params(query), headers=self._headers,
+                                           json=body)
+            parsed = self._body(res)
+            if res.is_success:
+                return parsed
+            wait = self._retry_wait(method, res, parsed, attempt)
+            if wait is None:
+                raise LPSignalError(res.status_code, parsed, res.headers.get("x-request-id"))
+            await asyncio.sleep(wait)
+            attempt += 1
+
+    async def health(self) -> dict[str, Any]:
+        return await self.request("GET", "/v1/health")
+
+    async def chains(self) -> list[ChainStatus]:
+        return (await self.request("GET", "/v1/chains"))["chains"]
+
+    async def pools(self, chain: Optional[str] = None, pair_class: Optional[str] = None, window: Optional[int] = None,
+                    min_tvl_usd: Optional[float] = None, limit: Optional[int] = None, offset: Optional[int] = None) -> PoolsPage:
+        return await self.request("GET", "/v1/pools", self._pools_query(chain, pair_class, window, min_tvl_usd, limit, offset))
+
+    async def pool(self, chain: str, address: str) -> PoolDetail:
+        return await self.request("GET", f"/v1/pools/{_q(chain)}/{_q(address)}")
+
+    async def pool_hours(self, chain: str, address: str, hours: Optional[int] = None) -> list[PoolHour]:
+        return (await self.request("GET", f"/v1/pools/{_q(chain)}/{_q(address)}/hours", {"hours": hours}))["hours"]
+
+    async def backtest(self, chain: str, address: str, range_pct: float, days: Optional[int] = None) -> Backtest:
+        return await self.request("GET", f"/v1/pools/{_q(chain)}/{_q(address)}/backtest", {"rangePct": range_pct, "days": days})
+
+    async def signals(self, kind: Optional[str] = None, limit: Optional[int] = None, before: Optional[str] = None) -> SignalsPage:
+        return await self.request("GET", "/v1/signals", {"kind": kind, "limit": limit, "before": before})
+
+    async def signal_stats(self, days: Optional[int] = None) -> dict[str, Any]:
+        return await self.request("GET", "/v1/signals/stats", {"days": days})
+
+    async def signal(self, signal_id: str) -> Signal:
+        return await self.request("GET", f"/v1/signals/{_q(signal_id)}")
+
+    async def iter_signals(self, kind: Optional[str] = None, limit: int = 100) -> AsyncIterator[Signal]:
+        before: Optional[str] = None
+        while True:
+            page = await self.signals(kind=kind, limit=limit, before=before)
+            for s in page["signals"]:
+                yield s
+            if not page["next"]:
+                return
+            before = page["next"]
+
+    async def signals_after(self, after_id: str) -> list[Signal]:
+        newer: list[Signal] = []
+        async for s in self.iter_signals():
+            if int(s["id"]) <= int(after_id):
+                break
+            newer.append(s)
+        newer.reverse()
+        return newer
+
+    async def smart_lps(self, window_days: Optional[int] = None, chain: Optional[str] = None, limit: Optional[int] = None) -> Leaderboard:
+        return await self.request("GET", "/v1/smart-lps", {"windowDays": window_days, "chain": chain, "limit": limit})
+
+    async def wallet_positions(self, owner: str, limit: Optional[int] = None) -> WalletPositions:
+        return await self.request("GET", f"/v1/smart-lps/{_q(owner)}/positions", {"limit": limit})
+
+    async def follows(self) -> list[Follow]:
+        return (await self.request("GET", "/v1/me/follows"))["follows"]
+
+    async def follow(self, owner: str) -> dict[str, Any]:
+        return await self.request("PUT", f"/v1/me/follows/{_q(owner)}")
+
+    async def unfollow(self, owner: str) -> None:
+        await self.request("DELETE", f"/v1/me/follows/{_q(owner)}")
+
+    async def me(self) -> Me:
+        return await self.request("GET", "/v1/me")
+
+    async def set_webhook(self, url: str) -> WebhookRegistration:
+        return await self.request("PUT", "/v1/me/webhook", body={"url": url})
+
+    async def delete_webhook(self) -> None:
+        await self.request("DELETE", "/v1/me/webhook")
+
+    async def create_api_key(self, replace: Optional[bool] = None) -> dict[str, str]:
+        return await self.request("POST", "/v1/me/api-key", body=None if replace is None else {"replace": replace})
+
+    async def telegram_link(self) -> TelegramLink:
+        return await self.request("POST", "/v1/me/telegram-link")
+
+    async def billing(self, refresh: bool = False) -> BillingStatus:
+        return await self.request("GET", "/v1/billing", {"refresh": 1 if refresh else None})
+
+    async def checkout(self, tier: Literal["basic", "pro"]) -> dict[str, str]:
+        return await self.request("POST", "/v1/billing/checkout", body={"tier": tier})
+
+    async def billing_portal(self) -> dict[str, str]:
+        return await self.request("POST", "/v1/billing/portal")
+
+    async def crypto_billing(self) -> dict[str, Any]:
+        return await self.request("GET", "/v1/billing/crypto")
+
+    async def create_crypto_order(self, tier: Literal["basic", "pro"], months: Literal[1, 3, 12]) -> dict[str, Any]:
+        return await self.request("POST", "/v1/billing/crypto/orders", body={"tier": tier, "months": months})
+
+    async def crypto_order(self, order_id: str) -> dict[str, Any]:
+        return await self.request("GET", f"/v1/billing/crypto/orders/{_q(order_id)}")
+
+    async def cancel_crypto_order(self, order_id: str) -> dict[str, Any]:
+        return await self.request("POST", f"/v1/billing/crypto/orders/{_q(order_id)}/cancel")

lpsignal/stream.py

@@ -0,0 +1,305 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import inspect
+import json
+import os
+from pathlib import Path
+from typing import Any, Awaitable, Callable, Literal, Optional, Protocol, Union
+
+from websockets.asyncio.client import ClientConnection, connect
+from websockets.exceptions import ConnectionClosed, InvalidStatus
+
+from .client import AsyncLPSignal, LPSignalError
+from .types import Signal
+
+Source = Literal["rest", "replay", "live"]
+
+
+class LastIdStore(Protocol):
+    """Where the stream is: the id of the last signal handled. Persist it to resume after a restart.
+
+    To make a crash unable to repeat a signal's side effects, keep the id in the same database transaction as those
+    effects (write it inside on_signal) and pass a store over that same row. Its save() must only move forward
+    (e.g. `SET last_id = GREATEST(last_id, %s)`): the stream also saves the starting point with it.
+    """
+
+    def load(self) -> Optional[str]: ...
+    def save(self, last_id: str) -> None: ...
+
+
+class MemoryLastIdStore:
+    def __init__(self) -> None:
+        self._id: Optional[str] = None
+
+    def load(self) -> Optional[str]:
+        return self._id
+
+    def save(self, last_id: str) -> None:
+        self._id = last_id
+
+
+class FileLastIdStore:
+    """A small JSON file, replaced atomically (temp file + os.replace). Same format as the Node SDK's."""
+
+    def __init__(self, path: Union[str, Path]) -> None:
+        self.path = Path(path)
+
+    def load(self) -> Optional[str]:
+        try:
+            data = json.loads(self.path.read_text("utf8"))
+        except FileNotFoundError:
+            return None
+        last = data.get("lastId") if isinstance(data, dict) else None
+        if not isinstance(last, str) or not last.isdigit():
+            raise ValueError(f"{self.path}: no valid lastId")
+        return last
+
+    def save(self, last_id: str) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self.path.with_name(self.path.name + ".tmp")
+        tmp.write_text(json.dumps({"lastId": last_id}), "utf8")
+        os.replace(tmp, self.path)
+
+
+OnSignal = Callable[[Signal, Source], Union[None, Awaitable[None]]]
+OnEvent = Callable[[dict[str, Any]], None]
+
+
+class SignalStream:
+    """Live signals in id order, with no gaps across disconnects, outages and restarts.
+
+    The server replays the last 24 hours on `?since=<id>`. Before every connection this stream first fetches
+    everything newer than its position over REST, repeating until a pass finds nothing new, so an outage of any length
+    is filled and the socket opens seconds after the last fetch. Anything at or below the position is dropped, so
+    within one running process each signal reaches the handler once; across a crash the last one may be offered again.
+
+    `on_signal(signal, source)` is called in ascending id order, never concurrently; `source` is "rest", "replay" or
+    "live". The position is saved only after the handler returns: if it raises, the connection is dropped and the
+    signal is offered again. Delivery is at-least-once across crashes, so make the handler idempotent on
+    `signal["id"]` (or keep the position in your own database, see LastIdStore).
+
+    `on_event(event)` receives dicts with a `type`: anchored, caught_up, connecting, connected, live, disconnected,
+    error, fatal (the stream has stopped: bad key, or the plan does not include the stream).
+    """
+
+    def __init__(self, client: AsyncLPSignal, on_signal: OnSignal, on_event: Optional[OnEvent] = None,
+                 store: Optional[LastIdStore] = None, since: Optional[str] = None, ping_interval: float = 30.0,
+                 min_backoff: float = 1.0, max_backoff: float = 30.0):
+        if not client.api_key:
+            raise ValueError("SignalStream: the client needs an API key (the stream is for paid plans)")
+        if since is not None and not str(since).isdigit():
+            raise ValueError("SignalStream: since must be a signal id")
+        self._client = client
+        self._on_signal = on_signal
+        self._on_event = on_event
+        self._store = store or MemoryLastIdStore()
+        self._since = since
+        self._ping = ping_interval
+        self._min_backoff = min_backoff
+        self._max_backoff = max_backoff
+        self._last_id: Optional[str] = None
+        self._running = False
+        self._task: Optional[asyncio.Task[None]] = None
+        self._ws: Optional[ClientConnection] = None
+        self._wake = asyncio.Event()
+        self._idle = asyncio.Event()  # set while no handler is running
+        self._idle.set()
+        self._done = asyncio.Event()
+        self._stopping: Optional[asyncio.Task[None]] = None
+        # the first-run starting point, chosen once and kept until it is saved (a retry must not pick a newer one)
+        self._anchor: Optional[str] = None
+
+    @property
+    def position(self) -> Optional[str]:
+        """Id of the last signal handed to on_signal (None before the first connection)."""
+        return self._last_id
+
+    async def start(self) -> None:
+        """Load the saved position and start in the background. Call stop() to end.
+
+        A no-op while running; during a stop() it starts once the stop has finished. After a `fatal` event, call
+        stop() before starting again.
+        """
+        while self._stopping is not None:
+            await asyncio.shield(self._stopping)
+        if self._task is not None:
+            return
+        self._last_id = self._store.load() or self._since
+        self._running = True
+        self._wake.clear()
+        self._done = asyncio.Event()  # each run has its own: run() must not return when an older run ends
+        self._task = asyncio.create_task(self._loop(self._done))
+
+    async def run(self) -> None:
+        """Start and run until stop() or a fatal error. Cancelling run() stops the stream."""
+        await self.start()
+        done = self._done
+        try:
+            await done.wait()
+        except asyncio.CancelledError:
+            await self.stop()
+            raise
+
+    async def stop(self) -> None:
+        """Wait for the signal being handled (if any), then close the connection. The stream can be started again.
+
+        Don't await it from inside on_signal: it would wait for itself.
+        """
+        if self._stopping is None:
+            if self._task is None:
+                return
+            self._stopping = asyncio.create_task(self._shutdown())
+        # every caller waits for the same, complete shutdown; a cancelled caller does not cancel it
+        await asyncio.shield(self._stopping)
+
+    async def _shutdown(self) -> None:
+        try:
+            self._running = False
+            self._wake.set()
+            task = self._task
+            assert task is not None
+            # never interrupt a handler; anywhere else (REST, handshake, waiting for frames) the loop can be cancelled
+            await self._idle.wait()
+            if self._ws is not None:
+                with contextlib.suppress(Exception):
+                    await self._ws.close()
+            task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await task
+        finally:
+            self._task = None
+            self._stopping = None
+
+    def _emit(self, event: dict[str, Any]) -> None:
+        if self._on_event:
+            with contextlib.suppress(Exception):  # a listener must not break the stream
+                self._on_event(event)
+
+    def _fatal(self, error: Exception) -> None:
+        self._running = False
+        self._emit({"type": "fatal", "error": error})
+
+    async def _loop(self, done: asyncio.Event) -> None:
+        try:
+            await self._loop_body()
+        finally:
+            done.set()
+
+    async def _loop_body(self) -> None:
+        backoff = self._min_backoff
+        while self._running:
+            healthy = False
+            try:
+                await self._catch_up()
+                if self._running:
+                    healthy = await self._connect_once()
+            except asyncio.CancelledError:
+                raise
+            except LPSignalError as e:
+                if e.status == 401:
+                    self._fatal(e)
+                else:
+                    self._emit({"type": "error", "error": e})
+            except Exception as e:  # network errors, timeouts: retry
+                self._emit({"type": "error", "error": e})
+            if not self._running:
+                break
+            backoff = self._min_backoff if healthy else min(backoff * 2, self._max_backoff)
+            with contextlib.suppress(asyncio.TimeoutError):
+                await asyncio.wait_for(self._wake.wait(), timeout=backoff)
+
+    async def _catch_up(self) -> None:
+        """Establish a position (first run) or fetch everything after it over REST."""
+        if self._last_id is None:
+            # nothing is consumed until the starting point is saved: a restart must resume from this same point
+            if self._anchor is None:
+                page = await self._client.signals(limit=1)
+                self._anchor = page["signals"][0]["id"] if page["signals"] else "0"
+            self._store.save(self._anchor)
+            self._last_id = self._anchor
+            self._emit({"type": "anchored", "last_id": self._last_id})
+        # repeat until a pass finds nothing: a long backlog can take longer than the server's 24h replay window, and
+        # whatever was created meanwhile must come from REST too, or the socket would skip it
+        delivered = 0
+        while self._running:
+            batch = await self._client.signals_after(self._last_id)
+            if not batch:
+                break
+            for s in batch:
+                if not self._running:
+                    return
+                if await self._deliver(s, "rest"):
+                    delivered += 1
+        if delivered:
+            self._emit({"type": "caught_up", "delivered": delivered})
+
+    async def _connect_once(self) -> bool:
+        """One connection's life. Returns True when it went live."""
+        url = f"{self._client.stream_url}?since={self._last_id}"
+        self._emit({"type": "connecting", "url": url})
+        live = failed = False
+        try:
+            async with connect(url, additional_headers={"authorization": f"Bearer {self._client.api_key}"},
+                               ping_interval=self._ping, ping_timeout=self._ping, open_timeout=15) as ws:
+                self._ws = ws
+                if not self._running:
+                    return False
+                self._emit({"type": "connected"})
+                try:
+                    async for raw in ws:
+                        try:
+                            frame = json.loads(raw)
+                        except ValueError:
+                            continue
+                        if not isinstance(frame, dict):
+                            continue
+                        if frame.get("type") == "signal" and isinstance(frame.get("signal"), dict):
+                            try:
+                                await self._deliver(frame["signal"], "replay" if frame.get("replay") else "live")
+                            except Exception as e:  # keep the position: the signal is offered again
+                                self._emit({"type": "error", "error": e})
+                                failed = True
+                                break
+                        elif frame.get("type") == "ready":
+                            live = True
+                            self._emit({"type": "live"})
+                        # replay_truncated / replay_failed: the server closes with 4409; we resume from the position
+                except ConnectionClosed:
+                    pass
+            code, reason = ws.close_code or 1006, ws.close_reason or ""
+        except InvalidStatus as e:
+            status = e.response.status_code
+            if status == 401:
+                self._fatal(Exception("stream refused (401): the API key is invalid or was replaced"))
+            elif status == 402:
+                self._fatal(Exception("stream refused (402): the plan does not include the stream"))
+            else:
+                self._emit({"type": "error", "error": Exception(
+                    f"stream refused ({status}){': too many connections for this key' if status == 429 else ''}")})
+            return False
+        finally:
+            self._ws = None
+        self._emit({"type": "disconnected", "code": code, "reason": reason})
+        if code == 4402:
+            self._fatal(Exception("stream closed (4402): the plan no longer includes the stream"))
+        return live and not failed
+
+    async def _deliver(self, s: Signal, source: Source) -> bool:
+        """True when the signal was new and handed to on_signal."""
+        if not self._running:  # after stop(), nothing new reaches the handler
+            return False
+        if self._last_id is not None and int(s["id"]) <= int(self._last_id):
+            return False
+        self._idle.clear()
+        try:
+            r = self._on_signal(s, source)
+            if inspect.isawaitable(r):
+                await r
+        finally:
+            self._idle.set()
+        # the in-memory position follows the saved one: a failed save offers the signal again
+        self._store.save(str(s["id"]))
+        self._last_id = str(s["id"])
+        return True

lpsignal/types.py

@@ -0,0 +1,154 @@
+"""Response shapes of the LPSignal API, as returned (camelCase keys, JSON values).
+
+- APRs and ratios are fractions: 0.345 = 34.5%.
+- `ilApr` / `il7d` are the loss versus holding, so they are <= 0, and `netApr = feeApr + ilApr`.
+- `fee` is in hundredths of a basis point: 500 = the 0.05% fee tier.
+- `rangeBp` is the range half-width in basis points of price: 500 = ±5%, 0 = full range.
+- Ids and 256-bit values are strings; timestamps are ISO 8601 strings in UTC.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, Optional, TypedDict, Union
+
+
+class ChainStatus(TypedDict):
+    chain: str
+    block: str
+    blockTs: str
+    firstBlockTs: str
+    lagSec: int
+    activePools: int
+
+
+class BestRange(TypedDict):
+    windowHours: int
+    rangeBp: int
+    tickLower: int
+    tickUpper: int
+    exact: bool
+    feeApr: float
+    ilApr: float
+    netApr: float
+    inRangeRatio: float
+    stakedEmissionApr: float
+    asOf: str
+
+
+class RankedPool(TypedDict):
+    chain: str
+    address: str
+    dex: str
+    pair: str
+    fee: int
+    pairClass: str
+    tvlUsd: float
+    tvlAt: Optional[str]
+    best: BestRange
+
+
+class PoolsPage(TypedDict):
+    pools: list[RankedPool]
+    limit: int
+    offset: int
+
+
+class PoolDetail(TypedDict):
+    pool: dict[str, Any]
+    metrics: list[dict[str, Any]]
+
+
+class PoolHour(TypedDict):
+    hour: str
+    swaps: int
+    volume0: float
+    volume1: float
+    fee0PerL: float
+    fee1PerL: float
+    openTick: int
+    closeTick: int
+    minTick: int
+    maxTick: int
+    closeLiquidity: str
+    feeExact: bool
+
+
+class Backtest(TypedDict):
+    chain: str
+    address: str
+    rangeBp: int
+    days: int
+    asOf: str
+    feeApr: float
+    ilApr: float
+    netApr: float
+    inRangeRatio: float
+    uncertainFeeApr: float
+    startTick: int
+    endTick: int
+    tickLower: int
+    tickUpper: int
+    feesExact: bool
+    exact: bool
+
+
+class SignalOutcome(TypedDict):
+    status: Literal["done", "inexact"]
+    netApr: Optional[float]
+    feeApr: Optional[float]
+    ilApr: Optional[float]
+    evaluatedAt: str
+
+
+# A signal carries the common fields below plus its kind's own fields (see the README):
+#   net_apr:     tvlUsd, net24h, net7d, net30d, fee7d, il7d, inRange7d, stakedEmissionApr?
+#   tvl_outflow: tvlBeforeUsd, tvlNowUsd, drop, windowHours
+#   depeg:       deviation, severe, medianTick, tick
+#   smart_lp:    owner, tokenId, entryUsd, top, rank, wallet30d
+Signal = dict[str, Any]
+
+
+class SignalsPage(TypedDict):
+    signals: list[Signal]
+    next: Optional[str]
+
+
+class Leaderboard(TypedDict):
+    windowDays: int
+    full: bool
+    wallets: list[dict[str, Any]]
+
+
+class WalletPositions(TypedDict):
+    owner: str
+    open: list[dict[str, Any]]
+    closed: list[dict[str, Any]]
+
+
+class Follow(TypedDict):
+    owner: str
+    since: str
+
+
+class Me(TypedDict):
+    id: str
+    tier: Literal["free", "basic", "pro"]
+    paid: bool
+    telegramLinked: bool
+    webhookUrl: Optional[str]
+    walletAddress: Optional[str]
+    hasApiKey: bool
+
+
+class WebhookRegistration(TypedDict):
+    url: str
+    secret: str
+
+
+class TelegramLink(TypedDict):
+    code: str
+    instruction: str
+
+
+BillingStatus = dict[str, Any]
+Json = Union[dict[str, Any], list[Any]]

lpsignal/webhook.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import re
+import time
+from typing import Any, Mapping, Optional, Union
+
+
+class WebhookVerificationError(Exception):
+    """`reason` is one of: missing_headers, bad_timestamp, expired, bad_signature, bad_body."""
+
+    def __init__(self, reason: str):
+        self.reason = reason
+        super().__init__(f"LPSignal webhook rejected: {reason}")
+
+
+def _header(headers: Mapping[str, Any], name: str) -> Optional[str]:
+    for k, v in headers.items():
+        if k.lower() == name:
+            return v[0] if isinstance(v, (list, tuple)) else v
+    return None
+
+
+def verify_webhook(raw_body: Union[bytes, str], headers: Mapping[str, Any], secret: str,
+                   tolerance_sec: int = 300, now: Optional[float] = None) -> dict[str, Any]:
+    """Verify a webhook delivery and return its parsed body.
+
+    `x-lpsignal-signature` is `sha256=` + hex HMAC-SHA256 of `"<x-lpsignal-timestamp>.<raw body>"`, keyed with the
+    secret returned when the webhook was set. Pass the raw request bytes, before any JSON parsing. Deliveries older
+    than `tolerance_sec` are rejected as replays; each retry is signed afresh.
+
+    Deliveries are at-least-once: skip `deliveryId`s you have already handled.
+    """
+    ts = _header(headers, "x-lpsignal-timestamp")
+    sig = _header(headers, "x-lpsignal-signature")
+    if not ts or not sig or not secret:
+        raise WebhookVerificationError("missing_headers")
+    if not re.fullmatch(r"\d{1,12}", ts):
+        raise WebhookVerificationError("bad_timestamp")
+    if abs((time.time() if now is None else now) - int(ts)) > tolerance_sec:
+        raise WebhookVerificationError("expired")
+    body = raw_body.encode("utf8") if isinstance(raw_body, str) else raw_body
+    want = "sha256=" + hmac.new(secret.encode("utf8"), ts.encode("ascii") + b"." + body, hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(sig.encode("utf8"), want.encode("ascii")):
+        raise WebhookVerificationError("bad_signature")
+    try:
+        return json.loads(body)
+    except ValueError:
+        raise WebhookVerificationError("bad_body") from None

lpsignal-0.1.0.dist-info/METADATA

@@ -0,0 +1,126 @@
+Metadata-Version: 2.5
+Name: lpsignal
+Version: 0.1.0
+Summary: Official LPSignal SDK: net-of-IL APR signals for concentrated-liquidity pools, a WebSocket stream that never misses a signal, webhook verification and the REST API.
+Project-URL: Homepage, https://github.com/Ligengxin96/lpsignal-sdk
+License-Expression: MIT
+License-File: LICENSE
+Keywords: apr,concentrated-liquidity,defi,impermanent-loss,liquidity-provider,lpsignal,uniswap
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: websockets>=14
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# lpsignal (Python)
+
+Official Python SDK for [LPSignal](https://lpsignal.app): net-of-IL APR signals for concentrated-liquidity pools.
+Python ≥ 3.10, built on `httpx` and `websockets`.
+
+```bash
+pip install lpsignal
+```
+
+## REST
+
+```python
+from lpsignal import LPSignal, LPSignalError
+
+with LPSignal(api_key="lps_...") as lps:          # key optional for public endpoints
+    page = lps.pools(chain="base", window=168, min_tvl_usd=1e6)
+    top = page["pools"][0]
+    detail = lps.pool("base", top["address"])     # every (window × range) metric
+    bt = lps.backtest("base", top["address"], range_pct=5, days=7)
+    try:
+        lps.wallet_positions("0x...")
+    except LPSignalError as e:
+        if e.code == "pro_required":
+            ...
+```
+
+`AsyncLPSignal` has the same methods as coroutines. Responses are the API's JSON (camelCase keys); `lpsignal.types`
+has `TypedDict`s for the main shapes.
+
+| Method | Endpoint | Key |
+|---|---|---|
+| `health()` · `chains()` | `/v1/health` · `/v1/chains` | – |
+| `pools(chain, pair_class, window, min_tvl_usd, limit, offset)` | `GET /v1/pools` | – |
+| `pool(chain, address)` · `pool_hours(chain, address, hours)` | `GET /v1/pools/:chain/:address[/hours]` | – |
+| `backtest(chain, address, range_pct, days)` | `GET …/backtest` | – |
+| `signals(kind, limit, before)` · `signal(id)` | `GET /v1/signals[/:id]` | optional |
+| `signal_stats(days)` | `GET /v1/signals/stats` — the public track record | – |
+| `iter_signals(kind)` | every page, newest first | optional |
+| `signals_after(id)` | everything newer than `id`, oldest first | optional |
+| `smart_lps(window_days, chain, limit)` | `GET /v1/smart-lps` | optional |
+| `wallet_positions(owner)` | `GET /v1/smart-lps/:owner/positions` | Pro |
+| `follows()` · `follow(owner)` · `unfollow(owner)` | `/v1/me/follows` | Pro |
+| `me()` · `set_webhook(url)` · `delete_webhook()` · `telegram_link()` | `/v1/me…` | yes |
+| `create_api_key(replace)` | `POST /v1/me/api-key` — replaces the key (or `replace=False`: only if none), returned once | yes |
+| `billing(refresh)` · `checkout(tier)` · `billing_portal()` | `/v1/billing…` | yes |
+| `crypto_billing()` · `create_crypto_order(tier, months)` · `crypto_order(id)` · `cancel_crypto_order(id)` | `/v1/billing/crypto…` — prepaid USDT/USDC plans | yes |
+
+Errors are `LPSignalError` with `status`, `code` (the API's `error` field), `body` and `request_id`. A `429` on a
+GET, PUT or DELETE is retried after its `Retry-After` (`max_retries`, default 2).
+
+## Stream
+
+```python
+import asyncio
+from lpsignal import AsyncLPSignal, FileLastIdStore, SignalStream
+
+async def on_signal(signal, source):   # source: "rest" | "replay" | "live"
+    ...                                # once per signal, in id order, never concurrently
+
+async def main():
+    lps = AsyncLPSignal(api_key="lps_...")   # Basic or Pro
+    stream = SignalStream(lps, on_signal, store=FileLastIdStore("lpsignal-state.json"),
+                          on_event=lambda e: print(e) if e["type"] == "fatal" else None)
+    await stream.run()                        # or: await stream.start() … await stream.stop()
+
+asyncio.run(main())
+```
+
+- **First start** with an empty store: begins after the newest signal that exists now (or after `since`).
+- **Every (re)connect**: first fetches everything after the saved id over REST, repeating until a pass finds
+  nothing new, then connects with `?since=<id>`; anything at or below the saved id is dropped. No gap however long
+  you were away, and no duplicates while the process runs.
+- **Your handler decides progress**: the id is saved only after `on_signal` returns. If it raises, the connection
+  is dropped and the signal is offered again. A crash after the handler but before the save also offers it again
+  after the restart: delivery is **at-least-once**, so make the handler idempotent on `signal["id"]`.
+- **No repeats even across crashes**: keep the last id in the same database transaction as your side effects
+  (write it inside `on_signal`), and pass a `store` that reads and writes that same row; its `save()` must only
+  move forward (e.g. `UPDATE … SET last_id = GREATEST(last_id, %s)`), since the stream also saves the starting point.
+- `stop()` waits for the signal being handled; nothing new is handed over after it is called. Cancelling `run()`
+  stops the stream. Don't await `stop()` from inside `on_signal` (it would wait for itself). After a `fatal` event,
+  call `stop()` before `start()` again.
+- **Fatal** (the stream stops): invalid key (401), a plan without the stream (402), or the plan expiring (4402).
+  Everything else reconnects with backoff.
+
+The state file has the same format as the Node SDK's, so you can switch languages without losing your place.
+
+## Webhooks
+
+```python
+from fastapi import FastAPI, Request, Response
+from lpsignal import WebhookVerificationError, verify_webhook
+
+app = FastAPI()
+
+@app.post("/lpsignal")
+async def lpsignal(request: Request):
+    try:
+        event = verify_webhook(await request.body(), request.headers, SECRET)
+    except WebhookVerificationError as e:
+        return Response(e.reason, status_code=400)
+    # deliveries are at-least-once: skip event["deliveryId"] if already handled
+    return Response(status_code=200)
+```
+
+Pass the raw body bytes, never re-serialised JSON. Deliveries older than 5 minutes are rejected (`tolerance_sec`);
+every retry is signed afresh.
+
+## License
+
+MIT

lpsignal-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+lpsignal/__init__.py,sha256=D1kr2MBH6hxHoe-8G_No8AVOuF6ALPVJvBSAOpObsxc,539
+lpsignal/client.py,sha256=7p6Z4jvI8jPT4o_oOXUqvUQ7NXuGAV5cd3ASoizB2qA,17751
+lpsignal/stream.py,sha256=DJaV7wBo1PFKsr5Mc186PNxHR_rZmIrhKFZR-T6PSE0,13397
+lpsignal/types.py,sha256=GOvxRA60HIFdKKFCswM4738SWkvTrXMyWqLcmqtONJE,3205
+lpsignal/webhook.py,sha256=CR7e9e24M9gDNlk8gsgGF0KaB6gV2yyrl1qAx9acFGY,2150
+lpsignal-0.1.0.dist-info/METADATA,sha256=GvkuMDe1p152BHbDZd7X7lmLim3g9doaRx_bcIskqCM,6117
+lpsignal-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+lpsignal-0.1.0.dist-info/licenses/LICENSE,sha256=v5TTMRPLe5FH9vCDpsxD2mFSBIHWPBX9ZVpliPA24BU,1065
+lpsignal-0.1.0.dist-info/RECORD,,

lpsignal-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

lpsignal-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LPSignal
+
+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.