social-stock-sentiment 1.18.0

Python SDK for the Finance Sentiment API — stock sentiment (Reddit, X/Twitter, Polymarket) and crypto sentiment (Reddit)

social-stock-sentiment

Python SDK for the Finance Sentiment API — analyze stock sentiment (Reddit, X/Twitter, Polymarket) and crypto sentiment (Reddit).

Installation

pip install social-stock-sentiment

Quick Start

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

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

Polymarket Data

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

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. Free tier includes 250 requests/month.

# 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