WebSocket API

The InsightX WebSocket API delivers real-time blockchain data directly to your application. Instead of polling REST endpoints, you open a single persistent connection and subscribe to the streams and addresses you care about.

Base URL

wss://api.insightx.network/?api-key=YOUR_API_KEY

Quick Start

const ws = new WebSocket("wss://api.insightx.network/?api-key=YOUR_API_KEY");

ws.onopen = () => {
  // Subscribe to cluster updates for a token
  ws.send(JSON.stringify({
    op: "subscribe",
    network: "sol",
    address: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    stream: "clusters"
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log(msg.op, msg);
};

Authentication

Authentication is performed via the api-key query parameter. The key must be a valid UUID tied to an active API account. You can create and manage API keys at the InsightX Hub.

Note: Authentication happens before the WebSocket handshake is accepted. If your key is invalid, you will receive a close frame immediately -- no ready message is sent.

Connection Lifecycle

Client                                   Server
  │                                        │
  │── GET /ws/?api-key=xxx ───────────────>│  (1) HTTP Upgrade
  │                                        │  (2) Validate API key
  │                                        │  (3) Check connection limit
  │<── 101 Switching Protocols ────────────│
  │<── {"op":"ready","ts":1707300000} ─────│  (4) Connection established
  │                                        │
  │── {"op":"subscribe",...} ─────────────>│  (5) Subscribe to topics
  │<── {"op":"subscribed",...} ────────────│
  │                                        │
  │<── {"op":"event",...} ─────────────────│  (6) Receive real-time events
  │<── {"op":"event",...} ─────────────────│
  │                                        │
  │── {"op":"ping","id":"abc"} ──────────>│  (7) Keep-alive
  │<── {"op":"pong","id":"abc",...} ───────│
  │                                        │
  │── close ──────────────────────────────>│  (8) Disconnect

The ready Message

After a successful connection, the server sends:

{
  "op": "ready",
  "ts": 1707300000
}

This confirms the connection is authenticated and ready to accept commands. Do not send subscribe messages before receiving ready.

Plan Limits

Your API plan determines three WebSocket limits:

Supported Networks

Supported Streams

New streams will be added over time. Sending an unrecognized stream name returns a BAD_STREAM error. Subscribing to a stream on an unsupported network returns a BAD_NETWORK error.

Message Format

All messages -- both client-to-server and server-to-client -- are JSON objects. Every message includes an op field indicating the operation type.

Client Operations

Server Operations