A useful stock sentiment alert does more than announce that a score changed. It identifies the equity, compares the signal with a stable baseline, adds attention and source context, links to evidence, and suppresses repetitive noise. This guide uses Nebula's public API to build that workflow without treating social activity as a trading instruction.
Alert design
Resolve the equity once, query sentiment, mindshare, and social momentum on matching windows, evaluate an explicit rule on your server, and send an evidence-rich notification with a cooldown.
1. Resolve the stock identity
Search for the stock and constrain the result to equities. Persist the returned asset_idand asset_class; do not construct identifiers from a ticker or display name. Resolution prevents similarly named or cross-listed instruments from entering the wrong alert.
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'Cache canonical identities and refresh them when your application receives an identity-related error or when your own reference-data policy requires it. Keep the user-facing symbol separate from the API identity stored by the monitoring job.
2. Request aligned signals
Request sentiment, mindshare, and social momentum for the same stock and lookback. The examples use seven days with daily granularity for a stable baseline. A shorter operational alert can use a shorter window, but comparisons must remain aligned.
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' \
--data-urlencode 'granularity=1d' \
--header 'X-API-Key: YOUR_API_KEY'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' \
--data-urlencode 'granularity=1d' \
--header 'X-API-Key: YOUR_API_KEY'curl --get \
--url 'https://nebula-api.hiddensystems.ai/api/v1/public/social-momentum' \
--data-urlencode 'asset_id=RETURNED_ASSET_ID' \
--data-urlencode 'asset_class=equity' \
--data-urlencode 'hours=168' \
--data-urlencode 'granularity=1d' \
--header 'X-API-Key: YOUR_API_KEY'Social momentum returns post activity, unique posters, sentiment counts, and average sentiment over time. Mindshare supplies relative attention. Sentiment supplies the primary tone series. Store the response timestamp, requested window, granularity, and any sample context with every evaluation.
3. Define an alert rule
Build rules from changes rather than universal absolute values. An ordinary activity level for NVIDIA may be exceptional for another equity. A robust rule can require several conditions: activity above a stock-specific baseline, enough unique posters, a material sentiment change, and a mindshare increase.
| Condition | Purpose |
|---|---|
| Minimum recent post activity | Avoid extreme percentages from tiny samples |
| Minimum unique posters | Reduce dependence on one loud source |
| Change versus historical baseline | Adapt the rule to each stock |
| Sentiment or emotion shift | Describe how the reaction changed |
| Mindshare confirmation | Show whether relative attention expanded |
| Cooldown and deduplication | Prevent repeated alerts for one event |
Keep thresholds in versioned server configuration so changes are reviewable. Record both triggered and non-triggered evaluations for later calibration. Do not build a rule around one memorable price event.
4. Add catalyst and evidence context
A metric-only notification forces the recipient to repeat discovery work. Add the likely catalyst, leading narrative, first credible timestamp, and relevant evidence when available. Use Nebula insights or your own filings and news workflow, but label unverified claims clearly.
A useful message might say: “NVIDIA social activity moved materially above its seven-day baseline, unique participation increased, sentiment deteriorated, and mindshare rose. Discussion centres on a newly published regulatory report. Data current at 14:00 UTC.” Link to the original record and the internal chart or API snapshot.
5. Deliver alerts safely
- Keep API keys in server-side secrets and never expose them in browser code or client logs.
- Schedule requests within plan entitlements and handle rate limits explicitly.
- Retry transient errors with bounded backoff; do not retry invalid requests indefinitely.
- Mark stale data and suppress a “live” alert when required calls failed.
- Group multiple conditions from one event into one notification.
- Include the subject, window, timestamp, evidence, and rule version.
- Route material conclusions to a human reviewer.
6. Evaluate the alert system
Define success according to the workflow. For event discovery, measure how many alerts correspond to verified new catalysts and how early they arrive relative to the existing process. For coverage triage, measure whether analysts find important changes with less monitoring time. A price move is not the only valid outcome and may not be the right one.
Review false positives from duplicated posts, scheduled events, thin activity, ticker ambiguity, and stale claims. Also review false negatives using a catalogue of known events. Recalibrate per-equity or cohort baselines only when enough history supports the change.
Next steps
Start with one stock and one daily digest before moving to real-time messaging. Confirm that identities, windows, timestamps, and evidence render correctly. Then expand to a watchlist and introduce severity levels. Read how to use social momentum in stock research for the analytical framework and the stock sentiment API guide for the foundational request pattern.
Where financial attention becomes signal
Explore live market intelligence in Nebula or use the same structured signals in your own workflow.