social-stock-sentiment 1.16.0
Python SDK for the Stock Sentiment API — Reddit, X/Twitter, and Polymarket sentiment analysis for stocks
Requires Python: >=3.10
Keywords: api, finance, polymarket, reddit, sentiment, stock, twitter

# social-stock-sentiment

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

## 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)
```

## 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.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