How to Use a Stock Sentiment API

A stock sentiment API turns public market conversation into structured data that an application, model, alert, or agent can query repeatedly. The reliable workflow is simple: resolve the equity first, request sentiment over an explicit window, add mindshare for attention context, and keep enough metadata to explain every comparison.

1. Resolve the equity

Tickers can collide across exchanges and names can change, so asset resolution belongs at the start of the workflow. Search with the stock symbol or name and constrain the result to the equity class. Persist the canonical asset_id and asset_classreturned by the API.

curl --get \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/assets' \
  --data-urlencode 'query=NVDA' \
  --data-urlencode 'asset_class=equity' \
  --header 'X-API-Key: YOUR_API_KEY'

Treat the response as the source of truth. A user-facing label can remain “NVIDIA,” but downstream requests should use the resolved identity rather than a guessed slug.

2. Request stock sentiment

Use the resolved identity with an explicit lookback. A 24-hour window answers a different question from a seven-day or 90-day window. Store the requested hours, response timestamps, and granularity beside the values so historical comparisons remain reproducible.

curl --get \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/sentiment' \
  --data-urlencode 'asset_id=RETURNED_ASSET_ID' \
  --data-urlencode 'asset_class=equity' \
  --data-urlencode 'hours=168' \
  --header 'X-API-Key: YOUR_API_KEY'

Sentiment measures tone in the tracked conversation. It does not by itself show how large the conversation is, who produced it, or whether price agrees. Use it as one research input rather than a standalone trading instruction.

3. Add mindshare

Mindshare measures the stock's share of tracked market attention. Reading it beside sentiment distinguishes quiet improvement from a narrative that is spreading rapidly.

curl --get \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/mindshare' \
  --data-urlencode 'asset_id=RETURNED_ASSET_ID' \
  --data-urlencode 'asset_class=equity' \
  --data-urlencode 'hours=168' \
  --header 'X-API-Key: YOUR_API_KEY'

4. Make the workflow production-safe

• Keep API keys on a server and out of browser bundles, logs, and analytics events.
• Cache resolved identities and refresh them when the API reports they are stale.
• Align windows, timestamps, and granularity before comparing assets or periods.
• Record sample size and treat thin conversation as lower-confidence evidence.
• Handle authentication, entitlement, rate-limit, and transient server errors explicitly.
• Validate request and response fields against the generated OpenAPI contract.

Useful applications

A stock sentiment API can power watchlist context, earnings-event monitoring, narrative alerts, cross-sectional stock screens, research notebooks, model features, and agent tools. The application should always expose the subject, time window, freshness, and evidence behind a signal. A number without provenance is difficult to trust and impossible to debug.

For AI-sector equities, keep the asset class as equity and curate the comparison universe separately. The AI stock sentiment guideexplains how to distinguish public stocks from private AI subjects such as OpenAI.

Validate before acting

Compare social sentiment with price, fundamentals, filings, event timing, and the underlying posts. Investigate divergence instead of assuming the API predicts returns. Sentiment can reveal expectations, attention, and emotional regime; it cannot establish fair value or remove market risk.