Lightweight, secondary social-sentiment input — never primary trigger.
3. Why This Bot Matters
Strategy uses sentiment as a primary trigger
Social sentiment is noisy, gameable, and easily manipulated by bot networks. Treated as a primary signal it produces churn and drawdowns; treated as a secondary input — 'is the prior consistent with public mood?' — it adds a small but real filter.
No freshness or provenance on sentiment numbers
A sentiment score with no source string and no timestamp cannot be audited or replayed. Every emission must carry both, or downstream consumers have no way to reason about the data they are reading.
Sentiment signal duplicated across teams
Strategy authors otherwise build one-off sentiment fetchers each. Centralising the read gives a single rate-limited source, a single cache, and a single place to swap providers when one degrades.
4. Required Polymarket Inputs
Input
Source
Required?
Use
Social post feed per market slug
ws_sports
Yes
Primary sentiment scoring data source.
Market slug and condition_id mapping
data
Yes
Resolve market slug to condition_id for ObservationReport output.
5. Required Internal Inputs
Input
Source
Required?
Use
KillSwitch active flag
KillSwitch
Yes
Suppress all sentiment emissions when KillSwitch is active.
6. Parameter Guide
Parameter
Default
Warning
Hard
What it controls
min_post_count
10
5
1
Minimum number of posts in the sampling window required to emit a sentiment signal.
poll_interval_s
60
300
600
Seconds between social feed polls per market slug.
7. Detailed Parameter Instructions
min_post_count
What it means
Minimum number of posts in the sampling window required to emit a sentiment signal.
Default
{ "min_post_count": 10 }
Why this default matters
10 posts provides a statistically meaningful sample; fewer posts produce unreliable scores.
Threshold logic
Condition
Action
posts >= 10
Normal — emit ObservationReport
5–9 posts
WARN — low sample; emit with SOCIALSENTIMENT_LOW_SAMPLE warning
< 1 post
Reject — skip emission entirely
Developer check
if (p.min_post_count < p.hard) return;
User-facing English
Sentiment signals require a minimum number of recent posts to be reliable.
poll_interval_s
What it means
Seconds between social feed polls per market slug.
Default
{ "poll_interval_s": 60 }
Why this default matters
60 s provides near-real-time sentiment without overloading the social feed API.
Threshold logic
Condition
Action
interval <= 60 s
Normal
60–300 s
WARN — reduced signal freshness
> 600 s
Reject — PARAMETER_CHANGE_REQUIRES_APPROVAL
Developer check
if (p.poll_interval_s > p.hard) throw ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL');
User-facing English
Social feed is polled regularly to ensure sentiment signals are fresh.
Strategy adjusted position size based on positive sentiment signal
Recent social discussion about this market shows a positive trend. The system used this as one factor in its assessment, alongside price and liquidity data.
No sentiment signal emitted for a market
There was not enough recent discussion about this market to generate a reliable sentiment signal. Signals require a minimum volume of posts.
18. Failure-Mode Block
main_failure_mode
Social feed API outage during high-activity periods causes SocialSentiment to miss sentiment spikes, leaving downstream strategies without fresh signal data.
false_positive_risk
A coordinated posting burst by a small group of accounts inflates the sentiment score for a market without reflecting genuine market opinion.
false_negative_risk
Genuine sentiment shift occurs outside the polling window or below the min_post_count threshold, causing the signal to be suppressed.
safe_fallback
If feed returns an error or zero posts for > 5 min, emit STALE_DATA WARN and suppress further emissions until feed recovers.
required_dependencies
ws_sports social feed, KillSwitch active flag, Data API for slug resolution
19. Failure-Injection Recipes
Scenario
How to inject
Expected behaviour
Recovery
FEED_OUTAGE
Return 503 from ws_sports social feed for 5 min
Automatic on feed recovery; next successful poll emits normally
LOW_SAMPLE_FLOOD
Return 1 post per poll for all slugs for 30 min
Automatic when post volume normalises
KILL_SWITCH_ON
Set killswitch.active=true during active polling
Emissions resume automatically on KillSwitch reset
20. State & Persistence
Cold-start recovery
On cold start, state re-initialised from next poll cycle; no historical backfill required.
21. Concurrency & Idempotency
Aspect
Specification
Execution model
async poll loop per market slug
Max in-flight
20
Idempotency key
market_slug + window_start_ms
Per-call timeout (ms)
8000
Backpressure strategy
drop-after-buffer — skip slugs that have not drained within 2x poll interval
Locking / mutual exclusion
Redis SETNX on slug + window_start_ms to prevent duplicate emissions
ObservationReport emitted with sentiment_score=0.62, post_count=42
Low sample below hard floor skips emission
0 posts in window, min_post_count hard=1
No ObservationReport; low_sample_skips counter incremented
KillSwitch suppresses emission
killswitch.active=true; 50 posts available
No ObservationReport; KILL_SWITCH_ACTIVE logged
Integration Tests
Test
Expected result
Full lifecycle: feed poll → sentiment score → ObservationReport consumed by strategy
Strategy receives ObservationReport with correct sentiment_score and market_slug
Feed outage: STALE_DATA emitted after 5 min of feed errors
STALE_DATA WARN logged; no ObservationReports during outage
Property Tests
Property
Required behaviour
SocialSentiment never submits or signs orders
Always true
No ObservationReport emitted when KillSwitch is active
Always true
27. Operational Runbook
SocialSentiment incidents are most commonly feed outages or low-volume conditions. Neither blocks trading. Monitor for extended stale periods.
On-call actions
Alert
First step
Diagnosis
Mitigation
Escalate to
SocialSentimentFeedStale
Check ws_sports feed health endpoint and last_emitted_at_ms. Verify feed credentials are valid.
Intelligence pod lead if feed is down > 15 min
SocialSentimentHighSkipRate
Check post volume for affected market slugs. If genuinely low, reduce min_post_count via config.
Intelligence pod lead if all slugs affected simultaneously
Manual overrides
force_low_sample_bypass — Set config.min_post_count=1 temporarily in staging to verify emission pipeline — Debugging emission pipeline in staging environment only
Healthcheck
Endpoint: /internal/health/socialsentiment | Green: Last emission < 2x poll_interval_s ago AND Redis reachable AND feed returning 200 | Red: No emission for > 10 min on any active slug OR Redis unreachable
28. Promotion Gates
A bot does not advance to the next readiness state until every gate below is green. Gates are observable from production data — no subjective sign-off.
Promote to Shadow
Gate
How measured
Threshold
Unit tests pass for low-sample gate, KillSwitch suppression, and sample rate