Skip to docs content
Docs

Developer Docs for Real-Time Trading Feeds

TweetStream streams selected X activity and supported Truth Social notifications into trading systems over WebSocket, with REST endpoints for history replay and watchlist operations.

What arrives in the feed

The live feed uses one JSON envelope for tweet content, enrichment metadata, lifecycle events, account events, and handle-management acknowledgements.

ConnectOpen the live WebSocket and route events by family and operation.Read payloadsUnderstand content, meta, lifecycle, account, and control payloads.Replay historyBackfill stored content, profile, and follow events with bearer-authenticated REST.Manage accountsAdd, remove, and inspect the monitored accounts that define the feed.
  • X post, reply, quote, and retweet content for monitored accounts.
  • Truth Social notifications when enabled for supported sources.
  • Token, OCR, price, CEX, and prediction-market enrichment as separate meta events.
  • Deletes, pins, unpins, profile updates, follows, and unfollows when observed.

Base URLs

SurfaceURLUse
WebSocket (USA)wss://ws-iad.tweetstream.io/wsBest for US-based connections
WebSocket (global)wss://ws-global.tweetstream.io/wsBest for connections outside the USA
RESThttps://api.tweetstream.ioBase origin for /api/history, /api/me, and account management
Dashboardhttps://tweetstream.io/dashboardAPI key, watchlists, billing, and Discord routing

Authentication

Use WebSocket subprotocol auth for realtime clients and bearer auth for REST. US-based clients should connect to `wss://ws-iad.tweetstream.io/ws`; clients outside the USA should connect to `wss://ws-global.tweetstream.io/ws`. Keep API keys on a server process; do not ship them in public browser code.

ContextHeader or protocolNotes
WebSockettweetstream.v1 + tweetstream.auth.token.<API_KEY>Recommended realtime auth shape
WebSocket fallbackAuthorization: Bearer <API_KEY> or ?apiKey=<API_KEY>Prefer Authorization when possible; query auth is last-resort for constrained runtimes
RESTAuthorization: Bearer <API_KEY>History requires the standard key; account management accepts the standard or an active Ultra key; /api/me accepts either key
Server-side WebSocket authtypescript
const socket = new WebSocket("wss://ws-global.tweetstream.io/ws", [
  "tweetstream.v1",
  `tweetstream.auth.token.${process.env.TWEETSTREAM_API_KEY}`,
]);
 
socket.addEventListener("message", (event) => {
  const message = JSON.parse(event.data);
  console.log(message.t, message.op, message.d);
});

Recommended path

  • Create an API key in the dashboard after signup.
  • Add monitored accounts before opening the WebSocket.
  • Consume content and meta events first; add lifecycle/account events once your routing is stable.
  • Use /api/history on Pro or Scale to backfill stored content, profile, and follow events after downtime.
  • Use wss://ws-iad.tweetstream.io/ws for US-based connections and wss://ws-global.tweetstream.io/ws outside the USA.