0xDocs 0x.limo

Docs / REST API

Push stream

The /v1/stream WebSocket — connecting from native code and browsers, the events it delivers, resuming after a reconnect, tracker requests and the binary relay.

wss://api.0x.limo/v1/stream is one WebSocket per client process: a game, a game server or the launcher. The service pushes JSON events over it, for lobby changes, invites, friends, chat, trades and relay-list changes. It also carries swarm tracker requests and a binary relay between players.

GET /v1/me and POST /v1/gameservers/logon return the stream URL to use (stream, with every gateway in streams).

#Connect

Authenticate with the same tokens as REST: an access token or a game-server session.

js
// Browsers can't set headers on a WebSocket: offer the token as a subprotocol.
const ws = new WebSocket("wss://api.0x.limo/v1/stream", ["sg.v1", "sg.bearer." + accessToken]);
ws.onmessage = (m) => {
  if (typeof m.data !== "string") return;          // binary frames: the relay
  const ev = JSON.parse(m.data);
  lastEid = ev._eid ?? lastEid;
  if (ev.type === "lobby") onLobby(ev.event, ev.lobby);
};
  • The server answers the sg.v1 subprotocol.
  • A bad or expired token gets 401 on the upgrade.
  • While a node is draining for a deploy, the upgrade gets 503; connect to another gateway or retry.
  • The server pings every 20 s. A connection that stays silent for three intervals is closed.
  • Messages may be up to 1 MiB.

#Resuming

Every JSON event carries _eid, its ID in the user's event stream. After a reconnect, pass the last one you saw:

text
wss://api.0x.limo/v1/stream?since=1792259580679-0

You first get every event you missed, from any gateway node, then live events. Drop duplicates by _eid. The replay keeps the last ~64 events for about 30 s. After a longer gap, resync your state over REST (GET /v1/lobbies/{id}, GET /v1/me/social). Binary relay frames are never replayed.

When a user's last connection closes, they get 10 seconds to reconnect, on any node, before they drop out of their lobbies.

#Events

typeWhen
lobbya lobby you are in changed: event is member_entered, member_left, data or chat, with the full lobby
lobby_invitesomeone invited you to a lobby
persona_changea friend's name, relationship or game changed (flags, Steam's EPersonaChange)
rich_presencea friend's rich presence changed (user, appid)
game_invitea friend invited you to their game (connect)
friend_messagean in-game chat message from a friend
clan_chat_join / clan_chat_leave / clan_chat_msgclan chat room activity
party_beacons / party_reservationparty beacons in your clans; a player reserved a slot in yours
inventory_tradea trade offer for you, or a trade done
net_configthe relay list changed (v); fetch GET /v1/net/config again
peersthe answer to a tracker peers request
overlay_jointhe launcher asks your game to join something the player clicked in its overlay
deprecationa client feature you use is being retired

Ignore event types you don't know; new ones are added over time.

#Requests over the stream

Text frames from the client, at most 96 KiB, are swarm tracker requests (Transfers):

json
{"op": "announce", "id": "<cid>"}
{"op": "announce", "ids": ["<cid>", "..."]}
{"op": "peers", "id": "<cid>", "req": 1}

#Binary relay

Binary frames are a last-resort relay between players when no direct or relayed connection works. To send, write [u64 little-endian: recipient SteamID][payload]. Every connection of the recipient receives [u64 little-endian: sender SteamID][payload], whichever gateway node it is on. Delivery is best effort, and frames are not replayed. Use real networking (ISteamNetworkingSockets, @0xlimo/net) for game traffic.