X stream and social alerts

QuantDesk runs a dedicated Social Stream Ingestion Matrix for X/Twitter ingestion. It is separate from both the Market Data Ingestion Pipeline and the Sentiment Feed Aggregator.

Status

Shipped: dedicated Social Stream Ingestion Matrix, backend /api/v2/x/* routes, alert fanout, terminal windows, and an agent context tool
Dev sample mode: when TWITTER_BEARER_TOKEN is unset in non-production, env-gated sample posts (not live KOL firehose)
Not supported: direct client-side X API access or frontend-held bearer tokens

Service boundaries

Layer	Responsibility
Social Stream Ingestion Matrix	Poll or stream watched accounts, normalize posts, derive alert events
Gateway API	Persist recent posts/alerts, expose `/api/v2/x/*`, fan out websocket events
Lite / Pro / agent tools	Read the normalized feed and alert cache only

Normalized post shape

Each ingested post is normalized to:

{
  "post_id": "tweet-id",
  "author": "@account",
  "text": "Post body",
  "ts": "2026-06-25T12:00:00.000Z",
  "urls": [],
  "entity_tags": ["SOL", "JUP"],
  "linked_symbols": ["SOL-PERP", "JUP-PERP"],
  "lists": ["solana_ecosystem"],
  "url": "https://x.com/..."
}

The service publishes raw normalized events to x.posts.raw and stores recent history in the x_posts table.

Alert types

QuantDesk currently emits separate alert events to x.alerts.raw and stores them in the x_alerts table.

Alert type	Trigger	Typical use
`account_post`	A tracked account posts	Breaking headline awareness
`keyword`	Watch keywords match	Macro, policy, or protocol watchlists
`symbol_mention`	A mapped market symbol is mentioned	Jump from social context to chart / market

Each alert includes severity, linked_symbols, lists, and the original post_url.

Public read paths

Surface	Route / event
Feed snapshot	`GET /api/v2/x/feed`
Alerts snapshot	`GET /api/v2/x/alerts`
Agent context	`GET /api/v2/x/context` and the backend context tool
Correlated UI timeline	Client-side merge of `GET /api/v2/news` and `GET /api/v2/x/feed`
Compatibility timeline	`GET /api/v2/x/timeline` (legacy compatibility only)
Push updates	Socket.IO `x_post` and `x_alert` via dedicated X feed / alert subscriptions
Service health	`GET /health` on the X stream service origin

API usage and ToS posture

QuantDesk treats X as a licensed upstream with rate and ToS limits.
Frontend clients and agent tools do not call X directly.
TWITTER_BEARER_TOKEN is owned by the Social Stream Ingestion Matrix only.
Development mode may serve env-gated sample posts when no bearer token is configured.

​X stream and social alerts

​Status

​Service boundaries

​Normalized post shape

​Alert types

​Public read paths

​API usage and ToS posture

​Related