2.8.0

adanos

adanos is the public Python SDK for the Adanos Market Sentiment API.

This SDK targets API 1.54.0.

It gives you typed access to:

• Reddit stock sentiment
• News sentiment and source-filtered rankings
• X/Twitter stock sentiment
• Polymarket stock activity and market attention
• Reddit crypto sentiment
• Direct finance text sentiment analysis

Links:

• Source: https://github.com/adanos-software/adanos-python-sdk
• PyPI: https://pypi.org/project/adanos/
• API docs: https://api.adanos.com/docs
• Homepage: https://adanos.com

Package and import:

• PyPI package: adanos
• Python import: adanos

Install

python3 -m pip install adanos

Quick Start

from adanos import AdanosClient

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

trending = client.reddit.trending(limit=10)
tsla = client.reddit.stock("TSLA")
explanation = client.reddit.explain("TSLA")
direct = client.sentiment.analyze("TSLA looks like a short squeeze setup")

print(trending[0].ticker)
print(tsla.buzz_score)
print(explanation.explanation)
print(direct["sentiment_label"])

What You Can Do

• Rank trending stocks across Reddit, News, X, and Polymarket
• Pull service-level market sentiment snapshots across every public namespace
• Pull detailed ticker reports for a fixed lookback window
• Search and compare tickers across datasets
• Generate AI-written explanations for Reddit and News stock trends
• Track Reddit crypto tokens via the same client
• Use sync or async methods without changing the namespace structure

Namespaces

• client.reddit.* for Reddit Stocks
• client.news.* for News Stocks
• client.x.* for X/Twitter Stocks
• client.polymarket.* for Polymarket Stocks
• client.crypto.* for Reddit Crypto
• client.reddit_crypto.* is an alias for client.crypto.*
• client.sentiment.* for direct finance text sentiment
• client.health() for root API health aggregated across services

Examples

Reddit Stocks

from adanos import AdanosClient

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

root_health = client.health()
trending = client.reddit.trending(limit=10)
sectors = client.reddit.trending_sectors(limit=10)
countries = client.reddit.trending_countries(limit=10)
tsla = client.reddit.stock("TSLA")
explanation = client.reddit.explain("TSLA")
results = client.reddit.search("Tesla", limit=10)
comparison = client.reddit.compare(["TSLA", "AAPL", "MSFT"])
market = client.reddit.market_sentiment()

News

from adanos import AdanosClient

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

news_trending = client.news.trending(source="reuters")
sectors = client.news.trending_sectors(source="reuters")
countries = client.news.trending_countries(source="reuters")
nvda = client.news.stock("NVDA")
explanation = client.news.explain("NVDA")
results = client.news.search("Nvidia", limit=10)
comparison = client.news.compare(["NVDA", "AAPL"])
market = client.news.market_sentiment()
stats = client.news.stats()
health = client.news.health()

News ticker arguments identify one company. Exchange suffixes such as ABX.DE are supported. The API rejects share classes and malformed tickers.

X/Twitter

from adanos import AdanosClient

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

x_trending = client.x.trending(limit=20)
sectors = client.x.trending_sectors(limit=10)
countries = client.x.trending_countries(limit=10)
nvda = client.x.stock("NVDA")
explanation = client.x.explain("NVDA")
results = client.x.search("Nvidia", limit=10)
comparison = client.x.compare(["NVDA", "AMD"])
market = client.x.market_sentiment()
stats = client.x.stats()
health = client.x.health()

Polymarket

from adanos import AdanosClient

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

pm_trending = client.polymarket.trending(limit=20, type="stock")
sectors = client.polymarket.trending_sectors(limit=10)
countries = client.polymarket.trending_countries(limit=10)
aapl = client.polymarket.stock("AAPL")
results = client.polymarket.search("Apple", limit=10)
comparison = client.polymarket.compare(["AAPL", "TSLA"])
market = client.polymarket.market_sentiment()
stats = client.polymarket.stats()
health = client.polymarket.health()

Polymarket history starts on 2025-10-11. Earlier requested windows return an availability error.

Polymarket semantics:

• buzz_score is activity-first and optimized for current market attention
• total_liquidity is a windowed signal over the selected period
• current_market_count is the live-only active-market breadth; market_count remains the selected-window breadth
• unique_traders can be None when retained wallet-level trades do not fully cover the requested window
• pulse on stock() provides a compact current interpretation; use its evidence and warnings as data-quality context
• top_mentions on stock() are representative sentiment evidence, with directional markets prioritized

Across platforms, each trend_history value represents its own UTC calendar day. The final value for a live window describes the current partial UTC day and is not expected to equal the top-level period buzz_score.

Reddit Crypto

from adanos import AdanosClient

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

trending = client.crypto.trending(limit=20)
btc = client.crypto.token("BTC")
mentions = client.crypto.mentions("BTC", from_="2026-05-01", to="2026-05-07", limit=10, offset=10)
results = client.crypto.search("bitcoin", limit=10)
comparison = client.crypto.compare(["BTC", "ETH"])
market = client.crypto.market_sentiment()
stats = client.crypto.stats()
health = client.crypto.health()

Reddit crypto total_upvotes and mention upvotes are signed Reddit scores and can be negative. Raw mention created_utc UTC timestamps parse into timezone-aware datetime values.

Available Methods

client.*

client.reddit.*

Period options: use from_ and to as YYYY-MM-DD inclusive UTC dates for reproducible windows. The SDK serializes from_ as query parameter from. days remains available as a legacy v1-compatible shorthand. The API returns 422 if from, to, and days are all sent together. Responses keep period_days; retain requested dates client-side if you need them later. Search endpoints are the exception: they accept only limit and use the API-managed recent summary window.

client.news.*

client.x.*

client.polymarket.*

client.crypto.*

client.sentiment.*

target is keyword-only and accepts up to 100 characters. Omitting it or passing None sends text-only analysis. The API validates the target.

result = client.sentiment.analyze("Tesla gained while Ford fell", target="Tesla")

Sentiment responses are JSON dictionaries. components.model_score can be absent or None. Legacy component fields remain in responses but are deprecated.

Async Usage

Every namespace method also has an _async variant.

import asyncio

from adanos import AdanosClient


async def main() -> None:
    async with AdanosClient(api_key="sk_live_...") as client:
        trending = await client.reddit.trending_async(limit=10)
        tsla = await client.reddit.stock_async("TSLA")
        explanation = await client.news.explain_async("NVDA")
        print(trending[0].ticker)
        print(tsla.trend)
        print(explanation.explanation)


asyncio.run(main())

Authentication and Configuration

Get an API key at https://api.adanos.com/docs

from adanos import AdanosClient

client = AdanosClient(
    api_key="sk_live_...",
    base_url="https://api.adanos.com",
    timeout=60.0,
)

Notes:

• api_key is required for protected endpoints
• base_url defaults to https://api.adanos.com. Explicit https://api.adanos.org and custom deployments remain supported
• timeout is passed through to the underlying httpx client
• the SDK does not auto-load local CLI profiles or env-specific config files

Context management:

from adanos import AdanosClient

with AdanosClient(api_key="sk_live_...") as client:
    print(client.reddit.health())

Errors and Responses

• Most SDK methods return typed models from the generated OpenAPI client
• market_sentiment() methods return the live JSON payload directly so the new endpoint family is available before the next full generated refresh
• Documented API errors are returned as typed error models
• Undocumented statuses raise UnexpectedStatus
• For long-lived processes, use with, async with, close(), or aclose() to release HTTP resources

Rate Limits

Typical platform limits:

See the live API docs for the current contract and plan details.

Migration from social-stock-sentiment

Version 1.0.0 starts the new adanos package line and renames both the PyPI package and the Python import path.

Old:

python3 -m pip install social-stock-sentiment

from stocksentiment import StockSentimentClient

New:

python3 -m pip install adanos

from adanos import AdanosClient

The client API and namespace layout stay the same. Most upgrades only need a dependency rename and an import rewrite.

AdanosClient is now the primary public client name. StockSentimentClient remains available as a compatibility alias.

If you adopted the pre-release adanos-python-sdk naming locally, switch that install/import pair too:

python3 -m pip uninstall adanos-python-sdk
python3 -m pip install adanos

from adanos import AdanosClient

Development

python3 -m pip install -e ".[dev]"
python3 -m pytest tests -q
python3 -m build

License

MIT