WebSocket Guide

wss://api.xshot.fun/ws?api_key=YOUR_KEY

{
  "type": "connected",
  "timestamp": "2026-03-28T13:39:50.995Z"
}

{
  "type": "subscribe",
  "channel": "tweet:engagement",
  "params": { "tweet_id": "2035548674483273831" },
  "interval": 15
}

{
  "type": "subscribed",
  "channel": "tweet:engagement",
  "params": { "tweet_id": "2035548674483273831" },
  "interval": 15
}

{
  "type": "event",
  "channel": "tweet:engagement",
  "params": { "tweet_id": "2035548674483273831" },
  "data": {
    "view_count": 41836,
    "view_count_delta": 2
  },
  "timestamp": "2026-03-28T13:40:14.239Z"
}

{
  "type": "unsubscribe",
  "channel": "tweet:engagement",
  "params": { "tweet_id": "2035548674483273831" }
}

{
  "type": "unsubscribed",
  "channel": "tweet:engagement",
  "params": { "tweet_id": "2035548674483273831" }
}

{
  "type": "event",
  "channel": "user:tweets",
  "params": { "username": "elonmusk" },
  "data": {
    "new_tweets": [
      {
        "id": "2037850934274138146",
        "text": "Starship launch window opens tomorrow",
        "created_at": "Fri Mar 28 14:30:00 +0000 2026",
        "author": {
          "id": "44196397",
          "name": "Elon Musk",
          "username": "elonmusk",
          "profile_image": "https://pbs.twimg.com/profile_images/.../normal.jpg",
          "verified": false,
          "followers_count": 237614000
        },
        "like_count": 45000,
        "retweet_count": 8200,
        "reply_count": 3100,
        "view_count": 12000000
      }
    ]
  },
  "timestamp": "2026-03-28T14:30:30.000Z"
}

{
  "type": "event",
  "channel": "user:mentions",
  "params": { "username": "elonmusk" },
  "data": {
    "new_mentions": [
      {
        "id": "2037851000000000000",
        "text": "@elonmusk when is the next Starship launch?",
        "created_at": "Fri Mar 28 14:35:00 +0000 2026",
        "author": {
          "id": "999999999",
          "name": "Space Fan",
          "username": "spacefan42",
          "profile_image": "https://pbs.twimg.com/profile_images/.../normal.jpg",
          "verified": false,
          "followers_count": 1500
        },
        "like_count": 5,
        "retweet_count": 0,
        "reply_count": 1,
        "view_count": 200
      }
    ]
  },
  "timestamp": "2026-03-28T14:35:30.000Z"
}

{
  "type": "event",
  "channel": "user:followers",
  "params": { "username": "elonmusk" },
  "data": {
    "followers_count": 237614746,
    "previous_count": 237614000,
    "change": 746
  },
  "timestamp": "2026-03-28T14:31:00.000Z"
}

{
  "type": "event",
  "channel": "tweet:engagement",
  "params": { "tweet_id": "2035548674483273831" },
  "data": {
    "like_count": 328,
    "like_count_delta": 2,
    "view_count": 41836,
    "view_count_delta": 985,
    "retweet_count": 70,
    "retweet_count_delta": 2
  },
  "timestamp": "2026-03-28T13:40:14.239Z"
}

{
  "type": "event",
  "channel": "search:tweets",
  "params": { "query": "bitcoin" },
  "data": {
    "new_tweets": [
      {
        "id": "2037852000000000000",
        "text": "Bitcoin breaking through resistance levels today",
        "created_at": "Fri Mar 28 15:00:00 +0000 2026",
        "author": {
          "id": "888888888",
          "name": "Crypto Analyst",
          "username": "cryptoanalyst",
          "profile_image": "https://pbs.twimg.com/profile_images/.../normal.jpg",
          "verified": false,
          "followers_count": 50000
        },
        "like_count": 120,
        "retweet_count": 30,
        "reply_count": 15,
        "view_count": 25000
      }
    ]
  },
  "timestamp": "2026-03-28T15:00:30.000Z"
}

{
  "type": "error",
  "channel": "tweet:engagement",
  "params": { "tweet_id": "2035548674483273831" },
  "code": "POLL_ERROR",
  "message": "Rate limited (429)"
}

{ "type": "ping" }

{ "type": "pong" }

const ws = new WebSocket("wss://api.xshot.fun/ws?api_key=YOUR_KEY");

ws.onopen = () => {
  console.log("Connected to Xshot WebSocket");

  // Monitor tweet engagement in real-time
  ws.send(JSON.stringify({
    type: "subscribe",
    channel: "tweet:engagement",
    params: { tweet_id: "2035548674483273831" },
    interval: 15
  }));

  // Watch for new tweets from a user
  ws.send(JSON.stringify({
    type: "subscribe",
    channel: "user:tweets",
    params: { username: "elonmusk" },
    interval: 30
  }));

  // Monitor follower count changes
  ws.send(JSON.stringify({
    type: "subscribe",
    channel: "user:followers",
    params: { username: "elonmusk" },
    interval: 60
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  switch (msg.type) {
    case "connected":
      console.log("Server ready:", msg.timestamp);
      break;

    case "subscribed":
      console.log(`Subscribed to ${msg.channel} (polling every ${msg.interval}s)`);
      break;

    case "event":
      console.log(`[${msg.channel}]`, JSON.stringify(msg.data, null, 2));
      break;

    case "error":
      console.error(`Error on ${msg.channel}: ${msg.message}`);
      break;
  }
};

ws.onclose = (event) => {
  if (event.code === 4001) {
    console.error("Authentication failed - check your API key");
  } else {
    console.log("Disconnected:", event.code, event.reason);
  }
};

import asyncio
import json
import websockets

API_KEY = "YOUR_KEY"

async def main():
    uri = f"wss://api.xshot.fun/ws?api_key={API_KEY}"

    async with websockets.connect(uri) as ws:
        # Subscribe to follower changes
        await ws.send(json.dumps({
            "type": "subscribe",
            "channel": "user:followers",
            "params": {"username": "elonmusk"},
            "interval": 60
        }))

        async for message in ws:
            msg = json.loads(message)

            if msg["type"] == "event":
                data = msg["data"]
                print(f"Followers: {data['followers_count']} ({data['change']:+d})")

            elif msg["type"] == "error":
                print(f"Error: {msg['message']}")

asyncio.run(main())