API reference

The complete public surface of the SDK. For type definitions, your editor will pull them straight from the published types — this page exists for skimming and copy-pasting signatures.

createClient(options)

import { createClient } from 'realtimeodds'

function createClient(options: ClientOptions): Client

Constructs a client. Doesn’t open the connection — call client.connect() to do that.

ClientOptions

interface ClientOptions {
  url: string                        // wss://api.realtimeodds.xyz
  apiKey: string                     // your API key
  reconnect?: ReconnectPolicy        // see below
}

ReconnectPolicy

interface ReconnectPolicy {
  initialDelayMs?: number   // default: 1000
  maxDelayMs?: number       // default: 30000
  factor?: number           // default: 2
  jitter?: number           // default: 0.3 (±30%)
  maxAttempts?: number      // default: Infinity
}

The defaults give exponential backoff 1s → 30s with ±30% jitter, indefinite retries on transient errors. See Reconnect tuning.

Client

interface Client {
  connect(options?: { signal?: AbortSignal }): Promise<void>
  disconnect(): Promise<void>
  snapshot(): Snapshot
  getSportEvent(id: SportEventId): SportEvent | null
  on<E extends keyof ClientEventMap>(event: E, listener: (payload: ClientEventMap[E]) => void): void
  off<E extends keyof ClientEventMap>(event: E, listener: (payload: ClientEventMap[E]) => void): void
  readonly connectionState: ConnectionState
}

client.connect(options?)

Opens the WebSocket and starts consuming events.

• Resolves on the first successful connection.
• Rejects on fatal errors: invalid apiKey (close 4001/4002), incompatible protocol, exhausted reconnect attempts.
• Transient errors (network blips, gateway restarts) keep the promise pending while reconnect attempts run.
• Concurrent calls return the same in-flight promise.
• Calling on an already-connected client resolves immediately.
• Pass options.signal (AbortSignal) to cancel an in-flight attempt — the promise rejects with an AbortError and the client is fully disconnected.

const ctrl = new AbortController()
setTimeout(() => ctrl.abort(), 5000)
await client.connect({ signal: ctrl.signal })

client.disconnect()

Closes the WebSocket and stops the reconnect loop. Idempotent. If a connect() is in flight, it rejects.

client.snapshot()

interface Snapshot {
  sportEvents: ReadonlyMap<SportEventId, SportEvent>
  stale: boolean
}

A live view of the SDK’s in-memory store. stale: true when the connection is currently down. The map is not a copy — every call returns the same live reference, always reflecting the latest state.

client.getSportEvent(id)

client.getSportEvent(id: SportEventId): SportEvent | null

O(1) single lookup. Returns null for unknown ids.

client.on(event, listener) / client.off(event, listener)

Subscribe / unsubscribe to a client event. The same listener reference must be passed to off to remove it.

client.connectionState

interface ConnectionState {
  status: 'disconnected' | 'connecting' | 'connected' | 'reconnecting'
  lastError?: Error
}

Snapshot of the current connection. For reactive flows, prefer the lifecycle events.

Entity types

The SDK re-exports the entity types so you can import them directly:

import type {
  SportEvent, BasketballMatch, FootballMatch, TennisMatch,
  Market, BasketballMoneyline, BasketballHandicap, BasketballTotal,
  BasketballPlayerPropOverUnder, FootballMoneyline, TennisMoneyline,
  Selection, Quote, OrderBook, Level,
  Bookmaker, Sport, SportEventKind, MarketKind, SelectionKind, SelectionResult,
  BasketballPeriod, BasketballTotalScope, PlayerPropType,
  Competition, SportEventId, MarketId, SelectionId
} from 'realtimeodds'

For the full shape of each, see Data model and Markets.