главная

API

WebSocket

Данные Seeryx в реальном времени через один WebSocket: подписка на раунд (оба стакана, сделки, объём) и на аккаунт; форматы сообщений, переподключение.

Подключение

URL
wss://seeryx.com/ws
Подписки
Один раунд и один аккаунт на соединение. Новая подписка того же типа заменяет старую; чтобы следить за несколькими раундами, откройте несколько соединений.
Доставка
Первое сообщение после подписки — полное состояние. Дальше сообщение приходит, только когда его содержимое изменилось, и сразу после изменения.

Подписка

Вы отправляете
{ "subscribe": "round", "slug": "btc-updown-5m-1791916200" }
{ "subscribe": "account", "token": "eyJ0eXAiOiJKV1Qi..." }
Slug раунда или событийного рынка; для аккаунта нужен ваш токен входа.

Сообщения

Вы получаете
{ "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: оба стакана целиком (как GET /api/orderbook), последние 100 сделок и объём.
  • account: ровно то же, что GET /api/account. Когда меняется heads, прочитайте новые строки из /api/activity или /api/settled.
  • error не закрывает сокет; после него можно отправить другую подписку.

Heartbeat-сообщения

Сервер отправляет ping WebSocket каждые 30 секунд; библиотеки WebSocket сами отвечают на него pong. Соединение, от которого 120 секунд ничего не приходит, закрывается. Отправьте первую подписку в течение 10 секунд после подключения.

Переподключение

  • Переподключайтесь с растущей задержкой (1, 2, 4… до 30 секунд) и подписывайтесь заново: первое сообщение приносит полное состояние, поэтому ничего не теряется.
  • Закрытие с причиной «Token expired» означает, что перед подпиской на аккаунт нужно войти заново.
  • Когда раунд заканчивается, подпишитесь на следующий в том же соединении.

Лимиты и коды закрытия

ЛимитЗначениеПри превышении
Размер сообщения4 КБСоединение закрывается
Сообщения от одного соединения60 в минутуЗакрытие 1008 «Rate limit»
Сообщения подписки600 в минуту на IP-адрес, 60 на аккаунт{ "type": "error", "error": "Too many subscriptions" }
Открытые соединения50 на IP-адресHTTP 429 до переключения протокола (upgrade), с Retry-After
Первая подпискаВ течение 10 секундЗакрытие 1008 «Handshake timeout»
Тишина120 секунд без единого фреймаЗакрытие 1008 «Idle timeout»
Непрочитанные сообщения256 в очередиЗакрытие 1013 «Slow consumer»
Токен входаПока не истечёт или не будет отозванЗакрытие 1008 «Token expired» или «Token revoked»

Код

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(); },
  };
}
Клиент, который сам переподключается.
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);
  },
});