Build a Real-Time Tadawul Stream with SAHMK WebSocket (JavaScript + Python)

wss://app.sahmk.sa/ws/v1/stocks/?api_key=YOUR_API_KEY

{
  "type": "connected",
  "plan": "pro",
  "limits": {
    "max_symbols_per_connection": 60,
    "max_symbols_per_call": 20,
    "stream_modes": ["quotes"]
  },
  "message": "Connected to SAHMK real-time stock stream",
  "timestamp": "2026-02-10T10:00:00.000Z"
}

{"action":"subscribe","symbols":["2222","1120"]}
{"action":"unsubscribe","symbols":["2222"]}
{"action":"ping"}
{"action":"subscribe","symbols":["*"]}

const API_KEY = "YOUR_API_KEY";
const URL = `wss://app.sahmk.sa/ws/v1/stocks/?api_key=${API_KEY}`;
const SYMBOLS = ["2222", "1120"];

let ws = null;
let pingTimer = null;
let reconnectAttempt = 0;
let manualClose = false;

function nextDelayMs(attempt) {
  const base = 1000;
  const cap = 30000;
  const exp = Math.min(cap, base * 2 ** attempt);
  const jitter = Math.floor(Math.random() * 500);
  return exp + jitter;
}

function startPing() {
  clearInterval(pingTimer);
  pingTimer = setInterval(() => {
    if (ws && ws.readyState === WebSocket.OPEN) {
      ws.send(JSON.stringify({ action: "ping" }));
    }
  }, 30000);
}

function stopPing() {
  clearInterval(pingTimer);
  pingTimer = null;
}

function connect() {
  ws = new WebSocket(URL);

  ws.onopen = () => {
    reconnectAttempt = 0;
    ws.send(JSON.stringify({ action: "subscribe", symbols: SYMBOLS }));
    startPing();
  };

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

    if (msg.type === "connected") {
      console.log("Connected limits:", msg.limits);
      return;
    }

    if (msg.type === "subscribed") {
      console.log("Subscribed symbols:", msg.symbols);
      return;
    }

    if (msg.type === "quote") {
      const { symbol, data } = msg;
      console.log(`${symbol}: ${data.price} (${data.change_percent}%)`);
      // Example UI hook:
      // document.querySelector(__TOKEN_12__).textContent = data.price;
      return;
    }

    if (msg.type === "error") {
      console.error("Server error:", msg);
      return;
    }

    if (msg.type === "pong") {
      console.log("pong");
    }
  };

  ws.onerror = (event) => {
    console.error("WebSocket error:", event);
  };

  ws.onclose = (event) => {
    stopPing();
    console.warn(`Closed: code=${event.code} reason=${event.reason}`);

    // Auth path. Do not loop forever without intervention.
    if (event.code === 4401) {
      console.error("Authentication failure (4401). Check API key.");
      return;
    }

    // Entitlement / inactive / unverified account path.
    if (event.code === 4403) {
      console.error("Access denied (4403). Check plan/account entitlement status.");
      return;
    }

    // Deploy/restart can drop active sockets; reconnect and resubscribe on open.
    if (!manualClose) {
      const delay = nextDelayMs(reconnectAttempt++);
      setTimeout(connect, delay);
    }
  };
}

window.addEventListener("beforeunload", () => {
  manualClose = true;
  if (ws && ws.readyState === WebSocket.OPEN) {
    ws.send(JSON.stringify({ action: "unsubscribe", symbols: SYMBOLS }));
  }
  stopPing();
  ws?.close(1000, "Page unload");
});

connect();

import asyncio
import contextlib
import json
import random
import websockets

API_KEY = "YOUR_API_KEY"
URL = f"wss://app.sahmk.sa/ws/v1/stocks/?api_key={API_KEY}"
SYMBOLS = ["2222", "1120"]

def next_delay_seconds(attempt: int) -> float:
  base = 1.0
  cap = 30.0
  exp = min(cap, base * (2 ** attempt))
  jitter = random.uniform(0.0, 0.5)
  return exp + jitter

async def ping_loop(ws):
  while True:
    await asyncio.sleep(30)
    await ws.send(json.dumps({"action": "ping"}))

async def stream_forever():
  attempt = 0
  while True:
    try:
      async with websockets.connect(URL, ping_interval=None) as ws:
        attempt = 0
        await ws.send(json.dumps({"action": "subscribe", "symbols": SYMBOLS}))
        pinger = asyncio.create_task(ping_loop(ws))

        try:
          async for raw in ws:
            msg = json.loads(raw)
            msg_type = msg.get("type")

            if msg_type == "connected":
              print("Connected limits:", msg.get("limits"))
            elif msg_type == "subscribed":
              print("Subscribed:", msg.get("symbols"))
            elif msg_type == "quote":
              symbol = msg.get("symbol")
              data = msg.get("data", {})
              print(f"{symbol}: {data.get('price')} ({data.get('change_percent')}%)")
            elif msg_type == "error":
              print("Server error:", msg)
            elif msg_type == "pong":
              print("pong")
        finally:
          pinger.cancel()
          with contextlib.suppress(asyncio.CancelledError):
            await pinger
    except websockets.exceptions.ConnectionClosed as exc:
      print(f"Connection closed: code={exc.code}, reason={exc.reason}")
      if exc.code == 4401:
        print("Authentication failure (4401). Check API key.")
        return
      if exc.code == 4403:
        print("Access denied (4403). Check plan/account entitlement status.")
        return
    except Exception as exc:
      print(f"Unexpected error: {exc}")

    delay = next_delay_seconds(attempt)
    print(f"Reconnecting in {delay:.2f}s")
    await asyncio.sleep(delay)
    attempt += 1

if __name__ == "__main__":
  asyncio.run(stream_forever())

pip install websockets

// Enterprise-only example:
ws.send(JSON.stringify({
  action: "subscribe",
  symbols: ["*"]
}));