Realtime Overview

LedgerCore ships a Socket.IO server alongside the REST gateway for sub-second market data, streaming query results, and live credit/activity notifications. It's built on the same authentication and credit system as the REST API — so a valid JWT is all you need to subscribe.

When to use the Realtime API

Use WebSockets whenever you need push semantics: live candle ticks, orderbook updates, long-running query progress, or credit balance alerts. For simple point-in-time reads, stick with the REST endpoints.

Connection

The WebSocket server is co-located with the gateway but listens on its own port.

Environment	WebSocket URL
Local	`ws://localhost:8091`
Staging	`wss://api-staging.ledgercore.io/ws`
Production	`wss://api.ledgercore.io/ws`

All connections go through Socket.IO — use the official client for your language:

npm install socket.io-client

Authentication

Pass a Clerk JWT (or API key) as the auth.token on connection. The server rejects any socket that can't authenticate within 5 seconds.

import { io } from 'socket.io-client';

const socket = io('ws://localhost:8091', {
  auth: { token: 'Bearer ' + process.env.LEDGERCORE_TOKEN },
  transports: ['websocket'],
});

socket.on('connected', (hello) => {
  console.log('ready:', hello); // { userId, sid, timestamp }
});

socket.on('disconnect', (reason) => {
  console.warn('disconnected:', reason);
});

Rooms & channels

When you authenticate, the server joins you to a personal room named user:<clerkUserId>. Any server-initiated event (credits updated, activity logged, etc.) is broadcast there automatically. Beyond that you can subscribe to topic-specific rooms:

socket.emit('subscribe', { room: 'market:BTC-USD' });
socket.on('subscribed', ({ room }) => console.log('listening to', room));

socket.on('market_chart_live_update', (tick) => {
  // { symbol, open, high, low, close, volume, timestamp }
});

// Later…
socket.emit('unsubscribe', { room: 'market:BTC-USD' });

Event categories

The Realtime API emits dozens of events organised into five families:

System

connected, ping/pong, subscribe, unsubscribe

Query Engine

query, query_progress, query_completed, query_error

Market Data

request_market_data, market_chart_live_update

Compliance

address_analysis, address_transactions, cross_border_flows

Credits

credit_balance_updated, credits_deducted, credits_granted

Chat / AI

chat, chat_response, chat_typing, chat_stop_typing

See Event Reference for the full catalog and payload shapes, or Examples for ready-to-run snippets.

Scaling & reliability

Redis-backed

The Socket.IO server uses the @socket.io/redis-adapter so you can horizontally scale the gateway without losing pub/sub. Every API instance publishes to the shared api:events Redis channel; any WebSocket instance subscribed to that channel fans the payload out to the matching rooms.

Automatic reconnect: the Socket.IO client reconnects with exponential backoff on its own.
Heartbeats: the server pings every 25s; if your network drops you'll see a disconnect event with reason ping timeout.
Per-user rate limits: subscriptions are capped at 100 rooms per socket. Exceeding the limit emits a rate_limit_error instead of disconnecting you.