> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbitflare.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WebSocket-клиент

> Подписки в реальном времени на изменения аккаунтов, логи, слоты и подписи с автоматическим переподключением.

## Установка

```bash theme={null}
npm install @orbitflare/sdk ws
```

`ws` - опциональная peer-зависимость. Устанавливайте её, только если используете WebSocket-клиент.

## Сборка клиента

```ts theme={null}
import { WsClientBuilder } from '@orbitflare/sdk/ws';
import type { RetryPolicy } from '@orbitflare/sdk';

const client = await new WsClientBuilder()
  .url('ws://ny.rpc.orbitflare.com')
  .fallbackUrl('ws://fra.rpc.orbitflare.com')
  .apiKey('ORBIT-XXXXXX-NNNNNN-NNNNNN')
  .retry({
    initialDelayMs: 100,
    maxDelayMs: 30_000,
    multiplier: 2.0,
    maxAttempts: 0,
  })
  .pingIntervalSecs(10)
  .maxMissedPongs(3)
  .build();
```

Минимально:

```ts theme={null}
const client = await new WsClientBuilder()
  .url('ws://ny.rpc.orbitflare.com')
  .build();
```

Обратите внимание: `.build()` асинхронный - перед резолвом устанавливается WebSocket-соединение. При ошибке подключения промис отклоняется сразу.

### Методы билдера

**`.url(url)`** - основной WebSocket-эндпоинт. Резерв: переменная `ORBITFLARE_WS_URL`.

```ts theme={null}
.url('ws://ny.rpc.orbitflare.com')
```

**`.urls([...])`** - основной и резервные за один вызов.

```ts theme={null}
.urls(['ws://ny.rpc.orbitflare.com', 'ws://fra.rpc.orbitflare.com'])
```

**`.fallbackUrl(url)` / `.fallbackUrls([...])`** - добавить резерв для failover. При переподключении SDK перебирает их по очереди.

```ts theme={null}
.fallbackUrl('ws://fra.rpc.orbitflare.com')
```

**`.apiKey(key)`** - лицензионный ключ. Резерв: `ORBITFLARE_LICENSE_KEY`.

```ts theme={null}
.apiKey('ORBIT-XXXXXX-NNNNNN-NNNNNN')
```

**`.retry(policy)`** - backoff при переподключении. По умолчанию: 100 мс начальная, 30 с максимум, 2×, бесконечные попытки.

```ts theme={null}
.retry({
  initialDelayMs: 200,
  maxDelayMs: 15_000,
  multiplier: 2.0,
  maxAttempts: 0,
})
```

**`.pingIntervalSecs(n)`** - как часто SDK отправляет фреймы WebSocket `Ping`. По умолчанию: 10.

```ts theme={null}
.pingIntervalSecs(15)
```

**`.maxMissedPongs(n)`** - сколько ping без ответа перед обрывом соединения. По умолчанию: 3.

```ts theme={null}
.maxMissedPongs(5)
```

## Доступные подписки

### `slotSubscribe()`

Срабатывает при обработке, подтверждении или финализации слота.

```ts theme={null}
const sub = await client.slotSubscribe();
```

Каждое событие - объект с полями `slot`, `parent` и `root`:

```json theme={null}
{"slot": 413014740, "parent": 413014739, "root": 413014708}
```

### `accountSubscribe(address, commitment)`

Срабатывает при изменении данных указанного аккаунта.

```ts theme={null}
const sub = await client.accountSubscribe(
  'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
  'confirmed',
);
```

Возвращает данные аккаунта в base64 вместе с lamports, владельцем и флагом executable.

### `logsSubscribe(mentions, commitment)`

Для транзакций, в которых фигурируют указанные адреса. Передайте пустой массив для всех транзакций.

```ts theme={null}
const sub = await client.logsSubscribe(
  ['6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P'],
  'confirmed',
);
```

Все логи:

```ts theme={null}
const sub = await client.logsSubscribe([], 'confirmed');
```

### `signatureSubscribe(signature, commitment)`

Срабатывает один раз, когда транзакция достигает заданного уровня commitment. Удобно для подтверждения только что отправленной транзакции.

```ts theme={null}
const sub = await client.signatureSubscribe('5K8F2j...', 'confirmed');
```

## Чтение событий

Все подписки возвращают `WsSubscription`. Вызовите `.next()` для следующего события:

```ts theme={null}
while (true) {
  const event = await sub.next();
  if (event === undefined) break;
  console.log(event);
}
```

`.next()` резолвится в `undefined`, когда подписка закрыта.

Также можно подключить колбэк в стиле слушателя событий:

```ts theme={null}
const off = sub.on((event) => {
  console.log(event);
});

// later: off();
```

## Отписка

```ts theme={null}
await sub.unsubscribe();
```

Отправляет на сервер сообщение об отписке. Если дропнуть подписку без вызова, SDK обнаружит «сироту» и сам отправит отписку.

## Несколько подписок

Все подписки идут по одному WebSocket-соединению. SDK маршрутизирует уведомления на нужную подписку внутри себя.

```ts theme={null}
const slots = await client.slotSubscribe();
const usdc = await client.accountSubscribe('EPjFWdd5...', 'confirmed');
const logs = await client.logsSubscribe(['6EF8r...'], 'confirmed');
```

Новые подписки можно добавлять в любой момент, пока работают существующие.

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

Если соединение обрывается, фоновая задача переподключается с экспоненциальным backoff и автоматически заново подписывается. Ваши вызовы `.next()` продолжают работать - события возобновятся после восстановления связи.

## Полный пример

Скрипт мониторинга: подписка на обновления слотов и изменения аккаунта USDC, вывод ленты в реальном времени.

```ts theme={null}
import { WsClientBuilder } from '@orbitflare/sdk/ws';

async function main() {
  const client = await new WsClientBuilder()
    .url('ws://ny.rpc.orbitflare.com')
    .build();

  const slots = await client.slotSubscribe();
  const usdc = await client.accountSubscribe(
    'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
    'confirmed',
  );

  console.log('watching slots and USDC mint account...');

  slots.on((slot) => {
    const s = slot?.slot ?? 0;
    const parent = slot?.parent ?? 0;
    console.log(`slot ${s} (parent ${parent})`);
  });

  usdc.on((acct) => {
    const lamports = acct?.lamports ?? 0;
    const data = acct?.data?.[0];
    const dataLen = typeof data === 'string' ? data.length : 0;
    console.log(`USDC mint updated: ${lamports} lamports, ${dataLen} bytes`);
  });

  await new Promise(() => {});
}

void main();
```