crowdwisdomtrading 0.2.0__py3-none-any.whl

crowdwisdomtrading/__init__.py

@@ -0,0 +1,5 @@
+"""crowdwisdomtrading: client for CrowdWisdom Trading crowd data (free weekly crowd score, x402 pay-per-call or Bearer key)."""
+from crowdwisdomtrading.client import Client, CrowdWisdomError, PaymentFailed
+
+__version__ = "0.2.0"
+__all__ = ["Client", "CrowdWisdomError", "PaymentFailed", "__version__"]

crowdwisdomtrading/aihf.py

@@ -0,0 +1,138 @@
+"""CrowdConsensusModel: an ai-hedge-fund AlphaModel that buys CrowdWisdom crowd consensus per call.
+
+Register it in hedge_fund/signals/__init__.py:
+    from crowdwisdomtrading.aihf import CrowdConsensusModel
+    ALPHA_MODEL_REGISTRY["crowd"] = CrowdConsensusModel
+and add it to a strategy YAML (models: - name: crowd). It pays with the wallet in
+X402_WALLET_PRIVATE_KEY (the same one ai-hedge-fund uses for Financial Datasets) or uses a
+CWT_API_KEY Bearer key. predict() only ever asks for data dated on or before `date`
+(point-in-time), and disk caching means one payment per (ticker, date) in a backtest.
+
+Works without ai-hedge-fund installed (a small shim replaces Signal / QuantModel) so the
+package can be tested standalone; with aihf installed the real classes are used.
+"""
+from __future__ import annotations
+
+from datetime import date, datetime
+from typing import Any, ClassVar
+
+from crowdwisdomtrading.client import Client
+
+try:  # real ai-hedge-fund classes
+    from hedge_fund.models import Signal  # type: ignore
+    from hedge_fund.signals.base import QuantModel  # type: ignore
+
+    HAVE_AIHF = True
+except Exception:  # pragma: no cover - shim path is tested explicitly below
+    HAVE_AIHF = False
+    from dataclasses import dataclass, field
+
+    @dataclass
+    class Signal:  # type: ignore[no-redef]
+        model_name: str
+        ticker: str
+        date: str
+        value: float
+        reasoning: str | None = None
+        components: dict[str, float] = field(default_factory=dict)
+        metadata: dict[str, Any] = field(default_factory=dict)
+        horizon_days: int | None = None
+
+    class QuantModel:  # type: ignore[no-redef]
+        investment_approach: ClassVar[str] = "long_short"
+        horizon_days: ClassVar[int] = 5
+
+
+def _as_day(value: date | str) -> str:
+    if isinstance(value, datetime):
+        return value.date().isoformat()
+    if isinstance(value, date):
+        return value.isoformat()
+    return str(value)[:10]
+
+
+class CrowdConsensusModel(QuantModel):
+    """Crowd consensus (-1..+1) from YouTube, X and Reddit mentions, as of the backtest date."""
+
+    investment_approach = "long_short"
+    horizon_days = 5
+
+    def __init__(
+        self,
+        client: Client | None = None,
+        *,
+        cycle: str | None = None,
+        max_staleness_days: int = 10,
+        neutral_band: float = 0.0,
+    ) -> None:
+        self._client = client
+        self._cycle = cycle
+        self._max_staleness_days = max_staleness_days
+        self._neutral_band = neutral_band
+
+    @property
+    def name(self) -> str:
+        return "crowd"
+
+    @property
+    def client(self) -> Client:
+        if self._client is None:
+            self._client = Client()
+        return self._client
+
+    def predict(self, ticker: str, date: date | str, data_client: Any = None) -> Signal:  # noqa: A002
+        """Signal for `ticker` using only crowd sessions dated on or before `date`. data_client is unused."""
+        day = _as_day(date)
+        try:
+            answer = self.client.consensus(ticker, as_of=day, cycle=self._cycle)
+        except Exception as exc:
+            return self._abstain(ticker, day, f"crowd data unavailable: {type(exc).__name__}")
+        data = answer.get("data") or {}
+        session = data.get("session") or {}
+        value = data.get("value")
+        if value is None or not session.get("date"):
+            return self._abstain(ticker, day, "no crowd session on or before this date")
+        try:
+            age = (datetime.strptime(day, "%Y-%m-%d").date() - datetime.strptime(str(session["date"]), "%Y-%m-%d").date()).days
+        except ValueError:
+            return self._abstain(ticker, day, "malformed crowd session date")
+        if age > self._max_staleness_days:
+            return self._abstain(ticker, day, f"latest crowd session {session['date']} is {age} days old")
+        if abs(float(value)) < self._neutral_band:
+            value = 0.0
+        sources = data.get("sources") or {}
+        components = {k: float(v) / 100.0 for k, v in sources.items() if v is not None}
+        mentions = data.get("mentions") or {}
+        receipt = (answer.get("meta") or {}).get("payment") or {}
+        return Signal(
+            model_name=self.name,
+            ticker=ticker,
+            date=day,
+            value=max(-1.0, min(1.0, float(value))),
+            reasoning=(
+                f"Crowd {data.get('direction') or 'view'} {float(data.get('score') or 0):+.0f} on {session['date']} "
+                f"({session.get('cycle')}) from {mentions.get('total', '?')} mentions"
+            ),
+            components=components,
+            metadata={
+                "as_of": session["date"],
+                "cycle": session.get("cycle"),
+                "confidence": data.get("confidence"),
+                "mentions": mentions,
+                "latest_setup": data.get("latest_setup"),
+                "payment_tx": receipt.get("transaction"),
+                "cached": (answer.get("meta") or {}).get("cached"),
+            },
+            horizon_days=self.horizon_days,
+        )
+
+    def _abstain(self, ticker: str, day: str, reason: str) -> Signal:
+        return Signal(
+            model_name=self.name,
+            ticker=ticker,
+            date=day,
+            value=0.0,
+            reasoning=reason,
+            metadata={"abstained": True},
+            horizon_days=self.horizon_days,
+        )

crowdwisdomtrading/cli.py

@@ -0,0 +1,71 @@
+"""crowdwisdomtrading command line: quick checks and demos.
+
+  crowdwisdomtrading catalog
+  crowdwisdomtrading sample
+  crowdwisdomtrading daily NVDA                   (free: daily crowd score)
+  crowdwisdomtrading weekly NVDA                  (free: weekly crowd score)
+  crowdwisdomtrading consensus NVDA [--as-of 2026-11-04] [--cycle daily]
+  crowdwisdomtrading latest NVDA
+  crowdwisdomtrading crowdmap NVDA
+  crowdwisdomtrading history NVDA --from 2026-10-01 --to 2026-10-31
+Pays with X402_WALLET_PRIVATE_KEY or uses CWT_API_KEY; --base overrides the API host.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from crowdwisdomtrading.client import Client, CrowdWisdomError
+from crowdwisdomtrading.payment import PaymentFailed
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="crowdwisdomtrading", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("command", choices=["catalog", "sample", "daily", "weekly", "consensus", "latest", "today", "crowdmap", "history"])
+    parser.add_argument("ticker", nargs="?")
+    parser.add_argument("--as-of", dest="as_of")
+    parser.add_argument("--cycle")
+    parser.add_argument("--from", dest="date_from")
+    parser.add_argument("--to", dest="date_to")
+    parser.add_argument("--base")
+    parser.add_argument("--no-cache", action="store_true")
+    args = parser.parse_args(argv)
+
+    client = Client(args.base, cache=not args.no_cache)
+    try:
+        if args.command == "catalog":
+            out = client.catalog()
+        elif args.command == "sample":
+            out = client.sample()
+        elif args.command == "today":
+            out = client.setups_today(args.cycle)
+        else:
+            if not args.ticker:
+                parser.error("ticker required")
+            if args.command == "daily":
+                out = client.daily_sentiment(args.ticker)
+            elif args.command == "weekly":
+                out = client.weekly_sentiment(args.ticker)
+            elif args.command == "consensus":
+                out = client.consensus(args.ticker, as_of=args.as_of, cycle=args.cycle)
+            elif args.command == "latest":
+                out = client.setup_latest(args.ticker, cycle=args.cycle)
+            elif args.command == "crowdmap":
+                out = client.crowdmap(args.ticker)
+            else:
+                if not (args.date_from and args.date_to):
+                    parser.error("--from and --to required")
+                out = client.history(args.ticker, args.date_from, args.date_to, cycle=args.cycle)
+    except PaymentFailed as exc:
+        print(f"payment failed: {exc}", file=sys.stderr)
+        return 2
+    except CrowdWisdomError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    print(json.dumps(out, indent=2, default=str))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

crowdwisdomtrading/client.py

@@ -0,0 +1,262 @@
+"""CrowdWisdom Trading client.
+
+Free, no wallet, no key:
+  daily_sentiment(ticker)  - daily crowd score for one ticker (all sources, newest session)
+  weekly_sentiment(ticker) - weekly crowd score for one ticker (all sources, newest Monday session)
+                             50 free calls a day per IP address for each.
+
+Two ways to the full data:
+  wallet mode  - Client(wallet_key=...) or env X402_WALLET_PRIVATE_KEY: pays per call on the /x402 routes
+                 (USDC on Base, same wallet ai-hedge-fund uses for Financial Datasets).
+  key mode     - Client(api_key=...) or env CWT_API_KEY: a Bearer key for the /v1 routes (monthly plan).
+                 A key wins over a wallet, so a subscriber is never billed per call.
+
+Every method returns {"data": ..., "as_of": ..., "meta": {...}}. Point-in-time: pass as_of / date_to and
+the server only returns what was published by then. Answers with an as_of are cached forever on disk,
+live answers for 10 minutes, so a backtest never pays twice for the same (ticker, date). Errors are
+never cached.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+import requests
+
+from crowdwisdomtrading.payment import BASE_MAINNET, PaymentFailed, decode_receipt, payment_session
+
+DEFAULT_BASE_URL = "https://api.crowdwisdomtrading.com"
+# 2026-11-08: every request names the package, so the API can count package users apart from other callers
+# (stored in cwt_api.api_request_log.client_agent). No personal data, only the package and version.
+LANDING_URL = "https://crowdwisdomtrading.com/x402"
+
+
+def user_agent() -> str:
+    from crowdwisdomtrading import __version__
+
+    return f"crowdwisdomtrading-python/{__version__} (+{LANDING_URL})"
+DEFAULT_CACHE_DIR = Path.home() / ".crowdwisdomtrading" / "cache"
+LIVE_TTL_S = 600
+
+
+class CrowdWisdomError(Exception):
+    """HTTP or data error from the CrowdWisdom API (status and body excerpt in the message)."""
+
+    def __init__(self, status: int, message: str) -> None:
+        self.status = status
+        super().__init__(f"HTTP {status}: {message}")
+
+
+def _day(value: date | str | None) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, date):
+        return value.isoformat()
+    return str(value)[:10]
+
+
+def _is_past_day(day: str | None) -> bool:
+    """Only a finished day is immutable; today's sessions can still be published later today."""
+    from datetime import datetime, timezone
+
+    return bool(day) and day < datetime.now(timezone.utc).date().isoformat()
+
+
+class Client:
+    def __init__(
+        self,
+        base_url: str | None = None,
+        *,
+        api_key: str | None = None,
+        wallet_key: str | None = None,
+        network: str | None = None,
+        cache_dir: str | Path | None = None,
+        timeout: float = 30.0,
+        session: requests.Session | None = None,
+        cache: bool = True,
+    ) -> None:
+        self.base_url = (base_url or os.getenv("CWT_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.api_key = (api_key if api_key is not None else os.getenv("CWT_API_KEY") or "").strip()
+        wallet = wallet_key if wallet_key is not None else os.getenv("X402_WALLET_PRIVATE_KEY") or ""
+        self._wallet_key = wallet.strip()
+        self.network = (network or os.getenv("X402_NETWORK") or BASE_MAINNET).strip()
+        self.timeout = timeout
+        self.cache_enabled = cache
+        self.cache_dir = Path(cache_dir) if cache_dir else Path(os.getenv("CWT_CACHE_DIR") or DEFAULT_CACHE_DIR)
+        self._session = session
+        self.last_receipt: dict[str, Any] | None = None
+
+    # ------------------------------------------------------------------ mode
+
+    @property
+    def mode(self) -> str:
+        if self.api_key:
+            return "key"
+        if self._wallet_key:
+            return "wallet"
+        return "free"
+
+    def pays_per_call(self) -> bool:
+        return self.mode == "wallet"
+
+    def _http(self) -> requests.Session:
+        if self._session is None:
+            if self.mode == "wallet":
+                self._session = payment_session(
+                    self._wallet_key, self.network, timeout=max(self.timeout, 60.0), base_url=self.base_url
+                )
+            else:
+                self._session = requests.Session()
+        return self._session
+
+    # ----------------------------------------------------------------- cache
+
+    def _cache_path(self, key: str) -> Path:
+        return self.cache_dir / f"{key}.json"
+
+    def _cache_get(self, key: str, ttl: float | None) -> dict[str, Any] | None:
+        if not self.cache_enabled:
+            return None
+        path = self._cache_path(key)
+        if not path.is_file():
+            return None
+        try:
+            entry = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return None
+        if ttl is not None and time.time() - float(entry.get("fetched_at", 0)) > ttl:
+            return None
+        return entry.get("body")
+
+    def _cache_put(self, key: str, body: dict[str, Any]) -> None:
+        if not self.cache_enabled:
+            return
+        try:
+            self.cache_dir.mkdir(parents=True, exist_ok=True)
+            self._cache_path(key).write_text(json.dumps({"fetched_at": time.time(), "body": body}), encoding="utf-8")
+        except OSError:
+            pass
+
+    # ------------------------------------------------------------------- http
+
+    def _get(self, path: str, params: dict[str, Any] | None = None, *, point_in_time: bool = False) -> dict[str, Any]:
+        params = {k: v for k, v in (params or {}).items() if v is not None}
+        key = hashlib.sha256(f"{self.mode}|{self.base_url}|{path}|{json.dumps(params, sort_keys=True)}".encode()).hexdigest()[:24]
+        cached = self._cache_get(key, None if point_in_time else LIVE_TTL_S)
+        if cached is not None:
+            cached.setdefault("meta", {})["cached"] = True
+            return cached
+        headers = {"Accept": "application/json", "User-Agent": user_agent()}
+        if self.mode == "key":
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        try:
+            response = self._http().get(f"{self.base_url}{path}", params=params, headers=headers, timeout=self.timeout)
+        except PaymentFailed:
+            raise
+        except requests.RequestException as exc:
+            raise CrowdWisdomError(0, f"{type(exc).__name__}: {exc}") from None
+        if response.status_code == 402:
+            raise PaymentFailed("payment required: set X402_WALLET_PRIVATE_KEY (with USDC on Base) or CWT_API_KEY")
+        if response.status_code >= 400:
+            raise CrowdWisdomError(response.status_code, response.text[:300])
+        body = response.json()
+        if not isinstance(body, dict):
+            raise CrowdWisdomError(response.status_code, "unexpected body")
+        self.last_receipt = decode_receipt(response)
+        body.setdefault("meta", {})
+        body["meta"]["payment"] = self.last_receipt
+        body["meta"]["cached"] = False
+        self._cache_put(key, body)
+        return body
+
+    # ---------------------------------------------------------------- free
+
+    def catalog(self) -> dict[str, Any]:
+        return self._get("/x402/catalog")
+
+    def sample(self) -> dict[str, Any]:
+        return self._get("/x402/sample")
+
+    def daily_sentiment(self, ticker: str) -> dict[str, Any]:
+        """Free daily all-source crowd sentiment score for one ticker (-100..+100, newest session). Never pays, needs
+        no key or wallet. Capped per IP per day."""
+        t = ticker.upper().strip()
+        return self._get(f"/x402/daily/{t}")
+
+    def weekly_sentiment(self, ticker: str) -> dict[str, Any]:
+        """Free weekly all-source crowd sentiment score for one ticker (-100..+100, newest Monday). Never pays, needs
+        no key or wallet. Capped per IP per day."""
+        t = ticker.upper().strip()
+        return self._get(f"/x402/weekly/{t}")
+
+    # ---------------------------------------------------------------- data
+
+    def consensus(self, ticker: str, as_of: date | str | None = None, cycle: str | None = None) -> dict[str, Any]:
+        """Crowd score in [-1, +1] for one ticker, latest session on or before as_of."""
+        t = ticker.upper().strip()
+        day = _day(as_of)
+        if self.mode == "key":
+            body = self._get(f"/v1/sentiment/{t}", point_in_time=False)
+            path = [p for p in body.get("path") or [] if day is None or p.get("date", "") <= day]
+            if cycle:
+                path = [p for p in path if p.get("cycle") == cycle]
+            latest = path[-1] if path else None
+            score = float(latest["score"]) if latest and latest.get("score") is not None else None
+            data = {
+                "ticker": t,
+                "as_of": day,
+                "cycle": cycle,
+                "session": {"date": latest["date"], "cycle": latest.get("cycle")} if latest else None,
+                "value": max(-1.0, min(1.0, score / 100.0)) if score is not None else None,
+                "ProCrowdSentimentScore": score,
+                "direction": latest.get("direction") if latest else None,
+                "confidence": None,
+                "mentions": None,
+                "sources": None,
+                "latest_setup": None,
+            }
+            return {"data": data, "as_of": day or (latest["date"] if latest else None), "meta": {**body.get("meta", {}), "route": "/v1/sentiment (key mode)"}}
+        return self._get(f"/x402/consensus/{t}", {"as_of": day, "cycle": cycle}, point_in_time=_is_past_day(day))
+
+    def setup_latest(self, ticker: str, cycle: str | None = None) -> dict[str, Any]:
+        t = ticker.upper().strip()
+        if self.mode == "key":
+            body = self._get("/v1/signals", {"ticker": t, "cycle": cycle, "limit": 100})
+            rows = sorted(body.get("data") or [], key=lambda r: (r.get("date") or "", r.get("published_at") or ""))
+            row = rows[-1] if rows else None
+            return {"data": row, "as_of": row.get("date") if row else None, "meta": {**body.get("meta", {}), "route": "/v1/signals (key mode)"}}
+        return self._get(f"/x402/setups/latest/{t}", {"cycle": cycle})
+
+    def setups_today(self, cycle: str | None = None) -> dict[str, Any]:
+        if self.mode == "key":
+            body = self._get("/v1/signals", {"cycle": cycle, "limit": 500})
+            rows = body.get("data") or []
+            latest = max((r.get("date") or "" for r in rows), default=None)
+            rows = [r for r in rows if r.get("date") == latest]
+            return {"data": {"date": latest, "cycle": cycle, "count": len(rows), "setups": rows}, "as_of": latest, "meta": {**body.get("meta", {}), "route": "/v1/signals (key mode)"}}
+        return self._get("/x402/setups/today", {"cycle": cycle})
+
+    def crowdmap(self, ticker: str) -> dict[str, Any]:
+        """CrowdMap: the crowd's support / resistance levels for one ticker (newest day)."""
+        t = ticker.upper().strip()
+        if self.mode == "key":
+            body = self._get(f"/v1/socialmap/{t}", {"days": 1})
+            sessions = body.get("sessions") or []
+            latest = sessions[-1] if sessions else None
+            return {"data": latest, "as_of": latest.get("ladder_date") if latest else None, "meta": {**body.get("meta", {}), "route": "/v1/socialmap (key mode)"}}
+        return self._get(f"/x402/crowdmap/{t}")
+
+    def history(self, ticker: str, date_from: date | str, date_to: date | str, cycle: str | None = None) -> dict[str, Any]:
+        """Setups between the two dates. Wallet mode is point-in-time (nothing published after date_to)."""
+        t = ticker.upper().strip()
+        start, end = _day(date_from), _day(date_to)
+        if self.mode == "key":
+            body = self._get("/v1/signals", {"ticker": t, "date_from": start, "date_to": end, "cycle": cycle, "limit": 500})
+            rows = body.get("data") or []
+            return {"data": {"ticker": t, "from": start, "to": end, "count": len(rows), "setups": rows, "point_in_time": False}, "as_of": end, "meta": {**body.get("meta", {}), "route": "/v1/signals (key mode)"}}
+        return self._get(f"/x402/setups/history/{t}", {"from": start, "to": end, "cycle": cycle}, point_in_time=_is_past_day(end))

crowdwisdomtrading/payment.py

@@ -0,0 +1,91 @@
+"""x402 payment session: a requests.Session that pays any 402 it meets, like ai-hedge-fund's wallet.py.
+
+The private key never leaves this process and is never logged; errors are re-raised as PaymentFailed
+with the key stripped from the message.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+import requests
+
+BASE_MAINNET = "eip155:8453"
+BASE_SEPOLIA = "eip155:84532"
+
+
+class PaymentFailed(requests.RequestException):
+    """The x402 payment could not be made (no funds, facilitator down, wrong network)."""
+
+
+def _scrub(text: str, secret: str) -> str:
+    if not secret:
+        return text
+    out = text.replace(secret, "<redacted>")
+    bare = secret[2:] if secret.lower().startswith("0x") else secret
+    return out.replace(bare, "<redacted>") if bare else out
+
+
+def payment_session(
+    wallet_key: str, network: str = BASE_MAINNET, *, timeout: float = 60.0, base_url: str | None = None
+) -> requests.Session:
+    """requests.Session that pays x402 402s. The paying adapter is mounted only on `base_url` (when given) and
+    redirects are off, so a 3xx to a third-party 402 can never be paid by accident. Needs crowdwisdomtrading[x402]."""
+    try:
+        from eth_account import Account
+        from x402 import x402ClientSync
+        from x402.http.clients.requests import PaymentError, x402HTTPAdapter
+        from x402.mechanisms.evm import EthAccountSigner
+        from x402.mechanisms.evm.exact import ExactEvmScheme
+    except ImportError as exc:  # pragma: no cover - exercised only without the extra
+        raise ImportError("x402 payments need: pip install 'crowdwisdomtrading[x402]'") from exc
+
+    client = x402ClientSync()
+    client.register(network, ExactEvmScheme(EthAccountSigner(Account.from_key(wallet_key))))
+
+    class _Adapter(x402HTTPAdapter):
+        def send(self, request: Any, **kwargs: Any) -> Any:  # type: ignore[override]
+            try:
+                return super().send(request, **kwargs)
+            except PaymentError as exc:
+                raise PaymentFailed(_scrub(str(exc), wallet_key)) from None
+            except Exception as exc:
+                raise PaymentFailed(f"{type(exc).__name__}: {_scrub(str(exc), wallet_key)}") from None
+
+    session = requests.Session()
+    adapter = _Adapter(client)
+    if base_url:
+        session.mount(base_url.rstrip("/"), adapter)
+    else:
+        session.mount("https://", adapter)
+        session.mount("http://", adapter)
+    session.request = _with_defaults(session.request, timeout)  # type: ignore[method-assign]
+    return session
+
+
+def _with_defaults(request_fn: Any, timeout: float) -> Any:
+    def wrapped(method: str, url: str, **kwargs: Any) -> Any:
+        kwargs.setdefault("timeout", timeout)
+        kwargs.setdefault("allow_redirects", False)
+        return request_fn(method, url, **kwargs)
+
+    return wrapped
+
+
+def decode_receipt(response: requests.Response) -> dict[str, Any] | None:
+    """The PAYMENT-RESPONSE receipt (tx hash, payer, network) or None when the call was not paid."""
+    header = response.headers.get("PAYMENT-RESPONSE")
+    if not header:
+        return None
+    try:
+        from x402.http import decode_payment_response_header
+
+        settled = decode_payment_response_header(header)
+    except Exception:
+        return None
+    return {
+        "success": settled.success,
+        "transaction": settled.transaction,
+        "network": settled.network,
+        "payer": settled.payer,
+        "amount": settled.amount,
+    }

crowdwisdomtrading-0.2.0.dist-info/METADATA

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: crowdwisdomtrading
+Version: 0.2.0
+Summary: Client for CrowdWisdom Trading crowd data: free weekly crowd score, pay per call with x402 or use a Bearer key; includes an ai-hedge-fund alpha model.
+Author: CrowdWisdom Trading
+License: MIT
+Project-URL: Homepage, https://crowdwisdomtrading.com/x402?utm_source=pypi&utm_medium=package&utm_campaign=crowdwisdomtrading
+Project-URL: Catalog, https://api.crowdwisdomtrading.com/x402/catalog
+Project-URL: Docs, https://api.crowdwisdomtrading.com/docs
+Keywords: x402,trading,crowd,sentiment,ai-hedge-fund,alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31
+Provides-Extra: x402
+Requires-Dist: x402[evm,requests]>=2.26; extra == "x402"
+Requires-Dist: eth-account>=0.13; extra == "x402"
+Provides-Extra: aihf
+Requires-Dist: aihf>=2.7; extra == "aihf"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+
+# crowdwisdomtrading
+
+Python client for [CrowdWisdom Trading](https://crowdwisdomtrading.com/x402?utm_source=pypi&utm_medium=readme&utm_campaign=crowdwisdomtrading) crowd data on US stocks:
+free daily and weekly crowd scores, the per-source crowd consensus, the newest crowd setup (direction, entry,
+targets, stops), today's setups, CrowdMap (crowd support / resistance levels) and point-in-time setup history.
+
+Start free with no account. Pay per call with [x402](https://x402.org) (USDC on Base, no account) or use a
+Bearer key from a plan. Includes a ready-made alpha model for [virattt/ai-hedge-fund](https://github.com/virattt/ai-hedge-fund).
+
+## Install
+
+```bash
+pip install crowdwisdomtrading            # free daily + weekly scores, Bearer-key mode
+pip install "crowdwisdomtrading[x402]"    # pay per call with a wallet
+pip install "crowdwisdomtrading[aihf]"    # + ai-hedge-fund model
+```
+
+## Try it free
+
+```python
+from crowdwisdomtrading import Client
+
+Client().daily_sentiment("NVDA")       # today's crowd score
+Client().weekly_sentiment("NVDA")      # this week's
+# {"data": {"cycle": "weekly", "week_of": "2026-11-02", "score": 42.0, "value": 0.42, "direction": "BULLISH",
+#           "confidence": 70, "mentions": 380, "sources_included": ["youtube", "x", "reddit"]}, ...}
+```
+
+No key, no wallet. One crowd score from YouTube, X, StockTwits, Reddit, brokers, podcasts and newsletters: of the people
+who took a side, long versus short (-100 to +100). Direction, confidence and the score per source are paid.
+50 free calls a day per IP address for each (daily and weekly counted separately), any tickers.
+
+## What it costs
+
+| Call | Price | What you get |
+|---|---|---|
+| `daily_sentiment(ticker)` | free | Today's `ProCrowdSentimentScore` (-100 to +100) and `ProTraders` (distinct traders behind it; `low_coverage` under 10) |
+| `weekly_sentiment(ticker)` | free | The same for the week (newest Monday) |
+| `consensus(ticker)` | $0.10 | The score per source (YouTube, X, Reddit, brokers, podcasts, newsletters), mention breakdown, point-in-time history (`as_of`) |
+| `setup_latest(ticker)` | $0.50 | Newest setup: direction, entry, 2 targets, 2 stops, confidence, risk/reward |
+| `setups_today()` | $10.00 | Every setup of the newest day |
+| `crowdmap(ticker)` | $0.30 | CrowdMap, the crowd's support / resistance levels, newest day: every level, role, trader count, impact, horizons |
+| `history(ticker, from, to)` | $0.10 | Up to 200 past setups, as published at the time (backtest-safe) |
+| `catalog()`, `sample()` | free | Price list; one setup at least 7 days old |
+
+Live prices: `https://api.crowdwisdomtrading.com/x402/catalog`.
+
+## Paying
+
+| Mode | Set | What it uses |
+|---|---|---|
+| wallet (pay per call) | `X402_WALLET_PRIVATE_KEY=0x...` with USDC on Base | `/x402/*` routes, receipt (tx hash) on every answer |
+| key (plan) | `CWT_API_KEY=cwt_live_...` | `/v1/*` routes you already pay for monthly |
+
+A key wins over a wallet. Fund the wallet with small amounts; the `exact` scheme pays only the quoted
+price and nothing else.
+
+## Use
+
+```python
+from crowdwisdomtrading import Client
+
+c = Client()                                   # reads the env vars above
+c.daily_sentiment("NVDA")                      # free
+c.weekly_sentiment("NVDA")                     # free
+c.catalog()                                    # free: prices, schemas, examples
+c.sample()                                     # free: one setup at least 7 days old
+c.consensus("NVDA")                            # {"data": {"value": 0.42, "direction": "BULLISH", ...}, "as_of": ...}
+c.consensus("NVDA", as_of="2026-11-04")        # point-in-time: latest session on or before that day
+c.setup_latest("NVDA")                         # direction, last_close, targets, stops, confidence, rr
+c.setups_today()
+c.crowdmap("NVDA")                             # CrowdMap: crowd support / resistance levels
+c.history("NVDA", "2026-10-01", "2026-10-31")  # only rows published by `to` (backtest-safe)
+c.last_receipt                                 # {"transaction": "0x...", "payer": ..., "network": ...} in wallet mode
+```
+
+Every answer is `{"data": ..., "as_of": ..., "meta": {...}}`. Answers with `as_of` / `to` are cached on disk
+(`~/.crowdwisdomtrading/cache`), live answers for 10 minutes, so a backtest pays once per (ticker, date). Errors
+are never cached. `Client(cache=False)` disables it.
+
+## ai-hedge-fund
+
+```python
+# hedge_fund/signals/__init__.py
+from crowdwisdomtrading.aihf import CrowdConsensusModel
+ALPHA_MODEL_REGISTRY["crowd"] = CrowdConsensusModel
+```
+
+```yaml
+# hedge_fund/strategies/crowd-tilt.yaml
+name: crowd-tilt
+display_name: Crowd Tilt
+models:
+  - name: crowd
+    weight: 1.0
+  - name: pead
+blend:
+  mode: long_short
+  method: conviction_weighted
+  gross_target: 1.0
+```
+
+`CrowdConsensusModel.predict(ticker, date, data_client)` returns a `Signal` with `value` in [-1, +1]
+(crowd score / 100), `components` per source, and abstains (`value 0`, `metadata.abstained`) when the
+latest crowd session is older than 10 days. It only asks for sessions dated on or before `date`.
+
+## Command line
+
+```bash
+crowdwisdomtrading daily NVDA                   # free
+crowdwisdomtrading weekly NVDA                  # free
+crowdwisdomtrading catalog
+crowdwisdomtrading consensus NVDA --as-of 2026-11-04
+crowdwisdomtrading history NVDA --from 2026-10-01 --to 2026-10-31
+```
+
+## Notes
+
+- Data is aggregated crowd opinion for research. Not investment advice. Payments are final; a failed
+  response is not charged.
+- Networks: Base mainnet `eip155:8453` (default). `X402_NETWORK=eip155:84532` for Base Sepolia testing.
+- Docs, prices and the paid plans: https://crowdwisdomtrading.com/x402?utm_source=pypi&utm_medium=readme&utm_campaign=crowdwisdomtrading

crowdwisdomtrading-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+crowdwisdomtrading/__init__.py,sha256=2B1IvdHuB_gfSuESVdELn5JLPLL-aYvbtJuzFig-kyc,307
+crowdwisdomtrading/aihf.py,sha256=Y_bFAi8t3yNpKXq0z3eoorQF3ScuUqqQI_bwpfwaLo8,5529
+crowdwisdomtrading/cli.py,sha256=bNWoXheQxABMPfmnAYuUmHGkxgyzr9lEwi6Qi46FxAU,3015
+crowdwisdomtrading/client.py,sha256=6s2Ru6ReTFY-Wqh8qGczoW4SSbLmzvkZSX-gD6JqnjU,12625
+crowdwisdomtrading/payment.py,sha256=oS3_lo72bVtR70PJkUGb14-aAuj5FS4YXrHdcGbvS9A,3573
+crowdwisdomtrading-0.2.0.dist-info/METADATA,sha256=iITQiUwJUF8LbUAxk5xsxn--PMARs_6J-ApGskHaCg8,7061
+crowdwisdomtrading-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+crowdwisdomtrading-0.2.0.dist-info/entry_points.txt,sha256=2EJMCv_wOu6xXiJI4ECzUGQ_hKYteWfq3qjMUyJRU3E,67
+crowdwisdomtrading-0.2.0.dist-info/top_level.txt,sha256=cMpCt4V8ek9OWd4hZeLvqFq9m5hhoNiL1Cw3d7uvChU,19
+crowdwisdomtrading-0.2.0.dist-info/RECORD,,

crowdwisdomtrading-0.2.0.dist-info/WHEEL

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

crowdwisdomtrading-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+crowdwisdomtrading = crowdwisdomtrading.cli:main

crowdwisdomtrading-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+crowdwisdomtrading