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.

Scenario	Behaviour
Missing `api-key` parameter	Connection rejected with close code 4401
Malformed key (not a valid UUID)	Connection rejected with close code 4401
Key not found or inactive	Connection rejected with close code 4401
Connection limit exceeded	Connection accepted, then closed with code 1013 and a `CONN_LIMIT` error message

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:

Limit	Description
Max connections	Maximum number of simultaneous WebSocket connections across all your API keys. Exceeding this returns a `CONN_LIMIT` error.
Max topics	Maximum number of address+stream subscriptions active at the same time on a single connection. Exceeding this returns a `TOPIC_LIMIT` error.

Supported Networks

Network	ID
Ethereum	`eth`
Solana	`sol`
Base	`base`
BNB Smart Chain	`bsc`
Monad	`monad`
XLayer	`xlayer`
Abstract	`abs`

Supported Streams

Stream	Supported Networks	Description
`dex_metrics`	`sol`, `eth`, `base`, `bsc`	Unified holder analysis stream delivering top-10 distribution, clusters, and (on Solana) snipers, bundlers, insiders, and dev holdings. See DEX Metrics Stream for details.
`clusters`	All networks	Real-time token holder cluster analysis. See Clusters Stream for details.
`bundlers`	`sol`	Real-time bundler concentration percentage. See Bundlers Stream for details.
`insiders`	`sol`	Real-time insider and dev holdings percentages. See Insiders Stream for details.
`snipers`	`sol`	Real-time sniper concentration percentage. See Snipers Stream for details.
`distribution`	`sol`, `eth`, `base`, `bsc`	Real-time top-10 holder distribution percentage.
`scanner`	`sol`	Real-time token security scan events. See Scanner Stream for details.
`dex_trades`	`sol`	Real-time DEX trade events with multi-address filtering. See DEX Trades Stream for details.

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

Operation	Description
`subscribe`	Subscribe to one or more topics
`unsubscribe`	Unsubscribe from topics
`ping`	Keep-alive ping

Server Operations

Operation	Description
`ready`	Connection established and authenticated
`subscribed`	Subscription confirmation
`unsubscribed`	Unsubscription confirmation
`event`	Real-time data event
`pong`	Ping response
`error`	Error response