Payloads, Token Detection & OCR

Complete reference for TweetStream alert data structures and enrichment features

Tweet Lifecycle

When a monitored account tweets, TweetStream sends a base content message first, optional update messages, and a meta message when enrichment is ready:

content - The tweet text, author, and media (arrives first)
update - Optional ref context or URL expansion updates
meta - Enrichment data: OCR results, detected tokens, markets (arrives shortly after)

Tweet Content Type

type TweetContent = {
  tweetId: string;
  text: string;
  createdAt: number;
  author: {
    id?: string;
    handle?: string;
    name?: string;
    profileImage?: string;
  };
  link?: string;
  media?: Array<{
    url: string;
    type?: 'image' | 'video' | 'gif';
    thumbnail?: string;
  }>;
  ref?: {
    type: 'reply' | 'quote' | 'retweet';
    tweetId?: string;
    text?: string;
    author?: TweetAuthor;
    media?: Media[];
  };
};

Tweet Meta Type

The meta payload contains all enrichment data:

type TweetMeta = {
  tweetId: string;
  ocr?: {
    text: string;  // Extracted text from images
  };
  detected?: {
    tokens?: Array<{
      symbol?: string;
      name?: string;
      contract?: string;
      chain?: string;
      networkId?: number;
      priceUsd?: number;
      sources: Array<'text' | 'ocr'>;
    }>;
    cex?: Array<{
      exchange: 'bybit' | 'binance' | 'hyperliquid';
      symbol?: string;
      priceUsd?: number;
      url?: string;
      baseAsset?: string;
      quoteAsset?: string;
      sources: Array<'text' | 'ocr'>;
    }>;
    prediction?: Array<{
      exchange: 'polymarket' | 'kalshi';
      marketId?: string;
      title?: string;
      priceUsd?: number;
      url?: string;
      sources: Array<'text' | 'ocr'>;
    }>;
  };
};

Token Detection

TweetStream automatically detects tokens from multiple sources:

Source	Examples
$TICKER symbols	$BTC, $ETH, $SOL
Contract addresses	0x... (EVM), pump... (Solana)
DEX URLs	dexscreener.com, birdeye.so
OCR text	Tickers and addresses in images

OCR Text Extraction

Text is automatically extracted from images attached to tweets. This includes:

Screenshots of charts and trading terminals
Images containing token information
Announcements and promotional graphics

OCR results are included in the meta.ocr.text field and are also scanned for token detection.

Prediction Markets

References to Polymarket and Kalshi markets are detected and enriched with live odds. The detected.prediction array includes:

Market ID and title
Current price (probability)
Direct link to the market

Example: Content Envelope

{
  "v": 1,
  "t": "tweet",
  "op": "content",
  "ts": 1702500000000,
  "d": {
    "tweetId": "1234567890",
    "text": "Just bought some $SOL, looking bullish!",
    "createdAt": 1702500000000,
    "author": {
      "handle": "cryptotrader",
      "name": "Crypto Trader"
    },
    "link": "https://twitter.com/cryptotrader/status/1234567890"
  }
}

Example: Meta Envelope

{
  "v": 1,
  "t": "tweet",
  "op": "meta",
  "ts": 1702500001000,
  "d": {
    "tweetId": "1234567890",
    "ocr": {
      "text": "Chart showing SOL breakout at $100"
    },
    "detected": {
      "tokens": [
        {
          "symbol": "SOL",
          "name": "Solana",
          "priceUsd": 98.50,
          "sources": ["text", "ocr"]
        }
      ]
    }
  }
}

Start real-time Twitter WebSocket alerts today

WebSocket delivery, OCR, and token detection—no infrastructure to build.

Start 1-Day Trial

From $199/mo · 1-day trial included · OCR + token detection included

WebSocket Quickstart WebSocket for Trading Bots Discord Crypto Alerts