social-stock-sentiment 1.19.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 (News, 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)

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

News Data

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

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