crowdwisdomtrading 0.2.0__tar.gz

crowdwisdomtrading-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,122 @@
+# 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/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-0.2.0/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-0.2.0/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())