Metadata-Version: 2.4
Name: social-stock-sentiment
Version: 1.19.0
Summary: Python SDK for the Finance Sentiment API — stock sentiment (Reddit, X/Twitter, Polymarket) and crypto sentiment (Reddit)
Project-URL: Homepage, https://adanos.org
Project-URL: Documentation, https://api.adanos.org
Author: Alexander Schneider
License-Expression: MIT
License-File: LICENSE
Keywords: api,finance,polymarket,reddit,sentiment,stock,twitter
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: attrs>=22.2
Requires-Dist: httpx<1,>=0.23
Requires-Dist: python-dateutil>=2.8
Description-Content-Type: text/markdown

# social-stock-sentiment

Python SDK for the [Finance Sentiment API](https://api.adanos.org) — analyze stock sentiment (News, Reddit, X/Twitter, Polymarket) and crypto sentiment (Reddit).

## Installation

```bash
pip install social-stock-sentiment
```

## Quick Start

```python
from stocksentiment import StockSentimentClient

client = StockSentimentClient(api_key="sk_live_...")

# Get trending stocks on Reddit
trending = client.reddit.trending(days=7, limit=10)
for stock in trending:
    print(f"{stock.ticker}: buzz={stock.buzz_score}, sentiment={stock.sentiment_score}")

# Get detailed sentiment for a stock
tsla = client.reddit.stock("TSLA", days=14)
print(f"TSLA buzz: {tsla.buzz_score}, trend: {tsla.trend}")

# AI-generated trend explanation
explanation = client.reddit.explain("TSLA")
print(explanation.explanation)

# Search for stocks
results = client.reddit.search("Tesla")

# Compare multiple stocks
comparison = client.reddit.compare(["TSLA", "AAPL", "MSFT"], days=7)

# News endpoints support an optional source filter
news_trending = client.news.trending(days=7, source="reuters")
```

## News Data

```python
news_trending = client.news.trending(days=7, source="reuters")
nvda = client.news.stock("NVDA", days=7, source="reuters")
news_compare = client.news.compare(["NVDA", "AAPL"], days=7, source="reuters")
```

## X/Twitter Data

```python
# Same interface, different data source
x_trending = client.x.trending(days=1, limit=20)
nvda = client.x.stock("NVDA")
```

## Polymarket Data

```python
# Prediction-market sentiment and activity
pm_trending = client.polymarket.trending(days=7, limit=20, type="stock")
aapl = client.polymarket.stock("AAPL")
```

## Async Usage

Every method has an `_async` variant:

```python
import asyncio
from stocksentiment import StockSentimentClient

async def main():
    async with StockSentimentClient(api_key="sk_live_...") as client:
        trending = await client.reddit.trending_async(days=7)
        tsla = await client.reddit.stock_async("TSLA")

asyncio.run(main())
```

## Available Methods

### `client.reddit.*`

| Method | Description |
|--------|-------------|
| `trending(days, limit, offset, type)` | Trending stocks by buzz score |
| `trending_sectors(days, limit, offset)` | Trending sectors |
| `trending_countries(days, limit, offset)` | Trending countries |
| `stock(ticker, days)` | Detailed sentiment for a ticker |
| `explain(ticker)` | AI-generated trend explanation |
| `search(query)` | Search stocks by name/ticker |
| `compare(tickers, days)` | Compare up to 10 stocks |

### `client.news.*`

| Method | Description |
|--------|-------------|
| `trending(days, limit, offset, type, source)` | Trending stocks from news |
| `trending_sectors(days, limit, offset, source)` | Trending sectors from news |
| `trending_countries(days, limit, offset, source)` | Trending countries from news |
| `stock(ticker, days, source)` | Detailed news sentiment for a ticker |
| `explain(ticker, source)` | AI-generated explanation from news context |
| `search(query, source)` | Search stocks in the news dataset |
| `compare(tickers, days, source)` | Compare up to 10 stocks in news |
| `stats(source)` | News dataset statistics |
| `health()` | Public news service health |

### `client.x.*`

| Method | Description |
|--------|-------------|
| `trending(days, limit, offset, type)` | Trending stocks on X/Twitter |
| `trending_sectors(days, limit, offset)` | Trending sectors |
| `trending_countries(days, limit, offset)` | Trending countries |
| `stock(ticker, days)` | Detailed X/Twitter sentiment |
| `search(query)` | Search stocks |
| `compare(tickers, days)` | Compare stocks |

### `client.polymarket.*`

| Method | Description |
|--------|-------------|
| `trending(days, limit, offset, type)` | Trending stocks on Polymarket |
| `trending_sectors(days, limit, offset)` | Trending sectors |
| `trending_countries(days, limit, offset)` | Trending countries |
| `stock(ticker, days)` | Detailed Polymarket sentiment |
| `search(query)` | Search stocks |
| `compare(tickers, days)` | Compare stocks |

## Authentication

Get your API key at [api.adanos.org](https://api.adanos.org). Free tier includes 250 requests/month.

```python
# Custom base URL (e.g. for self-hosted instances)
client = StockSentimentClient(
    api_key="sk_live_...",
    base_url="https://your-instance.com",
    timeout=60.0,
)
```

## Rate Limits

| Tier | Monthly Requests | Burst Limit |
|------|-----------------|-------------|
| Free | 250 | 100/min |
| Paid | Unlimited | 1000/min |

Rate limit headers are included in every response.

## License

MIT
