Docs
TweetStream developer docs
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
| Surface | URL | Use |
|---|---|---|
| WebSocket | wss://ws.tweetstream.io/ws | Standard live event stream |
| Ultra WebSocket | wss://ws-iad.tweetstream.io/ws | Paid Ultra Speed live event stream |
| REST | https://api.tweetstream.io | Base origin for /api/history, /api/me, and account management |
| Dashboard | https://tweetstream.io/dashboard | API key, watchlists, billing, and Discord routing |
Authentication
Use WebSocket subprotocol auth for realtime clients and bearer auth for REST. Standard clients connect to `wss://ws.tweetstream.io/ws`; paid Ultra Speed clients connect to `wss://ws-iad.tweetstream.io/ws` with the dedicated Ultra API key. Keep API keys on a server process; do not ship them in public browser code.
| Context | Header or protocol | Notes |
|---|---|---|
| WebSocket | tweetstream.v1 + tweetstream.auth.token.<API_KEY> | Recommended realtime auth shape |
| WebSocket fallback | Authorization: Bearer <API_KEY> or ?apiKey=<API_KEY> | Prefer Authorization when possible; query auth is last-resort for constrained runtimes |
| REST | Authorization: Bearer <API_KEY> | The standard key is required for history and account management; /api/me accepts the standard or Ultra key |
Server-side WebSocket authtypescript
const socket = new WebSocket("wss://ws.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 the standard WebSocket URL unless you are on paid Ultra Speed; Ultra clients use wss://ws-iad.tweetstream.io/ws.