Skip to docs content
Docs

Developer Docs for Real-Time Trading Feeds

TweetStream sends selected X activity to trading systems over WebSocket. REST endpoints handle history replay and watchlist changes. Ultra Speed adds supported Donald Trump and White House Truth Social posts.

What arrives in the feed

Every live event uses the same JSON envelope, whether it contains tweet content, enrichment metadata, a lifecycle or account event, or a handle-management acknowledgement.

ConnectOpen the WebSocket, then route each event by t and op.Read payloadsSee how content, meta, lifecycle, account, and control payloads are structured.Replay historyUse bearer-authenticated REST to backfill stored content, profile, and follow events.Manage accountsAdd, remove, and inspect the monitored accounts that define the feed.
  • X post, reply, quote, and retweet content for monitored accounts.
  • Supported Donald Trump and White House Truth Social notifications with Ultra Speed. If Truth Social was already enabled on an active plan, you keep access.
  • 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/wsUse for connections in the USA
WebSocket (global)wss://ws-global.tweetstream.io/wsUse 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

Authenticate realtime clients with WebSocket subprotocols and REST requests with a bearer token. Connect US-based clients to wss://ws-iad.tweetstream.io/ws and clients outside the USA to wss://ws-global.tweetstream.io/ws. Keep API keys on the server. Never include them in public browser code.

ContextHeader or protocolNotes
WebSockettweetstream.v1 + tweetstream.auth.token.<API_KEY>Preferred realtime authentication
WebSocket fallbackAuthorization: Bearer <API_KEY> or ?apiKey=<API_KEY>Prefer Authorization; use query authentication only when the runtime cannot set headers
RESTAuthorization: Bearer <API_KEY>History accepts a standard key for Pro or Scale. With active or trialing Ultra, AFFILIATE accepts the standard or Ultra key that owns the account. Account management and /api/me accept 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);
});

Start here

  • Create an API key in the dashboard after signup.
  • Add monitored accounts before opening the WebSocket.
  • Handle content and meta events first. Add lifecycle and 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.