Payloads, Token Detection & OCR

Complete reference for TweetStream alert data structures and enrichment features

Tweet Lifecycle

When a monitored account tweets, TweetStream sends two messages:

content - The tweet text, author, and media (arrives first)
meta - Enrichment data: OCR results, detected tokens, markets (arrives shortly after)

Additional operations include update (tweet edits) and delete (tweet deletions).

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"]
        }
      ]
    }
  }
}

Ready to get started?

Try TweetStream free for 1 day. No commitment required.

Start 1-Day Trial

WebSocket Quickstart WebSocket for Trading Bots Discord Crypto Alerts