WebSocket

Writing a client

Use this if you are not on Python or TypeScript, or you would rather not take a dependency. Everything the SDKs do is these frames: mint a socket_url over REST as in Connecting, open a WebSocket to it, send a frame, and match the reply on its msgid.

No SDK. Python needs one dependency (pip install websockets), and TypeScript needs none, since Node 22 ships both fetch and WebSocket.

Frames without your msgid are events, so skip them while you wait for a reply.

Frames and replies: every field, status and error shape.
Events: the pushes that arrive without being asked for.

Last modified on September 18, 2026

Connecting Frames and replies

WebSocket

Writing a client

No SDK. Python needs one dependency (pip install websockets), and TypeScript needs none, since Node 22 ships both fetch and WebSocket.

import json
import os
import urllib.request
from typing import Any

from websockets.sync.client import connect

TOKEN = os.environ["ZEROBULL_API_TOKEN"]


def controller_session() -> dict[str, Any]:
    """Mint a socket URL with the REST endpoint."""
    request = urllib.request.Request(
        "https://0bull.net/api/v1/phone-controller",
        headers={"Authorization": f"Bearer {TOKEN}", "Accept": "application/json"},
    )
    with urllib.request.urlopen(request, timeout=30) as response:
        data: dict[str, Any] = json.load(response)
        return data


session = controller_session()
print("farm_online:", session["farm_online"])

with connect(session["socket_url"], ping_interval=20) as socket:
    socket.send(json.dumps({"fun": "/app/phones/list", "msgid": "1", "data": {}}))
    for message in socket:
        frame: dict[str, Any] = json.loads(message)
        if frame.get("msgid") != "1":
            continue
        if frame["status"] != 200:
            raise SystemExit(f"{frame['status']}: {frame['message']}")
        for phone in frame["data"]:
            print(phone["slot"], phone["name"], phone["can_control"])
        break

Frames without your msgid are events, so skip them while you wait for a reply.

Frames and replies: every field, status and error shape.
Events: the pushes that arrive without being asked for.

Last modified on September 18, 2026

Connecting Frames and replies

Writing a client

Next

Writing a client

Next