API

WebSocket

Live Seeryx data over one WebSocket: subscribe to a round for both order books, trades and volume, and to your account; message shapes and reconnects.

Connect

URL: wss://seeryx.com/ws
Subscriptions: One round and one account per connection. A new subscription of the same kind replaces the old one; watch more rounds with more connections.
Delivery: The first message after a subscription is the full state. After that a message comes only when its content changed, as soon as it changed.

You send

{ "subscribe": "round", "slug": "btc-updown-5m-1791916200" }
{ "subscribe": "account", "token": "eyJ0eXAiOiJKV1Qi..." }

A round slug or an event market slug; the account needs your sign-in token.

Messages

You receive

{ "type": "round", "slug": "btc-updown-5m-1791916200",
  "up":   { "bids": [[13, 10], [12, 100]], "asks": [[16, 100], [17, 100]] },
  "down": { "bids": [[84, 100], [83, 100]], "asks": [[87, 10], [88, 100]] },
  "trades": [{ "id": 13, "side": "down", "action": "buy", "shares": 10, "price": 53, "time": 1791916330063 }, ...],
  "volume": { "volume": 55.845724, "trades": 13 } }

{ "type": "account",
  "positions": [{ "slug": "btc-updown-5m-1791916200", "side": "down", "shares": 50.3462, "cost": 18.126554 }],
  "orders": [{ "id": 25538, "slug": "btc-updown-5m-1791916200", "side": "down", "action": "buy", "shares": 10, "limit": 48, "createdAt": 1791916330045 }],
  "balance": { "available": 474.097965, "locked": 0, "total": 474.097965, "currency": "USDC" },
  "heads": { "activity": 116, "settled": null } }

{ "type": "error", "error": "Invalid subscription or authentication" }

round: both books in full (as GET /api/orderbook), the last 100 trades and the volume.
account: exactly GET /api/account. When heads changes, read /api/activity or /api/settled for the new rows.
error leaves the socket open; another subscription can follow.

The server sends a WebSocket ping every 30 seconds; WebSocket libraries answer with a pong by themselves. A connection from which nothing arrives for 120 seconds is closed. Send the first subscription within 10 seconds of connecting.

Reconnecting

Reconnect with a growing delay (1, 2, 4 ... up to 30 seconds) and subscribe again: the first message brings the full state, so nothing is missed.
A close with reason "Token expired" means sign in again before subscribing to the account.
When a round ends, subscribe to the next one on the same connection.

Limits and close codes

Limit	Value	Over it
Message size	4 KB	The connection closes
Messages from one connection	60 a minute	Close 1008 "Rate limit"
Subscribe messages	600 a minute per IP address, 60 per account	{ "type": "error", "error": "Too many subscriptions" }
Open connections	50 per IP address	HTTP 429 before the upgrade, with Retry-After
First subscription	Within 10 seconds	Close 1008 "Handshake timeout"
Silence	120 seconds without any frame	Close 1008 "Idle timeout"
Unread messages	256 queued	Close 1013 "Slow consumer"
Sign-in token	Until it expires or is revoked	Close 1008 "Token expired" or "Token revoked"

Code

live.ts

// live.ts: a WebSocket client that reconnects by itself. Node 22+ (WebSocket is built in) or any browser.
import { ACCESS, BASE } from './seeryx';

export type Message = { type: 'round' | 'account' | 'error' } & Record<string, unknown>;

export function live(options: { slug?: string; token?: string; onMessage: (message: Message) => void }) {
  let socket: WebSocket | null = null;
  let attempt = 0;
  let stopped = false;
  let { slug, token } = options;
  const gate = ACCESS ? { access: ACCESS } : {};
  const send = (message: object) => {
    if (socket?.readyState === WebSocket.OPEN) socket.send(JSON.stringify({ ...message, ...gate }));
  };

  function connect() {
    socket = new WebSocket(`${BASE.replace(/^http/, 'ws')}/ws`);
    socket.onopen = () => {
      attempt = 0;
      if (slug) send({ subscribe: 'round', slug });
      if (token) send({ subscribe: 'account', token });
    };
    socket.onmessage = (event) => options.onMessage(JSON.parse(String(event.data)));
    socket.onclose = (event) => {
      if (stopped) return;
      if (event.reason === 'Access code required') { stopped = true; return; } // get a new access token
      if (event.reason === 'Token expired') token = undefined;                   // sign in again for it
      setTimeout(connect, Math.min(30_000, 1000 * 2 ** attempt++));              // 1 s, 2 s, 4 s ... 30 s
    };
  }
  connect();

  return {
    // one round per connection: subscribing to the next round replaces the previous one
    follow(next: string) { slug = next; send({ subscribe: 'round', slug }); },
    close() { stopped = true; socket?.close(); },
  };
}

A client that reconnects by itself.

watch.ts

import { api, loadWallet, signIn } from './seeryx';
import { live } from './live';

const token = await signIn(await loadWallet());
const { slug } = await api<{ slug: string }>('/markets/BTC/5m/current');
live({
  slug, token, onMessage: (m) => {
    if (m.type === 'round') console.log('Up book', m.up);
    if (m.type === 'account') console.log('cash', m.balance);
  },
});

Connect

Subscribe

Messages

Heartbeats

Reconnecting

Limits and close codes

Code