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
